Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

ci(sdk): compare field names of loosely typed excluded pairs

Yudhi Armyndharisdc8d6bde8406
diff --git a/scripts/check-contract-shapes.mjs b/scripts/check-contract-shapes.mjs
index 4acc088d8..9c387eff7 100644
--- a/scripts/check-contract-shapes.mjs
+++ b/scripts/check-contract-shapes.mjs
@@ -44,6 +44,14 @@
* the goal is to shrink it to zero (usually by tightening the hand type; where the CONTRACT
* under-describes reality, fix the backend DTO decorator, regenerate, and un-exclude).
*
+ * An excluded pair listed in NAMES_ONLY is still compared by field NAME in both directions (not by
+ * optionality or token), so a renamed or dropped field in it fails the run. Those are the Go and Java
+ * response types whose field TYPES are deliberately looser than the contract: a plain string where the
+ * contract lists a vocabulary keeps a value the server adds later decodable and callers' string
+ * handling compiling, and a defined type or a changed pointer would be a source break for a
+ * published client. Only a pair whose every other field conforms belongs there; one that cannot be
+ * read as wire fields at all (a hand-written MarshalJSON, a client-side flag) stays whole-excluded.
+ *
* A mapping only gates the types somebody remembered to list, so a new DTO used to ship ungated by
* default. The coverage check closes that: every schema an exposed operation sends or returns
* (request bodies and 2xx responses, nested schemas included, the resources sdk/README.md declares
@@ -266,6 +274,15 @@ const EXCLUDED = {
},
};
+/**
+ * Excluded pairs that are still compared by field name (see the header). Each entry must also be in
+ * EXCLUDED: the run fails on one that is not, so a retyped pair cannot keep the weaker comparison.
+ */
+const NAMES_ONLY = {
+ 'sdk/go': ['ContactRecord', 'GroupPictureResponse', 'GroupSettings', 'StatusRecord', 'AuthValidateResponse'],
+ 'sdk/java': ['GroupSettings', 'StatusRecord', 'AuthValidateResponse'],
+};
+
const ACK_SHAPE =
'every client answers it as the shared SuccessResult {success, message?}, which spans the success-only and the success-plus-message acks, so no single schema fits it';
const INVITE_CODE_SHAPE =
@@ -908,8 +925,17 @@ function isSimpleToken(token) {
/**
* Compares one hand type against one schema. Returns an array of human-readable diff lines —
* empty when the pair conforms. Exported for the spec; the CLI loop below is a thin driver.
+ * `namesOnly` keeps the field-name comparison and drops optionality and token (see NAMES_ONLY).
*/
-export function comparePair(handName, handMembers, schemaName, schema, schemas, compareOptionality = true) {
+export function comparePair(
+ handName,
+ handMembers,
+ schemaName,
+ schema,
+ schemas,
+ compareOptionality = true,
+ namesOnly = false,
+) {
const diffs = [];
const schemaFields = parseObjectToken(schemaToken(schema, schemas));
for (const [field, handInfo] of Object.entries(handMembers)) {
@@ -918,6 +944,7 @@ export function comparePair(handName, handMembers, schemaName, schema, schemas,
diffs.push(`hand has "${field}" — contract does not`);
continue;
}
+ if (namesOnly) continue;
if (compareOptionality && handInfo.optional !== sField.optional) {
diffs.push(
`"${field}": hand ${handInfo.optional ? 'optional' : 'required'}, contract ${sField.optional ? 'optional' : 'required'}`,
@@ -1468,6 +1495,7 @@ if (isDirectRun) {
load: () => parseHandTypes(readFileSync(`${REPO_ROOT}${file}`, 'utf8')),
mapping,
excluded: EXCLUDED[file] ?? {},
+ namesOnly: NAMES_ONLY[file] ?? [],
floor: MINIMUM_MAPPED[file],
compareOptionality: true,
sdk: file.startsWith('sdk/'),
@@ -1477,6 +1505,7 @@ if (isDirectRun) {
load: () => parsePythonTypes(readFileSync(`${REPO_ROOT}sdk/python/openwa/types.py`, 'utf8')),
mapping: PYTHON_MAPPING,
excluded: EXCLUDED['sdk/python/openwa/types.py'] ?? {},
+ namesOnly: NAMES_ONLY['sdk/python/openwa/types.py'] ?? [],
floor: MINIMUM_MAPPED['sdk/python/openwa/types.py'],
compareOptionality: true,
sdk: true,
@@ -1486,6 +1515,7 @@ if (isDirectRun) {
load: () => parseGoTypes(goSources()),
mapping: GO_MAPPING,
excluded: EXCLUDED['sdk/go'] ?? {},
+ namesOnly: NAMES_ONLY['sdk/go'] ?? [],
floor: MINIMUM_MAPPED['sdk/go'],
compareOptionality: true,
sdk: true,
@@ -1495,6 +1525,7 @@ if (isDirectRun) {
load: () => parseJavaTypes(javaSources()),
mapping: JAVA_MAPPING,
excluded: EXCLUDED['sdk/java'] ?? {},
+ namesOnly: NAMES_ONLY['sdk/java'] ?? [],
floor: MINIMUM_MAPPED['sdk/java'],
compareOptionality: false,
sdk: true,
@@ -1509,8 +1540,16 @@ if (isDirectRun) {
let fileCompared = 0;
const fileResults = [];
+ for (const name of client.namesOnly.filter(n => !client.excluded[n])) {
+ fileResults.push(
+ ` ${name} is in NAMES_ONLY but not in EXCLUDED: remove it, or the pair is compared by name only`,
+ );
+ failures++;
+ }
+
for (const [handName, target] of Object.entries(client.mapping)) {
- if (client.excluded[handName]) continue;
+ const namesOnly = Boolean(client.excluded[handName]) && client.namesOnly.includes(handName);
+ if (client.excluded[handName] && !namesOnly) continue;
const hand = handTypes[handName];
if (!hand) {
fileResults.push(` MISSING hand type ${handName} (declared in mapping but not found in ${client.label})`);
@@ -1528,7 +1567,7 @@ if (isDirectRun) {
}
fileCompared++;
compared++;
- const diffs = comparePair(handName, hand, schemaName, schema, schemas, client.compareOptionality);
+ const diffs = comparePair(handName, hand, schemaName, schema, schemas, client.compareOptionality, namesOnly);
if (diffs.length) {
fileResults.push(` ${handName} ↔ ${schemaName}:`, ...diffs.map(d => ` ${d}`));
failures++;
@@ -1550,7 +1589,8 @@ if (isDirectRun) {
for (const line of fileResults) console.log(line);
const excludedCount = Object.keys(client.excluded).length;
if (excludedCount) {
- console.log(` (${excludedCount} excluded pair(s) with recorded reasons — see EXCLUDED in this script)`);
+ const byName = client.namesOnly.length ? `, ${client.namesOnly.length} of them still compared by field name` : '';
+ console.log(` (${excludedCount} excluded pair(s) with recorded reasons, see EXCLUDED in this script${byName})`);
}
}
diff --git a/scripts/check-contract-shapes.spec.mjs b/scripts/check-contract-shapes.spec.mjs
index 97c2999f0..fc391ca3a 100644
--- a/scripts/check-contract-shapes.spec.mjs
+++ b/scripts/check-contract-shapes.spec.mjs
@@ -129,6 +129,23 @@ test('comparePair flags a primitive widened to a union of primitives', () => {
assert.ok(diffs.some(d => d.includes('"count": hand union(int,str), contract number')));
});
+test('comparePair with namesOnly keeps the field names and drops optionality and token', () => {
+ // The excluded Go and Java pairs keep a deliberately looser type: that stays accepted, a renamed field does not.
+ const loose = {
+ id: { optional: true, token: 'number' },
+ direction: { optional: false, token: 'string' },
+ count: { optional: false, token: 'string' },
+ name: { optional: false, token: 'string' },
+ };
+ assert.deepEqual(comparePair('Sample', loose, 'SampleDto', schemas.SampleDto, schemas, true, true), []);
+ assert.ok(comparePair('Sample', loose, 'SampleDto', schemas.SampleDto, schemas, true).length > 0);
+ const renamed = { ...loose, nmae: loose.name };
+ delete renamed.name;
+ const diffs = comparePair('Sample', renamed, 'SampleDto', schemas.SampleDto, schemas, true, true);
+ assert.equal(diffs.length, 2);
+ assert.ok(diffs[0].startsWith('hand has "nmae"') && diffs[1].startsWith('contract has "name"'));
+});
+
test('parseObjectToken splits nested object tokens without losing members', () => {
const members = parseObjectToken('object(id:string,sub:object(a:number,b?:boolean),tail:string)');
assert.deepEqual(Object.keys(members), ['id', 'sub', 'tail']);
@@ -526,8 +543,16 @@ const gateRoot = fileURLToPath(new URL('..', import.meta.url));
* sources linked in. A hook receives the original text (the parsed contract for `contract`) and returns the
* one to use. Every file is read with LF endings, so a hook anchors the same text on any checkout, and
* written with `lineEnding`: '\r\n' also copies the SDK sources the gate reads, as a Windows checkout has them.
+ * `sdk` maps a path under the repository (`sdk/go/types_group.go`) to such a hook for one SDK source, which
+ * also makes the run copy the SDK sources instead of linking them.
*/
-function runGateOnCopy({ script = s => s, contract = c => c, dashboardTypes = s => s, lineEnding = '\n' } = {}) {
+function runGateOnCopy({
+ script = s => s,
+ contract = c => c,
+ dashboardTypes = s => s,
+ lineEnding = '\n',
+ sdk = {},
+} = {}) {
const dir = mkdtempSync(join(tmpdir(), 'contract-shapes-copy-'));
const read = (...path) => readFileSync(join(gateRoot, ...path), 'utf8').replace(/\r\n/g, '\n');
const write = (path, text) => {
@@ -535,7 +560,7 @@ function runGateOnCopy({ script = s => s, contract = c => c, dashboardTypes = s
writeFileSync(join(dir, ...path), text.replace(/\n/g, lineEnding));
};
try {
- if (lineEnding === '\n') {
+ if (lineEnding === '\n' && !Object.keys(sdk).length) {
symlinkSync(join(gateRoot, 'sdk'), join(dir, 'sdk'));
} else {
const modelDir = ['sdk', 'java', 'src', 'main', 'java', 'com', 'rmyndharis', 'openwa', 'model'];
@@ -550,7 +575,13 @@ function runGateOnCopy({ script = s => s, contract = c => c, dashboardTypes = s
.filter(f => f.endsWith('.java'))
.map(f => [...modelDir, f]),
];
- for (const path of sources) write(path, read(...path));
+ for (const path of sources) write(path, (sdk[path.join('/')] ?? (text => text))(read(...path)));
+ for (const path of Object.keys(sdk)) {
+ assert.ok(
+ sources.some(s => s.join('/') === path),
+ `${path} is not an SDK source the gate reads`,
+ );
+ }
}
write(['scripts', 'check-contract-shapes.mjs'], script(read('scripts', 'check-contract-shapes.mjs')));
write(
@@ -636,6 +667,82 @@ test('a schema that only the dashboard compares, or only an excluded pair holds,
);
});
+const javaModel = 'sdk/java/src/main/java/com/rmyndharis/openwa/model';
+
+test('an excluded pair with a looser field type is still compared by field name', () => {
+ // Each pair keeps a plain string (or a pointer) where the contract is stricter, so it is excluded from the
+ // full comparison. Renaming one wire field in the hand type must still fail the run, naming the pair.
+ const rename = (from, to) => text => editSource(text, from, to);
+ const cases = [
+ ['sdk/go/types_contact.go', 'ContactRecord ↔ ContactDto', 'json:"isBlocked"', 'json:"isBlockedd"', 'isBlockedd'],
+ [
+ 'sdk/go/types_group.go',
+ 'GroupPictureResponse ↔ GroupPictureResponseDto',
+ 'URL string `json:"url"`',
+ 'URL string `json:"uri"`',
+ 'uri',
+ ],
+ [
+ 'sdk/go/types_group.go',
+ 'GroupSettings ↔ GroupSettingsResponseDto',
+ 'MemberAddMode *string `json:"memberAddMode,omitempty"`',
+ 'MemberAddMode *string `json:"memberAddmode,omitempty"`',
+ 'memberAddmode',
+ ],
+ [
+ 'sdk/go/types_status.go',
+ 'StatusRecord ↔ StatusDto',
+ 'json:"backgroundColor,omitempty"',
+ 'json:"backgroundColour,omitempty"',
+ 'backgroundColour',
+ ],
+ [
+ 'sdk/go/types_misc.go',
+ 'AuthValidateResponse ↔ ValidateApiKeyResponseDto',
+ 'json:"engineType,omitempty"',
+ 'json:"engine,omitempty"',
+ 'engine',
+ ],
+ [
+ `${javaModel}/GroupSettings.java`,
+ 'GroupSettings ↔ GroupSettingsResponseDto',
+ 'String memberAddMode) {',
+ 'String memberAddModes) {',
+ 'memberAddModes',
+ ],
+ [
+ `${javaModel}/StatusRecord.java`,
+ 'StatusRecord ↔ StatusDto',
+ ' String backgroundColor,',
+ ' String backgroundColour,',
+ 'backgroundColour',
+ ],
+ [
+ `${javaModel}/AuthValidateResponse.java`,
+ 'AuthValidateResponse ↔ ValidateApiKeyResponseDto',
+ 'String engineType,',
+ 'String engine,',
+ 'engine',
+ ],
+ ];
+ for (const [path, pair, from, to, renamed] of cases) {
+ const run = runGateOnCopy({ sdk: { [path]: rename(from, to) } });
+ assert.equal(run.status, 1, `${path}: ${run.output}`);
+ assert.ok(run.output.includes(`${pair}:`), `${path} did not fail on ${pair}: ${run.output}`);
+ assert.match(run.output, new RegExp(`hand has "${renamed}"`), path);
+ }
+});
+
+test('the gate refuses a NAMES_ONLY entry whose pair is not excluded', () => {
+ // An entry left behind after a pair is retyped and un-excluded would keep the weaker name-only comparison.
+ const run = runGateOnCopy({
+ script: source =>
+ editSource(source, " 'sdk/java': ['GroupSettings',", " 'sdk/java': ['ContactRecord', 'GroupSettings',"),
+ });
+ assert.equal(run.status, 1, run.output);
+ assert.match(run.output, /ContactRecord is in NAMES_ONLY but not in EXCLUDED/);
+});
+
test('the gate and its CLI cases give the same verdicts on a CRLF checkout', () => {
// A Windows checkout holds every file with CRLF endings: the parsers, the README reading and the anchors of
// these cases must not depend on them. The existing case above covers the parsers on strings only.