@zapo-js/fake-server 1.0.0 → 1.1.0

package/dist/api/FakeWaServer.d.ts

@@ -1,47 +1,65 @@
 import { Agent as HttpsAgent } from 'node:https';
 import { type WaFakeAuthenticatedInfo, WaFakeConnectionPipeline } from '../infra/WaFakeConnectionPipeline';
+import type { ParsedClientPayload } from '../protocol/auth/client-payload-validate';
+import type { BuildSuccessNodeInput } from '../protocol/auth/success-node';
 import type { BuildAbPropsResultInput } from '../protocol/iq/abprops';
 import { type BuildServerSyncNotificationInput, type FakeAppStateCollectionPayload } from '../protocol/iq/appstate-sync';
 import type { FakeBusinessProfile } from '../protocol/iq/business';
 import type { FakePrivacyCategoryName, FakePrivacySettingsState } from '../protocol/iq/privacy';
 import type { FakePrivacyTokenIssue } from '../protocol/iq/privacy-token';
 import type { FakeProfilePictureResult } from '../protocol/iq/profile';
-import { type WaFakeIqMatcher, type WaFakeIqResponder } from '../protocol/iq/router';
+import type { WaFakeIqMatcher, WaFakeIqResponder } from '../protocol/iq/router';
 import type { ClientPreKeyBundle } from '../protocol/signal/prekey-upload';
 import { type PublishedMediaBlob, type PublishMediaInput } from '../state/fake-media-store';
 import { type BinaryNode } from '../transport/codec';
-import { AppStateSyncManager, type CapturedAppStateMutation } from './AppStateSyncManager';
+import { type AppStateSyncManager, type CapturedAppStateMutation } from './AppStateSyncManager';
 import { type FakePairingDriverOptions } from './FakePairingDriver';
 import { type CreateFakePeerOptions, FakePeer } from './FakePeer';
-import { PreKeyDispenser } from './PreKeyDispenser';
+import { type ExpectIqOptions, type ExpectStanzaOptions, FakeServerSession, type StanzaMatcher } from './FakeServerSession';
+import type { PreKeyDispenser } from './PreKeyDispenser';
 import { type AuthenticatedPipelineListener, Scenario } from './Scenario';
-import { type CapturedBlocklistChange, type CapturedDirtyBitsClear, type CapturedGroupOp, type CapturedPrivacySet, type CapturedProfilePictureSet, type CapturedStatusSet, type FakeGroupMetadata, ServerRegistries } from './ServerRegistries';
+import type { CapturedBlocklistChange, CapturedDirtyBitsClear, CapturedGroupOp, CapturedPrivacySet, CapturedProfilePictureSet, CapturedStatusSet, FakeGroupMetadata, ServerRegistries } from './ServerRegistries';
 export type { FakeGroupMetadata, CapturedGroupOp, CapturedPrivacySet, CapturedBlocklistChange, CapturedProfilePictureSet, CapturedStatusSet, CapturedDirtyBitsClear } from './ServerRegistries';
 export type { CapturedAppStateMutation } from './AppStateSyncManager';
 export interface FakeWaServerOptions {
     readonly host?: string;
     readonly port?: number;
     readonly path?: string;
+    /**
+     * Attributes stamped on the post-handshake `<success/>` node of every
+     * authenticated connection (lid, display name, props versions, ...).
+     */
+    readonly successNodeAttributes?: BuildSuccessNodeInput;
+    /**
+     * Register the built-in IQ auto-handlers that answer everything the lib
+     * emits during normal operation. Default `true`; pass `false` to start
+     * with an empty router and wire every response via `registerIqHandler`.
+     */
+    readonly defaultIqHandlers?: boolean;
+    /**
+     * Assigns each authenticated connection to an isolated session, keyed by
+     * the returned id. Two connections that resolve to different ids share no
+     * peers, groups, prekeys, app-state, or captured stanzas. When omitted,
+     * every connection uses one shared default session (single-client mode).
+     *
+     * The resolver runs once per connection, right after authentication, so
+     * `info.clientPayload` is available for keying by login identity, e.g.
+     * `sessionKey: ({ clientPayload }) => clientPayload.kind === 'login' ?
+     * clientPayload.username : 'pending'`.
+     */
+    readonly sessionKey?: (info: FakeSessionKeyInfo) => string;
+}
+export interface FakeSessionKeyInfo {
+    readonly clientPayload: ParsedClientPayload;
+    readonly pipeline: WaFakeConnectionPipeline;
 }
 export interface FakeWaServerNoiseRootCa {
     readonly publicKey: Uint8Array;
     readonly serial: number;
 }
 export type FakeWaServerPipelineListener = (pipeline: WaFakeConnectionPipeline) => void;
