@fuzdev/fuz_app 0.147.0 → 0.148.0

package/dist/testing/cross_backend/conformance_table.d.ts

@@ -1,10 +1,14 @@
 import '../assert_dev_env.js';
-import type { AppSurfaceSpec } from '../../http/surface.js';
+import type { AppSurfaceSpec, RpcEndpointSpec } from '../../http/surface.js';
+import type { RouteSpec } from '../../http/route_spec.js';
+import type { RpcAction } from '../../actions/action_rpc.js';
 import type { SessionOptions } from '../../auth/session_cookie.js';
-import { type RpcEndpointsSuiteOption } from '../rpc_helpers.js';
-import { type ConformanceCase } from './conformance_case.js';
+import { resolve_rpc_endpoints_for_setup, type RpcEndpointsSuiteOption } from '../rpc_helpers.js';
+import type { FetchTransport } from '../transports/fetch_transport.js';
+import { type ConformanceCase, type ConformancePrincipal } from './conformance_case.js';
 import type { BackendCapabilities } from './capabilities.js';
-import type { SetupTest } from './setup.js';
+import type { SetupTest, TestFixture } from './setup.js';
+import type { WsEndpointTarget } from './ws_endpoint.js';
 /**
  * Names a seeded `extra_accounts` username for the `role_holder` /
  * `wrong_role` principals — the only two that aren't backed by an
@@ -29,13 +33,91 @@ export interface ConformanceTableOptions {
     readonly capabilities: BackendCapabilities;
     /** RPC endpoints — resolved to find each method's action spec. */
     readonly rpc_endpoints: RpcEndpointsSuiteOption;
+    /**
+     * The RPC endpoints the backend live-mounts, for methods kept off the
+     * declared `rpc_endpoints` (cell verbs, opt-in resolvers, `_testing_*`
+     * backdoors). A method resolves from `rpc_endpoints` first and from here
+     * only when the declared surface lacks it, so passing a backend's whole
+     * live mount is fine. Omitted, only declared methods resolve.
+     */
+    readonly live_rpc_endpoints?: RpcEndpointsSuiteOption;
     /** Session options — needed to resolve the `rpc_endpoints` factory form. */
     readonly session_options: SessionOptions<string>;
     /** Maps the `role_holder` / `wrong_role` principals to seeded usernames. */
     readonly principals?: ConformancePrincipalConfig;
+    /**
+     * Run the cases over a WebSocket at this endpoint instead of HTTP: each RPC
+     * case's principal opens an admitted socket and sends its request as a
+     * frame. Only the cases `is_ws_conformance_case` admits run; the rest are
+     * left out, and so is an equivalence group left with fewer than two members.
+     */
+    readonly ws?: WsEndpointTarget;
     /** `describe` block label. Defaults to `'conformance table'`. */
     readonly suite_name?: string;
 }
+/** What `resolve_conformance_rpc_endpoints` reads. */
+export interface ConformanceRpcEndpointsOptions {
+    /** The declared RPC endpoints. */
+    readonly rpc_endpoints: RpcEndpointsSuiteOption;
+    /** The live-mounted RPC endpoints, for methods off the declared surface. */
+    readonly live_rpc_endpoints?: RpcEndpointsSuiteOption;
+    /** Session options — needed to resolve the factory forms. */
+    readonly session_options: SessionOptions<string>;
+}
+/**
+ * Resolve the endpoints a conformance case's RPC method is looked up in: the
+ * declared `rpc_endpoints`, then `live_rpc_endpoints`. `find_rpc_action`
+ * takes the first match, so a declared method resolves from the declared
+ * surface even when the live mount repeats it.
+ *
+ * @param options - the declared and live endpoints, and the session options
+ * @returns the endpoints in lookup order
+ */
+export declare const resolve_conformance_rpc_endpoints: (options: ConformanceRpcEndpointsOptions) => Array<RpcEndpointSpec>;
+/**
+ * Whether a case can run over a WebSocket: an RPC method (not a REST auth
+ * route), sent as `POST` (a `GET` row pins the HTTP query path), pinning no
+ * header value (a frame has no headers; an absence pin holds vacuously), as
+ * a principal that can hold a socket.
+ *
+ * @param c - the case
+ * @returns whether the WS leg runs it
+ */
+export declare const is_ws_conformance_case: (c: ConformanceCase) => boolean;
+/** A resolved principal: the transport + headers a case fires through. */
+export interface ResolvedConformancePrincipal {
+    readonly transport: FetchTransport;
+    readonly headers: Record<string, string>;
+    /**
+     * Suppress the default `Origin` header on the request. Required for
+     * non-browser credential probes (bearer / daemon) — `bearer_auth`
+     * discards the token when `Origin` / `Referer` is present.
+     */
+    readonly suppress_default_origin?: boolean;
+    /**
+     * The actor of the account the credential names — what the `principal`
+     * acting binding writes. Absent for principals that present no account.
+     */
+    readonly actor_id?: string;
+}
+/**
+ * Map a `ConformancePrincipal` onto the transport + headers it
+ * authenticates with, reading exclusively from the per-test `TestFixture`.
+ *
+ * The five always-available principals resolve from fixture accessors;
+ * `role_holder` / `wrong_role` read a seeded `extra_accounts` entry named
+ * via `options.principals` (throws a clear setup error when unconfigured);
+ * `scoped_token` mints its narrowed credential over the production path.
+ * Also used outside the table by suites that send a principal's requests
+ * themselves (`describe_rpc_adversarial_cross_tests`).
+ *
+ * @param fixture - the per-test fixture
+ * @param as - the principal
+ * @param principals - usernames for `role_holder` / `wrong_role`
+ * @param resolved_rpc_endpoints - the endpoints `scoped_token` mints through
+ * @returns the transport and headers the principal sends with
+ */
+export declare const resolve_conformance_principal: (fixture: TestFixture, as: ConformancePrincipal, principals?: ConformancePrincipalConfig, resolved_rpc_endpoints?: ReturnType<typeof resolve_rpc_endpoints_for_setup>) => Promise<ResolvedConformancePrincipal>;
 /**
  * Response headers that fingerprint the backend implementation or framework.
  * Neither spine emits these; the runner asserts they stay absent on EVERY
@@ -57,6 +139,64 @@ export declare const assert_no_fingerprint_headers: (headers: Record<string, str
  * always-on no-fingerprint floor.
  */
 export declare const assert_expected_headers: (headers: Record<string, string>, expected: Record<string, string | null>, label: string) => void;
