actor-ts 0.9.0

package/dist/discovery/DnsSeedProvider.d.ts

@@ -0,0 +1,49 @@
+import { NodeAddress } from '../cluster/NodeAddress.js';
+import type { SeedProvider } from './SeedProvider.js';
+export interface DnsSeedProviderSettings {
+    /** Hostname to resolve (e.g. `my-cluster.default.svc.cluster.local`). */
+    readonly hostname: string;
+    /** System name to stamp on discovered NodeAddresses. */
+    readonly systemName: string;
+    /** Port each discovered IP should be paired with. */
+    readonly port: number;
+    /** Override the DNS-resolve function — defaults to `node:dns/promises`. */
+    readonly resolve?: (hostname: string) => Promise<string[]>;
+    /** When using SRV records, override `resolveSrv` similarly. */
+    readonly resolveSrv?: (hostname: string) => Promise<Array<{
+        name: string;
+        port: number;
+    }>>;
+    /** If true, prefer SRV records (which carry a port) over A. */
+    readonly useSrv?: boolean;
+    /**
+     * In-process TTL cache for DNS lookups.  Deliberately *not* a
+     * distributed cache — DNS resolution is a per-process concern, and a
+     * Redis hop here would cost more than the lookup itself.  Default:
+     * 60_000 ms.  Set `0` to disable.  Failures are NOT cached: a query
+     * that throws will retry on the next call.
+     */
+    readonly cacheTtlMs?: number;
+}
+/**
+ * Seed provider backed by DNS.  Default mode resolves A records and pairs
+ * each IP with the configured port; SRV mode picks up `name:port` directly.
+ *
+ * The actual DNS functions are injected via settings so tests can stub them
+ * without touching the network.  The real impl uses `node:dns/promises`.
+ *
+ * **TTL cache:** repeated lookups inside the configured `cacheTtlMs`
+ * window are served from a per-instance in-memory cache, halving the
+ * DNS load on large clusters where each node polls the same name.
+ */
+export declare class DnsSeedProvider implements SeedProvider {
+    private readonly settings;
+    private cached;
+    private readonly cacheTtlMs;
+    constructor(settings: DnsSeedProviderSettings);
+    lookup(): Promise<NodeAddress[]>;
+    /** Test hook — drop the cached entry so the next `lookup()` re-queries DNS. */
+    invalidateCacheForTest(): void;
+    private doLookup;
+}
+//# sourceMappingURL=DnsSeedProvider.d.ts.map

package/dist/discovery/DnsSeedProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DnsSeedProvider.d.ts","sourceRoot":"","sources":["../../src/discovery/DnsSeedProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3D,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAC3F,+DAA+D;IAC/D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,YAAW,YAAY;IAItC,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAHrC,OAAO,CAAC,MAAM,CAA4D;IAC1E,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAEP,QAAQ,EAAE,uBAAuB;IAOxD,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAYtC,+EAA+E;IAC/E,sBAAsB,IAAI,IAAI;YAEhB,QAAQ;CAUvB"}

package/dist/discovery/DnsSeedProvider.js

