testing/cross_backend/request_header_conformance.ts

The request header conformance table: how both spines read Origin, Referer, Host and Content-Type — the gates' inputs — and what a request carrying given lines of them observably does.

request_header_conformance.json (beside this module) holds one row per case, `{name, lines, read, post?, upgrade?, upgrade_runtime_refusal?, wire_reason?, note?}`:

  • lines — header lines, each Name: value, one byte per character (a character U+0080–U+00FF is that byte on the wire). A name may repeat.
  • read — each reader's reading of exactly those lines (http/request_headers.ts, the Rust fuz_http::request_headers): origin, host and content_type are "absent", "refused", or {"one": value} (HeaderRead; a content type's value is its lowercased essence), and browser_context whether an Origin or Referer line is there at all.
  • post and upgrade — what the request does on the wire, sent as an RPC POST and as a WebSocket upgrade: {"refused": code}, or {"authenticates": credential} (null for none). The wire leg adds a Host naming the server when the row has no Host line, and Content-Type: application/json on the POST when it has no Content-Type line, so a row says only what it is about. Where one request trips several gates the row pins which answers: the host gate, then the origin check, then the content type, then the credential legs.
  • upgrade_runtime_refusal — a runtime trait the row's upgrade meets before the app runs on a backend declaring it (BackendCapabilities.ws_upgrade_runtime_refusals).
  • wire_reason — present instead of post and upgrade on a row the wire leg can't send as the row means it; the unit legs still read it.

The legs: the TS unit test over the readers (src/test/http/), the Rust unit test beside fuz_http::request_headers over a byte-identical copy of the file, and request_header_conformance_wire.ts, sending each row to a live backend. Both unit legs also hold every row join-invariant: the reading of its lines equals the reading of the same lines folded to one line per name (fold_header_lines) — the view Bun and an in-process app.request give the spine — which is what lets one expected column hold on every runtime.

Live values are per leg, so lines name them with {placeholders} (REQUEST_HEADER_CONFORMANCE_PLACEHOLDERS); the unit legs fill them from the table's own unit_placeholders. Edited by hand, never generated.

view source

Declarations
#

16 declarations

fill_request_header_conformance_placeholders
#

testing/cross_backend/request_header_conformance.ts view source

(text: string, placeholders: Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "origin" | "host" | "foreign_host" | "foreign_origin", string>>): string import {fill_request_header_conformance_placeholders} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

Fill a row's {placeholders}.

text

type string

placeholders

type Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "origin" | "host" | "foreign_host" | "foreign_origin", string>>

returns

string

throws

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

fill_request_header_conformance_read
#

testing/cross_backend/request_header_conformance.ts view source

(read: "absent" | "refused" | { one: string; }, placeholders: Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "origin" | "host" | "foreign_host" | "foreign_origin", string>>): "absent" | ... 1 more ... | { ...; } import {fill_request_header_conformance_read} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

A reading in the table's spelling, its one value filled.

read

placeholders

type Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "origin" | "host" | "foreign_host" | "foreign_origin", string>>

returns

RequestHeaderConformanceRead

fold_header_lines
#

testing/cross_backend/request_header_conformance.ts view source

(lines: readonly string[]): string[] import {fold_header_lines} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

Fold lines to one line per name, in the order each name first appears — the view a runtime without a per-line view gives: the Fetch Headers value, its lines joined with , (; for Cookie), then stripped of SP and HTAB at both ends as get_header_lines strips every line.

lines

Name: value lines

type readonly string[]

returns

string[]

one Name: value line per name

load_request_header_conformance
#

testing/cross_backend/request_header_conformance.ts view source

(): { unit_placeholders: { cookie_name: string; session_cookie: string; api_token: string; daemon_token: string; host: string; foreign_host: string; origin: string; foreign_origin: string; }; rows: { ...; }[]; } import {load_request_header_conformance} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

Read and parse the committed table, and check each row is either a wire row (post and upgrade) or names why it isn't (wire_reason).

returns

RequestHeaderConformance

throws

  • Error - when the file is off the schema, or a row is neither

parse_request_header_line
#

testing/cross_backend/request_header_conformance.ts view source

(line: string): ParsedHeaderLine import {parse_request_header_line} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

Split a Name: value line.

line

type string

returns

ParsedHeaderLine

throws

  • Error - on a line with no `:` — the table holds none

ParsedHeaderLine
#

testing/cross_backend/request_header_conformance.ts view source

ParsedHeaderLine import type {ParsedHeaderLine} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

