plugin

type ObserveAfterWrite ¶

type ObserveAfterWrite interface {
	Plugin
	AfterWrite(ctx context.Context, tr trace.Trace)
}

ObserveAfterWrite is the observe-class hook called AFTER the writer chain has finished. It fires after the JSONL line is on disk and the SQLite row has been upserted — i.e. the trace is durable and queryable.

AfterWrite is the natural home for side-effecting observation: counter exports, downstream notification sinks, operator dashboards (the doc's "alert" and "metrics" categories — see uiux-research/plugin.md § 2.6, § 7.5). Per PHILOSOPHY principle 4 ("compose, don't absorb"), the in-tree project does NOT ship an alerting plugin; operators who want webhooks write their own and register it here.

Hook contract:

• Runs after the writer ack. (Phase A.1 caveat: TrySend is currently non-blocking; the trace is queued but may not be on disk when AfterWrite fires. See uiux-research/plugin.md § 10 "after_record durability semantics" — Phase A ships best-effort and explicitly documents it.)
• Runs in registration order, sequentially per trace. Phase A does NOT fan out to a worker pool; that is Phase B territory if the observed plugins prove load-bearing.
• Errors are logged. There is no way for an AfterWrite plugin to un-write an already-recorded trace (principle 6: filesystem is truth, append-only). Operators learn about plugin errors via /healthz counters.

Renamed from ObserveAfterRecord per plugin-b-c-spec §7.3 (Phase A migration); the "AfterWrite" name keeps the side-effecting-only semantics distinct from the hook-class AFTER (which can mutate the response before the client sees it).

type ObserveOnFinalize ¶

type ObserveOnFinalize interface {
	Plugin
	OnFinalize(ctx context.Context, tr trace.Trace) (shouldRecord bool, err error)
}

ObserveOnFinalize is the observe-class hook called BEFORE the writer chain runs. It fires inside the trace finalize block, after buildTrace has produced a *trace.Trace but before the writer goroutine has been notified.

Returning shouldRecord=false drops the trace: no JSONL line is appended, no SQLite row is inserted, no downstream observation fires. This is the path-filter plugin's mechanism for honoring operator-configured noise filters at capture time (the principled home for ROADMAP § 4 "capture-time skip"; see uiux-research/plugin.md § 7.1).

Returning a non-nil err is LOGGED and surfaced via /healthz counters but does NOT block forwarding and does NOT change shouldRecord on its own — fail-open per PHILOSOPHY principle 3 ("fail open on capture"). A plugin that wants to drop on error returns shouldRecord=false alongside its err; a plugin that wants to record on error returns shouldRecord=true.

The trace value is passed BY VALUE to communicate read-only intent. Plugins MUST NOT retain references to req/resp body bytes past the call; the underlying buffers may be reused by the parser.

Hook contract:

• Runs after the response has been fully delivered to the client. Cannot affect forwarding (principle 2 honored by construction).
• Runs synchronously on the finalize goroutine; the writer is not notified until every OnFinalize plugin has returned.
• Runs in registration order. Returning shouldRecord=false from any plugin SHORT-CIRCUITS the iteration: subsequent plugins do not see the dropped trace.

Renamed from ObserveBeforeRecord per plugin-b-c-spec §7.3 (Phase A migration) to reflect that this fires inside the finalize block, not the writer pipeline. Observer-class plugins decide whether the trace is recorded; hook-class plugins (v2.BeforePlugin / v2.AfterPlugin) shape what flows to the client.

type Plugin ¶

type Plugin interface {
	// Name returns the stable identifier used in config and telemetry.
	// MUST be a compile-time constant string and MUST match the key
	// the registry knows the plugin by. Two plugins with the same Name
	// are a configuration error.
	Name() string

	// Init is called once at process startup with the plugin's parsed
	// config subtree (the value at plugins.config.<name> in YAML, or
	// the equivalent struct field). Returning a non-nil error fails
	// process start; the caller logs and exits.
	//
	// Plugins MUST NOT perform background work, open files, or start
	// goroutines from Init unless those resources are owned and closed
	// in Close. Init should be cheap and synchronous.
	Init(cfg map[string]any) error

	// Close is called at process shutdown after the writer has drained.
	// Plugins SHOULD flush any buffered state here. Errors are logged
	// but do not block shutdown.
	Close() error
}

Plugin is the base contract every observe-class plugin satisfies.

A plugin opts into individual hooks by also implementing one of the hook interfaces (ObserveOnFinalize, ObserveAfterWrite). The base contract here is only "I am a named, configurable, closable thing."

type Registry ¶

type Registry struct {
	// contains filtered or unexported fields
}

Registry holds the operator's enabled plugins in registration order.

The order matters: OnFinalize plugins fire in registration order, and a shouldRecord=false return SHORT-CIRCUITS the chain. Operators who care about ordering (e.g. "tag-by-path runs before path-filter so dropped traces still carry the tag in logs") control it via the order of the enabled list in config.

Registry is constructed once at startup and treated as immutable thereafter. There is no hot-reload; restart the process.

func NewRegistry() *Registry

func (r *Registry) Close() error

func (r *Registry) Init(cfgs map[string]map[string]any) error

func (r *Registry) IterateAfterWrite(ctx context.Context, tr trace.Trace)

func (r *Registry) IterateOnFinalize(ctx context.Context, tr trace.Trace) (shouldRecord bool, errs []error)

func (r *Registry) Plugins() []Plugin

func (r *Registry) Register(p Plugin) error