@@ -0,0 +1,57 @@
+import { NodeAddress } from '../cluster/NodeAddress.js';
+/**
+ * Seed provider backed by DNS.  Default mode resolves A records and pairs
+ * each IP with the configured port; SRV mode picks up `name:port` directly.
+ *
+ * The actual DNS functions are injected via settings so tests can stub them
+ * without touching the network.  The real impl uses `node:dns/promises`.
+ *
+ * **TTL cache:** repeated lookups inside the configured `cacheTtlMs`
+ * window are served from a per-instance in-memory cache, halving the
+ * DNS load on large clusters where each node polls the same name.
+ */
+export class DnsSeedProvider {
+    settings;
+    cached = null;
+    cacheTtlMs;
+    constructor(settings) {
+        this.settings = settings;
+        this.cacheTtlMs = settings.cacheTtlMs ?? 60_000;
+        if (!Number.isFinite(this.cacheTtlMs) || this.cacheTtlMs < 0) {
+            throw new Error(`DnsSeedProvider: cacheTtlMs must be a non-negative finite number, got ${this.cacheTtlMs}`);
+        }
+    }
+    async lookup() {
+        const now = Date.now();
+        if (this.cached && this.cached.expiresAt > now) {
+            return this.cached.value;
+        }
+        const value = await this.doLookup();
+        if (this.cacheTtlMs > 0) {
+            this.cached = { value, expiresAt: now + this.cacheTtlMs };
+        }
+        return value;
+    }
+    /** Test hook — drop the cached entry so the next `lookup()` re-queries DNS. */
+    invalidateCacheForTest() { this.cached = null; }
+    async doLookup() {
+        if (this.settings.useSrv) {
+            const resolveSrv = this.settings.resolveSrv ?? defaultResolveSrv;
+            const records = await resolveSrv(this.settings.hostname);
+            return records.map(r => new NodeAddress(this.settings.systemName, r.name, r.port));
+        }
+        const resolve = this.settings.resolve ?? defaultResolve;
+        const ips = await resolve(this.settings.hostname);
+        return ips.map(ip => new NodeAddress(this.settings.systemName, ip, this.settings.port));
+    }
+}
+async function defaultResolve(hostname) {
+    const dns = await import('node:dns/promises');
+    return dns.resolve4(hostname);
+}
+async function defaultResolveSrv(hostname) {
+    const dns = await import('node:dns/promises');
+    const records = await dns.resolveSrv(hostname);
+    return records.map(r => ({ name: r.name, port: r.port }));
+}
+//# sourceMappingURL=DnsSeedProvider.js.map

package/dist/discovery/DnsSeedProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DnsSeedProvider.js","sourceRoot":"","sources":["../../src/discovery/DnsSeedProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AA0BxD;;;;;;;;;;GAUG;AACH,MAAM,OAAO,eAAe;IAIG;IAHrB,MAAM,GAAuD,IAAI,CAAC;IACzD,UAAU,CAAS;IAEpC,YAA6B,QAAiC;QAAjC,aAAQ,GAAR,QAAQ,CAAyB;QAC5D,IAAI,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,IAAI,MAAM,CAAC;QAChD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,KAAK,CAAC,yEAAyE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;QAC9G,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC;YAC/C,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;QAC3B,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,CAAC,MAAM,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QAC5D,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+EAA+E;IAC/E,sBAAsB,KAAW,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;IAE9C,KAAK,CAAC,QAAQ;QACpB,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;YACzB,MAAM,UAAU,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,IAAI,iBAAiB,CAAC;YACjE,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YACzD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACrF,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,IAAI,cAAc,CAAC;QACxD,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAClD,OAAO,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,EAAE,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;IAC1F,CAAC;CACF;AAED,KAAK,UAAU,cAAc,CAAC,QAAgB;IAC5C,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAC9C,OAAO,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAChC,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,QAAgB;IAC/C,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IAC/C,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;AAC5D,CAAC"}

package/dist/discovery/KubernetesApiSeedProvider.d.ts

@@ -0,0 +1,30 @@
+import { NodeAddress } from '../cluster/NodeAddress.js';
+import type { SeedProvider } from './SeedProvider.js';
+export interface KubernetesApiSeedProviderSettings {
+    /** Target namespace to look up endpoints in. */
+    readonly namespace: string;
+    /** Service or Endpoints name whose backing pods provide the cluster. */
+    readonly serviceName: string;
+    /** System name stamped on the discovered NodeAddresses. */
+    readonly systemName: string;
+    /** Port for the cluster remoting endpoint on each pod. */
+    readonly port: number;
+    /** Override the Endpoints-fetch function — defaults to the in-cluster API. */
+    readonly fetchEndpoints?: () => Promise<string[]>;
+}
+/**
+ * Seed provider driven by the Kubernetes API.  Reads the Endpoints object
+ * for a headless Service (or any Service) and extracts the ready pod IPs.
+ *
+ * Intentionally lightweight: we don't ship a full K8s client.  The
+ * `fetchEndpoints` hook lets callers plug in either `@kubernetes/client-node`
+ * or their own small fetch wrapper; the default implementation makes a
+ * simple HTTPS call to `https://kubernetes.default.svc` using the standard
+ * ServiceAccount token mount.
+ */
+export declare class KubernetesApiSeedProvider implements SeedProvider {
+    private readonly settings;
+    constructor(settings: KubernetesApiSeedProviderSettings);
+    lookup(): Promise<NodeAddress[]>;
+}
+//# sourceMappingURL=KubernetesApiSeedProvider.d.ts.map

