@aventara/testing 0.1.0-pilot.4 → 1.0.0-rc.1

package/dist/protocol/protocol-fixture.d.ts

@@ -1,4 +1,4 @@
-import type { OperationCode, ValidationCode } from "@aventara/core";
+import type { AvOperationCode, AvValidationCode } from "@aventara/core";
 import type { AvProtocolRequest } from "@aventara/core/protocol";
 /**
  * One row of the protocol fixture corpus: the HTTP request a host receives
@@ -25,11 +25,11 @@ export type AvProtocolFixture = {
          */
         readonly status: number;
         /** `null`: the host produces no framework envelope at all. */
-        readonly code: OperationCode | null;
+        readonly code: AvOperationCode | null;
         /** The exact, sorted key set of `cause`. */
         readonly causeKeys?: readonly string[];
         readonly issues?: readonly {
-            readonly code: ValidationCode;
+            readonly code: AvValidationCode;
             readonly path?: readonly (string | number)[];
         }[];
         /** Always stated: `0` is an assertion, not a default. */
@@ -47,6 +47,6 @@ export type AvProtocolFixture = {
          */
         readonly outcome: "resolve" | "framework-error" | "transport-error";
         /** Present iff `outcome` is `"framework-error"`. */
-        readonly code?: OperationCode;
+        readonly code?: AvOperationCode;
     };
 };

package/dist/protocol/protocol-fixtures.js

@@ -322,20 +322,20 @@ const TRANSACTIONS = [
     ]), 422, "A2004", [{ code: "V1019", path: ["operations", 1, "resource"] }], 1),
     ...["scope", "origin"].map((key) => invalid(`transaction — a plan node carrying "${key}" cannot smuggle an origin → 422 A2004 / V1001`, planRequest(`corpus-tx-smuggle-${key}`, [
         { ...AUTHORS_FIND_MANY, [key]: "application" },
-    ]), 422, "A2004", [{ code: "V1001", path: [key] }], 0)),
+    ]), 422, "A2004", [{ code: "V1001", path: ["operations", 0, key] }], 0)),
     invalid("a client-hidden field — single route", corpusRequest("find/many", { select: ["id", "secret"] }, "corpus-r1-field"), 422, "A2004", [{ code: "V1005", path: ["arguments", "select", 1] }]),
     invalid("a client-hidden field — /_transactions", planRequest("corpus-r1-field-tx", [
         AUTHORS_FIND_MANY,
         planNode("authors", "find.many", { select: ["id", "secret"] }, "fp1:1t8vSfPuohv1N5MIX8ccNw"),
-    ]), 422, "A2004", [{ code: "V1005", path: ["arguments", "select", 1] }], 1),
+    ]), 422, "A2004", [{ code: "V1005", path: ["operations", 1, "args", "select", 1] }], 1),
     invalid("a client-restricted variant — single route", {
         ...corpusRequest("", {}, "corpus-r1-variant"),
         path: "/_resources/secrets/find/many",
-    }, 404, "A2002", [{ code: "V1006", path: ["operation"] }]),
+    }, 404, "A2002", [{ code: "V1006", path: ["family"] }]),
     invalid("a client-restricted variant — /_transactions", planRequest("corpus-r1-variant-tx", [
         AUTHORS_FIND_MANY,
         planNode("secrets", "find.many", {}, "fp1:KegI5OcquDHi8z39VH11EQ"),
-    ]), 404, "A2002", [{ code: "V1006", path: ["operation"] }], 1),
+    ]), 404, "A2002", [{ code: "V1006", path: ["operations", 1, "family"] }], 1),
     invalid("a client-hidden Resource — single route", {
         ...corpusRequest("", {}, "corpus-r1-resource"),
         path: "/_resources/hiddenRes/find/many",
@@ -343,11 +343,12 @@ const TRANSACTIONS = [
     invalid("a client-hidden Resource — /_transactions", planRequest("corpus-r1-resource-tx", [
         AUTHORS_FIND_MANY,
         planNode("hiddenRes", "find.many", {}, "fp1:UY6pLVLKM2LaIMnfQa0zGw"),
-    ]), 404, "A2001", [{ code: "V1005", path: ["resource"] }], 1),
+    ]), 404, "A2001", [{ code: "V1005", path: ["operations", 1, "resource"] }], 1),
     refused("method: GET on /_transactions → 405 A2012 with Allow: POST", planRequest("corpus-tx-get", [AUTHORS_FIND_MANY], { method: "GET" }), 405, "A2012", "The HTTP method is not allowed on this framework route.", { Allow: "POST" }),
 ];
 const STALE_HASH = `sha256:${"0".repeat(64)}`;
