pubsub

package
v0.12.11 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 3, 2026 License: AGPL-3.0 Imports: 6 Imported by: 0

Documentation

Overview

Package pubsub is the Clawker Control Plane's type-safe, in-memory pub/sub engine: a dumb pipe that transports strongly-typed enveloped events and nothing else. It has no notion of state, stores, or any domain — it knows about envelopes and subscribers, never about agents, containers, or firewalls. Domains depend on this package; this package depends only on internal/logger (for audit lines) and github.com/rs/zerolog (for the LogObjectMarshaler type the single internal audit hook embeds — the one tolerated type assertion; there is no payload-identity interface).

The pipe emits exactly one structured audit line per accepted Publish via a single internal hook NewTopic attaches per topic; the orchestrator wires ZERO hooks and there is no public hook surface. The audit line keys on the envelope Source + Timestamp, never on a payload method.

Resilience is the package's reason to be careful. In the Clawker CP a panic is a security incident, not an availability one: it kills PID 1, skips drain-to-zero, and leaves eBPF programs pinned and unsupervised while the user believes the firewall is enforcing. Because the bus sits on the hot path of every CP event, the engine never fans out via a bare `go handler(event)`: every handler invocation runs under recover, each subscriber owns a bounded buffer with counted drop-oldest on overflow, Publish is non-blocking with a back-pressure signal, and construction returns (*Topic[T], error) rather than panicking.

Index

Constants

View Source
const DefaultBuffer = 256

DefaultBuffer is the per-subscriber queue depth used when no WithBuffer option is supplied. It bounds how many undelivered events a slow consumer may hold before drop-oldest begins evicting.

View Source
const DefaultStatsInterval = 30 * time.Second

DefaultStatsInterval is the heartbeat period used when NewStatsHeartbeat is given a non-positive interval. It matches the cadence the CP orchestrator historically used for its pub/sub stats heartbeat.

Variables

View Source
var (
	// ErrNilLogger is returned by NewTopic when no logger is provided. The
	// engine logs recovered panics for audit, so a logger is mandatory.
	ErrNilLogger = errors.New("pubsub: logger must not be nil")
	// ErrInvalidBuffer is returned by NewTopic when the configured
	// per-subscriber buffer is not a positive integer.
	ErrInvalidBuffer = errors.New("pubsub: buffer size must be positive")
	// ErrTopicClosed classifies a publish to a closed topic. Publish itself
	// signals this via a false return; the sentinel is for callers that want
	// to reason about the cause.
	ErrTopicClosed = errors.New("pubsub: topic is closed")
)

Sentinel errors let callers classify construction and delivery outcomes without string matching.

Functions

This section is empty.

Types

type Event

type Event[T any] struct {
	// ID identifies this event instance.
	ID string
	// Timestamp is the event time as Unix nanoseconds (time.Now().UnixNano()),
	// a compact, monotonic-friendly in-memory value.
	Timestamp int64
	// Source names the producer that published the event.
	Source string
	// Payload is the strongly-typed domain struct.
	Payload T
}

Event wraps a strongly-typed payload with routing metadata. The four fields are the entire envelope: the raw domain struct rides in Payload, separating domain data from routing metadata. Payload is a plain T with no method contract — consumers read it natively (event.Payload.Action) with no type assertion and no JSON.

type Option

type Option func(*topicOptions)

Option configures a Topic at construction time.

func WithBuffer

func WithBuffer(n int) Option

WithBuffer sets the per-subscriber bounded buffer depth. A non-positive value makes NewTopic return ErrInvalidBuffer rather than panicking.

type Stats

type Stats struct {
	// Subscribers is the number of currently-registered handlers.
	Subscribers int
	// QueueCapacity is the per-subscriber bounded buffer depth.
	QueueCapacity int
	// PublishedTotal is the count of events accepted by Publish (returned true).
	PublishedTotal int64
	// DroppedTotal is the count of events evicted by drop-oldest across all
	// subscriber buffers.
	DroppedTotal int64
	// PanicsRecovered is the count of subscriber panics contained by recover.
	PanicsRecovered int64
	// HookPanicsRecovered is the count of audit-hook panics contained by
	// recover. Tracked separately from PanicsRecovered so an operator can tell
	// a panicking payload MarshalZerologObject (in the audit hook) from a buggy
	// subscriber.
	HookPanicsRecovered int64
}

Stats is a snapshot of a topic's pipe counters. It carries ONLY transport metrics — the engine holds no application state, so there are no domain-specific fields here.

type StatsHeartbeat

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

StatsHeartbeat is a periodic, recover-guarded telemetry loop. It samples each injected StatsSource once per interval and writes the result to the CP log, giving an operator tailing the log a coarse health signal without a dedicated metrics surface. It holds no domain state: every number it logs is pulled, at tick time, from a source the orchestrator owns.

Like every long-lived CP goroutine, its loop runs under recover: in the clawker CP a panic is a security incident, not an availability one, so a future panic in a StatsSource must not silently kill the heartbeat and leave the operator without telemetry (CP CLAUDE.md, hard rule 3).

func NewStatsHeartbeat

func NewStatsHeartbeat(log *logger.Logger, interval time.Duration, sources ...StatsSource) *StatsHeartbeat

NewStatsHeartbeat constructs a heartbeat that samples sources every interval. A non-positive interval falls back to DefaultStatsInterval. It never panics; a nil logger or empty source list yields a heartbeat whose Start loop simply has nothing to log. Construction does not start the loop — call Start.

