@aventara/testing 1.0.0-rc.10 → 1.0.0-rc.12

package/dist/protocol/in-process.driver.d.ts

@@ -1,3 +1,4 @@
+import { AvProtocol, type AvProtocolResponse } from "@aventara/core/protocol";
 import type { AvProtocolDriver } from "./protocol-driver.js";
 /**
  * The protocol hosted in process, with no HTTP stack: `/_contract` goes to
@@ -6,3 +7,5 @@ import type { AvProtocolDriver } from "./protocol-driver.js";
  * `protocol.handleOperation`, and the answer is written back as it is.
  */
 export declare const inProcessDriver: AvProtocolDriver;
+/** An Operation Set's answer as a host writes it: a streamed one's lines, in order, as its body text. */
+export declare function written(answer: Awaited<ReturnType<ReturnType<typeof AvProtocol.bind>["handleAll"]>>): Promise<AvProtocolResponse>;

package/dist/protocol/in-process.driver.js

@@ -10,6 +10,8 @@ export const inProcessDriver = async (framework) => {
                     return protocol.handleTransaction(request);
                 case "/_access/can":
                     return protocol.handleCan(request);
+                case "/_all":
+                    return written(await protocol.handleAll(request));
                 default:
                     return protocol.handleOperation(request);
             }
@@ -17,3 +19,13 @@ export const inProcessDriver = async (framework) => {
         close: async () => undefined,
     };
 };
+export async function written(answer) {
+    if (typeof answer.body === "string") {
+        return answer;
+    }
+    let body = "";
+    for await (const line of answer.body) {
+        body += line;
+    }
+    return { status: answer.status, headers: answer.headers, body };
+}

package/dist/protocol/per-route.driver.d.ts

@@ -3,7 +3,7 @@ import type { AvProtocolDriver } from "./protocol-driver.js";
  * The protocol hosted in process as a host that mounts one route per
  * `protocol.surface()` entry (each operation on `handleOperation`,
  * `/_transactions` on `handleTransaction`, `/_access/can` on `handleCan`,
- * `/_contract` on `encodeContract`,
+ * `/_all` on `handleAll`, `/_contract` on `encodeContract`,
  * matched by method and path) and uses `protocol.answerAbsent` as the fallback
  * for everything it did not mount. `undefined` from the fallback is a path
  * outside the protocol, which this host answers with its own bodiless 404.

package/dist/protocol/per-route.driver.js

@@ -1,4 +1,5 @@
 import { AvProtocol } from "@aventara/core/protocol";