package/dist/discovery/KubernetesApiSeedProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KubernetesApiSeedProvider.d.ts","sourceRoot":"","sources":["../../src/discovery/KubernetesApiSeedProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,MAAM,WAAW,iCAAiC;IAChD,gDAAgD;IAChD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;CACnD;AAED;;;;;;;;;GASG;AACH,qBAAa,yBAA0B,YAAW,YAAY;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,iCAAiC;IAElE,MAAM,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAKvC"}

package/dist/discovery/KubernetesApiSeedProvider.js

@@ -0,0 +1,66 @@
+import { NodeAddress } from '../cluster/NodeAddress.js';
+/**
+ * Seed provider driven by the Kubernetes API.  Reads the Endpoints object
+ * for a headless Service (or any Service) and extracts the ready pod IPs.
+ *
+ * Intentionally lightweight: we don't ship a full K8s client.  The
+ * `fetchEndpoints` hook lets callers plug in either `@kubernetes/client-node`
+ * or their own small fetch wrapper; the default implementation makes a
+ * simple HTTPS call to `https://kubernetes.default.svc` using the standard
+ * ServiceAccount token mount.
+ */
+export class KubernetesApiSeedProvider {
+    settings;
+    constructor(settings) {
+        this.settings = settings;
+    }
+    async lookup() {
+        const fetchEndpoints = this.settings.fetchEndpoints ?? defaultFetchEndpoints(this.settings);
+        const ips = await fetchEndpoints();
+        return ips.map(ip => new NodeAddress(this.settings.systemName, ip, this.settings.port));
+    }
+}
+/**
+ * Minimal in-cluster endpoints fetcher.  Reads the in-pod ServiceAccount
+ * credentials and calls the core API.  Keeps the code path small — real
+ * production deployments often swap this for the canonical K8s client.
+ */
+function defaultFetchEndpoints(settings) {
+    return async () => {
+        const fs = await import('node:fs/promises');
+        const https = await import('node:https');
+        const token = await fs.readFile('/var/run/secrets/kubernetes.io/serviceaccount/token', 'utf8').catch(() => '');
+        const ca = await fs.readFile('/var/run/secrets/kubernetes.io/serviceaccount/ca.crt').catch(() => undefined);
+        if (!token)
+            throw new Error('KubernetesApiSeedProvider: no ServiceAccount token found — run inside a pod or provide fetchEndpoints');
+        const path = `/api/v1/namespaces/${settings.namespace}/endpoints/${settings.serviceName}`;
+        const agent = new https.Agent(ca ? { ca } : {});
+        const res = await new Promise((resolve, reject) => {
+            const req = https.request({
+                host: 'kubernetes.default.svc',
+                path,
+                method: 'GET',
+                headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+                agent,
+            }, (r) => {
+                let body = '';
+                r.setEncoding('utf8');
+                r.on('data', (c) => { body += c; });
+                r.on('end', () => resolve({ status: r.statusCode ?? 0, body }));
+                r.on('error', reject);
+            });
+            req.on('error', reject);
+            req.end();
+        });
+        if (res.status !== 200)
+            throw new Error(`K8s API returned ${res.status}: ${res.body.slice(0, 200)}`);
+        const parsed = JSON.parse(res.body);
+        const ips = [];
+        for (const subset of parsed.subsets ?? []) {
+            for (const addr of subset.addresses ?? [])
+                ips.push(addr.ip);
+        }
+        return ips;
+    };
+}
+//# sourceMappingURL=KubernetesApiSeedProvider.js.map

