lease_machines 0.1.6

data/ext/lease_machines_native/core/src/authority.rs

@@ -0,0 +1,287 @@
+use core::time::Duration;
+
+use crate::{FencingToken, Lease, OwnerId};
+
+/// Why an authority rejected a request.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum Rejection {
+    /// An unexpired lease already occupies the resource.
+    Occupied,
+    /// No grant exists to renew or release.
+    NoLease,
+    /// The request's owner does not match the current grant.
+    WrongOwner,
+    /// The request's token does not match the current grant.
+    StaleToken,
+    /// The current grant has expired.
+    Expired,
+    /// Time moved backwards relative to a previous observation.
+    ClockRegressed,
+    /// TTL is zero or its addition overflows the duration range.
+    InvalidTtl,
+    /// No greater fencing token can be issued.
+    TokenExhausted,
+}
+
+/// How an authority treats an observation earlier than its last one.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+#[non_exhaustive]
+pub enum ClockPolicy {
+    /// Reject the request with `Rejection::ClockRegressed`, changing nothing.
+    #[default]
+    Reject,
+    /// Evaluate the request at the last observation instead of the earlier `now`.
+    Clamp,
+}
+
+/// A proposed state-machine outcome, to commit before exposing success.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum Decision {
+    /// A new token and lease were assigned.
+    Granted(Lease),
+    /// The current lease was renewed without changing its token.
+    Renewed(Lease),
+    /// The current lease was released.
+    Released,
+    /// The request was rejected.
+    Rejected(Rejection),
+}
+
+/// Opaque authority state with no promised wire representation.
+///
+/// Restore only the newest committed state with the same monotonic clock origin.
+/// Copying or rolling back this value does not create an independent authority.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Checkpoint {
+    last_issued: Option<FencingToken>,
+    lease: Option<Lease>,
+    observed: Duration,
+}
+
+impl Checkpoint {
+    /// Rebuild committed state from storage columns.
+    ///
+    /// Returns `None` when a lease carries a token the history never issued.
+    /// Use `Duration::ZERO` as `observed` when storage keeps no clock watermark.
+    #[must_use]
+    pub const fn from_parts(
+        last_issued: Option<FencingToken>,
+        lease: Option<Lease>,
+        observed: Duration,
+    ) -> Option<Self> {
+        if let Some(lease) = lease {
+            match last_issued {
+                Some(highest) if lease.token.value() <= highest.value() => {}
+                _ => return None,
+            }
+        }
+        Some(Self {
+            last_issued,
+            lease,
+            observed,
+        })
+    }
+
+    /// Greatest token issued in this authority history, even after release.
+    #[must_use]
+    pub const fn last_issued(self) -> Option<FencingToken> {
+        self.last_issued
+    }
+
+    /// Last grant; it may already be expired at the latest observation.
+    #[must_use]
+    pub const fn lease(self) -> Option<Lease> {
+        self.lease
+    }
+
+    /// Latest accepted clock observation, including rejected requests.
+    #[must_use]
+    pub const fn observed(self) -> Duration {
+        self.observed
+    }
+}
+
+/// A deterministic lease authority for one resource and token namespace.
+///
+/// Runtime adapters must serialize and durably commit transitions before
+/// exposing success. This type provides no distributed agreement or I/O.
+#[derive(Debug, PartialEq, Eq)]
+pub struct LeaseAuthority {
+    state: Checkpoint,
+    clock: ClockPolicy,
+}
+
+impl Default for LeaseAuthority {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+impl LeaseAuthority {
+    /// Start a **fresh** authority namespace. Never use this to reset an old one.
+    #[must_use]
+    pub const fn new() -> Self {
+        Self {
+            state: Checkpoint {
+                last_issued: None,
+                lease: None,
+                observed: Duration::ZERO,
+            },
+            clock: ClockPolicy::Reject,
+        }
+    }
+
+    /// Restore the newest committed checkpoint under the same clock origin.
+    ///
+    /// The caller must prevent simultaneous serving by the previous authority.
+    #[must_use]
+    pub const fn restore(checkpoint: Checkpoint) -> Self {
+        Self {
+            state: checkpoint,
+            clock: ClockPolicy::Reject,
+        }
+    }
+
+    /// Choose how earlier-than-observed clocks are handled; `Reject` by default.
+    #[must_use]
+    pub const fn with_clock_policy(mut self, clock: ClockPolicy) -> Self {
+        self.clock = clock;
+        self
+    }
+
+    /// Policy applied to regressing observations.
+    #[must_use]
+    pub const fn clock_policy(&self) -> ClockPolicy {
+        self.clock
+    }
+
+    /// Capture state for a host-controlled commit or deterministic simulation.
+    #[must_use]
+    pub const fn checkpoint(&self) -> Checkpoint {
+        self.state
+    }
+
+    /// Acquire an unoccupied/expired resource with a new, strictly greater token.
+    #[must_use]
+    pub fn acquire(&mut self, owner: OwnerId, now: Duration, ttl: Duration) -> Decision {
+        self.grant(owner, now, ttl, false)
+            .map_or_else(Decision::Rejected, Decision::Granted)
+    }
+
+    /// Acquire like `acquire`, or rotate the token of `owner`'s own unexpired grant.
+    ///
+    /// Another owner's unexpired grant is still `Occupied`. The previous token
+    /// becomes stale, so in-flight work under it is fenced.
+    #[must_use]
+    pub fn reacquire(&mut self, owner: OwnerId, now: Duration, ttl: Duration) -> Decision {
+        self.grant(owner, now, ttl, true)
+            .map_or_else(Decision::Rejected, Decision::Granted)
+    }
+
+    fn grant(
+        &mut self,
+        owner: OwnerId,
+        now: Duration,
+        ttl: Duration,
+        rotate: bool,
+    ) -> Result<Lease, Rejection> {
+        let now = self.observe(now)?;
+        let expires_at = expiration(now, ttl).ok_or(Rejection::InvalidTtl)?;
+        if self
+            .state
+            .lease
+            .is_some_and(|lease| now < lease.expires_at && !(rotate && lease.owner == owner))
+        {
+            return Err(Rejection::Occupied);
+        }
+        let token = FencingToken::next(self.state.last_issued).ok_or(Rejection::TokenExhausted)?;
+        let lease = Lease {
+            owner,
+            token,
+            expires_at,
+        };
+        self.state.last_issued = Some(token);
+        self.state.lease = Some(lease);
+        Ok(lease)
+    }
+
+    /// Renew only the current unexpired grant, retaining its token.
+    ///
+    /// A shorter requested TTL does not shorten the previous expiration.
+    #[must_use]
+    pub fn renew(
+        &mut self,
+        owner: OwnerId,
+        token: FencingToken,
+        now: Duration,
+        ttl: Duration,
+    ) -> Decision {
+        self.extend(owner, token, now, ttl)
+            .map_or_else(Decision::Rejected, Decision::Renewed)
+    }
+
+    fn extend(
+        &mut self,
+        owner: OwnerId,
+        token: FencingToken,
+        now: Duration,
+        ttl: Duration,
+    ) -> Result<Lease, Rejection> {
+        let (now, mut lease) = self.held(owner, token, now)?;
+        let expires_at = expiration(now, ttl).ok_or(Rejection::InvalidTtl)?;
+        lease.expires_at = lease.expires_at.max(expires_at);
+        self.state.lease = Some(lease);
+        Ok(lease)
+    }
+
+    /// Release only the current unexpired grant, retaining the token high-water.
+    #[must_use]
+    pub fn release(&mut self, owner: OwnerId, token: FencingToken, now: Duration) -> Decision {
+        match self.held(owner, token, now) {
+            Ok(_) => {
+                self.state.lease = None;
+                Decision::Released
+            }
+            Err(reason) => Decision::Rejected(reason),
+        }
+    }
+
+    /// Observe `now`, then return it with the current grant if `owner` holds
+    /// it under `token` and it has not expired.
+    fn held(
+        &mut self,
+        owner: OwnerId,
+        token: FencingToken,
+        now: Duration,
+    ) -> Result<(Duration, Lease), Rejection> {
+        let now = self.observe(now)?;
+        let lease = self.state.lease.ok_or(Rejection::NoLease)?;
+        lease
+            .rejection(owner, token, now)
+            .map_or(Ok((now, lease)), Err)
+    }
+
+    fn observe(&mut self, now: Duration) -> Result<Duration, Rejection> {
+        if now < self.state.observed {
+            return match self.clock {
+                ClockPolicy::Reject => Err(Rejection::ClockRegressed),
+                ClockPolicy::Clamp => Ok(self.state.observed),
+            };
+        }
+        self.state.observed = now;
+        Ok(now)
+    }
+}
+
+const fn expiration(now: Duration, ttl: Duration) -> Option<Duration> {
+    if ttl.is_zero() {
+        None
+    } else {
+        now.checked_add(ttl)
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/lease_machines_native/core/src/fencing.rs

@@ -0,0 +1,67 @@
+use core::num::NonZeroU64;
+
+/// A positive fencing sequence number within one resource's authority namespace.
+///
+/// This value is not a cryptographic proof that an authority issued it.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct FencingToken(NonZeroU64);
+
+impl FencingToken {
+    /// Decode a positive token; zero is not a valid issued token.
+    #[must_use]
+    pub const fn new(value: u64) -> Option<Self> {
+        match NonZeroU64::new(value) {
+            Some(value) => Some(Self(value)),
+            None => None,
+        }
+    }
+
+    /// Sequence number for trusted storage or transport adapters.
+    #[must_use]
+    pub const fn value(self) -> u64 {
+        self.0.get()
+    }
+
+    pub(crate) fn next(previous: Option<Self>) -> Option<Self> {
+        let value = previous.map_or(0, Self::value).checked_add(1)?;
+        Self::new(value)
+    }
+}
+
+/// Protected-resource high-water tracking for a single token namespace.
+///
+/// Persist updates atomically with the protected write. This local predicate does
+/// not check expiry, authenticate tokens, or serialize external mutations.
+#[derive(Debug, PartialEq, Eq)]
+pub struct Fence {
+    highest: Option<FencingToken>,
+}
+
+impl Fence {
+    /// Restore the newest committed high-water mark, or start a fresh resource.
+    #[must_use]
+    pub const fn new(highest: Option<FencingToken>) -> Self {
+        Self { highest }
+    }
+
+    /// Accept an equal/newer token and advance the local high-water mark.
+    ///
+    /// Returns `false` for a stale token, without changing state.
+    #[must_use]
+    pub fn accept(&mut self, token: FencingToken) -> bool {
+        if self.highest.is_some_and(|highest| token < highest) {
+            return false;
+        }
+        self.highest = Some(token);
+        true
+    }
+
+    /// Highest accepted token, to persist atomically with protected mutations.
+    #[must_use]
+    pub const fn highest(&self) -> Option<FencingToken> {
+        self.highest
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/lease_machines_native/core/src/holder.rs

@@ -0,0 +1,193 @@
+use core::time::Duration;
+
+use crate::FencingToken;
+
+/// Renewal timing for one grant, on the holder's own clock.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Cadence {
+    ttl: Duration,
+    renew_after: Duration,
+    warn_before: Duration,
+}
+
+impl Cadence {
+    /// Renew `renew_after` each confirmation; warn `warn_before` the local expiry.
+    ///
+    /// Returns `None` unless `renew_after < ttl` and `warn_before <= ttl`.
+    #[must_use]
+    pub const fn new(ttl: Duration, renew_after: Duration, warn_before: Duration) -> Option<Self> {
+        if ttl.is_zero()
+            || renew_after.as_nanos() >= ttl.as_nanos()
+            || warn_before.as_nanos() > ttl.as_nanos()
+        {
+            return None;
+        }
+        Some(Self {
+            ttl,
+            renew_after,
+            warn_before,
+        })
+    }
+
+    /// Lease duration the holder requests on every renewal.
+    #[must_use]
+    pub const fn ttl(self) -> Duration {
+        self.ttl
+    }
+}
+
+/// Where a holder stands with the grant it believes it owns.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+#[non_exhaustive]
+pub enum HolderState {
+    /// The last renewal succeeded and none is in flight.
+    Confirmed,
+    /// A renewal is in flight, with time to spare before the warning deadline.
+    Unconfirmed,
+    /// A renewal is in flight past the warning deadline.
+    AtRisk,
+    /// The authority reported expiry; only a fresh grant restores ownership.
+    Expired,
+    /// Ownership is lost for good; no event leaves this state.
+    Fenced,
+}
+
+/// Holder-side renewal tracker for a single grant.
+///
+/// Durations come from the holder's clock, not the authority's, so two
+/// machines never compare instants. Deadlines are derived from the moment a
+/// renewal was confirmed locally, which is never later than the authority's view.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Holder {
+    state: HolderState,
+    cadence: Cadence,
+    token: FencingToken,
+    renew_due: Duration,
+    warning_at: Duration,
+}
+
+impl Holder {
+    /// Track a grant confirmed at `confirmed_at` on the holder's clock.
+    #[must_use]
+    pub const fn new(token: FencingToken, confirmed_at: Duration, cadence: Cadence) -> Self {
+        let mut holder = Self {
+            state: HolderState::Confirmed,
+            cadence,
+            token,
+            renew_due: Duration::ZERO,
+            warning_at: Duration::ZERO,
+        };
+        holder.schedule(confirmed_at);
+        holder
+    }
+
+    /// Current lifecycle state.
+    #[must_use]
+    pub const fn state(&self) -> HolderState {
+        self.state
+    }
+
+    /// Newest token this holder has seen for its grant.
+    #[must_use]
+    pub const fn token(&self) -> FencingToken {
+        self.token
+    }
+
+    /// Whether a renewal should be started or retried now.
+    #[must_use]
+    pub const fn renewal_due(&self, now: Duration) -> bool {
+        match self.state {
+            HolderState::Confirmed => now.as_nanos() >= self.renew_due.as_nanos(),
+            HolderState::Fenced => false,
+            HolderState::Unconfirmed | HolderState::AtRisk | HolderState::Expired => true,
+        }
+    }
+
+    /// Point after which unconfirmed ownership should be treated as doubtful.
+    #[must_use]
+    pub const fn warning_deadline(&self) -> Option<Duration> {
+        match self.state {
+            HolderState::Fenced => None,
+            _ => Some(self.warning_at),
+        }
+    }
+
+    /// Whether ownership is unconfirmed or the warning deadline has passed.
+    #[must_use]
+    pub const fn at_risk(&self, now: Duration) -> bool {
+        !matches!(self.state, HolderState::Confirmed)
+            || now.as_nanos() >= self.warning_at.as_nanos()
+    }
+
+    /// Start a renewal attempt; repeated calls while one is outstanding are no-ops.
+    ///
+    /// Returns `false` once fenced.
+    pub const fn refresh(&mut self, now: Duration) -> bool {
+        match self.state {
+            HolderState::Fenced => false,
+            HolderState::Confirmed | HolderState::Unconfirmed => {
+                self.state = if now.as_nanos() >= self.warning_at.as_nanos() {
+                    HolderState::AtRisk
+                } else {
+                    HolderState::Unconfirmed
+                };
+                true
+            }
+            HolderState::AtRisk | HolderState::Expired => true,
+        }
+    }
+
+    /// Record a successful renewal observed at `at`.
+    ///
+    /// A response carrying a token older than the current one is ignored, as is
+    /// one arriving without an outstanding attempt or after expiry or fencing.
+    pub const fn confirm(&mut self, token: FencingToken, at: Duration) -> bool {
+        match self.state {
+            HolderState::Unconfirmed | HolderState::AtRisk
+                if token.value() >= self.token.value() =>
+            {
+                self.token = token;
+                self.state = HolderState::Confirmed;
+                self.schedule(at);
+                true
+            }
+            _ => false,
+        }
+    }
+
+    /// Record that the authority reported the grant expired.
+    pub const fn expire(&mut self) -> bool {
+        if matches!(self.state, HolderState::Fenced) {
+            return false;
+        }
+        self.state = HolderState::Expired;
+        true
+    }
+
+    /// Record a fresh grant with a strictly newer token after expiry.
+    pub const fn reacquire(&mut self, token: FencingToken, at: Duration) -> bool {
+        match self.state {
+            HolderState::Expired if token.value() > self.token.value() => {
+                self.token = token;
+                self.state = HolderState::Confirmed;
+                self.schedule(at);
+                true
+            }
+            _ => false,
+        }
+    }
+
+    /// Give up ownership permanently; idempotent.
+    pub const fn fence(&mut self) {
+        self.state = HolderState::Fenced;
+    }
+
+    const fn schedule(&mut self, confirmed_at: Duration) {
+        self.renew_due = confirmed_at.saturating_add(self.cadence.renew_after);
+        let window = self.cadence.ttl.saturating_sub(self.cadence.warn_before);
+        self.warning_at = confirmed_at.saturating_add(window);
+    }
+}
+
+#[cfg(test)]
+mod tests;

data/ext/lease_machines_native/core/src/lease.rs

@@ -0,0 +1,76 @@
+use core::time::Duration;
+
+use crate::{FencingToken, Rejection};
+
+/// An opaque numeric owner identity, scoped and authenticated by the adapter.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
+pub struct OwnerId(u64);
+
+impl OwnerId {
+    /// Construct an owner identity. Zero is a valid identity.
+    #[must_use]
+    pub const fn new(value: u64) -> Self {
+        Self(value)
+    }
+
+    /// Numeric identity for storage or transport adapters.
+    #[must_use]
+    pub const fn value(self) -> u64 {
+        self.0
+    }
+}
+
+/// One grant in a resource's serialized authority history.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Lease {
+    pub(crate) owner: OwnerId,
+    pub(crate) token: FencingToken,
+    pub(crate) expires_at: Duration,
+}
+
+impl Lease {
+    /// Rebuild a committed grant from storage; see `Checkpoint::from_parts`.
+    #[must_use]
+    pub const fn new(owner: OwnerId, token: FencingToken, expires_at: Duration) -> Self {
+        Self {
+            owner,
+            token,
+            expires_at,
+        }
+    }
+
+    /// Owner identity that received this grant.
+    #[must_use]
+    pub const fn owner(self) -> OwnerId {
+        self.owner
+    }
+
+    /// Resource-scoped token to present to protected mutations.
+    #[must_use]
+    pub const fn token(self) -> FencingToken {
+        self.token
+    }
+
+    /// Expiration relative to the authority's monotonic origin.
+    #[must_use]
+    pub const fn expires_at(self) -> Duration {
+        self.expires_at
+    }
+
+    pub(crate) fn rejection(
+        self,
+        owner: OwnerId,
+        token: FencingToken,
+        now: Duration,
+    ) -> Option<Rejection> {
+        if self.owner != owner {
+            Some(Rejection::WrongOwner)
+        } else if self.token != token {
+            Some(Rejection::StaleToken)
+        } else if now >= self.expires_at {
+            Some(Rejection::Expired)
+        } else {
+            None
+        }
+    }
+}

data/ext/lease_machines_native/core/src/lib.rs

@@ -0,0 +1,12 @@
+#![no_std]
+#![doc = include_str!("../README.md")]
+
+mod authority;
+mod fencing;
+mod holder;
+mod lease;
+
+pub use authority::{Checkpoint, ClockPolicy, Decision, LeaseAuthority, Rejection};
+pub use fencing::{Fence, FencingToken};
+pub use holder::{Cadence, Holder, HolderState};
+pub use lease::{Lease, OwnerId};

data/ext/lease_machines_native/extconf.rb

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+require_relative 'ffi/extconf'

data/ext/lease_machines_native/ffi/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "lease_machines_native"
+version = "0.1.5"
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+publish = false
+[lib]
+crate-type = ["cdylib"]
+test = false
+doctest = false
+[dependencies]
+lease-machines.workspace = true
+magnus.workspace = true
+rb-sys.workspace = true
+[lints]
+workspace = true

data/ext/lease_machines_native/ffi/extconf.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+require 'mkmf'
+require 'pathname'
+require 'rb_sys/mkmf'
+create_rust_makefile('lease_machines_native/lease_machines_native') do |extension|
+  extension.ext_dir = Pathname(__dir__).relative_path_from(Pathname(Dir.pwd)).to_s
+  extension.profile = ENV.fetch('RB_SYS_CARGO_PROFILE', :release).to_sym
+end
+makefile = File.join(Dir.pwd, 'Makefile')
+manifest_dir = File.expand_path(__dir__)
+patched = File.read(makefile).gsub(/^RB_SYS_CARGO_MANIFEST_DIR \?=.*$/, "RB_SYS_CARGO_MANIFEST_DIR ?= #{manifest_dir}")
+File.write(makefile, patched)