@lovrozagar/oat 0.6.1 → 0.7.0

package/dist/runtime/checks.js

@@ -12,7 +12,9 @@ import { encodeForOperation } from "./body.js";
 import { STRING_PAYLOADS, payloadFits } from "./payloads.js";
 import { describeFeatureGate, isDocumentedFeatureGateDenial, reportFeatureGateSchemaDrift } from "./feature-gate.js";
 import { driveAsync, inspectStreamAsync, matchesPredicate, resolveAsyncId } from "./async.js";
+import { resolveOutOfBandValue } from "./auth.js";
 import { buildCohort } from "./fixture.js";
+import { driveWait } from "./wait.js";
 import { fillPath } from "./world.js";
 /* ------------------------------------------------------------------- helpers */
 /**
@@ -33,6 +35,16 @@ function standDownForFeatureGate(ctx, op, exchange, check) {
         "down rather than treat the documented 403 as a defect.");
     return true;
 }
+/**
+ * A 429 that survived Client retries is the bucket, not the backend. The check that needed a
+ * 2xx stands down; it is not a defect and it is not a concurrency conclusion.
+ */
+function standDownForRateLimit(ctx, exchange, check) {
+    if (exchange.status !== 429)
+        return false;
+    ctx.findings.unresolved(check, ctx.entityName, "the request was rate-limited (429) after retries, so this check could not complete");
+    return true;
+}
 /** The list endpoint's derived conventions — parameter roles and envelope spellings. */
 function conv(ctx) {
     return ctx.listOp.conventions;
@@ -151,6 +163,7 @@ function linkRelations(exchange) {
 async function list(ctx, query = {}, auth = ctx.auth, scope = ctx.scope) {
     const exchange = await ctx.client.get(fillPath(ctx.listOp.path, scope), {
         headers: auth(),
+        operationId: ctx.listOp.operationId,
         query,
     });
     const body = exchange.responseBody;
@@ -2591,6 +2604,7 @@ const inviteGrantsThenRevokes = {
         const invited = await ctx.client.request(inviteOp.method, fillPath(inviteOp.path, resource), {
             body: { [spec.granteeField]: delegate.inviteAs },
             headers: { ...owner.headers(), "content-type": "application/json" },
+            operationId: inviteOp.operationId,
         });
         if (standDownForFeatureGate(ctx, inviteOp, invited, this.id))
             return;
@@ -2602,10 +2616,25 @@ const inviteGrantsThenRevokes = {
                 "step is then theatre — anyone who can be named in an invite body is already in.", [invited]);
             return;
         }
-        const token = pointerValue(invited.responseBody, spec.tokenPointer);
         const grantId = pointerValue(invited.responseBody, spec.grantPointer);
-        if (token === undefined) {
-            return ctx.findings.unresolved(this.id, ctx.entityName, `invite response has no token at ${spec.tokenPointer}`);
+        let token;
+        if (spec.tokenFrom === "outOfBand") {
+            const kind = spec.tokenKind ?? `${ctx.entityName}-invite`;
+            try {
+                token = await resolveOutOfBandValue(ctx.hooks.resolveOutOfBand, delegate.inviteAs, kind, {
+                    label: `invite to ${ctx.entityName}`,
+                    outOfBand: ctx.outOfBand,
+                });
+            }
+            catch (error) {
+                return ctx.findings.unresolved(this.id, ctx.entityName, error instanceof Error ? error.message : String(error));
+            }
+        }
+        else {
+            token = pointerValue(invited.responseBody, spec.tokenPointer);
+            if (token === undefined) {
+                return ctx.findings.unresolved(this.id, ctx.entityName, `invite response has no token at ${spec.tokenPointer}`);
+            }
         }
         const acceptScope = { ...resource, token };
         const acceptBody = documentedJsonBody(ctx, acceptOp, acceptScope);
@@ -2615,6 +2644,7 @@ const inviteGrantsThenRevokes = {
                 ...delegate.headers(),
                 ...(acceptBody === undefined ? {} : { "content-type": "application/json" }),
             },
+            operationId: acceptOp.operationId,
         });
         if (standDownForFeatureGate(ctx, acceptOp, accepted, this.id))
             return;
@@ -2637,6 +2667,7 @@ const inviteGrantsThenRevokes = {
                 ...owner.headers(),
                 ...(revokeBody === undefined ? {} : { "content-type": "application/json" }),
             },
+            operationId: revokeOp.operationId,
         });
         if (standDownForFeatureGate(ctx, revokeOp, revoked, this.id))
             return;
