Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(wwebjs): bound the pinned WhatsApp Web HTML fetch

Yudhi Armyndharis7771733cb710
diff --git a/.env.example b/.env.example
index f2d78c12b..6c67d7126 100644
--- a/.env.example
+++ b/.env.example
@@ -180,11 +180,12 @@ OPENWA_PIDS_LIMIT=2048
# https://github.com/wppconnect-team/wa-version). WWEBJS_WEB_VERSION_REMOTE_PATH overrides the
# HTML URL template (use {version} as the placeholder) to fetch from an operator-controlled copy
# instead. The requested build + its source (pinned/auto/native) is shown on the dashboard's
-# Infrastructure page. A pin is not guaranteed to hold: a pin whose HTML cannot be fetched is dropped
-# for the live build, and WhatsApp Web's service worker can serve its own cached build instead of the
-# pinned HTML. Each session logs the build it actually runs when it reaches ready (action
-# web_version_running), and warns with both builds when that is not the pinned one (action
-# web_version_pin_not_applied).
+# Infrastructure page. A pin is not guaranteed to hold: a pin whose HTML cannot be fetched within
+# 10 s is dropped for the live build (warning web_version_html_unavailable), and WhatsApp Web's
+# service worker can serve its own cached build instead of the pinned HTML. A fetched build is kept
+# under SESSION_DATA_PATH/.wa-web-cache/. Each session logs the build it actually runs when it
+# reaches ready (action web_version_running), and warns with both builds when that is not the
+# pinned one (action web_version_pin_not_applied).
# WWEBJS_WEB_VERSION=<a build from that registry's html/ folder>
# WWEBJS_WEB_VERSION=off
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 054a062da..0d3583350 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -343,20 +343,24 @@ WWEBJS_WEB_VERSION=<a build from that registry's html/ folder>
Restart the container after changing it. Pick the build from
[wppconnect-team/wa-version](https://github.com/wppconnect-team/wa-version) (the `html/` folder) — a
-build the registry no longer serves is fetched, missed, and ignored, leaving you on the default
-behaviour rather than the pin you asked for (the `ready`-time warning below names both builds). With
+build the registry no longer serves cannot be fetched, and the session starts on the live build rather
+than the pin you asked for, with a warning at start (action `web_version_html_unavailable`, naming the
+build, the URL and the reason). With
`WWEBJS_WEB_VERSION` unset, `latest`, or `auto` (the default), OpenWA auto-resolves a settled build
from that registry and pins its HTML — note this HTML is fetched from a third-party repository and
executed inside the `web.whatsapp.com` origin without an integrity check. Set
`WWEBJS_WEB_VERSION=off` to disable pinning and use the first-party build served by WhatsApp. An
unpinned session (this setting, or an auto-resolve that could not reach the registry) caches nothing to
-disk, so it also works on the image's read-only root filesystem.
+disk, so it also works on the image's read-only root filesystem. A pinned build's HTML is downloaded
+at start, with a 10 s bound, into `<SESSION_DATA_PATH>/.wa-web-cache/` on the writable data volume and
+served from there; a build no session has started on for a week is removed.
A pin is not guaranteed to hold. whatsapp-web.js applies it by answering the page's document request
with the pinned HTML, and that can miss in two ways: a pin whose HTML could not be fetched is dropped
-and the live build loads, and WhatsApp Web's service worker can serve its own cached build without the
-request reaching whatsapp-web.js. Either way the page can run a different build than the one
-requested, while the startup line `Pinning WhatsApp Web version …` still names the requested build.
+at start (the `web_version_html_unavailable` warning above) and the live build loads, and WhatsApp
+Web's service worker can serve its own cached build without the request reaching whatsapp-web.js. In
+the second case the page runs a different build than the one requested, while the startup line
+`Pinning WhatsApp Web version …` still names the requested build.
When a session reaches `ready`, OpenWA reads the build the page reports and logs it (action
`web_version_running`); when a pin was requested and the page runs a different build, it logs a
warning naming both (action `web_version_pin_not_applied`). The comparison ignores the registry's
@@ -364,9 +368,8 @@ suffix such as `-alpha`, so a pin and the same bare build count as a match.
The warning changes nothing about the session. It reached `ready` on the build the warning names, so
the pin did not cover that page load, and a session that works on that build needs no action.
-If the pin is one you set yourself, check that the registry still serves it. Whether the service worker
-answers can differ from one page load to the next, so a later restart may load the pin. When you report
-a problem with the session, include both builds.
+Whether the service worker answers can differ from one page load to the next, so a later restart may
+load the pin. When you report a problem with the session, include both builds.
### Issue: QR generation times out on slow first boot (WSL2 / low-resource)
diff --git a/src/engine/adapters/wwebjs-lifecycle.ts b/src/engine/adapters/wwebjs-lifecycle.ts
index 8fd0478b6..2ff36a190 100644
--- a/src/engine/adapters/wwebjs-lifecycle.ts
+++ b/src/engine/adapters/wwebjs-lifecycle.ts
@@ -300,7 +300,12 @@ export class WwebjsLifecycle {
// #251/#488). DEFAULT: auto-resolve a settled build from the wa-version registry and pin its
// remote HTML (no integrity check — resolveWebVersionPin logs a loud warning); only
// WWEBJS_WEB_VERSION=off leaves whatsapp-web.js to use the first-party build from WhatsApp.
- const versionPin = await resolveWebVersionPin();
+ // The pinned HTML is downloaded (bounded) onto the writable data volume and served from there,
+ // so an unreachable mirror is named in the log instead of silently loading the live build.
+ const versionPin = await resolveWebVersionPin(
+ undefined,
+ path.join(path.resolve(this.host.config.sessionDataPath), '.wa-web-cache'),
+ );
// Assigned on every init, including the unpinned case, so a pin from an earlier init is never
// compared against the page this one loads.
this.requestedWebVersion = versionPin?.webVersion;
@@ -451,7 +456,9 @@ export class WwebjsLifecycle {
// Unpinned, whatsapp-web.js defaults to a local HTML cache at the cwd-relative
// './.wwebjs_cache/' and writes it after the link, before `ready`. The image's /app is not
// writable (root-owned, read-only in compose and Helm), so that write throws and the session
- // never reaches ready. 'none' caches nothing and serves WhatsApp's live build.
+ // never reaches ready. 'none' caches nothing and serves WhatsApp's live build. A pin is a
+ // strict local cache under SESSION_DATA_PATH (see resolveWebVersionPin), which the library
+ // only reads: it persists nothing when the cache served the page.
...(versionPin ?? { webVersionCache: { type: 'none' as const } }),
});
this.client = client;
diff --git a/src/engine/adapters/wwebjs-running-build.ts b/src/engine/adapters/wwebjs-running-build.ts
index 911711a04..515fbeac8 100644
--- a/src/engine/adapters/wwebjs-running-build.ts
+++ b/src/engine/adapters/wwebjs-running-build.ts
@@ -26,10 +26,11 @@ function numericBuild(version: string): string | null {
* whatsapp-web.js applies a pin by answering the page's document request from its request
* interceptor, so the pin holds only for a page load that goes through it. WhatsApp Web's service
* worker can answer the document from its own cache without the request ever reaching the
- * interceptor, and a pin whose HTML could not be fetched installs no interceptor at all (the
- * library's remote cache is non-strict and falls back to the live build). Either way the startup
- * line `Pinning WhatsApp Web version …` still names the pin, and nothing read back the build that
- * actually booted, so a session reported to be on one build could be running another.
+ * interceptor. (A pin whose HTML could not be fetched is dropped before the Client is built: it
+ * logs `web_version_html_unavailable`, no pin is requested, and the page loads the live build.) In
+ * the service-worker case the startup line `Pinning WhatsApp Web version …` still names the pin,
+ * and nothing read back the build that actually booted, so a session reported to be on one build
+ * could be running another.
*
* The comparison is on the numeric build only (see {@link numericBuild}). A pin that does not parse
* as one cannot be compared, and gets the info line rather than a warning. A read that fails or
diff --git a/src/engine/adapters/wwebjs-web-version-cache.spec.ts b/src/engine/adapters/wwebjs-web-version-cache.spec.ts
index 2f54c3d8a..a9444bb27 100644
--- a/src/engine/adapters/wwebjs-web-version-cache.spec.ts
+++ b/src/engine/adapters/wwebjs-web-version-cache.spec.ts
@@ -1,5 +1,9 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
import { Client } from 'whatsapp-web.js';
import { WhatsAppWebJsAdapter } from './whatsapp-web-js.adapter';
+import { __resetWebVersionCache } from '../wa-web-version';
/**
* The web version cache handed to the whatsapp-web.js Client. Unpinned, the library's default is a
@@ -9,12 +13,13 @@ import { WhatsAppWebJsAdapter } from './whatsapp-web-js.adapter';
describe('whatsapp-web.js web version cache', () => {
let clientInitSpy: jest.SpyInstance;
let savedWebVersion: string | undefined;
+ let dataDir: string;
const launchedCacheOption = async (webVersion: string): Promise<unknown> => {
process.env.WWEBJS_WEB_VERSION = webVersion;
const adapter = new WhatsAppWebJsAdapter({
sessionId: 'sess-web-version-cache',
- sessionDataPath: './data/sessions',
+ sessionDataPath: dataDir,
puppeteer: {},
});
await adapter.initialize({});
@@ -22,6 +27,8 @@ describe('whatsapp-web.js web version cache', () => {
};
beforeEach(() => {
+ __resetWebVersionCache();
+ dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wwebjs-web-version-'));
savedWebVersion = process.env.WWEBJS_WEB_VERSION;
// Build the real Client, whose options are merged over the library defaults, but launch no browser.
clientInitSpy = jest
@@ -30,6 +37,9 @@ describe('whatsapp-web.js web version cache', () => {
});
afterEach(() => {
+ jest.restoreAllMocks();
+ __resetWebVersionCache();
+ fs.rmSync(dataDir, { recursive: true, force: true });
clientInitSpy.mockRestore();
if (savedWebVersion === undefined) {
delete process.env.WWEBJS_WEB_VERSION;
@@ -42,7 +52,33 @@ describe('whatsapp-web.js web version cache', () => {
expect(await launchedCacheOption('off')).toEqual({ type: 'none' });
});
- it('keeps the remote cache for a pinned build', async () => {
- expect(await launchedCacheOption('2.3000.1000000000')).toMatchObject({ type: 'remote' });
+ // whatsapp-web.js's remote cache fetches with no timeout and loads the live build on failure, so a
+ // pinned build's HTML is downloaded first and served as a strict file on the data volume.
+ it('serves a pinned build from a strict local cache under the session data path', async () => {
+ const html = `<html>${'x'.repeat(2048)}</html>`;
+ jest
+ .spyOn(globalThis, 'fetch')
+ .mockResolvedValue({ ok: true, status: 200, text: () => Promise.resolve(html) } as unknown as Response);
+
+ expect(await launchedCacheOption('2.3000.1000000000')).toEqual({
+ type: 'local',
+ path: path.join(path.resolve(dataDir), '.wa-web-cache'),
+ strict: true,
+ });
+ expect(fs.readFileSync(path.join(dataDir, '.wa-web-cache', '2.3000.1000000000.html'), 'utf8')).toBe(html);
+
+ // The library's own strict cache finds the file under the name it looks for.
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ const LocalWebCache = require('whatsapp-web.js/src/webCache/LocalWebCache') as new (options: object) => {
+ resolve: (version: string) => Promise<string | null>;
+ };
+ const cache = new LocalWebCache({ path: path.join(path.resolve(dataDir), '.wa-web-cache'), strict: true });
+ await expect(cache.resolve('2.3000.1000000000')).resolves.toBe(html);
+ });
+
+ it('runs unpinned when the pinned build cannot be downloaded', async () => {
+ jest.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('getaddrinfo ENOTFOUND'));
+
+ expect(await launchedCacheOption('2.3000.1000000000')).toEqual({ type: 'none' });
});
});
diff --git a/src/engine/wa-web-version.spec.ts b/src/engine/wa-web-version.spec.ts
index dc8094947..72050e058 100644
--- a/src/engine/wa-web-version.spec.ts
+++ b/src/engine/wa-web-version.spec.ts
@@ -3,8 +3,12 @@ jest.mock('../common/services/logger.service', () => ({
createLogger: () => ({ warn: mockWarn, log: jest.fn(), error: jest.fn(), info: jest.fn(), debug: jest.fn() }),
}));
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
import {
__resetWebVersionCache,
+ PINNED_HTML_TIMEOUT_MS,
pickSettledWebVersion,
resolveCurrentWebVersion,
resolveWebVersionPin,
@@ -270,3 +274,145 @@ describe('resolveCurrentWebVersion failure warning', () => {
expect(mockWarn).toHaveBeenCalledTimes(1);
});
});
+
+// whatsapp-web.js fetches a remote pin's HTML with no timeout and, non-strict, loads the live build
+// when that fails, silently. The HTML is now fetched here, bounded, and served as a strict local file.
+describe('resolveWebVersionPin with a cache directory', () => {
+ const ORIGINAL_ENV = process.env.WWEBJS_WEB_VERSION;
+ const VERSION = '2.3000.1234';
+ const HTML = `<!DOCTYPE html><html><head></head><body>${'x'.repeat(2048)}</body></html>`;
+ let dir: string;
+
+ const page = (body: string, status = 200) => ({ ok: status < 400, status, text: () => Promise.resolve(body) });
+ const htmlWarning = (): Record<string, unknown> | undefined =>
+ (mockWarn.mock.calls as [string, Record<string, unknown>][]).find(
+ ([, meta]) => meta?.action === 'web_version_html_unavailable',
+ )?.[1];
+
+ beforeEach(() => {
+ __resetWebVersionCache();
+ mockWarn.mockClear();
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wa-web-cache-'));
+ process.env.WWEBJS_WEB_VERSION = VERSION;
+ });
+ afterEach(() => {
+ jest.useRealTimers();
+ __resetWebVersionCache();
+ fs.rmSync(dir, { recursive: true, force: true });
+ if (ORIGINAL_ENV === undefined) delete process.env.WWEBJS_WEB_VERSION;
+ else process.env.WWEBJS_WEB_VERSION = ORIGINAL_ENV;
+ });
+
+ it('writes the HTML and answers a strict local cache for it', async () => {
+ const fetcher = jest.fn(() => Promise.resolve(page(HTML)));
+
+ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toEqual({
+ webVersion: VERSION,
+ webVersionCache: { type: 'local', path: dir, strict: true },
+ });
+ expect(fs.readFileSync(path.join(dir, `${VERSION}.html`), 'utf8')).toBe(HTML);
+ expect(fs.readdirSync(dir)).toEqual([`${VERSION}.html`]);
+ expect(htmlWarning()).toBeUndefined();
+ });
+
+ it('sends URL credentials as a Basic header, since fetch refuses a URL that carries them', async () => {
+ process.env.WWEBJS_WEB_VERSION_REMOTE_PATH = 'https://u:[email protected]/{version}.html';
+ try {
+ const fetcher = jest.fn(() => Promise.resolve(page(HTML)));
+
+ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toMatchObject({
+ webVersionCache: { type: 'local' },
+ });
+ expect(fetcher).toHaveBeenCalledWith(
+ `https://mirror.example/${VERSION}.html`,
+ expect.objectContaining({ headers: { Authorization: 'Basic dTpw' } }),
+ );
+
+ fetcher.mockResolvedValue(page('', 503));
+ __resetWebVersionCache();
+ await resolveWebVersionPin(fetcher as never, dir);
+ expect(htmlWarning()?.remotePath).toBe(`https://mirror.example/${VERSION}.html`);
+ const logged = JSON.stringify(mockWarn.mock.calls);
+ expect(logged).not.toContain('u:p@');
+ } finally {
+ delete process.env.WWEBJS_WEB_VERSION_REMOTE_PATH;
+ }
+ });
+
+ it('removes a build no start has written for a week, and keeps a recent one', async () => {
+ const stale = path.join(dir, '2.3000.1.html');
+ const recent = path.join(dir, '2.3000.2.html');
+ fs.writeFileSync(stale, HTML);
+ fs.writeFileSync(recent, HTML);
+ const eightDaysAgo = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000);
+ fs.utimesSync(stale, eightDaysAgo, eightDaysAgo);
+ const fetcher = jest.fn(() => Promise.resolve(page(HTML)));
+
+ await resolveWebVersionPin(fetcher as never, dir);
+
+ expect(fs.readdirSync(dir).sort()).toEqual(['2.3000.1234.html', '2.3000.2.html']);
+ });
+
+ it('gives up at the bound and drops the pin with a named warning', async () => {
+ jest.useFakeTimers();
+ const fetcher = jest.fn(
+ (_url: string, init: { signal: AbortSignal }) =>
+ new Promise((_resolve, reject) => init.signal.addEventListener('abort', () => reject(new Error('aborted')))),
+ );
+
+ const pending = resolveWebVersionPin(fetcher as never, dir);
+ await jest.advanceTimersByTimeAsync(PINNED_HTML_TIMEOUT_MS);
+
+ await expect(pending).resolves.toBeUndefined();
+ const warning = htmlWarning();
+ expect(warning?.webVersion).toBe(VERSION);
+ expect(warning?.reason).toContain(`${PINNED_HTML_TIMEOUT_MS} ms`);
+ expect(warning?.remotePath).toContain(VERSION);
+ });
+
+ it.each([
+ ['a non-ok status', page(HTML, 404), 'HTTP 404'],
+ ['a body too short to be the page', page('<html></html>'), 'not a WhatsApp Web page'],
+ ['a body that is not HTML', page('x'.repeat(4096)), 'not a WhatsApp Web page'],
+ ])('drops the pin on %s and writes nothing', async (_label, response, reason) => {
+ const fetcher = jest.fn(() => Promise.resolve(response));
+
+ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toBeUndefined();
+ expect(htmlWarning()?.reason).toContain(reason);
+ expect(fs.readdirSync(dir)).toEqual([]);
+ });
+
+ it('fetches a build once, shares a concurrent fetch, and retries after a failure', async () => {
+ const fetcher = jest.fn().mockResolvedValueOnce(page('', 503)).mockResolvedValue(page(HTML));
+
+ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toBeUndefined();
+ const [a, b] = await Promise.all([
+ resolveWebVersionPin(fetcher as never, dir),
+ resolveWebVersionPin(fetcher as never, dir),
+ ]);
+ await resolveWebVersionPin(fetcher as never, dir);
+
+ expect(a?.webVersionCache.type).toBe('local');
+ expect(b?.webVersionCache.type).toBe('local');
+ expect(fetcher).toHaveBeenCalledTimes(2);
+ });
+
+ it('refuses a version that is not a build number, without fetching or writing', async () => {
+ process.env.WWEBJS_WEB_VERSION = '../../etc/x';
+ const fetcher = jest.fn(() => Promise.resolve(page(HTML)));
+
+ await expect(resolveWebVersionPin(fetcher as never, dir)).resolves.toBeUndefined();
+ expect(fetcher).not.toHaveBeenCalled();
+ expect(fs.readdirSync(dir)).toEqual([]);
+ expect(htmlWarning()).toBeDefined();
+ });
+
+ it('keeps the remote shape when no cache directory is given', async () => {
+ const fetcher = jest.fn();
+
+ await expect(resolveWebVersionPin(fetcher as never)).resolves.toMatchObject({
+ webVersionCache: { type: 'remote' },
+ });
+ expect(fetcher).not.toHaveBeenCalled();
+ });
+});
diff --git a/src/engine/wa-web-version.ts b/src/engine/wa-web-version.ts
index c85edb598..901ac1361 100644
--- a/src/engine/wa-web-version.ts
+++ b/src/engine/wa-web-version.ts
@@ -4,11 +4,16 @@
* pulling in the heavy whatsapp-web.js module and breaking engine lazy-loading.
*/
+import { randomUUID } from 'crypto';
+import * as fs from 'fs';
+import * as path from 'path';
import { createLogger } from '../common/services/logger.service';
const logger = createLogger('WebVersion');
-export type WebVersionPin = { webVersion: string; webVersionCache: { type: 'remote'; remotePath: string } };
+type RemoteWebVersionPin = { webVersion: string; webVersionCache: { type: 'remote'; remotePath: string } };
+type LocalWebVersionPin = { webVersion: string; webVersionCache: { type: 'local'; path: string; strict: true } };
+export type WebVersionPin = RemoteWebVersionPin | LocalWebVersionPin;
// The wppconnect-team/wa-version registry tracks the current known-good WhatsApp Web build. Its
// `currentVersion` is what we pin to when the operator hasn't chosen one — far more reliable than
@@ -42,6 +47,18 @@ let lastFailureAt = 0;
let warnedRemoteTrust = false;
+// The pinned build's HTML. whatsapp-web.js's own remote cache fetches it with no timeout and, being
+// non-strict, loads WhatsApp's live build when the fetch fails: the #488 class the pin exists to
+// prevent. A non-OK answer falls back with nothing logged, a network error reaches only a bare
+// console.error, and a hang never ends. It is fetched here instead, bounded, and handed to the library
+// as a strict local cache. A successful download is kept per URL for the life of the process (a
+// build's HTML does not change); a failure is not, so the next start retries.
+export const PINNED_HTML_TIMEOUT_MS = 10_000;
+const PINNED_HTML_MIN_LENGTH = 1024;
+const PINNED_HTML_KEEP_MS = 7 * 24 * 60 * 60 * 1000;
+const pinnedHtml = new Map<string, string>();
+const pinnedHtmlInFlight = new Map<string, Promise<string>>();
+
/** Test-only: reset the resolved-version cache between cases. */
export function __resetWebVersionCache(): void {
cachedCurrentVersion = undefined;
@@ -49,6 +66,8 @@ export function __resetWebVersionCache(): void {
inFlight = null;
lastFailureAt = 0;
warnedRemoteTrust = false;
+ pinnedHtml.clear();
+ pinnedHtmlInFlight.clear();
}
/**
@@ -57,7 +76,7 @@ export function __resetWebVersionCache(): void {
* so pinning is a trust decision the operator must make knowingly — the log states the source and
* the opt-outs. Once-only: resolveWebVersionPin runs on every session (re)start.
*/
-function warnRemoteTrustOnce(pin: WebVersionPin): void {
+function warnRemoteTrustOnce(pin: RemoteWebVersionPin): void {
if (warnedRemoteTrust) return;
warnedRemoteTrust = true;
logger.warn(
@@ -65,7 +84,7 @@ function warnRemoteTrustOnce(pin: WebVersionPin): void {
{
action: 'web_version_remote_pin',
webVersion: pin.webVersion,
- remotePath: pin.webVersionCache.remotePath,
+ remotePath: splitCredentials(pin.webVersionCache.remotePath).href,
optOut:
'set WWEBJS_WEB_VERSION=off for the first-party build served by WhatsApp, or point WWEBJS_WEB_VERSION_REMOTE_PATH at an operator-controlled copy',
},
@@ -107,7 +126,7 @@ function warnResolveFailed(reason: string, previous: string | null): void {
});
}
-function buildRemotePin(version: string): WebVersionPin {
+function buildRemotePin(version: string): RemoteWebVersionPin {
const template = process.env.WWEBJS_WEB_VERSION_REMOTE_PATH?.trim() || DEFAULT_REMOTE_TEMPLATE;
return {
webVersion: version,
@@ -198,23 +217,154 @@ export async function resolveCurrentWebVersion(fetcher: typeof fetch = fetch): P
* from the wa-version registry and pin it; if that fetch fails, keep the previously resolved
* build, or fall back to native auto-select when none was ever resolved.
* `WWEBJS_WEB_VERSION_REMOTE_PATH` overrides the HTML URL template (`{version}` placeholder).
+ * With `cacheDir`, the pinned HTML is downloaded there first and the pin becomes a strict local cache;
+ * a download that fails (or takes over PINNED_HTML_TIMEOUT_MS) drops the pin with a named warning.
* The auto-resolve replaces whatsapp-web.js's unreliable default that caused #488 (scan → stuck →
* disconnect loop) on Docker setups where no version was pinned.
*/
-export async function resolveWebVersionPin(fetcher: typeof fetch = fetch): Promise<WebVersionPin | undefined> {
+export function resolveWebVersionPin(fetcher?: typeof fetch): Promise<RemoteWebVersionPin | undefined>;
+export function resolveWebVersionPin(
+ fetcher: typeof fetch | undefined,
+ cacheDir: string,
+): Promise<WebVersionPin | undefined>;
+export async function resolveWebVersionPin(
+ fetcher: typeof fetch = fetch,
+ cacheDir?: string,
+): Promise<WebVersionPin | undefined> {
const raw = process.env.WWEBJS_WEB_VERSION?.trim();
const lc = raw?.toLowerCase();
+ let pin: RemoteWebVersionPin;
if (raw && lc !== 'off' && lc !== 'latest' && lc !== 'auto') {
- const pin = buildRemotePin(raw); // operator-pinned exact version
- warnRemoteTrustOnce(pin);
- return pin;
+ pin = buildRemotePin(raw); // operator-pinned exact version
+ } else {
+ if (lc === 'off') return undefined; // explicit escape hatch → native auto-select
+ const current = await resolveCurrentWebVersion(fetcher);
+ if (!current) return undefined;
+ pin = buildRemotePin(current);
}
- if (lc === 'off') return undefined; // explicit escape hatch → native auto-select
- const current = await resolveCurrentWebVersion(fetcher);
- if (!current) return undefined;
- const pin = buildRemotePin(current);
warnRemoteTrustOnce(pin);
- return pin;
+ return cacheDir ? localisePin(pin, cacheDir, fetcher) : pin;
+}
+
+/**
+ * Download the pinned HTML (bounded) into `<cacheDir>/<version>.html` and answer a strict local cache
+ * for it. When it cannot be had, say so by name and answer no pin: the session then loads the live
+ * build, as the docs promise, instead of hanging on an unbounded fetch that ends the same way.
+ */
+async function localisePin(
+ pin: RemoteWebVersionPin,
+ cacheDir: string,
+ fetcher: typeof fetch,
+): Promise<WebVersionPin | undefined> {
+ const { webVersion } = pin;
+ const { remotePath } = pin.webVersionCache;
+ try {
+ // The version becomes a file name, and an operator sets it: no separators, no leading dots.
+ if (!/^\d[\w.-]*$/.test(webVersion)) throw new Error('the version is not a WhatsApp Web build number');
+ const html = await fetchPinnedHtml(remotePath, fetcher);
+ writePinnedHtml(cacheDir, webVersion, html);
+ return { webVersion, webVersionCache: { type: 'local', path: cacheDir, strict: true } };
+ } catch (error) {
+ logger.warn('Could not load the pinned WhatsApp Web build; continuing WITHOUT a pin', {
+ action: 'web_version_html_unavailable',
+ reason: error instanceof Error ? error.message : String(error),
+ webVersion,
+ remotePath: splitCredentials(remotePath).href,
+ consequence:
+ "the live WhatsApp Web build loads instead, which on some setups authenticates then never reaches 'ready'",
+ remedy:
+ 'confirm the host can reach remotePath, pin a build the registry still serves in WWEBJS_WEB_VERSION, or point WWEBJS_WEB_VERSION_REMOTE_PATH at a reachable copy',
+ });
+ return undefined;
+ }
+}
+
+function fetchPinnedHtml(remotePath: string, fetcher: typeof fetch): Promise<string> {
+ const cached = pinnedHtml.get(remotePath);
+ if (cached) return Promise.resolve(cached);
+ let pending = pinnedHtmlInFlight.get(remotePath);
+ if (!pending) {
+ pending = downloadPinnedHtml(remotePath, fetcher).finally(() => pinnedHtmlInFlight.delete(remotePath));
+ pinnedHtmlInFlight.set(remotePath, pending);
+ }
+ return pending;
+}
+
+async function downloadPinnedHtml(remotePath: string, fetcher: typeof fetch): Promise<string> {
+ const controller = new AbortController();
+ const timer = setTimeout(() => controller.abort(), PINNED_HTML_TIMEOUT_MS);
+ try {
+ const { href, authorization } = splitCredentials(remotePath);
+ const headers: Record<string, string> = authorization ? { Authorization: authorization } : {};
+ const res = await fetcher(href, { signal: controller.signal, headers });
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
+ const html = await res.text();
+ if (html.length < PINNED_HTML_MIN_LENGTH || !/<html/i.test(html)) {
+ throw new Error('the response is not a WhatsApp Web page');
+ }
+ pinnedHtml.set(remotePath, html);
+ return html;
+ } catch (error) {
+ if (controller.signal.aborted) throw new Error(`no answer within ${PINNED_HTML_TIMEOUT_MS} ms`, { cause: error });
+ throw error;
+ } finally {
+ clearTimeout(timer);
+ }
+}
+
+/**
+ * Move URL userinfo into a Basic Authorization header. Node's fetch refuses a URL that carries
+ * credentials, while the library's own fetcher used to send them this way, so a mirror reached as
+ * https://user:pass@host/... keeps working. The credential-free URL is also what gets logged.
+ */
+function splitCredentials(remotePath: string): { href: string; authorization?: string } {
+ let url: URL;
+ try {
+ url = new URL(remotePath);
+ } catch {
+ return { href: remotePath };
+ }
+ if (!url.username && !url.password) return { href: remotePath };
+ const decode = (part: string): string => {
+ try {
+ return decodeURIComponent(part);
+ } catch {
+ return part;
+ }
+ };
+ const authorization = `Basic ${Buffer.from(`${decode(url.username)}:${decode(url.password)}`).toString('base64')}`;
+ url.username = '';
+ url.password = '';
+ return { href: url.href, authorization };
+}
+
+/**
+ * Write through a unique temp file and rename it into place: several sessions, or several nodes on
+ * one data volume, can write the same build at once, and the strict cache must never read half a file.
+ */
+function writePinnedHtml(cacheDir: string, version: string, html: string): void {
+ fs.mkdirSync(cacheDir, { recursive: true });
+ const file = path.join(cacheDir, `${version}.html`);
+ const tmp = `${file}.${randomUUID()}.tmp`;
+ try {
+ fs.writeFileSync(tmp, html);
+ fs.renameSync(tmp, file);
+ } catch (error) {
+ fs.rmSync(tmp, { force: true });
+ throw error;
+ }
+ // The directory sits on the backed-up data volume, and every build pinned over the months would
+ // otherwise stay there. Each start rewrites its own file, so a build any session still starts on
+ // is never a week old: only those that are not get removed.
+ for (const name of fs.readdirSync(cacheDir)) {
+ const other = path.join(cacheDir, name);
+ if (other === file) continue;
+ try {
+ if (Date.now() - fs.statSync(other).mtimeMs > PINNED_HTML_KEEP_MS) fs.rmSync(other, { force: true });
+ } catch {
+ // Another writer renamed or removed it first; nothing left to prune.
+ }
+ }
}
/**