inbox

package
v0.7.2 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package inbox is the coordinator-inbox notifier: the optional Layer-2 discovery for 1-1 spaces (docs/one-to-one-spaces.md). It funnels the coordinator's push stream and a periodic poll into a single serialized worker that fetches inbox messages, verifies + decrypts each, and hands the result to a caller-supplied handler.

Guarantees (docs/one-to-one-spaces.md § "Heart bugs we fix"): the cursor advances once per batch, after the handler commits, to the furthest handled message (no process-before-persist loss); content failures (verify/decrypt) are skipped with a loud log while transient failures (Fetch error, handler ErrRetry) halt the cursor and retry; both triggers feed one worker, so nothing is processed twice concurrently. The cursor is synced and account-scoped; load/save are injected.

Index

Constants

This section is empty.

Variables

View Source
var ErrRetry = errors.New("inbox: retry")

ErrRetry, returned by a Handler, marks a TRANSIENT failure (e.g. a local write that should be retried). The notifier halts the cursor at that message and reprocesses it on the next pass. Any other handler outcome (nil, or a non-retry error) advances the cursor past the message — the handler is expected to swallow permanent conditions.

Functions

This section is empty.

Types

type Deps

type Deps struct {
	// Fetch pulls messages from the coordinator inbox.
	Fetch FetchFunc
	// MyKey is the account private key used to decrypt message bodies
	// (bodies are ECIES-encrypted to our account public key on send).
	MyKey crypto.PrivKey
	// Handle receives each verified, decrypted message.
	Handle Handler
	// LoadCursor returns the persisted start offset ("" = from the
	// beginning). SaveCursor persists an advanced offset (monotonic-
	// forward). Both back onto the SYNCED, account-scoped tech-space
	// cursor — so a fresh device seeds from the account's read position
	// instead of replaying the whole inbox; everything below it is already
	// represented by synced 1-1 rows (the correctness truth). Idempotent
	// processing makes a synced cursor safe (see docs/one-to-one-spaces.md § "Heart bugs we
	// fix" #3).
	LoadCursor func(ctx context.Context) (string, error)
	SaveCursor func(ctx context.Context, offset string) error
	// ReplayGuard, if set, is consulted before a pass whose loaded
	// cursor is EMPTY — the full-replay case. A non-nil error defers the
	// whole pass; the next tick/kick retries. On an established account
	// an empty cursor is indistinguishable from "the synced cursor
	// hasn't reached this device yet": fetching would replay the entire
	// inbox and resurrect long-resolved invites as pending rows (the
	// row-level dedup can't help — the synced rows are equally missing).
	// The guard returns nil only once local state provably reflects the
	// account's synced truth; from then on an empty cursor really means
	// "nothing processed ever" and a from-the-beginning fetch is
	// correct. The first nil is latched for the notifier's lifetime —
	// convergence can only advance within one process, so an account
	// with no inbox history doesn't pay the guard on every pass. Not
	// consulted when the cursor is non-empty.
	ReplayGuard func(ctx context.Context) error
	// Interval is the poll fallback cadence. The push stream drives
	// latency; this is the safety net for missed/disconnected pushes.
	Interval time.Duration
}

Deps configures a Notifier.

type FetchFunc

type FetchFunc func(ctx context.Context, offset string) (msgs []*coordinatorproto.InboxMessage, hasMore bool, err error)

FetchFunc fetches inbox messages after offset (empty offset = from the beginning). Bodies are returned still encrypted — the notifier verifies + decrypts. Matches any-sync inboxclient.InboxFetch.

type Handler

type Handler func(ctx context.Context, m Message) error

Handler processes one verified message. Return nil on success, ErrRetry for a transient failure (halts + retries the cursor), or any other error to log-and-skip (advances the cursor). The handler must be idempotent: a message can be re-delivered (crash mid-pass, coordinator resend) and the single crash-replay reprocesses the last message.

type Message

type Message struct {
	Id             string
	SenderIdentity string
	PayloadType    coordinatorproto.InboxPayloadType
	Body           []byte
	Timestamp      int64
}

Message is one verified, decrypted inbox message handed to a Handler. SenderIdentity is the coordinator-verified account address (the body signature checked against it) — the authoritative peer identity, NOT anything self-declared inside Body.

type Notifier

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

Notifier owns the single serialized worker. Construct with New, drive with Run; Notify kicks an immediate pass; Close stops and drains.

func New

func New(d Deps) *Notifier

New builds a Notifier. It does not start the worker — call Run.

func (*Notifier) Close

func (n *Notifier) Close()

Close stops the worker and waits for it to drain. Safe to call once.

func (*Notifier) Notify

func (n *Notifier) Notify()

Notify wakes the worker for an immediate pass. Non-blocking and coalescing (buffered-1 kick). Called by the coordinator push forwarder and by send-on-initiate (so the sender's own devices converge quickly).

func (*Notifier) Run

func (n *Notifier) Run(context.Context)

Run starts the worker goroutine bound to a fresh cancellable context. Idempotent: a second call while running is a no-op.

Jump to

Keyboard shortcuts

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