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

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

@@ -8,6 +8,8 @@ export const inProcessDriver = async (framework) => {
                     return protocol.encodeContract(request);
                 case "/_transactions":
                     return protocol.handleTransaction(request);
+                case "/_access/can":
+                    return protocol.handleCan(request);
                 default:
                     return protocol.handleOperation(request);
             }

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

@@ -2,7 +2,8 @@ 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`, `/_contract` on `encodeContract`,
+ * `/_transactions` on `handleTransaction`, `/_access/can` on `handleCan`,
+ * `/_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

@@ -14,6 +14,8 @@ export const perRouteDriver = async (framework) => {
                     return protocol.handleOperation(request);
                 case "transactions":
                     return protocol.handleTransaction(request);
+                case "can":
+                    return protocol.handleCan(request);
                 case "contract":
                     return protocol.encodeContract(request);
                 default:

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

@@ -1,6 +1,6 @@
 import type { AvProtocolDriver } from "./protocol-driver.js";
 /**
- * `runAvProtocolConformance(driver)` — drives the protocol fixture corpus
+ * `runAvProtocolConformance(driver)` drives the protocol fixture corpus
  * through one host.
  *
  * Every row a host answers is driven; rows whose `client.outcome` is
@@ -12,17 +12,17 @@ import type { AvProtocolDriver } from "./protocol-driver.js";
  * held to the row's `server` block:
  *
  * - `status`, exactly;
- * - `code`: the body is a framework envelope carrying that code — or, for
+ * - `code`: the body is a framework envelope carrying that code or, for
  *   `null`, is none;
  * - `causeKeys`: the exact sorted key set of `cause`;
  * - `issues`: each issue's `code` and `path`, in order;
  * - `adapterCalls`: the operations the corpus Adapter was handed, exactly;
  * - `responseHeaders`: each named header present (names matched without
- *   regard to case) with exactly that value — a host may add its own;
+ *   regard to case) with exactly that value; a host may add its own;
  * - `bodyBytes`: the body text, exactly.
  *
  * Resolves one result per driven row, in corpus order, each with the
- * mismatches found — none when the host conforms. A driver that throws is a
+ * mismatches found (none when the host conforms). A driver that throws is a
  * mismatch of its row, not a rejection of the run. Works with any test
  * runner: assert on the results with whatever runner you use.
  */

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

@@ -1,4 +1,4 @@
-import type { Framework } from "@aventara/core";
+import type { AvFramework } from "@aventara/core";
 /**
  * The server side of the protocol fixture corpus (`AvProtocolFixtures`), for
  * a client or host author who serves it through their own stack: a Framework
@@ -17,13 +17,15 @@ export declare const AvProtocolCorpus: {
      * pure function of the operation it is handed. `contractHash` picks which
      * 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 main one for anything else.
+     * `/_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.
      */
-    readonly framework: (contractHash?: string) => Promise<Framework>;
+    readonly framework: (contractHash?: string) => Promise<AvFramework>;
     /** Where the corpus Framework is mounted; every row's `path` is relative to it. */
     readonly entrypoint: string;
     /**
-     * The hash of the main corpus ClientContract — what a client generated against
+     * The hash of the main corpus ClientContract: what a client generated against
      * it sends as `Aventara-Contract-Hash`, and what `GET /_contract` names.
      */
     readonly clientContractHash: string;

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

@@ -1,4 +1,4 @@
-import type { Framework } from "@aventara/core";
+import type { AvFramework } from "@aventara/core";
 import type { AvProtocolRequest, AvProtocolResponse } from "@aventara/core/protocol";
 /**
  * One host under test, as `runAvProtocolConformance` drives it: given the
@@ -7,7 +7,7 @@ import type { AvProtocolRequest, AvProtocolResponse } from "@aventara/core/proto
  * and body text, as an `AvProtocolResponse`). The run calls `close` once per
  * row, after its one request.
  */
-export type AvProtocolDriver = (framework: Framework) => Promise<{
+export type AvProtocolDriver = (framework: AvFramework) => Promise<{
     readonly send: (request: AvProtocolRequest) => Promise<AvProtocolResponse>;
     readonly close: () => Promise<void>;
 }>;

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

@@ -1,4 +1,4 @@
-import { 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_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",
@@ -347,7 +347,8 @@ const TRANSACTIONS = [
     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,
@@ -371,7 +372,7 @@ const absentRequest = (path, requestId, headers = {}, method = "POST") => {
     return { ...base, method, path, headers: { ...base.headers, ...headers } };
 };
 const unavailableOperation = (resource, operation, key) => ({
-    message: VALIDATION_FAILED,
+    message: OPERATION_UNAVAILABLE,
     issues: [
         {
             path: [key],
@@ -381,7 +382,7 @@ const unavailableOperation = (resource, operation, key) => ({
     ],
 });
 const unavailableResource = (resource) => ({
-    message: VALIDATION_FAILED,
+    message: RESOURCE_UNAVAILABLE,
     issues: [
         {
             code: "V1005",
@@ -836,6 +837,146 @@ const CORRELATION = [
         ["an id with a space", "a b"],
     ].map(([what, id]) => answered(`correlation: ${what} is not adopted, and never refused → 200 A1000`, corpusRequest("find/many", {}, id), 200, 1, { data: [CORPUS_AUTHOR], code: "A1000", cause: null }, { "Content-Type": "application/json" })),
 ];
+const canRequest = (requestId, questions, overrides = {}) => {
+    const base = corpusRequest("", { questions }, requestId);
+    return {
+        ...base,
+        path: "/_access/can",
+        headers: {
+            ...base.headers,
+            "Aventara-Contract-Hash": CORPUS_ACCESS_CLIENT_CONTRACT_HASH,
+        },
+        ...overrides,
+    };
+};
+const AUTHOR_ROW = { where: { id: CORPUS_AUTHOR.id } };
+const QUESTIONS_INVALID = "Operation arguments failed framework validation.";
+const ACCESS_QUESTIONS = [
+    answered("can: three questions in one request, one answer each → 200 A1000", canRequest("corpus-can-three", [
+        { resource: "authors", action: "update", ...AUTHOR_ROW },
+        { resource: "authors", action: "delete", ...AUTHOR_ROW },
+        { resource: "authors", action: "read" },
+    ]), 200, 1, { data: [true, false, true], code: "A1000", cause: null }),
+    answered("can: a row that does not exist answers false, never A2003", canRequest("corpus-can-missing", [
+        {
+            resource: "authors",
+            action: "update",
+            where: { id: CORPUS_NOBODY },
+        },
+    ]), 200, 1, { data: [false], code: "A1000", cause: null }),
+    answered("can: an operation the client is not offered answers false", canRequest("corpus-can-unoffered", [
+        { resource: "secrets", action: "read" },
+        { resource: "samples", action: "delete" },
+    ]), 200, 0, { data: [false, false], code: "A1000", cause: null }),
+    answered("can: an AvError the engine throws answers false", canRequest("corpus-can-engine-refuses", [
+        { resource: "books", action: "read" },
+        { resource: "authors", action: "read" },
+    ]), 200, 0, { data: [false, true], code: "A1000", cause: null }),
+    answered("can: no questions, no answers → 200 A1000", canRequest("corpus-can-none", []), 200, 0, { data: [], code: "A1000", cause: null }),
+    absent('/_access/can without access → 404 A2002 at ["questions"]', {
+        ...canRequest("corpus-absent-can", []),
+        headers: {
+            ...canRequest("corpus-absent-can", []).headers,
+            "Aventara-Contract-Hash": CORPUS_CLIENT_CONTRACT_HASH,
+        },
+    }, 404, "A2002", {
+        message: "Access questions are not available on the active Contract.",
+        issues: [
+            {
+                code: "V1006",
+                path: ["questions"],
+                message: "Access questions are not available on the active Contract.",
+            },
+        ],
+    }),
+    refused("method: GET on /_access/can → 405 A2012 with Allow: POST", canRequest("corpus-can-get", [], { method: "GET" }), 405, "A2012", "The HTTP method is not allowed on this framework route.", { Allow: "POST" }),
+    answered("can: an unknown and a client-hidden Resource → 404 A2001 for the batch", canRequest("corpus-can-unknown", [
+        { resource: "authors", action: "read" },
+        { resource: "nope", action: "read" },
+        { resource: "hiddenRes", action: "read" },
+    ]), 404, 0, {
+        data: null,
+        code: "A2001",
+        cause: {
+            message: "The requested Resource is not available.",
+            issues: [
+                {
+                    code: "V1005",
+                    path: ["questions", 1, "resource"],
+                    message: 'Resource "nope" is not available in the active Contract.',
+                },
+                {
+                    code: "V1005",
+                    path: ["questions", 2, "resource"],
+                    message: 'Resource "hiddenRes" is not available in the active Contract.',
+                },
+            ],
+        },
+    }),
+    answered('can: a malformed question → 422 A2004 at ["questions", i, …]', canRequest("corpus-can-malformed", [
+        { resource: "authors", action: "refund" },
+        { resource: "authors", action: "read", where: { name: "Ada" } },
+        { resource: "authors", action: "create", ...AUTHOR_ROW },
+    ]), 422, 0, {
+        data: null,
+        code: "A2004",
+        cause: {
+            message: QUESTIONS_INVALID,
+            issues: [
+                {
+                    code: "V1002",
+                    path: ["questions", 0, "action"],
+                    message: 'action must be one of "read", "create", "update" or "delete".',
+                },
+                {
+                    code: "V1007",
+                    path: ["questions", 1, "where"],
+                    message: 'Unique selector must exactly match one active identifier on Resource "authors".',
+                },
+                {
+                    code: "V1001",
+                    path: ["questions", 2, "where"],
+                    message: "A create question names no row: it takes no where.",
+                },
+            ],
+        },
+    }),
+    answered("can: more questions than maxListLimit → 422 A2009", canRequest("corpus-can-over-limit", Array.from({ length: 251 }, () => ({
+        resource: "authors",
+        action: "read",
+    }))), 422, 0, {
+        data: null,
+        code: "A2009",
+        cause: {
+            message: QUESTIONS_INVALID,
+            issues: [
+                {
+                    code: "V1014",
+                    path: ["questions"],
+                    message: "Question count exceeds maxListLimit (250).",
+                },
+            ],
+        },
+    }),
+    answered("can: the engine throws → 500 A3000", canRequest("corpus-can-engine-throws", [
+        { resource: "samples", action: "read" },
+    ]), 500, 0, {
+        data: null,
+        code: "A3000",
+        cause: { message: "Internal framework error." },
+    }),
+    answered("can: the Adapter fails reading the row → 500 A3001", canRequest("corpus-can-adapter-throws", [
+        {
+            resource: "authors",
+            action: "update",
+            where: { id: CORPUS_TRIGGER.adapterThrows },
+        },
+    ]), 500, 1, {
+        data: null,
+        code: "A3001",
+        cause: { message: "Adapter execution failed." },
+    }),
+];
 export const AvProtocolFixtures = [
     ...CONTRACT_DISCOVERY,
     ...SUCCESS_STATUSES,
@@ -848,6 +989,7 @@ export const AvProtocolFixtures = [
     ...ABSENCE,
     ...TRANSACTIONS,
     ...TRANSACTION_REFERENCES,
+    ...ACCESS_QUESTIONS,
     ...INTERNAL,
     ...CONFLICT,
     ...WIRE_SCALARS,

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

@@ -4,7 +4,7 @@ import type { AvProtocolFixture } from "./protocol-fixture.js";
  * its bytes: `prefix + repeat × times + suffix`. The one oversized-body row
  * would otherwise be a megabyte of `x`.
  */
-export type ProtocolFixtureContentRecipe = {
+type ProtocolFixtureContentRecipe = {
     readonly prefix?: string;
     readonly repeat: string;
     readonly times: number;
@@ -41,3 +41,4 @@ export declare function expandProtocolFixtureRow(row: ProtocolFixtureJsonRow): A
  * in corpus order, so a change to the corpus is a change to its own lines.
  */
 export declare function protocolFixturesJson(): Promise<string>;
+export {};

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