How shoplineapp/captin works
Project Type and Purpose
• This is a CLI tool (“captin”) written in Go for managing the delivery of webhooks in a distributed fashion.
• It reads a JSON configuration, ingests incoming events (HTTP, message queue, etc.), applies filters and throttles, and dispatches webhooks to arbitrary destinations (HTTP endpoint, SQS, Beanstalkd, console, etc.).
File Structure
Top-level packages:
• cmd (entrypoint “captin” CLI)
• core (core engine orchestration)
• interfaces (abstractions for dispatcher, store, document store, errors)
• destinations (user-configurable filters before sending)
• dispatcher (pipelines: delayers, error handlers, tracking)
• senders (concrete destination implementations: HTTP, SQS, console, Beanstalkd)
• internal (helpers, in-memory stores, custom outgoing dispatch logic, throttles)
• models (configuration mapping, incoming event definition, distributed tracing data)
• configs/examples/tests (demonstrate Redis store, filters, incoming HTTP hooks)
README for Additional Insights
• Usage is simply captin ./example/config.json.
• By convention, you supply a hook configuration and captin spins up listeners, pipelines, and sends outgoing webhooks.
Main Components & Their Relationships
[CLI Entrypoint]
• cmd/captin/main.go
• Reads JSON config via models/config_mapper.go
↓ loads configuration
[Core Engine]
• core/captin.go
• Orchestrates incoming adapters, dispatcher pipeline, and outgoing senders
↙ ↘
[Incoming Adapters] [Dispatcher Pipeline] [Outgoing Senders]
• HTTP listener • dispatcher/delayers/goroutine.go • senders/http_sender.go
• (could be extended via internal/outgoing/custom.go) • dispatcher/error_handlers • senders/sqs_sender.go
• models/incoming_event.go • dispatcher/filters • senders/beanstlakd_sender.go
• dispatcher/tracking.go • senders/console_sender.go
• internal/throttles/throttler.go
↓ Events feed into
[Destination Filters]
• destinations/filters/*.go
• base rules (environment, source, validate, desired_hook)
↓ Filtered events feed into
[Document Store & Tracking]
• interfaces/document_store.go
• internal/document_stores (memstore, null_store)
• used for deduplication, retry tracking, throttling
↓ Persisted & enriched
[Dispatcher → Senders]
• dispatcher invokes appropriate sender(s)
• uses interfaces/store.go, interfaces/errors.go
Architectural Patterns & Principles
• Pipeline pattern – events flow through a configurable chain of delayers, filters, error handlers, trackers, then senders.
• Dependency inversion – core logic depends on interfaces; concrete implementations are pluggable.
• Modular, package-per-responsibility – clear separation between incoming, dispatching, filtering, persistence, and sending.
• Config-driven – behavior defined entirely by JSON hooks config (models/config.go, models/config_mapper.go).
Technologies, Frameworks & Libraries
• Go modules (go.mod)
• Standard Go net/http for HTTP ingress and egress
• Optional Redis (examples/redis/stores/redis_store.go)
• Message queues (SQS, Beanstalkd)
• JSON config parsing (encoding/json)
• Unit tests for every package