package/dist/discovery/KubernetesApiSeedProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KubernetesApiSeedProvider.js","sourceRoot":"","sources":["../../src/discovery/KubernetesApiSeedProvider.ts"],"names":[],"mappings":"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"}

package/dist/discovery/Receptionist.d.ts

@@ -0,0 +1,55 @@
+import { Actor } from '../Actor.js';
+import { type Option } from '../util/Option.js';
+import type { ActorRef } from '../ActorRef.js';
+import type { ActorSystem } from '../ActorSystem.js';
+import { type ExtensionId } from '../Extension.js';
+import type { Cluster } from '../cluster/Cluster.js';
+import { Deregister, Find, Register, Subscribe, Unsubscribe } from './ReceptionistMessages.js';
+type Msg = Register | Deregister | Find | Subscribe | Unsubscribe;
+export interface ReceptionistSettings {
+    readonly cluster?: Cluster | null;
+    readonly gossipIntervalMs?: number;
+}
+/**
+ * Cluster-wide service registry.  Each node hosts one Receptionist actor.
+ * Register/Deregister are authoritative locally; peers learn about
+ * registrations through periodic gossip carrying a delta of local keys.
+ *
+ * When a peer node leaves, every key entry it contributed is removed and
+ * subscribers are notified with an updated Listing.
+ */
+export declare class Receptionist extends Actor<Msg> {
+    private readonly keys;
+    private readonly clusterRef;
+    private readonly gossipIntervalMs;
+    private version;
+    private gossipTimer;
+    private unsubWire;
+    private unsubCluster;
+    constructor(settings: ReceptionistSettings);
+    preStart(): void;
+    postStop(): void;
+    onReceive(msg: Msg): void;
+    private handleRegister;
+    private handleDeregister;
+    private handleFind;
+    private handleSubscribe;
+    private handleUnsubscribe;
+    private gossipTick;
+    private handleGossip;
+    private forgetNode;
+    private getOrCreate;
+    private maybeDrop;
+    private collectRefs;
+    private notifySubscribers;
+}
+export declare class ReceptionistExtension {
+    private readonly system;
+    private started;
+    constructor(system: ActorSystem);
+    start(cluster?: Cluster | null, settings?: Omit<ReceptionistSettings, 'cluster'>): ActorRef<Msg>;
+    get(): Option<ActorRef<Msg>>;
+}
+export declare const ReceptionistId: ExtensionId<ReceptionistExtension>;
+export {};
+//# sourceMappingURL=Receptionist.d.ts.map

package/dist/discovery/Receptionist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Receptionist.d.ts","sourceRoot":"","sources":["../../src/discovery/Receptionist.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEpC,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEhE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAIrD,OAAO,EACL,UAAU,EACV,IAAI,EAEJ,QAAQ,EAER,SAAS,EACT,WAAW,EAEZ,MAAM,2BAA2B,CAAC;AAGnC,KAAK,GAAG,GACJ,QAAQ,GACR,UAAU,GACV,IAAI,GACJ,SAAS,GACT,WAAW,CAAC;AAWhB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,qBAAa,YAAa,SAAQ,KAAK,CAAC,GAAG,CAAC;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA+B;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAiB;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,WAAW,CAA4B;IAC/C,OAAO,CAAC,SAAS,CAA6B;IAC9C,OAAO,CAAC,YAAY,CAA6B;gBAErC,QAAQ,EAAE,oBAAoB;IAMjC,QAAQ,IAAI,IAAI;IAiBhB,QAAQ,IAAI,IAAI;IAMhB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI;IAYlC,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,gBAAgB;IAWxB,OAAO,CAAC,UAAU;IAKlB,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,YAAY;IAuBpB,OAAO,CAAC,UAAU;IAclB,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,iBAAiB;CAK1B;AAID,qBAAa,qBAAqB;IAEpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IADnC,OAAO,CAAC,OAAO,CAA8B;gBAChB,MAAM,EAAE,WAAW;IAEhD,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,EAAE,QAAQ,GAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,CAAM,GAAG,QAAQ,CAAC,GAAG,CAAC;IAUpG,GAAG,IAAI,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;CAC7B;AAED,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,qBAAqB,CAG7D,CAAC"}

