sources

Documentation

Overview

Package sources defines the trigger Source plugin interface and registry.

A Source is a first-party or community-contributed adapter that converts an external signal — an HTTP webhook, a cron tick, a queue message — into a normalized inbound Event that the control plane dispatches to a reasoner.

First-party Source impls live under sources/<name>/<name>.go and register themselves in their package init() via Register. The blank-import aggregator at sources/all wires every first-party source into a single import.

Index

• func Register(s Source)
• type Catalog
  • func List() []Catalog
• type ErrSourceKindMismatch
  • func (e ErrSourceKindMismatch) Error() string
• type ErrUnknownSource
  • func (e ErrUnknownSource) Error() string
• type Event
  • func HandleHTTP(ctx context.Context, name string, req *RawRequest, cfg json.RawMessage, ...) ([]Event, error)
• type HTTPSource
• type Kind
  • func (k Kind) String() string
• type LoopSource
• type RawRequest
• type Source
  • func Get(name string) (Source, bool)

Functions

func Register

func Register(s Source)

Register adds a Source to the global registry. Intended to be called from init() of each first-party source package. Panics if name is empty or already registered — registration conflicts are programmer errors.

Types

type Catalog

type Catalog struct {
	Name           string          `json:"name"`
	Kind           string          `json:"kind"`
	SecretRequired bool            `json:"secret_required"`
	ConfigSchema   json.RawMessage `json:"config_schema"`
}

Catalog is the public-facing description of a registered Source.

func List

func List() []Catalog

List returns the registered sources sorted by name. Used by the GET /api/v1/sources catalog endpoint and by the UI's "new trigger" form.

type ErrSourceKindMismatch

type ErrSourceKindMismatch struct {
	Name string
	Want string
}

ErrSourceKindMismatch is returned when a caller invokes the wrong dispatch path for a source (e.g. POSTing to a cron source).

func (ErrSourceKindMismatch) Error

func (e ErrSourceKindMismatch) Error() string

type ErrUnknownSource

type ErrUnknownSource struct{ Name string }

ErrUnknownSource is returned when a trigger references a source that is not registered. Surfaced to the UI when a stale trigger row outlives a removed plugin.

func (ErrUnknownSource) Error

func (e ErrUnknownSource) Error() string

type Event

type Event struct {
	// Type is the source-specific event type (e.g. "payment_intent.succeeded",
	// "pull_request.opened", or "tick" for cron). Used for filtering.
	Type string
	// IdempotencyKey is the provider's globally unique event ID. The control
	// plane dedups on (source_name, idempotency_key) so retries from a provider
	// produce exactly one inbound_events row. Empty string disables dedup.
	IdempotencyKey string
	// Raw is the original payload bytes as received.
	Raw json.RawMessage
	// Normalized is a Source-curated subset suitable for downstream reasoners.
	// Sources should populate this even when it equals Raw, so the dispatcher
	// has a stable contract regardless of source.
	Normalized json.RawMessage
	// ReceivedAt is when the event entered the control plane. Sources should
	// not override this — leave zero and the registry will stamp it.
	ReceivedAt time.Time
}

Event is the normalized record produced by a Source. The control plane persists every Event, mints a VC over it (when DID is enabled), and dispatches it to the trigger's target reasoner.

func HandleHTTP

func HandleHTTP(ctx context.Context, name string, req *RawRequest, cfg json.RawMessage, secret string) ([]Event, error)

HandleHTTP is a registry-level helper that resolves a Source by name, verifies it implements HTTPSource, and invokes HandleRequest. It is used by the public ingest handler so the handler stays free of registry plumbing.

type HTTPSource

type HTTPSource interface {
	Source
	HandleRequest(ctx context.Context, req *RawRequest, cfg json.RawMessage, secret string) ([]Event, error)
}

HTTPSource is implemented by Sources that ingest via inbound HTTP. It owns signature verification — verification failures should return a non-nil error so the registry can return 401.

type Kind

type Kind int

Kind distinguishes how a Source produces events.

const (
	// KindHTTP sources receive events through inbound HTTP requests.
	KindHTTP Kind = iota
	// KindLoop sources run a long-lived goroutine that emits events on a schedule
	// or by polling an external system.
	KindLoop
)

func (Kind) String

func (k Kind) String() string

String renders the Kind for logging and the JSON catalog.

type LoopSource

type LoopSource interface {
	Source
	Run(ctx context.Context, cfg json.RawMessage, secret string, emit func(Event)) error
}

LoopSource is implemented by Sources that emit events from a long-lived goroutine (cron schedules, polling adapters, queue consumers). Run blocks until ctx is cancelled and must call emit for each event produced.

type RawRequest

type RawRequest struct {
	Headers http.Header
	Body    []byte
	URL     *url.URL
	Method  string
}

RawRequest carries the unparsed inbound HTTP request for an HTTPSource to verify.

type Source

type Source interface {
	// Name is the unique registry key (e.g. "stripe", "github", "cron").
	Name() string
	// Kind reports whether the source is HTTP-driven or loop-driven.
	Kind() Kind
	// ConfigSchema returns a JSON Schema describing the per-trigger config. The
	// UI uses this to render a dynamic form when creating a trigger instance.
	ConfigSchema() json.RawMessage
	// SecretRequired reports whether the trigger must have a non-empty
	// secret_env_var pointing at an environment variable holding the provider
	// secret (e.g. Stripe webhook secret, GitHub webhook secret).
	SecretRequired() bool
	// Validate checks the per-trigger config payload before persistence. Return
	// an error to reject the trigger.
	Validate(cfg json.RawMessage) error
}

Source is the common contract every plugin satisfies.

Implementations also satisfy exactly one of HTTPSource or LoopSource depending on Kind(). The dispatcher routes calls based on the satisfied interface.

func Get

func Get(name string) (Source, bool)

Get returns the registered Source for the given name, or false if no source has been registered under that name.