@lovrozagar/oat 0.3.0 → 0.5.0

package/dist/runtime/checks.js

@@ -6,6 +6,10 @@
  * the oracle of what oat just wrote. Check ids are stable: the conformance suite asserts on them.
  */
 import { filterTerm, selectTerm, sortTerm } from "../spec/conventions.js";
+import { requestContent } from "../spec/collection.js";
+import { pathTemplateMatches } from "../spec/load.js";
+import { encodeForOperation } from "./body.js";
+import { STRING_PAYLOADS, payloadFits } from "./payloads.js";
 import { describeFeatureGate, isDocumentedFeatureGateDenial, reportFeatureGateSchemaDrift } from "./feature-gate.js";
 import { driveAsync } from "./async.js";
 import { buildCohort } from "./fixture.js";
@@ -1312,19 +1316,20 @@ const idempotentReplay = {
             return;
         const schema = requestSchemaOf(ctx, createOp);
         if (schema === null) {
-            return ctx.findings.unresolved(this.id, ctx.entityName, "the create operation declares no JSON request body to replay");
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the create operation declares no request body to replay");
         }
         const body = validBody(ctx, schema);
         const key = `oat-idem-${ctx.seed}-${ctx.entityName}`;
         const path = fillPath(createOp.path, ctx.scope);
         const headers = { ...ctx.auth(), [header]: key };
-        const first = await ctx.client.request("POST", path, { body, headers });
+        const encoded = await encodeOpBody(ctx, createOp, body);
+        const first = await ctx.client.request("POST", path, { ...encoded, headers });
         if (standDownForFeatureGate(ctx, createOp, first, this.id))
             return;
         if (first.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `the first create returned ${first.status}, so there was nothing to replay`);
         }
