@orkestrel/scaffold 0.0.138 → 0.0.139
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agents/skills/orkestrel-parallel/scripts/lane.js +489 -23
- package/dist/bin/main.js +5 -5
- package/dist/host/agents/skills/orkestrel-parallel/SKILL.md +1 -1
- package/dist/host/agents/skills/orkestrel-parallel/scripts/lane.ts +628 -41
- package/dist/host/claude/agents/orkestrel.md +6 -6
- package/dist/host/guides/contract.md +314 -210
- package/dist/host/guides/middleware.md +489 -259
- package/dist/host/guides/router.md +282 -165
- package/dist/host/guides/scaffold.md +2 -2
- package/dist/host/guides/server.md +417 -181
- package/dist/host/manifest.json +9 -9
- package/dist/src/core/index.cjs +5 -5
- package/dist/src/core/index.js +5 -5
- package/package.json +5 -5
|
@@ -42,7 +42,7 @@ const response = await dispatcher.handle(new Request('http://x/users/7'), { user
|
|
|
42
42
|
|
|
43
43
|
Path patterns are `/`-prefixed: a literal segment (`/users`), a `:name` param
|
|
44
44
|
(one segment), or a final `*name` wildcard (captures the rest of the path).
|
|
45
|
-
Matching is case-sensitive by default (`sensitive: false`
|
|
45
|
+
Matching is case-sensitive by default (`sensitive: false` folds ASCII letters); a single
|
|
46
46
|
trailing slash is always optional except on the root `/` and the empty
|
|
47
47
|
pattern.
|
|
48
48
|
|
|
@@ -58,34 +58,46 @@ Browser and server usage appear under [Patterns](#patterns).
|
|
|
58
58
|
|
|
59
59
|
### Constants
|
|
60
60
|
|
|
61
|
-
| Name
|
|
62
|
-
|
|
|
63
|
-
| `METHOD_LIST`
|
|
64
|
-
| `HTTP_METHODS`
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
61
|
+
| Name | Kind | Signature | Summary |
|
|
62
|
+
| --------------------- | ----- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
63
|
+
| `METHOD_LIST` | const | `readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]` | Lists the HTTP methods a `DispatcherInterface` registers routes under, in canonical order — a frozen literal tuple, and the single source the `Method` type, `HTTP_METHODS`, and `parseMethod` are all derived from. |
|
|
64
|
+
| `HTTP_METHODS` | const | `ReadonlySet<string>` | Holds every HTTP method a `DispatcherInterface` registers routes under as a `ReadonlySet` — backs the registration guard (`add` rejects any `method` outside this set). |
|
|
65
|
+
| `PATH_ENCODE_SET` | const | `ReadonlySet<string>` | Holds the printable ASCII members of the path encode set `encodePath` reads: the URL Standard's path percent-encode set plus `\|`, beside every C0 control, U+007F, and greater code point. |
|
|
66
|
+
| `PATH_ESCAPE_PATTERN` | const | `RegExp` | Matches each ASCII code point `encodePath` writes as one escape — a C0 control, a member of `PATH_ENCODE_SET`, or U+007F — in one global `replace` pass. |
|
|
67
|
+
| `PATH_WIDE_PATTERN` | const | `RegExp` | Matches each run of non-ASCII code points `encodePath` hands to one `encodeURIComponent` call, in one global `replace` pass. |
|
|
68
|
+
| `PERCENT_ESCAPES` | const | `readonly string[]` | Lists the uppercase percent-escape of every byte value, indexed by the byte, so `encodePath` writes each escape with one lookup. |
|
|
69
|
+
| `PATH_ENCODE_PATTERN` | const | `RegExp` | Matches one code point `encodePath` writes as escapes: a C0 control, a member of `PATH_ENCODE_SET`, U+007F, or any greater code point. |
|
|
70
|
+
| `PATH_REFUSED_SET` | const | `ReadonlySet<string>` | Holds the code points a route pattern must not hold: `\`, tab, line feed, and carriage return, which a URL parser reads as a separator or deletes, so the pattern would name a path other than its text. |
|
|
71
|
+
| `PROTOTYPE_KEYS` | const | `ReadonlySet<string>` | Holds the own property names of `Object.prototype` — the names `compilePath` refuses as a param name, so a params record never shadows or drops an inherited key. |
|
|
72
|
+
| `TIER_LITERAL` | const | `2` | Names the specificity tier for a \*\*literal\*\* path segment (`/users`) — the highest tier, always outranking a param or wildcard segment at the same position. |
|
|
73
|
+
| `TIER_PARAM` | const | `1` | Names the specificity tier for a \*\*param\*\* path segment (`:name`) — ranks below a literal segment and above a wildcard segment at the same position. |
|
|
74
|
+
| `TIER_WILDCARD` | const | `0` | Names the specificity tier for a \*\*wildcard\*\* path segment (`*name`) — the lowest tier; a wildcard only ever wins against another wildcard shape (an equal-specificity tie resolved by registration order). |
|
|
68
75
|
|
|
69
76
|
### Helpers
|
|
70
77
|
|
|
71
78
|
| Name | Kind | Signature | Summary |
|
|
72
79
|
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
73
|
-
| `canonicalizePath` | function | `(path: string) => string` | Canonicalizes a route path for registry identity — strips a single trailing slash, except the root `/` (and the empty pattern). The trailing-slash fold `compilePath` normalizes a pattern through, so identity agrees with the matcher.
|
|
80
|
+
| `canonicalizePath` | function | `(path: string) => string` | Canonicalizes a route path for registry identity — encodes it with `encodePath` and strips a single trailing slash, except the root `/` (and the empty pattern). The trailing-slash fold `compilePath` normalizes a pattern through, so identity agrees with the matcher. |
|
|
74
81
|
| `computeDispatchKey` | function | `(entry: RouteEntry<{ readonly method: Method; }>) => string` | Computes the canonical `METHOD /path` registry key for a method-dimensioned dispatcher route. |
|
|
75
|
-
| `compilePath` | function | `(path: string, sensitive?: boolean) => CompiledPath` | Compiles a route path pattern into an anchored regex
|
|
82
|
+
| `compilePath` | function | `(path: string, sensitive?: boolean) => CompiledPath` | Compiles a route path pattern into an anchored regex, its ordered param names, and its specificity vector. |
|
|
83
|
+
| `encodePath` | function | `(text: string) => string` | Encodes path text, raw or already encoded, into the canonical form the router compares: each member of its path encode set becomes its UTF-8 percent-escapes. |
|
|
84
|
+
| `collectInputs` | function | `<T>(input: T \| readonly T[]) => readonly T[]` | Returns the input list as it is, or a one-entry list holding a single input — the shape every batch-capable `add` reads. |
|
|
76
85
|
| `decodeParam` | function | `(value: string) => string` | Decodes one captured param value from a URL, tolerating a malformed percent-escape — the decode `matchPath` applies to each captured group. |
|
|
77
86
|
| `matchPath` | function | `(compiled: CompiledPath, pathname: string) => Readonly<Record<string, string>> \| undefined` | Extracts the URL-decoded params a compiled path captures from a concrete pathname, or `undefined` when the pathname does not match. |
|
|
78
87
|
| `classifySegment` | function | `(segment: string, isFinal: boolean) => number` | Classifies one path segment into its specificity tier — the same syntax `compilePath` rewrites: a syntactically valid `:name` head is a param segment, a final `*name` is a wildcard segment, and everything else (including a literal segment that merely contains a `:` mid-string, for example `a:b`) is a literal segment. |
|
|
79
|
-
| `computeSpecificity` | function | `(path: string) => readonly
|
|
80
|
-
| `compareSpecificity` | function | `(a:
|
|
88
|
+
| `computeSpecificity` | function | `(path: string) => readonly SegmentRank[]` | Computes a route path's specificity vector — one `SegmentRank` per segment, the ranking that picks the winner when several registered routes match the same concrete pathname. |
|
|
89
|
+
| `compareSpecificity` | function | `(a: readonly SegmentRank[], b: readonly SegmentRank[]) => number` | Compares two specificity vectors — the comparator that picks the most-specific matching route: tier first, then literal length, segment by segment. |
|
|
81
90
|
| `joinPaths` | function | `(prefix: string, path: string) => string` | Joins a group prefix and a route path into one `/`-prefixed path, normalizing duplicate or missing joining slashes. |
|
|
82
91
|
| `defineRoute` | function | `<const Path extends string, TState = undefined>(input: RouteInput<Path, TState>) => RouteInput<Path, TState>` | Provides an identity pass-through for a `RouteInput` that pins its `Path` generic to the literal registration-site string, so `context.params` types correctly through `PathParams` without an explicit type argument. |
|
|
83
92
|
| `computeNavigationKey` | function | `(entry: RouteEntry<unknown>) => string` | Computes the canonical path key a `Navigator` registers a browser navigation route under. |
|
|
84
93
|
| `extractHashPath` | function | `(hash: string) => string` | Extracts the `/`-prefixed pathname from a `location.hash` value — strips the leading `#` (keeping the route's own leading `/`) and any `?query` suffix. |
|
|
85
|
-
| `resolveLocationPath` | function | `(location: Pick<Location, 'hash' \| 'pathname'>, history: boolean, base?: string) => string`
|
|
94
|
+
| `resolveLocationPath` | function | `(location: Pick<Location, 'hash' \| 'pathname'>, history: boolean, base?: string) => string \| undefined` | Resolves the `/`-prefixed pathname to match for the current location, in either navigation mode — the one seam `extractHashPath` (hash mode) and history-mode base-stripping share. |
|
|
86
95
|
| `findAnchor` | function | `(event: Event) => HTMLAnchorElement \| undefined` | Finds the nearest enclosing `<a>` element a DOM event originated from, by walking its composed path — the pure lookup behind history-mode link interception. |
|
|
87
96
|
| `buildRequest` | function | `(message: IncomingMessage, options?: RequestOptions) => Request` | Builds a fetch-standard `Request` from a `node:http` `IncomingMessage` — the server-adapter half of the fetch/node conversion seam. |
|
|
88
97
|
| `sendResponse` | function | `(response: Response, target: ServerResponse) => Promise<void>` | Writes a fetch-standard `Response` back to a `node:http` `ServerResponse` — the reverse half of the fetch/node conversion seam. |
|
|
98
|
+
| `buildURL` | function | `(message: IncomingMessage, origin?: string) => URL` | Builds the URL of a `node:http` request from its request target, by the target's form. |
|
|
99
|
+
| `readChunk` | function | `(message: IncomingMessage, signal: AbortSignal) => Promise<Uint8Array \| undefined>` | Reads the next chunk of a `node:http` request body, waiting for one to arrive. |
|
|
100
|
+
| `discardBody` | function | `(message: IncomingMessage, discard: AbortController) => void` | Discards the unread rest of a `node:http` request body in place, leaving the connection reusable. |
|
|
89
101
|
|
|
90
102
|
### Parsers
|
|
91
103
|
|
|
@@ -98,19 +110,13 @@ Browser and server usage appear under [Patterns](#patterns).
|
|
|
98
110
|
| Name | Kind | Signature | Summary |
|
|
99
111
|
| ------------------- | -------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
100
112
|
| `isEncryptedSocket` | function | `(socket: unknown) => socket is { readonly encrypted: true; }` | Determines whether a `node:http` connection socket is TLS-encrypted — the total, never-throwing narrow `buildRequest` uses to pick the derived scheme (`https` vs `http`). |
|
|
101
|
-
|
|
102
|
-
### Handlers
|
|
103
|
-
|
|
104
|
-
| Name | Kind | Signature | Summary |
|
|
105
|
-
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
106
|
-
| `handleListenerRequest` | function | `<TState>(dispatcher: DispatcherInterface<TState>, state: StateFunction<TState>, request: IncomingMessage, response: ServerResponse) => Promise<void>` | Handles one `node:http` request through a core dispatcher and writes its fetch-standard response. |
|
|
107
|
-
| `createListener` | function | `<TState>(dispatcher: DispatcherInterface<TState>, state: StateFunction<TState>) => ListenerFunction` | Creates a `node:http` request listener over a core `DispatcherInterface` — the whole server face's entry point: converts the incoming message to a fetch `Request`, hands it to the dispatcher with the consumer's per-request `state`, and writes the resulting `Response` back. |
|
|
113
|
+
| `isAuthority` | function | `(value: unknown) => value is string` | Checks whether a value is an HTTP authority a server accepts: a host with an optional port, and no userinfo. |
|
|
108
114
|
|
|
109
115
|
### Classes
|
|
110
116
|
|
|
111
117
|
| Name | Kind | Signature | Summary |
|
|
112
118
|
| --------------- | ----- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
113
|
-
| `Router` | class | `new <Meta>(options?: RouterOptions<Meta>) => RouterInterface<Meta>` | Represents the path-matching + registry engine — registers `{ path, meta, name? }` entries (compiling each path once) and resolves
|
|
119
|
+
| `Router` | class | `new <Meta>(options?: RouterOptions<Meta>) => RouterInterface<Meta>` | Represents the path-matching + registry engine — registers `{ path, meta, name? }` entries (compiling each path once) and resolves raw or encoded text to the most specific matching entry. The shared machine both the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose. |
|
|
114
120
|
| `Group` | class | `new <Meta>(parent: RouterInterface<Meta>, prefix: string) => GroupInterface<Meta>` | Represents a prefix-scoped registration handle over a `Router` — pure string composition, no independent state or storage. |
|
|
115
121
|
| `Dispatcher` | class | `new <TState = undefined>(options?: DispatcherOptions<TState>) => DispatcherInterface<TState>` | Represents the fetch-standard, method-dimensioned dispatch entity — layers HTTP method dispatch and web-standard `Request`/`Response` handling over one internal `Router<RouteRecord<TState>>`. The core machine the server face and any fetch-native runtime consume directly. |
|
|
116
122
|
| `DispatchGroup` | class | `new <TState>(parent: DispatcherInterface<TState>, prefix: string) => DispatchGroupInterface<TState>` | Represents a prefix-scoped registration handle over a `Dispatcher` — the method-dimensioned counterpart of `Group`. |
|
|
@@ -127,12 +133,13 @@ Browser and server usage appear under [Patterns](#patterns).
|
|
|
127
133
|
| `TakeIdentifierTail` | type | ``S extends `${infer Head}${infer Tail}` ? Head extends IdentifierChar ? TakeIdentifierTail<Tail, `${Acc}${Head}`> : Acc : Acc`` | Consumes the identifier-continuation run at the front of a string literal, char by char, appending each onto the accumulator. |
|
|
128
134
|
| `IdentifierHead` | type | ``S extends `${infer Head}${infer Tail}` ? Head extends IdentifierStartChar ? TakeIdentifierTail<Tail, Head> : '' : ''`` | Captures the identifier at the front of a string literal, or an empty string when the literal does not begin with an identifier-start char. |
|
|
129
135
|
| `SegmentParam` | type | ``Segment extends `:${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : { readonly [K in Name]: string; } : unknown : Segment extends `*${infer Rest}` ? IdentifierHead<Rest> extends infer Name extends string ? Name extends '' ? unknown : { readonly [K in Name]: string; } : unknown : unknown`` | Contributes one path segment's type-level param record — the type-level mirror of the runtime `classifySegment` and `compilePath` segment parser. |
|
|
130
|
-
| `
|
|
136
|
+
| `SegmentRank` | interface | `{ tier, length }` | Represents one segment's place in a route path's specificity vector — its tier, then the length of the literal text it carries. |
|
|
137
|
+
| `CompiledPath` | interface | `{ regex, params, specificity }` | Represents a compiled route path — the anchored regex, its ordered param names, and its specificity vector. |
|
|
131
138
|
| `RouteEntry` | interface | `{ path, meta, name? }` | Represents one registered route in a `RouterInterface` — the `path` pattern plus the opaque `meta` payload to return on a match, with an optional `name`. |
|
|
132
139
|
| `RouterMatch` | interface | `{ path, params, meta, name? }` | Represents one matched route — the winning entry's registered pattern, its decoded params, its `meta` payload, and its optional `name`. |
|
|
133
140
|
| `AnswerHandler` | type | `(meta: Meta) => boolean` | Represents the native-override seam — a predicate deciding whether an entry's `meta` answers a given `match` call, beyond path matching. |
|
|
134
141
|
| `RouterOptions` | interface | `{ entries?, sensitive?, key? }` | Represents the options for `createRouter` — an optional initial entry set, the case-sensitivity toggle, and the dedup identity function. |
|
|
135
|
-
| `RouterInterface` | interface | `{ count, add(), match(), entries(), group(), clear() }` | Represents the path-matching + registry engine contract (the behavioral-interface role for the one-class-per-file `Router`). Registers `{ path, meta, name? }` entries (compiling each path once) and resolves
|
|
142
|
+
| `RouterInterface` | interface | `{ count, add(), match(), entries(), group(), clear() }` | Represents the path-matching + registry engine contract (the behavioral-interface role for the one-class-per-file `Router`). Registers `{ path, meta, name? }` entries (compiling each path once) and resolves path text, raw or encoded, to the most specific matching entry by the per-segment precedence `compareSpecificity` defines, a remaining tie going to the earlier registration. The shared engine both the `Navigator` (browser) and the `Dispatcher` (core, method-dimensioned) compose. |
|
|
136
143
|
| `GroupInterface` | interface | `{ prefix, add(), group() }` | Represents a prefix-scoped registration handle over a `RouterInterface` — pure string composition, no independent state or storage. |
|
|
137
144
|
| `Method` | type | `(typeof METHOD_LIST)[number]` | Names the HTTP methods a `DispatcherInterface` dimensions dispatch over — derived from `METHOD_LIST`, whose membership counterpart is `HTTP_METHODS`. |
|
|
138
145
|
| `RouteContext` | interface | `{ params, pattern, url, state }` | Represents the ambient context a `RouteHandler` receives alongside the raw `Request` — decoded params, the winning pattern, the parsed URL, and the consumer's opaque per-request state. |
|
|
@@ -146,10 +153,8 @@ Browser and server usage appear under [Patterns](#patterns).
|
|
|
146
153
|
| `DispatchGroupInterface` | interface | `{ prefix, add(), group() }` | Represents a prefix-scoped registration handle over a `DispatcherInterface` — the method-dimensioned counterpart of `GroupInterface`. |
|
|
147
154
|
| `NavigatorEventMap` | type | `{ readonly navigate: readonly [match: RouterMatch<Meta>]; }` | Represents the `Navigator`'s event map — the single `navigate` signal a consumer observes. |
|
|
148
155
|
| `NavigatorOptions` | interface | `{ routes, history?, base?, fallback?, guard?, intercept?, sensitive?, on?, error? }` | Represents the options for `createNavigator` — the `routes` to dispatch between, the navigation substrate, the optional guard hook, and the Emitter pattern's wiring. |
|
|
149
|
-
| `NavigatorInterface` | interface | `{ router, emitter, active, start(), stop(), navigate(),
|
|
150
|
-
| `RequestOptions` | interface | `{ origin?, response? }`
|
|
151
|
-
| `ListenerFunction` | type | `(request: IncomingMessage, response: ServerResponse) => void` | Represents a `node:http` request handler — the function `createListener` returns, matching `http.createServer`'s handler signature. |
|
|
152
|
-
| `StateFunction` | type | `(message: IncomingMessage) => TState` | Derives a consumer's opaque per-request `TState` from the raw `IncomingMessage` — the `state` argument `createListener` threads into `dispatcher.handle`. |
|
|
156
|
+
| `NavigatorInterface` | interface | `{ router, emitter, active, start(), stop(), navigate(), destroy() }` | Represents the headless History/hash navigation entity contract (the behavioral-interface role for the one-class-per-file `Navigator`). Composes a core `Router<Meta>`, resolves the current location on `start()` and on every subsequent navigation event, tracks `active`, and emits `navigate` through the `EmitterInterface`. |
|
|
157
|
+
| `RequestOptions` | interface | `{ origin?, response?, signal? }` | Represents the options for `buildRequest` — URL origin, response-side disconnect tracking, and a linked cancellation signal. |
|
|
153
158
|
|
|
154
159
|
The `count` member of `RouterInterface`, the `prefix` member of `GroupInterface` and
|
|
155
160
|
`DispatchGroupInterface`, the `router` and `emitter` members of `DispatcherInterface`, and the
|
|
@@ -197,13 +202,12 @@ declaration it belongs to:
|
|
|
197
202
|
The navigation entity's call-signature members, each documented on the interface
|
|
198
203
|
declaration it belongs to:
|
|
199
204
|
|
|
200
|
-
| Method | Returns
|
|
201
|
-
| ---------- |
|
|
202
|
-
| `start` | `void`
|
|
203
|
-
| `stop` | `void`
|
|
204
|
-
| `navigate` | `void`
|
|
205
|
-
| `
|
|
206
|
-
| `destroy` | `void` | Stops listening and tears down the emitter. |
|
|
205
|
+
| Method | Returns | Summary |
|
|
206
|
+
| ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
207
|
+
| `start` | `void` | Begins listening and resolves the current location — idempotent, so a second call is a no-op. |
|
|
208
|
+
| `stop` | `void` | Stops listening and aborts any pending guard — idempotent. |
|
|
209
|
+
| `navigate` | `void` | Navigates programmatically — runs the guard, then pushes the entry (`#path` in hash mode, the `base`-joined path in history mode) and commits. |
|
|
210
|
+
| `destroy` | `void` | Stops listening, aborts any pending guard, and tears down the emitter. |
|
|
207
211
|
|
|
208
212
|
#### `GroupInterface`
|
|
209
213
|
|
|
@@ -240,41 +244,81 @@ These invariants hold across `src/core` / `src/browser` / `src/server` ↔
|
|
|
240
244
|
exhaustive, both directions — and `Router` / `Group` / `Dispatcher` /
|
|
241
245
|
`DispatchGroup` / `Navigator` expose the same public methods, no more.
|
|
242
246
|
3. **Path grammar.** Segment kinds: literal (`/users`), param
|
|
243
|
-
(`:name`, one segment
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
+
(`:name`, one segment, with optional literal text after the name, as in
|
|
248
|
+
`:name.json`), wildcard (`*name`, final segment only, captures the rest of
|
|
249
|
+
the path including slashes). `compilePath` throws a `ContractError` at
|
|
250
|
+
registration for a wildcard anywhere but the final segment, a final
|
|
251
|
+
`*name` followed by more text (`/files/*rest.json`), a param or wildcard
|
|
252
|
+
named for a `PROTOTYPE_KEYS` member (`:__proto__`, `:constructor`), and a
|
|
253
|
+
name used twice (`/a/:id/b/:id`). It also throws, with code `pattern`, for
|
|
254
|
+
a pattern holding `\`, tab, line feed, or carriage return anywhere, because
|
|
255
|
+
a URL parser reads `\` as a separator and deletes the others; the `limit`
|
|
256
|
+
names each one and its escape (`%5C`, `%09`, `%0A`, `%0D`). 0.0.22 refused
|
|
257
|
+
only the wildcard outside the final segment and registered every other
|
|
258
|
+
pattern this item names. The matcher
|
|
259
|
+
compares one canonical text, which `encodePath` writes from its own table,
|
|
260
|
+
`PATH_ENCODE_SET`, on both sides. The table is the URL Standard's path
|
|
261
|
+
percent-encode set (Last Updated 2026-11-14, snapshot `47721bbd`) plus
|
|
262
|
+
`|`, a declared departure: Chromium encodes `|` in a path as `%7C` and Node
|
|
263
|
+
leaves it raw, so with `|` in the table both compare as `%7C`. The encoder
|
|
264
|
+
runs on the pattern at
|
|
265
|
+
registration, and on the request text inside `router.match`,
|
|
266
|
+
`router.entries`, and `matchPath`. So `/café` matches `/café` and
|
|
267
|
+
`/caf%C3%A9`, `/^w` matches `/^w` and `/%5Ew`, and `router.match` takes path
|
|
268
|
+
text raw or encoded. Nothing is decoded before matching, so `/us%65rs`
|
|
269
|
+
does not match `/users`, and `/100%25` does not match `/100%`. In 0.0.22
|
|
270
|
+
the matcher compared the pattern as written with the text as given, so
|
|
271
|
+
`/café` answered 404 through `Dispatcher.handle`, whose pathname is
|
|
272
|
+
encoded, and `/a|b` missed `/a%7Cb`, the form Chromium writes. Each capture is decoded with
|
|
273
|
+
`decodeParam` and is opaque text the router refuses nothing in:
|
|
274
|
+
`/files/*rest` captures `../../etc/passwd` from
|
|
275
|
+
`/files/..%2F..%2Fetc%2Fpasswd`. A consumer that maps a capture to a file
|
|
276
|
+
path must contain it within its root.
|
|
277
|
+
4. **Precedence.** A literal segment (`TIER_LITERAL`, 2) outranks a
|
|
247
278
|
param (`TIER_PARAM`, 1), which outranks a wildcard (`TIER_WILDCARD`, 0).
|
|
248
|
-
Two matching routes compare left to right,
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
279
|
+
Two matching routes compare left to right, segment by segment: the higher
|
|
280
|
+
tier wins, and within one tier the longer literal text wins, so
|
|
281
|
+
`/files/:name.json` outranks `/files/:name` in either registration order.
|
|
282
|
+
A shorter pattern that is a prefix of a longer one ranks below it. A
|
|
283
|
+
remaining tie, such as `/t/:a.js` against `/t/:b.js`, goes to the earlier
|
|
284
|
+
registration. In 0.0.22 only the tier counted, so the earlier registration
|
|
285
|
+
of `/files/:name` and `/files/:name.json` won.
|
|
253
286
|
5. **Trailing slash is insensitive.** A single trailing slash on the request
|
|
254
287
|
path is always optional, folded both at registration (`canonicalizePath`)
|
|
255
288
|
and at match time — except the root `/` and the empty pattern, which are
|
|
256
289
|
exempt and anchor exactly.
|
|
257
290
|
6. **Case-sensitive by default.** `sensitive: true` (`Router`/`Dispatcher`
|
|
258
|
-
construction) is the default; `sensitive: false` folds
|
|
259
|
-
matching
|
|
291
|
+
construction) is the default; `sensitive: false` folds the ASCII letters
|
|
292
|
+
A to Z with a to z during matching, in literal text and in escape hex,
|
|
293
|
+
without altering the pattern's own stored casing. No other letter folds:
|
|
294
|
+
`/CAFÉ` misses `/café` under either setting, while `/CAFé` and
|
|
295
|
+
`/caf%c3%a9` hit it under `sensitive: false`. In 0.0.22 `sensitive: false`
|
|
296
|
+
folded every letter the regular expression `i` flag folds, so `/CAFÉ` hit
|
|
297
|
+
`/café`.
|
|
260
298
|
7. **Dedup with `key`.** When `RouterOptions.key` is set, an entry whose
|
|
261
299
|
computed key already exists replaces the prior entry in place (last write
|
|
262
300
|
wins, no engine rebuild); `Dispatcher` always constructs its internal
|
|
263
301
|
`Router` with `key: computeDispatchKey`, which pairs the route's method
|
|
264
|
-
with `canonicalizePath(entry.path)`,
|
|
265
|
-
|
|
266
|
-
|
|
302
|
+
with `canonicalizePath(entry.path)`, the encoded pattern with one trailing
|
|
303
|
+
slash removed, so two registrations differing only by a trailing slash or
|
|
304
|
+
by encoding (`/café` and `/caf%C3%A9`) replace each other while different
|
|
305
|
+
methods stay distinct. A batch `add` admits every entry before it registers
|
|
306
|
+
any, so a refused batch registers nothing.
|
|
267
307
|
8. **The `answers` seam.** `RouterInterface.match`'s optional
|
|
268
308
|
`AnswerHandler<Meta>` predicate is the single native-override point both
|
|
269
309
|
faces compose differently: the `Dispatcher` passes a method-check, the
|
|
270
310
|
browser `Navigator` omits it entirely — every path match answers.
|
|
271
311
|
9. **Dispatch semantics.** A `HEAD` request with no explicit `HEAD` route
|
|
272
|
-
runs the matching `GET` handler
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
`
|
|
276
|
-
`
|
|
277
|
-
invokes the `
|
|
312
|
+
runs the matching `GET` handler, cancels the `GET` response body, and
|
|
313
|
+
answers with its status and headers alone. An `OPTIONS` request with no
|
|
314
|
+
explicit `OPTIONS` route answers `204` with a derived `Allow` header: the
|
|
315
|
+
methods of `router.entries(pathname)` in registration order, then `HEAD`
|
|
316
|
+
when `GET` is present, then `OPTIONS`. A path-matches-but-method-doesn't
|
|
317
|
+
dispatch invokes the `unmethoded` responder with the same set (default
|
|
318
|
+
`405` + `Allow`, so `GET` alone reads `GET, HEAD, OPTIONS`); nothing matching
|
|
319
|
+
invokes the `unmatched` responder (default `404`). In 0.0.22 the `405`
|
|
320
|
+
`Allow` header left `OPTIONS` out, so `GET` alone read `GET, HEAD`, and
|
|
321
|
+
auto-`HEAD` dropped the `GET` body without cancelling it. **A handler throw
|
|
278
322
|
propagates uncaught** — the dispatcher never invents an error boundary
|
|
279
323
|
(that is the consuming server's policy).
|
|
280
324
|
10. **Wildcard trailing-slash capture is asymmetric with param folding
|
|
@@ -302,26 +346,53 @@ These invariants hold across `src/core` / `src/browser` / `src/server` ↔
|
|
|
302
346
|
14. **The history toggle.** `history: false` (default) reads/writes
|
|
303
347
|
`location.hash` and binds `hashchange`; `history: true` reads/writes through
|
|
304
348
|
`pushState`/`popstate`, with an optional `base` path prefix stripped
|
|
305
|
-
before matching and prepended when navigating. `
|
|
306
|
-
|
|
349
|
+
before matching and prepended when navigating. `base` is compared in the
|
|
350
|
+
encoded form `location.pathname` carries, so `base: '/café'` strips from
|
|
351
|
+
`/caf%C3%A9/users/7`. `intercept: true` (history mode only) adds
|
|
352
|
+
same-origin `<a>` click interception for a link inside `base` — a plain
|
|
307
353
|
left-click with no modifier keys, no `target`, and no `download`
|
|
308
|
-
attribute.
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
354
|
+
attribute. A link outside `base` navigates natively, where 0.0.22
|
|
355
|
+
intercepted it and pushed it under `base`, so `/other/page` became
|
|
356
|
+
`/app/other/page`. In history mode, `navigate` throws a `ContractError`
|
|
357
|
+
coded `pattern` for a path that resolves on another origin, such as
|
|
358
|
+
`//elsewhere.example/b`, before the guard runs; 0.0.22 handed that path to
|
|
359
|
+
`pushState`, which threw a `DOMException`. `navigate` pushes an
|
|
360
|
+
entry in both modes, `#path` in hash mode, and writes `{ index }` into its
|
|
361
|
+
`history.state`; `start` writes `{ index: 0 }` to an entry that carries no
|
|
362
|
+
index. A hash `navigate` to the hash the location shows keeps its entry.
|
|
363
|
+
15. **Fallback semantics.** A location that matches nothing, or in history
|
|
364
|
+
mode lies outside `base`, resolves the configured `fallback` pattern
|
|
365
|
+
(default: the first route's path) through the same engine. 0.0.22 matched
|
|
366
|
+
a location outside `base` by its whole pathname, so `/other/page` under
|
|
367
|
+
`base: '/app'` resolved the `/other/page` route. A `fallback`
|
|
368
|
+
that itself matches no registered route leaves `active` `undefined` and
|
|
369
|
+
emits nothing — no phantom match is ever fabricated.
|
|
314
370
|
16. **Guard + supersede semantics.** An optional `guard(to, from, signal)` may
|
|
315
|
-
veto (or asynchronously veto) a navigation.
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
371
|
+
veto (or asynchronously veto) a navigation.
|
|
372
|
+
- `navigate` and an intercepted link ask the guard before the URL moves: a
|
|
373
|
+
veto leaves the location, the history length, and `active` unchanged,
|
|
374
|
+
and an allowed navigation pushes its entry, then commits.
|
|
375
|
+
- When the browser moves the URL first (`popstate` or `hashchange`), a veto
|
|
376
|
+
moves it back with `history.go` to the entry `active` describes, by the
|
|
377
|
+
`index` both entries carry. An entry the navigator did not write — a
|
|
378
|
+
native fragment link, an address-bar edit, or an entry from before
|
|
379
|
+
`start` — carries no index: the location stays where the browser put
|
|
380
|
+
it, `active` stays unchanged, and the consumer reconciles them.
|
|
381
|
+
- Each navigation holds an `@orkestrel/abort` handle until its verdict
|
|
382
|
+
arrives. A newer navigation, `stop`, and `destroy` abort every pending
|
|
383
|
+
handle, and a verdict that resolves after its abort (`signal.aborted`)
|
|
384
|
+
is discarded, same as a synchronous `false`/rejected verdict: `active`
|
|
385
|
+
stays unchanged and nothing is emitted. A guard throw routes to the
|
|
386
|
+
`error` handler (not through the emitter's own `emit`) and vetoes.
|
|
387
|
+
- A `navigate` called from a `navigate` listener runs in a microtask after
|
|
388
|
+
the emission ends, unless a later navigation supersedes it first. Every
|
|
389
|
+
listener of one emission reads `active` equal to the match it receives,
|
|
390
|
+
and the second navigation's emission follows.
|
|
391
|
+
- After `destroy`, `start` and `navigate` do nothing: no listener, no
|
|
392
|
+
history entry, and no emit.
|
|
322
393
|
17. **Case-sensitive by default.** `sensitive: true` (forwarded to the
|
|
323
|
-
underlying `Router`) is the default; `sensitive: false` folds
|
|
324
|
-
matching.
|
|
394
|
+
underlying `Router`) is the default; `sensitive: false` folds the ASCII
|
|
395
|
+
letters A to Z with a to z during matching, and no other letter.
|
|
325
396
|
18. **Intercepted links carry pathname only (known limitation).** Click
|
|
326
397
|
interception passes only the intercepted link's `/`-prefixed pathname
|
|
327
398
|
through to `navigate` — a query string on the link's `href` is not
|
|
@@ -333,37 +404,56 @@ These invariants hold across `src/core` / `src/browser` / `src/server` ↔
|
|
|
333
404
|
an `HTMLAnchorElement` — an SVG `<a>` (`SVGAElement`) is not intercepted,
|
|
334
405
|
even inside a same-origin document, and falls through to the browser's
|
|
335
406
|
native navigation.
|
|
336
|
-
20. **
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
`
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
407
|
+
20. **The target form decides the URL.** `buildRequest` builds its URL
|
|
408
|
+
through `buildURL`. An origin-form target is appended to the origin, so
|
|
409
|
+
`GET //evil.example/admin` keeps the origin's authority and routes the
|
|
410
|
+
pathname `//evil.example/admin`. An absolute-form target takes its own
|
|
411
|
+
authority, for `http:` and `https:` only. The asterisk form and every
|
|
412
|
+
other form throw a `ContractError`. The origin is `RequestOptions.origin`
|
|
413
|
+
when given; otherwise it is the connection's scheme and the `Host` header.
|
|
414
|
+
A `Host` header that is present must pass `isAuthority` for every target
|
|
415
|
+
form, with `RequestOptions.origin` set as well: a host with an optional
|
|
416
|
+
port, with no path, userinfo, whitespace, or port above 65535, on one
|
|
417
|
+
field line only (RFC 9112 section 3.2). A consuming server maps the throw
|
|
418
|
+
to 400. In 0.0.22 `buildRequest` resolved the target against the origin
|
|
419
|
+
with no check of its form or of the `Host` header: `//evil.example/admin`
|
|
420
|
+
took the authority `evil.example`, the asterisk form read as the path `/*`,
|
|
421
|
+
and the first of several `Host` lines won.
|
|
422
|
+
21. **The request signal aborts on a peer disconnect or on
|
|
423
|
+
`RequestOptions.signal`, and on nothing else.** `buildRequest` mints an
|
|
424
|
+
`AbortController`, builds the `Request` over its `signal`, and listens on
|
|
425
|
+
`RequestOptions.signal` until the exchange ends: when the paired
|
|
426
|
+
`RequestOptions.response` closes, or, without one, when the message
|
|
427
|
+
closes. An option signal that aborts in that time aborts the request
|
|
428
|
+
signal with the option signal's own reason; afterward it holds no
|
|
429
|
+
listener of the exchange and aborts nothing. A peer disconnect is the
|
|
430
|
+
message closing before it completed, or the paired response closing
|
|
431
|
+
before it ended. A body cancel, a discarded body, and a finished response
|
|
432
|
+
never abort it. 0.0.22 took no `signal` option and ignored one passed.
|
|
433
|
+
22. **The request body is pull-based.** For a body-carrying method, the body
|
|
434
|
+
reads the message only when its reader reads, through `readChunk`, with
|
|
435
|
+
`duplex: 'half'` set as Node's fetch implementation requires. An unread
|
|
436
|
+
body holds no more than the message's own buffer whatever the upload
|
|
437
|
+
size, and Node discards it after the response. A cancel discards the
|
|
438
|
+
remainder in place through `discardBody`, and so does the `finish` of the
|
|
439
|
+
paired response, so the connection serves its next request. In 0.0.22
|
|
440
|
+
`buildRequest` pumped the whole upload into the body whether or not a
|
|
441
|
+
reader read it, and a cancel destroyed the message, aborted
|
|
442
|
+
`request.signal`, and left the next request on the connection unanswered.
|
|
443
|
+
23. **A failed response reads as aborted.** `sendResponse` ends the
|
|
444
|
+
`ServerResponse` with a body that completes in its first chunk, framed by
|
|
445
|
+
its length, and pipes any other non-`null` body through
|
|
446
|
+
`Readable.fromWeb`, which honors backpressure. It removes every listener
|
|
447
|
+
it adds when the exchange ends. A response to a `HEAD` request, and a 1xx, 204, or 304 response,
|
|
448
|
+
carries no body on the wire, so `sendResponse` cancels its body unread and
|
|
449
|
+
ends the target, where 0.0.22 read a `HEAD` response's body to its end and
|
|
450
|
+
Node dropped each write. When the peer closes first, it cancels
|
|
451
|
+
the body, even one waiting for its next chunk, and resolves. When Node
|
|
452
|
+
refuses a header or the body fails, it destroys the target and rejects, so
|
|
453
|
+
the client reads an aborted response, never a truncated one that looks
|
|
454
|
+
complete. In 0.0.22 a failed body ended the target and `sendResponse`
|
|
455
|
+
resolved, so the client read the truncated response as complete.
|
|
456
|
+
24. **Header fidelity.** `buildRequest` copies every incoming header
|
|
367
457
|
(multi-value headers comma-joined, except `set-cookie`, appended
|
|
368
458
|
individually); `sendResponse` writes every outgoing header and re-derives
|
|
369
459
|
`set-cookie` through `Headers.getSetCookie()` so multiple response cookies
|
|
@@ -510,8 +600,11 @@ dispatcher.destroy() // tears down the #emitter; router.entries() is still valid
|
|
|
510
600
|
|
|
511
601
|
### Hash-mode navigation
|
|
512
602
|
|
|
513
|
-
A `Navigator` in hash mode dispatches on `location.hash
|
|
514
|
-
|
|
603
|
+
A `Navigator` in hash mode dispatches on `location.hash`, updates `active` after each
|
|
604
|
+
`hashchange`, and commits a `navigate` call as it pushes the hash. In 0.0.22 a hash
|
|
605
|
+
`navigate` set `location.hash` and committed after the `hashchange` fired. 0.0.23
|
|
606
|
+
removes the 0.0.22 `navigator.match` method, and `navigator.router.match` answers the
|
|
607
|
+
same lookup, as the following example shows:
|
|
515
608
|
|
|
516
609
|
```ts
|
|
517
610
|
import { createNavigator } from '@orkestrel/router/browser'
|
|
@@ -524,8 +617,8 @@ const navigator = createNavigator({
|
|
|
524
617
|
})
|
|
525
618
|
navigator.emitter.on('navigate', (match) => (document.title = match.meta.title))
|
|
526
619
|
navigator.start()
|
|
527
|
-
navigator.match('/about')?.meta.title // 'About' — a
|
|
528
|
-
navigator.navigate('/about') //
|
|
620
|
+
navigator.router.match('/about')?.meta.title // 'About' — a lookup, no location read
|
|
621
|
+
navigator.navigate('/about') // pushes '#/about'; `active` updates before the call returns
|
|
529
622
|
navigator.stop()
|
|
530
623
|
navigator.destroy() // stop() plus tear down the #emitter
|
|
531
624
|
```
|
|
@@ -549,7 +642,16 @@ navigator.start() // binds popstate + same-origin <a> click interception
|
|
|
549
642
|
### Guarding navigation (auth walls)
|
|
550
643
|
|
|
551
644
|
A guard may veto synchronously or asynchronously; a superseded guard's
|
|
552
|
-
verdict is discarded through its own `signal`.
|
|
645
|
+
verdict is discarded through its own `signal`. A `navigate` call or an intercepted
|
|
646
|
+
link asks the guard before the URL moves, so a vetoed one leaves the address bar
|
|
647
|
+
alone. In 0.0.22 both moved the URL first and asked the guard after, and no veto moved
|
|
648
|
+
the browser back, so the address bar kept the vetoed location while `active` kept the
|
|
649
|
+
previous match. When the browser moves first, through back, forward, a native fragment
|
|
650
|
+
link, or an address-bar edit, a veto of an entry the navigator wrote moves the
|
|
651
|
+
browser back to the entry `active` describes. For an entry it did not write, the
|
|
652
|
+
address bar keeps the vetoed location while `active` keeps the previous match:
|
|
653
|
+
compare `location` with `active` in your own `hashchange` or `popstate` listener
|
|
654
|
+
and `navigate` to the location you want.
|
|
553
655
|
|
|
554
656
|
```ts
|
|
555
657
|
import { createNavigator } from '@orkestrel/router/browser'
|
|
@@ -567,12 +669,20 @@ const navigator = createNavigator({
|
|
|
567
669
|
navigator.start()
|
|
568
670
|
```
|
|
569
671
|
|
|
570
|
-
###
|
|
672
|
+
### Composing a server
|
|
571
673
|
|
|
572
|
-
|
|
674
|
+
The server face converts and writes, and your server composes three calls:
|
|
675
|
+
`buildRequest`, `Dispatcher.handle`, and `sendResponse`. The error policy is
|
|
676
|
+
yours. `buildRequest` throws a `ContractError` for a refused target or `Host`,
|
|
677
|
+
which a server can answer with 400, and `sendResponse` has already destroyed
|
|
678
|
+
the connection when it rejects. 0.0.22 exported a `createListener` function
|
|
679
|
+
that composed these three calls and answered a throw before the headers went
|
|
680
|
+
out with a bare 500. 0.0.23 removes it, with `handleListenerRequest`,
|
|
681
|
+
`ListenerFunction`, and `StateFunction`, so compose the calls as the following
|
|
682
|
+
example does:
|
|
573
683
|
|
|
574
684
|
```ts
|
|
575
|
-
import {
|
|
685
|
+
import { buildRequest, sendResponse } from '@orkestrel/router/server'
|
|
576
686
|
import { createDispatcher } from '@orkestrel/router'
|
|
577
687
|
import http from 'node:http'
|
|
578
688
|
|
|
@@ -584,36 +694,13 @@ dispatcher.add({
|
|
|
584
694
|
Response.json({ id: context.params.id, requestId: context.state.requestId }),
|
|
585
695
|
})
|
|
586
696
|
|
|
587
|
-
const server = http.createServer(
|
|
588
|
-
createListener(dispatcher, () => ({ requestId: crypto.randomUUID() })),
|
|
589
|
-
)
|
|
590
|
-
server.listen(0)
|
|
591
|
-
```
|
|
592
|
-
|
|
593
|
-
### Converting requests and responses directly
|
|
594
|
-
|
|
595
|
-
For a runtime seam that needs finer control than `createListener` (custom
|
|
596
|
-
error handling around `dispatcher.handle`, for instance), compose
|
|
597
|
-
`buildRequest`/`sendResponse` directly:
|
|
598
|
-
|
|
599
|
-
```ts
|
|
600
|
-
import { buildRequest, sendResponse } from '@orkestrel/router/server'
|
|
601
|
-
import { createDispatcher } from '@orkestrel/router'
|
|
602
|
-
import http from 'node:http'
|
|
603
|
-
|
|
604
|
-
const dispatcher = createDispatcher()
|
|
605
|
-
dispatcher.add({ method: 'GET', path: '/health', handler: () => new Response('ok') })
|
|
606
|
-
|
|
607
|
-
const server = http.createServer(async (incoming, target) => {
|
|
608
|
-
const request = buildRequest(incoming, {
|
|
609
|
-
origin: 'https://api.example.com',
|
|
610
|
-
response: target,
|
|
611
|
-
})
|
|
697
|
+
const server = http.createServer(async (message, target) => {
|
|
612
698
|
try {
|
|
613
|
-
const
|
|
699
|
+
const request = buildRequest(message, { response: target })
|
|
700
|
+
const response = await dispatcher.handle(request, { requestId: crypto.randomUUID() })
|
|
614
701
|
await sendResponse(response, target)
|
|
615
|
-
} catch
|
|
616
|
-
target.writeHead(500).end(
|
|
702
|
+
} catch {
|
|
703
|
+
if (!target.headersSent && !target.destroyed) target.writeHead(500).end() // this consumer's own error policy
|
|
617
704
|
}
|
|
618
705
|
})
|
|
619
706
|
server.listen(0)
|
|
@@ -621,16 +708,17 @@ server.listen(0)
|
|
|
621
708
|
|
|
622
709
|
### Observing client disconnect
|
|
623
710
|
|
|
624
|
-
The `Request` returned by `buildRequest` carries a `signal` that aborts when the
|
|
625
|
-
|
|
711
|
+
The `Request` returned by `buildRequest` carries a `signal` that aborts when the peer
|
|
712
|
+
disconnects, or when the `signal` option aborts, such as a server's own shutdown:
|
|
626
713
|
|
|
627
714
|
```ts
|
|
628
715
|
import { buildRequest } from '@orkestrel/router/server'
|
|
629
716
|
import http from 'node:http'
|
|
630
717
|
|
|
718
|
+
const shutdown = new AbortController()
|
|
631
719
|
const server = http.createServer((incoming, response) => {
|
|
632
|
-
const request = buildRequest(incoming, { response })
|
|
633
|
-
request.signal.addEventListener('abort', () => console.log('client
|
|
720
|
+
const request = buildRequest(incoming, { response, signal: shutdown.signal })
|
|
721
|
+
request.signal.addEventListener('abort', () => console.log('client gone or server stopping'))
|
|
634
722
|
})
|
|
635
723
|
```
|
|
636
724
|
|
|
@@ -654,8 +742,12 @@ const server = http.createServer((incoming, response) => {
|
|
|
654
742
|
render in the consumer, never inside this headless entity.
|
|
655
743
|
- **`stop()`/`destroy()` before disposal** — releases listeners and aborts
|
|
656
744
|
any pending guard; `destroy()` also tears down the `#emitter`.
|
|
657
|
-
- **
|
|
658
|
-
|
|
745
|
+
- **Pass the paired response to `buildRequest`** — its `close` aborts the
|
|
746
|
+
request signal on a disconnect after the body, and its `finish` discards a
|
|
747
|
+
body the handler left unread, so a keep-alive connection serves its next
|
|
748
|
+
request.
|
|
749
|
+
- **Cancel a body you stop reading** — a cancel discards the rest of the upload
|
|
750
|
+
in place; it never aborts `request.signal` and never closes the connection.
|
|
659
751
|
- **Install your own error boundary for mapped error responses** — the
|
|
660
752
|
router (core and this adapter) never invents one; a handler throw
|
|
661
753
|
propagates.
|
|
@@ -671,7 +763,7 @@ const server = http.createServer((incoming, response) => {
|
|
|
671
763
|
interface-to-class method bijection for `RouterInterface`, `GroupInterface`,
|
|
672
764
|
`DispatcherInterface`, `DispatchGroupInterface`, and `NavigatorInterface`, and the
|
|
673
765
|
equality gate: every `Summary` cell against its declaration's description paragraph,
|
|
674
|
-
the titled `
|
|
766
|
+
the titled `Register and match` fence against the `@example` block of that title (pinned so
|
|
675
767
|
the titled pair cannot be retired silently), and the README pitch against this guide's
|
|
676
768
|
tagline. It also runs the flagship fences this project can execute and asserts the
|
|
677
769
|
values their comments claim.
|
|
@@ -695,12 +787,21 @@ const server = http.createServer((incoming, response) => {
|
|
|
695
787
|
with prefixes composed.
|
|
696
788
|
- [`tests/src/core/helpers.test.ts`](../tests/src/core/helpers.test.ts) —
|
|
697
789
|
`canonicalizePath`, `computeDispatchKey`, `compilePath` (literal/param/wildcard, escaped
|
|
698
|
-
regex metacharacters, trailing-slash folding, case sensitivity,
|
|
699
|
-
`decodeParam` (including a malformed `%` escape), `matchPath`,
|
|
790
|
+
regex metacharacters, encoded literals, trailing-slash folding, case sensitivity, and each
|
|
791
|
+
registration refusal), `decodeParam` (including a malformed `%` escape), `matchPath`,
|
|
700
792
|
`classifySegment` (the literal-vs-param classification fix regression
|
|
701
|
-
case), `computeSpecificity`, `compareSpecificity
|
|
793
|
+
case), `computeSpecificity`, `compareSpecificity` (tier, then literal length),
|
|
794
|
+
`encodePath`, `collectInputs`, `joinPaths`, and
|
|
702
795
|
`defineRoute` (identity pass-through, literal `Path` preservation at the
|
|
703
796
|
call site).
|
|
797
|
+
- [`tests/src/core/integration.test.ts`](../tests/src/core/integration.test.ts) —
|
|
798
|
+
the path matrix: `Router.match` and `Dispatcher.handle` against a reference
|
|
799
|
+
matcher written from the declared grammar, with its own encode set, refusal list,
|
|
800
|
+
and method list, over segment shapes, segment counts, trailing slashes, request
|
|
801
|
+
forms, case rules, methods, and registration orders, through the URL door and the
|
|
802
|
+
raw-text door, with the precedence applied by sort, an order-permutation property,
|
|
803
|
+
the encoder's pairs and a seeded differential, the host row, the registration
|
|
804
|
+
refusals, the batch admission, and the hand-declared rows for each path finding.
|
|
704
805
|
- [`tests/src/core/parsers.test.ts`](../tests/src/core/parsers.test.ts) —
|
|
705
806
|
`parseMethod` narrowing every registrable verb, rejecting an unknown verb
|
|
706
807
|
and the wrong casing, and accepting exactly the verbs `METHOD_LIST`
|
|
@@ -710,30 +811,46 @@ const server = http.createServer((incoming, response) => {
|
|
|
710
811
|
assertions.
|
|
711
812
|
- [`tests/src/browser/Navigator.test.ts`](../tests/src/browser/Navigator.test.ts) —
|
|
712
813
|
hash and history modes, `navigate()`/`active`/`navigate` event, fallback
|
|
713
|
-
semantics, guard veto (sync + async, including supersede-discard),
|
|
714
|
-
|
|
814
|
+
semantics, guard veto (sync + async, including supersede-discard), the guard
|
|
815
|
+
before the URL moves, the restore after a browser-initiated veto, a `navigate`
|
|
816
|
+
from a `navigate` listener, calls after `destroy`, link interception on/off and
|
|
817
|
+
outside `base`, `base` and hash text compared in one form,
|
|
818
|
+
`start`/`stop`/`destroy` idempotence, every door (history and hash `navigate`,
|
|
819
|
+
the configured and default fallback, raw and encoded text through `router.match`)
|
|
820
|
+
reaching a literal the path encoder changes,
|
|
715
821
|
`NavigatorInterface` conformance, and the transcriptions of this guide's
|
|
716
822
|
`@orkestrel/router/browser` fences.
|
|
823
|
+
- [`tests/src/browser/integration.test.ts`](../tests/src/browser/integration.test.ts) —
|
|
824
|
+
the core path grammar on the Chromium host: the host row, and a `|` literal through
|
|
825
|
+
Chromium's URL parsing of `new URL` and `history.pushState`, handed to `new Request` and
|
|
826
|
+
the real dispatcher (no fetch, navigation, or socket runs there).
|
|
717
827
|
- [`tests/src/browser/factories.test.ts`](../tests/src/browser/factories.test.ts) —
|
|
718
828
|
`createNavigator` returns a working `NavigatorInterface`.
|
|
719
829
|
- [`tests/src/browser/helpers.test.ts`](../tests/src/browser/helpers.test.ts) —
|
|
720
830
|
`computeNavigationKey`, `extractHashPath`, `resolveLocationPath` (hash + history, with/without
|
|
721
|
-
`base`), and `findAnchor` (including a click on a styled child inside an
|
|
831
|
+
`base`, a non-ASCII `base`, and `undefined` outside `base`), and `findAnchor` (including a click on a styled child inside an
|
|
722
832
|
anchor).
|
|
723
833
|
- [`tests/src/server/validators.test.ts`](../tests/src/server/validators.test.ts) —
|
|
724
|
-
`isEncryptedSocket` on
|
|
725
|
-
off-shape value
|
|
834
|
+
`isEncryptedSocket` on a real TLS socket, a plain socket, a plain record, and
|
|
835
|
+
every off-shape value; `isAuthority` over accepted and refused authorities and
|
|
836
|
+
every non-string value.
|
|
726
837
|
- [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) —
|
|
727
|
-
`
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
838
|
+
`buildURL` by target form, scheme, `Host`, and origin, with each refusal;
|
|
839
|
+
`readChunk` and `discardBody` on a paused message; `buildRequest` fidelity
|
|
840
|
+
(method, URL, headers including multi-value and `set-cookie`, body streaming,
|
|
841
|
+
the incomplete-request abort, and normal-response signal and listener
|
|
842
|
+
cleanup); and `sendResponse` (status, headers including `set-cookie`, bodies,
|
|
843
|
+
backpressure, a disconnect under pressure, and a body that is no stream) over
|
|
844
|
+
real `node:http` sockets.
|
|
845
|
+
- [`tests/src/server/integration.test.ts`](../tests/src/server/integration.test.ts) —
|
|
846
|
+
the HTTP conformance matrix: each row fed to a bare `node:http` control and to
|
|
847
|
+
the adapter, read through a raw client's own framing parse — the target form
|
|
848
|
+
and `Host` tables, the unread body's `bytesRead` at two upload sizes, a cancel
|
|
849
|
+
that leaves the connection reusable, a failed body and a refused header read
|
|
850
|
+
as aborted, the idle-body cancel on disconnect, the request signal, and the
|
|
851
|
+
transport rows (matched, 404, 405, auto-HEAD, auto-OPTIONS, a handler throw,
|
|
852
|
+
and per-request state) through the three-call composition, with the
|
|
853
|
+
`Composing a server` fence transcribed.
|
|
737
854
|
|
|
738
855
|
## See also
|
|
739
856
|
|
|
@@ -741,6 +858,6 @@ const server = http.createServer((incoming, response) => {
|
|
|
741
858
|
contract & validation architecture, one engine with native overrides,
|
|
742
859
|
and documentation as contracts.
|
|
743
860
|
- [`abort.md`](abort.md) — `@orkestrel/abort`, the supersede-safe guard
|
|
744
|
-
cancellation primitive the Navigator composes, and the
|
|
745
|
-
|
|
861
|
+
cancellation primitive the Navigator composes, and the primitive behind the
|
|
862
|
+
request signal `buildRequest` builds.
|
|
746
863
|
- [`README.md`](README.md) — the guides index.
|