actor-ts 0.9.1 → 0.11.0

package/dist/cluster/ClusterBootstrap.js

@@ -1,9 +1,13 @@
 import { ActorSystem } from '../ActorSystem.js';
+import { ActorSystemOptions } from '../ActorSystemOptions.js';
 import { ReceptionistId, } from '../discovery/index.js';
 import { autoDiscovery, singleProviderDiscovery } from '../discovery/autoDiscovery.js';
+import { AutoDiscoveryOptions } from '../discovery/AutoDiscoveryOptions.js';
 import { AggregateSeedProvider } from '../discovery/AggregateSeedProvider.js';
 import { Cluster } from './Cluster.js';
+import { ClusterOptions } from './ClusterOptions.js';
 import { SelfUp } from './ClusterEvents.js';
+import { ClusterBootstrapOptionsValidator } from './ClusterBootstrapOptions.js';
 const DEFAULT_AWAIT_READY_MS = 5_000;
 const DEFAULT_PORT = 2552;
 /**
@@ -13,13 +17,15 @@ const DEFAULT_PORT = 2552;
  * Power users keep `ActorSystem.create()` + `Cluster.join()` for
  * full control.
  *
- * See the {@link ClusterBootstrapOptions} doc for what each field
+ * See the {@link ClusterBootstrapOptionsType} doc for what each field
  * controls and which env vars steer the defaults.
  */
