http/request_target.ts

The strict readers of the request target: the query string to its pairs, and one path segment to its text — each percent-decoded, or refused.

An escape that doesn't decode is refused, never left literal and never replaced with U+FFFD: a % not followed by two hex digits is a malformed_escape, and decoded bytes that are not UTF-8 are invalid_utf8. A literal spelling would make %FF and %25FF one value, and a lossy one would make every invalid sequence the same U+FFFD — either way a handler reads a value the client never sent. The Rust spine's fuz_http::request_target reads by the same rule, and the shared table testing/cross_backend/request_target_conformance.json holds both to the same rows.

The pure readers take text and are Hono-free. read_request_query_pairs and read_request_route_params apply them to a request (a type-only import of the Hono context): every read of the query or the path params in the spine goes through one of the two.

view source

Declarations
#

13 declarations

get_request_path
#

http/request_target.ts view source

(request: Request): string import {get_request_path} from '@fuzdev/fuz_app/http/request_target.js';

A request's path as sent — nothing percent-decoded — which the assembled server routes on (new Hono({getPath})), as the Rust spine's router matches the raw Uri::path. So /%61pi/x is its own path, not /api/x, on both spines, and every path-keyed layer (the auth and origin scopes, the origin carve-outs, the session-cookie clear, the unmatched-route handler) reads the spelling the router matched. Dot segments are the runtime's: Node and Bun resolve them while building the request's URL, before this runs.

request

the request, its url as the runtime serialized it

type Request

returns

string

PathSegmentRead
#

http/request_target.ts view source

PathSegmentRead

type ({ ok: true; } & { readonly value: string; }) | ({ ok: false; } & { readonly error: "malformed_escape" | "invalid_utf8"; })

import type {PathSegmentRead} from '@fuzdev/fuz_app/http/request_target.js';

A decoded path segment, or why it doesn't decode.

PERCENT_DECODE_ERRORS
#

http/request_target.ts view source

readonly ["malformed_escape", "invalid_utf8"] import {PERCENT_DECODE_ERRORS} from '@fuzdev/fuz_app/http/request_target.js';

Why a query string or a path segment doesn't decode.

PercentDecodeError
#

http/request_target.ts view source

"malformed_escape" | "invalid_utf8"

type "malformed_escape" | "invalid_utf8"

import type {PercentDecodeError} from '@fuzdev/fuz_app/http/request_target.js';

Why a query string or a path segment doesn't decode: a % not followed by two hex digits, or decoded bytes that are not UTF-8. Twin of the Rust fuz_http::PercentDecodeError.

query_first
#

http/request_target.ts view source

(pairs: readonly QueryPair[], key: string): string | undefined import {query_first} from '@fuzdev/fuz_app/http/request_target.js';

The first value of key among pairs — a repeated key's later values are ignored. Twin of the Rust fuz_http::query_first.

pairs

type readonly QueryPair[]

key

type string

returns

string | undefined

the value, '' for a key with no value, undefined when absent

QueryPair
#

http/request_target.ts view source

QueryPair

type readonly [name: string, value: string]

import type {QueryPair} from '@fuzdev/fuz_app/http/request_target.js';

One query pair, decoded: its name and its value.

QueryPairsRead
#

http/request_target.ts view source

QueryPairsRead

type ({ ok: true; } & { readonly value: readonly QueryPair[]; }) | ({ ok: false; } & { readonly error: "malformed_escape" | "invalid_utf8"; })

import type {QueryPairsRead} from '@fuzdev/fuz_app/http/request_target.js';

A decoded query string, or why it doesn't decode.

read_path_segment
#

http/request_target.ts view source

(segment: string): PathSegmentRead import {read_path_segment} from '@fuzdev/fuz_app/http/request_target.js';

Read one raw path segment to its text: percent-decoded strictly, + left a plus (a path is no form encoding).

segment

a segment of the raw request path, between two /

type string

returns

PathSegmentRead

read_query_pairs
#

http/request_target.ts view source

(query: string | null): QueryPairsRead import {read_query_pairs} from '@fuzdev/fuz_app/http/request_target.js';

Read a raw query string to its pairs, in order: split on & (an empty piece is no pair), each piece split at its first = (none reads an empty value), + read as a space, then name and value percent-decoded strictly. Every pair is read, a repeated key's and a nameless one's included, and the first component that doesn't decode refuses the whole string — a key no handler reads included, so no reader of one key sees a query another reader would refuse.

What a pair means is the caller's: query_first takes a key's first occurrence, and to_query_record builds the record a route's query schema parses.

query

the text after ?, or null for a target with none

type string | null

returns

QueryPairsRead

read_request_query_pairs
#

http/request_target.ts view source

(c: Context<any, any, {}>): QueryPairsRead import {read_request_query_pairs} from '@fuzdev/fuz_app/http/request_target.js';

Read a request's query string strictly (read_query_pairs) — the one read of the query in the spine: the route context's query_pairs, a route's query schema, and the WebSocket upgrade's acting.

c

the Hono context

type Context<any, any, {}>

returns

QueryPairsRead

read_request_route_params
#

http/request_target.ts view source

(c: Context<any, any, {}>): Result<{ readonly value: Record<string, string>; }, { readonly error: "malformed_escape" | "invalid_utf8"; }> import {read_request_route_params} from '@fuzdev/fuz_app/http/request_target.js';

Read the matched route's path params, every escape in the request path decoded strictly first — the one read of the path params in the spine.

The whole path is read rather than each param's own segments: the router matches the raw path (get_request_path), so a literal segment matches only as the template spells it — no escape at all — and on a matched route every escape is inside a param. Once every segment decodes, Hono's own reading of each param — the raw matched text by decodeURIComponent — is exactly its strict decoding, so the values are taken from Hono's match, which knows which segments each param spans.

c

the Hono context

type Context<any, any, {}>

returns

Result

the params by name, or why the path doesn't decode

split_request_url
#

http/request_target.ts view source

(url: string): { path: string; query: string | null; } import {split_request_url} from '@fuzdev/fuz_app/http/request_target.js';

The path and the query of an absolute request URL, both as sent: the path from the first / after the authority, the query the text after the first ? (null without one), a fragment dropped.

url

the request URL, as the runtime serialized it

type string

returns

{ path: string; query: string | null; }

to_query_record
#

http/request_target.ts view source

(pairs: readonly QueryPair[]): Record<string, string> import {to_query_record} from '@fuzdev/fuz_app/http/request_target.js';

The record a route's query schema parses: each name's first value, a nameless pair skipped — what Hono's c.req.query() builds, on a null-prototype object.

pairs

type readonly QueryPair[]

returns

Record<string, string>

Imported by
#