Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(wwebjs): report a message-id backport left half applied

Yudhi Armyndharisedfd09486ab7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index a532e5a35..d0bc61bac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -124,6 +124,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Bound `GET /api/search` to 1000 characters and 32 distinct words and run a repeated word once, so one request can no longer hold the event loop on SQLite for seconds.
- Print the startup banner's API Docs URL only when Swagger is served, so a production boot no longer points at a `404`.
- Decode numeric and common named character references in a Baileys link preview's title and description, so `’` and `é` no longer reach the recipient as written.
+- Log an error at whatsapp-web.js start when the message-id backport is only partly applied, naming the files it did not reach.
### Documentation
diff --git a/docs/12-troubleshooting-faq.md b/docs/12-troubleshooting-faq.md
index 7ca127dbc..00fe617d1 100644
--- a/docs/12-troubleshooting-faq.md
+++ b/docs/12-troubleshooting-faq.md
@@ -736,7 +736,8 @@ curl -H "X-API-Key: $API_KEY" \
- `POST /api/sessions/{id}/messages/send-text` returns `{"statusCode":500,"message":"Internal server error"}` — but the message _is_ delivered
- Logs show `the engine returned no message for this send, so it may not have been delivered`
- Unrelated operations fail with the minified error `r: r`: `GET /api/sessions/{id}/chats`, media downloads, typing indicators
-- Startup logs may contain `The installed whatsapp-web.js is missing the message-id backport…`
+- Startup logs may contain `The installed whatsapp-web.js is missing the message-id backport…`, or
+ `The installed whatsapp-web.js carries only part of the message-id backport…` after an interrupted install
**Cause:** WhatsApp Web 2.3000.x renamed the internal message-id property that whatsapp-web.js
reads. OpenWA ships a backport that restores it, applied at install time by
diff --git a/scripts/patch-wwebjs-201832.js b/scripts/patch-wwebjs-201832.js
index 28d5eae80..0ca843a5e 100644
--- a/scripts/patch-wwebjs-201832.js
+++ b/scripts/patch-wwebjs-201832.js
@@ -79,6 +79,24 @@ function siteLanded(wwjsDir, rel) {
return marker.test(fs.readFileSync(path.join(wwjsDir, rel), 'utf8'));
}
+/**
+ * The REQUIRED_SITES a backport this patcher began did not reach, by relative path. The tree is judged
+ * ours by the id read in the Message constructor: without it the backport never started (the caller's
+ * own check says so) or upstream fixed the tree its own way. A file that cannot be read is not counted,
+ * since an install that cannot be inspected is not evidence of a broken one.
+ */
+function missingSites(wwjsDir = DEFAULT_WWJS) {
+ const landed = rel => {
+ try {
+ return siteLanded(wwjsDir, rel);
+ } catch {
+ return undefined;
+ }
+ };
+ if (landed('src/structures/Message.js') !== true) return [];
+ return REQUIRED_SITES.filter(([rel]) => landed(rel) === false).map(([rel]) => rel);
+}
+
/**
* Flag an error raised against a tree that is no longer pristine — either this run wrote to it, or a
* previous run left it half-patched. `--best-effort` degrades on a pre-flight failure (no `patch`
@@ -331,6 +349,8 @@ if (require.main === module) {
module.exports = {
applyBackport,
+ missingSites,
+ REQUIRED_SITES,
normalizeArtifactPath,
gitApplyLeftTreeUntouched,
DEFAULT_WWJS,
diff --git a/src/engine/adapters/wwebjs-backport-check.spec.ts b/src/engine/adapters/wwebjs-backport-check.spec.ts
index 5fef8863a..04212b948 100644
--- a/src/engine/adapters/wwebjs-backport-check.spec.ts
+++ b/src/engine/adapters/wwebjs-backport-check.spec.ts
@@ -1,7 +1,20 @@
import * as fs from 'fs';
import * as os from 'os';
import * as path from 'path';
-import { isBackportMissing } from './wwebjs-backport-check';
+import {
+ BACKPORT_MISSING_MESSAGE,
+ backportProblem,
+ isBackportMissing,
+ partialBackportSites,
+} from './wwebjs-backport-check';
+
+// The patcher is a CommonJS build script; its site list is what a finished backport is measured against.
+const {
+ REQUIRED_SITES,
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+} = require('../../../scripts/patch-wwebjs-201832') as {
+ REQUIRED_SITES: Array<[string, RegExp]>;
+};
/**
* Guards the startup diagnostic for an unpatched whatsapp-web.js (#889). The cost of getting this
@@ -42,6 +55,63 @@ describe('isBackportMissing', () => {
expect(isBackportMissing(path.join(os.tmpdir(), 'wwjs-not-installed-here'))).toBe(false);
});
+ /** An install the backport finished: every site carries the text its marker looks for. */
+ function wholeInstall(): string {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wwjs-check-'));
+ tmpDirs.push(dir);
+ for (const [rel, marker] of REQUIRED_SITES) {
+ fs.mkdirSync(path.dirname(path.join(dir, rel)), { recursive: true });
+ fs.writeFileSync(path.join(dir, rel), marker.source.replace(/\\(.)/g, '$1'));
+ }
+ return dir;
+ }
+
+ // The patcher writes file by file, so a run killed part-way (out of memory, Ctrl-C, a full disk) leaves
+ // Message.js patched and the rest not. The patcher itself refuses that tree, and every later start of it
+ // would otherwise read as healthy.
+ describe('a backport that was begun and not finished', () => {
+ it('is not reported for a tree the patcher finished', () => {
+ const dir = wholeInstall();
+
+ expect(isBackportMissing(dir)).toBe(false);
+ expect(partialBackportSites(dir)).toEqual([]);
+ expect(backportProblem(dir)).toBeUndefined();
+ });
+
+ it('names the sites the patcher did not reach', () => {
+ const dir = wholeInstall();
+ fs.writeFileSync(path.join(dir, 'src', 'util', 'Injected', 'Utils.js'), '_serialized: msg.id._serialized');
+ fs.writeFileSync(path.join(dir, 'src', 'Client.js'), 'res.gid._serialized');
+
+ expect(isBackportMissing(dir)).toBe(false);
+ expect(partialBackportSites(dir)).toEqual(['src/util/Injected/Utils.js', 'src/Client.js']);
+ expect(backportProblem(dir)).toContain('src/util/Injected/Utils.js, src/Client.js');
+ });
+
+ it('answers a tree with no backport at all with the missing-backport message, not a list of sites', () => {
+ const dir = wholeInstall();
+ fs.writeFileSync(path.join(dir, 'src', 'structures', 'Message.js'), 'this.id = data.id;');
+
+ expect(partialBackportSites(dir)).toEqual([]);
+ expect(backportProblem(dir)).toBe(BACKPORT_MISSING_MESSAGE);
+ });
+
+ it('leaves a tree fixed upstream in its own way alone', () => {
+ const dir = install('this.id = data.id._serialized || data.id.$1;');
+
+ expect(partialBackportSites(dir)).toEqual([]);
+ expect(backportProblem(dir)).toBeUndefined();
+ });
+
+ it('does not count a site whose file is not there', () => {
+ const dir = wholeInstall();
+ fs.rmSync(path.join(dir, 'src', 'structures', 'GroupChat.js'));
+ fs.writeFileSync(path.join(dir, 'src', 'structures', 'Chat.js'), 'this.id = data.id;');
+
+ expect(partialBackportSites(dir)).toEqual(['src/structures/Chat.js']);
+ });
+ });
+
it('can reach the file it reads in a real install', () => {
// The no-argument path fails open, so a resolution that silently stopped working — an `exports`
// map on a future whatsapp-web.js would do it — would retire the check without failing anything.
diff --git a/src/engine/adapters/wwebjs-backport-check.ts b/src/engine/adapters/wwebjs-backport-check.ts
index e67f8cbbc..9aee7079a 100644
--- a/src/engine/adapters/wwebjs-backport-check.ts
+++ b/src/engine/adapters/wwebjs-backport-check.ts
@@ -28,6 +28,21 @@ export const BACKPORT_MISSING_MESSAGE =
'`node scripts/patch-wwebjs-201832.js` (or reinstall with `npm install`) and restart. ' +
'See docs/12-troubleshooting-faq.md.';
+/**
+ * The message for a tree the patcher began and did not finish: it kills a run's later files (an
+ * out-of-memory kill, Ctrl-C or a full disk while `npm install` ran), and the patcher refuses the tree
+ * from then on, so reapplying it does not help.
+ */
+export function partialBackportMessage(sites: string[]): string {
+ return (
+ 'The installed whatsapp-web.js carries only part of the message-id backport this build requires: ' +
+ `${sites.join(', ')} did not land, usually because an install was interrupted while the patch was ` +
+ 'being written. On current WhatsApp Web builds inbound messages and chat reads will fail with empty ids ' +
+ 'or "r: r". The patcher cannot repair that tree: reinstall the dependency ' +
+ '(`rm -rf node_modules/whatsapp-web.js && npm ci`) and restart. See docs/12-troubleshooting-faq.md.'
+ );
+}
+
/**
* Whether the installed whatsapp-web.js is known NOT to carry the backport.
*
@@ -43,3 +58,29 @@ export function isBackportMissing(wwjsDir?: string): boolean {
return false;
}
}
+
+/**
+ * The sites of a backport the patcher began and did not finish, by relative path: the patcher's own
+ * answer, so the guard and the patcher cannot disagree about which sites a finished backport has.
+ * Empty when the patcher cannot be loaded, for the same reason {@link isBackportMissing} fails open.
+ */
+export function partialBackportSites(wwjsDir?: string): string[] {
+ try {
+ const dir = wwjsDir ?? path.dirname(require.resolve('whatsapp-web.js/package.json'));
+ // `scripts/` sits beside dist/ and src/, three levels up, where the image copies the patchers.
+ // eslint-disable-next-line @typescript-eslint/no-require-imports
+ const patcher = require(path.join(__dirname, '..', '..', '..', 'scripts', 'patch-wwebjs-201832.js')) as {
+ missingSites?: (dir: string) => string[];
+ };
+ return patcher.missingSites?.(dir) ?? [];
+ } catch {
+ return [];
+ }
+}
+
+/** What the startup guard should say about the installed backport, or undefined when it needs no word. */
+export function backportProblem(wwjsDir?: string): string | undefined {
+ if (isBackportMissing(wwjsDir)) return BACKPORT_MISSING_MESSAGE;
+ const sites = partialBackportSites(wwjsDir);
+ return sites.length ? partialBackportMessage(sites) : undefined;
+}
diff --git a/src/engine/adapters/wwebjs-lifecycle.ts b/src/engine/adapters/wwebjs-lifecycle.ts
index b1844330d..e48d18ac1 100644
--- a/src/engine/adapters/wwebjs-lifecycle.ts
+++ b/src/engine/adapters/wwebjs-lifecycle.ts
@@ -16,7 +16,7 @@ import { resolveWebVersionPin } from '../wa-web-version';
import { resolveAuthTimeoutMs, resolveEngineInitTimeoutMs } from '../engine-init-timeout';
import { killOrphanedChromiumProcesses, removeStaleSingletonFiles } from './chromium-profile-hygiene';
import { isSupportedProxyUrl, buildProxyLaunchConfig } from './wwebjs-proxy';
-import { BACKPORT_MISSING_MESSAGE, isBackportMissing } from './wwebjs-backport-check';
+import { backportProblem } from './wwebjs-backport-check';
import { unappliedPatches, unappliedPatchesMessage } from './engine-patch-status';
import { type EvaluatablePage, reportMissingCallHook } from './wwebjs-call-hook-check';
import { reportRunningWebBuild } from './wwebjs-running-build';
@@ -257,8 +257,9 @@ export class WwebjsLifecycle {
// An install that skipped the message-id backport fails later with errors that name no cause
// (#889) — say so here instead, while the operator is still looking at the startup logs.
- if (isBackportMissing()) {
- this.host.logger.error(BACKPORT_MISSING_MESSAGE);
+ const backportProblemText = backportProblem();
+ if (backportProblemText) {
+ this.host.logger.error(backportProblemText);
}
// The other whatsapp-web.js patchers fail the same way and were equally silent about it.