+/** What `send_conformance_case` needs besides the case. */
+export interface SendConformanceCaseOptions {
+    /** The per-test fixture the principal resolves from. */
+    readonly fixture: TestFixture;
+    /** Surface spec — supplies the `RouteSpec`s for the REST branch. */
+    readonly surface_source: AppSurfaceSpec;
+    /** Usernames for the `role_holder` / `wrong_role` principals. */
+    readonly principals?: ConformancePrincipalConfig;
+    /**
+     * The endpoints RPC methods (and the `scoped_token` mint) resolve against —
+     * `resolve_conformance_rpc_endpoints` of the declared and live endpoints.
+     */
+    readonly resolved_rpc_endpoints: ReturnType<typeof resolve_rpc_endpoints_for_setup>;
+    /** Send the request as a frame on a socket at this endpoint instead of over HTTP. */
+    readonly ws?: WsEndpointTarget;
+}
+/** The spec a sent case resolved to — the RPC action, or the REST route. */
+export type ConformanceCaseTarget = {
+    readonly kind: 'rpc';
+    readonly path: string;
+    readonly action: RpcAction;
+} | {
+    readonly kind: 'rest';
+    readonly route: RouteSpec;
+};
+/**
+ * One case's request as sent and its response unparsed: the HTTP status, the
+ * response-headers snapshot (lowercased keys), and the JSON body exactly as
+ * the server sent it — the whole JSON-RPC envelope for an RPC method,
+ * `undefined` for a REST body that is not JSON.
+ *
+ * Over a WebSocket the body is the response frame, the headers are empty (a
+ * frame carries none), and the status is the one the HTTP binding answers
+ * for the frame's outcome: `200` for a result, else
+ * `jsonrpc_error_code_to_http_status` of its error code — so a row's
+ * `expect.status` reads as the error code on both transports.
+ */
+export interface ConformanceCaseResponse {
+    readonly target: ConformanceCaseTarget;
+    readonly status: number;
+    readonly headers: Record<string, string>;
+    readonly body: unknown;
+}
+/**
+ * Resolve a case's principal on `fixture` and send its request, asserting
+ * nothing about the response.
+ *
+ * The send half of the table runner, shared with the cross-backend
+ * differential (`describe_differential_conformance_tests`), which sends one
+ * case to two backends and compares what came back.
+ *
+ * @param c - the case
+ * @param options - the fixture, surface and endpoints to send through
+ * @returns the resolved target and the raw response
+ * @throws Error when the method is on neither the RPC surface nor the REST
+ *   auth routes
+ */
+export declare const send_conformance_case: (c: ConformanceCase, options: SendConformanceCaseOptions) => Promise<ConformanceCaseResponse>;
 /**
  * Register a `describe` block running every `ConformanceCase` as a
  * vitest `test` (or `xfail_until` for deferred-by-design rows). Drives

package/dist/testing/cross_backend/conformance_table.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conformance_table.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/conformance_table.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA8B9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAOnE,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAEN,KAAK,eAAe,EAEpB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAe,MAAM,YAAY,CAAC;AAIzD;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IAC1C,iEAAiE;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,gEAAgE;IAChE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,sDAAsD;AACtD,MAAM,WAAW,uBAAuB;IACvC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IAC/C,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAC;IACxC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,uBAAuB,CAAC;IAChD,4EAA4E;IAC5E,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACjD,4EAA4E;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACjD,iEAAiE;IACjE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC7B;AAmPD;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,EAAE,aAAa,CAAC,MAAM,CAIrD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,6BAA6B,GACzC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,OAAO,MAAM,KACX,IAQF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GACnC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,EACvC,OAAO,MAAM,KACX,IAYF,CAAC;AAwKF;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAAI,SAAS,uBAAuB,KAAG,IAkEnF,CAAC"}
+{"version":3,"file":"conformance_table.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/conformance_table.ts"],"names":[],"mappings":"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"}