@oxidezap/baileyrs 0.2.5 → 0.2.6

package/README.md

@@ -226,8 +226,23 @@ A few behaviors that differ from upstream — almost always to your advantage:
   [When `connecting` lasts minutes](#when-connecting-lasts-minutes): a
   readiness timeout written for upstream's `connecting` misreads this one.
 - **No `getMessage` / `cachedGroupMetadata` polyfill required.** The Rust
-  side caches group metadata and message keys natively. You can still pass
-  them — they're respected as overrides — but they're optional.
+  side caches group metadata and message keys natively, and nothing here calls
+  either hook: a `cachedGroupMetadata` carried over from upstream never runs,
+  and neither does a `getMessage`. Passing them is harmless — the whole
+  `SocketConfig` shape is accepted so a migration needs no edits — but they are
+  not overrides, so delete them rather than maintain them. Every socket warns once
+  at construction naming any option in that group it received; that list is the
+  authority — the type system requires each `SocketConfig` member to be
+  classified, so it cannot fall behind — and it also covers `keepAliveIntervalMs`,
+  `markOnlineOnConnect`, `maxMsgRetryCount`, `msgRetryCounterCache`,
+  `retryRequestDelayMs`, `fireInitQueries`, `syncFullHistory`,
+  `shouldSyncHistoryMessage`, `generateHighQualityLinkPreview`,
+  `linkPreviewImageThumbnailWidth`, `enableAutoSessionRecreation`,
+  `enableRecentMessageCache`, `appStateMacVerification`,
+  `patchMessageBeforeSending`, `customUploadHosts`, `countryCode`,
+  `connectTimeoutMs`, `qrTimeout`, `printQRInTerminal`, `ignoreOfflineMessages`,
+  `downloadHistory`, `agent`, `fetchAgent`, `mobile`, `mediaCache`,
+  `userDevicesCache`, `callOfferCache` and `placeholderResendCache`.
 - **`Boom` ships in the box.** baileyrs exports its own
   `@hapi/boom`-compatible `Boom`, so the existing
   `(err as Boom).output.statusCode` pattern works unchanged. If your

package/lib/Socket/events.js

@@ -161,6 +161,12 @@ const emitClose = ({ ctx, callbacks, historySync }, reason, statusCode, data) =>
  * 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.
  */
+/**
+ * `<stream:error code="429">` — the server rate limiting this session. The one
+ * stream error the engine forwards that is not a preserved connection; see the
+ * `streamError` dispatcher.
+ */
+const RATE_LIMITED_STREAM_ERROR = '429';
 const emitRetrying = (ctx) => ctx.ev.emit('connection.update', {
     connection: 'connecting',
     // Same shape upstream's own `connecting` always carries. Without the
@@ -298,15 +304,49 @@ const DISPATCHERS = {
         const status = mapConnectFailureToDisconnect(evt.reason);
         emitClose(dispatchCtx, evt.message ?? 'Connection failure', status);
     },
-    // 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
+    // NOT a close, in either branch below. 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'),
+    // re-pair, so a routine stream recycle could destroy a working session.
+    //
+    // Two kinds of event arrive here, and they are not interchangeable:
+    //
+    //  - the engine's catch-all `<stream:error>` branch — an unknown code, an
+    //    `<ack/>` it still owes the server, or `<xml-not-well-formed>` — where
+    //    it keeps or deliberately recycles the connection. Nothing to publish:
+    //    the recycle reaches the consumer as a `disconnected` of its own.
+    //
+    //  - `429`, which is a *rejected session*, not a preserved connection.
+    //    `client/node_io.rs` clears `is_logged_in`, adds five rungs to the
+    //    Fibonacci backoff and suppresses the reset that would undo them, then
+    //    dispatches this event so an embedder can act on it — the core's comment
+    //    says as much ("An embedder has none, so report the rate limit through
+    //    `StreamError`"). It falls through the handler's `should_disconnect`
+    //    block, so the transport is still up at this instant and the socket
+    //    would keep reporting `open` until the server ends the stream.
+    //
+    // `connecting` for 429 is not a new state: it is the one this library
+    // already defines for "the engine is restoring the connection", and the one
+    // the next server frame produces anyway. Publishing it here just moves it to
+    // the moment the engine already knows, instead of the round trip that
+    // confirms it. The coded errors that *are* terminal (401/409/515/516) never
+    // reach this dispatcher; they emit `loggedOut` / `streamReplaced` instead.
+    streamError: (evt, { ctx, callbacks }) => {
+        if (evt.code === RATE_LIMITED_STREAM_ERROR) {
+            ctx.logger.warn({ code: evt.code }, 'stream error: the server rate limited this session; the engine will retry with an extended backoff');
+            // `connecting` promises the engine is restoring this connection.
+            // Under `setAutoReconnect(false)` it will not — the run loop breaks
+            // on the pass after the disconnect that follows — so publishing it
+            // would leave a retrying state nobody resolves. Silence, not a
+            // close: the engine still dispatches `Disconnected` when the server
+            // ends the stream, and that dispatcher already turns it into a
+            // terminal close under this flag. Closing here too would publish two
+            // for one failure, the second after teardown had already run.
+            if (callbacks?.isAutoReconnectEnabled?.() !== false)
+                emitRetrying(ctx);
+            return;
+        }
+        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`

package/lib/Socket/index.js

@@ -28,6 +28,7 @@ import { makeChatActionMethods } from './chat-actions.js';
 import { makeContactMethods } from './contacts.js';
 import { makeCommunityMethods } from './communities.js';
 import { makeBridgeClientOwner } from './bridge-client-owner.js';
+import { warnUnsupportedConfig } from './unsupported-config.js';
 import { wrapBridgeClient } from './bridge-error-boundary.js';
 import { makeTerminalCloseReporter } from './terminal-close-reporter.js';
 import { makeEventHandlers } from './events.js';
@@ -74,6 +75,10 @@ const browserToPlatformType = (browser) => {
 const makeWASocket = (config) => {
     const fullConfig = { ...DEFAULT_CONNECTION_CONFIG, ...config };
     const { logger } = fullConfig;
+    // Against `config`, not `fullConfig`: only what this caller actually passed
+    // is worth naming. Merging the defaults first would report every unsupported
+    // option on every socket, including the ones nobody chose.
+    warnUnsupportedConfig(config, logger);
     const auth = normalizeSocketAuthenticationState(fullConfig.auth);
     const getExposedKeys = makeLazyTransactionKeyStore(auth.keys, logger, fullConfig.transactionOpts);
     const ev = makeEventBuffer(logger);

package/lib/Socket/unsupported-config.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Options `SocketConfig` accepts that nothing on this side reads.
+ *
+ * Being a drop-in replacement means accepting the whole upstream shape, so none
+ * of these throws and none of them ever will. But the Rust engine owns
+ * keepalive, retry, history sync, link previews and its own message and group
+ * caches, so for these keys there is no reader to hand the value to — and a
+ * consumer that passes one is describing behaviour it will not get.
+ *
+ * That gap is expensive precisely because it is quiet. Two shapes found in a
+ * production bot, both dead for months, both looking deliberate:
+ *
+ * ```ts
+ * cachedGroupMetadata: async jid => myOwnCache.get(jid)   // never called
+ * getMessage: async key => myStore.get(key.id)            // never called
+ * ```
+ *
+ * `enableRecentMessageCache: true` is worse: it names a cache the consumer
+ * believes it turned on.
+ *
+ * The list is deliberately hand-maintained rather than derived. Deriving it
+ * (scanning for reads) would quietly go wrong in both directions — an option
+ * read through a computed key would look unsupported, and one only mentioned in
+ * a type would look supported. A test anchors every entry to `SocketConfig`, so
+ * an option that starts being read here fails the audit for whoever removes it.
+ */
+export declare const UNSUPPORTED_CONFIG_KEYS: readonly ["keepAliveIntervalMs", "maxMsgRetryCount", "msgRetryCounterCache", "retryRequestDelayMs", "fireInitQueries", "markOnlineOnConnect", "syncFullHistory", "shouldSyncHistoryMessage", "generateHighQualityLinkPreview", "linkPreviewImageThumbnailWidth", "enableAutoSessionRecreation", "enableRecentMessageCache", "appStateMacVerification", "cachedGroupMetadata", "getMessage", "patchMessageBeforeSending", "customUploadHosts", "countryCode", "connectTimeoutMs", "qrTimeout", "agent", "fetchAgent", "mobile", "printQRInTerminal", "ignoreOfflineMessages", "downloadHistory", "mediaCache", "userDevicesCache", "callOfferCache", "placeholderResendCache"];
+/**
+ * The other half: options something on this side actually reads.
+ *
+ * Only here to make the classification total. Nothing consumes this list at
+ * runtime; its job is to let the assertion below fail the build when a new
+ * member of `SocketConfig` belongs to neither list — which is exactly how the
+ * first version of the catalog shipped twelve keys short.
+ */
+export declare const READ_CONFIG_KEYS: readonly ["waWebSocketUrl", "options", "logger", "version", "browser", "pushName", "auth", "cache", "deviceProps", "wantedPreKeyCount", "emitOwnEvents", "shouldIgnoreJid", "defaultQueryTimeoutMs", "transactionOpts", "makeSignalRepository"];
+/**
+ * Which unsupported options this caller actually passed.
+ *
+ * Only own, non-`undefined` properties count: spreading a partial config
+ * commonly leaves `{ getMessage: undefined }` behind, and warning about a key
+ * whose value is absent would be noise about nothing.
+ *
+ * @param config the object handed to `makeWASocket`, before defaults are merged
+ * @returns the offending keys, in catalog order (stable across consumers)
+ */
+export declare const unsupportedConfigKeys: (config: object) => string[];
+/**
+ * Say once per socket, at construction, which unsupported options this caller
+ * passed.
+ *
+ * Per socket, not per process: a replacement socket built after a terminal
+ * close carries its own configuration decision, and `Socket/internals.ts`
+ * already warns "once per socket rather than per call" for its own no-ops.
+ *
+ * `warn` and not `error`: nothing is broken.
+ *
+ * A socket must never fail to build over a diagnostic. That guarantee is
+ * unconditional, so the guard covers the whole of it — the reading as well as
+ * the writing:
+ *
+ *  - the optional chaining, for a logger with no `warn` (a minimal one in a
+ *    test, say);
+ *  - the `try` around the logging call, for a logger whose `warn` throws — a
+ *    synchronous transport failing there would take down `makeWASocket` itself;
+ *  - the same `try` around the inspection, because telling a passed option from
+ *    a spread leftover means reading `config[key]`, and reading fires getters. A
+ *    config with a throwing accessor, or a proxy with a throwing trap, would
+ *    otherwise fail construction from outside the logging call.
+ *
+ * All of it only ever bites consumers who passed an inert option, which is the
+ * one group this warning exists to help. The failure is swallowed rather than
+ * reported, because the only thing left to report it with is the logger that
+ * just threw.
+ *
+ * @param config the object handed to `makeWASocket`, before defaults are merged
+ * @param logger the socket's logger
+ */
+export declare const warnUnsupportedConfig: (config: object, logger: {
+    warn?: (payload: object, message: string) => void;
+}) => void;
+//# sourceMappingURL=unsupported-config.d.ts.map

package/lib/Socket/unsupported-config.js

@@ -0,0 +1,162 @@
+/**
+ * Options `SocketConfig` accepts that nothing on this side reads.
+ *
+ * Being a drop-in replacement means accepting the whole upstream shape, so none
+ * of these throws and none of them ever will. But the Rust engine owns
+ * keepalive, retry, history sync, link previews and its own message and group
+ * caches, so for these keys there is no reader to hand the value to — and a
+ * consumer that passes one is describing behaviour it will not get.
+ *
+ * That gap is expensive precisely because it is quiet. Two shapes found in a
+ * production bot, both dead for months, both looking deliberate:
+ *
+ * ```ts
+ * cachedGroupMetadata: async jid => myOwnCache.get(jid)   // never called
+ * getMessage: async key => myStore.get(key.id)            // never called
+ * ```
+ *
+ * `enableRecentMessageCache: true` is worse: it names a cache the consumer
+ * believes it turned on.
+ *
+ * The list is deliberately hand-maintained rather than derived. Deriving it
+ * (scanning for reads) would quietly go wrong in both directions — an option
+ * read through a computed key would look unsupported, and one only mentioned in
+ * a type would look supported. A test anchors every entry to `SocketConfig`, so
+ * an option that starts being read here fails the audit for whoever removes it.
+ */
+export const UNSUPPORTED_CONFIG_KEYS = [
+    // The engine runs its own keepalive (WA Web's idle-ping + dead-socket
+    // watchdog) and its own Fibonacci reconnect ladder.
+    'keepAliveIntervalMs',
+    // Retry of an undecryptable message is engine-side, keyed off its own store
+    // of sent messages; there is nothing for a consumer counter to count.
+    'maxMsgRetryCount',
+    'msgRetryCounterCache',
+    'retryRequestDelayMs',
+    // The engine decides its own post-login queries.
+    'fireInitQueries',
+    // Presence is explicit here: call `sendPresenceUpdate` after `open`.
+    'markOnlineOnConnect',
+    // History sync is driven by the engine.
+    'syncFullHistory',
+    'shouldSyncHistoryMessage',
+    // Link previews are not generated on this side.
+    'generateHighQualityLinkPreview',
+    'linkPreviewImageThumbnailWidth',
+    // Session recreation and the recent-message cache are engine-side, and
+    // configured through `cache` (CacheConfig), not through these flags.
+    'enableAutoSessionRecreation',
+    'enableRecentMessageCache',
+    // App-state MAC verification happens in the engine.
+    'appStateMacVerification',
+    // The engine resolves group metadata and sent messages from its own stores;
+    // these two are the ones consumers most often carry over from upstream and
+    // keep believing in.
+    'cachedGroupMetadata',
+    'getMessage',
+    // Upstream hooks with no counterpart on this side.
+    'patchMessageBeforeSending',
+    'customUploadHosts',
+    'countryCode',
+    // Timeouts and transport knobs the engine owns. `connectTimeoutMs` is the
+    // one to point at: `Socket/internals.ts` already documented that it "reaches
+    // neither the transport nor the core", and it was still missing from the
+    // first version of this list. Proxy and TLS configuration goes through
+    // `options.dispatcher`, which is read — `agent` and `fetchAgent` are not.
+    'connectTimeoutMs',
+    'qrTimeout',
+    'agent',
+    'fetchAgent',
+    'mobile',
+    // The QR is published on `connection.update`; drawing it is the consumer's.
+    'printQRInTerminal',
+    // Offline delivery is the engine's, and history sync is driven by it too.
+    'ignoreOfflineMessages',
+    'downloadHistory',
+    // Caches the engine keeps natively, in Rust, keyed off its own stores.
+    'mediaCache',
+    'userDevicesCache',
+    'callOfferCache',
+    'placeholderResendCache'
+];
+/**
+ * The other half: options something on this side actually reads.
+ *
+ * Only here to make the classification total. Nothing consumes this list at
+ * runtime; its job is to let the assertion below fail the build when a new
+ * member of `SocketConfig` belongs to neither list — which is exactly how the
+ * first version of the catalog shipped twelve keys short.
+ */
+export const READ_CONFIG_KEYS = [
+    'waWebSocketUrl',
+    'options',
+    'logger',
+    'version',
+    'browser',
+    'pushName',
+    'auth',
+    'cache',
+    'deviceProps',
+    'wantedPreKeyCount',
+    'emitOwnEvents',
+    'shouldIgnoreJid',
+    'defaultQueryTimeoutMs',
+    'transactionOpts',
+    'makeSignalRepository'
+];
+const _everyConfigKeyIsClassified = true;
+void _everyConfigKeyIsClassified;
+/**
+ * Which unsupported options this caller actually passed.
+ *
+ * Only own, non-`undefined` properties count: spreading a partial config
+ * commonly leaves `{ getMessage: undefined }` behind, and warning about a key
+ * whose value is absent would be noise about nothing.
+ *
+ * @param config the object handed to `makeWASocket`, before defaults are merged
+ * @returns the offending keys, in catalog order (stable across consumers)
+ */
+export const unsupportedConfigKeys = (config) => UNSUPPORTED_CONFIG_KEYS.filter(key => Object.hasOwn(config, key) && config[key] !== undefined);
+/**
+ * Say once per socket, at construction, which unsupported options this caller
+ * passed.
+ *
+ * Per socket, not per process: a replacement socket built after a terminal
+ * close carries its own configuration decision, and `Socket/internals.ts`
+ * already warns "once per socket rather than per call" for its own no-ops.
+ *
+ * `warn` and not `error`: nothing is broken.
+ *
+ * A socket must never fail to build over a diagnostic. That guarantee is
+ * unconditional, so the guard covers the whole of it — the reading as well as
+ * the writing:
+ *
+ *  - the optional chaining, for a logger with no `warn` (a minimal one in a
+ *    test, say);
+ *  - the `try` around the logging call, for a logger whose `warn` throws — a
+ *    synchronous transport failing there would take down `makeWASocket` itself;
+ *  - the same `try` around the inspection, because telling a passed option from
+ *    a spread leftover means reading `config[key]`, and reading fires getters. A
+ *    config with a throwing accessor, or a proxy with a throwing trap, would
+ *    otherwise fail construction from outside the logging call.
+ *
+ * All of it only ever bites consumers who passed an inert option, which is the
+ * one group this warning exists to help. The failure is swallowed rather than
+ * reported, because the only thing left to report it with is the logger that
+ * just threw.
+ *
+ * @param config the object handed to `makeWASocket`, before defaults are merged
+ * @param logger the socket's logger
+ */
+export const warnUnsupportedConfig = (config, logger) => {
+    try {
+        const options = unsupportedConfigKeys(config);
+        if (!options.length)
+            return;
+        logger?.warn?.({ options }, 'these options are accepted for upstream compatibility but nothing reads them here: the engine owns that behaviour');
+    }
+    catch {
+        // See above: nothing here is worth failing a socket over.
+    }
+};
+//# sourceMappingURL=unsupported-config.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@oxidezap/baileyrs",
   "type": "module",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "A Rust-powered WhatsApp Web library for JavaScript, with a Baileys-compatible API",
   "keywords": [
     "whatsapp",