@oxidezap/baileyrs 0.0.35 → 0.1.0

package/lib/Socket/events.js

@@ -22,6 +22,7 @@ import { buildGroupCreateStubMessage, buildGroupJoinRequestEvents, buildGroupNot
 import { emitMessageUpsert } from '../Compatibility/message-upsert.js';
 import { extractMessageCappingPayload } from './message-capping.js';
 import { mapReachoutTimelock } from './reachout.js';
+import { isReconnectableConnectFailure } from './terminal-close.js';
 const CANONICAL_MESSAGE_EVENT = 'message';
 const MESSAGE_UPSERT_APPEND = 'append';
 const MESSAGE_UPSERT_NOTIFY = 'notify';
@@ -104,15 +105,72 @@ const clearHistorySyncPausedTimeout = (state) => {
         clearTimeout(state.pausedTimeout);
     state.pausedTimeout = undefined;
 };
-const emitClose = (ctx, reason, statusCode, data) => ctx.ev.emit('connection.update', {
-    connection: 'close',
-    lastDisconnect: { error: new Boom(reason, { statusCode, data }), date: new Date() }
+/**
+ * Report a disconnect the engine will NOT recover from.
+ *
+ * `connection: 'close'` carries one meaning on this socket, the same one it
+ * carries in upstream Baileys: the socket is finished and the consumer has to
+ * build a new one. Disconnects the engine is still retrying never come through
+ * here — see `emitRetrying` and `terminal-close.ts`.
+ *
+ * `onTerminalClose` owns both the teardown and the publish, so the socket can
+ * be fully torn down before the consumer sees the event — the order upstream
+ * uses, and what keeps a replacement socket from overlapping the old one's
+ * store flush. Without that callback (a bare `makeEventHandler`), the close
+ * goes out immediately.
+ */
+const emitClose = ({ ctx, callbacks, historySync }, reason, statusCode, data) => {
+    // Every terminal path cancels the history-sync pause timer, not just the
+    // one in `disconnected`. A transient drop deliberately keeps it armed, so
+    // without this a drop followed by a terminal close leaves it to fire a
+    // `messaging-history.status: paused` from a socket that has already ended.
+    clearHistorySyncPausedTimeout(historySync);
+    const error = new Boom(reason, { statusCode, data });
+    const publish = () => ctx.ev.emit('connection.update', {
+        connection: 'close',
+        lastDisconnect: { error, date: new Date() }
+    });
+    if (callbacks?.onTerminalClose) {
+        callbacks.onTerminalClose(error, publish);
+        return;
+    }
+    publish();
+};
+/**
+ * Report a disconnect the engine is retrying on its own.
+ *
+ * Emitted as `connecting` rather than `close` on purpose. The canonical
+ * upstream handler is `if (connection === 'close') reconnect()`, and upstream
+ * has no auto-reconnect — so surfacing a transient drop as `close` makes that
+ * handler build a second socket while the engine is already backing off to
+ * restore the first. Two live sockets for one connection. `connecting` is the
+ * state upstream itself uses while a connection is being (re)established, so
+ * consumers read this as `open → connecting → open` and stay out of the way.
+ */
+const emitRetrying = (ctx) => ctx.ev.emit('connection.update', {
+    connection: 'connecting',
+    // Same shape upstream's own `connecting` always carries. Without the
+    // explicit clear, a consumer merging partial state keeps rendering the
+    // QR from before the drop — one the server has already rotated away.
+    qr: undefined,
+    receivedPendingNotifications: false
 });
+/**
+ * `<failure reason="405">` — the wire code, kept as-is rather than folded into
+ * `DisconnectReason`, which has no member for it. See the `clientOutdated`
+ * dispatcher for why `badSession` was the wrong home.
+ */
+const CLIENT_OUTDATED_STATUS = 405;
 /**
  * Map bridge `ConnectFailureReason` wire codes (per the bridge's
  * `.d.ts` annotation) onto upstream Baileys' `DisconnectReason`.
  * Unknown codes fall through to `connectionClosed` so existing
  * reconnect heuristics keep working.
+ *
+ * Several cases here are belt-and-braces: the engine dispatches its own event
+ * for `is_logged_out()` reasons (401/403/406) and for 405, so those never
+ * reach `connectFailure` in practice. Kept because they cost nothing and the
+ * engine's routing is not ours to depend on.
  */
 const mapConnectFailureToDisconnect = (reason) => {
     switch (reason) {
@@ -123,7 +181,7 @@ const mapConnectFailureToDisconnect = (reason) => {
         case 402: // TempBanned
             return DisconnectReason.forbidden;
         case 405: // ClientOutdated
-            return DisconnectReason.badSession;
+            return CLIENT_OUTDATED_STATUS;
         case 411: // MultideviceMismatch (legacy alias)
             return DisconnectReason.multideviceMismatch;
         case 503: // ServiceUnavailable
@@ -168,9 +226,26 @@ const DISPATCHERS = {
     offlineSyncCompleted: (_, { ctx }) => emitConnectionUpdate(ctx, {
         receivedPendingNotifications: true
     }),
-    disconnected: (_, { ctx, historySync }) => {
-        clearHistorySyncPausedTimeout(historySync);
-        emitClose(ctx, 'Connection closed', DisconnectReason.connectionClosed);
+    // The engine dispatches `Disconnected` only for an *unexpected* loop exit,
+    // and every terminal path marks `expected_disconnect` first — so this is
+    // normally "the Fibonacci backoff is already running".
+    //
+    // The exception is `sock.setAutoReconnect(false)`: `client/lifecycle.rs`
+    // dispatches `Disconnected` and only *then* tests the flag and breaks out
+    // of the run loop. Treating that as transient would leave the socket
+    // reporting `connecting` forever, with the wasm client never freed and the
+    // consumer's reconnect handler never firing.
+    disconnected: (_, dispatchCtx) => {
+        if (dispatchCtx.callbacks?.isAutoReconnectEnabled?.() === false) {
+            emitClose(dispatchCtx, 'Connection closed', DisconnectReason.connectionClosed);
+            return;
+        }
+        // The pause timer survives a retrying drop. It is the only pending
+        // transition to `messaging-history.status: paused`, and this socket
+        // lives on — clearing it left a RECENT sync that had reported progress
+        // below 100 with neither `paused` nor `complete` if the reconnect
+        // produced no further chunk, hanging consumers waiting on hydration.
+        emitRetrying(dispatchCtx.ctx);
     },
     qr: (evt, { ctx }) => emitConnectionUpdate(ctx, { qr: evt.code }),
     pairSuccess: (evt, { ctx, callbacks }) => {
@@ -183,47 +258,57 @@ const DISPATCHERS = {
         // a compat hook for upstream's lifecycle.
         ctx.ev.emit('creds.update', { registered: true, me: { id, lid, name: businessName }, platform });
     },
-    pairError: (evt, { ctx }) => emitClose(ctx, 'Pairing failed: ' + evt.error, DisconnectReason.connectionClosed),
-    loggedOut: (evt, { ctx }) => emitClose(ctx, evt.reason ? `Logged out: ${evt.reason}` : 'Logged out', DisconnectReason.loggedOut),
-    connectFailure: (evt, { ctx }) => {
+    // Pairing failed, but the engine keeps its loop and re-emits a QR — nothing
+    // about the client is dead, so this must not read as `close`. It still
+    // belongs on the bus: the QR the user was shown is spent, and `connecting`
+    // clears it while telling the consumer a fresh one is coming.
+    pairError: (evt, { ctx }) => {
+        ctx.logger.error({ err: evt.error }, 'pairing failed; the engine will retry');
+        emitRetrying(ctx);
+    },
+    loggedOut: (evt, dispatchCtx) => emitClose(dispatchCtx, evt.reason ? `Logged out: ${evt.reason}` : 'Logged out', DisconnectReason.loggedOut),
+    connectFailure: (evt, dispatchCtx) => {
         // Map bridge `ConnectFailureReason` wire codes onto Baileys'
         // DisconnectReason. Defaults to connectionClosed for unknown codes.
         // LoggedOut paths (401/403/406) drive bots' "should I re-pair?"
         // branch — folding them into connectionClosed kept that broken.
+        // "Reconnectable" is only true while the engine is allowed to reconnect.
+        // With `setAutoReconnect(false)` the run loop breaks on the next pass,
+        // so reporting `connecting` for a 500/503 would leave the socket stuck
+        // in that state with nothing left to restore it.
+        if (isReconnectableConnectFailure(evt.reason) && dispatchCtx.callbacks?.isAutoReconnectEnabled?.() !== false) {
+            dispatchCtx.ctx.logger.warn({ reason: evt.reason, message: evt.message }, 'connect failure; the engine will retry');
+            emitRetrying(dispatchCtx.ctx);
+            return;
+        }
         const status = mapConnectFailureToDisconnect(evt.reason);
-        emitClose(ctx, evt.message ?? 'Connection failure', status);
+        emitClose(dispatchCtx, evt.message ?? 'Connection failure', status);
     },
-    // Preserve the wire code on `boom.data.streamErrorCode` so consumers can
-    // branch on the actual `<stream:error code="...">` (e.g. 500 vs an
-    // unknown code) without losing the canonical DisconnectReason.badSession.
-    streamError: (evt, { ctx }) => emitClose(ctx, 'Stream error: ' + evt.code, DisconnectReason.badSession, {
-        streamErrorCode: evt.code
-    }),
-    streamReplaced: (_, { ctx }) => emitConnectionUpdate(ctx, {
-        connection: 'close',
-        lastDisconnect: {
-            error: new Boom('Connection replaced', { statusCode: DisconnectReason.connectionReplaced }),
-            date: new Date()
-        }
-    }),
-    clientOutdated: (_, { ctx }) => emitClose(ctx, 'Client outdated', DisconnectReason.badSession),
-    temporaryBan: (evt, { ctx }) => {
+    // NOT a close. The engine dispatches `StreamError` only from its catch-all
+    // `<stream:error>` branch — an unknown code, an `<ack/>` it still owes the
+    // server, or `<xml-not-well-formed>` — and it keeps or deliberately recycles
+    // the connection in every one of those. This used to report
+    // `DisconnectReason.badSession`, the code bots use to wipe credentials and
+    // re-pair, so a routine stream recycle could destroy a working session. The
+    // coded stream errors (401/409/515/516) never arrive here; they dispatch
+    // `loggedOut` / `streamReplaced` of their own.
+    streamError: (evt, { ctx }) => ctx.logger.warn({ code: evt.code }, 'stream error; the connection is preserved'),
+    streamReplaced: (_, dispatchCtx) => emitClose(dispatchCtx, 'Connection replaced', DisconnectReason.connectionReplaced),
+    // Carries the wire code (405), not `DisconnectReason.badSession`. Upstream
+    // does the same for stream errors — `+node.attrs.code` first, `badSession`
+    // only as the no-code fallback (`Utils/generics.ts` `getErrorCodeFromStreamError`).
+    // badSession is 500, the code bots use to wipe credentials and re-pair; an
+    // outdated build is the one failure where wiping a perfectly good session
+    // helps nobody, and the next connect fails identically.
+    clientOutdated: (_, dispatchCtx) => emitClose(dispatchCtx, 'Client outdated', CLIENT_OUTDATED_STATUS),
+    temporaryBan: (evt, dispatchCtx) => {
         // Surface the wire code + expire on the Boom so consumers reading
         // `lastDisconnect.error.data` can act on the specific reason.
         const reason = describeTempBan(evt.code);
         const message = evt.expire
             ? `Temporary ban (${reason}); expires at ${new Date(evt.expire * 1000).toISOString()}`
             : `Temporary ban (${reason})`;
-        ctx.ev.emit('connection.update', {
-            connection: 'close',
-            lastDisconnect: {
-                error: new Boom(message, {
-                    statusCode: DisconnectReason.forbidden,
-                    data: { code: evt.code, expire: evt.expire }
-                }),
-                date: new Date()
-            }
-        });
+        emitClose(dispatchCtx, message, DisconnectReason.forbidden, { code: evt.code, expire: evt.expire });
     },
     qrScannedWithoutMultidevice: (_, { ctx }) => ctx.logger.warn('QR scanned but multi-device not enabled on phone'),
     // ── Messages ──
@@ -784,6 +869,7 @@ export const makeEventHandlers = (ctx, callbacks) => {
         callbacks,
         historySync: { initialBootstrapComplete: false, recentSyncComplete: false }
     };
+    callbacks?.onCleanup?.(() => clearHistorySyncPausedTimeout(dispatchCtx.historySync));
     const onEvent = (event) => {
         const canonical = adaptBridgeEvent(event, ctx.logger);
         if (canonical)
@@ -857,12 +943,29 @@ export const makeEventHandlers = (ctx, callbacks) => {
         for (const data of acks)
             onEvent({ type: 'server_ack', data });
     };
+    // Opting the two packed paths into the bridge's borrowing contract, which
+    // lets it hand every batch out of one reused buffer instead of allocating
+    // per batch. Both handlers already satisfied the contract unchanged: each
+    // decodes as its first act, and `decodeReceiptWireBatch` /
+    // `decodeServerAckWireBatch` materialise every field rather than keeping a
+    // view, so nothing points at the buffer once they return. Neither is async,
+    // and no exception escapes them — the decode is guarded here and the
+    // dispatch is guarded in `dispatchCanonicalEvent` — both of which the
+    // contract requires, since either one drops the whole session back to a
+    // buffer per batch.
+    //
+    // Declaring a borrowing name replaces its copying counterpart as the sink,
+    // so the pair below is the whole opt-in. There is deliberately none for
+    // messages: `decodeMessageWireBatch` returns views over the batch, so reuse
+    // would alias the decoded result and not just the buffer.
     return {
         onEvent,
         onMessageBatch,
         onHistorySyncBatch,
         onReceiptBatch,
         onServerAckBatch,
+        onReceiptBatchBorrowed: onReceiptBatch,
+        onServerAckBatchBorrowed: onServerAckBatch,
         historySyncConversationTypes: CONVERSATION_HISTORY_SYNC_TYPES
     };
 };

package/lib/Socket/index.d.ts

@@ -1,5 +1,5 @@
 import { Buffer } from 'node:buffer';
-import { type UploadMediaResult, type WasmWhatsAppClient } from '@oxidezap/whatsapp-rust-bridge';
+import { type UploadMediaResult } from '@oxidezap/whatsapp-rust-bridge';
 import { WebSocketClient } from '../Compatibility/websocket-client.js';
 import { type MediaType } from '../Defaults/index.js';
 import type { BinaryNode, AuthenticationCreds, ConnectionState, Contact, ReachoutTimelockState, SignalKeyStoreWithTransaction, UserFacingSocketConfig, WAPrivacyGroupAddValue, WAPrivacyOnlineValue, WAPrivacyValue, WABusinessProfile, WAReadReceiptsValue, WAMessage, WAMessageKey } from '../Types/index.js';
@@ -120,8 +120,34 @@ declare const makeWASocket: (config: UserFacingSocketConfig) => {
     logger: import("../Utils/logger.js").ILogger;
     ws: WebSocketClient;
     type: 'md';
+    /**
+     * `await using sock = makeWASocket(config)` — frees the wasm client on
+     * scope exit. Nothing else can: the bridge holds the JS event callbacks
+     * as wasm-bindgen externrefs and those callbacks reach back to this
+     * closure, so the reference cycle crosses the JS/wasm boundary and no
+     * `FinalizationRegistry` will ever fire for the client.
+     *
+     * Delegates to `end()`, so it flushes the auth store and is idempotent.
+     *
+     * Then awaits `initPromise`, because `end()` alone does not satisfy the
+     * async-disposal contract: called before `createWhatsAppClient()`
+     * settles, it sees `client === undefined`, frees nothing, and resolves
+     * while initialization is still running. What actually disposes that
+     * client is the `ended` guard inside `init()` — so code after the
+     * `await using` scope would otherwise overlap with bridge construction,
+     * event callbacks, and store access. `end()` runs first because it sets
+     * `ended` synchronously, which is what makes `init()` bail out early.
+     *
+     * The `finally` is load-bearing: `end()` rethrows the first auth-store
+     * flush failure, and letting that propagate directly would skip the wait
+     * and resolve the disposer with `init()` still in flight — losing the
+     * one guarantee it exists to provide, in exactly the situation where
+     * cleanup already went wrong. `initPromise` swallows its own failures,
+     * so awaiting it here cannot mask the flush error.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
     user: Contact | undefined;
-    waClient: WasmWhatsAppClient | undefined;
+    waClient: import("@oxidezap/whatsapp-rust-bridge").WasmWhatsAppClient | undefined;
     isConnected: boolean;
     isLoggedIn: boolean;
     authState: {