package/dist/discovery/Receptionist.js

@@ -0,0 +1,207 @@
+import { match, P } from 'ts-pattern';
+import { Actor } from '../Actor.js';
+import { DEFAULT_GOSSIP_INTERVAL_MS } from '../util/Constants.js';
+import { fromNullable } from '../util/Option.js';
+import { extensionId } from '../Extension.js';
+import { Props } from '../Props.js';
+import { MemberRemoved, MemberUp } from '../cluster/ClusterEvents.js';
+import { NodeAddress } from '../cluster/NodeAddress.js';
+import { RemoteActorRef } from '../cluster/RemoteActorRef.js';
+import { Deregister, Find, Listing, Register, Registered, Subscribe, Unsubscribe, } from './ReceptionistMessages.js';
+import { ServiceKey } from './ServiceKey.js';
+/**
+ * Cluster-wide service registry.  Each node hosts one Receptionist actor.
+ * Register/Deregister are authoritative locally; peers learn about
+ * registrations through periodic gossip carrying a delta of local keys.
+ *
+ * When a peer node leaves, every key entry it contributed is removed and
+ * subscribers are notified with an updated Listing.
+ */
+export class Receptionist extends Actor {
+    keys = new Map();
+    clusterRef;
+    gossipIntervalMs;
+    version = 0;
+    gossipTimer = null;
+    unsubWire = null;
+    unsubCluster = null;
+    constructor(settings) {
+        super();
+        this.clusterRef = settings.cluster ?? null;
+        this.gossipIntervalMs = settings.gossipIntervalMs ?? DEFAULT_GOSSIP_INTERVAL_MS;
+    }
+    preStart() {
+        if (this.clusterRef) {
+            this.unsubWire = this.clusterRef._onWire('receptionist-gossip', (msg) => this.handleGossip(msg));
+            this.unsubCluster = this.clusterRef.subscribe((evt) => match(evt)
+                .with(P.instanceOf(MemberRemoved), (e) => this.forgetNode(e.member.address))
+                .with(P.instanceOf(MemberUp), () => { this.version++; })
+                .otherwise(() => { }));
+            this.gossipTimer = this.system.scheduler.scheduleAtFixedRateFn(this.gossipIntervalMs, this.gossipIntervalMs, () => this.gossipTick());
+        }
+    }
+    postStop() {
+        this.unsubWire?.();
+        this.unsubCluster?.();
+        this.gossipTimer?.cancel();
+    }
+    onReceive(msg) {
+        match(msg)
+            .with(P.instanceOf(Register), (m) => this.handleRegister(m))
+            .with(P.instanceOf(Deregister), (m) => this.handleDeregister(m))
+            .with(P.instanceOf(Find), (m) => this.handleFind(m))
+            .with(P.instanceOf(Subscribe), (m) => this.handleSubscribe(m))
+            .with(P.instanceOf(Unsubscribe), (m) => this.handleUnsubscribe(m))
+            .exhaustive();
+    }
+    /* ---------------- handlers ---------------- */
+    handleRegister(msg) {
+        const entry = this.getOrCreate(msg.key);
+        const pathStr = msg.ref.path.toString();
+        if (!entry.local.has(pathStr)) {
+            entry.local.set(pathStr, msg.ref);
+            this.version++;
+            this.notifySubscribers(msg.key, entry);
+        }
+        msg.replyTo?.tell(new Registered(msg.key, msg.ref));
+    }
+    handleDeregister(msg) {
+        const entry = this.keys.get(msg.key.id);
+        if (!entry)
+            return;
+        const pathStr = msg.ref.path.toString();
+        if (entry.local.delete(pathStr)) {
+            this.version++;
+            this.notifySubscribers(msg.key, entry);
+            this.maybeDrop(msg.key.id, entry);
+        }
+    }
+    handleFind(msg) {
+        const entry = this.keys.get(msg.key.id);
+        msg.replyTo.tell(new Listing(msg.key, entry ? this.collectRefs(entry) : []));
+    }
+    handleSubscribe(msg) {
+        const entry = this.getOrCreate(msg.key);
+        entry.subscribers.add(msg.replyTo);
+        // Replay current listing to the new subscriber.
+        msg.replyTo.tell(new Listing(msg.key, this.collectRefs(entry)));
+    }
+    handleUnsubscribe(msg) {
+        const entry = this.keys.get(msg.key.id);
+        if (!entry)
+            return;
+        entry.subscribers.delete(msg.replyTo);
+        this.maybeDrop(msg.key.id, entry);
+    }
+    /* ---------------- cluster plumbing ---------------- */
+    gossipTick() {
+        if (!this.clusterRef)
+            return;
+        const peers = this.clusterRef.upMembers()
+            .filter(m => !m.address.equals(this.clusterRef.selfAddress));
+        if (peers.length === 0)
+            return;
+        const entries = {};
+        for (const [id, entry] of this.keys) {
+            if (entry.local.size === 0)
+                continue;
+            entries[id] = Array.from(entry.local.keys());
+        }
+        const gossip = {
+            t: 'receptionist-gossip',
+            from: this.clusterRef.selfAddress.toJSON(),
+            entries,
+            version: this.version,
+        };
+        const target = peers[Math.floor(Math.random() * peers.length)];
+        this.clusterRef.transport.send(target.address, gossip);
+    }
+    handleGossip(msg) {
+        if (!this.clusterRef)
+            return;
+        const senderAddr = NodeAddress.fromJSON(msg.from).toString();
+        // Replace this sender's remote contribution wholesale so diff-to-notify
+        // works per-key.
+        const affected = new Set();
+        for (const [id, entry] of this.keys) {
+            if (entry.remote.has(senderAddr)) {
+                entry.remote.delete(senderAddr);
+                affected.add(id);
+            }
+        }
+        for (const [id, paths] of Object.entries(msg.entries)) {
+            const entry = this.getOrCreate(new ServiceKey(id));
+            entry.remote.set(senderAddr, paths.slice());
+            affected.add(id);
+        }
+        for (const id of affected) {
+            const entry = this.keys.get(id);
+            if (entry)
+                this.notifySubscribers(new ServiceKey(id), entry);
+        }
+    }
+    forgetNode(addr) {
+        const key = addr.toString();
+        const affected = new Set();
+        for (const [id, entry] of this.keys) {
+            if (entry.remote.delete(key))
+                affected.add(id);
+        }
+        for (const id of affected) {
+            const entry = this.keys.get(id);
+            if (entry)
+                this.notifySubscribers(new ServiceKey(id), entry);
+        }
+    }
+    /* ---------------- helpers ---------------- */
+    getOrCreate(key) {
+        let e = this.keys.get(key.id);
+        if (!e) {
+            e = { local: new Map(), remote: new Map(), subscribers: new Set() };
+            this.keys.set(key.id, e);
+        }
+        return e;
+    }
+    maybeDrop(id, entry) {
+        if (entry.local.size === 0 && entry.remote.size === 0 && entry.subscribers.size === 0) {
+            this.keys.delete(id);
+        }
+    }
+    collectRefs(entry) {
+        const refs = Array.from(entry.local.values());
+        if (this.clusterRef) {
+            for (const [nodeStr, paths] of entry.remote) {
+                const nodeAddr = NodeAddress.parse(nodeStr);
+                for (const path of paths) {
+                    refs.push(new RemoteActorRef(nodeAddr, path, this.clusterRef));
+                }
+            }
+        }
+        return refs;
+    }
+    notifySubscribers(key, entry) {
+        if (entry.subscribers.size === 0)
+            return;
+        const listing = new Listing(key, this.collectRefs(entry));
+        for (const sub of entry.subscribers)
+            sub.tell(listing);
+    }
+}
+/* -------------------------- Extension ---------------------------- */
+export class ReceptionistExtension {
+    system;
+    started = null;
+    constructor(system) {
+        this.system = system;
+    }
+    start(cluster, settings = {}) {
+        if (this.started)
+            return this.started;
+        const ref = this.system.spawn(Props.create(() => new Receptionist({ cluster: cluster ?? null, ...settings })), 'receptionist');
+        this.started = ref;
+        return ref;
+    }
+    get() { return fromNullable(this.started); }
+}
+export const ReceptionistId = extensionId('actor-ts/discovery/receptionist', (system) => new ReceptionistExtension(system));
+//# sourceMappingURL=Receptionist.js.map