-        const second = await ctx.client.request("POST", path, { body, headers });
+        const second = await ctx.client.request("POST", path, { ...encoded, headers });
         if (standDownForFeatureGate(ctx, createOp, second, this.id))
             return;
         if (second.status >= 300) {
@@ -1370,7 +1375,7 @@ const declaredInvalidationHappens = {
             return;
         const schema = requestSchemaOf(ctx, createOp);
         if (schema === null) {
-            return ctx.findings.unresolved(this.id, ctx.entityName, "the create operation declares no JSON request body, so no write can be made");
+            return ctx.findings.unresolved(this.id, ctx.entityName, "the create operation declares no request body, so no write can be made");
         }
         /* Only routes whose path can be filled from this entity's scope are probed: a route
          * needing an identifier oat does not hold would 404 for a reason unrelated to staleness. */
@@ -1395,7 +1400,7 @@ const declaredInvalidationHappens = {
             return ctx.findings.unresolved(this.id, ctx.entityName, "none of the declared routes could be read before the write");
         }
         const created = await ctx.client.request("POST", fillPath(createOp.path, ctx.scope), {
-            body: validBody(ctx, schema),
+            ...(await encodeOpBody(ctx, createOp, validBody(ctx, schema))),
             headers: ctx.auth(),
         });
         if (standDownForFeatureGate(ctx, createOp, created, this.id))
@@ -2775,7 +2780,9 @@ const createPersistsFields = {
         const sent = createExchange(ctx);
         if (sent === undefined || sent.requestBody === undefined)
             return;
-        const request = sent.requestBody;
+        const request = submittedFields(sent.requestBody);
+        if (Object.keys(request).length === 0)
+            return;
         const response = (sent.responseBody ?? {});
         const dropped = Object.entries(request).filter(([key, value]) => {
             if (value === null || value === undefined)
@@ -2811,7 +2818,7 @@ const enumValidated = {
             return;
         const body = { ...validBody(ctx, schema), [target.name]: "oat-not-a-member" };
         const exchange = await ctx.client.request("POST", fillPath(createOp.path, ctx.scope), {
-            body,
+            ...(await encodeOpBody(ctx, createOp, body)),
             headers: ctx.auth(),
         });
         if (standDownForFeatureGate(ctx, createOp, exchange, this.id))
@@ -2842,7 +2849,7 @@ const maxLengthValidated = {
         const max = target.schema.maxLength;
         const body = { ...validBody(ctx, schema), [target.name]: "x".repeat(max + 25) };
         const exchange = await ctx.client.request("POST", fillPath(createOp.path, ctx.scope), {
-            body,
+            ...(await encodeOpBody(ctx, createOp, body)),
             headers: ctx.auth(),
         });
         if (standDownForFeatureGate(ctx, createOp, exchange, this.id))
@@ -2871,7 +2878,7 @@ const requiredValidated = {
             return;
         const { [field]: _omitted, ...body } = validBody(ctx, schema);
         const exchange = await ctx.client.request("POST", fillPath(createOp.path, ctx.scope), {
-            body,
+            ...(await encodeOpBody(ctx, createOp, body)),
             headers: ctx.auth(),
         });
         if (standDownForFeatureGate(ctx, createOp, exchange, this.id))
@@ -2971,6 +2978,8 @@ const successSchemaHonoured = {
         const exchange = createExchange(ctx);
         if (exchange === undefined)
             return;
+        if (isEventStream(exchange))
+            return;
         if (!validator.documents(raw, exchange.status)) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `create returned ${exchange.status}, which the document declares no schema for — ` +
                 "there is nothing to validate the body against");
@@ -3005,14 +3014,34 @@ function bodyForOp(ctx, op) {
 }
 function requestSchemaOf(ctx, op) {
     const raw = ctx.model.rawOperations.get(op.operationId);
-    const content = raw?.requestBody?.content;
-    if (content === undefined)
-        return null;
-    for (const [mediaType, media] of Object.entries(content)) {
-        if (mediaType.includes("json") && media.schema !== undefined)
-            return media.schema;
+    const picked = raw === undefined ? null : requestContent(raw);
+    return picked === null ? null : picked.schema;
+}
+async function encodeOpBody(ctx, op, fields, variant = "baseline", index = 0) {
+    const encoded = await encodeForOperation(op, ctx.model, fields, ctx.uploads, variant, index);
+    return encoded.contentType === undefined
+        ? { body: encoded.body }
+        : { body: encoded.body, contentType: encoded.contentType };
+}
+function submittedFields(body) {
+    if (typeof FormData !== "undefined" && body instanceof FormData) {
+        const out = {};
+        for (const [name, value] of body.entries()) {
+            if (typeof value === "string")
+                out[name] = value;
+        }
+        return out;
     }
-    return null;
+    if (typeof URLSearchParams !== "undefined" && body instanceof URLSearchParams) {
+        return Object.fromEntries(body.entries());
+    }
+    if (body !== null && typeof body === "object" && !Array.isArray(body))
+        return body;
+    return {};
+}
+function isEventStream(exchange) {
+    const type = exchange.responseHeaders["content-type"] ?? "";
+    return type.includes("text/event-stream");
 }
 function findConstrained(schema, predicate) {
     const props = schema.properties;
@@ -3265,7 +3294,7 @@ const declaredEffectsOccur = {
                 const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
                 const invoked = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
                     headers: ctx.auth(),
-                    ...(body === undefined ? {} : { body }),
+                    ...(body === undefined ? {} : await encodeOpBody(ctx, op, body)),
                 });
                 if (standDownForFeatureGate(ctx, op, invoked, this.id))
                     continue;
@@ -3337,7 +3366,7 @@ const asyncReachesTerminalState = {
             const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
             const start = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
                 headers: ctx.auth(),
-                ...(body === undefined ? {} : { body }),
+                ...(body === undefined ? {} : await encodeOpBody(ctx, op, body)),
             });
             if (standDownForFeatureGate(ctx, op, start, this.id))
                 continue;
@@ -3405,6 +3434,284 @@ const asyncReceiptIsResolvable = {
         }
     },
 };
+const ASCII_PAYLOAD_PROBE = "oat-payload-probe";
+function pickPayloadField(ctx, op) {
+    const schema = requestSchemaOf(ctx, op);
+    const properties = (schema?.properties ?? {});
+    const immutable = new Set([
+        ...(ctx.updateOp?.immutable ?? []),
+        ...(ctx.updateOp?.generated ?? []),
+        ...(ctx.createOp?.generated ?? []),
+        ctx.identity,
+    ]);
+    let best = null;
+    for (const [name, declared] of Object.entries(properties)) {
+        if (immutable.has(name) || /_at$|_id$/.test(name))
+            continue;
+        if (declared === null || typeof declared !== "object")
+            continue;
+        if (declared.readOnly === true)
+            continue;
+        const union = declared.oneOf ?? declared.anyOf;
+        const branch = Array.isArray(union)
+            ? union.find((candidate) => candidate !== null && typeof candidate === "object" && candidate.type === "string")
+            : undefined;
+        const stringSchema = branch ?? declared;
+        const type = stringSchema.type;
+        const isString = type === "string" || (Array.isArray(type) && type.includes("string"));
+        if (!isString && type !== undefined)
+            continue;
+        if (Array.isArray(stringSchema.enum))
+            continue;
+        if (typeof stringSchema.pattern === "string")
+            continue;
+        if (typeof stringSchema.format === "string")
+            continue;
+        const maxLength = typeof stringSchema.maxLength === "number" ? stringSchema.maxLength : undefined;
+        const minLength = typeof stringSchema.minLength === "number" ? stringSchema.minLength : undefined;
+        if (maxLength !== undefined && maxLength < 8)
+            continue;
+        const nullable = declared.nullable === true ||
+            (Array.isArray(declared.type) && declared.type.includes("null")) ||
+            (Array.isArray(union) &&
+                union.some((candidate) => candidate !== null && typeof candidate === "object" && candidate.type === "null"));
+        const score = (nullable ? 1000 : 0) + (maxLength ?? 1024);
+        if (best === null || score > best.score)
+            best = { maxLength, minLength, name, score };
+    }
+    return best;
+}
+const stringPayloadSurvives = {
+    applicable: (ctx) => ctx.readOp !== undefined &&
+        ctx.records.length > 0 &&
+        (ctx.updateOp !== undefined || (ctx.createOp !== undefined && ctx.deleteOp !== undefined)),
+    dependsOn: ["list.read-after-write"],
+    id: "payload.string-survives",
+    mutates: true,
+    needs: "an update or create+delete, an item route, and a writable unconstrained string",
+    async run(ctx) {
+        const writeOp = ctx.updateOp ?? ctx.createOp;
+        const readOp = ctx.readOp;
+        if (writeOp === undefined || readOp === undefined)
+            return;
+        const field = pickPayloadField(ctx, writeOp);
+        if (field === null) {
+            return ctx.findings.unresolved(this.id, ctx.entityName, "no writable unconstrained string field is available to probe payloads against");
+        }
+        const viaPatch = ctx.updateOp !== undefined;
+        const target = ctx.records.at(-1) ?? ctx.records[0];
+        if (target === undefined)
+            return;
+        const id = String(target[ctx.identity]);
+        const params = { ...ctx.scope, ...itemParamFor(ctx, id) };
+        const original = target[field.name];
+        const writeField = async (value, recordId) => {
+            if (viaPatch && ctx.updateOp !== undefined) {
+                return ctx.client.request("PATCH", fillPath(ctx.updateOp.path, { ...ctx.scope, ...itemParamFor(ctx, recordId) }), {
+                    body: { [field.name]: value },
+                    headers: ctx.auth(),
+                });
+            }
+            const createOp = ctx.createOp;
+            if (createOp === undefined)
+                throw new Error("payload probe has no write operation");
+            const body = { ...validBody(ctx, requestSchemaOf(ctx, createOp) ?? {}), [field.name]: value };
+            return ctx.client.request("POST", fillPath(createOp.path, ctx.scope), { body, headers: ctx.auth() });
+        };
+        const readField = async (recordId) => {
+            const exchange = await ctx.client.get(fillPath(readOp.path, { ...ctx.scope, ...itemParamFor(ctx, recordId) }), {
+                headers: ctx.auth(),
+            });
+            const body = (exchange.responseBody ?? {});
+            return { exchange, value: body[field.name] };
+        };
+        const remove = async (recordId) => {
+            if (viaPatch || ctx.deleteOp === undefined)
+                return;
+            await ctx.client.request("DELETE", fillPath(ctx.deleteOp.path, { ...ctx.scope, ...itemParamFor(ctx, recordId) }), {
+                headers: ctx.auth(),
+            });
+        };
+        const identityOf = (exchange) => {
+            const body = exchange.responseBody;
+            if (body === null || typeof body !== "object")
+                return undefined;
+            const value = body[ctx.identity];
+            return value === undefined || value === null ? undefined : String(value);
+        };
+        try {
+            const control = await writeField(ASCII_PAYLOAD_PROBE, id);
+            if (standDownForFeatureGate(ctx, writeOp, control, this.id))
+                return;
+            if (control.status === 401 || control.status === 403) {
+                return ctx.findings.unresolved(this.id, ctx.entityName, `the ASCII control write returned ${control.status}, so later refusals cannot be attributed to the payload`);
+            }
+            if (control.status >= 400 && control.status < 500) {
+                return ctx.findings.unresolved(this.id, ctx.entityName, `the ASCII control write was rejected with ${control.status}, so the field refuses ordinary strings`);
+            }
+            if (control.status >= 500) {
+                ctx.findings.backend(this.id, ctx.entityName, "an ordinary ASCII write returned 5xx", `PATCH/POST of "${ASCII_PAYLOAD_PROBE}" on "${field.name}" returned ${control.status}.`, [control]);
+                return;
+            }
+            const controlId = viaPatch ? id : identityOf(control);
+            if (controlId === undefined) {
+                return ctx.findings.unresolved(this.id, ctx.entityName, "the ASCII control write did not return an identity, so the value could not be read back");
+            }
+            const controlRead = await readField(controlId);
+            if (!viaPatch)
+                await remove(controlId);
+            if (controlRead.value !== ASCII_PAYLOAD_PROBE) {
+                ctx.findings.backend(this.id, ctx.entityName, "an ordinary ASCII write did not persist exactly", `"${field.name}" was sent ${JSON.stringify(ASCII_PAYLOAD_PROBE)} and read back ` +
+                    `${JSON.stringify(controlRead.value)}.`, [control, controlRead.exchange]);
+                return;
+            }
+            const failed = [];
+            const evidence = [];
+            let lostAuth = false;
+            for (const payload of STRING_PAYLOADS) {
+                if (!payloadFits(payload.value, field.maxLength, field.minLength))
+                    continue;
+                const written = await writeField(payload.value, id);
+                if (standDownForFeatureGate(ctx, writeOp, written, this.id))
+                    return;
+                if (written.status === 401) {
+                    const retry = await writeField(ASCII_PAYLOAD_PROBE, id);
+                    if (retry.status >= 400) {
+                        lostAuth = true;
+                        break;
+                    }
+                    failed.push(`${payload.id} (${payload.why}): sent ${JSON.stringify(payload.value)}, got HTTP 401`);
+                    if (evidence.length < 4)
+                        evidence.push(written);
+                    continue;
+                }
+                if (written.status === 404 || written.status === 409 || written.status === 415 || written.status === 429) {
+                    continue;
+                }
+                if (written.status >= 400 && written.status < 500) {
+                    failed.push(`${payload.id} (${payload.why}): sent ${JSON.stringify(payload.value)}, got HTTP ${written.status}`);
+                    if (evidence.length < 4)
+                        evidence.push(written);
+                    if (!viaPatch) {
+                        const extra = identityOf(written);
+                        if (extra !== undefined)
+                            await remove(extra);
+                    }
+                    continue;
+                }
+                if (written.status >= 500) {
+                    failed.push(`${payload.id} (${payload.why}): sent ${JSON.stringify(payload.value)}, got HTTP ${written.status}`);
+                    if (evidence.length < 4)
+                        evidence.push(written);
+                    continue;
+                }
+                const writtenId = viaPatch ? id : identityOf(written);
+                if (writtenId === undefined) {
+                    failed.push(`${payload.id} (${payload.why}): write succeeded but returned no identity`);
+                    continue;
+                }
+                const got = await readField(writtenId);
+                if (!viaPatch)
+                    await remove(writtenId);
+                if (got.value !== payload.value) {
+                    failed.push(`${payload.id} (${payload.why}): sent ${JSON.stringify(payload.value)}, got ${JSON.stringify(got.value)}`);
+                    if (evidence.length < 4)
+                        evidence.push(written, got.exchange);
+                }
+            }
+            if (lostAuth && failed.length === 0) {
+                return ctx.findings.unresolved(this.id, ctx.entityName, "authentication failed in the middle of the payload catalog, so remaining cases were not run");
+            }
+            if (failed.length === 0)
+                return;
+            ctx.findings.backend(this.id, ctx.entityName, "a documented-valid string did not survive a write", `"${field.name}" failed ${failed.length} payload case(s): ${failed.slice(0, 6).join("; ")}` +
+                (failed.length > 6 ? `; and ${failed.length - 6} more` : "") +
+                ". The document accepts these as strings; refusing or mutating them is silent corruption " +
+                "or an undocumented constraint.", evidence);
+        }
+        finally {
+            if (viaPatch && ctx.updateOp !== undefined) {
+                await ctx.client.request("PATCH", fillPath(ctx.updateOp.path, params), {
+                    body: { [field.name]: original ?? null },
+                    headers: ctx.auth(),
+                });
+            }
+        }
+    },
+};
+function resolveEntityOperation(ctx, method, pathname) {
+    let best = null;
+    for (const op of ctx.model.operations) {
+        if (op.method !== method)
+            continue;
+        if (op.entity !== ctx.entityName)
+            continue;
+        if (!pathTemplateMatches(op.path, pathname))
+            continue;
+        if (best === null || op.path.length > best.path.length)
+            best = op;
+    }
+    return best;
+}
+function statusIsDeclared(raw, status) {
+    const keys = Object.keys(raw?.responses ?? {});
+    if (keys.includes(String(status)))
+        return true;
+    return keys.includes(`${Math.floor(status / 100)}XX`);
+}
+function declaresConcreteStatuses(raw) {
+    return Object.keys(raw?.responses ?? {}).some((key) => /^\d{3}$/.test(key) || /^[1-5]XX$/i.test(key));
+}
+const documentedStatusHonoured = {
+    applicable: (ctx) => ctx.model.operations.some((op) => op.entity === ctx.entityName && op.action !== "create"),
+    id: "response.status-is-documented",
+    needs: "a modeled non-create operation on this entity",
+    async run(ctx) {
+        const createId = ctx.createOp?.operationId;
+        const byOp = new Map();
+        for (const exchange of ctx.client.transcript) {
+            let pathname;
+            try {
+                pathname = new URL(exchange.url).pathname;
+            }
+            catch {
+                continue;
+            }
+            const op = resolveEntityOperation(ctx, exchange.method, pathname);
+            if (op === null)
+                continue;
+            if (op.operationId === createId || op.action === "create")
+                continue;
+            if (isDocumentedFeatureGateDenial(op, exchange.status, exchange.responseBody))
+                continue;
+            const raw = ctx.model.rawOperations.get(op.operationId);
+            if (!declaresConcreteStatuses(raw))
+                continue;
+            if (statusIsDeclared(raw, exchange.status))
+                continue;
+            const seen = byOp.get(op.operationId) ?? [];
+            seen.push(exchange);
+            byOp.set(op.operationId, seen);
+        }
+        if (byOp.size === 0)
+            return;
+        const lines = [];
+        const evidence = [];
+        for (const [operationId, exchanges] of byOp) {
+            const raw = ctx.model.rawOperations.get(operationId);
+            const declared = Object.keys(raw?.responses ?? {})
+                .filter((key) => key !== "default")
+                .sort()
+                .join(", ");
+            const seen = [...new Set(exchanges.map((item) => item.status))].sort((a, b) => a - b);
+            lines.push(`${operationId} returned ${seen.join(", ")}; the document declares ${declared || "no concrete status"}`);
+            const first = exchanges[0];
+            if (first !== undefined && evidence.length < 6)
+                evidence.push(first);
+        }
+        ctx.findings.spec(this.id, ctx.entityName, "an operation returned a status the document does not declare", `${lines.join(". ")}. Clients generated from this document will not recognise the response.`, evidence);
+    },
+};
 export const CHECKS = [
     /* foundations — did the write land, is it visible, and do the paging primitives work at all.
      * Everything below assumes these hold, so they must be evaluated first for cascade
@@ -3442,6 +3749,7 @@ export const CHECKS = [
     /* write semantics */
     patchMinimality,
     immutableRejected,
+    stringPayloadSurvives,
     idempotentReplay,
     declaredInvalidationHappens,
     projectionsAgree,
@@ -3474,5 +3782,8 @@ export const CHECKS = [
     declaredEffectsOccur,
     asyncReachesTerminalState,
     asyncReceiptIsResolvable,
+    /* After every other check has written to the transcript — create is owned by
+     * create.status-matches-document. */
+    documentedStatusHonoured,
 ];
 //# sourceMappingURL=checks.js.map