🥮 mooncakes.io
    Sign in

    moonleasekit

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

    lease
    fencing-token
    leader-election
    distributed-systems
    deterministic
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Repository
    Last updated
    3 months ago
    Downloads
    31

    #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