Crate crafty_core

Expand description

crafty-core — the pure Raft consensus state machine (no I/O).

RaftNode drives leader election and log replication deterministically: it consumes events and returns Output effects for an outer runtime to execute (architecture-style). Because it performs no I/O and derives all randomness from a seed, an entire cluster can be simulated reproducibly (testing-strategy).

Joint-consensus membership (membership-early), ReadIndex (read-consistency), and snapshots build on this foundation in later increments.

Re-exports§

pub use crafty_proto as proto;

Structs§

AckWindowLiveness: Per-peer latched reachability with ack-window + hysteresis.
CatalogExpansionPlan: Plan for appending contiguous Raft groups to the catalog (Tier 2).
Committed: A committed application command ready to apply to the state machine.
CompactionPolicy: When the runtime should automatically compact the Raft log.
CompactionStats: Observed log retention relative to the last snapshot.
Config: Timing and determinism configuration, in logical ticks.
GroupMembershipChange: Per-group membership delta between a committed and desired voter set.
GroupRebalancePlan: Local rebalance actions for one physical node (multi-Raft control plane).
GroupReplicationTarget: Desired voters + learners for one group.
NotLeader: Returned by RaftNode::propose / RaftNode::read_index when the node is not the leader.
Persist: A batch of durable state changes an outer runtime must fsync before acting on any network effect drained from the same step (Raft §5.1–§5.3): a follower persists appended entries before ack’ing them, and a node persists its term/vote before replying to a vote. Produced by RaftNode::take_persist; it is the delta since the previous call.
PhiAccrualDetector: Phi-accrual failure detector for one peer (Haystack-style, tick time base).
PhiAccrualLiveness: Per-peer phi detectors for all voters.
RaftGroupId: Identifies one of the cluster’s independent Raft groups (multi-Raft).
RaftNode: A single Raft participant: a deterministic, I/O-free state machine.
ReachabilityConfig: Tunable reachability parameters (logical ticks).
ReadId: Client-supplied token identifying a linearizable read request (read-consistency).
ShardCountExpansionPlan: Plan for expanding the active shard keyspace (Tier 1).
ShardId: A partition of the keyspace. Fixed count per cluster; each shard is owned by exactly one Raft group at a time.
ShardRouter: Maps application keys onto a fixed number of shards with a stable hash.
ShardRoutingSwitchPlan: Operator plan for switching keyed routing from modulus to stable virtual.
SnapshotState: A read-only view of this node’s most recent snapshot (Raft §7): its boundary (term, index), the configuration in effect there, and the opaque application bytes. Returned by RaftNode::stored_snapshot so a runtime can persist the snapshot durably and purge the compacted log prefix (backlog A6), and fed back to RaftNode::restore_with_snapshot on restart.
StableShardActivationPlan: Plan for activating more virtual shards without remapping existing keys.
StableShardRouter: Router over a fixed virtual space with a tunable active prefix (Tier 2).
TwoPhasePlan: Client-coordinated cross-shard 2PC plan.
TwoPhaseStep: One keyed prepare step in a cross-shard 2PC plan.

Enums§

CatalogError: Invalid multi-Raft group catalog.
CatalogProposeError: Why a catalog metadata change could not be started.
FailureDetectorKind: Which algorithm derives per-peer reachability on the leader.
MembershipError: Why a membership change could not be started.
Output: An effect produced by the core for the runtime to execute.
Role: The role a node currently plays in its term.
ShardExpansionError: Why a shard-count expansion request was rejected.
ShardRoutingKind: How keyed traffic maps into the virtual shard space (Tier 1 vs Tier 2).
ShardRoutingSwitchError: Why a Tier 1 → Tier 2 routing switch was rejected.
StableShardActivationError: Why stable shard activation was rejected.
TwoPhasePlanError: Why a TwoPhasePlan fails validation.

Constants§