func (*StatsHeartbeat) Start

func (h *StatsHeartbeat) Start(ctx context.Context)

Start launches the heartbeat loop on its own goroutine and returns immediately. The loop ticks every interval, sampling and logging each source, and exits when ctx is cancelled. The loop body runs under recover so a panic in a StatsSource is contained and audited (event=pubsub_stats_heartbeat_panic) rather than killing the goroutine and stranding the operator without telemetry. The heartbeat owns no resources beyond the ticker, which it stops on exit; ctx cancellation is the only stop signal.

type StatsSource

type StatsSource interface {
	// LogSnapshot samples the source's current values and writes them as a
	// single structured log line. It is called once per heartbeat tick. It must
	// not panic on its own account; if it does, the heartbeat goroutine's
	// recover contains it (so a buggy source can't strand eBPF), but the loop
	// continues and other sources are unaffected only until the panicking tick —
	// keep LogSnapshot non-panicking and non-blocking.
	LogSnapshot(log *logger.Logger)
}

StatsSource is a read-only telemetry source the heartbeat samples once per tick and writes to the CP log. The heartbeat holds no state of its own: every number it reports is pulled, at tick time, from a source the orchestrator injects. Sources are the orchestrator's domain knowledge (a topic's transport counters, the agent domain's observed-now worldview size); the heartbeat is the dumb timer that samples and logs them. A source must be safe to call from the heartbeat goroutine and must never block.

type Topic

type Topic[T any] struct {
	// contains filtered or unexported fields
}

Topic manages subscribers for a SPECIFIC generic schema type T. It is the only public surface of the pipe; there is no multi-topic bus that erases to any on the public API.

func NewTopic

func NewTopic[T any](log *logger.Logger, opts ...Option) (*Topic[T], error)

NewTopic constructs a topic for payload type T. It returns (*Topic[T], error) and never panics: a nil logger or a non-positive buffer degrades to a typed error the orchestrator can surface as event=<subsystem>_unavailable.

func (*Topic[T]) Close

func (t *Topic[T]) Close() error

Close shuts the topic down: it stops accepting publishes, closes every subscriber queue so the drain goroutines exit cleanly, and waits for them. It is idempotent — a second Close is a no-op and never panics.

func (*Topic[T]) Publish

func (t *Topic[T]) Publish(event Event[T]) bool

Publish enqueues event to every current subscriber and returns whether the event was accepted. It is non-blocking: a closed topic returns false immediately, and a full subscriber buffer triggers counted drop-oldest rather than blocking the producer into deadlock. The hook, if any, runs once before fan-out.

func (*Topic[T]) Stats

func (t *Topic[T]) Stats() Stats

Stats returns a snapshot of the topic's pipe counters.

func (*Topic[T]) Subscribe

func (t *Topic[T]) Subscribe(handler func(Event[T]))

Subscribe registers handler as a typed consumer. The handler signature must match the topic's type parameter T exactly — the compiler rejects a mismatch. Each subscriber gets its own bounded buffer and drain goroutine. Subscribing to a closed topic is a no-op.

type TopicStatsSource

type TopicStatsSource struct {
	// Name labels the topic in the log line (e.g. "docker", "agent").
	Name string
	// Stats samples the topic's current transport counters. Typically the
	// topic's own Stats method value (topic.Stats).
	Stats func() Stats
}

TopicStatsSource adapts a topic's Stats() accessor to a StatsSource. It logs the named topic's transport counters — the exact field set Topic.Stats reports — on every tick. The accessor is a func rather than a *Topic[T] so the heartbeat stays type-parameter-free and can sample heterogeneous topics (docker, agent, ebpf_enrolled) through one slice.

func NewTopicStatsSource

func NewTopicStatsSource(name string, stats func() Stats) TopicStatsSource

NewTopicStatsSource builds a StatsSource that logs name's transport counters, sampling them through stats once per tick.

func (TopicStatsSource) LogSnapshot

func (s TopicStatsSource) LogSnapshot(log *logger.Logger)

LogSnapshot writes one "pubsub stats heartbeat" line carrying the topic's six transport counters. The field set and message are byte-for-byte the ones the CP orchestrator emitted before this was extracted.

type WorldviewStatsSource

type WorldviewStatsSource struct {
	// Topic labels the worldview in the log line (e.g. "agent").
	Topic string
	// Size returns the domain's current observed-now worldview size. Typically
	// a read-only accessor like agentRepo.Agents.Len.
	Size func() int
}

WorldviewStatsSource adapts a domain's read-only worldview-size accessor to a StatsSource. The pub/sub pipe holds zero application state, so a domain that owns the faithful home of a count (the agent Repository's observed-now store) exposes its size through a read-only accessor; this source samples it. It is generic over which domain via the injected Size closure.

func NewWorldviewStatsSource

func NewWorldviewStatsSource(topic string, size func() int) WorldviewStatsSource

NewWorldviewStatsSource builds a StatsSource that logs the domain worldview size for topic, sampling it through size once per tick.

func (WorldviewStatsSource) LogSnapshot

func (s WorldviewStatsSource) LogSnapshot(log *logger.Logger)

LogSnapshot writes one "agent worldview heartbeat" line carrying the domain's observed-now worldview size. The field set and message are byte-for-byte the ones the CP orchestrator emitted before this was extracted.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL