broker

package
v0.6.23 Latest Latest
Warning

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

Go to latest
Published: Oct 21, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package broker carries events over NATS JetStream (design §8).

Every service has one stream, bp_<service>, with subjects bp.<service>.<Event>. The emitter creates or updates it at start with the operator's Streams (its configuration wins); a subscriber creates it when missing, with the platform defaults, so it exists before the emitter first runs. Events are CloudEvents in NATS binary mode: ce-* headers, JSON data, Nats-Msg-Id = ce-id for deduplication and the W3C trace context. The publisher may set ce-id itself (an outbox's id), ce-time and extension attributes.

A reactor is a durable pull consumer <subscriber>__<consumer> filtered on one event, delivered as its env.Delivery says over the broker's defaults. A handler that fails is redelivered with a growing delay; when the last delivery fails, or the handler marks its error terminal, the message goes to the dead-letter subject bp.dlq.<subscriber>.<consumer> (stream bp_dlq_<subscriber>) and is terminated. A handler cancelled by the service's stop is nacked without a delay and never dead-lettered. A consumer deleted on the server while the service runs is recreated at the reactor's position (the oldest unsettled message, else after the newest one seen) and consumption resumes.

NATS is optional and may be down: Connect does not wait for it, streams and consumers are ensured in the background, Publish fails fast while disconnected, and consumption resumes after a reconnect.

Index

Constants

View Source
const (
	HeaderSpecVersion = wire.HeaderSpecVersion
	HeaderID          = wire.HeaderID
	HeaderSource      = wire.HeaderSource
	HeaderType        = wire.HeaderType
	HeaderTime        = wire.HeaderTime
	HeaderSubject     = wire.HeaderSubject
	HeaderContentType = wire.HeaderContentType
	HeaderInstance    = wire.HeaderInstance
	HeaderVersion     = wire.HeaderVersion
	// HeaderMIME is the binding's content type header.
	HeaderMIME = wire.HeaderMIME

	// HeaderError and HeaderConsumer are added to a dead letter: the last
	// handler error and the reactor that gave up.
	HeaderError    = wire.HeaderError
	HeaderConsumer = wire.HeaderConsumer
	// HeaderDelivered: deliveries before the message was dead-lettered.
	HeaderDelivered = wire.HeaderDelivered
)

CloudEvents over the NATS binding (binary mode): attributes and extensions are ce-* headers, the payload is the data. The names are the wire contract's (internal/wire).

Variables

View Source
var (
	// ErrEventName: an event name is not "<service>.<Event>".
	ErrEventName = wire.ErrEventName
	// ErrReserved: the service name is reserved for dead letters.
	ErrReserved = errors.New("broker: service name dlq is reserved for dead letters")
)

Errors of names.

View Source
var (
	// ErrHandlerPanic: a reactor's handler panicked.
	ErrHandlerPanic = errors.New("broker: reactor handler panicked")
	// ErrStopTimeout: handlers in flight did not finish within the stop
	// budget and were cancelled.
	ErrStopTimeout = errors.New("broker: reactor handlers did not finish in time")
)

Errors of reactors.

View Source
var (
	// ErrNoReactor: the service declares no reactor with that consumer.
	ErrNoReactor = errors.New("broker: no such reactor")
	// ErrRedrive: some dead letters failed again and stay dead letters.
	ErrRedrive = errors.New("broker: dead letters failed again")
)

Errors of Redrive.

View Source
var ErrNoService = errors.New("broker: service name is empty")

ErrNoService: the broker has no service name to derive NATS names from.

View Source
var ErrNotConnected = errors.New("broker: nats not connected")

ErrNotConnected: NATS is not reachable right now.

Functions

func DLQStreamName

func DLQStreamName(subscriber string) string

DLQStreamName of the dead letters of subscriber's reactors: bp_dlq_<subscriber>.

func DLQStreamSubjects

func DLQStreamSubjects(subscriber string) string

DLQStreamSubjects of subscriber's dead-letter stream: bp.dlq.<subscriber>.>.

func DLQSubject

func DLQSubject(subscriber, consumer string) string

