@lovrozagar/oat 0.6.2 → 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 */
 /**
@@ -161,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;
@@ -2601,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;
@@ -2612,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);
@@ -2625,6 +2644,7 @@ const inviteGrantsThenRevokes = {
                 ...delegate.headers(),
                 ...(acceptBody === undefined ? {} : { "content-type": "application/json" }),
             },
+            operationId: acceptOp.operationId,
         });
         if (standDownForFeatureGate(ctx, acceptOp, accepted, this.id))
             return;
@@ -2647,6 +2667,7 @@ const inviteGrantsThenRevokes = {
                 ...owner.headers(),
                 ...(revokeBody === undefined ? {} : { "content-type": "application/json" }),
             },
+            operationId: revokeOp.operationId,
         });
         if (standDownForFeatureGate(ctx, revokeOp, revoked, this.id))
             return;
@@ -3396,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 {
@@ -3849,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