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 typedResilienceError::Timeout.crdb_retry— CockroachDB serializable retry that retries only on SQLSTATE40001, 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§
- Audit
Ledger - File-backed, HMAC-signed, append-only JSONL audit ledger with per-record signature chaining.
- Audit
Record - A fully materialized, signed ledger record (one JSONL line).
- Audit
Record Input - Caller-supplied fields of an audit record.
inputsandsourcesaccept any JSON value; optional fields default to omitted. - File
Ledger - File/JSONL-backed
IdempotencyLedger. - Retry
Policy - Policy controlling retry attempts and backoff timing.
- SqlError
- Error carrying a SQLSTATE, as classified for CRDB retry purposes.
Enums§
- Audit
Error - Errors from audit-ledger operations.
- Ledger
Error - Errors from ledger operations.
- Resilience
Error - Errors produced by the resilience wrappers themselves.
- Verify
Result - 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§
- Idempotency
Ledger - 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_retrybut with a caller-suppliedRetryPolicy. - 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 runningprev_sigand returns the index of the first broken line. WhenkeyisNone, resolves it the same wayAuditLedger::opendoes. - with_
timeout - Run
futwith a deadline ofdur.