+import { written } from "./in-process.driver.js";
 const HOST_NOT_FOUND = Object.freeze({
     status: 404,
     headers: Object.freeze({}),
@@ -16,6 +17,8 @@ export const perRouteDriver = async (framework) => {
                     return protocol.handleTransaction(request);
                 case "can":
                     return protocol.handleCan(request);
+                case "all":
+                    return written(await protocol.handleAll(request));
                 case "contract":
                     return protocol.encodeContract(request);
                 default:

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

@@ -8,8 +8,9 @@ import type { AvProtocolDriver } from "./protocol-driver.js";
  * answer, so they are skipped. Each driven row runs against a fresh corpus
  * Framework, through a fresh driver session, with one request (the corpus
  * Framework whose ClientContract hash the row's `Aventara-Contract-Hash`
- * names; the main corpus contract for any other hash), and its answer is
- * held to the row's `server` block:
+ * names, or a cached read's `v` when it sends no such header; the main corpus
+ * contract for any other hash), and its answer is held to the row's `server`
+ * block:
  *
  * - `status`, exactly;
  * - `code`: the body is a framework envelope carrying that code or, for

package/dist/protocol/protocol-conformance.js

@@ -70,7 +70,11 @@ function mismatchesOf(server, response, adapterCalls) {
 }
 function contractHashOf(request) {
     const value = Object.entries(request.headers).find(([name]) => name.toLowerCase() === "aventara-contract-hash")?.[1];
-    return typeof value === "string" ? value : undefined;
+    if (typeof value === "string") {
+        return value;
+    }
+    const v = new URLSearchParams(request.query ?? "").get("v");
+    return v === null ? undefined : v;
 }
 function parsedBody(text) {
     try {

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

@@ -18,8 +18,9 @@ export declare const AvProtocolCorpus: {
      * corpus ClientContract it serves, as a row's `Aventara-Contract-Hash` does:
      * the corpus's `transactions: "none"` contract for that contract's hash (the
      * `/_transactions` absence rows send it), the one with the framework's
-     * `access` option for its hash (the `/_access/can` rows send it), the main one
-     * for anything else.
+     * `access` option for its hash (the `/_access/can` rows send it), the one with
+     * cached reads for its hash (the cached-read rows send it as their query's
+     * `v`), the main one for anything else.
      */
     readonly framework: (contractHash?: string) => Promise<AvFramework>;
     /** Where the corpus Framework is mounted; every row's `path` is relative to it. */

package/dist/protocol/protocol-fixtures.js

@@ -1,4 +1,4 @@
-import { CORPUS_ACCESS_CLIENT_CONTRACT_HASH, CORPUS_AUTHOR, CORPUS_CLIENT_CONTRACT_DOCUMENT, CORPUS_CLIENT_CONTRACT_HASH, CORPUS_NOBODY, CORPUS_NONE_CLIENT_CONTRACT_HASH, CORPUS_TRIGGER, } from "./corpus-contract.fixture.js";
+import { CORPUS_ACCESS_CLIENT_CONTRACT_HASH, CORPUS_AUTHOR, CORPUS_CACHE_CLIENT_CONTRACT_HASH, CORPUS_CLIENT_CONTRACT_DOCUMENT, CORPUS_CLIENT_CONTRACT_HASH, CORPUS_NOBODY, CORPUS_NONE_CLIENT_CONTRACT_HASH, CORPUS_TRIGGER, } from "./corpus-contract.fixture.js";
 const OPERATION_REQUEST = {
     method: "POST",
     path: "/_resources/authors/find/many",
@@ -212,6 +212,7 @@ const contractServed = (label, requestId, headers = {}) => ({
             ...answeredHeaders(requestId),
             ETag: CORPUS_ETAG,
             "Cache-Control": "no-cache",
+            "X-Content-Type-Options": "nosniff",
         },
         bodyBytes: CORPUS_CLIENT_CONTRACT_DOCUMENT,
     },
@@ -228,6 +229,7 @@ const contractNotModified = (label, requestId, ifNoneMatch) => ({
             "Aventara-Request-Id": requestId,
             ETag: CORPUS_ETAG,
             "Cache-Control": "no-cache",
+            "X-Content-Type-Options": "nosniff",
         },
         bodyBytes: "",
     },
@@ -977,6 +979,340 @@ const ACCESS_QUESTIONS = [
         cause: { message: "Adapter execution failed." },
     }),
 ];
+const setEntry = (resource, operation, args = {}) => {
+    const [family, variant] = operation.split(".");
+    return { resource, family, variant, args };
+};
+const setRequest = (requestId, operations, headers = {}, overrides = {}) => {
+    const base = corpusRequest("", { operations }, requestId);
+    return {
+        ...base,
+        path: "/_all",
+        headers: { ...base.headers, ...headers },
+        ...overrides,
+    };
+};
+const countEntries = (count) => Object.fromEntries(Array.from({ length: count }, (_, index) => [
+    `k${index}`,
+    setEntry("authors", "find.count"),
+]));
+const NDJSON = "application/x-ndjson";
+const SET_INVALID = "Operation Set failed framework validation.";
+const OVER_MAX_ALL = {
+    data: null,
+    code: "A2009",
+    cause: {
+        message: "Operation count exceeds the active Contract limit.",
+        issues: [
+            {
+                code: "V1014",
+                path: ["operations"],
+                message: "Operation count exceeds maxAll (10).",
+            },
+        ],
+    },
+};
+const AUTHOR_LIST = {
+    data: [CORPUS_AUTHOR],
+    code: "A1000",
+    cause: null,
+};
+const AUTHOR_MISSING = {
+    data: null,
+    code: "A2003",
+    cause: { message: NO_MATCH },
+};
+const OPERATION_SETS = [
+    answered("all: reads and writes in one request → 200 A1000, each key its single route's envelope", setRequest("corpus-all-mixed", {
+        list: setEntry("authors", "find.many"),
+        total: setEntry("authors", "find.count"),
+        missing: setEntry("authors", "find.unique", {
+            where: { id: CORPUS_NOBODY },
+        }),
+        created: setEntry("authors", "create.one", { data: DATA }),
+        denied: setEntry("authors", "find.first", {
+            where: { id: CORPUS_TRIGGER.guardDenies },
+        }),
+        hidden: setEntry("hiddenRes", "find.many"),
+    }), 200, 4, {
+        data: {
+            list: AUTHOR_LIST,
+            total: { data: 2, code: "A1000", cause: null },
+            missing: AUTHOR_MISSING,
+            created: { data: CORPUS_AUTHOR, code: "A1002", cause: null },
+            denied: {
+                data: null,
+                code: "A4001",
+                cause: { message: "Operation denied by a framework guard." },
+            },
+            hidden: {
+                data: null,
+                code: "A2001",
+                cause: {
+                    message: RESOURCE_UNAVAILABLE,
+                    issues: [
+                        {
+                            code: "V1005",
+                            path: ["resource"],
+                            message: 'Resource "hiddenRes" is not available in the active Contract.',
+                        },
+                    ],
+                },
+            },
+        },
+        code: "A1000",
+        cause: null,
+    }),
+    {
+        label: "all: __proto__ and constructor are plain keys",
+        request: {
+            ...setRequest("corpus-all-hostile-keys", {}),
+            body: {
+                kind: "raw",
+                content: '{"operations":{"__proto__":{"resource":"authors","family":"find","variant":"count","args":{}},"constructor":{"resource":"authors","family":"find","variant":"count","args":{}}}}',
+            },
+        },
+        server: {
+            status: 200,
+            code: "A1000",
+            adapterCalls: 2,
+            responseHeaders: answeredHeaders("corpus-all-hostile-keys"),
+            bodyBytes: '{"data":{"__proto__":{"data":2,"code":"A1000","cause":null},"constructor":{"data":2,"code":"A1000","cause":null}},"code":"A1000","cause":null}',
+        },
+        client: { outcome: "resolve" },
+    },
+    {
+        label: "all: streamed (Accept: application/x-ndjson) → 200, one line per entry in settle order",
+        request: setRequest("corpus-all-streamed", {
+            list: setEntry("authors", "find.many"),
+            missing: setEntry("authors", "find.unique", {
+                where: { id: CORPUS_NOBODY },
+            }),
+        }, { Accept: NDJSON }),
+        server: {
+            status: 200,
+            code: null,
+            adapterCalls: 2,
+            responseHeaders: {
+                "Content-Type": NDJSON,
+                "Cache-Control": "no-store",
+                "X-Accel-Buffering": "no",
+                "Aventara-Request-Id": "corpus-all-streamed",
+            },
+            bodyBytes: `${JSON.stringify({ key: "missing", envelope: AUTHOR_MISSING })}\n${JSON.stringify({ key: "list", envelope: AUTHOR_LIST })}\n`,
+        },
+        client: { outcome: "resolve" },
+    },
+    answered("all: refused whole while streamed is plain JSON at its status (more than maxAll → 422 A2009)", setRequest("corpus-all-streamed-refused", countEntries(11), {
+        Accept: NDJSON,
+    }), 422, 0, OVER_MAX_ALL),
+    answered("all: more entries than limits.maxAll → 422 A2009 / V1014", setRequest("corpus-all-over-max", countEntries(11)), 422, 0, OVER_MAX_ALL),
+    answered("all: no entries → 422 A2004 / V1004", setRequest("corpus-all-empty", {}), 422, 0, {
+        data: null,
+        code: "A2004",
+        cause: {
+            message: SET_INVALID,
+            issues: [
+                {
+                    code: "V1004",
+                    path: ["operations"],
+                    message: "Value outside accepted range.",
+                },
+            ],
+        },
+    }),
+    answered("all: a key that is no identifier → 422 A2004 / V1001", setRequest("corpus-all-bad-key", {
+        "a-b": setEntry("authors", "find.count"),
+    }), 422, 0, {
+        data: null,
+        code: "A2004",
+        cause: {
+            message: SET_INVALID,
+            issues: [
+                {
+                    code: "V1001",
+                    path: ["operations"],
+                    message: "Every operation key must be an identifier.",
+                },
+            ],
+        },
+    }),
+    answered("all: an entry with a fifth member → 422 A2004 / V1001 at it", setRequest("corpus-all-entry-member", {
+        a: { ...setEntry("authors", "find.count"), extra: 1 },
+    }), 422, 0, {
+        data: null,
+        code: "A2004",
+        cause: {
+            message: SET_INVALID,
+            issues: [
+                {
+                    code: "V1001",
+                    path: ["operations", "a", "extra"],
+                    message: 'Property "extra" is not valid here.',
+                },
+            ],
+        },
+    }),
+    answered("all: a body member beside operations → 422 A2004 / V1001 at it", {
+        ...setRequest("corpus-all-body-member", {}),
+        body: {
+            kind: "raw",
+            content: JSON.stringify({
+                operations: { a: setEntry("authors", "find.count") },
+                extra: 1,
+            }),
+        },
+    }, 422, 0, {
+        data: null,
+        code: "A2004",
+        cause: {
+            message: SET_INVALID,
+            issues: [
+                {
+                    code: "V1001",
+                    path: ["extra"],
+                    message: 'Property "extra" is not valid here.',
+                },
+            ],
+        },
+    }),
+    refused("all: a stale hash → 409 A2005, nothing runs", setRequest("corpus-all-stale", { a: setEntry("authors", "find.count") }, { "Aventara-Contract-Hash": STALE_HASH }), 409, "A2005", STALE_CLIENT),
+    refused("method: GET on /_all → 405 A2012 with Allow: POST", setRequest("corpus-all-get", { a: setEntry("authors", "find.count") }, {}, { method: "GET" }), 405, "A2012", "The HTTP method is not allowed on this framework route.", { Allow: "POST" }),
+];
+const CACHE_V = encodeURIComponent(CORPUS_CACHE_CLIENT_CONTRACT_HASH);
+const plainQ = (args) => encodeURIComponent(JSON.stringify(args));
+const DEFLATED_WHERE_A1 = "q1Yqz0gtSlWyqlbKTFGyUko0VKqtBQA";
+const DEFLATE_BOMB = `7cEBDQAwCAMwK89k3A06CN4RQttO5ecB${"A".repeat(2582)}DnZBY`;
+const cachedRead = (route, query, requestId, extra = {}, method = "GET") => ({
+    method,
+    path: `/_resources/${route}`,
+    ...(query === undefined ? {} : { query }),
+    headers: { "Aventara-Request-Id": requestId, ...extra },
+    body: { kind: "raw", content: "" },
+});
+const cacheQuery = (args) => `q=${plainQ(args)}&v=${CACHE_V}`;
+const GET_HEADERS = {
+    "Referrer-Policy": "no-referrer",
+    "X-Content-Type-Options": "nosniff",
+};
+const GET_REFUSED = { "Cache-Control": "no-store", ...GET_HEADERS };
+const USER_CACHE = {
+    "Cache-Control": "private, max-age=60",
+    Vary: "Authorization, Cookie",
+    ...GET_HEADERS,
+};
+const AUTHOR_LIST_ETAG = '"Hw1Lk7KqP84xBk693Mz4B2LG8SHbThNf7TUw48xZUGI"';
+const AUTHOR_ETAG = '"bY0J9tlkShjFaZpC9KaS3xX3YaoRzKji-HAb69ASAsQ"';
+const EVERYONE_CACHE = {
+    "Cache-Control": "public, max-age=300",
+    ...GET_HEADERS,
+};
+const BOOK_LIST_ETAG = '"boybbH17GgkJBSByRCwm0xJj3tbWWrPd2O0BPrDCNSo"';
+const BOOK_LIST = {
+    data: [{ authorId: CORPUS_AUTHOR.id, id: "b1", label: "book:b1" }],
+    code: "A1000",
+    cause: null,
+};
+const AUTHOR_FOUND = {
+    data: CORPUS_AUTHOR,
+    code: "A1000",
+    cause: null,
+};
+const CACHED_READS = [
+    answered('cache: GET for "user", plain q → 200 private, Vary, ETag', cachedRead("authors/find/many", cacheQuery({}), "corpus-cache-user"), 200, 1, AUTHOR_LIST, {
+        ...answeredHeaders("corpus-cache-user"),
+        ...USER_CACHE,
+        ETag: AUTHOR_LIST_ETAG,
+    }),
+    answered("cache: GET, compressed q → the plain form's answer", cachedRead("authors/find/unique", `q=${DEFLATED_WHERE_A1}&v=${CACHE_V}`, "corpus-cache-deflated"), 200, 1, AUTHOR_FOUND, {
+        ...answeredHeaders("corpus-cache-deflated"),
+        ...USER_CACHE,
+        ETag: AUTHOR_ETAG,
+    }),
+    {
+        label: "cache: If-None-Match its ETag → 304, no body, the same validators",
+        request: cachedRead("authors/find/many", cacheQuery({}), "corpus-cache-304", { "If-None-Match": AUTHOR_LIST_ETAG }),
+        server: {
+            status: 304,
+            code: null,
+            adapterCalls: 1,
+            responseHeaders: {
+                "Aventara-Request-Id": "corpus-cache-304",
+                ...USER_CACHE,
+                ETag: AUTHOR_LIST_ETAG,
+            },
+            bodyBytes: "",
+        },
+        client: { outcome: "resolve" },
+    },
+    answered('cache: GET for "everyone" → 200 public, no Vary, no request id', cachedRead("books/find/many", cacheQuery({}), "corpus-cache-everyone"), 200, 1, BOOK_LIST, {
+        "Content-Type": "application/json",
+        ...EVERYONE_CACHE,
+        ETag: BOOK_LIST_ETAG,
+    }),
+    {
+        label: "cache: If-None-Match weak W/ on a public answer → 304",
+        request: cachedRead("books/find/many", cacheQuery({}), "corpus-cache-public-304", { "If-None-Match": `W/${BOOK_LIST_ETAG}` }),
+        server: {
+            status: 304,
+            code: null,
+            adapterCalls: 1,
+            responseHeaders: { ...EVERYONE_CACHE, ETag: BOOK_LIST_ETAG },
+            bodyBytes: "",
+        },
+        client: { outcome: "resolve" },
+    },
+    answered('cache: GET for "anonymous", no Cookie or Authorization → public', cachedRead("authors/find/first", cacheQuery({}), "corpus-cache-anonymous"), 200, 1, AUTHOR_FOUND, {
+        "Content-Type": "application/json",
+        "Cache-Control": "public, max-age=30",
+        Vary: "Authorization, Cookie",
+        ...GET_HEADERS,
+        ETag: AUTHOR_ETAG,
+    }),
+    answered('cache: GET for "anonymous" with a Cookie → private', cachedRead("authors/find/first", cacheQuery({}), "corpus-cache-signed-in", {
+        Cookie: "session=s1",
+    }), 200, 1, AUTHOR_FOUND, {
+        ...answeredHeaders("corpus-cache-signed-in"),
+        "Cache-Control": "private, max-age=30",
+        Vary: "Authorization, Cookie",
+        ...GET_HEADERS,
+        ETag: AUTHOR_ETAG,
+    }),
+    refused("cache: a query parameter beside q and v → 400 A2000, no-store", cachedRead("authors/find/many", `${cacheQuery({})}&utm=1`, "corpus-cache-extra-param"), 400, "A2000", MALFORMED, GET_REFUSED),
+    refused("cache: q that is no JSON object → 400 A2000, no-store", cachedRead("authors/find/many", cacheQuery([1]), "corpus-cache-q-list"), 400, "A2000", MALFORMED, GET_REFUSED),
+    refused("cache: a compressed q inflating past maxRequestBytes → 413 A2010, no-store", cachedRead("authors/find/many", `q=${DEFLATE_BOMB}&v=${CACHE_V}`, "corpus-cache-bomb"), 413, "A2010", "The request body exceeds the maximum request size.", GET_REFUSED),
+    refused("cache: a stale v → 409 A2005, no-store", cachedRead("authors/find/many", `q=${plainQ({})}&v=${encodeURIComponent(STALE_HASH)}`, "corpus-cache-stale"), 409, "A2005", STALE_CLIENT, GET_REFUSED),
+    {
+        ...refused("cache: a unique miss → 404 A2003, no-store", cachedRead("authors/find/unique", cacheQuery({ where: { id: CORPUS_NOBODY } }), "corpus-cache-miss"), 404, "A2003", NO_MATCH, GET_REFUSED),
+        server: {
+            status: 404,
+            code: "A2003",
+            causeKeys: ["message"],
+            adapterCalls: 1,
+            responseHeaders: {
+                ...answeredHeaders("corpus-cache-miss"),
+                ...GET_REFUSED,
+            },
+            bodyBytes: JSON.stringify({
+                data: null,
+                code: "A2003",
+                cause: { message: NO_MATCH },
+            }),
+        },
+    },
+    refused("cache: the pipelines run on a GET: a guard refusal → 403 A4001, no-store", cachedRead("authors/find/many", cacheQuery({ where: { id: CORPUS_TRIGGER.guardDenies } }), "corpus-cache-denied"), 403, "A4001", "Operation denied by a framework guard.", GET_REFUSED),
+    refused("method: GET on a write → 405 A2012 with Allow: POST, no-store", cachedRead("authors/create/one", cacheQuery({ data: DATA }), "corpus-cache-get-write"), 405, "A2012", "The HTTP method is not allowed on this framework route.", { Allow: "POST", ...GET_REFUSED }),
+    refused("method: GET on a read with no cache stage → 405 A2012 with Allow: POST, no-store", cachedRead("samples/find/unique", cacheQuery({ where: { id: "s1" } }), "corpus-cache-get-uncached"), 405, "A2012", "The HTTP method is not allowed on this framework route.", { Allow: "POST", ...GET_REFUSED }),
+    refused("method: PUT on a cached read → 405 A2012 with Allow: GET, POST", {
+        ...corpusRequest("find/many", {}, "corpus-cache-put", { method: "PUT" }),
+        headers: {
+            "Content-Type": "application/json",
+            "Aventara-Protocol-Version": "1",
+            "Aventara-Contract-Hash": CORPUS_CACHE_CLIENT_CONTRACT_HASH,
+            "Aventara-Request-Id": "corpus-cache-put",
+        },
+    }, 405, "A2012", "The HTTP method is not allowed on this framework route.", { Allow: "GET, POST" }),
+];
 export const AvProtocolFixtures = [
     ...CONTRACT_DISCOVERY,
     ...SUCCESS_STATUSES,
@@ -990,6 +1326,8 @@ export const AvProtocolFixtures = [
     ...TRANSACTIONS,
     ...TRANSACTION_REFERENCES,
     ...ACCESS_QUESTIONS,
+    ...OPERATION_SETS,
+    ...CACHED_READS,
     ...INTERNAL,
     ...CONFLICT,
     ...WIRE_SCALARS,

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

@@ -1,6 +1,6 @@
 import { AVENTARA_PROTOCOL_VERSION } from "@aventara/core/internal";
 import { AvProtocol } from "@aventara/core/protocol";
-import { CORPUS_ACCESS_CLIENT_CONTRACT_HASH, CORPUS_CLIENT_CONTRACT_HASH, CORPUS_ENTRYPOINT, CORPUS_NONE_CLIENT_CONTRACT_HASH, createCorpusFramework, } from "./corpus-contract.fixture.js";
+import { CORPUS_ACCESS_CLIENT_CONTRACT_HASH, CORPUS_CACHE_CLIENT_CONTRACT_HASH, 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) {
@@ -82,6 +82,10 @@ export async function protocolFixturesJson() {
             hash: CORPUS_ACCESS_CLIENT_CONTRACT_HASH,
             document: await contractDocument(CORPUS_ACCESS_CLIENT_CONTRACT_HASH),
         },
+        {
+            hash: CORPUS_CACHE_CLIENT_CONTRACT_HASH,
+            document: await contractDocument(CORPUS_CACHE_CLIENT_CONTRACT_HASH),
+        },
     ];
     const head = JSON.stringify({
         protocolVersion: AVENTARA_PROTOCOL_VERSION,