-export async function bootstrapCluster(opts) {
+export async function bootstrapCluster(options) {
+    const opts = options;
+    new ClusterBootstrapOptionsValidator().validate(opts);
     const host = resolveHost(opts);
     const port = resolvePort(opts);
-    const system = ActorSystem.create(opts.name, extractSystemSettings(opts));
+    const system = ActorSystem.create(opts.name, extractSystemOptions(opts));
     const seeds = await resolveSeeds({
         explicit: opts.seeds,
         discovery: opts.discovery,
@@ -28,17 +34,21 @@ export async function bootstrapCluster(opts) {
         selfHost: host,
         log: (msg, err) => system.log.warn(`bootstrap discovery: ${msg}${err ? ` (${err.message ?? err})` : ''}`),
     });
-    const clusterSettings = {
-        host,
-        port,
-        seeds: [...seeds],
-        ...(opts.roles ? { roles: [...opts.roles] } : {}),
-        ...(opts.transport ? { transport: opts.transport } : {}),
-        ...(opts.failureDetector ? { failureDetector: opts.failureDetector } : {}),
-        ...(opts.gossipIntervalMs !== undefined ? { gossipIntervalMs: opts.gossipIntervalMs } : {}),
-        ...(opts.downing ? { downing: opts.downing } : {}),
-    };
-    const cluster = await Cluster.join(system, clusterSettings);
+    const clusterOptions = ClusterOptions.create()
+        .withHost(host)
+        .withPort(port)
+        .withSeeds([...seeds]);
+    if (opts.roles)
+        clusterOptions.withRoles([...opts.roles]);
+    if (opts.transport)
+        clusterOptions.withTransport(opts.transport);
+    if (opts.failureDetector)
+        clusterOptions.withFailureDetector(opts.failureDetector);
+    if (opts.gossipIntervalMs !== undefined)
+        clusterOptions.withGossipIntervalMs(opts.gossipIntervalMs);
+    if (opts.downing)
+        clusterOptions.withDowning(opts.downing);
+    const cluster = await Cluster.join(system, clusterOptions);
     const startReceptionist = opts.receptionist ?? true;
     const receptionist = startReceptionist
         ? system.extension(ReceptionistId).start(cluster)
@@ -86,18 +96,18 @@ function resolvePort(opts) {
     }
     return DEFAULT_PORT;
 }
-function extractSystemSettings(opts) {
-    const out = {};
+function extractSystemOptions(opts) {
+    const out = ActorSystemOptions.create();
     if (opts.logger)
-        out.logger = opts.logger;
+        out.withLogger(opts.logger);
     if (opts.logLevel !== undefined)
-        out.logLevel = opts.logLevel;
+        out.withLogLevel(opts.logLevel);
     if (opts.config !== undefined)
-        out.config = opts.config;
+        out.withConfig(opts.config);
     if (opts.configFile !== undefined)
-        out.configFile = opts.configFile;
+        out.withConfigFile(opts.configFile);
     if (opts.persistence)
-        out.persistence = opts.persistence;
+        out.withPersistence(opts.persistence);
     return out;
 }
 async function resolveSeeds(args) {
@@ -120,10 +130,14 @@ async function resolveSeeds(args) {
         .map((a) => a.toString());
 }
 function buildSeedProvider(spec, base) {
+    const discoveryOptions = AutoDiscoveryOptions.create()
+        .withSystemName(base.systemName)
+        .withPort(base.port)
+        .withLog(base.log);
     if (spec === 'auto')
-        return autoDiscovery(base);
+        return autoDiscovery(discoveryOptions);
     if (spec === 'config' || spec === 'dns' || spec === 'kubernetes') {
-        return singleProviderDiscovery(spec, base);
+        return singleProviderDiscovery(spec, discoveryOptions);
     }
     if ('providers' in spec) {
         return new AggregateSeedProvider([...spec.providers], base.log);

package/dist/cluster/ClusterBootstrap.js.map

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

package/dist/cluster/ClusterBootstrapOptions.d.ts

@@ -0,0 +1,158 @@
+import { OptionsBuilder } from '../util/OptionsBuilder.js';
+import { OptionsValidator } from '../util/OptionsValidator.js';
+import type { ActorSystemOptionsType } from '../ActorSystemOptions.js';
+import type { SeedProvider } from '../discovery/index.js';
+import type { ClusterOptionsType } from './ClusterOptions.js';
+/**
+ * Options accepted by {@link Cluster.bootstrap}.  Everything is
+ * optional except `name`; sensible defaults turn the call into a
+ * single-line hello-cluster.  Build one with {@link ClusterBootstrapOptions}.
+ */
+export interface ClusterBootstrapOptionsType {
+    /** ActorSystem name. */
+    readonly name: string;
+    /** Optional logger / log level / config overrides — forwarded to `ActorSystem.create`. */
+    readonly logger?: ActorSystemOptionsType['logger'];
+    readonly logLevel?: ActorSystemOptionsType['logLevel'];
+    readonly config?: ActorSystemOptionsType['config'];
+    readonly configFile?: ActorSystemOptionsType['configFile'];
+    readonly persistence?: ActorSystemOptionsType['persistence'];
+    /**
+     * Whether the bootstrap helper installs `SIGTERM` + `SIGINT`
+     * handlers that call the returned `shutdown()` once.  Set
+     * to a list of signals to customise, or to `false` to disable.
+     * Default: `['SIGTERM', 'SIGINT']`.
+     */
+    readonly shutdownOnSignals?: boolean | ReadonlyArray<NodeJS.Signals>;
+    /**
+     * Bind host.  Default resolution order:
+     *   1. `opts.host`
+     *   2. `process.env.POD_IP` (Kubernetes)
+     *   3. `process.env.HOSTNAME`
+     *   4. `'0.0.0.0'`
+     */
+    readonly host?: string;
+    /**
+     * Bind port.  Default: `process.env.CLUSTER_PORT` (when present and
+     * a finite integer), otherwise `2552`.
+     */
+    readonly port?: number;
+    /** Transport override.  Default: `TcpTransport`. */
+    readonly transport?: ClusterOptionsType['transport'];
+    /**
+     * Explicit seed list.  When set, `discovery` is ignored and the
+     * cluster contacts exactly these addresses.
+     */
+    readonly seeds?: ReadonlyArray<string>;
+    /**
+     * Discovery strategy.  Values:
+     *
+     *   - `'auto'` (default) — env-driven {@link autoDiscovery} chain.
+     *   - `'kubernetes' | 'dns' | 'config'` — pin to a single provider,
+     *     still configured from env vars.
+     *   - a `SeedProvider` instance — use as-is.
+     *   - `{ providers: [...] }` — assemble a custom aggregate chain.
+     *
+     * Ignored when `seeds` is set.
+     */
+    readonly discovery?: 'auto' | 'kubernetes' | 'dns' | 'config' | SeedProvider | {
+        readonly providers: ReadonlyArray<SeedProvider>;
+    };
+    readonly roles?: ClusterOptionsType['roles'];
+    readonly failureDetector?: ClusterOptionsType['failureDetector'];
+    readonly gossipIntervalMs?: ClusterOptionsType['gossipIntervalMs'];
+    readonly downing?: ClusterOptionsType['downing'];
+    /**
+     * Auto-start the {@link Receptionist} extension so service-key
+     * lookups (`Find`, `Subscribe`) work without explicit wiring.
+     * Default: `true`.
+     */
+    readonly receptionist?: boolean;
+    /**
+     * Wait for this node's `SelfUp` event before resolving.
+     *
+     *   - `true` (default) — wait up to 5 000 ms.
+     *   - `false` / `0`    — return immediately.
+     *   - a number         — wait at most that many ms.
+     *
+     * On timeout the returned promise still resolves — the cluster
+     * keeps trying in the background.  Set a custom value when seed
+     * contact is slow (e.g. K8s pod start lag).
+     */
+    readonly awaitReady?: boolean | number;
+}
+/**
+ * Fluent builder for {@link ClusterBootstrapOptionsType} — the sole input
+ * to {@link Cluster.bootstrap}.  `name` is required; everything else has
+ * a sensible default.  Polymorphic / whole-value fields (`transport`,
+ * `downing`, `discovery`, `failureDetector`, `seeds`, `roles`, the
+ * logger / config / persistence forwards) are passed as-is via a single
+ * `withX(value)`.
+ *
+ *     const { system, cluster, shutdown } = await Cluster.bootstrap(
+ *       ClusterBootstrapOptions.create('my-app').withPort(2552),
+ *     );
+ */
+export declare class ClusterBootstrapOptionsBuilder extends OptionsBuilder<ClusterBootstrapOptionsType> {
+    /**
+     * Start a fresh builder for the given ActorSystem name.  `name` is the
+     * one required field, so it is taken up-front rather than via a
+     * separate `withX`.
+     */
+    static create(name: string): ClusterBootstrapOptionsBuilder;
+    /** Logger forwarded to `ActorSystem.create`. */
+    withLogger(logger: NonNullable<ClusterBootstrapOptionsType['logger']>): this;
+    /** Log level forwarded to `ActorSystem.create`. */
+    withLogLevel(logLevel: NonNullable<ClusterBootstrapOptionsType['logLevel']>): this;
+    /** Inline HOCON / config object forwarded to `ActorSystem.create`. */
+    withConfig(config: NonNullable<ClusterBootstrapOptionsType['config']>): this;
+    /** Config file path forwarded to `ActorSystem.create`. */
+    withConfigFile(configFile: NonNullable<ClusterBootstrapOptionsType['configFile']>): this;
+    /** Persistence options forwarded to `ActorSystem.create`. */
+    withPersistence(persistence: NonNullable<ClusterBootstrapOptionsType['persistence']>): this;
+    /**
+     * Signals that trigger `shutdown()`.  `true` (default) uses
+     * `['SIGTERM','SIGINT']`; pass a list to customise or `false` to
+     * disable.
+     */
+    withShutdownOnSignals(signals: NonNullable<ClusterBootstrapOptionsType['shutdownOnSignals']>): this;
+    /** Bind host.  Defaults resolve via `POD_IP` / `HOSTNAME` / `0.0.0.0`. */
+    withHost(host: string): this;
+    /** Bind port.  Defaults to `CLUSTER_PORT` env or `2552`. */
+    withPort(port: number): this;
+    /** Transport override.  Default: `TcpTransport`. */
+    withTransport(transport: NonNullable<ClusterBootstrapOptionsType['transport']>): this;
+    /** Explicit seed list.  When set, `discovery` is ignored. */
+    withSeeds(seeds: NonNullable<ClusterBootstrapOptionsType['seeds']>): this;
+    /** Discovery strategy — `'auto'`, a named provider, or a custom aggregate. */
+    withDiscovery(discovery: NonNullable<ClusterBootstrapOptionsType['discovery']>): this;
+    /** Role tags exposed to other members. */
+    withRoles(roles: NonNullable<ClusterBootstrapOptionsType['roles']>): this;
+    /** Failure-detector thresholds. */
+    withFailureDetector(failureDetector: NonNullable<ClusterBootstrapOptionsType['failureDetector']>): this;
+    /** How often gossip is pushed to a random reachable peer. */
+    withGossipIntervalMs(ms: number): this;
+    /** Optional split-brain resolver. */
+    withDowning(downing: NonNullable<ClusterBootstrapOptionsType['downing']>): this;
+    /** Auto-start the Receptionist extension.  Default `true`. */
+    withReceptionist(enabled?: boolean): this;
+    /**
+     * Wait for this node's `SelfUp` before resolving — `true` (5 000 ms),
+     * `false`/`0` (immediate), or a millisecond budget.
+     */
+    withAwaitReady(awaitReady: boolean | number): this;
+}
+/** Validates resolved {@link ClusterBootstrapOptionsType} settings. */
+export declare class ClusterBootstrapOptionsValidator extends OptionsValidator<ClusterBootstrapOptionsType> {
+    constructor();
+    protected rules(s: Partial<ClusterBootstrapOptionsType>): void;
+}
+/**
+ * Accepted input for {@link Cluster.bootstrap}: the fluent
+ * {@link ClusterBootstrapOptionsBuilder} OR a plain
+ * {@link ClusterBootstrapOptionsType} object.
+ */
+export type ClusterBootstrapOptions = ClusterBootstrapOptionsBuilder | Partial<ClusterBootstrapOptionsType>;
+/** Value alias so `ClusterBootstrapOptions.create()` / `new ClusterBootstrapOptions()` resolve to the builder. */
+export declare const ClusterBootstrapOptions: typeof ClusterBootstrapOptionsBuilder;
+//# sourceMappingURL=ClusterBootstrapOptions.d.ts.map

package/dist/cluster/ClusterBootstrapOptions.d.ts.map

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

package/dist/cluster/ClusterBootstrapOptions.js

@@ -0,0 +1,121 @@
+import { OptionsBuilder } from '../util/OptionsBuilder.js';
+import { OptionsValidator } from '../util/OptionsValidator.js';
+/**
+ * Fluent builder for {@link ClusterBootstrapOptionsType} — the sole input
+ * to {@link Cluster.bootstrap}.  `name` is required; everything else has
+ * a sensible default.  Polymorphic / whole-value fields (`transport`,
+ * `downing`, `discovery`, `failureDetector`, `seeds`, `roles`, the
+ * logger / config / persistence forwards) are passed as-is via a single
+ * `withX(value)`.
+ *
+ *     const { system, cluster, shutdown } = await Cluster.bootstrap(
+ *       ClusterBootstrapOptions.create('my-app').withPort(2552),
+ *     );
+ */
+export class ClusterBootstrapOptionsBuilder extends OptionsBuilder {
+    /**
+     * Start a fresh builder for the given ActorSystem name.  `name` is the
+     * one required field, so it is taken up-front rather than via a
+     * separate `withX`.
+     */
+    static create(name) {
+        return new ClusterBootstrapOptionsBuilder().set('name', name);
+    }
+    /* ----------------------------- System -------------------------------- */
+    /** Logger forwarded to `ActorSystem.create`. */
+    withLogger(logger) {
+        return this.set('logger', logger);
+    }
+    /** Log level forwarded to `ActorSystem.create`. */
+    withLogLevel(logLevel) {
+        return this.set('logLevel', logLevel);
+    }
+    /** Inline HOCON / config object forwarded to `ActorSystem.create`. */
+    withConfig(config) {
+        return this.set('config', config);
+    }
+    /** Config file path forwarded to `ActorSystem.create`. */
+    withConfigFile(configFile) {
+        return this.set('configFile', configFile);
+    }
+    /** Persistence options forwarded to `ActorSystem.create`. */
+    withPersistence(persistence) {
+        return this.set('persistence', persistence);
+    }
+    /**
+     * Signals that trigger `shutdown()`.  `true` (default) uses
+     * `['SIGTERM','SIGINT']`; pass a list to customise or `false` to
+     * disable.
+     */
+    withShutdownOnSignals(signals) {
+        return this.set('shutdownOnSignals', signals);
+    }
+    /* ----------------------------- Cluster ------------------------------- */
+    /** Bind host.  Defaults resolve via `POD_IP` / `HOSTNAME` / `0.0.0.0`. */
+    withHost(host) {
+        return this.set('host', host);
+    }
+    /** Bind port.  Defaults to `CLUSTER_PORT` env or `2552`. */
+    withPort(port) {
+        return this.set('port', port);
+    }
+    /** Transport override.  Default: `TcpTransport`. */
+    withTransport(transport) {
+        return this.set('transport', transport);
+    }
+    /** Explicit seed list.  When set, `discovery` is ignored. */
+    withSeeds(seeds) {
+        return this.set('seeds', seeds);
+    }
+    /** Discovery strategy — `'auto'`, a named provider, or a custom aggregate. */
+    withDiscovery(discovery) {
+        return this.set('discovery', discovery);
+    }
+    /** Role tags exposed to other members. */
+    withRoles(roles) {
+        return this.set('roles', roles);
+    }
+    /** Failure-detector thresholds. */
+    withFailureDetector(failureDetector) {
+        return this.set('failureDetector', failureDetector);
+    }
+    /** How often gossip is pushed to a random reachable peer. */
+    withGossipIntervalMs(ms) {
+        return this.set('gossipIntervalMs', ms);
+    }
+    /** Optional split-brain resolver. */
+    withDowning(downing) {
+        return this.set('downing', downing);
+    }
+    /** Auto-start the Receptionist extension.  Default `true`. */
+    withReceptionist(enabled = true) {
+        return this.set('receptionist', enabled);
+    }
+    /**
+     * Wait for this node's `SelfUp` before resolving — `true` (5 000 ms),
+     * `false`/`0` (immediate), or a millisecond budget.
+     */
+    withAwaitReady(awaitReady) {
+        return this.set('awaitReady', awaitReady);
+    }
+}
+/** Validates resolved {@link ClusterBootstrapOptionsType} settings. */
+export class ClusterBootstrapOptionsValidator extends OptionsValidator {
+    constructor() {
+        super('ClusterBootstrapOptions');
+    }
+    rules(s) {
+        this.nonEmptyString('name');
+        // Positive integer (not the TCP 1..65535 range) — the bootstrap port may
+        // be a synthetic InMemoryTransport node id, same as ClusterOptions.port.
+        this.positiveInt('port');
+        this.positiveNumber('gossipIntervalMs');
+        // awaitReady is boolean | number(ms); a numeric budget must be >= 0 (0 = immediate).
+        if (typeof s.awaitReady === 'number' && (!Number.isFinite(s.awaitReady) || s.awaitReady < 0)) {
+            this.fail('awaitReady', 'must be a boolean or a non-negative number of ms', s.awaitReady);
+        }
+    }
+}
+/** Value alias so `ClusterBootstrapOptions.create()` / `new ClusterBootstrapOptions()` resolve to the builder. */
+export const ClusterBootstrapOptions = ClusterBootstrapOptionsBuilder;
+//# sourceMappingURL=ClusterBootstrapOptions.js.map

package/dist/cluster/ClusterBootstrapOptions.js.map

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

package/dist/cluster/ClusterClient.d.ts

@@ -36,42 +36,30 @@
  * `cluster-client-reply` frames.  Reusing the wire layer means we
  * inherit framing, ordering, and TLS for free.
  */
-import { type TlsTransportSettings } from '../runtime/tcp/index.js';
-import { type Logger } from '../Logger.js';
 import { NodeAddress } from './NodeAddress.js';
-export interface ClusterClientSettings {
-    /**
-     * Cluster nodes to dial.  Each is a `host:port` or `<system>@host:port`
-     * string — the same shape `Cluster.join` accepts for seeds.  Tried in
-     * order; on dial failure the next is attempted.
-     */
-    readonly contactPoints: ReadonlyArray<string>;
-    /** Synthetic system name embedded in the client's hello.  Default: 'cluster-client'. */
-    readonly systemName?: string;
-    /**
-     * Host + port the client claims as its identity.  The cluster uses this
-     * to route `cluster-client-reply` frames back over the right connection.
-     * Use a host:port that uniquely identifies this client instance — random
-     * defaults are fine because the cluster only needs it for connection
-     * routing, not for actual networking back to the client.
-     */
-    readonly clientIdentity?: {
-        readonly host: string;
-        readonly port: number;
-    };
-    /** Default ask timeout (ms).  Default: 5_000. */
-    readonly askTimeoutMs?: number;
-    /** Optional TLS config — must match the cluster's. */
-    readonly tls?: TlsTransportSettings;
-    /** Custom logger; default: ConsoleLogger at WARN. */
-    readonly log?: Logger;
-}
+import type { ClusterClientOptions } from './ClusterClientOptions.js';
+/**
+ * Generate an unpredictable ask ID.  Used by `ClusterClient.ask()` to
+ * route a `cluster-client-reply` frame back to the right pending
+ * promise.
+ *
+ * **Security note (#120)**: previously this was `c${Date.now()}-${counter}`,
+ * which an attacker on the wire (MitM on plaintext, malicious cluster
+ * peer, or someone with frame-level write access via TLS-stripping
+ * proxy) could predict and use to inject a forged reply BEFORE the
+ * legitimate one arrives.  `crypto.randomUUID()` gives 122 bits of
+ * entropy per call — guessing the next ID is computationally
+ * infeasible.  Frame replies whose ID doesn't match a current
+ * pending entry are dropped by `handleReply()` (existing behaviour).
+ */
+declare function nextAskId(): string;
+/** @internal — test-only handle for the predictability regression. */
+export declare const _nextAskIdForTest: typeof nextAskId;
 /**
  * Connect to a cluster via one of the listed contact-points and exchange
  * messages with actors on the cluster.  See the file header for scope.
  */
 export declare class ClusterClient {
-    private readonly settings;
     private readonly contactPoints;
     private readonly identity;
     private readonly tls;
@@ -85,7 +73,8 @@ export declare class ClusterClient {
     private stopped;
     /** Filled by `hello-ack`; the contact-point's real address (post-handshake). */
     private contactPointPeer;
-    constructor(settings: ClusterClientSettings);
+    private readonly options;
+    constructor(options: ClusterClientOptions);
     /** The synthetic identity this client uses in its `hello` handshake. */
     get clientAddress(): NodeAddress;
     /**
@@ -109,4 +98,5 @@ export declare class ClusterClient {
     private onSocketClose;
     private writeFrame;
 }
+export {};
 //# sourceMappingURL=ClusterClient.d.ts.map

package/dist/cluster/ClusterClient.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClusterClient.d.ts","sourceRoot":"","sources":["../../src/cluster/ClusterClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAqC,KAAK,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACvG,OAAO,EAA2B,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAEpE,OAAO,EAAE,WAAW,EAAwB,MAAM,kBAAkB,CAAC;AAOrE,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,wFAAwF;IACxF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC3E,iDAAiD;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,GAAG,CAAC,EAAE,oBAAoB,CAAC;IACpC,qDAAqD;IACrD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAgBD;;;GAGG;AACH,qBAAa,aAAa;IAeZ,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAdrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA8B;IAClD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,OAAO,CAAS;IACxB,gFAAgF;IAChF,OAAO,CAAC,gBAAgB,CAA4B;gBAEvB,QAAQ,EAAE,qBAAqB;IAsB5D,wEAAwE;IACxE,IAAI,aAAa,IAAI,WAAW,CAA0B;IAE1D;;;;OAIG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/D;;;;OAIG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC;IAwBb,yCAAyC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAed,eAAe;YAYf,OAAO;IAiErB,OAAO,CAAC,MAAM;IAsBd,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,UAAU;CAMnB"}
+{"version":3,"file":"ClusterClient.d.ts","sourceRoot":"","sources":["../../src/cluster/ClusterClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,OAAO,EAAE,WAAW,EAAwB,MAAM,kBAAkB,CAAC;AAOrE,OAAO,KAAK,EAAE,oBAAoB,EAA4B,MAAM,2BAA2B,CAAC;AAUhG;;;;;;;;;;;;;GAaG;AACH,iBAAS,SAAS,IAAI,MAAM,CAE3B;AAED,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,kBAAY,CAAC;AAE3C;;;GAGG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA6B;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiC;IACrD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,iBAAiB,CAA8B;IACvD,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,OAAO,CAAS;IACxB,gFAAgF;IAChF,OAAO,CAAC,gBAAgB,CAA4B;IAEpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;gBAEvC,OAAO,EAAE,oBAAoB;IAsBzC,wEAAwE;IACxE,IAAI,aAAa,IAAI,WAAW,CAA0B;IAE1D;;;;OAIG;IACG,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAW/D;;;;OAIG;IACG,GAAG,CAAC,CAAC,GAAG,OAAO,EACnB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,CAAC,CAAC;IAwBb,yCAAyC;IACnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAed,eAAe;YAYf,OAAO;IAiErB,OAAO,CAAC,MAAM;IAsBd,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,UAAU;CAMnB"}

package/dist/cluster/ClusterClient.js

@@ -41,18 +41,32 @@ import { ConsoleLogger, LogLevel } from '../Logger.js';
 import { DEFAULT_ASK_TIMEOUT_MS } from '../util/Constants.js';
 import { NodeAddress } from './NodeAddress.js';
 import { encodeFrame, FrameDecoder } from './Protocol.js';
+import { ClusterClientOptionsValidator } from './ClusterClientOptions.js';
 const HELLO_TIMEOUT_MS = 5_000;
-let _askCounter = 0;
+/**
+ * Generate an unpredictable ask ID.  Used by `ClusterClient.ask()` to
+ * route a `cluster-client-reply` frame back to the right pending
+ * promise.
+ *
+ * **Security note (#120)**: previously this was `c${Date.now()}-${counter}`,
+ * which an attacker on the wire (MitM on plaintext, malicious cluster
+ * peer, or someone with frame-level write access via TLS-stripping
+ * proxy) could predict and use to inject a forged reply BEFORE the
+ * legitimate one arrives.  `crypto.randomUUID()` gives 122 bits of
+ * entropy per call — guessing the next ID is computationally
+ * infeasible.  Frame replies whose ID doesn't match a current
+ * pending entry are dropped by `handleReply()` (existing behaviour).
+ */
 function nextAskId() {
-    _askCounter = (_askCounter + 1) >>> 0;
-    return `c${Date.now()}-${_askCounter}`;
+    return globalThis.crypto.randomUUID();
 }
+/** @internal — test-only handle for the predictability regression. */
+export const _nextAskIdForTest = nextAskId;
 /**
  * Connect to a cluster via one of the listed contact-points and exchange
  * messages with actors on the cluster.  See the file header for scope.
  */
 export class ClusterClient {
-    settings;
     contactPoints;
     identity;
     tls;
@@ -66,17 +80,17 @@ export class ClusterClient {
     stopped = false;
     /** Filled by `hello-ack`; the contact-point's real address (post-handshake). */
     contactPointPeer = null;
-    constructor(settings) {
-        this.settings = settings;
-        if (!settings.contactPoints || settings.contactPoints.length === 0) {
-            throw new Error('ClusterClient: contactPoints must contain at least one entry');
-        }
-        const sysName = settings.systemName ?? 'cluster-client';
-        this.contactPoints = settings.contactPoints.map((s) => {
+    options;
+    constructor(options) {
+        const resolvedOptions = options;
+        this.options = resolvedOptions;
+        new ClusterClientOptionsValidator().validate(resolvedOptions);
+        const sysName = resolvedOptions.systemName ?? 'cluster-client';
+        this.contactPoints = resolvedOptions.contactPoints.map((s) => {
             const withSys = s.includes('@') ? s : `${sysName}@${s}`;
             return NodeAddress.parse(withSys);
         });
-        const id = settings.clientIdentity ?? {
+        const id = resolvedOptions.clientIdentity ?? {
             host: '127.0.0.1',
             // Synthetic port — must be unique per ClusterClient instance in the
             // same process so the cluster's byPeer map doesn't collide.  Use
@@ -84,9 +98,9 @@ export class ClusterClient {
             port: 50_000 + Math.floor(Math.random() * 15_000),
         };
         this.identity = new NodeAddress(sysName, id.host, id.port);
-        this.tls = settings.tls ?? null;
-        this.askTimeoutMs = settings.askTimeoutMs ?? DEFAULT_ASK_TIMEOUT_MS;
-        this.log = settings.log ?? new ConsoleLogger(LogLevel.Warn, 'cluster-client');
+        this.tls = resolvedOptions.tls ?? null;
+        this.askTimeoutMs = resolvedOptions.askTimeoutMs ?? DEFAULT_ASK_TIMEOUT_MS;
+        this.log = resolvedOptions.logger ?? new ConsoleLogger(LogLevel.Warn, 'cluster-client');
     }
     /** The synthetic identity this client uses in its `hello` handshake. */
     get clientAddress() { return this.identity; }
@@ -228,20 +242,20 @@ export class ClusterClient {
         throw new Error(`ClusterClient: failed to connect to any of ${this.contactPoints.length} `
             + `contact-point(s).  Errors: ${errors.map((e) => e.message).join('; ')}`);
     }
-    onData(sock, chunk, onHelloAck) {
+    onData(sock, chunk, onHelloAcknowledgment) {
         const frames = this.decoder.push(chunk);
         for (const frame of frames) {
             if (frame.t === 'hello-ack') {
                 const ack = frame;
-                onHelloAck(NodeAddress.fromJSON(ack.self));
+                onHelloAcknowledgment(NodeAddress.fromJSON(ack.self));
                 continue;
             }
-            const t = frame.t;
-            if (t === 'cluster-client-reply') {
+            const frameType = frame.t;
+            if (frameType === 'cluster-client-reply') {
                 this.handleReply(frame);
                 continue;
             }
-            this.log.debug(`ClusterClient: ignoring unsolicited frame type "${t}"`);
+            this.log.debug(`ClusterClient: ignoring unsolicited frame type "${frameType}"`);
         }
         void sock;
     }