Documentation
¶
Overview ¶
Package clusterbus is the small surface components use to take part in a cluster: publishing and receiving events on the cluster bus, knowing their own node ID and which nodes are alive, and dropping in-memory caches when another node writes the shared database (Invalidator).
Components take a Bus or Node through a setter or constructor option and treat nil as "standalone": a standalone server never publishes, so its behaviour is exactly that of a single process. internal/app adapts the cluster runtime with FromCluster, and only when the database is shared.
Index ¶
Constants ¶
const MaxPayload = cluster.MaxPayload
MaxPayload is the largest event payload the bus carries.
const PublishTimeout = 5 * time.Second
PublishTimeout bounds one Publish made on behalf of a local write.
const TopicResync = cluster.TopicResync
TopicResync is delivered locally after the bus reconnected: events may have been missed, so every bus-maintained cache must be dropped.
Variables ¶
var ErrPayloadTooLarge = errors.New("clusterbus: payload too large")
ErrPayloadTooLarge mirrors the cluster bus limit.
Functions ¶
func NewOrigin ¶
func NewOrigin() string
NewOrigin returns a random ID for one component instance, used to recognise (and skip) its own events when the bus echoes them back.
Types ¶
type ApplyFunc ¶
ApplyFunc reloads or clears a component's caches. all is true after a bus resync, an oversized burst or an event without a hint; otherwise hints lists the keys other nodes reported changing.
type Bus ¶
type Bus interface {
Publish(ctx context.Context, topic string, payload []byte) error
Subscribe(topic string, fn func(payload []byte)) (unsubscribe func())
}
Bus publishes and receives cluster events. Publish also delivers to this node's own subscribers (synchronously), so receivers that must ignore their own events tag payloads with an Origin.
type Hub ¶
type Hub struct {
// contains filtered or unexported fields
}
Hub is an in-memory cluster bus shared by several nodes in one process, for tests: Publish delivers synchronously to every subscriber on every node (the publisher's own included, as the PostgreSQL bus does) and enforces MaxPayload. Nodes are live until Kill.
type Invalidator ¶
type Invalidator struct {
// contains filtered or unexported fields
}
Invalidator keeps one component's in-memory caches consistent with writes made by other nodes: after a local write the component calls Notify; every other node's Invalidator for the same component runs apply on a worker goroutine (bursts are coalesced; bus callbacks never block). Its own events are ignored. After a bus resync apply runs with all=true.
A nil *Invalidator is valid and does nothing, which is what a standalone server uses.
func NewInvalidator ¶
NewInvalidator subscribes to "invalidate:<component>" on bus. A nil bus returns nil.
func (*Invalidator) Applied ¶
func (iv *Invalidator) Applied() int
Applied reports how many apply runs have completed (tests).
func (*Invalidator) Close ¶
func (iv *Invalidator) Close()
Close unsubscribes and stops the worker after any apply in progress.
func (*Invalidator) Notify ¶
func (iv *Invalidator) Notify(hint string)
Notify tells the other nodes that this node changed the component's data (hint optionally names what changed; "" means everything). It publishes synchronously with a short timeout; failures are logged, not returned: the write itself succeeded, and peers also reload on a bus resync.
Source Files