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
- Variables
- func DLQStreamName(subscriber string) string
- func DLQStreamSubjects(subscriber string) string
- func DLQSubject(subscriber, consumer string) string
- func Durable(subscriber, consumer string) string
- func RedriveSubject(source, subscriber, consumer string) string
- func SplitEvent(full string) (string, string, error)
- func StreamName(service string) string
- func StreamSubjects(service string) string
- func Subject(service, name string) string
- func Token(s string) string
- type Broker
- func (b *Broker) Alive() error
- func (b *Broker) Close(ctx context.Context) error
- func (b *Broker) Connect(ctx context.Context, g node.Group) error
- func (b *Broker) Connected() bool
- func (b *Broker) JetStream() (jetstream.JetStream, error)
- func (b *Broker) Publish(ctx context.Context, m env.Message) error
- func (b *Broker) Ready(ctx context.Context) error
- func (b *Broker) Redrive(ctx context.Context, consumer string) (int, error)
- func (b *Broker) StartReactors(ctx context.Context, g node.Group) error
- func (b *Broker) StopReactors(ctx context.Context) error
- type Params
- type Streams
Constants ¶
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 ¶
var ( // ErrDisconnected: the NATS connection is down (reconnecting). ErrDisconnected = errors.New("broker: nats not connected") // ErrJetStream: the connection is up but JetStream does not answer. ErrJetStream = errors.New("broker: jetstream unavailable") )
Errors of Ready.
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.
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.
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.
var ErrClosed = errors.New("broker: the NATS connection closed for good")
ErrClosed: the NATS connection closed for good without Close; it recovers only with a restart of the process.
var ErrNoService = errors.New("broker: service name is empty")
ErrNoService: the broker has no service name to derive NATS names from.
var ErrNotConnected = errors.New("broker: nats not connected")
ErrNotConnected: NATS is not reachable right now.
Functions ¶
func DLQStreamName ¶
DLQStreamName of the dead letters of subscriber's reactors: bp_dlq_<subscriber>.
func DLQStreamSubjects ¶
DLQStreamSubjects of subscriber's dead-letter stream: bp.dlq.<subscriber>.>.
func DLQSubject ¶
DLQSubject of the dead letters of one reactor: bp.dlq.<subscriber>.<consumer>.
func RedriveSubject ¶
RedriveSubject of one reactor's dead letters published back to it by backplane: bp.<source>._redrive.<subscriber>.<consumer>.
func SplitEvent ¶
SplitEvent splits a full event name "<service>.<Event>" at its first dot.
func StreamName ¶
StreamName of service's events: bp_<service>.
func StreamSubjects ¶
StreamSubjects of service's stream: bp.<service>.>.
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 (*Broker) Alive ¶ added in v0.6.72
Alive is nil while the connection is up or reconnecting, ErrClosed once it closed by itself.
func (*Broker) Connect ¶
Connect connects without blocking on an unreachable NATS and ensures the service's stream; background work runs on g.
func (*Broker) JetStream ¶
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 ¶
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) Ready ¶ added in v0.6.84
Ready is nil while the connection is up and JetStream answers an account info request within ctx: a server can hold the connection while JetStream has no meta leader, full storage or lost its cluster, and then the bus's streams and consumers fail.
func (*Broker) Redrive ¶
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 ¶
StartReactors starts a durable consumer per declared reactor on g.
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.