consensus

type AlarmID uint64

type AuthenticatedPeerValue struct {
	// ID is the admitted member, 0 for a joiner.
	ID NodeID
	// Incarnation is that member's incarnation.
	Incarnation Incarnation
	// Slot is the slot the certificate's URI SAN names.
	Slot string
	// SPKI is the SHA-256 of the certificate's SubjectPublicKeyInfo.
	SPKI [32]byte
}

type BatchingStateMachine interface {
	StateMachine
	// ApplyBatch applies es in order and writes each result into results.
	ApplyBatch(es []EntryValue, results []any)
}

type ClusterID [16]byte

type DurableStateMachine interface {
	StateMachine
	// AppliedPosition returns the log identity and the position of the last
	// entry whose effects are durable.
	AppliedPosition() (LogIdentityValue, PositionValue, error)
}

type EntryKind uint8

type EntryValue struct {
	// Position is the entry's term and index.
	Position PositionValue
	// Kind says what Data carries.
	Kind EntryKind
	// Version is the payload version the proposer set; it selects the frozen
	// code path that applies the entry.
	Version uint32
	// BodySum is the CRC-32C of Data, computed by the proposer.
	BodySum uint32
	// ChainSum chains the previous entry's header: computed by the LEADER at
	// its serialized append point, verified at append and before Apply.
	ChainSum uint32
	// Data is the payload: a command for EntryCommand, the engine's encoding
	// for the other kinds.
	Data []byte
	// Token is the entry's lineage-scoped command identity, set in memory by
	// the engine before Apply and never encoded in the log.
	Token TokenValue
}

type FencedAttestationValue struct {
	// Voter is the old voter.
	Voter NodeID
	// Method is how it was fenced: "stopped", "powered-off" or "cut".
	Method string
	// Receipts are Ed25519 signatures, one per witness key, over the old
	// cluster id, the new cluster id and the voter.
	Receipts [][]byte
}

type FrameLane uint8

type GroupID uint64

type HardState struct {
	// Term is the node's current term.
	Term uint64
	// Vote is the candidate voted for in Term, 0 for none.
	Vote NodeID
	// Commit is the highest index known committed.
	Commit uint64
}

type Incarnation [16]byte

type InstallAcceptValue struct {
	// SnapshotID is the snapshot answered.
	SnapshotID string
	// Offset is the chunk-aligned ENCODED offset to resume from, 0 for a
	// fresh spool.
	Offset int64
	// Refused is zero, or why the offer is refused.
	Refused errs.Code
	// Held reports that the receiver already holds the snapshot: an
	// idempotent success.
	Held bool
}

type InstallOfferValue struct {
	// Term is the sender's term.
	Term uint64
	// SnapshotID equals Meta.ID.
	SnapshotID string
	// Meta describes the snapshot.
	Meta SnapshotMetaValue
}

type InstallParams struct {
	// Ctx ends with the connection.
	Ctx context.Context
	// From is the peer TLS authenticated.
	From AuthenticatedPeerValue
	// Offer is the accepted offer.
	Offer InstallOfferValue
	// Offset is the accepted offset.
	Offset int64
	// Body is the encoded stream from Offset, ending with the connection.
	Body io.Reader
}

type JoinAuthorizer interface {
	// Authorize accepts or refuses the request.
	Authorize(ctx context.Context, r JoinRequestValue) (Operator, error)
}

type JoinConfig struct {
	// Addresses are the members to try, in order.
	Addresses []string
	// Stamp is the joiner's stamp, from Init.
	Stamp StampValue
	// Address is where the joiner listens.
	Address string
	// Pins are the SPKIs of the members the joiner trusts, from the
	// operator. An answer counts only from a peer presenting one of them,
	// and only when the membership it returns lists that peer under that
	// key; an empty list refuses the JOIN.
	Pins [][32]byte
	// MaxSnapshotBytes is the joiner's own MaxSnapshotBytes, announced in
	// the JOIN so the members hold their cuts to it (R2-30); 0 announces
	// nothing, and the JOIN is the one a member that predates the
	// announcement reads.
	MaxSnapshotBytes int64
}