@@ -3246,6 +3277,10 @@ const noLostUpdate = {
             return;
         if (standDownForFeatureGate(ctx, ctx.updateOp, secondWrite, this.id))
             return;
+        if (standDownForRateLimit(ctx, firstWrite, this.id))
+            return;
+        if (standDownForRateLimit(ctx, secondWrite, this.id))
+            return;
         if (firstWrite.status >= 300 || secondWrite.status >= 300) {
             return ctx.findings.unresolved(this.id, ctx.entityName, `a concurrent PATCH was rejected (${firstWrite.status}, ${secondWrite.status}), so no ` +
                 "race actually took place");
@@ -3343,6 +3378,8 @@ const declaredEffectsOccur = {
                 });
                 if (standDownForFeatureGate(ctx, op, invoked, this.id))
                     continue;
+                if (standDownForRateLimit(ctx, invoked, this.id))
+                    continue;
                 if (invoked.status >= 400) {
                     ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} could not be invoked`, `returned ${invoked.status}; its declared effects are unverified`);
                     continue;
@@ -3380,6 +3417,61 @@ const declaredEffectsOccur = {
         }
     },
 };
+/**
+ * After a write that declares `x-wait`, poll the named GET until a JSON path is occupied
+ * (or `awaitSideEffect` returns true). Timeout is a backend finding, not a coverage gap.
+ */
+const sideEffectArrives = {
+    applicable: (ctx) => ctx.waitOps.length > 0,
+    dependsOn: ["list.read-after-write"],
+    mutates: true,
+    id: "effects.side-effect-arrives",
+    needs: "an operation declaring x-wait",
+    async run(ctx) {
+        for (const op of ctx.waitOps) {
+            const spec = op.wait;
+            if (spec === null)
+                continue;
+            const pollOp = ctx.model.byOperationId.get(spec.operationId);
+            if (pollOp === undefined) {
+                ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} x-wait names "${spec.operationId}", which is not in the document`, "the side effect cannot be observed, so it is not verified");
+                continue;
+            }
+            const body = op.hasRequestBody ? bodyForOp(ctx, op) : undefined;
+            const invoked = await ctx.client.request(op.method, fillPath(op.path, ctx.scope), {
+                headers: ctx.auth(),
+                operationId: op.operationId,
+                ...(body === undefined ? {} : await encodeOpBody(ctx, op, body)),
+            });
+            if (standDownForFeatureGate(ctx, op, invoked, this.id))
+                continue;
+            if (standDownForRateLimit(ctx, invoked, this.id))
+                continue;
+            if (invoked.status >= 400) {
+                ctx.findings.gap(this.id, ctx.entityName, `${op.operationId} could not be invoked`, `returned ${invoked.status}; its declared x-wait is unverified`);
+                continue;
+            }
+            const outcome = await driveWait({
+                awaitSideEffect: ctx.hooks.awaitSideEffect,
+                client: ctx.client,
+                headers: ctx.auth,
+                pollOp,
+                record: invoked.responseBody,
+                scope: ctx.scope,
+                spec,
+                writeOpId: op.operationId,
+                ...(ctx.refreshIfStale === undefined ? {} : { refreshIfStale: ctx.refreshIfStale }),
+            });
+            if (!outcome.timedOut)
+                continue;
+            ctx.findings.backend(this.id, ctx.entityName, `${op.operationId} side effect did not appear within ${spec.timeoutMs}ms`, `x-wait polls ${spec.operationId}` +
+                (spec.until === undefined ? "" : ` until ${spec.until} is non-empty`) +
+                ` and the path was still empty after ${outcome.polls} poll(s) / ${Math.round(outcome.elapsedMs)}ms. ` +
+                "Queue consumers and webhook inboxes are not the same request; a timeout here is a " +
+                "missed delivery, not a coverage gap.", [invoked, ...outcome.exchanges.slice(-2)]);
+        }
+    },
+};
 async function observe(ctx, listOp) {
     let path;
     try {
@@ -3590,6 +3682,8 @@ const stringPayloadSurvives = {
             const control = await writeField(ASCII_PAYLOAD_PROBE, id);
             if (standDownForFeatureGate(ctx, writeOp, control, this.id))
                 return;
+            if (standDownForRateLimit(ctx, 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`);
             }
@@ -3632,7 +3726,9 @@ const stringPayloadSurvives = {
                         evidence.push(written);
                     continue;
                 }
-                if (written.status === 404 || written.status === 409 || written.status === 415 || written.status === 429) {
+                if (standDownForRateLimit(ctx, written, this.id))
+                    return;
+                if (written.status === 404 || written.status === 409 || written.status === 415) {
                     continue;
                 }
                 if (written.status >= 400 && written.status < 500) {
@@ -3731,6 +3827,8 @@ const documentedStatusHonoured = {
                 continue;
             if (isDocumentedFeatureGateDenial(op, exchange.status, exchange.responseBody))
                 continue;
+            if (exchange.status === 429)
+                continue;
             const raw = ctx.model.rawOperations.get(op.operationId);
             if (!declaresConcreteStatuses(raw))
                 continue;
@@ -3827,6 +3925,7 @@ export const CHECKS = [
     /* declared side effects and async lifecycles, last: both invoke operations that change the
      * world, and both are meaningless if the read surface above is already known broken */
     declaredEffectsOccur,
+    sideEffectArrives,
     asyncReachesTerminalState,
     asyncReceiptIsResolvable,
     /* After every other check has written to the transcript — create is owned by