http/route_error_check.ts

Whether an error response is one its route declares — the one rule the DEV error check (http/dev_route_error_check.ts) and the test helpers (assert_response_matches_spec) share.

A JSON body at an error status (400 and up) is declared when the route's error map (resolve_route_error_map) has that status and the body parses against it. Three exemptions: a 500 internal_error and a 503 service_unavailable (ALWAYS_ACCEPTED_ERRORS), which the catch layers answer on any route and no route declares, and, on a jsonrpc route, a JSON-RPC error envelope, which no REST error definition describes. A non-JSON response, by is_json_response, is not checked at all.

Also the hono-free route lookup the test helpers run (find_route_spec): a route's Hono path template read segment by segment (split_route_template, parse_route_param) and compiled to a RegExp (compile_route_path), and the first route in mount order matching a request, HEAD read as GET (find_mounted_route). The DEV check, on the Hono side, looks routes up with Hono's own router (create_route_lookup); the two are pinned against Hono and each other by the route-lookup tests.

Hono-free and esm-env-free.

view source

Declarations
#

14 declarations

ALWAYS_ACCEPTED_ERRORS
#

http/route_error_check.ts view source

readonly RestErrorDef<number, string, SchemaEntries>[]

type readonly RestErrorDef<number, string, SchemaEntries>[]

import {ALWAYS_ACCEPTED_ERRORS} from '@fuzdev/fuz_app/http/route_error_check.js';

The errors any route can answer with and none declares: the catch layer's 500 internal_error for a generic throw, and a failed pool checkout's 503 service_unavailable. Always accepted by check_route_error.

check_route_error
#

http/route_error_check.ts view source

(errors: RouteErrorMap, status: number, body: unknown, jsonrpc: boolean): RouteErrorCheck import {check_route_error} from '@fuzdev/fuz_app/http/route_error_check.js';

Check a JSON error body against its route's error map.

errors

the route's error map

status

the response status, an error status (is_error_status)

type number

body

the parsed JSON body

type unknown

jsonrpc

whether the route answers JSON-RPC envelopes (RouteSpec.jsonrpc)

type boolean

returns

RouteErrorCheck

ok, or why not: no definition at the status, or a body off the status's schema

compile_route_param_pattern
#

http/route_error_check.ts view source

(pattern: string): RegExp import {compile_route_param_pattern} from '@fuzdev/fuz_app/http/route_error_check.js';

Compile the re of a :name{re} param to the RegExp a value of the param must match, grouped and anchored at both ends, ^(?:re)$, as compile_route_path reads it inside a template. That is Hono's RegExpRouter reading; its TrieRouter, which SmartRouter falls back to for some route sets, anchors ^re$ and leaves a top-level alternation ungrouped, so ^a|b$ takes ab where the grouped form refuses it. The grouped form is the stricter of the two: a value it accepts both routers accept. Test it against the value as the assembled server's router reads it: the raw, percent-encoded segment (get_request_path).

pattern

the param's re (RouteParam.pattern)

type string

returns

RegExp

compile_route_path
#

http/route_error_check.ts view source

(template: string): RegExp import {compile_route_path} from '@fuzdev/fuz_app/http/route_error_check.js';

Compile a Hono path template to a RegExp over request paths, reading it as Hono 4's routers do: the template is split on / with each {…} group kept whole, and each segment is a *, a param — a whole segment :name (one non-empty segment) or :name{re} (the pattern re, which may span segments) — or literal text, so a : inside a segment (files:upload, :x-:y's second) is no param of its own; a literal segment holding a * (/a*), a wildcard in Hono, throws rather than be guessed at. A template ending in ? expands its optional params as Hono's checkOptionalParameter does. A trailing /* matches the prefix with anything after it or nothing (so /api/* matches /api), a * elsewhere one non-empty segment, and * alone every path. Trailing slashes are strict, as Hono's are by default. Pinned against Hono itself by the route-lookup tests.

template

the route's path template (RouteSpec.path)

type string

returns

RegExp

an anchored RegExp over a request path

throws

  • Error - on a segment holding a `*` that is not the whole segment (`/a*`), a wildcard in Hono this lookup refuses to guess at

find_mounted_route
#

http/route_error_check.ts view source

<T>(routes: readonly MountedRoute<T>[], method: string, path: string): T | undefined import {find_mounted_route} from '@fuzdev/fuz_app/http/route_error_check.js';

The first route in mount order that a request matches, as Hono picks the handler — a HEAD read as a GET, which Hono answers it with.

