resilient_call/lib.rs
1//! `resilient-call` — small, dependency-light resilience primitives for the
2//! cubiczan portfolio.
3//!
4//! Four building blocks that close the two most common defects found in the
5//! architecture audit — external calls with no timeout/retry/backoff, and
6//! money/state operations with no idempotency:
7//!
8//! - [`retry`] — async generic retry with exponential backoff + **full jitter**
9//! and a caller-supplied classifier (retryable vs terminal).
10//! - [`with_timeout`] — tokio timeout wrapper returning a typed
11//! [`ResilienceError::Timeout`].
12//! - [`crdb_retry`] — CockroachDB serializable retry that retries **only** on
13//! SQLSTATE `40001`, with capped backoff + jitter.
14//! - [`IdempotencyLedger`] + [`FileLedger`] — a JSONL-backed guard so retrying
15//! callers never double-execute a money/state operation.
16//! - [`AuditLedger`] — a signed, append-only JSONL audit ledger. Each record is
17//! HMAC-SHA256 signed over its canonical JSON **plus the previous record's
18//! signature**, chaining lines together so the ledger is tamper-evident.
19//!
20//! These were lifted and generalized from proven patterns in
21//! `cross-harness-scaffolder` (CRDB retry), `swarmfi-executor` / `cleanmandate`
22//! (idempotency ledger), and the HMAC audit ledgers in `cleanmandate`,
23//! `swarmfi-executor`, `glacier-edge-arm`, and `compliance-as-code-agent`.
24
25mod audit;
26mod crdb;
27mod error;
28mod ledger;
29mod retry;
30mod timeout;
31
32pub use audit::{
33 verify_ledger, AuditError, AuditLedger, AuditRecord, AuditRecordInput, VerifyResult,
34 AUDIT_LEDGER_KEY_ENV, DEFAULT_AUDIT_LEDGER_KEY,
35};
36pub use crdb::{
37 crdb_retry, crdb_retry_with_policy, default_crdb_policy, SqlError, SERIALIZATION_FAILURE,
38};
39pub use error::ResilienceError;
40pub use ledger::{FileLedger, IdempotencyLedger, LedgerError};
41pub use retry::{retry, RetryPolicy};
42pub use timeout::with_timeout;