InMemoryLease
Esta página aún no está disponible en tu idioma.
InMemoryLease is the dev / test implementation of the
Lease interface. It holds
the lease state in the memory of one isolate — one process, or
one worker thread of it — so multiple InMemoryLease instances
sharing the same name mutually exclude correctly, but only within
that isolate.
import { InMemoryLease, LeaseOptions } from 'actor-ts/coordination';
const leaseOptions = LeaseOptions.create() .withName('my-singleton') .withOwner('instance-1') .withTtlMs(30_000);const lease = new InMemoryLease( leaseOptions,);
await lease.acquire(); // → true (first acquire)name, owner and ttlMs are required — the constructor throws
OptionsError when one is missing, rather than building a lease
that cannot exclude anyone. Two leases with no owner both
compete under the same undefined holder and both win; with no
ttlMs the expiry is NaN, which is never later than now, so an
existing holder always reads as expired.
When to use it
Section titled “When to use it”- Unit tests for actors that take a
Leaseparameter — passInMemoryLeaseto verify lease-related behavior without a real backend. - Dev for code that needs a lease but you don’t want to set up Kubernetes or etcd locally.
- MultiNodeSpec tests — every “node” runs on one thread of one process, so an InMemoryLease shared across the test nodes mutually excludes correctly.
When NOT to use it
Section titled “When NOT to use it”The same reason keeps it out of configuration:
actor-ts.coordination.lease.backend takes kubernetes and refuses
in-memory by name, because a lease the framework builds for a singleton
or a coordinator has to exclude across nodes, and this one cannot.
The shared store
Section titled “The shared store”Every InMemoryLease in an isolate competes against one
module-global store (inMemoryLeaseStore) — there is no
per-instance registry to wire up. So two InMemoryLease
instances that share the same name mutually exclude
automatically:
const leaseOptions = LeaseOptions.create() .withName('singleton-x') .withOwner('node-a') .withTtlMs(30_000);const leaseA = new InMemoryLease( leaseOptions,);
const lease2Options = LeaseOptions.create() .withName('singleton-x') // same name .withOwner('node-b') .withTtlMs(30_000);const leaseB = new InMemoryLease( lease2Options,);
await leaseA.acquire(); // → trueawait leaseB.acquire(); // → false (leaseA holds it)This is the MultiNodeSpec pattern — every simulated node
gets an InMemoryLease for the same name, and they fight
for the lease like real distributed peers would.
Because the store is a module-global, and a worker thread loads its own copy of every module, mutual exclusion holds only within one isolate — separate processes, and separate worker threads of one process, each get their own store and can’t see each other’s leases.
Behavior details
Section titled “Behavior details”The implementation:
acquire()atomically CAS-es the registry slot. Returnstrueif it claimed;falseif held by another owner.- TTL expiry is lazy — nothing runs at the deadline. A record
past its expiry is simply free: the next
acquire()by another owner takes it, andinMemoryLeaseStore.peek()stops reporting it. checkAlive()compares against that same expiry, so a holder whose renewal did not come round in time readsfalsefrom the deadline on, before anything has told it so.- Renewal runs every
renewalIntervalMs(default a third of the TTL with a 100 ms floor, capped at half the TTL). A renewal that only comes round after the deadline gives the lease up and firesonLostinstead of extending the lapsed record. onLostfires when a renewal finds the record gone, held by another owner, or past its deadline — the last is what a holder that stalled past its TTL sees.
Timers run on setInterval by default.
LeaseOptions.withScheduler(...) puts the TTL, the renewal cadence
and the acquire retries on a scheduler instead — with a
ManualScheduler, a test advances thirty seconds of TTL without
waiting for them. To reset shared lease state between tests, clear
the exported inMemoryLeaseStore singleton directly
(inMemoryLeaseStore._clear()).
Example: a singleton test
Section titled “Example: a singleton test”import { describe, it, expect } from 'bun:test';import { TestKit } from 'actor-ts/testkit';import { InMemoryLease, LeaseOptions } from 'actor-ts/coordination';import { StartSingletonOptions } from 'actor-ts/cluster';
describe('SingletonManager with lease', () => { it('only one holder spawns the singleton', async () => { const tk1 = TestKit.create('node-1'); const tk2 = TestKit.create('node-2');
const leaseOptions = LeaseOptions.create() .withName('singleton') .withOwner('n1') .withTtlMs(30_000); const lease1 = new InMemoryLease( leaseOptions, ); const lease2Options = LeaseOptions.create() .withName('singleton') .withOwner('n2') .withTtlMs(30_000); const lease2 = new InMemoryLease( lease2Options, );
// (cluster wiring + singletonActor elided)
const singleton1Options = StartSingletonOptions.create() .withTypeName('s') .withActor(singletonActor) .withLease(lease1); cluster1.singleton.start(singleton1Options);
const singleton2Options = StartSingletonOptions.create() .withTypeName('s') .withActor(singletonActor) .withLease(lease2); cluster2.singleton.start(singleton2Options);
// Only one should ever have the singleton actor child. // ... assert via probes ... });});This kind of test verifies the lease integration without depending on a real K8s API.
Where to next
Section titled “Where to next”- Coordination overview — the bigger picture.
- Lease API — the
contract
InMemoryLeaseimplements. - KubernetesLease — the production alternative.
- MultiNodeSpec — the multi-node test harness this pairs with.
