Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(scripts): reject SDK methods that use an undeclared verb

Yudhi Armyndharis0ff57a2a83e2
diff --git a/package.json b/package.json
index b979be595..b1159dc39 100644
--- a/package.json
+++ b/package.json
@@ -41,7 +41,7 @@
"lint": "eslint \"{src,apps,libs,test}/**/*.ts\"",
"lint:fix": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
"test": "jest",
- "test:scripts": "node --test scripts/postinstall.spec.js scripts/patch-wwebjs-newsletter-preview.spec.js scripts/patch-wwebjs-status.spec.js scripts/patch-wwebjs-ready-sync.spec.js scripts/patch-wwebjs-participant-arity.spec.js scripts/patch-wwebjs-block.spec.js scripts/patch-wwebjs-group-description.spec.js scripts/patch-wwebjs-media-id.spec.js scripts/patch-wwebjs-send-error.spec.js scripts/patch-baileys-appstate.spec.js scripts/patch-baileys-newsletter-create.spec.js scripts/dockerfile-patchers.spec.js scripts/check-upstream-surface.spec.mjs scripts/check-sdk-docs.spec.mjs scripts/check-audit.spec.mjs scripts/check-contract-shapes.spec.mjs scripts/cli-entrypoint-guard.spec.mjs",
+ "test:scripts": "node --test scripts/postinstall.spec.js scripts/patch-wwebjs-newsletter-preview.spec.js scripts/patch-wwebjs-status.spec.js scripts/patch-wwebjs-ready-sync.spec.js scripts/patch-wwebjs-participant-arity.spec.js scripts/patch-wwebjs-block.spec.js scripts/patch-wwebjs-group-description.spec.js scripts/patch-wwebjs-media-id.spec.js scripts/patch-wwebjs-send-error.spec.js scripts/patch-baileys-appstate.spec.js scripts/patch-baileys-newsletter-create.spec.js scripts/dockerfile-patchers.spec.js scripts/check-upstream-surface.spec.mjs scripts/check-sdk-docs.spec.mjs scripts/check-audit.spec.mjs scripts/check-contract-shapes.spec.mjs scripts/check-sdk-coverage.spec.mjs scripts/cli-entrypoint-guard.spec.mjs",
"test:docs": "jest src/common/changelog-sections.spec.ts src/common/ci-privilege-gate.spec.ts src/common/docs-ci-jobs.spec.ts src/common/docs-coverage-policy.spec.ts src/common/docs-metrics-list.spec.ts src/common/docs-next-version.spec.ts src/common/openapi/docs-06-contract.spec.ts src/common/test-lane-partition.spec.ts src/config/docs-env-example.spec.ts src/config/openapi-contract.spec.ts src/config/openapi-export-pins.spec.ts src/config/wa-web-version-example-pin.spec.ts src/engine/docs-29-counts.spec.ts src/engine/docs-27-backfill-engine.spec.ts src/engine/engine-inventory-parity.spec.ts src/engine/engine-parity.spec.ts src/engine/inventory-mapping-direction.spec.ts src/engine/adapters/baileys-voice-waveform.spec.ts src/engine/adapters/wwebjs-newsletter-preview.spec.ts src/modules/audit/audit-coverage.spec.ts src/modules/auth/global-route-fence-coverage.spec.ts src/modules/auth/query-session-scope-coverage.spec.ts src/modules/docker/compose-network.spec.ts src/modules/queue/bull-board-mount-coverage.spec.ts src/common/release-gate-parity.spec.ts src/database/migrations/__tests__/migration-drift.spec.ts --testPathIgnorePatterns=/node_modules/",
"test:watch": "jest --watch",
"test:cov": "jest --coverage",
diff --git a/scripts/check-sdk-coverage.mjs b/scripts/check-sdk-coverage.mjs
index c0fbfcf1d..7a44a2ca2 100644
--- a/scripts/check-sdk-coverage.mjs
+++ b/scripts/check-sdk-coverage.mjs
@@ -15,7 +15,8 @@
* client, not just the route.
*
* SCOPE, stated so the guarantee is not read wider than it is:
- * - Asserts a route is REACHABLE from each client, not that its method, body or response match.
+ * - Asserts a route is REACHABLE from each client with the verbs the contract declares on it,
+ * not that its body or response match.
* - The exclusion list is PARSED from sdk/README.md, so the gate and the promise cannot drift.
*
* The harvester is deliberately GENEROUS: it over-approximates what each client builds. That is the
@@ -26,7 +27,7 @@
* Run locally: `npm run check:sdk-coverage`.
*/
import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
// fileURLToPath, not URL.pathname: the latter stays percent-encoded, so a checkout under a path
@@ -247,9 +248,10 @@ if (!errors.length) {
// The path layer above proves each client REACHES a route; a shared path can still miss a VERB
// entirely; the profile-picture route carried PUT in every client while its DELETE shipped in
// none, and the path gate stayed green because the PUT satisfied it. This layer asks the verb
-// question: for every contract path published with MORE THAN ONE verb, each client must build
-// that path with every verb the contract declares on it. Multi-verb paths only; a single-verb
-// path is already fully proven by the layer above.
+// question in both directions. For every contract path published with MORE THAN ONE verb, each
+// client must build that path with every verb the contract declares on it. And every verb a client
+// builds on a contract path must be one the contract declares there, which is what covers the
+// single-verb paths: the path layer only proves the path is reached, never with which verb.
const VERBS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
/** Join a concatenated path expression: literals verbatim, code between them becomes a `*`. */
@@ -309,6 +311,23 @@ const goVerbPairs = (dir) => {
return pairs;
};
+/**
+ * Python splits one path across adjacent literals (`f"/api/sessions/{a}/groups/{b}"` then
+ * `"/membership-requests/approve"`), which it concatenates implicitly; join them.
+ */
+export const joinPythonLiterals = (expr) => [...expr.matchAll(/"([^"]*)"/g)].map((m) => m[1]).join('');
+
+/** The `VERB path` pairs a client builds on a contract path that does not declare that verb. */
+export function undeclaredVerbPairs(sdkName, pairs, specByPath) {
+ const out = [];
+ for (const pair of pairs) {
+ const [verb, path] = pair.split(' ');
+ const operations = specByPath.get(path);
+ if (operations && !operations[verb.toLowerCase()]) out.push(`${verb} ${path}: built by ${sdkName}, not declared by the contract`);
+ }
+ return out;
+}
+
const verbPairsOf = (sdk) => {
if (sdk.name === 'go') return goVerbPairs(join(root, sdk.dir));
const pairs = new Set();
@@ -318,13 +337,13 @@ const verbPairsOf = (sdk) => {
sdk.name === 'javascript'
? [/(GET|POST|PUT|PATCH|DELETE)'\s*,\s*[\s\S]{0,80}?path:\s*[`'"]([^`'"]+)[`'"]/g]
: sdk.name === 'python'
- ? [/\.request\(\s*"(GET|POST|PUT|PATCH|DELETE)"\s*,\s*f?"([^"]+)"/g]
+ ? [/\.request\(\s*"(GET|POST|PUT|PATCH|DELETE)"\s*,\s*((?:f?"[^"\n]*"\s*)+)/g]
: sdk.name === 'php'
? [/->request\(\s*'(GET|POST|PUT|PATCH|DELETE)'\s*,\s*['"]([^'"]+)['"]/g]
: [/HttpMethod\.(GET|POST|PUT|PATCH|DELETE)\s*,\s*([\s\S]{2,400}?)\s*,\s*\n?\s*(?:null|new |[a-z]\w)/g];
for (const re of patterns) {
for (const m of src.matchAll(re)) {
- const path = sdk.name === 'java' ? literalsToPath(m[2]) : m[2];
+ const path = sdk.name === 'java' ? literalsToPath(m[2]) : sdk.name === 'python' ? joinPythonLiterals(m[2]) : m[2];
if (path && path.startsWith('/api/')) pairs.add(`${m[1]} ${normalize(path)}`);
}
}
@@ -332,7 +351,8 @@ const verbPairsOf = (sdk) => {
return pairs;
};
-{
+// A spec imports the helpers above; only a direct run reports and exits.
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
const spec = JSON.parse(readFileSync(join(root, 'openapi.json'), 'utf8')).paths;
// Same scope as the path layer: resources the README declares unexposed are not the SDKs' to build.
const specByPath = new Map(Object.entries(spec).map(([k, v]) => [normalize(k), v]));
@@ -351,23 +371,25 @@ const verbPairsOf = (sdk) => {
if (!pairs.has(`${verb} ${path}`)) verbErrors.push(`${verb} ${path} — declared by the contract, built by no ${sdk.name} method`);
}
}
+ // Checked against the whole contract: a client that builds an excluded route still owes it a real verb.
+ verbErrors.push(...undeclaredVerbPairs(sdk.name, pairs, specByPath));
}
if (multi.length < 15) {
console.error('check-sdk-coverage: expected 15+ in-scope multi-verb contract paths, found ' + multi.length);
process.exit(1);
}
if (verbErrors.length) {
- console.error('\n✖ Verbs missing from SDK methods on shared paths:');
+ console.error('\n✖ SDK verbs disagree with the contract:');
for (const e of verbErrors) console.error(` - ${e}`);
process.exit(1);
}
-}
-if (errors.length) {
- console.error('\n✖ The contract publishes routes the SDKs do not expose:');
- for (const e of errors) console.error(` - ${e}`);
- console.error('\nsdk/README.md promises that everything outside its excluded set is exposed.');
- console.error('Add the client method, or add the resource to that list with a reason.\n');
- process.exit(1);
+ if (errors.length) {
+ console.error('\n✖ The contract publishes routes the SDKs do not expose:');
+ for (const e of errors) console.error(` - ${e}`);
+ console.error('\nsdk/README.md promises that everything outside its excluded set is exposed.');
+ console.error('Add the client method, or add the resource to that list with a reason.\n');
+ process.exit(1);
+ }
+ console.log(`✓ SDK contract coverage OK (${inScope.length} in-scope contract paths reachable from all ${SDKS.length} clients).`);
}
-console.log(`✓ SDK contract coverage OK (${inScope.length} in-scope contract paths reachable from all ${SDKS.length} clients).`);
diff --git a/scripts/check-sdk-coverage.spec.mjs b/scripts/check-sdk-coverage.spec.mjs
new file mode 100644
index 000000000..af62445cf
--- /dev/null
+++ b/scripts/check-sdk-coverage.spec.mjs
@@ -0,0 +1,31 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { joinPythonLiterals, undeclaredVerbPairs } from './check-sdk-coverage.mjs';
+
+const specByPath = new Map([
+ ['/api/sessions/*/groups/*', { get: {} }],
+ ['/api/sessions/*/webhooks/*', { put: {}, delete: {} }],
+]);
+
+test('undeclaredVerbPairs flags a verb the contract does not declare on a single-verb path', () => {
+ assert.deepEqual(undeclaredVerbPairs('python', new Set(['POST /api/sessions/*/groups/*']), specByPath), [
+ 'POST /api/sessions/*/groups/*: built by python, not declared by the contract',
+ ]);
+ assert.deepEqual(undeclaredVerbPairs('python', new Set(['GET /api/sessions/*/groups/*']), specByPath), []);
+});
+
+test('undeclaredVerbPairs flags a wrong verb on a multi-verb path', () => {
+ const pairs = new Set(['PUT /api/sessions/*/webhooks/*', 'PATCH /api/sessions/*/webhooks/*']);
+ assert.deepEqual(undeclaredVerbPairs('go', pairs, specByPath), [
+ 'PATCH /api/sessions/*/webhooks/*: built by go, not declared by the contract',
+ ]);
+});
+
+test('undeclaredVerbPairs ignores a pair that is not a contract path', () => {
+ assert.deepEqual(undeclaredVerbPairs('javascript', new Set(['POST /api/sessions/*/messages/*']), specByPath), []);
+});
+
+test('joinPythonLiterals joins a path split across adjacent literals', () => {
+ const expr = 'f"/api/sessions/{a}/groups/{b}"\n "/membership-requests/approve"';
+ assert.equal(joinPythonLiterals(expr), '/api/sessions/{a}/groups/{b}/membership-requests/approve');
+});