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 ¶
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 ¶
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 (*Notifier) Close ¶
func (n *Notifier) Close()
Close stops the worker and waits for it to drain. Safe to call once.