InMemoryLease
InMemoryLease ist die Dev-/Test-Implementierung des
Lease-Interfaces. Sie hält den
Lease-State im Speicher eines Isolates — eines Prozesses oder
eines seiner Worker-Threads — mehrere InMemoryLease-Instanzen, die
denselben name teilen, schließen sich also korrekt aus, aber nur
innerhalb dieses Isolates.
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 (erstes Acquire)name, owner und ttlMs sind Pflicht — der Konstruktor wirft
OptionsError, sobald eines fehlt, statt ein Lease zu bauen, das
niemanden ausschließen kann. Zwei Leases ohne owner konkurrieren
beide unter demselben undefined-Holder und gewinnen beide; ohne
ttlMs ist die Ablaufzeit NaN und liegt damit nie nach jetzt, ein
bestehender Holder liest sich also immer als abgelaufen.
Wann du sie einsetzt
Abschnitt betitelt „Wann du sie einsetzt“- Unit Tests für Actors, die einen
Lease-Parameter bekommen — übergibInMemoryLease, um Lease-Verhalten ohne echtes Backend zu verifizieren. - Dev für Code, der einen Lease braucht, aber du willst Kubernetes oder etcd nicht lokal aufsetzen.
- MultiNodeSpec-Tests — jeder “Node” läuft auf einem Thread eines Prozesses, also schließt sich ein über die Test-Nodes geteiltes InMemoryLease korrekt aus.
Wann du sie NICHT einsetzt
Abschnitt betitelt „Wann du sie NICHT einsetzt“Aus demselben Grund ist sie aus der Konfiguration nicht wählbar:
actor-ts.coordination.lease.backend nimmt kubernetes an und lehnt
in-memory namentlich ab, denn ein Lease, den das Framework für ein
Singleton oder einen Koordinator baut, muss über Nodes hinweg ausschließen,
und dieser kann das nicht.
Der gemeinsame Store
Abschnitt betitelt „Der gemeinsame Store“Jedes InMemoryLease in einem Isolate konkurriert gegen einen
modul-globalen Store (inMemoryLeaseStore) — es gibt kein
Registry pro Instanz zu verdrahten. Zwei InMemoryLease-Instanzen,
die denselben name teilen, schließen sich also automatisch aus:
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') // gleicher Name .withOwner('node-b') .withTtlMs(30_000);const leaseB = new InMemoryLease( lease2Options,);
await leaseA.acquire(); // → trueawait leaseB.acquire(); // → false (leaseA hält ihn)Das ist das MultiNodeSpec-Muster — jeder simulierte Node
bekommt ein InMemoryLease für denselben name, und sie kämpfen
um den Lease, wie es echte verteilte Peers tun würden.
Da der Store ein modul-globales Objekt ist und ein Worker-Thread jedes Modul in einer eigenen Kopie lädt, gilt der gegenseitige Ausschluss nur innerhalb eines Isolates — separate Prozesse und separate Worker-Threads eines Prozesses bekommen jeweils ihren eigenen Store und sehen die Leases der anderen nicht.
Verhaltensdetails
Abschnitt betitelt „Verhaltensdetails“Die Implementierung:
acquire()CAS-t den Registry-Slot atomar. Gibttruezurück, wenn sie ihn beansprucht hat;false, wenn ein anderer Owner ihn hält.- TTL-Ablauf passiert lazy — zur Deadline läuft nichts. Ein
Record nach seinem Ablauf ist einfach frei: Das nächste
acquire()eines anderen Owners übernimmt ihn, undinMemoryLeaseStore.peek()meldet ihn nicht mehr. checkAlive()vergleicht gegen denselben Ablauf, sodass ein Halter, dessen Renewal nicht rechtzeitig kam, ab der Deadlinefalseliest, bevor ihm irgendetwas davon gesagt hat.- Renewal läuft alle
renewalIntervalMs(Default ein Drittel der TTL mit 100 ms Untergrenze, gedeckelt auf die halbe TTL). Ein Renewal, das erst nach der Deadline drankommt, gibt den Lease auf und feuertonLost, statt den abgelaufenen Record zu verlängern. onLostfeuert, wenn ein Renewal den Record weg, von einem anderen Owner gehalten oder über seiner Deadline findet — Letzteres sieht ein Halter, der länger als seine TTL stand.
Timer laufen standardmäßig auf setInterval.
LeaseOptions.withScheduler(...) legt TTL, Renewal-Takt und
Acquire-Retries stattdessen auf einen Scheduler — mit einem
ManualScheduler spult ein Test dreißig Sekunden TTL vor, ohne
darauf zu warten. Um geteilten Lease-State zwischen Tests
zurückzusetzen, leere das exportierte Singleton
inMemoryLeaseStore direkt (inMemoryLeaseStore._clear()).
Beispiel: ein Singleton-Test
Abschnitt betitelt „Beispiel: ein 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 mit Lease', () => { it('nur ein Halter spawnt den 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-Verdrahtung + singletonActor ausgelassen)
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);
// Nur einer sollte je das Singleton-Actor-Child haben. // ... per Probes asserten ... });});Diese Art Test verifiziert die Lease-Integration, ohne von einer echten K8s-API abzuhängen.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- Koordination im Überblick — das Gesamtbild.
- Lease-API — der Vertrag,
den
InMemoryLeaseimplementiert. - KubernetesLease — die Produktions-Alternative.
- MultiNodeSpec — das Multi-Node-Test-Harness, das dazu passt.
