testing/cross_backend/request_target_conformance.ts

The request target conformance table: how both spines decode what a matched route reads of the request target — the query string and the path params — and what a request carrying a given target observably answers, the routing of its method and path included.

request_target_conformance.json (beside this module) has three sections:

  • query — {name, query, read}: the raw query string (the text after ?, or null for a target with none) and what the strict query reader (http/request_target.ts, the Rust fuz_http::request_target) reads of it — {"pairs": [[name, value], …]}, every pair in order, or {"refused": reason} (PercentDecodeError).
  • param — {name, segment, read}: one raw path segment and what the strict segment reader reads of it — {"value": text} or {"refused": reason}.
  • wire — `{name, method, target, as, origin?, host?, headers?, upgrade?, requires?, expect, expect_where_dot_segments_resolved?, note?}`: a request sent over a raw socket with its method and target written as is, by the principal as names ("keeper_session", "none", or "invalid_session" — the session cookie's name with a value that doesn't verify), with origin as its one Origin line, host as its Host in place of the backend's, and each of headers as a line of its own, as a WebSocket upgrade when upgrade is set, and only to a backend declaring every capability requires names. expect pins the answer's status, the REST error code, and on a JSON-RPC answer the envelope's id — which pins the decoding of an echoed value — with its error code and data.reason; and where the row routes, the Allow methods as a set ([] for none), a plain-text body byte for byte (text), the Content-Type's kind of a bodiless HEAD answer (media), and whether the session cookie is cleared (clears_session). Never a whole JSON body, and never the DEV-only issues. A dot-segment row's expect is the answer where the router reads the raw path, and expect_where_dot_segments_resolved the answer where the runtime resolves dot segments first (BackendCapabilities.runtime_resolves_dot_segments).

Wire targets name the backend's paths with {placeholders} (REQUEST_TARGET_CONFORMANCE_PLACEHOLDERS), filled per backend.

The legs: the TS unit test over the readers (src/test/http/), the Rust unit test beside fuz_http::request_target over a byte-identical copy of the file, and request_target_conformance_wire.ts, sending each wire row to a live backend. Edited by hand, never generated.

view source

Declarations
#

15 declarations

fill_request_target_conformance_placeholders
#

testing/cross_backend/request_target_conformance.ts view source

(target: string, placeholders: Readonly<Record<"rpc_path" | "ws_path" | "account_status_path" | "account_login_path" | "sse_path" | "health_path", string>>): string import {fill_request_target_conformance_placeholders} from '@fuzdev/fuz_app/testing/cross_backend/request_target_conformance.js';

Fill a wire target's {placeholders}.

target

type string

placeholders

type Readonly<Record<"rpc_path" | "ws_path" | "account_status_path" | "account_login_path" | "sse_path" | "health_path", string>>

returns

string

throws

  • Error - on a placeholder this backend has no value for

load_request_target_conformance
#

testing/cross_backend/request_target_conformance.ts view source

(): { query: { name: string; query: string | null; read: { refused: "malformed_escape" | "invalid_utf8"; } | { pairs: string[][]; }; }[]; param: { name: string; segment: string; read: { refused: "malformed_escape" | "invalid_utf8"; } | { ...; }; }[]; wire: { ...; }[]; } import {load_request_target_conformance} from '@fuzdev/fuz_app/testing/cross_backend/request_target_conformance.js';

Read and parse the committed table, and check every row name is unique within its section.

returns

RequestTargetConformance

throws

  • Error - when the file is off the schema, or a section repeats a name

REQUEST_TARGET_CONFORMANCE_MEDIA
#

REQUEST_TARGET_CONFORMANCE_PLACEHOLDERS
#

testing/cross_backend/request_target_conformance.ts view source

readonly ["rpc_path", "ws_path", "account_status_path", "account_login_path", "sse_path", "health_path"] import {REQUEST_TARGET_CONFORMANCE_PLACEHOLDERS} from '@fuzdev/fuz_app/testing/cross_backend/request_target_conformance.js';

The placeholder names a wire target may use, each written {name} in the table.

REQUEST_TARGET_CONFORMANCE_PRINCIPALS
#

testing/cross_backend/request_target_conformance.ts view source

readonly ["keeper_session", "none", "invalid_session"] import {REQUEST_TARGET_CONFORMANCE_PRINCIPALS} from '@fuzdev/fuz_app/testing/cross_backend/request_target_conformance.js';

Who sends a wire row: the keeper's session cookie, no credential, or the session cookie's name with a value that doesn't verify — the cookie the session middleware clears under the auth scope.

REQUEST_TARGET_CONFORMANCE_REQUIREMENTS
#