-export interface ExpectIqOptions {
-    readonly timeoutMs?: number;
-}
-export interface ExpectStanzaOptions {
-    readonly timeoutMs?: number;
-}
-export interface StanzaMatcher {
-    readonly tag?: string;
-    readonly type?: string;
-    readonly xmlns?: string;
-    readonly from?: string;
-    readonly to?: string;
-    readonly childTag?: string;
-}
+export { FakeServerSession } from './FakeServerSession';
+export type { ExpectIqOptions, ExpectStanzaOptions, StanzaMatcher } from './FakeServerSession';
 export interface CapturedMediaUpload {
     readonly path: string;
     readonly mediaType: string;
@@ -51,22 +69,18 @@ export interface CapturedMediaUpload {
     readonly receivedAtMs: number;
 }
 export declare class FakeWaServer {
-    readonly registries: ServerRegistries;
-    readonly preKeyDispenser: PreKeyDispenser;
-    readonly appStateSync: AppStateSyncManager;
     private readonly wsServer;
     private readonly pipelines;
-    private readonly iqRouter;
-    private readonly capturedStanzas;
-    private readonly pendingIqExpectations;
-    private readonly pendingStanzaExpectations;
+    private readonly defaultSession;
+    private readonly pipelineSessions;
     private readonly authenticatedListeners;
-    private readonly inboundStanzaListeners;
-    private readonly capturedStanzaListeners;
+    private readonly sessions;
+    private readonly globalIqHandlers;
+    private readonly options;
     private rootCa;
     private serverStaticKeyPair;
     private listenInfo;
-    private pipelineListener;
+    private readonly pipelineListeners;
     private rejectMode;
     private readonly mediaStore;
     private readonly mediaHttpsServer;
@@ -74,7 +88,20 @@ export declare class FakeWaServer {
     private nextUploadCounter;
     private cachedMediaProxyAgent;
     constructor(options?: FakeWaServerOptions);
-    private buildIqHandlerDeps;
+    /** State of the single default session (the only session for one client). */
+    get registries(): ServerRegistries;
+    get preKeyDispenser(): PreKeyDispenser;
+    get appStateSync(): AppStateSyncManager;
+    /**
+     * Returns the isolated session for `id`, creating it on first use. Every
+     * session gets its own registries, prekey dispenser, app-state, IQ router,
+     * and stanza capture. Use with the `sessionKey` option to run several
+     * `WaClient`s against one server without them sharing any state.
+     */
+    session(id: string): FakeServerSession;
+    /** The session a connection is bound to (default before authentication). */
+    sessionFor(pipeline: WaFakeConnectionPipeline): FakeServerSession;
+    private createSession;
     registerIqHandler(matcher: WaFakeIqMatcher, respond: WaFakeIqResponder, label?: string): () => void;
     routeIqForTest(iq: BinaryNode): Promise<BinaryNode | null>;
     onOutboundGroupOp(listener: (op: CapturedGroupOp) => void): () => void;
@@ -124,13 +151,12 @@ export declare class FakeWaServer {
     expectIq(matcher: WaFakeIqMatcher, options?: ExpectIqOptions): Promise<BinaryNode>;
     capturedStanzaSnapshot(): readonly BinaryNode[];
     /**
-     * Subscribes to every stanza captured from the client side (the lib).
-     * The listener is called synchronously for each new stanza as it
-     * arrives, in addition to `capturedStanzas` being appended. Returns
-     * an unsubscribe function. Useful for benches that need to count or
-     * react to a stream of receipts/messages without paying the O(N²)
-     * cost of polling `capturedStanzaSnapshot()` or queuing one
-     * `expectStanza(...)` per iteration.
+     * Subscribes to every stanza captured from the client side (the lib) of
+     * the default session. The listener is called synchronously for each new
+     * stanza as it arrives. Returns an unsubscribe function. Useful for
+     * benches that need to count or react to a stream of receipts/messages
+     * without paying the O(N²) cost of polling `capturedStanzaSnapshot()` or
+     * queuing one `expectStanza(...)` per iteration.
      */
     onCapturedStanza(listener: (node: BinaryNode) => void): () => void;
     expectStanza(matcher: StanzaMatcher, options?: ExpectStanzaOptions): Promise<BinaryNode>;
@@ -163,11 +189,21 @@ export declare class FakeWaServer {
     get host(): string;
     get port(): number;
     get noiseRootCa(): FakeWaServerNoiseRootCa;
-    onPipeline(listener: FakeWaServerPipelineListener): void;
+    /**
+     * Subscribes to every new connection pipeline (pre-auth). Listeners
+     * fan out; returns an unsubscribe function.
+     */
+    onPipeline(listener: FakeWaServerPipelineListener): () => void;
     listen(): Promise<void>;
     stop(): Promise<void>;
     private handleConnection;
-    private handleCapturedStanza;
+    /**
+     * Rebinds a connection to its keyed session once authenticated. Runs
+     * before user `onAuthenticated` listeners and before any client stanza, so
+     * captures and IQ routing land in the right session from the first frame.
+     * No-op without a `sessionKey` resolver (single default session).
+     */
+    private bindPipelineSession;
     private buildMediaRequestHandler;
     private handleMediaUpload;
     private requireListening;