🥮 mooncakes.io

moonleasekit

Deterministic leases, fencing tokens and leader election primitives for MoonBit.

lease
fencing-token
leader-election
distributed-systems
deterministic
moon add dxh8888/moonleasekit@0.1.0
Download zip
Author
Version
0.1.0
License
Apache-2.0
Repository
Last updated
last month
Downloads
12
README

#MoonLeaseKit

Deterministic leases, fencing tokens, and leader-election primitives for MoonBit.

MoonLeaseKit models distributed ownership as pure state transitions. Callers supply logical time explicitly, so the core does not depend on wall clocks, threads, networking, databases, or service discovery.

#Features

  • Acquire, renew, release, transfer, and reap leases
  • Monotonic fencing tokens and revision preconditions
  • Storage-side stale-writer rejection
  • Multi-resource tables, batches, metrics, and audit events
  • Deterministic candidate selection and quorum certificates
  • Duplicate-vote handling and equivocation detection
  • Validation for state restored from external storage
  • Stable JSON and reproducible failover simulation

#Install

moon add dxh8888/moonleasekit

#Example

let acquired = @moonleasekit.LeaseState::new("jobs/leader").apply(
  Acquire("worker-a", 10, None),
  100,
)

guard acquired.lease is Some(lease) else { return }

let write = lease.fenced_write("commit-job-42", 101).unwrap()
let checked = @moonleasekit.FenceGuard::new().check(write)
assert_true(checked.accepted)

When a later lease receives token 2, a delayed write carrying token 1 is rejected by FenceGuard.

#Verify

moon check --target all
moon test --target wasm
moon test --target wasm-gc
moon test --target js
moon run cmd/main --target js
moon run bench/main --target js

The benchmark performs 50,000 deterministic failovers and verifies that every old writer after the first takeover is rejected.

#Scope

This library provides embeddable coordination primitives. It intentionally does not implement transport, storage drivers, failure detection, or a full consensus protocol.

Apache-2.0 licensed.

#
AuditFinding

source
pub(all) struct AuditFinding {
  code : String
  resource : String
  event_index : Int
  message : String
} derive(Eq, 
Debug)

One invariant violation found in an event trace.

#
AuditReport

source
pub(all) struct AuditReport {
  valid : Bool
  checked_events : Int
  findings : Array[AuditFinding]
} derive(Eq, 
Debug)

Deterministic safety audit result.

#
AuditReport::to_json

source
fn AuditReport::to_json(self : AuditReport) -> String

Encodes a safety audit as stable JSON.

#
BatchResult

source
pub(all) struct BatchResult {
  table : LeaseTable
  decisions : Array[LeaseDecision]
  accepted : Int
  rejected : Int
} derive(Eq, 
Debug)

Summary for a deterministic command batch.

#
Candidate

source
pub(all) struct Candidate {
  id : String
  priority : Int
} derive(Eq, 
Debug)

Candidate used by deterministic local election policy.

#
DecisionKind

source
pub(all) enum DecisionKind {
  Acquired
  Renewed
  Released
  Transferred
  Reaped
  Rejected
} derive(Eq, 
Debug)

Administrative outcome of a lease command.

#
ElectionVote

source
pub(all) struct ElectionVote {
  voter : String
  candidate : String
  term : Int
  granted : Bool
} derive(Eq, 
Debug)

One cluster member's vote for a term.

#
FenceDecision

source
pub(all) struct FenceDecision {
  next_guard : FenceGuard
  accepted : Bool
  highest_token : Int
  message : String
} derive(Eq, 
Debug)

Result of validating a fenced write.

#
FenceGuard

source
pub(all) struct FenceGuard {
  marks : Array[FenceMark]
} derive(Eq, 
Debug)

Storage-independent fencing state.

#
FenceGuard::check

source
fn FenceGuard::check(self : FenceGuard, write : FencedWrite) -> FenceDecision

Validates a storage operation against the highest observed fencing token.

#
FenceGuard::highest_token

source
fn FenceGuard::highest_token(self : FenceGuard, resource : String) -> Int