package/dist/discovery/Receptionist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Receptionist.js","sourceRoot":"","sources":["../../src/discovery/Receptionist.ts"],"names":[],"mappings":"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"}

package/dist/discovery/ReceptionistMessages.d.ts

@@ -0,0 +1,65 @@
+import type { ActorRef } from '../ActorRef.js';
+import { ServiceKey } from './ServiceKey.js';
+/** Register `ref` under `key` on this node. */
+export declare class Register<T = unknown> {
+    readonly key: ServiceKey<T>;
+    readonly ref: ActorRef<T>;
+    /** Optional: reply with Registered once accepted. */
+    readonly replyTo: ActorRef | null;
+    constructor(key: ServiceKey<T>, ref: ActorRef<T>, 
+    /** Optional: reply with Registered once accepted. */
+    replyTo?: ActorRef | null);
+}
+/** Ack sent back to the `replyTo` of a Register message. */
+export declare class Registered<T = unknown> {
+    readonly key: ServiceKey<T>;
+    readonly ref: ActorRef<T>;
+    constructor(key: ServiceKey<T>, ref: ActorRef<T>);
+}
+/** Remove `ref` from `key`. */
+export declare class Deregister<T = unknown> {
+    readonly key: ServiceKey<T>;
+    readonly ref: ActorRef<T>;
+    constructor(key: ServiceKey<T>, ref: ActorRef<T>);
+}
+/** One-shot lookup: reply with Listing once to `replyTo`. */
+export declare class Find<T = unknown> {
+    readonly key: ServiceKey<T>;
+    readonly replyTo: ActorRef<Listing<T>>;
+    constructor(key: ServiceKey<T>, replyTo: ActorRef<Listing<T>>);
+}
+/**
+ * Continuous subscription: `replyTo` receives a Listing now AND every time
+ * the set of refs for this key changes (register, deregister, cluster
+ * gossip, node leaving).
+ */
+export declare class Subscribe<T = unknown> {
+    readonly key: ServiceKey<T>;
+    readonly replyTo: ActorRef<Listing<T>>;
+    constructor(key: ServiceKey<T>, replyTo: ActorRef<Listing<T>>);
+}
+/** Stop an active Subscribe. */
+export declare class Unsubscribe<T = unknown> {
+    readonly key: ServiceKey<T>;
+    readonly replyTo: ActorRef<Listing<T>>;
+    constructor(key: ServiceKey<T>, replyTo: ActorRef<Listing<T>>);
+}
+/**
+ * Reply sent to Find requesters and to every Subscribe subscriber whenever
+ * the current set of registrations for the key changes.  `refs` includes
+ * actors registered on *any* cluster node.
+ */
+export declare class Listing<T = unknown> {
+    readonly key: ServiceKey<T>;
+    readonly refs: ReadonlyArray<ActorRef<T>>;
+    constructor(key: ServiceKey<T>, refs: ReadonlyArray<ActorRef<T>>);
+}
+/** Wire message gossiped between receptionists. */
+export interface ReceptionistGossipMsg {
+    readonly t: 'receptionist-gossip';
+    readonly from: import('../cluster/NodeAddress.js').NodeAddressData;
+    /** key-id → list of actor paths on the sender node */
+    readonly entries: Record<string, string[]>;
+    readonly version: number;
+}
+//# sourceMappingURL=ReceptionistMessages.d.ts.map

