@oxidezap/baileyrs 0.0.32 → 0.1.0

package/lib/Compatibility/websocket-client.js

@@ -7,8 +7,13 @@ export const isRawNodeForwardingEnabled = (client) => client.hasRawNodeListeners
 export class WebSocketClient extends EventEmitter {
     constructor(url, config, getClient) {
         super();
-        this.closing = false;
-        this.closed = false;
+        /**
+         * One value rather than a pair of booleans plus a promise that could
+         * disagree with them. `closing` carries the in-flight close so a second
+         * caller joins it instead of returning while the first `disconnect()` is
+         * still running — which is how teardown reached `free()` on a busy client.
+         */
+        this.closeState = { phase: 'open' };
         this.listenerMutationDepth = 0;
         this.url = url instanceof URL ? url : new URL(url);
         this.config = config;
@@ -24,13 +29,13 @@ export class WebSocketClient extends EventEmitter {
         return this.getClient()?.isConnected() ?? false;
     }
     get isClosed() {
-        return this.closed;
+        return this.closeState.phase === 'closed';
     }
     get isClosing() {
-        return this.closing;
+        return this.closeState.phase === 'closing';
     }
     get isConnecting() {
-        return !this.isOpen && !this.closing && !this.closed;
+        return !this.isOpen && this.closeState.phase === 'open';
     }
     get hasRawNodeListeners() {
         return this.eventNames().some(eventName => isRawNodeEventName(eventName));
@@ -84,20 +89,44 @@ export class WebSocketClient extends EventEmitter {
         const client = this.getClient();
         if (!client || client.isConnected())
             return;
-        this.closed = false;
+        // A close in flight has already told the client to disconnect, which is
+        // exactly what makes `isConnected()` false above. Reopening here would
+        // clear the `closing` phase, and the next `close()` would start a second
+        // disconnect against the same client while the first is still running.
+        if (this.closeState.phase === 'closing')
+            return;
+        this.closeState = { phase: 'open' };
         void client.connect().catch(error => this.emit('error', error));
     }
+    /**
+     * Idempotent, and a second caller joins the first rather than returning
+     * while it is still going.
+     *
+     * The early return used to be bare: `void ws.close(); await sock.end()` saw
+     * the flag, returned immediately, and let teardown reach `free()` with the
+     * original `disconnect()` still in flight — the wasm heap corruption
+     * `bridge-free-safety.test.ts` documents. Awaiting a *second* `disconnect()`
+     * does not join the first one.
+     *
+     * The state is stored before `disconnect()` is called, and the work is
+     * deferred by a microtask to make that ordering hold: an inline async body
+     * runs eagerly to its first `await`, so `disconnect()` would be invoked
+     * while the state still said `open`, and anything it reaches synchronously
+     * that calls back into `close()` would issue a second one.
+     */
     async close() {
-        if (this.closing || this.closed)
-            return;
-        this.closing = true;
-        try {
-            await this.getClient()?.disconnect();
-        }
-        finally {
-            this.closing = false;
-            this.closed = true;
-        }
+        if (this.closeState.phase !== 'open')
+            return this.closeState.done;
+        const done = Promise.resolve().then(async () => {
+            try {
+                await this.getClient()?.disconnect();
+            }
+            finally {
+                this.closeState = { phase: 'closed', done };
+            }
+        });
+        this.closeState = { phase: 'closing', done };
+        return done;
     }
     send(str, cb) {
         const client = this.getClient();
@@ -110,9 +139,9 @@ export class WebSocketClient extends EventEmitter {
     get readyState() {
         if (this.isOpen)
             return 1;
-        if (this.closing)
+        if (this.closeState.phase === 'closing')
             return 2;
-        if (this.closed)
+        if (this.closeState.phase === 'closed')
             return 3;
         return 0;
     }

package/lib/Socket/bridge-client-owner.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Owns the bridge client's lifetime.
+ *
+ * The socket's startup is async and its teardown can start at any point during
+ * it — a `sock.end()` right after `makeWASocket()`, an `await using` scope
+ * exiting, or a terminal disconnect the dispatcher reports while `init()` is
+ * still building the client. That window used to be managed by hand across six
+ * closure variables and a scattering of `if (ended) return` checks, which is
+ * where every teardown bug in this file came from: startup dereferencing a
+ * handle teardown had already nulled, a client built after teardown with
+ * nobody left to free it, an `end()` that resolved for its second caller while
+ * the first was still flushing, and a re-entrant close releasing the same wasm
+ * handle twice.
+ *
+ * All of those are one question — *what phase is this client in?* — so it is
+ * one discriminated union rather than a set of booleans that can disagree:
+ *
+ * ```
+ *   starting ──adopt()──► running ──close()──► closing ──► closed
+ *      │                     │                    ▲
+ *      └──────close()────────┴──discard()─────────┘
+ * ```
+ *
+ * Two rules make the whole thing safe, and both are properties of the union
+ * rather than of any individual method:
+ *
+ *  - **The transition is synchronous and happens first.** `close()` publishes
+ *    `closing` — carrying the promise callers await — before any teardown work
+ *    starts, so re-entering it finds an in-flight close instead of starting a
+ *    second one. That is why the work is deferred by a microtask rather than
+ *    started inline: an async body would otherwise run eagerly to its first
+ *    `await`, i.e. before the state was stored.
+ *  - **`closing` still carries the client.** The socket's transport close
+ *    reads it back through `peek()` (`ws.close()` is `getClient()?.disconnect()`),
+ *    so dropping the handle at the start of teardown silently turns that into
+ *    a no-op and moves the disconnect after the auth-store flush. `isClosing()`
+ *    — not `peek()` — is the "should I still be doing work" signal.
+ */
+import type { WasmWhatsAppClient } from '@oxidezap/whatsapp-rust-bridge';
+import type { ILogger } from '../Utils/logger.js';
+export interface BridgeClientOwnerOptions {
+    logger: ILogger;
+    /**
+     * The socket's own shutdown work. Receives the adopted client, if there is
+     * one, while it is still usable, and the error teardown was started with.
+     *
+     * Runs once. Throwing propagates to `close()`'s callers; the client is
+     * released either way.
+     */
+    teardown: (client: WasmWhatsAppClient | undefined, error: Error | undefined) => Promise<void>;
+    /**
+     * Hand the client back to the bridge. Separate from `teardown` because
+     * ordering matters and the two have different failure semantics: this one
+     * is best-effort and never throws out.
+     */
+    release: (client: WasmWhatsAppClient) => Promise<void>;
+}
+export interface BridgeClientOwner {
+    /** The client while `running` or `closing`; undefined before and after. */
+    peek: () => WasmWhatsAppClient | undefined;
+    /**
+     * Publish a freshly built client. Returns `false` when teardown has already
+     * started — the client is released here and the caller must stop, because
+     * nothing else will ever own it.
+     */
+    adopt: (client: WasmWhatsAppClient) => boolean;
+    /** True from the moment `close()` is called. Startup checks it between awaits. */
+    isClosing: () => boolean;
+    /** Runs teardown once; later callers await that same run. */
+    close: (error: Error | undefined) => Promise<void>;
+    /**
+     * Drop the client without tearing the socket down — for a startup that
+     * failed after adopting, where the client exists but its read loop never
+     * started. Joins an in-flight close rather than releasing a client that
+     * close already owns.
+     */
+    discard: () => Promise<void>;
+    /**
+     * Resolves once every release this owner started has finished, including
+     * the one a refused `adopt()` kicks off. Startup awaits it on the way out
+     * so its own promise does not settle with a release still in flight.
+     *
+     * A release can outlive the set it started in, so this drains rather than
+     * awaiting one snapshot.
+     */
+    settled: () => Promise<void>;
+}
+export declare const makeBridgeClientOwner: (opts: BridgeClientOwnerOptions) => BridgeClientOwner;
+//# sourceMappingURL=bridge-client-owner.d.ts.map

package/lib/Socket/bridge-client-owner.js

@@ -0,0 +1,135 @@
+/**
+ * Owns the bridge client's lifetime.
+ *
+ * The socket's startup is async and its teardown can start at any point during
+ * it — a `sock.end()` right after `makeWASocket()`, an `await using` scope
+ * exiting, or a terminal disconnect the dispatcher reports while `init()` is
+ * still building the client. That window used to be managed by hand across six
+ * closure variables and a scattering of `if (ended) return` checks, which is
+ * where every teardown bug in this file came from: startup dereferencing a
+ * handle teardown had already nulled, a client built after teardown with
+ * nobody left to free it, an `end()` that resolved for its second caller while
+ * the first was still flushing, and a re-entrant close releasing the same wasm
+ * handle twice.
+ *
+ * All of those are one question — *what phase is this client in?* — so it is
+ * one discriminated union rather than a set of booleans that can disagree:
+ *
+ * ```
+ *   starting ──adopt()──► running ──close()──► closing ──► closed
+ *      │                     │                    ▲
+ *      └──────close()────────┴──discard()─────────┘
+ * ```
+ *
+ * Two rules make the whole thing safe, and both are properties of the union
+ * rather than of any individual method:
+ *
+ *  - **The transition is synchronous and happens first.** `close()` publishes
+ *    `closing` — carrying the promise callers await — before any teardown work
+ *    starts, so re-entering it finds an in-flight close instead of starting a
+ *    second one. That is why the work is deferred by a microtask rather than
+ *    started inline: an async body would otherwise run eagerly to its first
+ *    `await`, i.e. before the state was stored.
+ *  - **`closing` still carries the client.** The socket's transport close
+ *    reads it back through `peek()` (`ws.close()` is `getClient()?.disconnect()`),
+ *    so dropping the handle at the start of teardown silently turns that into
+ *    a no-op and moves the disconnect after the auth-store flush. `isClosing()`
+ *    — not `peek()` — is the "should I still be doing work" signal.
+ */
+export const makeBridgeClientOwner = (opts) => {
+    const { logger, teardown, release } = opts;
+    let state = { phase: 'starting' };
+    /** Releases started outside `close()`, so `settled()` can join them. */
+    const pendingReleases = new Set();
+    const releaseQuietly = async (target) => {
+        try {
+            await release(target);
+        }
+        catch (err) {
+            logger.error({ err }, 'failed to release the bridge client');
+        }
+    };
+    /** `releaseQuietly`, but joinable through `settled()`. */
+    const trackRelease = (target) => {
+        const running = releaseQuietly(target).finally(() => pendingReleases.delete(running));
+        pendingReleases.add(running);
+        return running;
+    };
+    /** Drain releases started outside this close — see `runClose`. */
+    const drainReleases = async () => {
+        while (pendingReleases.size)
+            await Promise.all(pendingReleases);
+    };
+    const runClose = async (client, error, done) => {
+        try {
+            await teardown(client, error);
+        }
+        finally {
+            state = { phase: 'closed', done };
+            if (client)
+                await releaseQuietly(client);
+            // A `discard()` in flight when this close started put the client
+            // back in `starting`, so the capture above found none and teardown
+            // ran without it. Its release is still going: joining here keeps
+            // `close()` from settling while a client is being disconnected and
+            // freed, which is what the caller is told it can rely on.
+            await drainReleases();
+        }
+    };
+    return {
+        peek: () => (state.phase === 'running' || state.phase === 'closing' ? state.client : undefined),
+        adopt: candidate => {
+            if (state.phase !== 'starting') {
+                // Teardown has already been through here and found nothing, so
+                // this client would have no owner: nothing would free it and its
+                // read loop would reconnect forever against a disposed socket.
+                void trackRelease(candidate);
+                return false;
+            }
+            state = { phase: 'running', client: candidate };
+            return true;
+        },
+        isClosing: () => state.phase === 'closing' || state.phase === 'closed',
+        close: error => {
+            if (state.phase === 'closing' || state.phase === 'closed') {
+                logger.trace({ trace: error?.stack }, 'already closing; awaiting the in-flight teardown');
+                return state.done;
+            }
+            const client = state.phase === 'running' ? state.client : undefined;
+            // Deferred by a microtask so the `closing` state below is stored
+            // before any teardown work runs. Calling `runClose` inline would
+            // execute its body eagerly up to the first `await` — teardown starts
+            // by closing the transport — and anything reached synchronously that
+            // calls back into `close()` would find no in-flight close and start
+            // a second teardown, releasing the same wasm handle twice.
+            const done = Promise.resolve().then(() => runClose(client, error, done));
+            state = { phase: 'closing', client, done };
+            return done;
+        },
+        discard: async () => {
+            // `close()` owns the client from the moment it starts, and keeps it
+            // published for the whole of teardown — releasing it here as well
+            // would be two disconnect/free sequences on one handle. Join instead.
+            //
+            // Joining without adopting the failure: `close()` rejects when
+            // teardown rethrows the first auth-store flush error, and this is
+            // best-effort cleanup called from `init()`'s catch. Propagating it
+            // would make `initPromise` reject — which the socket documents as
+            // impossible, relies on for `getClient()`'s error message, and does
+            // not always await, so it could surface as an unhandled rejection.
+            if (state.phase === 'closing' || state.phase === 'closed') {
+                await state.done.catch(() => { });
+                return;
+            }
+            if (state.phase !== 'running')
+                return;
+            const { client } = state;
+            // Back to `starting`, not `closed`: a later `close()` must still run
+            // teardown for everything the socket owns beyond the client.
+            state = { phase: 'starting' };
+            await trackRelease(client);
+        },
+        settled: drainReleases
+    };
+};
+//# sourceMappingURL=bridge-client-owner.js.map

package/lib/Socket/communities.d.ts

@@ -20,7 +20,7 @@ export declare const makeCommunityMethods: (ctx: SocketContext, groups?: {
     groupRevokeInvite: (jid: string) => Promise<string | undefined>;
     groupAcceptInvite: (code: string) => Promise<string | undefined>;
     groupRevokeInviteV4: (groupJid: string, invitedJid: string) => Promise<boolean>;
-    groupAcceptInviteV4: (key: string | import("../index.js").WAMessageKey, inviteMessage: import("whatsapp-rust-bridge/proto-types").proto.Message.IGroupInviteMessage) => Promise<any>;
+    groupAcceptInviteV4: (key: string | import("../index.js").WAMessageKey, inviteMessage: import("@oxidezap/whatsapp-rust-bridge/proto-types").proto.Message.IGroupInviteMessage) => Promise<any>;
     groupGetInviteInfo: (code: string) => Promise<GroupMetadata>;
     groupToggleEphemeral: (jid: string, ephemeralExpiration: number) => Promise<void>;
     groupSettingUpdate: (jid: string, setting: "announcement" | "locked" | "not_announcement" | "unlocked") => Promise<void>;
@@ -49,7 +49,7 @@ export declare const makeCommunityMethods: (ctx: SocketContext, groups?: {
     communityRevokeInvite: (jid: string) => Promise<string | undefined>;
     communityAcceptInvite: (code: string) => Promise<string | undefined>;
     communityRevokeInviteV4: (communityJid: string, invitedJid: string) => Promise<boolean>;
-    communityAcceptInviteV4: (key: string | import("../index.js").WAMessageKey, inviteMessage: import("whatsapp-rust-bridge/proto-types").proto.Message.IGroupInviteMessage) => Promise<any>;
+    communityAcceptInviteV4: (key: string | import("../index.js").WAMessageKey, inviteMessage: import("@oxidezap/whatsapp-rust-bridge/proto-types").proto.Message.IGroupInviteMessage) => Promise<any>;
     communityGetInviteInfo: (code: string) => Promise<GroupMetadata>;
     communityToggleEphemeral: (jid: string, ephemeralExpiration: number) => Promise<void>;
     communitySettingUpdate: (jid: string, setting: "announcement" | "locked" | "not_announcement" | "unlocked") => Promise<void>;

package/lib/Socket/contacts.d.ts

@@ -12,6 +12,6 @@ export type OnWhatsAppResult = {
 export declare const makeContactMethods: (ctx: SocketContext) => {
     onWhatsApp: (...phoneNumber: string[]) => Promise<OnWhatsAppResult[] | undefined>;
     profilePictureUrl: (jid: string, type?: 'preview' | 'image', timeoutMs?: number) => Promise<string | undefined>;
-    fetchUserInfo: (...jids: string[]) => Promise<Record<string, import("whatsapp-rust-bridge").UserInfoResult>>;
+    fetchUserInfo: (...jids: string[]) => Promise<Record<string, import("@oxidezap/whatsapp-rust-bridge").UserInfoResult>>;
 };
 //# sourceMappingURL=contacts.d.ts.map

package/lib/Socket/events.d.ts

@@ -6,7 +6,7 @@
  * mapped type so TS forces a handler per variant — a missing handler
  * is a compile error.
  */
-import type { WhatsAppEvent, WhatsAppEventCallbacks } from 'whatsapp-rust-bridge';
+import type { WhatsAppEvent, WhatsAppEventCallbacks } from '@oxidezap/whatsapp-rust-bridge';
 import type { CanonicalEvent } from '../Bridge/index.js';
 import type { SocketContext } from './types.js';
 interface EventCallbacks {
@@ -20,6 +20,37 @@ interface EventCallbacks {
     onDirtyState?: (event: Extract<CanonicalEvent, {
         type: 'dirtyState';
     }>) => void;
+    /**
+     * The engine has stopped reconnecting: this client is dead weight only
+     * `free()` can reclaim.
+     *
+     * Owns publishing the `close` too — `publish()` must be called, and the
+     * point of handing it over is that the socket can finish tearing down
+     * first. Upstream does the same, emitting its close only after `ws.close()`
+     * and the end handlers (`Socket/socket.ts`). A consumer answering `close`
+     * with a replacement socket on the same auth folder would otherwise race
+     * the old one's store flush and `free()`.
+     */
+    onTerminalClose?: (error: Error, publish: () => void) => void;
+    /**
+     * Hand back a cleanup for anything the dispatcher armed that outlives a
+     * single event — today the history-sync pause timer. The socket registers
+     * it as an end handler, so a plain `sock.end()` or an `await using` scope
+     * exiting cancels it too: only the terminal-close path goes through
+     * `emitClose`, and a timer surviving disposal fires
+     * `messaging-history.status: paused` from a socket that is already gone.
+     *
+     * Called once, during `makeEventHandlers`.
+     */
+    onCleanup?: (cleanup: () => void) => void;
+    /**
+     * Whether `sock.setAutoReconnect(true)` is in effect. A plain drop is only
+     * transient while the engine still intends to retry: with auto-reconnect
+     * off, the run loop dispatches `Disconnected` and then breaks for good
+     * (`client/lifecycle.rs` tests the flag *after* the dispatch), so the same
+     * event becomes terminal. Absent callback means the default, enabled.
+     */
+    isAutoReconnectEnabled?: () => boolean;
 }
 /**
  * Create typed single and batch handlers for the bridge. The bridge only uses