specshield 3.5.0 → 3.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +55 -0
- package/README.md +95 -2
- package/package.json +1 -1
- package/src/cli.js +4 -0
- package/src/commands/gate.js +13 -0
- package/src/commands/prove.js +149 -0
- package/src/commands/replay.js +195 -0
- package/src/core/configLoader.js +5 -2
- package/src/core/gate/runGate.js +10 -1
- package/src/core/prove/contract.js +241 -0
- package/src/core/prove/execute.js +135 -0
- package/src/core/prove/http.js +104 -0
- package/src/core/prove/index.js +84 -0
- package/src/core/prove/instance.js +400 -0
- package/src/core/prove/relate.js +23 -0
- package/src/core/prove/render.js +169 -0
- package/src/core/prove/repair.js +109 -0
- package/src/core/prove/schema.js +261 -0
- package/src/core/prove/subschema.js +257 -0
- package/src/core/prove/witness.js +702 -0
- package/src/core/replay/runReplay.js +169 -0
- package/src/core/replay/shape.js +100 -0
- package/src/core/replay/traffic.js +168 -0
package/src/core/gate/runGate.js
CHANGED
|
@@ -10,6 +10,7 @@ const { classifyChanges } = require('../classifyChanges');
|
|
|
10
10
|
const { resolveBaseline } = require('./baseline');
|
|
11
11
|
const G = require('./git');
|
|
12
12
|
const W = require('./waivers');
|
|
13
|
+
const P = require('../prove');
|
|
13
14
|
|
|
14
15
|
/**
|
|
15
16
|
* One gate run: the spec at the merge base vs the spec in the working tree,
|
|
@@ -23,7 +24,7 @@ async function runGate(opts) {
|
|
|
23
24
|
const {
|
|
24
25
|
spec, cwd = process.cwd(), base, env = process.env, fetch = true,
|
|
25
26
|
mode = 'blocking', waiversFile = W.DEFAULT_FILE, maxWaiverDays = W.DEFAULT_MAX_DAYS,
|
|
26
|
-
ignore = [], usage = null, now = Date.now(),
|
|
27
|
+
ignore = [], usage = null, now = Date.now(), prove = false,
|
|
27
28
|
} = opts;
|
|
28
29
|
if (!['blocking', 'shadow'].includes(mode)) throw new Error(`mode must be "blocking" or "shadow", got "${mode}"`);
|
|
29
30
|
|
|
@@ -69,11 +70,13 @@ async function runGate(opts) {
|
|
|
69
70
|
try { baseW = baseWText ? W.parseWaivers(baseWText, wOpts).waivers : []; } catch { /* the baseline's file may predate today's rules */ }
|
|
70
71
|
|
|
71
72
|
let breaking = [];
|
|
73
|
+
let docs = null;
|
|
72
74
|
if (out.specStatus === 'deleted') {
|
|
73
75
|
breaking = [{ type: 'SPEC_REMOVED', path: null, method: null, field: null, severity: 'error', description: `The spec ${specRel} was deleted` }];
|
|
74
76
|
} else if (out.specStatus === 'changed') {
|
|
75
77
|
const baseDoc = parseSpec(baseText, specRel);
|
|
76
78
|
const headDoc = parseSpec(headText, specRel);
|
|
79
|
+
docs = { baseDoc, headDoc };
|
|
77
80
|
let result = classifyChanges(diffSpecs(normalizeSpec(baseDoc), normalizeSpec(headDoc)));
|
|
78
81
|
out.nonBreaking = result.additions.length + result.modifications.length + result.warnings.length;
|
|
79
82
|
if (ignore.length) {
|
|
@@ -91,6 +94,12 @@ async function runGate(opts) {
|
|
|
91
94
|
}
|
|
92
95
|
|
|
93
96
|
out.breaking = breaking.map(withKey);
|
|
97
|
+
if (prove && docs) {
|
|
98
|
+
// A proof per finding: the request that worked at the baseline and fails now.
|
|
99
|
+
const proofs = P.witnesses(docs.baseDoc, docs.headDoc);
|
|
100
|
+
out.breaking = out.breaking.map((c) => ({ ...c, proof: P.proofFor(c, proofs) }));
|
|
101
|
+
out.proofs = P.summarize(out.breaking);
|
|
102
|
+
}
|
|
94
103
|
const { blocking, waived, used } = W.applyWaivers(out.breaking, headW.waivers, now);
|
|
95
104
|
out.blocking = blocking;
|
|
96
105
|
out.waived = waived;
|
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* One operation's contract, read from a raw spec (OpenAPI 3.x or Swagger 2.0):
|
|
5
|
+
* its parameters, request body and responses. Plus the two things a witness
|
|
6
|
+
* needs from it: build an HTTP request, and say whether a request satisfies it.
|
|
7
|
+
*
|
|
8
|
+
* Request = {
|
|
9
|
+
* method: 'POST', path: '/orders/{id}',
|
|
10
|
+
* params: { 'path:id': 1, 'query:limit': 10, 'header:X-Trace': 'abc' }, // typed values
|
|
11
|
+
* body: <JSON> | undefined,
|
|
12
|
+
* }
|
|
13
|
+
*
|
|
14
|
+
* Parameter values are kept typed; they are checked the way a server reads
|
|
15
|
+
* them off the wire (strings parsed into the declared type).
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
const L = require('../fix/locate');
|
|
19
|
+
const S = require('./schema');
|
|
20
|
+
const { generate, OMIT } = require('./instance');
|
|
21
|
+
|
|
22
|
+
const JSON_TYPE = /^application\/(.+\+)?json$|^\*\/\*$/i;
|
|
23
|
+
const FORM_TYPE = /^application\/x-www-form-urlencoded$/i;
|
|
24
|
+
|
|
25
|
+
function contractOf(doc, method, path) {
|
|
26
|
+
const m = method.toLowerCase();
|
|
27
|
+
const op = L.operationPtr(doc, m, path);
|
|
28
|
+
if (!op) return { doc, method: m.toUpperCase(), path, exists: false, params: [], body: null, responses: {} };
|
|
29
|
+
|
|
30
|
+
const params = [];
|
|
31
|
+
let body = null;
|
|
32
|
+
for (const { node } of L.parameterPtrs(doc, m, path)) {
|
|
33
|
+
if (node.in === 'body') {
|
|
34
|
+
body = { schema: node.schema || null, required: Boolean(node.required), mediaType: 'application/json', json: true, form: false, structured: true };
|
|
35
|
+
continue;
|
|
36
|
+
}
|
|
37
|
+
// Swagger 2.0 formData fields stay parameters (the diff engine reports them
|
|
38
|
+
// as parameters); they travel as a form body.
|
|
39
|
+
params.push({
|
|
40
|
+
name: node.name,
|
|
41
|
+
in: node.in,
|
|
42
|
+
key: `${node.in}:${node.name}`,
|
|
43
|
+
required: node.in === 'path' ? true : Boolean(node.required),
|
|
44
|
+
schema: node.schema || (node.type ? inlineSchema(node) : node.content ? contentSchema(node.content) : null),
|
|
45
|
+
style: node.style || null,
|
|
46
|
+
explode: node.explode,
|
|
47
|
+
collectionFormat: node.collectionFormat || null,
|
|
48
|
+
});
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
const rb = S.deref(doc, L.get(doc, [...op, 'requestBody']));
|
|
52
|
+
if (rb && rb.content) {
|
|
53
|
+
const types = Object.keys(rb.content);
|
|
54
|
+
const jsonType = types.find((t) => JSON_TYPE.test(t));
|
|
55
|
+
const formType = types.find((t) => FORM_TYPE.test(t));
|
|
56
|
+
const type = jsonType || formType || types[0];
|
|
57
|
+
body = {
|
|
58
|
+
schema: (rb.content[type] && rb.content[type].schema) || null,
|
|
59
|
+
required: Boolean(rb.required),
|
|
60
|
+
mediaType: type,
|
|
61
|
+
json: Boolean(jsonType),
|
|
62
|
+
form: !jsonType && Boolean(formType),
|
|
63
|
+
structured: Boolean(jsonType || formType),
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
const responses = {};
|
|
68
|
+
for (const code of Object.keys(L.get(doc, [...op, 'responses']) || {})) {
|
|
69
|
+
const ptr = L.responseSchemaPtr(doc, m, path, code);
|
|
70
|
+
responses[code] = { schema: ptr ? L.get(doc, ptr) : null };
|
|
71
|
+
}
|
|
72
|
+
return { doc, method: m.toUpperCase(), path, exists: true, params, body, responses };
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Swagger 2.0 non-body parameters declare their schema inline. */
|
|
76
|
+
function inlineSchema(p) {
|
|
77
|
+
const { name, in: _in, required, description, collectionFormat, allowEmptyValue, ...schema } = p;
|
|
78
|
+
return schema;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
function contentSchema(content) {
|
|
82
|
+
const first = Object.values(content)[0];
|
|
83
|
+
return first && first.schema ? first.schema : null;
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** The response entry a status code falls under: exact, "2XX", then "default". */
|
|
87
|
+
function responseFor(contract, code) {
|
|
88
|
+
const c = String(code);
|
|
89
|
+
const r = contract.responses;
|
|
90
|
+
for (const key of [c, `${c[0]}XX`, `${c[0]}xx`, 'default']) if (r[key]) return { key, ...r[key] };
|
|
91
|
+
return null;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
// ─── building requests ──────────────────────────────────────────────────────
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* A request for `contract`. Required parameters always; optional ones too with
|
|
98
|
+
* `full`. `target` puts one value in place: { param: 'query:limit', value } or
|
|
99
|
+
* { body: steps, value } (value may be OMIT). `like` copies parameter values
|
|
100
|
+
* from another request where this contract declares the same parameter, so a
|
|
101
|
+
* witness and its control differ only where they must.
|
|
102
|
+
*/
|
|
103
|
+
function buildRequest(contract, { full = false, variant = 0, examples = true, target = null, like = null } = {}) {
|
|
104
|
+
const { doc } = contract;
|
|
105
|
+
const params = {};
|
|
106
|
+
for (const p of contract.params) {
|
|
107
|
+
if (target && target.param === p.key) {
|
|
108
|
+
if (target.value !== OMIT) params[p.key] = target.value;
|
|
109
|
+
continue;
|
|
110
|
+
}
|
|
111
|
+
if (like && like.params[p.key] !== undefined) { params[p.key] = like.params[p.key]; continue; }
|
|
112
|
+
if (!p.required && !full) continue;
|
|
113
|
+
params[p.key] = p.schema ? generate(doc, p.schema, { side: 'request', full, examples, variant }) : 'abc';
|
|
114
|
+
}
|
|
115
|
+
if (target && target.param && !contract.params.some((p) => p.key === target.param) && target.value !== OMIT) {
|
|
116
|
+
params[target.param] = target.value;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
let body;
|
|
120
|
+
if (contract.body && contract.body.structured && contract.body.schema) {
|
|
121
|
+
const bodyTarget = target && target.body ? { steps: target.body, value: target.value } : null;
|
|
122
|
+
if (like && like.body !== undefined && !bodyTarget) body = like.body;
|
|
123
|
+
else if (contract.body.required || full || bodyTarget || (like && like.body !== undefined)) {
|
|
124
|
+
body = generate(doc, contract.body.schema, { side: 'request', full, examples, variant, target: bodyTarget });
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
return { method: contract.method, path: contract.path, params, body, mediaType: contract.body ? contract.body.mediaType : null };
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
// ─── checking requests ──────────────────────────────────────────────────────
|
|
131
|
+
|
|
132
|
+
/**
|
|
133
|
+
* Does `req` satisfy `contract`? Returns the reasons it doesn't, each tagged
|
|
134
|
+
* with the part of the request it is about ({ part: 'query:limit' | 'body' |
|
|
135
|
+
* 'operation' }). Undeclared parameters are not an error — servers ignore them.
|
|
136
|
+
*/
|
|
137
|
+
function checkRequest(contract, req) {
|
|
138
|
+
const problems = [];
|
|
139
|
+
if (!contract.exists) {
|
|
140
|
+
return [{ part: 'operation', message: `${contract.method} ${contract.path} is not in this spec`, errors: [] }];
|
|
141
|
+
}
|
|
142
|
+
for (const p of contract.params) {
|
|
143
|
+
const v = req.params[p.key];
|
|
144
|
+
if (v === undefined) {
|
|
145
|
+
if (p.required) problems.push({ part: p.key, message: `${p.in} parameter "${p.name}" is required`, errors: [] });
|
|
146
|
+
continue;
|
|
147
|
+
}
|
|
148
|
+
if (!p.schema) continue;
|
|
149
|
+
const r = S.validator(contract.doc, p.schema, { side: 'request', kind: 'param' })(wire(v));
|
|
150
|
+
if (!r.ok) problems.push({ part: p.key, message: r.errors.map((e) => S.describeError(e, `${p.in} parameter "${p.name}"`)).join('; '), errors: r.errors });
|
|
151
|
+
}
|
|
152
|
+
const b = contract.body;
|
|
153
|
+
if (b && b.structured && b.schema) {
|
|
154
|
+
if (req.body === undefined) {
|
|
155
|
+
if (b.required) problems.push({ part: 'body', message: 'a request body is required', errors: [] });
|
|
156
|
+
} else {
|
|
157
|
+
// Form fields arrive as text and are parsed into the declared types, like parameters.
|
|
158
|
+
const r = S.validator(contract.doc, b.schema, { side: 'request', kind: b.form ? 'param' : 'body' })(req.body);
|
|
159
|
+
if (!r.ok) problems.push({ part: 'body', label: 'body', message: r.errors.map((e) => S.describeError(e)).join('; '), errors: r.errors });
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
return problems;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/** A parameter value as a server receives it: strings (or a list of them). */
|
|
166
|
+
function wire(v) {
|
|
167
|
+
if (Array.isArray(v)) return v.map((x) => (typeof x === 'object' && x !== null ? JSON.stringify(x) : String(x)));
|
|
168
|
+
if (v !== null && typeof v === 'object') return v; // deepObject: leave as an object
|
|
169
|
+
return String(v);
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/** Check a response body against the contract's schema for `code`. */
|
|
173
|
+
function checkResponse(contract, code, body) {
|
|
174
|
+
const r = responseFor(contract, code);
|
|
175
|
+
if (!r) return { ok: false, documented: false, errors: [{ path: '', keyword: 'status', message: `status ${code} is not documented`, params: {} }] };
|
|
176
|
+
if (!r.schema) return { ok: true, documented: true, errors: [] };
|
|
177
|
+
return { documented: true, ...S.validator(contract.doc, r.schema, { side: 'response' })(body) };
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
// ─── rendering ──────────────────────────────────────────────────────────────
|
|
181
|
+
|
|
182
|
+
/** "/orders/{id}?limit=10" with values filled in, plus the headers. */
|
|
183
|
+
function urlOf(contract, req) {
|
|
184
|
+
let path = req.path;
|
|
185
|
+
const query = [];
|
|
186
|
+
const headers = {};
|
|
187
|
+
const form = [];
|
|
188
|
+
for (const [key, v] of Object.entries(req.params)) {
|
|
189
|
+
const [loc, ...rest] = key.split(':');
|
|
190
|
+
const name = rest.join(':');
|
|
191
|
+
const p = contract.params.find((x) => x.key === key) || { name, in: loc };
|
|
192
|
+
if (loc === 'path') path = path.split(`{${name}}`).join(encodeURIComponent(serialize(v, p, ',')));
|
|
193
|
+
else if (loc === 'query') {
|
|
194
|
+
const explode = p.explode !== undefined ? p.explode : (p.collectionFormat ? p.collectionFormat === 'multi' : true);
|
|
195
|
+
if (Array.isArray(v) && explode) for (const x of v) query.push(`${encodeURIComponent(name)}=${encodeURIComponent(scalar(x))}`);
|
|
196
|
+
else query.push(`${encodeURIComponent(name)}=${encodeURIComponent(serialize(v, p, delimiter(p)))}`);
|
|
197
|
+
} else if (loc === 'formData') {
|
|
198
|
+
const explode = p.collectionFormat === 'multi';
|
|
199
|
+
if (Array.isArray(v) && explode) for (const x of v) form.push(`${encodeURIComponent(name)}=${encodeURIComponent(scalar(x))}`);
|
|
200
|
+
else form.push(`${encodeURIComponent(name)}=${encodeURIComponent(serialize(v, p, delimiter(p)))}`);
|
|
201
|
+
} else if (loc === 'header') headers[name] = serialize(v, p, ',');
|
|
202
|
+
else if (loc === 'cookie') headers.Cookie = [headers.Cookie, `${name}=${serialize(v, p, ',')}`].filter(Boolean).join('; ');
|
|
203
|
+
}
|
|
204
|
+
return { path: path + (query.length ? `?${query.join('&')}` : ''), headers, form: form.length ? form.join('&') : null };
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/**
|
|
208
|
+
* A form body for a structured value, in the bracket notation most servers
|
|
209
|
+
* parse (Rails, PHP, Stripe): a[b]=1&list[0]=x.
|
|
210
|
+
*/
|
|
211
|
+
function formEncode(value, prefix = '') {
|
|
212
|
+
const out = [];
|
|
213
|
+
const add = (k, v) => out.push(`${encodeURIComponent(k).replace(/%5B/g, '[').replace(/%5D/g, ']')}=${encodeURIComponent(v)}`);
|
|
214
|
+
const walk = (v, key) => {
|
|
215
|
+
if (v === undefined) return;
|
|
216
|
+
if (v === null) { add(key, ''); return; }
|
|
217
|
+
if (Array.isArray(v)) { v.forEach((x, i) => walk(x, `${key}[${i}]`)); return; }
|
|
218
|
+
if (typeof v === 'object') { for (const [k, x] of Object.entries(v)) walk(x, key ? `${key}[${k}]` : k); return; }
|
|
219
|
+
add(key, String(v));
|
|
220
|
+
};
|
|
221
|
+
walk(value, prefix);
|
|
222
|
+
return out.join('&');
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
function delimiter(p) {
|
|
226
|
+
if (p.collectionFormat === 'ssv' || p.style === 'spaceDelimited') return ' ';
|
|
227
|
+
if (p.collectionFormat === 'pipes' || p.style === 'pipeDelimited') return '|';
|
|
228
|
+
if (p.collectionFormat === 'tsv') return '\t';
|
|
229
|
+
return ',';
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
function serialize(v, p, sep) {
|
|
233
|
+
if (Array.isArray(v)) return v.map(scalar).join(sep);
|
|
234
|
+
return scalar(v);
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
function scalar(v) {
|
|
238
|
+
return v !== null && typeof v === 'object' ? JSON.stringify(v) : String(v);
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
module.exports = { contractOf, responseFor, buildRequest, checkRequest, checkResponse, urlOf, wire, formEncode, JSON_TYPE };
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `prove --against <url>`: send each witness to a running build of the new
|
|
5
|
+
* API and see whether the build behaves the way the new spec says it will.
|
|
6
|
+
*
|
|
7
|
+
* Every request witness travels with a control — the same request, valid under
|
|
8
|
+
* the new spec. A rejected witness next to an accepted control is a confirmed
|
|
9
|
+
* break; both rejected means the build is refusing something else (missing
|
|
10
|
+
* credentials, missing test data), so the result is inconclusive rather than
|
|
11
|
+
* a false confirmation.
|
|
12
|
+
*
|
|
13
|
+
* confirmed the build does what the witness predicts
|
|
14
|
+
* not-reproduced it doesn't: it accepts the request, or still sends what
|
|
15
|
+
* old clients expect — the spec and the code disagree
|
|
16
|
+
* inconclusive the outcome can't be attributed to the change
|
|
17
|
+
* skipped not sent (a write without --include-mutating, or no witness)
|
|
18
|
+
* error no response
|
|
19
|
+
*/
|
|
20
|
+
|
|
21
|
+
const L = require('../fix/locate');
|
|
22
|
+
const C = require('./contract');
|
|
23
|
+
const H = require('./http');
|
|
24
|
+
const { relatesTo } = require('./relate');
|
|
25
|
+
const S = require('./schema');
|
|
26
|
+
|
|
27
|
+
async function confirmAll(items, opts) {
|
|
28
|
+
const { baseDoc, against, headers = {}, includeMutating = false, timeoutMs = 10000, concurrency = 4, http = H.send } = opts;
|
|
29
|
+
const run = async ({ diff, witness: w }) => {
|
|
30
|
+
if (!w.request || (w.status !== 'proven' && w.status !== 'example')) return { outcome: 'skipped', detail: 'nothing to send' };
|
|
31
|
+
if (!includeMutating && !H.SAFE_METHODS.has(w.request.method)) {
|
|
32
|
+
return { outcome: 'skipped', detail: `${w.request.method} changes data; pass --include-mutating to send it` };
|
|
33
|
+
}
|
|
34
|
+
const call = (req) => http({
|
|
35
|
+
method: req.method,
|
|
36
|
+
url: against + req.path,
|
|
37
|
+
headers: { ...headers, ...req.headers },
|
|
38
|
+
body: req.bodyText || (req.body === null ? undefined : JSON.stringify(req.body)),
|
|
39
|
+
timeoutMs,
|
|
40
|
+
});
|
|
41
|
+
try {
|
|
42
|
+
const res = await call(w.request);
|
|
43
|
+
const out = { status: res.status, ...judge(diff, w, res, baseDoc) };
|
|
44
|
+
if (w.expect === 'rejected' && w.control && res.status >= 400 && res.status !== 401 && res.status !== 403) {
|
|
45
|
+
const ctrl = await call(w.control);
|
|
46
|
+
out.controlStatus = ctrl.status;
|
|
47
|
+
Object.assign(out, withControl(res, ctrl));
|
|
48
|
+
}
|
|
49
|
+
return out;
|
|
50
|
+
} catch (err) {
|
|
51
|
+
return { outcome: 'error', detail: H.describeNetworkError(err) };
|
|
52
|
+
}
|
|
53
|
+
};
|
|
54
|
+
const results = await H.pool(items, concurrency, run);
|
|
55
|
+
items.forEach((it, i) => { it.witness.run = results[i]; });
|
|
56
|
+
return items;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function judge(diff, w, res, baseDoc) {
|
|
60
|
+
const s = res.status;
|
|
61
|
+
if (s === 401 || s === 403) return { outcome: 'inconclusive', detail: `HTTP ${s} — the build wants credentials; pass them with --header` };
|
|
62
|
+
|
|
63
|
+
if (w.expect === 'not-found' || w.expect === 'method-not-allowed') {
|
|
64
|
+
if (s === 404 || s === 405 || s === 501) return { outcome: 'confirmed', detail: `HTTP ${s}: the operation is gone` };
|
|
65
|
+
if (s < 400) return { outcome: 'not-reproduced', detail: `HTTP ${s}: the build still serves it, though the new spec removed it` };
|
|
66
|
+
return { outcome: 'inconclusive', detail: `HTTP ${s}` };
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
if (w.expect === 'rejected') {
|
|
70
|
+
if (s < 400) return { outcome: 'not-reproduced', detail: `HTTP ${s}: the build accepted it. The new spec says it should be rejected — the spec and the code disagree` };
|
|
71
|
+
return { outcome: 'confirmed', detail: `HTTP ${s}: rejected${s >= 500 ? ' (a server error, not a 4xx)' : ''}`, weak: true };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
if (w.expect === 'ignored') {
|
|
75
|
+
if (s >= 400) return { outcome: 'confirmed', detail: `HTTP ${s}: the build rejects requests that still send it` };
|
|
76
|
+
return { outcome: 'inconclusive', detail: `HTTP ${s}: accepted — whether the value is still used can't be seen from outside` };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
if (w.expect === 'response') {
|
|
80
|
+
const code = w.response.status;
|
|
81
|
+
if (!sameStatus(code, s)) return { outcome: 'inconclusive', detail: `HTTP ${s} instead of ${code} — check the test data` };
|
|
82
|
+
if (res.json === undefined) return { outcome: 'inconclusive', detail: `HTTP ${s} with no JSON body` };
|
|
83
|
+
const parsed = L.parseField(diff.field);
|
|
84
|
+
const oldC = C.contractOf(baseDoc, diff.method, diff.path);
|
|
85
|
+
const check = C.checkResponse(oldC, code, res.json);
|
|
86
|
+
const related = parsed ? (check.errors || []).filter((e) => relatesTo([e], parsed.steps)) : [];
|
|
87
|
+
if (related.length) {
|
|
88
|
+
return { outcome: 'confirmed', detail: `the build's response breaks old clients: ${related.map((e) => S.describeError(e, 'response')).join('; ')}` };
|
|
89
|
+
}
|
|
90
|
+
if (parsed && emptyAlong(res.json, parsed.steps)) return { outcome: 'inconclusive', detail: 'the response had no data at that field (an empty list?) — seed some test data' };
|
|
91
|
+
if (w.status === 'example' && parsed && present(res.json, parsed.steps)) {
|
|
92
|
+
return { outcome: 'not-reproduced', detail: `the build still sends ${diff.field.replace(/^responses\.[^.]+\./, '')}` };
|
|
93
|
+
}
|
|
94
|
+
return { outcome: w.status === 'example' ? 'confirmed' : 'not-reproduced', detail: w.status === 'example' ? 'the field is gone from the response' : 'the response still matches what old clients expect here' };
|
|
95
|
+
}
|
|
96
|
+
return { outcome: 'inconclusive', detail: `HTTP ${s}` };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
function withControl(res, ctrl) {
|
|
100
|
+
if (ctrl.status < 400) {
|
|
101
|
+
return { outcome: 'confirmed', weak: false, detail: `HTTP ${res.status}: rejected, while the same request valid under the new spec got HTTP ${ctrl.status}` };
|
|
102
|
+
}
|
|
103
|
+
return { outcome: 'inconclusive', weak: false, detail: `HTTP ${res.status}, but the control request was rejected too (HTTP ${ctrl.status}) — check credentials and test data` };
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function sameStatus(documented, actual) {
|
|
107
|
+
const d = String(documented);
|
|
108
|
+
const a = String(actual);
|
|
109
|
+
if (d === a) return true;
|
|
110
|
+
if (/^[1-5]xx$/i.test(d)) return d[0] === a[0];
|
|
111
|
+
return d === 'default';
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** Walks an actual response along diff steps; true when an array on the way is empty. */
|
|
115
|
+
function emptyAlong(body, steps) {
|
|
116
|
+
let cur = body;
|
|
117
|
+
for (const s of steps) {
|
|
118
|
+
if (cur === null || cur === undefined) return false;
|
|
119
|
+
if (s.items) { if (!Array.isArray(cur)) return false; if (cur.length === 0) return true; cur = cur[0]; } else if (s.prop !== undefined) cur = cur[s.prop];
|
|
120
|
+
else if (s.map) { const k = Object.keys(cur)[0]; if (k === undefined) return true; cur = cur[k]; }
|
|
121
|
+
}
|
|
122
|
+
return false;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
function present(body, steps) {
|
|
126
|
+
let cur = body;
|
|
127
|
+
for (const s of steps) {
|
|
128
|
+
if (cur === null || cur === undefined) return false;
|
|
129
|
+
if (s.items) { if (!Array.isArray(cur) || !cur.length) return false; cur = cur[0]; } else if (s.prop !== undefined) { if (!(s.prop in Object(cur))) return false; cur = cur[s.prop]; }
|
|
130
|
+
else if (s.map) { const k = Object.keys(cur)[0]; if (k === undefined) return false; cur = cur[k]; }
|
|
131
|
+
}
|
|
132
|
+
return cur !== undefined;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
module.exports = { confirmAll, judge };
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* HTTP for `prove --against` and `replay`: one request at a time, raw text in
|
|
5
|
+
* and out, HTTP errors returned as data (only connection failures throw), and
|
|
6
|
+
* a guard against pointing either command at a server by accident.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const axios = require('axios');
|
|
10
|
+
const net = require('net');
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* A server is "local" when it can only be a developer's or a CI job's own:
|
|
14
|
+
* loopback, private ranges, link-local, single-label hosts (docker-compose
|
|
15
|
+
* service names such as "api"), and the .local/.internal/.test/.localhost
|
|
16
|
+
* suffixes. Anything else needs --allow-remote.
|
|
17
|
+
*/
|
|
18
|
+
function isLocalHost(hostname) {
|
|
19
|
+
const h = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
|
|
20
|
+
if (!h) return false;
|
|
21
|
+
if (h === 'localhost' || /\.(localhost|local|internal|test)$/.test(h)) return true;
|
|
22
|
+
if (net.isIPv4(h)) {
|
|
23
|
+
const [a, b] = h.split('.').map(Number);
|
|
24
|
+
return a === 127 || a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254) || a === 0;
|
|
25
|
+
}
|
|
26
|
+
if (net.isIPv6(h)) return h === '::1' || /^f[cd]/.test(h) || /^fe80:/.test(h);
|
|
27
|
+
return !h.includes('.');
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** Validates a base URL and returns it without a trailing slash. */
|
|
31
|
+
function targetUrl(raw, { allowRemote = false, flag = '--against' } = {}) {
|
|
32
|
+
let u;
|
|
33
|
+
try { u = new URL(raw); } catch { throw new Error(`${flag} must be a URL like http://localhost:8080 (got "${raw}")`); }
|
|
34
|
+
if (u.protocol !== 'http:' && u.protocol !== 'https:') throw new Error(`${flag} must be an http(s) URL`);
|
|
35
|
+
if (!allowRemote && !isLocalHost(u.hostname)) {
|
|
36
|
+
throw new Error(`${flag} ${u.host} is not a local or private host. These requests are built to fail or to change data; pass --allow-remote if this server is a test environment you own.`);
|
|
37
|
+
}
|
|
38
|
+
return u.toString().replace(/\/+$/, '');
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** "Name: value" pairs from repeated --header options. */
|
|
42
|
+
function parseHeaders(list = []) {
|
|
43
|
+
const out = {};
|
|
44
|
+
for (const h of list) {
|
|
45
|
+
const i = h.indexOf(':');
|
|
46
|
+
if (i <= 0) throw new Error(`--header must look like "Name: value" (got "${h}")`);
|
|
47
|
+
out[h.slice(0, i).trim()] = h.slice(i + 1).trim();
|
|
48
|
+
}
|
|
49
|
+
return out;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Sends one request. Returns { status, headers, text, json, ms }; `json` is
|
|
54
|
+
* the parsed body when it is JSON. Rejects only when no response came back.
|
|
55
|
+
*/
|
|
56
|
+
async function send({ method, url, headers = {}, body, timeoutMs = 10000 }) {
|
|
57
|
+
const started = Date.now();
|
|
58
|
+
const res = await axios.request({
|
|
59
|
+
method,
|
|
60
|
+
url,
|
|
61
|
+
headers,
|
|
62
|
+
data: body,
|
|
63
|
+
timeout: timeoutMs,
|
|
64
|
+
validateStatus: () => true,
|
|
65
|
+
maxRedirects: 0,
|
|
66
|
+
responseType: 'text',
|
|
67
|
+
transformResponse: [(d) => d],
|
|
68
|
+
transitional: { silentJSONParsing: true },
|
|
69
|
+
});
|
|
70
|
+
const text = typeof res.data === 'string' ? res.data : res.data === undefined || res.data === null ? '' : String(res.data);
|
|
71
|
+
return { status: res.status, headers: res.headers || {}, text, json: parseJson(text, res.headers), ms: Date.now() - started };
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function parseJson(text, headers) {
|
|
75
|
+
if (!text) return undefined;
|
|
76
|
+
const type = String((headers && (headers['content-type'] || headers['Content-Type'])) || '');
|
|
77
|
+
if (!/json/i.test(type) && !/^\s*[[{]/.test(text)) return undefined;
|
|
78
|
+
try { return JSON.parse(text); } catch { return undefined; }
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** Runs `fn` over `items` with at most `n` in flight; keeps the order. */
|
|
82
|
+
async function pool(items, n, fn) {
|
|
83
|
+
const out = new Array(items.length);
|
|
84
|
+
let next = 0;
|
|
85
|
+
async function worker() {
|
|
86
|
+
while (next < items.length) {
|
|
87
|
+
const i = next++;
|
|
88
|
+
out[i] = await fn(items[i], i);
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
await Promise.all(Array.from({ length: Math.max(1, Math.min(n, items.length)) }, worker));
|
|
92
|
+
return out;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
|
|
96
|
+
|
|
97
|
+
function describeNetworkError(err) {
|
|
98
|
+
if (err.code === 'ECONNREFUSED') return 'connection refused';
|
|
99
|
+
if (err.code === 'ECONNABORTED' || /timeout/i.test(err.message)) return 'timed out';
|
|
100
|
+
if (err.code === 'ENOTFOUND') return 'host not found';
|
|
101
|
+
return err.message;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
module.exports = { isLocalHost, targetUrl, parseHeaders, send, pool, SAFE_METHODS, describeNetworkError };
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* `specshield prove` as a library: classify the changes between two specs the
|
|
5
|
+
* way `compare` and `gate` do, and attach a witness to each breaking change
|
|
6
|
+
* (and to each constraint warning, which the engine reports without ruling on).
|
|
7
|
+
*
|
|
8
|
+
* The diff engine merges a field change that a shared schema spreads across
|
|
9
|
+
* several endpoints into one finding; its proof is the strongest witness among
|
|
10
|
+
* those endpoints, with a count of how many were proven.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
const { normalizeSpec } = require('../normalizeSpec');
|
|
14
|
+
const { diffSpecs } = require('../diffEngine');
|
|
15
|
+
const { classifyChanges } = require('../classifyChanges');
|
|
16
|
+
const { context, proveChange, PROVABLE } = require('./witness');
|
|
17
|
+
|
|
18
|
+
const RANK = { proven: 3, example: 2, compatible: 1, unproven: 0 };
|
|
19
|
+
|
|
20
|
+
function prove(baseDoc, targetDoc) {
|
|
21
|
+
const raw = diffSpecs(normalizeSpec(baseDoc), normalizeSpec(targetDoc));
|
|
22
|
+
const classified = classifyChanges(raw);
|
|
23
|
+
const proofs = witnesses(baseDoc, targetDoc, raw);
|
|
24
|
+
|
|
25
|
+
const breaking = classified.breakingChanges.map((c) => attach(c, proofs));
|
|
26
|
+
const warnings = classified.warnings.map((c) => attach(c, proofs));
|
|
27
|
+
return {
|
|
28
|
+
breaking,
|
|
29
|
+
warnings,
|
|
30
|
+
nonBreaking: classified.additions.length + classified.modifications.length,
|
|
31
|
+
summary: summarize(breaking),
|
|
32
|
+
proofs,
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Per-endpoint witnesses for every provable raw diff. */
|
|
37
|
+
function witnesses(baseDoc, targetDoc, raw = diffSpecs(normalizeSpec(baseDoc), normalizeSpec(targetDoc))) {
|
|
38
|
+
const ctx = context(baseDoc, targetDoc);
|
|
39
|
+
return raw.filter((d) => PROVABLE.has(d.type)).map((d) => ({ diff: d, witness: proveChange(ctx, d) }));
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** The proof for one classified change, drawn from the per-endpoint witnesses. */
|
|
43
|
+
function proofFor(change, proofs) {
|
|
44
|
+
const eps = endpointsOf(change);
|
|
45
|
+
const merged = Array.isArray(change.affectedEndpoints) && change.affectedEndpoints.length > 1;
|
|
46
|
+
const mine = proofs.filter(({ diff: d }) => {
|
|
47
|
+
if (d.type !== change.type) return false;
|
|
48
|
+
if (eps.length === 0) return !d.method && (d.field || null) === (change.field || null);
|
|
49
|
+
if (!d.method || !eps.includes(`${d.method.toUpperCase()} ${d.path}`)) return false;
|
|
50
|
+
return merged ? leaf(d.field) === leaf(change.field) : (d.field || null) === (change.field || null);
|
|
51
|
+
});
|
|
52
|
+
if (mine.length === 0) return null;
|
|
53
|
+
const best = mine.reduce((a, b) => (RANK[b.witness.status] > RANK[a.witness.status] ? b : a));
|
|
54
|
+
return {
|
|
55
|
+
...best.witness,
|
|
56
|
+
diff: { type: best.diff.type, method: best.diff.method || null, path: best.diff.path || null, field: best.diff.field || null },
|
|
57
|
+
endpoints: mine.length,
|
|
58
|
+
provenOn: mine.filter((p) => p.witness.status === 'proven').length,
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
function attach(change, proofs) {
|
|
63
|
+
return { ...change, proof: proofFor(change, proofs) };
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
function summarize(changes) {
|
|
67
|
+
const out = { total: changes.length, proven: 0, example: 0, compatible: 0, unproven: 0 };
|
|
68
|
+
for (const c of changes) out[c.proof ? c.proof.status : 'unproven']++;
|
|
69
|
+
return out;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
function endpointsOf(c) {
|
|
73
|
+
if (Array.isArray(c.affectedEndpoints) && c.affectedEndpoints.length) return c.affectedEndpoints;
|
|
74
|
+
return c.method && c.path ? [`${c.method.toUpperCase()} ${c.path}`] : [];
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** Mirrors classifyChanges' leafFieldName: "responses.200.data[items].legacy_id" → "legacy_id". */
|
|
78
|
+
function leaf(field) {
|
|
79
|
+
if (!field) return null;
|
|
80
|
+
const parts = field.split('.');
|
|
81
|
+
return parts[parts.length - 1].replace(/\[.*$/, '');
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
module.exports = { prove, witnesses, proofFor, summarize };
|