package/dist/discovery/ReceptionistMessages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ReceptionistMessages.d.ts","sourceRoot":"","sources":["../../src/discovery/ReceptionistMessages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,+CAA+C;AAC/C,qBAAa,QAAQ,CAAC,CAAC,GAAG,OAAO;aAEb,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;aAClB,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChC,qDAAqD;aACrC,OAAO,EAAE,QAAQ,GAAG,IAAI;gBAHxB,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChC,qDAAqD;IACrC,OAAO,GAAE,QAAQ,GAAG,IAAW;CAElD;AAED,4DAA4D;AAC5D,qBAAa,UAAU,CAAC,CAAC,GAAG,OAAO;aAEf,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;aAClB,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;gBADhB,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;CAEnC;AAED,+BAA+B;AAC/B,qBAAa,UAAU,CAAC,CAAC,GAAG,OAAO;aAEf,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;aAClB,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;gBADhB,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;CAEnC;AAED,6DAA6D;AAC7D,qBAAa,IAAI,CAAC,CAAC,GAAG,OAAO;aAET,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;aAClB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBAD7B,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CAEhD;AAED;;;;GAIG;AACH,qBAAa,SAAS,CAAC,CAAC,GAAG,OAAO;aAEd,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;aAClB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBAD7B,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CAEhD;AAED,gCAAgC;AAChC,qBAAa,WAAW,CAAC,CAAC,GAAG,OAAO;aAEhB,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;aAClB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;gBAD7B,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;CAEhD;AAED;;;;GAIG;AACH,qBAAa,OAAO,CAAC,CAAC,GAAG,OAAO;aAEZ,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;aAClB,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;gBADhC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC,EAClB,IAAI,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;CAEnD;AAED,mDAAmD;AACnD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,CAAC,EAAE,qBAAqB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,OAAO,2BAA2B,EAAE,eAAe,CAAC;IACnE,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B"}