-const VALIDATION_FAILED = "Operation arguments failed framework validation.";
+const RESOURCE_UNAVAILABLE = "The requested Resource is not available.";
+const OPERATION_UNAVAILABLE = "The requested operation is not available on this Resource.";
 const absent = (label, request, status, code, cause) => ({
     label: `absent: ${label}`,
     request,
@@ -370,18 +371,18 @@ const absentRequest = (path, requestId, headers = {}, method = "POST") => {
     const base = corpusRequest("", {}, requestId);
     return { ...base, method, path, headers: { ...base.headers, ...headers } };
 };
-const unavailableOperation = (resource, operation) => ({
-    message: VALIDATION_FAILED,
+const unavailableOperation = (resource, operation, key) => ({
+    message: OPERATION_UNAVAILABLE,
     issues: [
         {
-            path: ["operation"],
+            path: [key],
             code: "V1006",
             message: `Operation "${operation}" is not available on Resource "${resource}".`,
         },
     ],
 });
 const unavailableResource = (resource) => ({
-    message: VALIDATION_FAILED,
+    message: RESOURCE_UNAVAILABLE,
     issues: [
         {
             code: "V1005",
@@ -391,7 +392,7 @@ const unavailableResource = (resource) => ({
     ],
 });
 const ABSENCE = [
-    absent("an unadvertised operation, current hash → 404 A2002", absentRequest("/_resources/books/delete/many", "corpus-absent-op"), 404, "A2002", unavailableOperation("books", "delete.many")),
+    absent("an unadvertised operation, current hash → 404 A2002", absentRequest("/_resources/books/delete/many", "corpus-absent-op"), 404, "A2002", unavailableOperation("books", "delete.many", "family")),
     absent("an unadvertised operation, stale hash → 409 A2005 (regenerate)", absentRequest("/_resources/books/delete/many", "corpus-absent-stale", {
         "Aventara-Contract-Hash": STALE_HASH,
     }), 409, "A2005", {
@@ -404,7 +405,7 @@ const ABSENCE = [
         "Aventara-Protocol-Version": "2",
     }), 400, "A2006", { message: "Aventara protocol version does not match the server." }),
     absent("an unknown Resource → 404 A2001", absentRequest("/_resources/nope/find/many", "corpus-absent-resource"), 404, "A2001", unavailableResource("nope")),
-    absent("a Resource with operations: {} → 404 A2002", absentRequest("/_resources/secrets/find/many", "corpus-absent-empty"), 404, "A2002", unavailableOperation("secrets", "find.many")),
+    absent("a Resource with operations: {} → 404 A2002", absentRequest("/_resources/secrets/find/many", "corpus-absent-empty"), 404, "A2002", unavailableOperation("secrets", "find.many", "family")),
     absent("a client-hidden Resource → 404 A2001", absentRequest("/_resources/hiddenRes/find/many", "corpus-absent-hidden"), 404, "A2001", unavailableResource("hiddenRes")),
     absent('/_transactions under transactions "none" → 404 A2002 at ["operations"]', {
         ...planRequest("corpus-absent-tx-none", [AUTHORS_FIND_MANY]),
@@ -476,6 +477,35 @@ const CREATE_ID = planNode("authors", "create.one", { data: { name: CORPUS_AUTHO
 const CREATE_ID_PRINT = CREATE_ID.fingerprint;
 const FIRST_NOBODY = planNode("authors", "find.first", { where: { id: CORPUS_NOBODY } }, "fp1:qNR9mD7_iVygNtmuuXjymw");
 const ARGUMENTS_FAILED = "Operation arguments failed framework validation.";
+const TRANSACTION_REFERENCES = [
+    answered("transaction — a unique where and a filter reference an earlier step's result → 200 A1009", planRequest("corpus-tx-ref-where", [
+        CREATE_ID,
+        planNode("authors", "find.unique", { where: { id: ref(0, CREATE_ID_PRINT, "id") } }, "fp1:hKbxzChGakplMZvnpEa1_w"),
+        planNode("authors", "find.many", { where: { OR: [{ id: { equals: ref(0, CREATE_ID_PRINT, "id") } }] } }, "fp1:4LK9l_j8Skjk4iU_wSoRzQ"),
+    ]), 200, 3, {
+        data: [{ id: CORPUS_AUTHOR.id }, CORPUS_AUTHOR, [CORPUS_AUTHOR]],
+        code: "A1009",
+        cause: null,
+    }),
+    answered("argument: a plan reference in a where to an operation index no earlier step has → 422 A2007 / V1016", planRequest("corpus-arg-ref-where-index", [
+        CREATE_ID,
+        planNode("authors", "find.unique", { where: { id: ref(5, CREATE_ID_PRINT, "id") } }, "fp1:VS6Zk71avpYzuC90z8qzrQ"),
+    ]), 422, 0, {
+        data: null,
+        code: "A2007",
+        cause: {
+            message: ARGUMENTS_FAILED,
+            issues: [
+                {
+                    code: "V1016",
+                    path: ["operations", 1, "args", "where", "id", "$ref", "operation"],
+                    message: "Transaction reference operation index is invalid.",
+                },
+            ],
+            operation: 1,
+        },
+    }),
+];
 const ARGUMENT_VALIDATION = [
     answered("argument: an unknown field in where → 422 A2004 / V1005", corpusRequest("find/many", { where: { nope: { equals: "x" } } }, "corpus-arg-field"), 422, 0, {
         data: null,
@@ -818,6 +848,7 @@ export const AvProtocolFixtures = [
     ...METHOD,
     ...ABSENCE,
     ...TRANSACTIONS,
+    ...TRANSACTION_REFERENCES,
     ...INTERNAL,
     ...CONFLICT,
     ...WIRE_SCALARS,

package/dist/protocol/protocol-fixtures.json-codec.d.ts

@@ -0,0 +1,43 @@
+import type { AvProtocolFixture } from "./protocol-fixture.js";
+/**
+ * A long run of one character in a request body, spelled as a recipe instead of
+ * its bytes: `prefix + repeat × times + suffix`. The one oversized-body row
+ * would otherwise be a megabyte of `x`.
+ */
+export type ProtocolFixtureContentRecipe = {
+    readonly prefix?: string;
+    readonly repeat: string;
+    readonly times: number;
+    readonly suffix?: string;
+};
+/** A row as the JSON file holds it: a raw body's content may be a recipe. */
+export type ProtocolFixtureJsonRow = Omit<AvProtocolFixture, "request"> & {
+    readonly request: Omit<AvProtocolFixture["request"], "body"> & {
+        readonly body: {
+            readonly kind: "raw";
+            readonly content: string | ProtocolFixtureContentRecipe;
+        } | {
+            readonly kind: "parsed";
+            readonly value: unknown;
+        };
+    };
+};
+/** The file: the protocol version, the corpus's mount point, its ClientContracts, every row. */
+export type ProtocolFixturesJson = {
+    readonly protocolVersion: number;
+    readonly entrypoint: string;
+    readonly clientContractHash: string;
+    /** Each ClientContract a row targets: its hash and its exact `GET /_contract` bytes. */
+    readonly contracts: readonly {
+        readonly hash: string;
+        readonly document: string;
+    }[];
+    readonly rows: readonly ProtocolFixtureJsonRow[];
+};
+/** A row of the file, expanded back to the TS row it was written from. */
+export declare function expandProtocolFixtureRow(row: ProtocolFixtureJsonRow): AvProtocolFixture;
+/**
+ * `fixtures/protocol-v1.json`, as text: one line per ClientContract and per row,
+ * in corpus order, so a change to the corpus is a change to its own lines.
+ */
+export declare function protocolFixturesJson(): Promise<string>;

package/dist/protocol/protocol-fixtures.json-codec.js

@@ -0,0 +1,89 @@
+import { AVENTARA_PROTOCOL_VERSION } from "@aventara/core/internal";
+import { AvProtocol } from "@aventara/core/protocol";
+import { CORPUS_CLIENT_CONTRACT_HASH, CORPUS_ENTRYPOINT, CORPUS_NONE_CLIENT_CONTRACT_HASH, createCorpusFramework, } from "./corpus-contract.fixture.js";
+import { AvProtocolFixtures } from "./protocol-fixtures.js";
+const RECIPE_MINIMUM = 1024;
+function recipeOf(text) {
+    let best = { start: 0, length: 0 };
+    let start = 0;
+    for (let index = 1; index <= text.length; index += 1) {
+        if (index === text.length || text[index] !== text[start]) {
+            if (index - start > best.length) {
+                best = { start, length: index - start };
+            }
+            start = index;
+        }
+    }
+    if (best.length < RECIPE_MINIMUM) {
+        return undefined;
+    }
+    const prefix = text.slice(0, best.start);
+    const suffix = text.slice(best.start + best.length);
+    return {
+        ...(prefix === "" ? {} : { prefix }),
+        repeat: text[best.start],
+        times: best.length,
+        ...(suffix === "" ? {} : { suffix }),
+    };
+}
+function encodeRow(row) {
+    const { body } = row.request;
+    if (body.kind === "parsed") {
+        return { ...row, request: { ...row.request, body } };
+    }
+    if (typeof body.content !== "string") {
+        throw new Error(`protocol fixture "${row.label}": a body of bytes has no JSON spelling`);
+    }
+    return {
+        ...row,
+        request: {
+            ...row.request,
+            body: { kind: "raw", content: recipeOf(body.content) ?? body.content },
+        },
+    };
+}
+export function expandProtocolFixtureRow(row) {
+    const { body } = row.request;
+    if (body.kind === "parsed" || typeof body.content === "string") {
+        return row;
+    }
+    const { prefix = "", repeat, times, suffix = "" } = body.content;
+    return {
+        ...row,
+        request: {
+            ...row.request,
+            body: { kind: "raw", content: prefix + repeat.repeat(times) + suffix },
+        },
+    };
+}
+async function contractDocument(contractHash) {
+    const { framework } = await createCorpusFramework(contractHash);
+    return AvProtocol.bind(framework).encodeContract({
+        method: "GET",
+        path: "/_contract",
+        headers: {},
+        body: { kind: "raw", content: "" },
+    }).body;
+}
+export async function protocolFixturesJson() {
+    if (AVENTARA_PROTOCOL_VERSION !== 1) {
+        throw new Error(`protocol-v1.json describes protocol version 1, not ${AVENTARA_PROTOCOL_VERSION}`);
+    }
+    const contracts = [
+        {
+            hash: CORPUS_CLIENT_CONTRACT_HASH,
+            document: await contractDocument(CORPUS_CLIENT_CONTRACT_HASH),
+        },
+        {
+            hash: CORPUS_NONE_CLIENT_CONTRACT_HASH,
+            document: await contractDocument(CORPUS_NONE_CLIENT_CONTRACT_HASH),
+        },
+    ];
+    const head = JSON.stringify({
+        protocolVersion: AVENTARA_PROTOCOL_VERSION,
+        entrypoint: CORPUS_ENTRYPOINT,
+        clientContractHash: CORPUS_CLIENT_CONTRACT_HASH,
+    }).slice(0, -1);
+    const lines = (items) => items.map((item) => JSON.stringify(item)).join(",\n");
+    return `${head},"contracts":[\n${lines(contracts)}\n],"rows":[\n${lines(AvProtocolFixtures.map(encodeRow))}\n]}\n`;
+}