DEFAULT_COMPACT_BYTES: Default retained applied log bytes before auto-compaction (~4 MiB).
DEFAULT_COMPACT_ENTRIES: Default retained applied entries before auto-compaction (Tier 1 ops).
DEFAULT_GROUP_LEARNER_FACTOR: Default non-voting learner replicas per group beyond voters (Tier 1). 0 disables.
DEFAULT_GROUP_REPLICATION_FACTOR: Default replication factor for per-group voter sets (per-group-raft-membership).
MAX_VIRTUAL_SHARDS: Upper bound for ShardRouter active shard counts (Tier 1 expansion).
META_RAFT_GROUP_ID: Reserved Raft group id for the cluster coordinator (Meta-Raft).
TWO_PHASE_DEFAULT_PREPARE_TIMEOUT_MS: Default prepare staging timeout (5 minutes) for durable 2PC garbage collection.
TWO_PHASE_MAX_GROUPS: Maximum distinct Raft groups in one 2PC transaction.
TWO_PHASE_MAX_PAYLOAD: Maximum encoded command payload per step.
TWO_PHASE_MAX_STEPS: Maximum steps in one 2PC transaction.

Traits§

Command: A replicated command applied to the StateMachine.
Query: A read-only query served by the StateMachine.
StateMachine: The user-defined, deterministic application state machine (state-machine).

Functions§

compaction_stats: Collect compaction stats from a live node view.
effective_replication_factor: Clamp replication_factor to [1, live_count]. Returns 0 when live_count == 0.
entry_estimated_bytes: Rough on-disk size of one log entry for byte-threshold policy.
group_host_assignment: Full assignment of each Raft group to a host node over nodes.
group_learners: Desired learner set for one Raft group: live nodes ranked after the voter set, up to learner_factor nodes (Tier 1 per-group-raft-membership).
group_membership_assignment: Full desired voter assignment for every group in groups (per-group-raft-membership).
group_voters: Desired voter set for one Raft group: the top effective_replication_factor live nodes by rendezvous weight for group, sorted by NodeId (per-group-raft-membership).
groups_joining_node_affects: Groups whose desired voter set gains node when the live set grows from live_nodes_before to live_nodes_after (cluster join).
groups_leaving_node_affects: Groups whose desired voter set loses node when it departs the live set (cluster leave).
is_meta_raft_group: Whether group is the Meta-Raft coordinator group.
node_should_host_group: Whether node_id should run a local replica for group (voter or learner).
place_shard: The Raft group that owns shard, chosen by rendezvous (highest-random-weight) hashing: the group maximizing mix64(shard, group). Returns None only when groups is empty. Deterministic given the same group set, and stable under group churn — removing the winning group promotes the next-highest weight, leaving all other shards’ owners unchanged.
plan_catalog_expansion: Plan appending add_groups contiguous ids after the current catalog tail.
plan_group_membership_change: Diff current_voters against desired_voters (sorted inputs not required).
plan_group_membership_sync: Groups whose desired voter/learner sets differ from current (per-group-raft-membership). Skips the Meta-Raft coordinator — its membership is managed by /cluster/join and /cluster/leave.
plan_node_group_rebalance: Diff the groups node_id currently hosts against groups where it belongs in the desired voter or learner set (per-group-raft-membership).
plan_shard_count_expansion: Plan a shard-count increase. Shrinking is rejected — pick a larger MAX_VIRTUAL_SHARDS up front or migrate data explicitly.
plan_stable_shard_activation: Plan increasing the active virtual shard prefix (Tier 2 stable expansion).
plan_switch_to_stable_routing: Validate switching from Tier 1 modulus to Tier 2 stable virtual routing.
shard_is_active: Whether shard is routable given active_count active virtual shards.
should_compact: Whether policy says the runtime should run RaftNode::compact now.
stable_router_preserves_routable_keys: After growing the active prefix, keys that were already routable keep the same virtual shard id.
validate_catalog: Validate a multi-Raft user group catalog (contiguous ids 0..=max).
validate_two_phase_plan: Validate a cross-shard 2PC plan before issuing prepare calls.
virtual_shard_for: Map key to a fixed virtual shard in [0, [``MAX_VIRTUAL_SHARDS``]). Unlike ShardRouter::shard_for, this id never changes when the active prefix grows ([tier2-multi-raft-architecture]).