Returns the highest accepted token for a resource, or zero if unseen.

#
FenceGuard::new

source
fn FenceGuard::new() -> FenceGuard

Creates an empty storage-side fencing guard.

#
FenceMark

source
pub(all) struct FenceMark {
  resource : String
  token : Int
  holder : String
} derive(Eq, 
Debug)

Highest fencing token observed for one resource.

#
FencedWrite

source
pub(all) struct FencedWrite {
  resource : String
  holder : String
  token : Int
  operation : String
} derive(Eq, 
Debug)

A write request protected by a lease fencing token.

#
Lease

source
pub(all) struct Lease {
  resource : String
  holder : String
  token : Int
  revision : Int
  issued_at : Int
  expires_at : Int
} derive(Eq, 
Debug)

A granted lease. token is a monotonically increasing fencing token.

#
Lease::fenced_write

source
fn Lease::fenced_write(self : Lease, operation : String, now : Int) -> FencedWrite?

Builds a write request directly from an active lease.

#
Lease::is_active

source
fn Lease::is_active(self : Lease, now : Int) -> Bool

Returns whether this lease is valid at the supplied logical time.

#
Lease::remaining

source
fn Lease::remaining(self : Lease, now : Int) -> Int

Remaining logical ticks, clamped to zero.

#
Lease::to_json

source
fn Lease::to_json(self : Lease) -> String

Encodes a lease as stable JSON.

#
LeaseCommand

source
pub(all) enum LeaseCommand {
  Acquire(String, Int, Int?)
  Renew(String, Int, Int)
  Release(String, Int)
  Transfer(String, Int, String, Int)
  Reap
} derive(Eq, 
Debug)

Commands accepted by the pure lease state machine.

#
LeaseDecision

source
pub(all) struct LeaseDecision {
  state : LeaseState
  accepted : Bool
  kind : DecisionKind
  lease : Lease?
  event : LeaseEvent?
  message : String
} derive(Eq, 
Debug)

Result returned for every command, including rejected commands.

#
LeaseEvent

source
pub(all) struct LeaseEvent {
  resource : String
  kind : DecisionKind
  at : Int
  holder : String
  token : Int
  revision : Int
  detail : String
} derive(Eq, 
Debug)

An auditable state transition record.

#
LeaseEvent::to_json

source
fn LeaseEvent::to_json(self : LeaseEvent) -> String

Encodes an audit event as stable JSON.

#
LeaseMetrics

source
pub(all) struct LeaseMetrics {
  resources : Int
  stored_leases : Int
  active_leases : Int
  expired_leases : Int
  highest_token : Int
  events : Int
  accepted_commands : Int
  rejected_commands : Int
} derive(Eq, 
Debug)

Point-in-time table metrics.

#
LeaseMetrics::to_json

source
fn LeaseMetrics::to_json(self : LeaseMetrics) -> String

Encodes metrics as stable JSON.

#
LeaseState

source
pub(all) struct LeaseState {
  resource : String
  lease : Lease?
  next_token : Int
  revision : Int
} derive(Eq, 
Debug)

Complete deterministic state for one leased resource.

#
LeaseState::active_lease

source
fn LeaseState::active_lease(self : LeaseState, now : Int) -> Lease?

Returns the active lease, treating expired or not-yet-issued records as absent.

#
LeaseState::apply

source
fn LeaseState::apply(self : LeaseState, command : LeaseCommand, now : Int) -> LeaseDecision

Applies one command at an explicit logical time.

#
LeaseState::new

source
fn LeaseState::new(resource : String) -> LeaseState

Creates an empty resource state. Token zero is never issued.

#
LeaseTable

source
pub(all) struct LeaseTable {
  states : Array[LeaseState]
  events : Array[LeaseEvent]
  accepted_commands : Int
  rejected_commands : Int
} derive(Eq, 
Debug)

Multi-resource lease coordinator state.

#
LeaseTable::acquire_leadership

source
fn LeaseTable::acquire_leadership(self : LeaseTable, resource : String, certificate : QuorumCertificate, ttl : Int, now : Int) -> TableDecision

