outbox

type AuthError struct{ Err error }

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

type Config struct {
	// Dir is the outbox directory. It is created 0700 if missing.
	Dir string
	// KeyFile is the encryption key file. Default: <Dir>/outbox.key. Point it
	// outside Dir (a mounted secret) to keep the key off the data volume.
	KeyFile string
	// MaxBytes caps the bytes on disk (pending + dead letters). Default 1 GiB.
	MaxBytes int64
	// MaxDiskFraction caps the outbox at this fraction of (its own bytes +
	// the free space). Default 0.5. Negative disables the free-space cap.
	MaxDiskFraction float64
	// MaxAge evicts pending items and dead letters older than this. Default
	// 7 days.
	MaxAge time.Duration
	// Concurrency is how many items are delivered at once (1 or 2). Default 1.
	Concurrency int
	// BackoffBase and BackoffMax bound the per-item retry delay.
	BackoffBase time.Duration
	BackoffMax  time.Duration
	// CircuitThreshold is the number of consecutive transient failures that
	// pause all delivery until the back-off passes or Wake is called.
	CircuitThreshold int
	// Logf receives the outbox's log lines (state changes, evictions,
	// quarantines, dead letters). Default: the standard logger.
	Logf func(format string, args ...any)
	// OnEvict is called (without locks held) after items were evicted to
	// respect the caps.
	OnEvict func(evicted []Meta, reason string)
	// OnDeadLetter is called (without locks held) when an item is
	// dead-lettered.
	OnDeadLetter func(DeadLetter)
	// contains filtered or unexported fields
}

type DeadLetter struct {
	Meta   Meta      `json:"meta"`
	DeadAt time.Time `json:"dead_at"`
	// Status is the HTTP status of the refusal (0 when the SDK refused it).
	Status int `json:"status,omitempty"`
	// Reason is a one-line explanation.
	Reason string `json:"reason"`
	// Problem is the server's RFC 9457 problem document, when it sent one.
	Problem json.RawMessage `json:"problem,omitempty"`
	// Attempts made before the refusal.
	Attempts int `json:"attempts"`
}

type Deliverer interface {
	Deliver(ctx context.Context, d *Delivery) (value any, err error)
}

type DelivererFunc func(ctx context.Context, d *Delivery) (any, error)

type Delivery struct {
	Meta    Meta
	Payload []byte
	// State is the item's state before this attempt (Attempts counts earlier
	// attempts).
	State State
	// contains filtered or unexported fields
}

type Inspection struct {
	Dir             string
	PendingCount    int
	PendingBytes    int64
	OldestPending   time.Time
	DeadLetters     []DeadLetter
	DeadLetterBytes int64
	// Unreadable counts pending entries Inspect could not read (a write in
	// progress, a torn file, another key); the owning process deals with
	// them.
	Unreadable int
}

type Kind string

type Meta struct {
	// ID is a UUIDv7 and the file name. Enqueue assigns it.
	ID   string `json:"id"`
	Kind Kind   `json:"kind"`
	// ReportID is the stable report id (UUIDv7) the v2 protocol uses as the
	// idempotency key. Enqueue assigns one to a KindReport item that has none.
	ReportID string `json:"report_id,omitempty"`
	// CommandID binds the item to a platform command.
	CommandID string `json:"command_id,omitempty"`
	// CreatedAt orders the items (oldest first). Enqueue sets it.
	CreatedAt time.Time `json:"created_at"`
	// Attrs are free-form small strings for the deliverer.
	Attrs map[string]string `json:"attrs,omitempty"`
}

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

type PermanentError struct {
	Status  int
	Reason  string
	Problem json.RawMessage
	Err     error
}

type Result struct {
	// Delivered: the platform acknowledged the item.
	Delivered bool
	// Value is what the Deliverer returned with the acknowledgement.
	Value any
	// Dead is set when the item was dead-lettered.
	Dead *DeadLetter
	// Evicted: the item was dropped by the size or age cap.
	Evicted bool
}

type RetryError struct {
	After time.Duration
	Err   error
}

type State struct {
	Attempts    int       `json:"attempts"`
	NextAttempt time.Time `json:"next_attempt,omitzero"`
	LastError   string    `json:"last_error,omitempty"`
	// RateLimited: the last failure carried a Retry-After, which Wake does
	// not override.
	RateLimited bool `json:"rate_limited,omitempty"`
	// Progress is owned by the deliverer (for example the v2 segments the
	// server already acknowledged); see Delivery.SaveProgress.
	Progress json.RawMessage `json:"progress,omitempty"`
	// LostResults is set on a KindCommandResult item when a result of the
	// same command was dropped before delivery (evicted by the caps, or
	// quarantined as unreadable): the command must not be reported as a
	// clean, complete run. It says why.
	LostResults string `json:"lost_results,omitempty"`
}

type Stats struct {
	PendingCount int
	PendingBytes int64
	// OldestPending is the creation time of the oldest pending item (zero
	// when none).
	OldestPending   time.Time
	DeadLetterCount int
	DeadLetterBytes int64
	// Counters since Open.
	Evicted     int64
	Corrupt     int64
	Delivered   int64
	DeadLetters int64
	Attempts    int64
	LastEvictAt time.Time
	// Delivery control.
	AuthPaused   bool
	CircuitOpen  bool
	CircuitUntil time.Time
	CapBytes     int64
}

type Ticket struct {
	Meta Meta
	// contains filtered or unexported fields
}