Documentation
¶
Index ¶
- Constants
- func RegisterRelayService(registrar ServiceRegistrar, relay *Relay)
- func RegisterStoreService(registrar ServiceRegistrar, store *Store)
- type Message
- type MessageCodec
- type Module
- type ModuleConfig
- type Pending
- type Relay
- type RelayCommand
- type RelayConfig
- type Repository
- type ServiceRegistrar
- type Store
- func (instance *Store) ClaimDueMessages(ctx context.Context, limit int, visibility time.Duration) ([]Pending, error)
- func (instance *Store) Enqueue(ctx context.Context, executor bun.IDB, message any) error
- func (instance *Store) EnsureSchema(ctx context.Context) error
- func (instance *Store) MarkDead(ctx context.Context, id int64, attempts int, lastError string, ...) error
- func (instance *Store) MarkSent(ctx context.Context, id int64, claimToken string) error
- func (instance *Store) RecordDeliveryAttempt(ctx context.Context, id int64, claimToken string) (int, bool, error)
- func (instance *Store) Reschedule(ctx context.Context, id int64, attempts int, availableAt time.Time, ...) error
Constants ¶
const ( StatusPending = "pending" StatusInFlight = "inflight" StatusSent = "sent" StatusDead = "dead" )
const ServiceRelay = "service.outbox.relay"
const ServiceStore = "service.outbox.store"
const TableName = "melody_outbox"
TableName is the outbox table the Store reads and writes.
Variables ¶
This section is empty.
Functions ¶
func RegisterRelayService ¶
func RegisterRelayService(registrar ServiceRegistrar, relay *Relay)
func RegisterStoreService ¶
func RegisterStoreService(registrar ServiceRegistrar, store *Store)
Types ¶
type Message ¶
type Message struct {
bun.BaseModel `bun:"table:melody_outbox"`
Id int64 `bun:"id,pk,autoincrement"`
TypeName string `bun:"type_name,notnull"`
Payload []byte `bun:"payload,notnull"`
Status string `bun:"status,notnull"`
Attempts int `bun:"attempts,notnull"`
DeliveryAttempts int `bun:"delivery_attempts,notnull"`
AvailableAt time.Time `bun:"available_at,notnull"`
CreatedAt time.Time `bun:"created_at,notnull"`
LastError string `bun:"last_error,nullzero"`
ClaimToken string `bun:"claim_token,nullzero"`
}
Message is the outbox table row. The relay-facing fields (status, attempts, delivery_attempts, available_at) drive retry scheduling; payload + type_name are what the codec needs to rebuild the message. Attempts counts send failures (drives backoff and the MaxAttempts dead-letter); delivery_attempts counts every delivery the relay actually attempts for this row (drives the MaxDeliveryAttempts crash-poison cap) — it is advanced per row at delivery time, not for the whole batch at claim time, so a batch-mate the relay never reached is never charged. claim_token is a fencing token rewritten on every claim: each transition write carries the token of the claim it belongs to, so a stale run whose claim has lapsed and been re-claimed by another instance matches no row and cannot clobber the new owner (guarding on status alone is not enough, because a re-claim returns the row to the in-flight state the stale run also holds).
type MessageCodec ¶
type MessageCodec interface {
Encode(message any) (typeName string, payload []byte, err error)
Decode(typeName string, payload []byte) (any, error)
}
MessageCodec encodes a domain message into a durable form for the outbox and decodes it back when the relay publishes it. The application supplies it because only the application knows its message types; a JSON codec over a small type registry is the typical implementation.
type Module ¶
type Module struct {
// contains filtered or unexported fields
}
func NewModule ¶
func NewModule(config ModuleConfig) *Module
func (*Module) Description ¶
func (*Module) RegisterCliCommands ¶
func (instance *Module) RegisterCliCommands(kernelInstance kernelcontract.Kernel) []clicontract.Command
func (*Module) RegisterServices ¶
func (instance *Module) RegisterServices(registrar applicationcontract.ServiceRegistrar)
type ModuleConfig ¶
type ModuleConfig struct {
Store *Store
Relay *Relay
StoreFactory func(resolver containercontract.Resolver) (*Store, error)
RelayFactory func(resolver containercontract.Resolver) (*Relay, error)
}
ModuleConfig wires the outbox services: a prebuilt Store and Relay, or a StoreFactory and RelayFactory registered as the service providers and run at first resolution, for a database not available before Boot; setting both a prebuilt object and its factory panics at RegisterServices. Only the *Store or *Relay a factory returns is registered, so a factory resolves container-owned services rather than opening private connections. The relay never closes its transport, so the composition root registers the transport with the container, through messagebus.RegisterTransports or as a service of its own.
type Pending ¶
type Pending struct {
Id int64
TypeName string
Payload []byte
Attempts int
DeliveryAttempts int
ClaimToken string
}
Pending is a stored outbox row ready to be relayed: the codec type name and payload needed to rebuild the message, plus the retry counters. Attempts is how many sends have failed (drives backoff and the MaxAttempts dead-letter); DeliveryAttempts is the row's stored delivery-attempt count at claim time — the relay advances it per row at delivery time (RecordDeliveryAttempt) and the post-increment value, not this snapshot, drives the MaxDeliveryAttempts crash-poison cap. ClaimToken is the fencing token stamped on the row by the claim that produced this Pending; the relay passes it back to every transition write so a stale run cannot clobber a row another instance has since re-claimed.
type Relay ¶
type Relay struct {
// contains filtered or unexported fields
}
func NewRelay ¶
func NewRelay(config RelayConfig) *Relay
func RelayMustFromContainer ¶
func RelayMustFromContainer(serviceContainer containercontract.Container) *Relay
func RelayMustFromResolver ¶
func RelayMustFromResolver(resolver containercontract.Resolver) *Relay
func (*Relay) RunOnce ¶
func (instance *Relay) RunOnce(runtimeInstance runtimecontract.Runtime) (int, error)
RunOnce drains one batch of due messages and returns how many were published; when a Locker is configured and another instance holds the lease, it returns 0. The lease is an optimisation: every claimed row carries this run's claim token, so a lease lost mid-batch hands no claimed row to the new holder, and the batch is drained to its end, or to a failed send, with the refresh failure reported after it. A repository failure mid-batch ends the run where it happened, and the visibility timeout re-surfaces the unreached rows. A failed send ends the batch too: the relay cannot tell a transport outage from a message the broker refused, and going on would charge every batch-mate an attempt on every pass of an outage, so the failed row alone is charged and the unreached rows are handed back uncharged, held until the failed row is tried again: the lowest id comes first in every claim, so through an outage that row is the only one charged, pass after pass.
type RelayCommand ¶
type RelayCommand struct {
// contains filtered or unexported fields
}
func NewRelayCommand ¶
func NewRelayCommand(relay *Relay) *RelayCommand
func NewRelayCommandFromResolver ¶ added in v3.1.0
func NewRelayCommandFromResolver(resolver containercontract.Resolver) *RelayCommand
NewRelayCommandFromResolver resolves service.outbox.relay on the first batch, opening no database at boot
func (*RelayCommand) Description ¶
func (instance *RelayCommand) Description() string
func (*RelayCommand) Flags ¶
func (instance *RelayCommand) Flags() []clicontract.Flag
func (*RelayCommand) Name ¶
func (instance *RelayCommand) Name() string
func (*RelayCommand) Run ¶
func (instance *RelayCommand) Run( runtimeInstance runtimecontract.Runtime, commandContext *clicontract.CommandContext, ) error
type RelayConfig ¶
type RelayConfig struct {
Repository Repository
/* Transport is what every row is published through. The relay only sends through it and never closes it: on the module's prebuilt path the composition root registers the transport with the container — through messagebus.RegisterTransports, or as a service of its own — so the container's ordered teardown closes it, and on the factory path the factory resolves a container-owned one, as ModuleConfig says. A transport that is neither closes with the process, abruptly. */
Transport messagebuscontract.Transport
Codec MessageCodec
Locker lockcontract.Locker
LockName string
LockTtl time.Duration
/* VisibilityTimeout is how long a claimed (in-flight) row stays hidden from other claimers before it re-surfaces — the safety net that recovers rows an instance claimed but crashed before resolving. It must comfortably exceed the time to drain one batch; defaults to defaultVisibilityTimeout. */
VisibilityTimeout time.Duration
BatchSize int
MaxAttempts int
/* MaxDeliveryAttempts caps how many delivery attempts the relay records for a single row (RecordDeliveryAttempt, once per row it reaches after a claim) before it is dead-lettered as poison, regardless of whether its sends ever returned an error. It is the safety net for a row that crashes (or hangs past the visibility timeout) the relay between claim and resolve: such a row's send-failure attempt count never advances, so without this cap it would re-surface forever and never reach MaxAttempts. It must exceed MaxAttempts because every recorded attempt — including a normal retry's — counts toward it: a value at or below MaxAttempts, an unset zero included, is raised to defaultMaxDeliveryAttemptsFactor * MaxAttempts, saturating at math.MaxInt. */
MaxDeliveryAttempts int
InitialBackoff time.Duration
MaxBackoff time.Duration
BackoffFactor float64
}
RelayConfig configures the outbox relay — the loop that drains pending rows to the message transport with retry, exponential backoff and a dead-letter terminal state. Every batch is claimed atomically (FOR UPDATE SKIP LOCKED), so two instances do not claim the same row while its VisibilityTimeout holds, even without a Locker; the relay stays at-least-once — a send still running when the timeout lapses, or a crash between the send and MarkSent, lets the row be claimed and published again —, and this requires a backend that supports SELECT … FOR UPDATE SKIP LOCKED (PostgreSQL, or MySQL 8+). A Locker is still useful as an additional optimization: supply one (for example the Redis locker) so only one instance does any work at a time in a multi-instance deployment.
type Repository ¶
type Repository interface {
ClaimDueMessages(ctx context.Context, limit int, visibility time.Duration) ([]Pending, error)
/* RecordDeliveryAttempt increments and persists a single row's delivery_attempts and returns the post-increment count. It is called for each row as the relay attempts it, not for the batch at claim time, so a row that crashes or hangs the relay advances only its own crash-poison counter. The claimToken fences the write: claimed is false when this claim does not hold the row any more, re-claimed by another instance or already resolved, and the relay skips it. */
RecordDeliveryAttempt(ctx context.Context, id int64, claimToken string) (deliveryAttempts int, claimed bool, err error)
MarkSent(ctx context.Context, id int64, claimToken string) error
Reschedule(ctx context.Context, id int64, attempts int, availableAt time.Time, lastError string, claimToken string) error
MarkDead(ctx context.Context, id int64, attempts int, lastError string, claimToken string) error
}
Repository is the persistence the relay drives. The bun-backed Store implements it; abstracting it keeps the relay's retry/dead-letter logic unit-testable without a database.
func NewLazyRepository ¶ added in v3.1.0
func NewLazyRepository(resolver containercontract.Resolver) Repository
NewLazyRepository returns a Repository that resolves the registered service.outbox.store on first use; the underlying Store is resolved once and reused, and a failed resolution is retried on the next call.
type ServiceRegistrar ¶
type ServiceRegistrar interface {
RegisterService(serviceName string, provider any, options ...containercontract.RegisterOption)
}
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
func StoreMustFromContainer ¶
func StoreMustFromContainer(serviceContainer containercontract.Container) *Store
func StoreMustFromResolver ¶
func StoreMustFromResolver(resolver containercontract.Resolver) *Store
func (*Store) ClaimDueMessages ¶
func (instance *Store) ClaimDueMessages(ctx context.Context, limit int, visibility time.Duration) ([]Pending, error)
ClaimDueMessages atomically claims a batch of due rows so that concurrent relay instances — even without a shared Locker — never grab the same row. It requires a backend that supports SELECT … FOR UPDATE SKIP LOCKED (PostgreSQL, or MySQL 8+). It selects due rows FOR UPDATE SKIP LOCKED inside a transaction (so a row another instance is claiming is skipped, not blocked on) and flips them to the in-flight state with available_at pushed out by the visibility timeout. A claimed row is therefore invisible to every other claimer until either the relay resolves it (sent/rescheduled/dead) or the visibility timeout lapses — which re-surfaces rows an instance claimed but crashed before resolving. A due row is one that is pending, or already in-flight but past its visibility deadline. Claiming does NOT touch delivery_attempts — that counter is advanced per row when the relay actually attempts delivery (RecordDeliveryAttempt), so a row the relay never reaches (a batch-mate behind a crashing row) is not charged a delivery attempt it never received.
func (*Store) Enqueue ¶
Enqueue serializes a message and inserts it as a pending outbox row using the given executor — pass the caller's bun.Tx so the outbox write commits atomically with the business write, which is the whole point of the pattern.
func (*Store) EnsureSchema ¶
EnsureSchema creates the outbox table for demos and tests. Production code would express this through the bunorm migrate package.
func (*Store) MarkSent ¶
MarkSent resolves the row as sent. Every resolution write is guarded on status in-flight and on the claim's fencing token, since a lapsed claim can be re-claimed back to in-flight by another instance and a status-only write would clobber that owner; with the token a stale run's write matches no row.
func (*Store) RecordDeliveryAttempt ¶
func (instance *Store) RecordDeliveryAttempt(ctx context.Context, id int64, claimToken string) (int, bool, error)
RecordDeliveryAttempt increments a single in-flight row's delivery_attempts and returns the post-increment count, charging only a row the relay actually reached. The read and write run in one transaction under FOR UPDATE, so a concurrent claimer cannot lose an increment. A row whose claim_token does not match this claim, re-claimed by another instance or already resolved, returns claimed=false so the relay skips it; the token, not the status, tells "still mine" from "re-claimed", since a re-claim returns the row to the same in-flight state.