Acquires a leadership lease only when a quorum certificate is valid.

#
LeaseTable::active_leases

source
fn LeaseTable::active_leases(self : LeaseTable, now : Int) -> Array[Lease]

Returns all leases active at an explicit logical time.

#
LeaseTable::apply

source
fn LeaseTable::apply(self : LeaseTable, resource : String, command : LeaseCommand, now : Int) -> TableDecision

Applies one resource command and records accepted transitions.

#
LeaseTable::apply_batch

source
fn LeaseTable::apply_batch(self : LeaseTable, commands : Array[TimedCommand]) -> BatchResult

Applies commands in input order and preserves every decision.

#
LeaseTable::get

source
fn LeaseTable::get(self : LeaseTable, resource : String) -> LeaseState?

Returns the state for a resource.

#
LeaseTable::metrics

source
fn LeaseTable::metrics(self : LeaseTable, now : Int) -> LeaseMetrics

Computes point-in-time table metrics.

#
LeaseTable::new

source
fn LeaseTable::new() -> LeaseTable

Creates an empty multi-resource lease table.

#
LeaseTable::reap_expired

source
fn LeaseTable::reap_expired(self : LeaseTable, now : Int) -> BatchResult

Reaps every expired stored lease in deterministic table order.

#
QuorumCertificate

source
pub(all) struct QuorumCertificate {
  valid : Bool
  leader : String
  term : Int
  quorum : Int
  voters : Array[String]
  equivocations : Array[String]
  message : String
} derive(Eq, 
Debug)

Evidence that one candidate reached quorum in a term.

#
SimulationReport

source
pub(all) struct SimulationReport {
  cycles : Int
  leases_acquired : Int
  writes_accepted : Int
  stale_writes_rejected : Int
  final_token : Int
  audit_valid : Bool
  evidence : Int
} derive(Eq, 
Debug)

Reproducible failover simulation evidence.

#
SimulationReport::to_json

source
fn SimulationReport::to_json(self : SimulationReport) -> String

Encodes reproducible simulation evidence as stable JSON.

#
StateIssue

source
pub(all) struct StateIssue {
  code : String
  message : String
} derive(Eq, 
Debug)

Validation issue for state restored from external storage.

#
TableDecision

source
pub(all) struct TableDecision {
  table : LeaseTable
  decision : LeaseDecision
} derive(Eq, 
Debug)

Result of applying a command to a resource table.

#
TimedCommand

source
pub(all) struct TimedCommand {
  resource : String
  command : LeaseCommand
  at : Int
} derive(Eq, 
Debug)

A command with its resource and deterministic logical timestamp.

#
audit_events

source
fn audit_events(events : Array[LeaseEvent]) -> AuditReport

Checks monotonic token, revision, and logical-time invariants.

#
certify_votes

source
fn certify_votes(votes : Array[ElectionVote], cluster_size : Int, term : Int) -> QuorumCertificate

Validates a term's votes and returns deterministic quorum evidence.

#
decision_kind_name

source
fn decision_kind_name(kind : DecisionKind) -> String

Stable snake-case name for a decision kind.

#
json_escape

source
fn json_escape(value : String) -> String

Escapes a string for JSON output.

#
quorum_size

source
fn quorum_size(cluster_size : Int) -> Int

Returns the strict majority required by a cluster size.

#
run_failover_simulation

source
fn run_failover_simulation(cycles : Int, ttl? : Int) -> SimulationReport

Runs repeated expiry, takeover, and stale-writer scenarios.

#
select_candidate

source
fn select_candidate(candidates : Array[Candidate]) -> Candidate?

Selects highest priority and resolves ties by lexicographically smaller id.

#
state_is_valid

source
fn state_is_valid(state : LeaseState) -> Bool

Returns whether restored state is safe to apply.

#
validate_state

source
fn validate_state(state : LeaseState) -> Array[StateIssue]

Validates invariants before using state loaded from external storage.

Source Files

Powered by MoonBit

Site sourceReport issuePackagesBuild queueSkillsStatistics

© 2026 mooncakes.io