outbox

package
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Nov 2, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package outbox 是事务性发件箱的 PG/bun 实现(root outbox 形状的可插 dialect 落地):Append 经 buntx.Conn 参与调用方事务(四件一拍), ClaimBatch 以 FOR UPDATE SKIP LOCKED 并发安全拉取,MarkPublished/ MarkFailed 走 at-least-once 语义。Pump 用 periodic 驱动轮询循环。

DDL 见 migrations/00001_outbox.sql(应用经 goosekit 挂链或手工执行)。

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewPump

func NewPump(opts PumpOptions) lynx.Service

NewPump 构造发件箱泵(lynx.Service,直挂 Assembly.Services)。 循环骨架经 periodic(预算轮次/WithoutCancel 不腰斩/panic 恢复全继承)。

func PumpOnce

func PumpOnce(ctx context.Context, store outbox.Store, sink outbox.Sink, batch, maxAttempts int) error

pumpOnce 执行一轮:拉取→投递→标记(失败释放重投)。 PumpOnce 执行一轮(导出:测试与手动运维面)。

Types

type BusSink

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

BusSink 把记录投递到进程内事件总线(events.BusPublisher 形态的 Sink 适配——信封 JSON 反序列化后经 bus.Publish 发布)。

func NewBusSink

func NewBusSink(bus interface {
	Publish(ctx context.Context, topic string, payload any) (string, error)
}) *BusSink

NewBusSink 构造(bus 是 lynx eventbus.Bus)。

func (*BusSink) Deliver

func (s *BusSink) Deliver(ctx context.Context, records []outbox.Record) error

Deliver 实现 outbox.Sink。

type PumpOptions

type PumpOptions struct {
	// Store 存储(必填)。
	Store outbox.Store
	// Sink 投递端口(必填;进程内用 BusSink,跨进程自带适配)。
	Sink outbox.Sink
	// Interval 轮询间隔(默认 5s;LISTEN/NOTIFY 唤醒是 PG 专属优化,
	// 轮询是可移植基线——torchwood 同款兜底)。
	Interval time.Duration
	// BatchSize 单批最大条数(默认 256,torchwood 实证值)。
	BatchSize int
	// MaxAttempts 重试上限(默认 10,torchwood 实证值;超限死信)。
	MaxAttempts int
	// Logger 日志。
	Logger *slog.Logger
}

PumpOptions 是泵配置。

type Store

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

Store 实现 outbox.Store(PG)。

func NewStore

func NewStore(db *bun.DB) *Store

NewStore 构造。

func (*Store) Append

func (s *Store) Append(ctx context.Context, r outbox.Record) error

Append 在调用方事务内写入一条(buntx.Conn:ctx 携带事务则加入)。

func (*Store) ClaimBatch

func (s *Store) ClaimBatch(ctx context.Context, batchSize, maxAttempts int, now time.Time) ([]outbox.Record, error)

ClaimBatch 以 FOR UPDATE SKIP LOCKED 拉取一批待发(多泵并发安全)。 同时递增 attempts 并标记 claimed_at;超限(attempts >= maxAttempts) 的记录标记 dead(不再返回)。返回空切片 = 无待发。

func (*Store) MarkFailed

func (s *Store) MarkFailed(ctx context.Context, ids []string, now time.Time) error

MarkFailed 释放回待发(claimed_at 清空;下轮重投)。

func (*Store) MarkPublished

func (s *Store) MarkPublished(ctx context.Context, ids []string, now time.Time) error

MarkPublished 标记一批为已投递。

Directories

Path Synopsis
Package migrations embeds the outbox table migration (goose format).
Package migrations embeds the outbox table migration (goose format).

Jump to

Keyboard shortcuts

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