Documentation
¶
Overview ¶
Package mailboxpull provides shared retry+backoff primitives for mailbox pull loops. The same shape is needed by the persistent identity-mailbox ingress loop in the parent serverconn package and by per-swap event consumers in the SDK; this package factors that shape out so reliability semantics stay uniform across both consumers.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PullWithRetry ¶
func PullWithRetry(ctx context.Context, edge mailboxpb.MailboxServiceClient, req *mailboxpb.PullRequest, cfg BackoffConfig, log btclog.Logger) (*mailboxpb.PullResponse, error)
PullWithRetry calls edge.Pull, retrying transport errors with exponential backoff until the call succeeds or ctx is done. The cursor and other request fields are passed through verbatim — the helper does not mutate req — so the caller's cursor state is preserved across reconnects.
On context cancellation the context error is returned, not the underlying transport error, so callers can distinguish "caller gave up" from "endpoint is flapping". A nil logger is treated as btclog.Disabled.
Status-level failures (resp.Status non-nil with Ok=false) are returned to the caller in resp; this helper retries only on transport errors. The caller decides how to handle a status error — usually that means surfacing it to the caller of the outer Wait loop, since it indicates a deterministic protocol-level problem rather than a transient network blip.
func RetryDelay ¶
func RetryDelay(cfg BackoffConfig, attempt int) time.Duration
RetryDelay returns an exponential backoff duration with jitter, capped at cfg.MaxDelay. The formula is
min(base * 2^(attempt-1), max) * U[0.5, 1.0).
The jitter uses non-cryptographic randomness because backoff timing is not security sensitive.
func Sleep ¶
func Sleep(ctx context.Context, cfg BackoffConfig, attempt *int)
Sleep increments *attempt and sleeps for the next backoff interval, respecting context cancellation. The attempt counter is owned by the caller so multiple pull cycles can share a single backoff schedule (i.e. successive failures grow the delay, while a success resets it).
Types ¶
type BackoffConfig ¶
type BackoffConfig struct {
// BaseDelay is the initial backoff increment. A non-positive value
// selects the default (200 ms).
BaseDelay time.Duration
// MaxDelay caps the exponential backoff delay. A non-positive value
// selects the default (30 s).
MaxDelay time.Duration
}
BackoffConfig controls exponential backoff with jitter for retryable pull failures. The zero value selects the package defaults (200 ms base, 30 s cap) so callers that do not care about backoff tuning can pass BackoffConfig{} without producing a tight retry loop.
func DefaultBackoffConfig ¶
func DefaultBackoffConfig() BackoffConfig
DefaultBackoffConfig returns the production defaults used by the serverconn ingress loop: 200 ms base, 30 s cap.
Source Files