Crate crafty_client

Expand description

crafty-client — client handles for talking to a crafty cluster (client-api).

Two layers over a shared crafty_proto wire contract (client-api):

In-process (L1): embed a node and use its crafty_actor::NodeHandle directly (propose/query) — no serialization, no network.
Remote (L2): RemoteClient speaks postcard over any crafty_net transport (live QUIC/HTTP/3 with client mTLS, or the in-memory LocalNetwork in tests). A follower transparently forwards to the leader server-side (client-routing), so a client can connect to any node; the built-in RetryPolicy adds failover + leader-follow for elections and downed nodes.

TypedClient wraps either layer with a StateMachine’s command/query/response types.

Re-exports§

InMemorySagaJournal: In-memory journal for unit tests.
InMemoryTwoPhaseJournal: In-memory 2PC journal (tests and single-process coordinators).
KeyedBatchStep: One keyed write in a propose_keyed_batch.
RemoteClient: A remote client that talks to a crafty cluster over any Transport (live QUIC/HTTP/3 in production, the in-memory LocalNetwork in tests).
ResumeSagaOpts: Hooks for resume_saga (journal required).
ResumeTwoPhaseOpts: Hooks for resume_cross_shard_2pc.
RetryPolicy: How a RemoteClient retries across nodes and elections (backlog F4).
RunSagaOpts: Optional hooks for run_saga.
RunTwoPhaseOpts: Hooks for propose_cross_shard_2pc.
SagaJournalRecord: Durable saga progress (journal value).
SagaPlan: Ordered cross-shard write plan executed by run_saga.
SagaStep: One forward step with a compensating keyed write on the same shard.
TwoPhaseJournalRecord: Client-side durable progress for cross-shard 2PC resume.
TypedClient: A strongly-typed view over any Client, carrying a StateMachine’s command/query/response types so callers work with real Rust values instead of postcard byte vectors.

BatchError: Why a multi-shard batch stopped early.
ClientError: Why a client request could not be completed.
SagaError: Why a saga could not finish cleanly.
SagaEvent: Lifecycle events for metrics / logging (see cross-shard-transactions ADR).
SagaJournalError: Journal persistence failure.
SagaJournalPhase: Journal phase for resume / observability.
SagaOutcome: Outcome of a saga run.
TwoPhaseError: Why a cross-shard 2PC attempt failed.
TwoPhaseEvent: Lifecycle events for metrics / logging (see cross-shard-transactions ADR).
TwoPhaseJournalError: Journal persistence failure.

Client: A cluster client: submit an application-encoded write (propose) or linearizable read (query) and get the application-encoded response back.
KeyedClient: Extension of Client for shard-aware multi-Raft routing (write-sharding-multi-raft).
SagaJournal: Object-safe saga journal (Redis, group-0 side channel, in-memory tests).
TwoPhaseClient: Extension of KeyedClient for limited cross-shard 2PC.
TwoPhaseJournal: Optional journal hook for propose_cross_shard_2pc / resume_cross_shard_2pc.

decode_journal_record: Decode a SagaJournalRecord.
decode_two_phase_journal_record: Postcard-decode a TwoPhaseJournalRecord.
encode_journal_record: Encode a SagaJournalRecord for external stores.
encode_two_phase_journal_record: Postcard-encode a TwoPhaseJournalRecord for Meta-Raft / Redis storage.
propose_cross_shard_2pc: Execute prepare-all then commit-all, aborting prepared steps on prepare failure.
propose_cross_shard_2pc_with_opts: Like propose_cross_shard_2pc with an optional client journal.
propose_keyed_batch: Propose each step to its owning Raft group in order. Not atomic across groups — if a later step fails, earlier writes remain committed (saga-style callers must compensate explicitly).
resume_cross_shard_2pc: Continue a cross-shard 2PC after partial progress or coordinator restart.
resume_saga: Continue a saga from its durable journal record.
run_saga: Execute plan forward; on failure run compensators in reverse for committed steps.