跳转到内容
简体中文

InMemoryLease

此内容尚不支持你的语言。

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.

  • Unit tests for actors that take a Lease parameter — pass InMemoryLease to 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.

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.

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(); // → true
await 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.

The implementation:

  • acquire() atomically CAS-es the registry slot. Returns true if it claimed; false if 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, and inMemoryLeaseStore.peek() stops reporting it.
  • checkAlive() compares against that same expiry, so a holder whose renewal did not come round in time reads false from 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 fires onLost instead of extending the lapsed record.
  • onLost fires 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()).

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.