aarondb/raft_runtime

raft_runtime — deterministic durable Raft protocol model

A transport-free reference runtime. Adapters persist HardState and deliver authenticated RPCs; this module makes protocol decisions and never claims network durability on its own.

Types

HardState

pub type HardState {
  HardState(
    term: Int,
    voted_for: option.Option(String),
    commit_index: Int,
  )
}

Constructors

HardState(
  term: Int,
  voted_for: option.Option(String),
  commit_index: Int,
)

LogEntry

pub type LogEntry {
  LogEntry(term: Int, command: String)
}

Constructors

```
LogEntry(term: Int, command: String)
```

LogIndex

pub type LogIndex =
  Int

Member

pub type Member {
  Voter(id: String)
  Learner(id: String)
}

Constructors

```
Voter(id: String)
```
```
Learner(id: String)
```

NodeId

pub type NodeId =
  String

Persisted

The durable recovery boundary. Persist this value atomically before exposing the corresponding reply or applying any command.

pub type Persisted {
  Persisted(
    hard: HardState,
    log: List(LogEntry),
    snapshot: option.Option(Snapshot),
    last_applied: Int,
  )
}

Constructors

Persisted(
  hard: HardState,
  log: List(LogEntry),
  snapshot: option.Option(Snapshot),
  last_applied: Int,
)

Reply

pub type Reply {
  VoteGranted(term: Int, granted: Bool)
  AppendAccepted(term: Int, matched: Int)
  AppendRejected(term: Int, next_index: Int)
  SnapshotAccepted(term: Int, index: Int)
  ReadIndexAccepted(term: Int, index: Int)
  StaleTerm(term: Int)
}

Constructors

```
VoteGranted(term: Int, granted: Bool)
```
```
AppendAccepted(term: Int, matched: Int)
```

AppendRejected(term: Int, next_index: Int)

```
SnapshotAccepted(term: Int, index: Int)
```

ReadIndexAccepted(term: Int, index: Int)

```
StaleTerm(term: Int)
```

Role

pub type Role {
  Follower
  Candidate
  Leader
}

Constructors

```
Follower
```
```
Candidate
```
```
Leader
```

Rpc

pub type Rpc {
  RequestVote(
    term: Int,
    candidate: String,
    last_index: Int,
    last_term: Int,
  )
  AppendEntries(
    term: Int,
    leader: String,
    prev_index: Int,
    prev_term: Int,
    entries: List(LogEntry),
    leader_commit: Int,
  )
  InstallSnapshot(term: Int, leader: String, snapshot: Snapshot)
  ReadIndex(term: Int, leader: String, committed: Int)
}

Constructors

RequestVote(
  term: Int,
  candidate: String,
  last_index: Int,
  last_term: Int,
)

AppendEntries(
  term: Int,
  leader: String,
  prev_index: Int,
  prev_term: Int,
  entries: List(LogEntry),
  leader_commit: Int,
)

InstallSnapshot(term: Int, leader: String, snapshot: Snapshot)

ReadIndex(term: Int, leader: String, committed: Int)

Snapshot

pub type Snapshot {
  Snapshot(index: Int, term: Int, state: String)
}

Constructors

Snapshot(index: Int, term: Int, state: String)

State

pub type State {
  State(
    node: String,
    role: Role,
    hard: HardState,
    members: List(Member),
    log: List(LogEntry),
    last_applied: Int,
    leader: option.Option(String),
    snapshot: option.Option(Snapshot),
  )
}

Constructors

State(
  node: String,
  role: Role,
  hard: HardState,
  members: List(Member),
  log: List(LogEntry),
  last_applied: Int,
  leader: option.Option(String),
  snapshot: option.Option(Snapshot),
)

Values

add_learner

pub fn add_learner(state: State, id: String) -> State

apply_committed

pub fn apply_committed(state: State) -> Result(State, String)

bootstrap_leader

pub fn bootstrap_leader(state: State) -> State

The only automatic bootstrap: a one-voter cluster. Multi-node bootstrap needs externally authenticated member configuration.

commit_quorum

pub fn commit_quorum(
  state: State,
  index: Int,
  replicated: Int,
) -> State

A leader may commit an index only after caller evidence proves current-term quorum replication.

compact

pub fn compact(
  state: State,
  index: Int,
  state_image: String,
) -> Result(State, String)

handle

pub fn handle(state: State, rpc: Rpc) -> #(State, Reply)

last_index

pub fn last_index(state: State) -> Int

last_term

pub fn last_term(state: State) -> Int

new

pub fn new(node: String, members: List(Member)) -> State

persist

pub fn persist(state: State) -> Persisted

promote_voter

pub fn promote_voter(state: State, id: String) -> State

Promotion is deliberately explicit so an adapter can make it a committed joint-consensus configuration entry rather than a local mutation.

quorum

pub fn quorum(state: State) -> Int

recover

pub fn recover(
  node: String,
  members: List(Member),
  saved: Persisted,
) -> State

Restores only durable state. Leadership never survives recovery; the node must establish a current-term quorum again.

start_election

pub fn start_election(state: State) -> State

Begins an election only for voting members. Persist the returned hard state before dispatching vote RPCs.

win_election

pub fn win_election(state: State, granted_votes: Int) -> State

Turns a candidate into leader only from explicit, same-term quorum evidence.