routes

the routes, compiled by to_mounted_routes

type readonly MountedRoute<T>[]

method

the request method

type string

path

the request path

type string

returns

T | undefined

the matched route's value, or undefined when no route matches

generics

find_mounted_route<T>
T

format_route_error_check
#

http/route_error_check.ts view source

(check: { ok: false; kind: "undeclared_status"; } | { ok: false; kind: "schema_mismatch"; issues: SchemaIssue[]; }, status: number, route: string): string import {format_route_error_check} from '@fuzdev/fuz_app/http/route_error_check.js';

Format a failed check_route_error as one line: `Undeclared error status (S): METHOD path or Error schema mismatch (S): METHOD path`. The DEV check logs it, with the issues or the body as a second argument; the test helpers (assert_response_matches_spec, assert_error_response_declared) throw it with the issues or the body as JSON after a : .

check

the failed check

type { ok: false; kind: "undeclared_status"; } | { ok: false; kind: "schema_mismatch"; issues: SchemaIssue[]; }

status

the response status

type number

route

what names the request, METHOD path

type string

returns

string

is_error_status
#

http/route_error_check.ts view source

(status: number): boolean import {is_error_status} from '@fuzdev/fuz_app/http/route_error_check.js';

Whether a status is an error status, the ones check_route_error reads: 400 and up.

status

the HTTP status

type number

returns

boolean

is_json_response
#

http/route_error_check.ts view source

(response: Response): boolean import {is_json_response} from '@fuzdev/fuz_app/http/route_error_check.js';

Whether a response is JSON by its Content-Type, the gate before any error check: a non-JSON response (SSE, bytes, the plain-text unrouted 404) is no error body to check, whatever its text looks like.

response

the response

type Response

returns

boolean

MountedRoute
#

http/route_error_check.ts view source

MountedRoute<T> import type {MountedRoute} from '@fuzdev/fuz_app/http/route_error_check.js';

A route a request can be matched to: its method, its compiled path, and what the caller keeps beside it.

generics

MountedRoute<T>
T

method

type string

readonly

pattern

type RegExp

readonly

value

type T

readonly

parse_route_param
#

http/route_error_check.ts view source

(segment: string): RouteParam | null import {parse_route_param} from '@fuzdev/fuz_app/http/route_error_check.js';

Read a template segment as Hono reads a param: a whole segment :name or :name{re}, either with a trailing ?. A segment that doesn't start with : is literal text, a : inside it (files:upload) included.

segment

one segment of a template split by split_route_template

type string

returns

RouteParam | null

the param, or null for a segment that is not one

RouteErrorCheck
#

http/route_error_check.ts view source

RouteErrorCheck

type { ok: true; } | { ok: false; kind: "undeclared_status"; } | { ok: false; kind: "schema_mismatch"; issues: SchemaIssue[]; }

import type {RouteErrorCheck} from '@fuzdev/fuz_app/http/route_error_check.js';

What check_route_error found of an error response.

RouteParam
#

http/route_error_check.ts view source

RouteParam import type {RouteParam} from '@fuzdev/fuz_app/http/route_error_check.js';

A param segment of a route template, as parse_route_param reads it.

name

The param's name, the key of its value in the route's params.

type string

readonly

pattern

The re of :name{re}, or null for a bare :name.

type string | null

readonly

optional

Whether the segment ends in ?, an optional param.

type boolean

readonly

split_route_template
#

http/route_error_check.ts view source

(template: string): string[] import {split_route_template} from '@fuzdev/fuz_app/http/route_error_check.js';

A template's segments, split on / with each {…} group kept whole, as Hono's splitRoutingPath splits them; a leading / gives no empty first segment.

template

a route's path template

type string

returns

string[]

to_mounted_routes
#

http/route_error_check.ts view source

<TRoute extends { readonly method: string; readonly path: string; }, T>(routes: readonly TRoute[], to_value: (route: TRoute) => T): MountedRoute<T>[] import {to_mounted_routes} from '@fuzdev/fuz_app/http/route_error_check.js';

Compile routes for find_mounted_route, in mount order.

routes

the routes, in the order they were mounted

type readonly TRoute[]

to_value

what to keep beside each route

type (route: TRoute) => T

returns

MountedRoute<T>[]

generics

to_mounted_routes<TRoute extends { readonly method: string; readonly path: string }, T>
TRoute
constraint { readonly method: string; readonly path: string }
T

Depends on
#

Imported by
#