type JoinReasonBinder interface {
	// BindJoinReason registers the group's JOIN callback that also returns
	// the refusal's reason, empty for none.
	BindJoinReason(group GroupID, join func(ctx context.Context, from AuthenticatedPeerValue, r JoinRequestValue) (PositionValue, errs.Code, string))
}

type JoinRequestValue struct {
	// Cluster is the cluster the joiner claims.
	Cluster ClusterID
	// ID is the joiner's new NodeID.
	ID NodeID
	// Incarnation is the joiner's incarnation.
	Incarnation Incarnation
	// Slot is the slot its certificate names.
	Slot string
	// SPKI is its key, from the handshake.
	SPKI [32]byte
	// Address is where it listens.
	Address string
	// MaxSnapshotBytes is the largest snapshot the joiner accepts, as it
	// announced it; 0 when it announced none, as a joiner that predates
	// the announcement does.
	MaxSnapshotBytes int64
}

type Joiner interface {
	// Join sends the JOIN and returns the position its AddLearner was
	// appended at.
	Join(ctx context.Context, cfg JoinConfig) (PositionValue, error)
}

type LeadershipWatcher interface {
	// Watch returns its OWN channel, of capacity one, holding the latest
	// status; it is unsubscribed and closed when ctx ends or the node closes.
	Watch(ctx context.Context) <-chan StatusValue
}

type LogIdentityValue struct {
	// Cluster is the cluster the log belongs to.
	Cluster ClusterID
	// Epoch counts the histories of this cluster id: 1 at founding.
	Epoch uint64
	// Predecessor is the cluster of the history this one was recovered from,
	// zero for a founding.
	Predecessor ClusterID
	// PredecessorEpoch is the predecessor's epoch.
	PredecessorEpoch uint64
	// KeptIndex is the last index Recover kept from the predecessor. An
	// applied position of the predecessor at or below it is still trusted
	// when its term is the one kept there: Recover adopts the verified
	// suffix past the commit the survivor persisted, which may hold
	// another term than the write the old cluster acknowledged.
	// Every node of the history applies the entries at or below it under the
	// predecessor's token: one admitted after the Recover learns it from the
	// snapshot it installs, never from an append.
	KeptIndex uint64
	// AdoptedFrom is the last index of the kept range the predecessor had
	// committed when Recover read it: the commit the survivor persisted,
	// or the snapshot a restore started from. An entry at or below it is
	// the one every node of the predecessor holds (Log Matching), so a
	// predecessor's token at or below it is trusted by its index once its
	// term can no longer be read; the adopted range above it, up to
	// KeptIndex, is not. 0 records nothing, and nothing is trusted that
	// way. It is recorded only in a cluster at protocol version 2, in the
	// stamp of the node Recover or RestoreSnapshot ran on: a snapshot does
	// not carry it, so a node that learns the lineage from one trusts
	// nothing that way (#509).
	AdoptedFrom uint64
}

type LogReader interface {
	// Entries returns entries in [lo, hi), at most maxBytes, and always at
	// least one entry when lo < hi, even above maxBytes. lo below first is
	// COMPACTED.
	Entries(lo, hi uint64, maxBytes int, dst []EntryValue) ([]EntryValue, error)
	// Term answers for first-1 too, from the term kept at compaction.
	Term(index uint64) (uint64, error)
	// Bounds of an empty log after a snapshot at s are (s+1, s).
	Bounds() (first, last uint64)
}

type LogStore interface {
	LogReader
	// Append buffers entries and, when hs is not nil, a hard state, in ONE
	// record batch.
	Append(entries []EntryValue, hs *HardState) error
	// Sync makes everything appended so far durable.
	Sync() error
	// TruncateSuffix writes ONE durable truncate record removing every entry
	// from index from on, and nothing else.
	TruncateSuffix(from uint64) error
	// CompactPrefix drops what a snapshot covers, through index through.
	CompactPrefix(through uint64) error
	// HardState returns the last hard state appended.
	HardState() (HardState, error)
	// Stamp returns the directory's stamp.
	Stamp() (StampValue, error)
	// WriteStamp writes the stamp, durable on return.
	WriteStamp(StampValue) error
	// Close releases the store.
	Close() error
}