One header line, split at its first : and its value stripped of SP and HTAB, as a request-head parser reads it.

name

The name as written.

type string

readonly

value

The value, outer SP and HTAB stripped.

type string

readonly

REQUEST_HEADER_CONFORMANCE_PLACEHOLDERS
#

testing/cross_backend/request_header_conformance.ts view source

readonly ["cookie_name", "session_cookie", "api_token", "daemon_token", "host", "foreign_host", "origin", "foreign_origin"] import {REQUEST_HEADER_CONFORMANCE_PLACEHOLDERS} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

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

REQUEST_HEADER_CONFORMANCE_URL
#

request_header_values
#

testing/cross_backend/request_header_conformance.ts view source

(lines: readonly string[], name: string): string[] import {request_header_values} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

The values of one header among lines, in order — what get_header_lines answers on a runtime with a per-line view.

lines

Name: value lines

type readonly string[]

name

the header name, in any case

type string

returns

string[]

RequestHeaderConformance
#

testing/cross_backend/request_header_conformance.ts view source

value + type

{ unit_placeholders: { cookie_name: string; session_cookie: string; api_token: string; daemon_token: string; host: string; foreign_host: string; origin: string; foreign_origin: string; }; rows: { ...; }[]; } import {RequestHeaderConformance} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

The table, a @fuzdev/fuz_schema object.

unit_placeholders

type { cookie_name: string; session_cookie: string; api_token: string; daemon_token: string; host: string; foreign_host: string; origin: string; foreign_origin: string; }

rows

type RequestHeaderConformanceRow[]

RequestHeaderConformanceOutcome
#

testing/cross_backend/request_header_conformance.ts view source

value + type

{ refused: "forbidden_host" | "forbidden_origin" | "unsupported_content_type"; } | { authenticates: "session" | "api_token" | "daemon_token" | null; }

type { refused: "forbidden_host" | "forbidden_origin" | "unsupported_content_type"; } | { authenticates: "session" | "api_token" | "daemon_token" | null; }

import {RequestHeaderConformanceOutcome} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

What a request observably does — refused with a code, or authenticated as a credential.

RequestHeaderConformancePlaceholder
#

testing/cross_backend/request_header_conformance.ts view source

"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "origin" | "host" | "foreign_host" | "foreign_origin"

type "api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "origin" | "host" | "foreign_host" | "foreign_origin"

import type {RequestHeaderConformancePlaceholder} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

A placeholder name — see REQUEST_HEADER_CONFORMANCE_PLACEHOLDERS.

RequestHeaderConformancePlaceholders
#

testing/cross_backend/request_header_conformance.ts view source

Readonly<Record<"api_token" | "daemon_token" | "session_cookie" | "cookie_name" | "origin" | "host" | "foreign_host" | "foreign_origin", string>>

type Readonly<Record<RequestHeaderConformancePlaceholder, string>>

import type {RequestHeaderConformancePlaceholders} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

The value each placeholder takes on one leg.

api_token

type string

readonly

daemon_token

type string

readonly

session_cookie

type string

readonly

cookie_name

type string

readonly

origin

type string

readonly

host

type string

readonly

foreign_host

type string

readonly

foreign_origin

type string

readonly

RequestHeaderConformanceRead
#

testing/cross_backend/request_header_conformance.ts view source

value + type

"absent" | "refused" | { one: string; }

type "absent" | "refused" | { one: string; }

import {RequestHeaderConformanceRead} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

One reader's reading in the table: "absent", "refused", or {"one": value}.

RequestHeaderConformanceRow
#

testing/cross_backend/request_header_conformance.ts view source

value + type

{ name: string; lines: string[]; read: { origin: "absent" | "refused" | { one: string; }; browser_context: boolean; host: "absent" | "refused" | { one: string; }; content_type: "absent" | "refused" | { ...; }; }; ... 4 more ...; note?: string | undefined; } import {RequestHeaderConformanceRow} from '@fuzdev/fuz_app/testing/cross_backend/request_header_conformance.js';

One row of the table.

name

type string

lines

type string[]

read

type { origin: "absent" | "refused" | { one: string; }; browser_context: boolean; host: "absent" | "refused" | { one: string; }; content_type: "absent" | "refused" | { one: string; }; }

post?

type RequestHeaderConformanceOutcome

upgrade?

type RequestHeaderConformanceOutcome

upgrade_runtime_refusal?

type "empty_host"

wire_reason?

type string

note?

type string

to_request_header_conformance_read
#

Depends on
#

Imported by
#