package/dist/discovery/ReceptionistMessages.js

@@ -0,0 +1,76 @@
+/** Register `ref` under `key` on this node. */
+export class Register {
+    key;
+    ref;
+    replyTo;
+    constructor(key, ref, 
+    /** Optional: reply with Registered once accepted. */
+    replyTo = null) {
+        this.key = key;
+        this.ref = ref;
+        this.replyTo = replyTo;
+    }
+}
+/** Ack sent back to the `replyTo` of a Register message. */
+export class Registered {
+    key;
+    ref;
+    constructor(key, ref) {
+        this.key = key;
+        this.ref = ref;
+    }
+}
+/** Remove `ref` from `key`. */
+export class Deregister {
+    key;
+    ref;
+    constructor(key, ref) {
+        this.key = key;
+        this.ref = ref;
+    }
+}
+/** One-shot lookup: reply with Listing once to `replyTo`. */
+export class Find {
+    key;
+    replyTo;
+    constructor(key, replyTo) {
+        this.key = key;
+        this.replyTo = replyTo;
+    }
+}
+/**
+ * Continuous subscription: `replyTo` receives a Listing now AND every time
+ * the set of refs for this key changes (register, deregister, cluster
+ * gossip, node leaving).
+ */
+export class Subscribe {
+    key;
+    replyTo;
+    constructor(key, replyTo) {
+        this.key = key;
+        this.replyTo = replyTo;
+    }
+}
+/** Stop an active Subscribe. */
+export class Unsubscribe {
+    key;
+    replyTo;
+    constructor(key, replyTo) {
+        this.key = key;
+        this.replyTo = replyTo;
+    }
+}
+/**
+ * Reply sent to Find requesters and to every Subscribe subscriber whenever
+ * the current set of registrations for the key changes.  `refs` includes
+ * actors registered on *any* cluster node.
+ */
+export class Listing {
+    key;
+    refs;
+    constructor(key, refs) {
+        this.key = key;
+        this.refs = refs;
+    }
+}
+//# sourceMappingURL=ReceptionistMessages.js.map