Zum Inhalt springen
Deutsch

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.

  • Unit Tests für Actors, die einen Lease-Parameter bekommen — übergib InMemoryLease, 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.

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.

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

Die Implementierung:

  • acquire() CAS-t den Registry-Slot atomar. Gibt true zurü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, und inMemoryLeaseStore.peek() meldet ihn nicht mehr.
  • checkAlive() vergleicht gegen denselben Ablauf, sodass ein Halter, dessen Renewal nicht rechtzeitig kam, ab der Deadline false liest, 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 feuert onLost, statt den abgelaufenen Record zu verlängern.
  • onLost feuert, 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()).

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.