type MemberValue struct {
	// ID is the node.
	ID NodeID
	// Incarnation is the node's data-directory incarnation.
	Incarnation Incarnation
	// Slot is the placement slot its certificate names.
	Slot string
	// SPKI is the SHA-256 of its certificate's SubjectPublicKeyInfo. A zero
	// pin admits nobody: it is what DenyPin leaves.
	SPKI [32]byte
	// Address is where its transport listens.
	Address string
	// Voter is true for a voter, false for a learner.
	Voter bool
	// Joining marks an empty learner admitted before it holds any log.
	Joining bool
	// PayloadMax is the highest payload version its state machine supports; 0
	// means only the lowest.
	PayloadMax uint32
	// MaxSnapshotBytes is the largest snapshot it accepts, 0 when unknown.
	MaxSnapshotBytes int64
}

type MembershipValue struct {
	// Index is the index of the entry that produced it, 0 at founding.
	Index uint64
	// Members lists every voter and learner.
	Members []MemberValue
	// Retired lists every removed NodeID.
	Retired []NodeID
	// RetiredKeys lists the SPKI pin of every member removed, and every pin
	// DenyPin withdrew, since the cluster version is 3: a key held once is
	// never admitted again under another id. Empty below version 3.
	RetiredKeys [][32]byte
}

type MessageFlags uint8

type MessageKind uint8

type MessageValue struct {
	// Version is the frame layout version, 1.
	Version uint8
	// Group is the consensus group, 1 in v1.
	Group GroupID
	// Kind says what the message is.
	Kind MessageKind
	// Flags qualify it.
	Flags MessageFlags
	// From is the sender, as the sender wrote it.
	From NodeID
	// To is the receiver.
	To NodeID
	// Term is the sender's term.
	Term uint64
	// LogTerm is the term of the entry at Index: the previous entry of an
	// append, the last entry of a vote request.
	LogTerm uint64
	// Index is the previous index of an append, the last index of a vote
	// request, the verified prefix of an acknowledgement, a read index.
	Index uint64
	// Commit is the commit index the sender lets the receiver advance to.
	Commit uint64
	// Reject marks a refusal.
	Reject bool
	// RejectHint is the receiver's last index, a hint where to probe from.
	RejectHint uint64
	// Context correlates a reply with its request: a heartbeat round, a read
	// request, a submission sequence.
	Context uint64
	// TransferIssuer is the leader that issued a transfer flag.
	TransferIssuer NodeID
	// TransferTerm is the term the transfer flag was issued in.
	TransferTerm uint64
	// Contract is the committed contract generation the sender has applied.
	Contract uint64
	// Code is a refusal's error code, 0 for none.
	Code errs.Code
	// Entries are the entries an append carries, or the proposal a forward
	// carries with a zero position.
	Entries []EntryValue
}

type NodeID uint64

type Operator string

type PositionValue struct {
	// Term is the leader term the entry was appended in.
	Term uint64
	// Index is the entry's place in the log, from 1.
	Index uint64
}

type PreconditionSpec struct {
	// Log is the identity the precondition was read in.
	Log LogIdentityValue
	// Alarm is the alarm a clearing operation names.
	Alarm AlarmID
	// Generation is the contract or cluster-version generation an operation
	// expects to replace.
	Generation uint64
}