DLQSubject of the dead letters of one reactor: bp.dlq.<subscriber>.<consumer>.

func Durable

func Durable(subscriber, consumer string) string

Durable name of subscriber's reactor consumer: <subscriber>__<consumer>.

func RedriveSubject

func RedriveSubject(source, subscriber, consumer string) string

RedriveSubject of one reactor's dead letters published back to it by backplane: bp.<source>._redrive.<subscriber>.<consumer>.

func SplitEvent

func SplitEvent(full string) (string, string, error)

SplitEvent splits a full event name "<service>.<Event>" at its first dot.

func StreamName

func StreamName(service string) string

StreamName of service's events: bp_<service>.

func StreamSubjects

func StreamSubjects(service string) string

StreamSubjects of service's stream: bp.<service>.>.

func Subject

func Subject(service, name string) string

Subject of service's event name: bp.<service>.<Event>.

func Token

func Token(s string) string

Token escapes s into one NATS token (wire.Token).

Types

type Broker

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

Broker is the service's NATS connection: it publishes the service's events and runs its reactors.

func New

func New(p Params) *Broker

New creates the broker; nothing connects until Connect.

func (*Broker) Close

func (b *Broker) Close(ctx context.Context) error

Close drains and closes the connection.

func (*Broker) Connect

func (b *Broker) Connect(ctx context.Context, g node.Group) error

Connect connects without blocking on an unreachable NATS and ensures the service's stream; background work runs on g.

func (*Broker) Connected

func (b *Broker) Connected() bool

Connected reports whether the NATS connection is up right now.

func (*Broker) JetStream

func (b *Broker) JetStream() (jetstream.JetStream, error)

JetStream is the service's own JetStream handle, for what the SDK does not wrap. It fails with env.ErrUnavailable before Connect and after Close; while the connection is down it is returned all the same (it reconnects by itself, its calls fail meanwhile).

func (*Broker) Publish

func (b *Broker) Publish(ctx context.Context, m env.Message) error

Publish implements env.Broker: m.Event is the full name "<service>.<Event>" of one of the service's events, m.Payload its JSON. It returns once JetStream acknowledged the event, and fails fast while NATS is unreachable.

func (*Broker) Redrive

func (b *Broker) Redrive(ctx context.Context, consumer string) (int, error)

Redrive runs the handler of the reactor named consumer on its dead letters, oldest first, in this process, and deletes each one it handled. A dead letter that fails again stays where it is. Dead letters that arrive meanwhile are left for the next call. It returns how many were handled; ErrRedrive (with the first failure) when some failed.

Only this reactor sees the events again: they are not published to their source stream, where every subscriber would get them.

func (*Broker) StartReactors

func (b *Broker) StartReactors(ctx context.Context, g node.Group) error

StartReactors starts a durable consumer per declared reactor on g.

func (*Broker) StopReactors

func (b *Broker) StopReactors(ctx context.Context) error

StopReactors stops consuming and waits for handlers in flight; when ctx ends first, their contexts are cancelled and get nakGrace to nak while the connection is still open.

type Params

type Params struct {
	// Conn is the connection: URL, credentials, TLS.
	Conn infranats.Config
	// PublishTimeout bounds a Publish whose ctx has no deadline; zero is
	// the default (5s).
	PublishTimeout time.Duration
	Service        string
	Instance       string
	Version        string
	Log            *xlog.Logger
	Env            *env.Env
	// Streams the service owns; the zero value takes the platform
	// defaults.
	Streams Streams
}

Params of New.

type Streams

type Streams struct {
	MaxAge     time.Duration // retention of the service's events
	MaxBytes   int64         // size of the event stream, oldest dropped first
	Replicas   int           // of both streams
	Duplicates time.Duration // dedup window of the event stream
	DeadMaxAge time.Duration // retention of the dead letters
}

Streams are the operator's settings of the streams the service owns: its event stream bp_<service> and its dead letters bp_dlq_<service>. Zero MaxAge, MaxBytes or DeadMaxAge mean unlimited.

func DefaultStreams

func DefaultStreams() Streams

DefaultStreams are the platform defaults of Streams.

Jump to

Keyboard shortcuts

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