testing/cross_backend/request_target_conformance.ts view source

readonly ["ws", "sse", "account_status", "fact_serving", "fact_serving_admin_hash", "spine_fallback"] import {REQUEST_TARGET_CONFORMANCE_REQUIREMENTS} from '@fuzdev/fuz_app/testing/cross_backend/request_target_conformance.js';

The backend capabilities a wire row may require.

REQUEST_TARGET_CONFORMANCE_URL
#

RequestTargetConformance
#

testing/cross_backend/request_target_conformance.ts view source

value + type

{ query: { name: string; query: string | null; read: { refused: "malformed_escape" | "invalid_utf8"; } | { pairs: string[][]; }; }[]; param: { name: string; segment: string; read: { refused: "malformed_escape" | "invalid_utf8"; } | { ...; }; }[]; wire: { ...; }[]; } import {RequestTargetConformance} from '@fuzdev/fuz_app/testing/cross_backend/request_target_conformance.js';

The table, a @fuzdev/fuz_schema object.

query

type RequestTargetConformanceQueryRow[]

param

type RequestTargetConformanceParamRow[]

wire

type RequestTargetConformanceWireRow[]

RequestTargetConformanceExpect
#

testing/cross_backend/request_target_conformance.ts view source

value + type

{ status: number; error?: string | undefined; jsonrpc?: { id: string | number | null; code?: number | undefined; reason?: string | undefined; } | undefined; allow?: string[] | undefined; text?: string | undefined; media?: "text" | ... 1 more ... | undefined; clears_session?: boolean | undefined; } import {RequestTargetConformanceExpect} from '@fuzdev/fuz_app/testing/cross_backend/request_target_conformance.js';

What a wire row's answer must carry.

status

type number

error?

The REST error body's error code.

type string

jsonrpc?

The JSON-RPC envelope: its id, and on an error its code and data.reason.

type { id: string | number | null; code?: number | undefined; reason?: string | undefined; }

allow?

The Allow header's methods, compared as a set (a router orders them its own way); [] is an answer with no Allow.

type string[]

text?

The body byte for byte, under a text/plain Content-Type.

type string

media?

The Content-Type's kind, for an answer with no body to read — a HEAD's.

type "text" | "json"

clears_session?

Whether the answer clears the session cookie (true) or leaves it alone (false).

type boolean

RequestTargetConformanceParamRow
#

RequestTargetConformancePlaceholder
#

RequestTargetConformancePlaceholders
#

testing/cross_backend/request_target_conformance.ts view source

Readonly<Record<"rpc_path" | "ws_path" | "account_status_path" | "account_login_path" | "sse_path" | "health_path", string>>

type Readonly<Record<RequestTargetConformancePlaceholder, string>>

import type {RequestTargetConformancePlaceholders} from '@fuzdev/fuz_app/testing/cross_backend/request_target_conformance.js';

The value each placeholder takes on one backend.

rpc_path

type string

readonly

ws_path

type string

readonly

account_status_path

type string

readonly

account_login_path

type string

readonly

sse_path

type string

readonly

health_path

type string

readonly

RequestTargetConformanceQueryRow
#

RequestTargetConformanceRefused
#

RequestTargetConformanceWireRow
#

testing/cross_backend/request_target_conformance.ts view source

value + type

{ name: string; method: string; target: string; as: "none" | "keeper_session" | "invalid_session"; expect: { status: number; error?: string | undefined; jsonrpc?: { id: string | number | null; code?: number | undefined; reason?: string | undefined; } | undefined; allow?: string[] | undefined; text?: string | undefin... import {RequestTargetConformanceWireRow} from '@fuzdev/fuz_app/testing/cross_backend/request_target_conformance.js';

One row of the wire section.

name

type string

method

type string

target

type string

as

type "none" | "keeper_session" | "invalid_session"

expect

type RequestTargetConformanceExpect

origin?

An Origin line to send; none when absent.

type string

host?

The Host to send in place of the backend's own.

type string

headers?

Header lines to send as written (name: value) — a POST's Content-Type, so a row reaches the router and not a content-type gate.

type string[]

upgrade?

type boolean

requires?

The capabilities a backend must declare, every one, to be sent the row.

type ("ws" | "sse" | "fact_serving" | "fact_serving_admin_hash" | "account_status" | "spine_fallback")[]

expect_where_dot_segments_resolved?

The answer on a backend whose runtime resolves dot segments before the app sees the request (BackendCapabilities.runtime_resolves_dot_segments); expect is then the answer where the path reaches the router raw.

type RequestTargetConformanceExpect

note?

type string

Depends on
#

Imported by
#