Skip to main content

Crate resilient_call

Crate resilient_call 

Source
Expand description

resilient-call — small, dependency-light resilience primitives for the cubiczan portfolio.

Four building blocks that close the two most common defects found in the architecture audit — external calls with no timeout/retry/backoff, and money/state operations with no idempotency:

  • retry — async generic retry with exponential backoff + full jitter and a caller-supplied classifier (retryable vs terminal).
  • with_timeout — tokio timeout wrapper returning a typed ResilienceError::Timeout.
  • crdb_retry — CockroachDB serializable retry that retries only on SQLSTATE 40001, with capped backoff + jitter.
  • IdempotencyLedger + FileLedger — a JSONL-backed guard so retrying callers never double-execute a money/state operation.
  • AuditLedger — a signed, append-only JSONL audit ledger. Each record is HMAC-SHA256 signed over its canonical JSON plus the previous record’s signature, chaining lines together so the ledger is tamper-evident.

These were lifted and generalized from proven patterns in cross-harness-scaffolder (CRDB retry), swarmfi-executor / cleanmandate (idempotency ledger), and the HMAC audit ledgers in cleanmandate, swarmfi-executor, glacier-edge-arm, and compliance-as-code-agent.

Structs§

AuditLedger
File-backed, HMAC-signed, append-only JSONL audit ledger with per-record signature chaining.
AuditRecord
A fully materialized, signed ledger record (one JSONL line).
AuditRecordInput
Caller-supplied fields of an audit record. inputs and sources accept any JSON value; optional fields default to omitted.
FileLedger
File/JSONL-backed IdempotencyLedger.
RetryPolicy
Policy controlling retry attempts and backoff timing.
SqlError
Error carrying a SQLSTATE, as classified for CRDB retry purposes.

Enums§

AuditError
Errors from audit-ledger operations.
LedgerError
Errors from ledger operations.
ResilienceError
Errors produced by the resilience wrappers themselves.
VerifyResult
Outcome of AuditLedger::verify / verify_ledger.

Constants§

AUDIT_LEDGER_KEY_ENV
The environment variable read for the signing key.
DEFAULT_AUDIT_LEDGER_KEY
The default signing key. Documented and safe ONLY for tests/dev.
SERIALIZATION_FAILURE
SQLSTATE for serialization_failure — the retryable transaction conflict.

Traits§

IdempotencyLedger
Guards money/state operations against duplicate execution.

Functions§

crdb_retry
Retry a CockroachDB transaction body, retrying only on SQLSTATE 40001.
crdb_retry_with_policy
Like crdb_retry but with a caller-supplied RetryPolicy.
default_crdb_policy
Default policy for CRDB retries: more attempts than the generic default, with a sensible cap so backoff never runs away under sustained contention.
retry
Retry an async operation according to policy.
verify_ledger
Verify a ledger file without constructing an AuditLedger. Re-derives each signature from the stored content plus the running prev_sig and returns the index of the first broken line. When key is None, resolves it the same way AuditLedger::open does.
with_timeout
Run fut with a deadline of dur.