outbox

Documentation

Overview

Package outbox provides the producer-side helpers for writing events to the outbox table and waking the per-org Svix relay workflow.

Typical usage from a service handler:

id, err := outbox.NewWriter(db).Insert(ctx, tx, outbox.InsertParams{
    OrganizationID: orgID,
    EventType:      "audit_log:created",
    Payload:        payloadJSON,
})
if err != nil { ... }
// commit the caller's tx, then:
signaler.SignalRelay(ctx, orgID)

The signal MUST be issued after the caller's transaction commits. Issuing it earlier risks waking the workflow before the row is visible to other connections; if the commit later fails the workflow will see no work and exit, with the next producer signal eventually doing the relay.

Index

• type AppendBatchResult
  • func AppendBatch(ctx context.Context, dbtx repo.DBTX, ps []AppendParams) (AppendBatchResult, error)
• type AppendParams
• type AppendResult
  • func Append(ctx context.Context, dbtx DBTX, p AppendParams) (AppendResult, error)
• type DBTX
• type EventType

Types

type AppendBatchResult

type AppendBatchResult struct {
	Count int64
}

func AppendBatch

func AppendBatch(ctx context.Context, dbtx repo.DBTX, ps []AppendParams) (AppendBatchResult, error)

AppendBatch inserts multiple outbox events for an organization and returns the count of inserted rows. This is a much more efficient alternative to multiple calls to Append when queuing many events at once.

THIS METHOD MUST BE CALLED WITHIN A TRANSACTION.

type AppendParams

type AppendParams struct {
	OrganizationID string
	EventType      EventType
	Payload        any
}

AppendParams is the producer-facing payload for queuing an event.

type AppendResult

type AppendResult struct {
	ID             int64
	OrganizationID string
}

AppendResult identifies the inserted row.

func Append

func Append(ctx context.Context, dbtx DBTX, p AppendParams) (AppendResult, error)

Append inserts a new outbox event for an organization.

THIS METHOD MUST BE CALLED WITHIN A TRANSACTION.

type DBTX

type DBTX interface {
	Exec(context.Context, string, ...any) (pgconn.CommandTag, error)
	Query(context.Context, string, ...any) (pgx.Rows, error)
	QueryRow(context.Context, string, ...any) pgx.Row
}

type EventType

type EventType string

const (
	EventTypeAuditLogCreated EventType = "audit_log.created"
)