type Replicated interface {
	// Propose replicates data and returns, once the entry is applied
	// locally, its lineage-scoped token and the value Apply returned.
	// NOT_LEADER means certainly not appended; OUTCOME_UNKNOWN means it may
	// still commit, and the caller must read the state before deciding.
	Propose(ctx context.Context, data []byte) (TokenValue, any, error)
	// Barrier returns once the local state machine reflects every write
	// committed before the call, with the token of the applied index.
	Barrier(ctx context.Context) (TokenValue, error)
	// WaitApplied returns once the local node has applied t, the entry of
	// t's term at t's index. A token of another lineage is
	// LINEAGE_MISMATCH. A token whose index holds an entry of another term
	// is ENTRY_SUPERSEDED, or LINEAGE_MISMATCH when it is one of the
	// predecessor's within the index Recover kept, as is a token of the
	// predecessor's whose term the node can no longer read there.
	WaitApplied(ctx context.Context, t TokenValue) error
	// Status returns the node's view after its last turn.
	Status() StatusValue
}

type Role uint8

type Snapshot interface {
	// WriteTo writes the view's state.
	WriteTo(w io.Writer) (int64, error)
	// Release frees the view.
	Release()
}

type SnapshotHandle interface {
	io.ReaderAt
	// Meta describes the snapshot.
	Meta() SnapshotMetaValue
	// Close unpins it.
	Close() error
}

type SnapshotMetaValue struct {
	// ID names the snapshot, the same in a spool, an offer and a handle.
	ID string
	// Version is the snapshot format version, 1.
	Version uint8
	// Position is the last entry the snapshot covers.
	Position PositionValue
	// Log is the identity of the log the snapshot was cut from.
	Log LogIdentityValue
	// Membership is the configuration valid at Position, never a later one.
	Membership MembershipValue
	// ChainTip is the authenticated chain value at Position: the chain is
	// carried across the boundary, never reseeded.
	ChainTip uint32
	// Codec names the compression of the chunks: "flate" or "gzip".
	Codec string
	// EncodedSize is the size of the encoded stream, chunk headers included.
	EncodedSize int64
	// DecodedSize is the size of the decoded stream.
	DecodedSize int64
	// ChunkSize is the largest decoded chunk.
	ChunkSize int64
	// SHA256 is the digest of the DECODED stream, computed by the engine.
	SHA256 [32]byte
	// Timing is the committed timing contract at Position.
	Timing TimingContractSpec
	// ClusterVersion is the committed cluster version at Position.
	ClusterVersion uint32
	// ClusterGeneration counts its raises.
	ClusterGeneration uint64
	// NoSpace is the no-space alarm raised at Position, 0 for none.
	NoSpace AlarmID
	// Reserved is carried uninterpreted for ADR 0173.
	Reserved []byte
}

type SnapshotSink interface {
	io.Writer
	// Commit publishes the snapshot; final carries the SHA-256 the engine
	// computed over the DECODED stream.
	Commit(final SnapshotMetaValue) error
	// Abort drops the spool.
	Abort() error
}

type SnapshotStore interface {
	// Create opens the spool of id. When a spool of that id exists, it is
	// returned with the ENCODED offset durably spooled so far.
	Create(id string, meta SnapshotMetaValue) (sink SnapshotSink, spooled int64, err error)
	// List returns the complete snapshots, newest first.
	List() ([]SnapshotMetaValue, error)
	// Open pins a snapshot until the handle is closed.
	Open(id string) (SnapshotHandle, error)
	// Remove deletes a snapshot; refused while a handle is open.
	Remove(id string) error
}

type StampState uint8

type StampValue struct {
	// Log is the log identity the directory belongs to.
	Log LogIdentityValue
	// ID is the node.
	ID NodeID
	// Incarnation is drawn when the stamp is first written.
	Incarnation Incarnation
	// Slot is the placement slot the node's certificate names.
	Slot string
	// State is how far the directory has come.
	State StampState
	// Founding is the digest of the founding member list while a bootstrap
	// is pending, so that a rerun with another list is refused.
	Founding [32]byte
}

type StateMachine interface {
	// Apply applies one committed command and returns its result, delivered
	// to the Propose that created it on the node that created it.
	Apply(e EntryValue) any
	// Snapshot captures a point-in-time view of the state, cheaply: it is
	// called on the apply goroutine.
	Snapshot() (Snapshot, error)
	// Restore replaces the state with a snapshot's. It is serialised with
	// Apply. An error coded VERSION_UNSUPPORTED says the snapshot is of a
	// format this build does not read: the node stops, as for an entry
	// kind it does not know, and a restart over that snapshot is refused
	// (D18). Any other error refuses that one install, and the leader
	// offers a snapshot again.
	Restore(r io.Reader, meta SnapshotMetaValue) error
}

type StatusValue struct {
	// ID is this node.
	ID NodeID
	// Role is its role.
	Role Role
	// Term is its current term.
	Term uint64
	// Leader is the leader it knows of in Term, 0 for none.
	Leader NodeID
	// Commit is the highest index it knows committed.
	Commit uint64
	// Applied is the highest index its state machine applied.
	Applied uint64
	// Log is the identity of its log.
	Log LogIdentityValue
	// Versions are its capabilities and the committed cluster version.
	Versions VersionsValue
	// Timing is the committed timing contract.
	Timing TimingContractSpec
	// NoSpace is the raised no-space alarm, 0 when none.
	NoSpace AlarmID
}

type StopReasonValue struct {
	// Err is the stop's error, built on its sentinel.
	Err error
	// Unmarked is set when a STORAGE_FAILED stop could write its marker
	// nowhere: the exit code is then 73.
	Unmarked bool
}

type TimingContractSpec struct {
	// Generation counts the committed contracts, 1 at founding.
	Generation uint64
	// HeartbeatInterval is how often the leader confirms itself.
	HeartbeatInterval time.Duration
	// ElectionTimeoutMin is the lower bound of the randomized election
	// timeout, and the vote-refusal window.
	ElectionTimeoutMin time.Duration
	// ElectionTimeoutMax is its upper bound, exclusive.
	ElectionTimeoutMax time.Duration
	// MaxClockDrift is the largest rate difference between two clocks, as a
	// fraction in (0, 1). Zero refuses lease reads.
	MaxClockDrift float64
}

type TokenValue struct {
	// Cluster is the cluster of the log that committed the entry.
	Cluster ClusterID
	// Epoch is that log's epoch.
	Epoch uint64
	// Term is the entry's term.
	Term uint64
	// Index is the entry's index.
	Index uint64
}

type Transport interface {
	// Send hands over an encoded frame. It never blocks and may drop; the
	// transport owns frame after the call.
	Send(to NodeID, frame []byte)
	// Stream sends a snapshot from the offset the receiver accepted; open
	// returns a reader at an encoded offset on a chunk boundary, which
	// Stream closes.
	Stream(ctx context.Context, to NodeID, offer InstallOfferValue, open func(offset int64) (io.ReadCloser, error)) error
	// Bind registers the group's callbacks. deliver gets the frame and the
	// peer TLS authenticated, valid until deliver returns; offer is judged
	// on the event loop and its spool then positioned off it, and the
	// shipped transport reads its answer under JoinTimeout; join is
	// answered off the loop, under a deadline.
	Bind(group GroupID, deliver func(from AuthenticatedPeerValue, frame []byte), offer func(from AuthenticatedPeerValue, o InstallOfferValue) InstallAcceptValue, install func(InstallParams) error, join func(ctx context.Context, from AuthenticatedPeerValue, r JoinRequestValue) (PositionValue, errs.Code)) error
	// SetMembership pushes the group's admitted members; the transport
	// computes the union over its groups.
	SetMembership(group GroupID, admitted []MemberValue)
}

type UnreachableReporter interface {
	// Unreachable registers the callback.
	Unreachable(func(NodeID))
}

type VersionsValue struct {
	// ProtocolMin is the lowest protocol version it speaks.
	ProtocolMin uint32
	// ProtocolMax is the highest.
	ProtocolMax uint32
	// PayloadMax is the highest payload version it applies.
	PayloadMax uint32
	// Cluster is the committed cluster version.
	Cluster uint32
	// ClusterGeneration counts cluster-version raises.
	ClusterGeneration uint64
}