@orkestrel/scaffold 0.0.138 → 0.0.140
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 +89 -29
- package/dist/bin/main.js.map +1 -1
- 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 +52 -52
- package/dist/host/guides/abort.md +2 -0
- package/dist/host/guides/browser.md +1 -1
- package/dist/host/guides/contract.md +314 -210
- package/dist/host/guides/guide.md +10 -2
- package/dist/host/guides/mcp.md +9 -9
- package/dist/host/guides/middleware.md +474 -259
- package/dist/host/guides/probe.md +1 -2
- package/dist/host/guides/router.md +282 -165
- package/dist/host/guides/scaffold.md +27 -18
- package/dist/host/guides/server.md +419 -183
- package/dist/host/manifest.json +14 -14
- package/dist/host/scripts/browsers.sh +0 -0
- package/dist/host/scripts/codex.sh +0 -0
- package/dist/host/scripts/cursor.sh +0 -0
- package/dist/host/scripts/deps.sh +0 -0
- package/dist/host/scripts/npm.sh +0 -0
- package/dist/host/scripts/ollama.sh +0 -0
- package/dist/src/core/index.cjs +17 -17
- package/dist/src/core/index.cjs.map +1 -1
- package/dist/src/core/index.js +17 -17
- package/dist/src/core/index.js.map +1 -1
- package/dist/src/server/index.cjs +6 -24
- package/dist/src/server/index.cjs.map +1 -1
- package/dist/src/server/index.d.cts +1 -1
- package/dist/src/server/index.d.ts +1 -1
- package/dist/src/server/index.js +7 -25
- package/dist/src/server/index.js.map +1 -1
- package/package.json +14 -14
|
@@ -4,19 +4,24 @@
|
|
|
4
4
|
> `create{Noun}(options) => MiddlewareHandler<TState>` factories for error
|
|
5
5
|
> boundaries, telemetry, compression, security headers, CORS, deadlines,
|
|
6
6
|
> trusted-proxy client facts, ETag, bearer authentication, rate limiting, body
|
|
7
|
-
> parsing, sessions, and CSRF
|
|
8
|
-
> static files, streaming multipart uploads, and a
|
|
9
|
-
>
|
|
7
|
+
> parsing, sessions, and CSRF over web-standard `Request` and `Response`, plus
|
|
8
|
+
> in-memory assets, static files, streaming multipart uploads, and a
|
|
9
|
+
> `node:zlib` compression sibling on Node.
|
|
10
10
|
|
|
11
|
-
This is the package's one guide
|
|
12
|
-
|
|
11
|
+
This is the package's one guide. The package publishes one server-only entry,
|
|
12
|
+
and every battery returns the `@orkestrel/server` `MiddlewareHandler`. Every
|
|
13
|
+
battery composes the frozen `@orkestrel/server` middleware seam
|
|
13
14
|
(`MiddlewareHandler`, `MiddlewareContext`, `compose`) and its substrate —
|
|
14
15
|
cookies, WebCrypto tokens, negotiation, conditionals, and security primitives.
|
|
15
16
|
This package never re-implements that seam, and it supplies mechanism rather
|
|
16
|
-
than product policy. Source: [`src/
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
17
|
+
than product policy. Source: [`src/server`](../src/server). Surfaced through
|
|
18
|
+
the `@orkestrel/middleware` barrel (aliased `@src/server` inside this repo).
|
|
19
|
+
Before 0.0.35, the package published two entries: the host-independent core at
|
|
20
|
+
`@orkestrel/middleware`, and `createAssets`, `createStatic`, `createMultipart`,
|
|
21
|
+
`createNodeCompression`, and the rest of the node face (its helpers, parsers,
|
|
22
|
+
errors, and asset store) at `@orkestrel/middleware/server`. From 0.0.35, the `./server` subpath is gone and
|
|
23
|
+
no alias replaces it: move every import from `@orkestrel/middleware/server` to
|
|
24
|
+
`@orkestrel/middleware`. The move removed and renamed no symbol.
|
|
20
25
|
|
|
21
26
|
## Surface
|
|
22
27
|
|
|
@@ -26,7 +31,7 @@ seam.
|
|
|
26
31
|
|
|
27
32
|
### Mount a battery
|
|
28
33
|
|
|
29
|
-
The fence composes
|
|
34
|
+
The fence composes the security battery outside an error boundary over `compose`, then answers with the request identifier `createSecurity` stashed on `context.state`.
|
|
30
35
|
|
|
31
36
|
```ts
|
|
32
37
|
import { createBoundary, createSecurity } from '@orkestrel/middleware'
|
|
@@ -38,118 +43,117 @@ interface State extends IdentifierState {}
|
|
|
38
43
|
const boundary = createBoundary({ expose: false })
|
|
39
44
|
const security = createSecurity({ hsts: true })
|
|
40
45
|
|
|
41
|
-
const handle = compose<State>([
|
|
46
|
+
const handle = compose<State>([security, boundary], async (_request, context) => {
|
|
42
47
|
return Response.json({ identifier: context.state.identifier })
|
|
43
48
|
})
|
|
44
49
|
```
|
|
45
50
|
|
|
46
|
-
### Middlewares —
|
|
47
|
-
|
|
48
|
-
| Name | Kind | Signature
|
|
49
|
-
| ------------------- | -------- |
|
|
50
|
-
| `createBoundary` | function | `<TState>(options?: BoundaryOptions) => MiddlewareHandler<TState>`
|
|
51
|
-
| `createTelemetry` | function | `<TState>(options: TelemetryOptions) => MiddlewareHandler<TState>`
|
|
52
|
-
| `createCompression` | function | `<TState>(options?: CompressionOptions) => MiddlewareHandler<TState>`
|
|
53
|
-
| `createSecurity` | function | `<TState extends IdentifierState>(options?: SecurityOptions) => MiddlewareHandler<TState>`
|
|
54
|
-
| `
|
|
55
|
-
| `createDeadline` | function | `<TState>(options: DeadlineOptions) => MiddlewareHandler<TState>`
|
|
56
|
-
| `createForwarded` | function | `<TState extends ClientState
|
|
57
|
-
| `createETag` | function | `<TState>(options?: ETagOptions) => MiddlewareHandler<TState>`
|
|
58
|
-
| `createBearer` | function | `<TState extends BearerState<TCredential>, TCredential = string>(options: BearerOptions<TCredential>) => MiddlewareHandler<TState>`
|
|
59
|
-
| `createLimiter` | function | `<TState extends BearerState<unknown> & ClientState
|
|
60
|
-
| `createBody` | function | `<TState extends BodyState = BodyState>() => MiddlewareHandler<TState>`
|
|
61
|
-
| `createSession` | function | `<S extends SessionInterface = SessionInterface, TState extends SessionState
|
|
62
|
-
| `createCSRF` | function | `<TState extends CSRFState & SessionState
|
|
63
|
-
| `only` | function | `<TState>(paths: string \| readonly string[], handler: MiddlewareHandler<TState>) => MiddlewareHandler<TState>`
|
|
64
|
-
| `except` | function | `<TState>(paths: string \| readonly string[], handler: MiddlewareHandler<TState>) => MiddlewareHandler<TState>`
|
|
51
|
+
### Middlewares — web-standard
|
|
52
|
+
|
|
53
|
+
| Name | Kind | Signature | Summary |
|
|
54
|
+
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| `createBoundary` | function | `<TState>(options?: BoundaryOptions) => MiddlewareHandler<TState>` | Creates the error-rendering battery — catches a downstream throw and renders it as a `Response`. |
|
|
56
|
+
| `createTelemetry` | function | `<TState>(options: TelemetryOptions) => MiddlewareHandler<TState>` | Creates the access-log/timing seam — records one `TelemetryEntry` per request after the response settles. |
|
|
57
|
+
| `createCompression` | function | `<TState>(options?: CompressionOptions) => MiddlewareHandler<TState>` | Creates the response-body compression battery — negotiates and compresses a buffered response body over the runtime's feature-detected `CompressionStream` codings. |
|
|
58
|
+
| `createSecurity` | function | `<TState extends IdentifierState>(options?: SecurityOptions) => MiddlewareHandler<TState>` | Creates the security-headers + request-identifier battery — sets each documented header default, and mints or echoes a request identifier. |
|
|
59
|
+
| `createCORS` | function | `<TState>(options?: CORSOptions) => MiddlewareHandler<TState>` | Creates the Cross-Origin Resource Sharing battery — answers a preflight itself, and reflects an allow-listed origin or serves the configured wildcard. |
|
|
60
|
+
| `createDeadline` | function | `<TState>(options: DeadlineOptions) => MiddlewareHandler<TState>` | Creates the application-level per-request deadline battery. |
|
|
61
|
+
| `createForwarded` | function | `<TState extends ClientState>(options: ForwardedOptions) => MiddlewareHandler<TState>` | Creates the trusted-proxy client-IP resolver battery — walks `X-Forwarded-For` past the hops its options declare trusted. |
|
|
62
|
+
| `createETag` | function | `<TState>(options?: ETagOptions) => MiddlewareHandler<TState>` | Creates the dynamic response `ETag` + conditional GET battery (RFC 7232). |
|
|
63
|
+
| `createBearer` | function | `<TState extends BearerState<TCredential>, TCredential = string>(options: BearerOptions<TCredential>) => MiddlewareHandler<TState>` | Creates the bearer-token authentication battery — reads the token from its header, resolves its credential through `verify`, and answers each `401` with a `WWW-Authenticate` challenge. |
|
|
64
|
+
| `createLimiter` | function | `<TState extends BearerState<unknown> & ClientState>(options: LimiterOptions<TState>) => MiddlewareHandler<TState>` | Creates the fixed-window rate-limiting battery — checks a key's budget before consuming it, so one window admits exactly `max` requests. |
|
|
65
|
+
| `createBody` | function | `<TState extends BodyState = BodyState>() => MiddlewareHandler<TState>` | Creates the body-driving battery — eagerly awaits the cached `context.body()` so its throws (or a malformed-JSON `undefined`) surface before the handler runs, and stashes the resolved value onto `BodyState.body`. |
|
|
66
|
+
| `createSession` | function | `<S extends SessionInterface = SessionInterface, TState extends SessionState = SessionState>(options: SessionOptions<S, TState>) => MiddlewareHandler<TState>` | Creates the generic session battery — resolves, mints, and persists a session across the request, with a mid-handler `regenerate`/`destroy` control handle. |
|
|
67
|
+
| `createCSRF` | function | `<TState extends CSRFState & SessionState>(options: CSRFOptions) => MiddlewareHandler<TState>` | Creates the CSRF protection battery: a signed double submit bound to the session the client holds, or to the battery's own nonce cookie when it holds none. |
|
|
68
|
+
| `only` | function | `<TState>(paths: string \| readonly string[], handler: MiddlewareHandler<TState>) => MiddlewareHandler<TState>` | Scopes a battery to the paths its route patterns match and nowhere else — outside them it steps aside through `next()`. |
|
|
69
|
+
| `except` | function | `<TState>(paths: string \| readonly string[], handler: MiddlewareHandler<TState>) => MiddlewareHandler<TState>` | Scopes a battery to every path its route patterns do not match — on the matched paths it steps aside through `next()`. |
|
|
65
70
|
|
|
66
71
|
### Middlewares — node
|
|
67
72
|
|
|
68
|
-
| Name | Kind | Signature | Summary
|
|
69
|
-
| ----------------------- | -------- | ------------------------------------------------------------------------------------------ |
|
|
70
|
-
| `createAssets` | function | `<TState>(options: AssetOptions) => MiddlewareHandler<TState>` | Serves validated in-memory assets with identity/Brotli negotiation.
|
|
71
|
-
| `createStatic` | function | `<TState>(options: StaticOptions) => MiddlewareHandler<TState>` | Serves static files from `options.root` over `node:fs` — the node-bound static-file battery, answering conditional, ranged, and SPA-fallback requests.
|
|
72
|
-
| `createMultipart` | function | `<TState extends MultipartState>(options?: MultipartOptions) => MiddlewareHandler<TState>` | Parses a streamed `multipart/form-data` request body and stashes its `MultipartBody` on `context.state.multipart` — the node-bound streaming multipart battery.
|
|
73
|
-
| `createNodeCompression` | function | `<TState>(options?: NodeCompressionOptions) => MiddlewareHandler<TState>` | Compresses response bodies through `node:zlib`,
|
|
73
|
+
| Name | Kind | Signature | Summary |
|
|
74
|
+
| ----------------------- | -------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
75
|
+
| `createAssets` | function | `<TState>(options: AssetOptions) => MiddlewareHandler<TState>` | Serves validated in-memory assets with identity/Brotli negotiation. |
|
|
76
|
+
| `createStatic` | function | `<TState>(options: StaticOptions) => MiddlewareHandler<TState>` | Serves static files from `options.root` over `node:fs` — the node-bound static-file battery, answering conditional, ranged, and SPA-fallback requests. |
|
|
77
|
+
| `createMultipart` | function | `<TState extends MultipartState>(options?: MultipartOptions) => MiddlewareHandler<TState>` | Parses a streamed `multipart/form-data` request body and stashes its `MultipartBody` on `context.state.multipart` — the node-bound streaming multipart battery. |
|
|
78
|
+
| `createNodeCompression` | function | `<TState>(options?: NodeCompressionOptions) => MiddlewareHandler<TState>` | Compresses response bodies through `node:zlib`, which every Node runtime bundles, instead of relying on the WHATWG `CompressionStream` global. This battery is the node-bound sibling of the feature-detected `createCompression`, and both compose the same `compressResponse` skeleton. |
|
|
74
79
|
|
|
75
80
|
### Types
|
|
76
81
|
|
|
77
|
-
| Name | Kind | Signature | Summary
|
|
78
|
-
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------- |
|
|
79
|
-
| `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the
|
|
80
|
-
| `TelemetryEntry` | interface | `{ method, pathname, status, duration }` | Represents one access-log-style entry `createTelemetry` records after a response settles — the access-log/timing seam's payload shape.
|
|
81
|
-
| `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam.
|
|
82
|
-
| `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }` | Configures `createCompression` — response-body compression.
|
|
83
|
-
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each of `createCompression` and `createNodeCompression` builds from its own option bag.
|
|
84
|
-
| `SecurityIdentifierOptions` | type | `{ readonly trust?: boolean; } \| false` | Describes `createSecurity`'s `identifier` sub-option — request-id minting/echo policy, or `false` to disable the feature entirely.
|
|
85
|
-
| `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }` | Configures `createSecurity` — the security-headers + request-id battery.
|
|
86
|
-
| `
|
|
87
|
-
| `DeadlineOptions` | interface | `{ ms, status? }` | Configures `createDeadline` — the application-level per-request deadline.
|
|
88
|
-
| `ForwardedOptions` | type | `{ readonly proxies: number; } \| { readonly trusted: readonly string[]; }` | Configures `createForwarded` — the trusted-proxy client-IP resolver.
|
|
89
|
-
| `ETagOptions` | interface | `{ weak? }` | Configures `createETag` — dynamic response ETag + conditional GET.
|
|
90
|
-
| `BearerOptions` | interface | `{ verify, header?, scheme?, challenge? }` | Configures `createBearer` — bearer-token authentication.
|
|
91
|
-
| `BearerVerifyFunction` | type | `(token: string, request: Request) => TCredential \| undefined \| Promise<TCredential \| undefined>` | Verifies a presented bearer token and resolves its credential, or `undefined` to refuse it.
|
|
92
|
-
| `LimiterOptions` | interface | `{ store?, max, window, capacity?, key?, message?, clock?, policy?, evict? }` | Configures `createLimiter` — fixed-window rate limiting.
|
|
93
|
-
| `BearerState` | interface | `{ token? }` | Describes the bearer-authentication state slice `createBearer` stashes on `context.state`
|
|
94
|
-
| `IdentifierState` | interface | `{ identifier? }` | Describes the request-identifier state slice `createSecurity` stashes when its `identifier` option is enabled.
|
|
95
|
-
| `Client` | interface | `{ ip? }` | Describes the resolved client connection facts `createForwarded` stashes.
|
|
96
|
-
| `ClientState` | interface | `{ client? }` | Describes the client-facts state slice `createForwarded` stashes.
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
100
|
-
| `
|
|
101
|
-
| `
|
|
102
|
-
| `
|
|
103
|
-
| `
|
|
104
|
-
| `
|
|
105
|
-
| `
|
|
106
|
-
| `
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
110
|
-
| `
|
|
111
|
-
| `
|
|
112
|
-
| `
|
|
113
|
-
| `
|
|
114
|
-
| `
|
|
115
|
-
| `
|
|
116
|
-
| `
|
|
117
|
-
| `
|
|
118
|
-
| `
|
|
119
|
-
| `
|
|
120
|
-
| `
|
|
121
|
-
| `
|
|
122
|
-
| `
|
|
123
|
-
| `
|
|
124
|
-
| `
|
|
125
|
-
| `
|
|
126
|
-
| `
|
|
127
|
-
| `
|
|
128
|
-
| `
|
|
129
|
-
| `
|
|
130
|
-
| `
|
|
131
|
-
| `ByteRange` | interface | `{ start, end }` | Describes one inclusive byte range over a file — `streamFile`'s optional `range` argument and the shape `createStatic` builds for a satisfiable `Range` request. |
|
|
82
|
+
| Name | Kind | Signature | Summary |
|
|
83
|
+
| --------------------------- | --------- | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
84
|
+
| `BoundaryOptions` | interface | `{ expose?, report? }` | Configures `createBoundary` — the error-rendering battery. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
85
|
+
| `TelemetryEntry` | interface | `{ method, pathname, status, duration }` | Represents one access-log-style entry `createTelemetry` records after a response settles — the access-log/timing seam's payload shape. |
|
|
86
|
+
| `TelemetryOptions` | interface | `{ record }` | Configures `createTelemetry` — the request timing/access-log seam. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
87
|
+
| `CompressionOptions` | interface | `{ threshold?, encodings?, filter? }` | Configures `createCompression` — response-body compression. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
88
|
+
| `CompressResponseOptions` | interface | `{ threshold, filter?, encodings, compress }` | Describes the already-resolved settings `compressResponse` runs its shared negotiate → skip → threshold → compress skeleton against — the shape each of `createCompression` and `createNodeCompression` builds from its own option bag. |
|
|
89
|
+
| `SecurityIdentifierOptions` | type | `{ readonly trust?: boolean; } \| false` | Describes `createSecurity`'s `identifier` sub-option — request-id minting/echo policy, or `false` to disable the feature entirely. |
|
|
90
|
+
| `SecurityOptions` | interface | `{ frame?, csp?, referrer?, permissions?, coop?, corp?, cluster?, coep?, hsts?, identifier? }` | Configures `createSecurity` — the security-headers + request-id battery. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
91
|
+
| `CORSOptions` | interface | `{ origin?, methods?, headers? }` | Configures `createCORS` — Cross-Origin Resource Sharing. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
92
|
+
| `DeadlineOptions` | interface | `{ ms, status? }` | Configures `createDeadline` — the application-level per-request deadline. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
93
|
+
| `ForwardedOptions` | type | `{ readonly proxies: number; } \| { readonly trusted: readonly string[]; }` | Configures `createForwarded` — the trusted-proxy client-IP resolver. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
94
|
+
| `ETagOptions` | interface | `{ weak? }` | Configures `createETag` — dynamic response ETag + conditional GET. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
95
|
+
| `BearerOptions` | interface | `{ verify, header?, scheme?, challenge? }` | Configures `createBearer` — bearer-token authentication. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
96
|
+
| `BearerVerifyFunction` | type | `(token: string, request: Request) => TCredential \| undefined \| Promise<TCredential \| undefined>` | Verifies a presented bearer token and resolves its credential, or `undefined` to refuse it. |
|
|
97
|
+
| `LimiterOptions` | interface | `{ store?, max, window, capacity?, key?, message?, clock?, policy?, evict? }` | Configures `createLimiter` — fixed-window rate limiting. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
98
|
+
| `BearerState` | interface | `{ token? }` | Describes the bearer-authentication state slice `createBearer` stashes on `context.state` after a token verifies. |
|
|
99
|
+
| `IdentifierState` | interface | `{ identifier? }` | Describes the request-identifier state slice `createSecurity` stashes when its `identifier` option is enabled. |
|
|
100
|
+
| `Client` | interface | `{ ip? }` | Describes the resolved client connection facts `createForwarded` stashes. |
|
|
101
|
+
| `ClientState` | interface | `{ client? }` | Describes the client-facts state slice `createForwarded` stashes. |
|
|
102
|
+
| `SessionInterface` | interface | `{ id, state, set(), delete(), clear() }` | Represents a server-managed session's public surface — an id, its live state, and the mutators that write it. |
|
|
103
|
+
| `SessionControlInterface` | interface | `{ destroyed, successor, fresh, regenerate(), destroy() }` | Describes the mid-handler control handle `createSession` stashes alongside the session itself — the OWASP anti-fixation / logout primitives. |
|
|
104
|
+
| `SessionState` | interface | `{ session?, control? }` | Describes the session state slice `createSession` stashes. |
|
|
105
|
+
| `BodyState` | interface | `{ body? }` | Describes the body state slice `createBody` stashes. |
|
|
106
|
+
| `SessionStoreInterface` | interface | `{ get(), set(), delete() }` | Describes the pluggable session persistence seam `createSession`'s `store` option implements — a point-access store keyed by session id. |
|
|
107
|
+
| `SessionTransportInterface` | interface | `{ read(), write(), clear() }` | Describes the transport seam `createSession`'s `transport` option implements — how a session id travels to and from the client (a signed cookie, a header, …). |
|
|
108
|
+
| `SessionOptions` | interface | `{ transport, store?, ttl?, lifetime?, capacity?, evict?, create?, mint?, required?, clock? }` | Configures `createSession` — the generic session battery. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
109
|
+
| `CookieTransportOptions` | interface | `{ name?, signer, cookie? }` | Configures `createCookieTransport` — the signed-cookie `SessionTransportInterface`. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
110
|
+
| `HeaderTransportOptions` | interface | `{ header? }` | Configures `createHeaderTransport` — the bare-header `SessionTransportInterface`. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
111
|
+
| `MemorySessionStoreOptions` | interface | `{ capacity?, evict? }` | Configures `createMemorySessionStore` — the default in-process `SessionStoreInterface`. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
112
|
+
| `SessionLimits` | interface | `{ ttl?, lifetime? }` | Describes the idle and absolute-lifetime thresholds a session store enforces — `sessionExpired`'s limits argument and both shipped stores' construction options. `createDatabaseSessionStore` admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
113
|
+
| `SessionCursors` | interface | `{ seen, created }` | Describes the per-session instants a store stamps and `sessionExpired` measures against. |
|
|
114
|
+
| `SessionRow` | interface | `{ id, session }` | Represents one persisted session row — an opaque snapshot column plus the store-owned idle/absolute-lifetime cursors, the shape a `DatabaseSessionStore`'s backing table holds. |
|
|
115
|
+
| `SessionEntry` | interface | `{ session }` | Represents one in-process session entry — the payload `MemorySessionStore` holds against an id, alongside the same cursors a persisted row carries. |
|
|
116
|
+
| `SessionSnapshot` | interface | `{ id, state }` | Represents a session's serializable projection — the value `snapshotSession` produces and a durable store's `set` writes. |
|
|
117
|
+
| `SessionRestoreFunction` | type | `(value: unknown) => SessionInterface \| undefined` | Rebuilds a session entity from an untrusted stored snapshot, or resolves `undefined` when the value is malformed. |
|
|
118
|
+
| `CSRFState` | interface | `{ csrf? }` | Describes the CSRF state slice `createCSRF` stashes — a token bound to the session the request arrived with, or to the battery's nonce, for the page to submit back. |
|
|
119
|
+
| `CSRFOptions` | interface | `{ signer, cookie?, header?, field?, safe? }` | Configures `createCSRF` — signed double-submit CSRF protection, bound to the session the client holds or to the battery's own nonce. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
120
|
+
| `MultipartFile` | interface | `{ field, name, size, mime, validated, status, path }` | Represents one staged multipart upload's public record — the shape the node-face `createMultipart` battery (`@orkestrel/middleware`) produces per uploaded file. |
|
|
121
|
+
| `MultipartBody` | interface | `{ files, fields }` | Describes the parsed multipart request body `createMultipart` stashes — files keyed by their field name, plus every plain text field. |
|
|
122
|
+
| `MultipartState` | interface | `{ multipart? }` | Describes the multipart state slice `createMultipart` stashes. |
|
|
123
|
+
| `AssetRepresentation` | interface | `{ body, encoding? }` | Describes one in-memory asset representation returned by an `AssetSourceInterface`. |
|
|
124
|
+
| `AssetSourceInterface` | interface | `{ read() }` | Reads in-memory assets by decoded, browser-build-relative path. |
|
|
125
|
+
| `AssetOptions` | interface | `{ source, store? }` | Configures `createAssets` — in-memory identity/Brotli asset serving. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
126
|
+
| `StaticOptions` | interface | `{ root, prefix?, index?, dotfiles?, cache?, etag?, fallback? }` | Configures `createStatic` — node `fs`-backed static file serving. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
127
|
+
| `MultipartLimitsInput` | interface | `{ file?, field?, total? }` | Describes the caller's partial `MultipartLimits` — `createMultipart`'s `limits` option, with every member optional. |
|
|
128
|
+
| `MultipartLimits` | interface | `{ file, field, total }` | Describes the per-category size/count caps `createMultipart` enforces mid-stream — the effective limits, every documented default already applied. |
|
|
129
|
+
| `MultipartOptions` | interface | `{ limits?, allowed?, directory? }` | Configures `createMultipart` — node `fs`/`os`/`crypto`-backed streaming multipart upload parsing. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
130
|
+
| `NodeCompressionOptions` | interface | `{ threshold?, filter? }` | Configures `createNodeCompression` — `node:zlib`-backed response compression. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
131
|
+
| `MultipartErrorCode` | type | `'limit' \| 'malformed' \| 'rejected'` | Names the reason `createMultipart` rejected a request — the machine-readable code `MultipartError` carries and maps onto its HTTP status: `'limit'` → 413, `'malformed'` → 400, `'rejected'` → 415. |
|
|
132
|
+
| `UploadStatus` | type | `'staged' \| 'moved'` | Names the lifecycle stage of one staged upload's temp file. |
|
|
133
|
+
| `UploadedFile` | interface | `{ status }` | Describes one uploaded file's post-parse record — the node-bound, richer sibling of `MultipartFile` (identical fields, `status` narrowed to `UploadStatus`). Structurally assignable into `MultipartFile` so a `createMultipart`-built `MultipartBody` satisfies the shared shape. |
|
|
134
|
+
| `PartHeaders` | interface | `{ name, filename, mime }` | Describes one multipart part's parsed header block — `parsePartHeaders`'s return shape. |
|
|
135
|
+
| `ByteRange` | interface | `{ start, end }` | Describes one inclusive byte range over a file — `streamFile`'s optional `range` argument and the shape `createStatic` builds for a satisfiable `Range` request. |
|
|
132
136
|
|
|
133
137
|
### Store and response types
|
|
134
138
|
|
|
135
|
-
| Name | Kind | Signature | Summary
|
|
136
|
-
| --------------------------- | --------- | --------------------------------- |
|
|
137
|
-
| `StaticFile` | interface | `{ path, handle, info }` | Describes an opened static file and the facts read from its handle.
|
|
138
|
-
| `StaticResolution` | interface | `{ path, contained }` | Describes a canonical static path and whether it lies inside the serving root.
|
|
139
|
-
| `StaticPlan` | interface | `{ status, headers, range }` | Describes response headers and the optional byte interval of a static file.
|
|
140
|
-
| `LimiterLimits` | interface | `{ max, window }` | Describes the budget and duration used when a limiter window starts.
|
|
141
|
-
| `LimiterResult` | interface | `{ admitted, expiry }` | Reports an atomic admission decision and its window expiry instant.
|
|
142
|
-
| `LimiterEntry` | interface | `{ budget, expiry }` | Holds the budget and expiry instant of an in-memory limiter entry.
|
|
143
|
-
| `LimiterStoreInterface` | interface | `{ consume() }` | Provides atomic per-key fixed-window admission.
|
|
144
|
-
| `MemoryLimiterStoreOptions` | interface | `{ capacity?, evict? }` | Configures the in-memory limiter's capacity and eviction observation.
|
|
145
|
-
| `AssetRecord` | interface | `{ key, identity, brotli, etag }` | Holds copied asset representations and their shared identity validator.
|
|
146
|
-
| `AssetStoreInterface` | interface | `{ get(), set(), delete() }` | Provides asynchronous point access to cached asset representations.
|
|
139
|
+
| Name | Kind | Signature | Summary |
|
|
140
|
+
| --------------------------- | --------- | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
141
|
+
| `StaticFile` | interface | `{ path, handle, info }` | Describes an opened static file and the facts read from its handle. |
|
|
142
|
+
| `StaticResolution` | interface | `{ path, contained }` | Describes a canonical static path and whether it lies inside the serving root. |
|
|
143
|
+
| `StaticPlan` | interface | `{ status, headers, range }` | Describes response headers and the optional byte interval of a static file. |
|
|
144
|
+
| `LimiterLimits` | interface | `{ max, window }` | Describes the budget and duration used when a limiter window starts. |
|
|
145
|
+
| `LimiterResult` | interface | `{ admitted, expiry }` | Reports an atomic admission decision and its window expiry instant. |
|
|
146
|
+
| `LimiterEntry` | interface | `{ budget, expiry }` | Holds the budget and expiry instant of an in-memory limiter entry. |
|
|
147
|
+
| `LimiterStoreInterface` | interface | `{ consume() }` | Provides atomic per-key fixed-window admission. |
|
|
148
|
+
| `MemoryLimiterStoreOptions` | interface | `{ capacity?, evict? }` | Configures the in-memory limiter's capacity and eviction observation. The factory admits the bag whole, and a refusal is a `ContractError`. The bag must be a plain object; a class instance refuses. |
|
|
149
|
+
| `AssetRecord` | interface | `{ key, identity, brotli, etag }` | Holds copied asset representations and their shared identity validator. |
|
|
150
|
+
| `AssetStoreInterface` | interface | `{ get(), set(), delete() }` | Provides asynchronous point access to cached asset representations. |
|
|
147
151
|
|
|
148
152
|
### Request control and stores
|
|
149
153
|
|
|
150
154
|
| Name | Kind | Signature | Summary |
|
|
151
155
|
| -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
|
|
152
|
-
| `SessionControl` | class | `new (session: SessionInterface, create?: (id: string) => SessionInterface) => SessionControlInterface`
|
|
156
|
+
| `SessionControl` | class | `new (session: SessionInterface, create?: (id: string) => SessionInterface, fresh?: boolean) => SessionControlInterface` | Records one request's session regeneration or destruction intent. |
|
|
153
157
|
| `MemoryLimiterStore` | class | `new (options?: MemoryLimiterStoreOptions) => LimiterStoreInterface` | Stores fixed-window budgets with atomic admission and bounded LRU retention. |
|
|
154
158
|
| `MemoryAssetStore` | class | `new () => AssetStoreInterface` | Stores asset representations by key for the lifetime of the store. |
|
|
155
159
|
| `createMemoryLimiterStore` | function | `(options?: MemoryLimiterStoreOptions) => LimiterStoreInterface` | Creates a bounded in-memory atomic limiter store. |
|
|
@@ -179,25 +183,32 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
179
183
|
| `DEFAULT_COEP` | const | `"require-corp"` | Holds `'require-corp'`, the value `createSecurity` sets for `Cross-Origin-Embedder-Policy` when `coep: true`. |
|
|
180
184
|
| `DEFAULT_HSTS` | const | `"max-age=31536000; includeSubDomains"` | Holds `'max-age=31536000; includeSubDomains'`, the value `createSecurity` sets for `Strict-Transport-Security` when `hsts: true`. |
|
|
181
185
|
| `DEFAULT_IDENTIFIER_HEADER` | const | `"x-request-id"` | Names `'x-request-id'`, the default header `createSecurity` mints or echoes a request identifier into. |
|
|
182
|
-
| `DEFAULT_CORS_METHODS` | const | `readonly string[]` | Lists the default methods `
|
|
183
|
-
| `DEFAULT_CORS_HEADERS` | const | `readonly string[]` | Lists the default headers `
|
|
186
|
+
| `DEFAULT_CORS_METHODS` | const | `readonly string[]` | Lists the default methods `createCORS` advertises on a preflight response. |
|
|
187
|
+
| `DEFAULT_CORS_HEADERS` | const | `readonly string[]` | Lists the default headers `createCORS` advertises on a preflight response. |
|
|
184
188
|
| `DEFAULT_DEADLINE_STATUS` | const | `503` | Holds `503`, the default response status `createDeadline` returns when its deadline fires first. |
|
|
185
189
|
| `DEFAULT_BEARER_HEADER` | const | `"authorization"` | Names `'authorization'`, the default header `createBearer` reads the token from. |
|
|
186
190
|
| `DEFAULT_BEARER_SCHEME` | const | `"Bearer"` | Names `'Bearer'`, the default scheme prefix `createBearer` strips before verification. |
|
|
187
191
|
| `CHALLENGE_TOKEN` | const | `Readonly<RegExp>` | Matches an RFC 9110 `token`, the form a challenge scheme and an auth-param name take. |
|
|
188
192
|
| `CHALLENGE_VALUE` | const | `Readonly<RegExp>` | Matches the characters RFC 6750 § 3 admits in a quoted auth-param value: `%x20-21 / %x23-5B / %x5D-7E`. |
|
|
193
|
+
| `IPV4_ADDRESS` | const | `Readonly<RegExp>` | Matches a dotted-decimal IPv4 address: four decimal octets from 0 to 255, with no sign, hex digit, leading zero, or empty octet. |
|
|
194
|
+
| `IPV4_MAPPED_PREFIX` | const | `Readonly<RegExp>` | Matches the `::ffff:` prefix, in either case, of an IPv4-mapped IPv6 address written with its embedded dotted IPv4. |
|
|
195
|
+
| `CIDR_LENGTH` | const | `Readonly<RegExp>` | Matches an IPv4 CIDR prefix length `createForwarded`'s roster admits: a decimal from 8 to 32, with no sign or leading zero. |
|
|
189
196
|
| `DEFAULT_LIMITER_CAPACITY` | const | `10000` | Holds `10_000`, the default maximum number of distinct rate-limit keys `createLimiter` tracks before LRU eviction. |
|
|
190
197
|
| `DEFAULT_LIMITER_MESSAGE` | const | `"rate limit exceeded"` | Holds `'rate limit exceeded'`, the default 429 body message `createLimiter` sends when a key is over budget. |
|
|
191
|
-
| `DEFAULT_SESSION_CAPACITY` | const | `10000` | Holds `10_000`, the default maximum number of distinct session ids `createMemorySessionStore` tracks before
|
|
198
|
+
| `DEFAULT_SESSION_CAPACITY` | const | `10000` | Holds `10_000`, the default maximum number of distinct session ids `createMemorySessionStore` tracks before least-recently-used eviction. |
|
|
192
199
|
| `DEFAULT_SESSION_COOKIE` | const | `"session"` | Names `'session'`, the default cookie `createCookieTransport` writes the signed session id under. |
|
|
193
200
|
| `DEFAULT_SESSION_HEADER` | const | `"session-id"` | Names `'session-id'`, the default header `createHeaderTransport` carries the session id in. |
|
|
194
|
-
| `DEFAULT_CSRF_COOKIE` | const | `"csrf"` | Names `'csrf'`, the default
|
|
201
|
+
| `DEFAULT_CSRF_COOKIE` | const | `"csrf"` | Names `'csrf'`, the default cookie `createCSRF` keeps its nonce in when the client holds no session. |
|
|
202
|
+
| `CSRF_LABEL` | const | `"csrf:"` | Opens every message `createCSRF` signs; its `:` lies outside the base64url alphabet, so no base64url `signToken` payload equals a CSRF message. |
|
|
203
|
+
| `CSRF_NONCE_BYTES` | const | `32` | Holds `32`, the byte count of a CSRF nonce and of a CSRF token's random part. |
|
|
204
|
+
| `CSRF_NONCE_PATTERN` | const | `Readonly<RegExp>` | Matches a CSRF nonce or a CSRF token's random part: the 43 base64url characters that encode `CSRF_NONCE_BYTES` bytes. |
|
|
205
|
+
| `CSRF_FIELD_TYPES` | const | `readonly string[]` | Lists the media types whose body `createCSRF` reads its field from: the two the server decodes to a record. |
|
|
195
206
|
| `DEFAULT_CSRF_HEADER` | const | `"x-csrf-token"` | Names `'x-csrf-token'`, the default header `createCSRF` reads a mutating request's submitted token from. |
|
|
196
207
|
| `DEFAULT_CSRF_FIELD` | const | `"_csrf"` | Names `'_csrf'`, the default body field `createCSRF` falls back to reading a mutating request's submitted token from. |
|
|
197
208
|
| `DEFAULT_CSRF_SAFE_METHODS` | const | `readonly string[]` | Lists `['GET', 'HEAD', 'OPTIONS']`, the default methods `createCSRF` treats as safe (mint instead of verify). |
|
|
198
209
|
| `MULTIPART_STATUS` | const | `Readonly<Record<MultipartErrorCode, number>>` | Holds the HTTP status `createMultipart` renders for each `MultipartErrorCode`: `'limit'` is 413, `'malformed'` is 400, and `'rejected'` is 415. |
|
|
199
210
|
| `MULTIPART_ERROR_BRAND` | const | `unique symbol` | Holds the `Symbol.for` brand `MultipartError` carries so `isMultipartError` recognizes an instance across duplicate copies of this package — a registry symbol rather than a module-local `Symbol()`, which would mint an unequal symbol per copy. |
|
|
200
|
-
| `NODE_COMPRESSION_ENCODINGS` | const | `readonly Encoding[]` | Lists `['gzip', 'deflate']`, the content-codings `createNodeCompression` offers —
|
|
211
|
+
| `NODE_COMPRESSION_ENCODINGS` | const | `readonly Encoding[]` | Lists `['gzip', 'deflate']`, the content-codings `createNodeCompression` offers — the codecs of `node:zlib`, which every Node runtime bundles, so this face never feature-detects. |
|
|
201
212
|
| `DEFAULT_STATIC_INDEX` | const | `"index.html"` | Names `'index.html'`, `createStatic`'s default directory-index filename. |
|
|
202
213
|
| `DEFAULT_STATIC_FALLBACK_EXCLUDE` | const | `"/api"` | Names `'/api'`, `createStatic`'s `fallback: true` default excluded path prefix. |
|
|
203
214
|
| `DEFAULT_STATIC_DOTFILES` | const | `NonNullable<StaticOptions['dotfiles']>` | Names `'ignore'`, `createStatic`'s default policy for a path carrying a dotfile segment. |
|
|
@@ -209,51 +220,88 @@ const handle = compose<State>([boundary, security], async (_request, context) =>
|
|
|
209
220
|
| `DEFAULT_MULTIPART_TOTAL` | const | `52428800` | Holds `52_428_800`, `createMultipart`'s default combined request-body byte-size cap. |
|
|
210
221
|
| `MULTIPART_MAX_HEADER_BLOCK` | const | `16384` | Holds `16_384`, the maximum bytes a single multipart part's header block may occupy before it is malformed. |
|
|
211
222
|
| `MULTIPART_MAX_PREAMBLE` | const | `65536` | Holds `65_536`, the maximum bytes scanned before the first multipart boundary is found before it is malformed. |
|
|
223
|
+
| `MULTIPART_MAX_BOUNDARY` | const | `70` | Holds `70`, the maximum length of a multipart boundary, which RFC 2046 § 5.1.1 fixes. |
|
|
212
224
|
| `RESERVED_DEVICE_NAMES` | const | `ReadonlySet<string>` | Lists the Windows reserved device-name stems (CVE-2025-27210) — matched case-insensitively against the segment's stem (before its first `.`). |
|
|
213
225
|
| `EXTENSION_TYPES` | const | `Readonly<Record<string, string>>` | Holds the file-extension (lowercase, with leading `.`) → MIME type lookup table for static serving. |
|
|
214
226
|
|
|
227
|
+
### Contracts
|
|
228
|
+
|
|
229
|
+
| Name | Kind | Signature | Summary |
|
|
230
|
+
| ------------------------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
231
|
+
| `BOUNDARY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { expose?: boolean; report?: (...args: never[]) => unknown; }>>` | Admits `BoundaryOptions` whole for `createBoundary`: a boolean `expose` and a function `report`. |
|
|
232
|
+
| `TELEMETRY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ record: (...args: never[]) => unknown; } & {}>>` | Admits `TelemetryOptions` whole for `createTelemetry`: a required function `record`. |
|
|
233
|
+
| `COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; encodings?: readonly ("deflate" \| "gzip" \| "identity")[]; filter?: (...args: never[]) => unknown; }>>` | Admits `CompressionOptions` whole for `createCompression`: a non-negative finite `threshold`, an `encodings` array of `Encoding` literals, and a function `filter`. |
|
|
234
|
+
| `NODE_COMPRESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { threshold?: number; filter?: (...args: never[]) => unknown; }>>` | Admits `NodeCompressionOptions` whole for `createNodeCompression`: a non-negative finite `threshold` and a function `filter`. |
|
|
235
|
+
| `SECURITY_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { frame?: "DENY" \| "SAMEORIGIN" \| false; csp?: string \| false; referrer?: string \| false; permissions?: string \| false; coop?: string \| false; corp?: string \| false; cluster?: string \| false; coep?: string \| boolean; hsts?: string \| boolean; identifier?: false \| Readonly<{} & { trust?: boolean; }>; }>>` | Admits `SecurityOptions` whole for `createSecurity`: each header option is a string or `false`, `coep` and `hsts` are a string or a boolean, and `identifier` is `{ trust? }` or `false`. |
|
|
236
|
+
| `CORS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { origin?: string \| readonly string[]; methods?: readonly string[]; headers?: readonly string[]; }>>` | Admits `CORSOptions` whole for `createCORS`: `origin` is a string or a string array, and `methods` and `headers` are string arrays. |
|
|
237
|
+
| `DEADLINE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ ms: number; } & { status?: number; }>>` | Admits `DeadlineOptions` whole for `createDeadline`: an integer `ms` from 1 through 2147483647, the range `@orkestrel/timeout` enforces, and an integer `status` from 200 through 599. |
|
|
238
|
+
| `FORWARDED_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ proxies: number; } & {}> \| Readonly<{ trusted: readonly string[]; } & {}>>` | Admits `ForwardedOptions` whole for `createForwarded`: exactly one of an integer `proxies` of at least 1 or a `trusted` string array. |
|
|
239
|
+
| `ETAG_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { weak?: boolean; }>>` | Admits `ETagOptions` whole for `createETag`: a boolean `weak`. |
|
|
240
|
+
| `BEARER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ verify: (...args: never[]) => unknown; } & { header?: string; scheme?: string; challenge?: { readonly [k: string]: string; }; }>>` | Admits `BearerOptions` whole for `createBearer`: a required function `verify`, string `header` and `scheme`, and a `challenge` record of strings. |
|
|
241
|
+
| `LIMITER_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ max: number; window: number; } & { store?: Readonly<{ consume: (...args: never[]) => unknown; } & {}>; capacity?: number; key?: (...args: never[]) => unknown; message?: string; clock?: (...args: never[]) => unknown; policy?: boolean; evict?: (...args: never[]) => unknown; }>>` | Admits `LimiterOptions` whole for `createLimiter`: an integer `max` of at least 1, a positive finite `window`, an integer `capacity` of at least 1, and the declared functions; `store` is an implementation that declares the function `consume`. |
|
|
242
|
+
| `SESSION_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ transport: Readonly<{ read: (...args: never[]) => unknown; write: (...args: never[]) => unknown; clear: (...args: never[]) => unknown; } & {}>; } & { store?: Readonly<{ get: (...args: never[]) => unknown; set: (...args: never[]) => unknown; delete: (...args: never[]) => unknown; } & {}>; ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; create?: (...args: never[]) => unknown; mint?: (...args: never[]) => unknown; required?: boolean; clock?: (...args: never[]) => unknown; }>>` | Admits `SessionOptions` whole for `createSession`: positive finite `ttl` and `lifetime`, an integer `capacity` of at least 1, and the declared functions; `transport` is an implementation that declares the functions `read`, `write`, and `clear`, and `store` one that declares `get`, `set`, and `delete`. |
|
|
243
|
+
| `COOKIE_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: Readonly<{ sign: (...args: never[]) => unknown; verify: (...args: never[]) => unknown; } & {}>; } & { name?: string; cookie?: Readonly<{} & { path?: string; domain?: string; maxAge?: number; httpOnly?: boolean; secure?: boolean; sameSite?: "Lax" \| "None" \| "Strict"; }>; }>>` | Admits `CookieTransportOptions` whole for `createCookieTransport`: a string `name`, a required `signer` implementation that declares the functions `sign` and `verify`, and an owned `cookie` record of the six optional members `@orkestrel/server` declares: string `path` and `domain`, a finite number `maxAge` (a non-finite value writes `Max-Age=NaN` or `Max-Age=Infinity` into `Set-Cookie`), boolean `httpOnly` and `secure`, and a `sameSite` of `'Strict'`, `'Lax'`, or `'None'`. |
|
|
244
|
+
| `HEADER_TRANSPORT_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { header?: string; }>>` | Admits `HeaderTransportOptions` whole for `createHeaderTransport`: a string `header`. |
|
|
245
|
+
| `SESSION_LIMITS_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; }>>` | Admits `SessionLimits` whole for `createDatabaseSessionStore`: positive finite `ttl` and `lifetime`. |
|
|
246
|
+
| `MEMORY_SESSION_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { ttl?: number; lifetime?: number; capacity?: number; evict?: (...args: never[]) => unknown; }>>` | Admits `MemorySessionStoreOptions` whole for `createMemorySessionStore`: positive finite `ttl` and `lifetime`, an integer `capacity` of at least 1, and a function `evict`. |
|
|
247
|
+
| `MEMORY_LIMITER_STORE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { capacity?: number; evict?: (...args: never[]) => unknown; }>>` | Admits `MemoryLimiterStoreOptions` whole for `createMemoryLimiterStore`: an integer `capacity` of at least 1 and a function `evict`. |
|
|
248
|
+
| `CSRF_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ signer: Readonly<{ sign: (...args: never[]) => unknown; verify: (...args: never[]) => unknown; } & {}>; } & { cookie?: string; header?: string; field?: string; safe?: readonly string[]; }>>` | Admits `CSRFOptions` whole for `createCSRF`: a required `signer` implementation that declares the functions `sign` and `verify`, string `cookie`, `header`, and `field`, and a `safe` string array. |
|
|
249
|
+
| `SCOPE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ paths: string \| readonly string[]; handler: (...args: never[]) => unknown; } & {}>>` | Admits the arguments of `only` and `except` whole: `paths` is a string or a string array, and `handler` is a function. |
|
|
250
|
+
| `ASSET_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ source: Readonly<{ read: (...args: never[]) => unknown; } & {}>; } & { store?: Readonly<{ get: (...args: never[]) => unknown; set: (...args: never[]) => unknown; delete: (...args: never[]) => unknown; } & {}>; }>>` | Admits `AssetOptions` whole for `createAssets`: `source` is an implementation that declares the function `read`, and `store` one that declares `get`, `set`, and `delete`. |
|
|
251
|
+
| `STATIC_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ root: string; } & { prefix?: string; index?: string; dotfiles?: "allow" \| "deny" \| "ignore"; cache?: number; etag?: boolean; fallback?: boolean \| Readonly<{} & { exclude?: string; }>; }>>` | Admits `StaticOptions` whole for `createStatic`: a non-empty string `root`, a non-negative finite `cache`, a `dotfiles` literal, and a `fallback` that is a boolean or `{ exclude? }`. |
|
|
252
|
+
| `MULTIPART_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{} & { limits?: Readonly<{} & { file?: Readonly<{} & { size?: number; count?: number; }>; field?: Readonly<{} & { size?: number; count?: number; }>; total?: number; }>; allowed?: readonly string[]; directory?: string; }>>` | Admits `MultipartOptions` whole for `createMultipart`: non-negative finite sizes and totals, non-negative integer counts, a string array `allowed`, and a string `directory`. |
|
|
253
|
+
| `UPLOADED_FILE_CONTRACT` | const | `import("@orkestrel/contract").ContractInterface<Readonly<{ field: string; name: string; size: number; mime: string; validated: boolean; status: "moved" \| "staged"; path: string; } & {}>>` | Admits one `UploadedFile` whole for `createUploadedFile`: string `field`, `name`, `mime`, and `path`, a non-negative finite `size`, a boolean `validated`, and a `status` literal. |
|
|
254
|
+
|
|
215
255
|
### Shapers
|
|
216
256
|
|
|
217
257
|
| Name | Kind | Signature | Summary |
|
|
218
258
|
| ---------------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
219
259
|
| `sessionColumns` | const | `{ id: import("@orkestrel/contract").StringShape; session: import("@orkestrel/contract").JSONShape; seen: import("@orkestrel/contract").NumberShape; created: import("@orkestrel/contract").NumberShape; }` | Holds the `@orkestrel/database` column shape for a `SessionRow` table. Pass it as-is to `createDatabase({ tables: { sessions: sessionColumns } })` so an app declaring a durable session table never hand-writes the shape. |
|
|
220
260
|
|
|
221
|
-
### Helpers —
|
|
222
|
-
|
|
223
|
-
| Name
|
|
224
|
-
|
|
|
225
|
-
| `resolveKey`
|
|
226
|
-
| `renderChallenge`
|
|
227
|
-
| `resolveOptInHeader`
|
|
228
|
-
| `buildRetryAfter`
|
|
229
|
-
| `buildRateLimitField`
|
|
230
|
-
| `buildRateLimitPolicyField`
|
|
231
|
-
| `matchesTrustedEntry`
|
|
232
|
-
| `resolveForwardedFor`
|
|
233
|
-
| `
|
|
234
|
-
| `
|
|
235
|
-
| `
|
|
236
|
-
| `
|
|
237
|
-
| `
|
|
238
|
-
| `
|
|
239
|
-
| `
|
|
240
|
-
| `
|
|
241
|
-
| `
|
|
242
|
-
| `
|
|
243
|
-
| `
|
|
244
|
-
| `
|
|
245
|
-
| `
|
|
246
|
-
|
|
247
|
-
|
|
261
|
+
### Helpers — web-standard
|
|
262
|
+
|
|
263
|
+
| Name | Kind | Signature | Summary |
|
|
264
|
+
| -------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
265
|
+
| `resolveKey` | function | `(state: BearerState<unknown> & ClientState, connection: Connection) => string` | Derives `createLimiter`'s default rate-limit bucket key from a request's resolved identity facts. |
|
|
266
|
+
| `renderChallenge` | function | `(scheme: string, parameters?: Readonly<Record<string, string>>, door?: string) => string` | Renders a `WWW-Authenticate` challenge as the scheme alone, or the scheme followed by quoted auth-params in the record's own key order. |
|
|
267
|
+
| `resolveOptInHeader` | function | `(value: string \| boolean \| undefined, fallback: string) => string \| undefined` | Resolves an opt-in, value-bearing security header — `string \| boolean` (off by default, `true` uses the secure default), the shape `createSecurity`'s `coep`/`hsts` options use, distinct from the plain value-or-`false` shape `resolveSecurityHeader` (the peer substrate) handles. |
|
|
268
|
+
| `buildRetryAfter` | function | `(expiry: number, now: number) => string` | Builds the `Retry-After` header value — whole seconds until a window reset, floored at a minimum of `1`. |
|
|
269
|
+
| `buildRateLimitField` | function | `(remaining: number, expiry: number, now: number) => string` | Builds the draft `RateLimit` structured header field — emitted only when `createLimiter`'s `policy` option is `true`. |
|
|
270
|
+
| `buildRateLimitPolicyField` | function | `(max: number, window: number) => string` | Builds the draft `RateLimit-Policy` structured header field — emitted only when `createLimiter`'s `policy` option is `true`. |
|
|
271
|
+
| `matchesTrustedEntry` | function | `(address: string, entry: string) => boolean` | Checks whether a candidate address is a trusted-hop match — an exact match, or a prefix-CIDR match for IPv4 (`/8`–`/32`), with an IPv4-mapped address compared by its embedded IPv4. An IPv6 entry matches by exact string only — there is no IPv6 CIDR support. |
|
|
272
|
+
| `resolveForwardedFor` | function | `(header: string \| undefined, trust: ForwardedOptions, peer: string \| undefined) => string \| undefined` | Resolves the client address from `X-Forwarded-For` and the socket peer — `createForwarded`'s core algorithm. |
|
|
273
|
+
| `matchesScope` | function | `(patterns: readonly CompiledPath[], pathname: string) => boolean` | Checks whether a request pathname matches any compiled scope pattern — the test `only` and `except` apply, through the router's own `matchPath`. |
|
|
274
|
+
| `detectEncodings` | function | `(candidates: readonly Encoding[]) => readonly Encoding[]` | Feature-detects which of `candidates` the runtime's `CompressionStream` actually supports — `createCompression`'s construction-time intersection. |
|
|
275
|
+
| `compressBytes` | function | `(bytes: Uint8Array<ArrayBuffer>, encoding: Exclude<Encoding, 'identity'>) => Promise<Uint8Array<ArrayBuffer>>` | Compresses bytes with the host-independent `CompressionStream` primitive. |
|
|
276
|
+
| `matchesUnbufferableResponse` | function | `(method: string, response: Response, skipHeader: string) => boolean` | Checks whether a response must skip the compression and ETag buffering pipeline — the shared cheap-skip predicate both batteries apply before ever touching `response.arrayBuffer()`, true for a `HEAD` request, a `204`/`304` or otherwise bodyless response, an `event-stream` response, and a response already carrying the header the caller is about to set. |
|
|
277
|
+
| `matchesUntransformableResponse` | function | `(response: Response) => boolean` | Checks whether a response must keep its content coding — a `206 Partial Content`, whose `Content-Range` counts bytes of the identity representation, or a response whose `Cache-Control` carries the `no-transform` directive (RFC 9111 § 5.2.2.6). |
|
|
278
|
+
| `isCompressionNegotiated` | function | `(encoding: Encoding \| undefined) => encoding is Exclude<Encoding, 'identity'>` | Checks whether a negotiated `Accept-Encoding` outcome is worth acting on — `createCompression`'s negotiation-eligibility half of the skip list. |
|
|
279
|
+
| `rebuildResponse` | function | `(body: ConstructorParameters<typeof Response>[0], response: Response, headers?: ConstructorParameters<typeof Headers>[0]) => Response` | Rebuilds a `Response` around a replacement body while preserving its status/statusText — the buffered-response reconstruction shared by the compression and ETag batteries after they have consumed `response.arrayBuffer()`. |
|
|
280
|
+
| `compressResponse` | function | `(request: Request, context: MiddlewareContext<unknown>, response: Response, options: CompressResponseOptions) => Promise<Response>` | Runs the shared negotiate → skip → threshold → compress → header-set skeleton `createCompression` and `createNodeCompression` compose — response-body compression over a caller-supplied set of feature-detected codings. |
|
|
281
|
+
| `transferSessionState` | function | `(from: SessionInterface, to: SessionInterface) => void` | Copies every entry of one session's `state` into another — the regenerate state-carry `createSession`'s `control.regenerate()` applies. |
|
|
282
|
+
| `matchesSessionState` | function | `(before: ReadonlyMap<string, unknown>, after: ReadonlyMap<string, unknown>) => boolean` | Checks whether two session states hold the same keys, each bound to the same value by `Object.is` — the test `createSession` applies to decide whether a handler wrote to a session. |
|
|
283
|
+
| `generateNonce` | function | `() => string` | Generates a random nonce: 32 bytes from the platform's cryptographic source, as 43 base64url characters — the nonce `createCSRF` keeps in its cookie and a CSRF token's random part. |
|
|
284
|
+
| `signCSRFToken` | function | `(signer: SignerInterface, binding: string) => Promise<string>` | Signs a CSRF token bound to `binding`: `random.signature`, where `signature` is the signer's HMAC over `CSRF_LABEL`, `binding`, and `random`, so the token carries no form of the binding. |
|
|
285
|
+
| `verifyCSRFToken` | function | `(signer: SignerInterface, binding: string, token: string) => Promise<boolean>` | Verifies a CSRF token against `binding`: the token's random part must match `CSRF_NONCE_PATTERN`, and its signature must be the signer's HMAC over `CSRF_LABEL`, `binding`, and that random part, under any held key. |
|
|
286
|
+
| `sessionExpired` | function | `(cursors: SessionCursors, now: number, limits: SessionLimits) => boolean` | Checks whether a session has aged past its idle timeout or absolute lifetime as of `now` — the pure expiry predicate `MemorySessionStore` delegates to. |
|
|
287
|
+
| `snapshotSession` | function | `(session: SessionInterface) => SessionSnapshot` | Snapshots a session's `state` into a plain, serializable record — the projection a durable store's `set` writes to disk. |
|
|
288
|
+
| `admitOptions` | function | `<T>(door: string, contract: ContractInterface<T>, value: unknown) => void` | Admits an options bag whole against its compiled contract through the contract's `own`, refusing a missing required key, an undeclared key, a value outside a declared range, and an implementation key that lacks a member its `interfaceShape` declares. |
|
|
289
|
+
| `isPreflight` | function | `(method: string, headers: Headers) => boolean` | Determines whether a request is a CORS preflight — an `OPTIONS` request carrying an `Access-Control-Request-Method` header. |
|
|
290
|
+
| `buildClient` | function | `(ip: string \| undefined) => Client` | Builds the `Client` slice `createForwarded` stashes, from the resolved client IP — a leaf shaping helper. |
|
|
291
|
+
| `equalsConstantTime` | function | `(a: string, b: string) => boolean` | Compares two strings in constant time when their lengths match, so a per-character mismatch never changes how long the comparison takes. |
|
|
292
|
+
|
|
293
|
+
### Validators — web-standard
|
|
248
294
|
|
|
249
295
|
Each guard in the following table is total: it accepts any input, returns `false` off-shape, and never throws.
|
|
250
296
|
|
|
251
|
-
| Name | Kind | Signature | Summary
|
|
252
|
-
| ------------------ | -------- | ------------------------------------------------------ |
|
|
253
|
-
| `isSession` | function | `(value: unknown) => value is SessionInterface` | Determines whether a value implements `SessionInterface` — a total structural guard: an `id` string, a `state` `Map`, and the `set`, `delete`, and `clear` mutators. Prototype-agnostic — accepts a plain object, a null-prototype object, and a class instance (a real `Session`), because a restored or stored session is routinely a class instance rather than a literal.
|
|
254
|
-
| `isSessionControl` | function | `(value: unknown) => value is SessionControlInterface` | Determines whether a value implements `SessionControlInterface` — a total structural guard: callable `regenerate` and `destroy`.
|
|
255
|
-
| `isMultipartFile` | function | `(value: unknown) => value is MultipartFile` | Determines whether a value is one staged `MultipartFile` record — a total structural guard checking every required field's shape.
|
|
256
|
-
| `isMultipartBody` | function | `(value: unknown) => value is MultipartBody` | Determines whether a value implements `MultipartBody` — a total structural guard: `files` keyed by field name to arrays of `MultipartFile`, and a `fields` string record.
|
|
297
|
+
| Name | Kind | Signature | Summary |
|
|
298
|
+
| ------------------ | -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
299
|
+
| `isSession` | function | `(value: unknown) => value is SessionInterface` | Determines whether a value implements `SessionInterface` — a total structural guard: an `id` string, a `state` `Map`, and the `set`, `delete`, and `clear` mutators. Prototype-agnostic — accepts a plain object, a null-prototype object, and a class instance (a real `Session`), because a restored or stored session is routinely a class instance rather than a literal. |
|
|
300
|
+
| `isSessionControl` | function | `(value: unknown) => value is SessionControlInterface` | Determines whether a value implements `SessionControlInterface` — a total structural guard over every declared member: boolean `destroyed` and `fresh`, a `successor` that is `undefined` or satisfies `isSession`, and callable `regenerate` and `destroy`. Prototype-agnostic — accepts a plain object, a callable object, and a class instance (a real `SessionControl`), and ignores unknown members. A value missing a declared member answers false, and so does a member read that throws, as on a revoked proxy. |
|
|
301
|
+
| `isMultipartFile` | function | `(value: unknown) => value is MultipartFile` | Determines whether a value is one staged `MultipartFile` record — a total structural guard checking every required field's shape. |
|
|
302
|
+
| `isMultipartBody` | function | `(value: unknown) => value is MultipartBody` | Determines whether a value implements `MultipartBody` — a total structural guard: `files` keyed by field name to arrays of `MultipartFile`, and a `fields` string record. |
|
|
303
|
+
|
|
304
|
+
Before 0.0.35, `isSessionControl` refused every class instance, a real `SessionControl` included, and accepted any value with callable `regenerate` and `destroy`. From 0.0.35, it also requires `destroyed`, `successor`, and `fresh` at their declared types, so a value that carries only the two methods answers false.
|
|
257
305
|
|
|
258
306
|
### Helpers — node
|
|
259
307
|
|
|
@@ -270,16 +318,15 @@ Each guard in the following table is total: it accepts any input, returns `false
|
|
|
270
318
|
| `computeFileETag` | function | `(size: number, mtimeMs: number) => string` | Computes a static file's weak ETag from its size and modification time. |
|
|
271
319
|
| `detectMIME` | function | `(head: Uint8Array) => string \| undefined` | Sniffs a MIME type from a file's leading bytes against a small magic-byte table (jpeg, png, gif87a/89a, webp, pdf, zip). |
|
|
272
320
|
| `matchesBytes` | function | `(bytes: Uint8Array, signature: readonly number[], offset?: number) => boolean` | Checks whether `bytes` contains `signature` at the requested offset. |
|
|
273
|
-
| `compressNodeBytes` | function | `(bytes: Uint8Array<ArrayBuffer>, encoding: Exclude<Encoding, 'identity'>) => Promise<Uint8Array<ArrayBuffer>>` | Compresses response bytes with
|
|
321
|
+
| `compressNodeBytes` | function | `(bytes: Uint8Array<ArrayBuffer>, encoding: Exclude<Encoding, 'identity'>) => Promise<Uint8Array<ArrayBuffer>>` | Compresses response bytes with the gzip or deflate codec of `node:zlib`, which every Node runtime bundles. |
|
|
274
322
|
| `extractMultipartBoundary` | function | `(contentType: string \| null) => string \| undefined` | Extracts the `boundary` parameter from a `Content-Type` header, or `undefined` when the request is not `multipart/form-data`. |
|
|
275
323
|
| `parsePartHeaders` | function | `(block: string) => PartHeaders` | Parses one multipart part's raw header block into its `name` (from `Content-Disposition`), optional `filename`, and optional `Content-Type`. |
|
|
276
324
|
| `resolveMultipartLimits` | function | `(limits: MultipartLimitsInput \| undefined) => MultipartLimits` | Resolves `createMultipart`'s effective `MultipartLimits`, applying every documented default to an omitted leaf. |
|
|
277
|
-
| `createUploadedFile` | function | `(input: UploadedFile) => UploadedFile` | Builds a frozen `UploadedFile` record. |
|
|
278
325
|
| `streamFile` | function | `(source: string \| FileHandle, range?: ByteRange) => ReadableStream<Uint8Array>` | Adapts a `node:fs` read stream over a file path (or an already-open `FileHandle`) into a DOM-compatible `ReadableStream<Uint8Array>` — the single shared node↔web stream bridge every static-file and uploaded-file response body routes through. |
|
|
279
326
|
| `streamUploadedFile` | function | `(file: UploadedFile) => ReadableStream<Uint8Array>` | Opens a staged/moved uploaded file as a web `ReadableStream`. |
|
|
280
327
|
| `readUploadedFile` | function | `(file: UploadedFile) => Promise<Uint8Array>` | Reads a staged/moved uploaded file's full contents into memory. |
|
|
281
328
|
| `moveUploadedFile` | function | `(file: UploadedFile, destination: string) => Promise<UploadedFile>` | Moves a staged uploaded file to its final `destination`. |
|
|
282
|
-
| `unlinkStagedFiles` | function | `(body: MultipartBody) => Promise<void>` | Attempts to unlink every still-`'staged'` file in a parsed `MultipartBody` — the
|
|
329
|
+
| `unlinkStagedFiles` | function | `(body: MultipartBody) => Promise<void>` | Attempts to unlink every still-`'staged'` file in a parsed `MultipartBody` — the cleanup `createMultipart` runs when its downstream handler settles, mirroring `parseMultipartRequest`'s own cleanup pattern (a missing file is already gone; failures are swallowed). |
|
|
283
330
|
|
|
284
331
|
### Parsers — node
|
|
285
332
|
|
|
@@ -305,6 +352,7 @@ omission is asserted rather than assumed, and adding it to the barrel would turn
|
|
|
305
352
|
|
|
306
353
|
| Name | Kind | Signature | Summary |
|
|
307
354
|
| ---------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
355
|
+
| `createUploadedFile` | function | `(input: UploadedFile) => UploadedFile` | Builds a frozen `UploadedFile` record. |
|
|
308
356
|
| `createCookieTransport` | function | `(options: CookieTransportOptions) => SessionTransportInterface` | Creates a signed-cookie `SessionTransportInterface` — the session id travels as a `signToken`-signed cookie value. |
|
|
309
357
|
| `createHeaderTransport` | function | `(options?: HeaderTransportOptions) => SessionTransportInterface` | Creates a bare-header `SessionTransportInterface` — the session id travels verbatim in a request/response header. |
|
|
310
358
|
| `createMemorySessionStore` | function | `<S extends SessionInterface>(options?: MemorySessionStoreOptions) => SessionStoreInterface<S>` | Creates the default in-process `SessionStoreInterface` — a `Map`-backed store enforcing an idle timeout and an absolute lifetime. |
|
|
@@ -357,7 +405,10 @@ the write path.
|
|
|
357
405
|
`regenerate` is the OWASP anti-fixation primitive (rotate the id, keep the
|
|
358
406
|
state); `destroy` ends the session outright. Both record intent
|
|
359
407
|
synchronously; the store I/O and transport write happen after `next()`
|
|
360
|
-
returns (`destroy` supersedes a prior `regenerate`).
|
|
408
|
+
returns (`destroy` supersedes a prior `regenerate`). `fresh` is `true` for a
|
|
409
|
+
session minted on this request, which the client holds no credential for
|
|
410
|
+
until a write or a `regenerate` persists it; `createCSRF` reads it to bind a
|
|
411
|
+
token to the battery's nonce instead.
|
|
361
412
|
|
|
362
413
|
| Method | Returns | Summary |
|
|
363
414
|
| ------------ | ------- | --------------------------------------------------------------------------------- |
|
|
@@ -406,7 +457,7 @@ returning onion makes "before send" automatic).
|
|
|
406
457
|
|
|
407
458
|
## Contract
|
|
408
459
|
|
|
409
|
-
These invariants hold across `src/
|
|
460
|
+
These invariants hold across `src/server` ↔ `middleware.md`.
|
|
410
461
|
|
|
411
462
|
1. **Guide ↔ source bijection.** Every `function` / `class` / `interface` /
|
|
412
463
|
`type` / `const` row in the `## Surface` tables is a real export of its
|
|
@@ -419,40 +470,88 @@ These invariants hold across `src/core` / `src/server` ↔ `middleware.md`.
|
|
|
419
470
|
|
|
420
471
|
### The ordering doctrine
|
|
421
472
|
|
|
422
|
-
The canonical onion, outermost first,
|
|
473
|
+
The canonical onion, outermost first, is `createTelemetry`, `createNodeCompression`,
|
|
474
|
+
`createSecurity`, `createCORS`, `createBoundary`, `createDeadline`, `createForwarded`,
|
|
475
|
+
`createETag`, `createBearer`, `createLimiter`, `createBody`, `createSession`, and `createCSRF`.
|
|
476
|
+
Before 0.0.35, the canonical onion mounted `createCompression` where it mounts
|
|
477
|
+
`createNodeCompression`, and placed `createSecurity` and `createCORS` inside `createBoundary` and
|
|
478
|
+
`createDeadline`, so an error the boundary rendered from a throw, and the deadline's answer,
|
|
479
|
+
carried no security headers and no `Vary: Origin`. Each item names a position and the failure it
|
|
423
480
|
prevents:
|
|
424
481
|
|
|
425
482
|
3. **`createTelemetry` is outermost.** It sees the mapped status (after
|
|
426
483
|
`createBoundary` renders) and measures honest wall-clock duration —
|
|
427
484
|
anything mounted inside it would be excluded from the timing.
|
|
428
|
-
4.
|
|
485
|
+
4. **Compression sits outside `createBoundary`.** An error `Response`
|
|
429
486
|
the boundary renders from a caught throw still passes through
|
|
430
487
|
compression — mount it inside instead and error bodies ship uncompressed.
|
|
488
|
+
Compression leaves a `206` response and a response whose `Cache-Control` carries
|
|
489
|
+
`no-transform` identity-coded (`matchesUntransformableResponse`), because the
|
|
490
|
+
`Content-Range` of a `206` counts bytes of the identity representation; before
|
|
491
|
+
0.0.35 it compressed both. Mount `createNodeCompression`, as the canonical
|
|
492
|
+
onion does, and mount `createCompression` only on a host without
|
|
493
|
+
`node:zlib`: in the kernel readings of 2026-11-16 on middleware 0.0.33 and
|
|
494
|
+
Node 22.23.5, gzip through `CompressionStream` took 542 µs per 1 KiB
|
|
495
|
+
response against 327 µs through `node:zlib`, and 815 µs against 617 µs at
|
|
496
|
+
64 KiB.
|
|
431
497
|
5. **`createBoundary` is the renderer.** Everything mounted beneath it may
|
|
432
498
|
throw `HTTPError` (or anything else) and have it mapped to a `Response`;
|
|
433
499
|
nothing below it needs its own try/catch.
|
|
434
|
-
6. **`createDeadline` sits inside the boundary.** A
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
500
|
+
6. **`createDeadline` sits inside the boundary.** A deadline that fires calls
|
|
501
|
+
`context.abort(reason)`, answers `status` with no body, and discards
|
|
502
|
+
whatever the downstream returns or throws after that. Inside the boundary,
|
|
503
|
+
a throw a handler raises on the aborted `signal` stops at the deadline;
|
|
504
|
+
mounted outside, the boundary beneath it reports that throw as a fault. The
|
|
505
|
+
battery builds no `Request`, so it composes with `createBody` in either
|
|
506
|
+
order.
|
|
507
|
+
7. **`createSecurity` sits outside `createBoundary` and `createDeadline`.**
|
|
508
|
+
Every response then carries the security headers: a returned response, a
|
|
509
|
+
redirect, an error the boundary renders from a throw, and the deadline's
|
|
510
|
+
answer. Mounted inside the boundary, `createSecurity`'s `next()` never
|
|
511
|
+
resolves for a throw beneath it, so the rendered error ships without the
|
|
512
|
+
headers.
|
|
513
|
+
8. **`createCORS` sits outside `createBoundary` and `createDeadline`.** In
|
|
514
|
+
list mode every response then carries `Vary: Origin`, an error the
|
|
515
|
+
boundary renders from a throw and the deadline's answer included, so a
|
|
516
|
+
shared cache never serves one origin's answer to another. Its preflight
|
|
517
|
+
answer runs before the terminal `Dispatcher.handle` sees the `OPTIONS`
|
|
518
|
+
request, so it claims a preflight before the dispatcher's automatic
|
|
519
|
+
`OPTIONS`.
|
|
450
520
|
9. **`createForwarded` resolves client facts before anything keys off
|
|
451
521
|
them.** `createLimiter`'s default key and any session/telemetry logic
|
|
452
|
-
that wants `ClientState.client.ip` must run downstream of it.
|
|
453
|
-
|
|
522
|
+
that wants `ClientState.client.ip` must run downstream of it. It reads
|
|
523
|
+
`X-Forwarded-For` only and ignores a `Forwarded` header. With
|
|
524
|
+
`proxies: N`, each of the `N` proxies appends one hop, and the client is
|
|
525
|
+
the hop at index `length − N`: `proxies: 1` behind one appending proxy
|
|
526
|
+
resolves the rightmost hop, the address that proxy saw. A header with fewer
|
|
527
|
+
than `N` hops resolves the socket peer. `proxies` fits only when every
|
|
528
|
+
request arrives through exactly `N` proxies, because a request that reaches
|
|
529
|
+
the server directly names its own client. With `trusted`, the walk starts
|
|
530
|
+
at the socket peer, `context.connection.ip`, and moves left through every
|
|
531
|
+
address the roster matches; the first address outside the roster is the
|
|
532
|
+
client. An untrusted socket peer is the client, whatever its header says,
|
|
533
|
+
and when the peer and every hop match, the leftmost hop is the client.
|
|
534
|
+
The roster compares an IPv4-mapped address (`::ffff:10.0.0.6`, which Node
|
|
535
|
+
reports for an IPv4 client on a dual-stack listener) by its embedded IPv4,
|
|
536
|
+
and reads an IPv4 address only as four decimal octets from 0 to 255, so a
|
|
537
|
+
hop such as `0x0a.0.0.1` matches no IPv4 entry. The resolved address is not
|
|
538
|
+
validated: it is the peer or the hop as written, so a malformed hop, a hop
|
|
539
|
+
with a port (`198.51.100.66:4711`), or an IPv4-mapped hop resolves
|
|
540
|
+
unchanged. Before 0.0.35, `proxies: 1` resolved the hop left of the
|
|
541
|
+
rightmost one, and `trusted` began its walk at the rightmost hop instead of
|
|
542
|
+
the socket peer.
|
|
543
|
+
10. **`createETag` sits inside compression.** The hash is computed
|
|
454
544
|
over the uncompressed representation — hashing the compressed bytes
|
|
455
545
|
would break revalidation the instant the negotiated coding changes.
|
|
546
|
+
Behind compression, a strong tag on a coded body gains `W/`, because one
|
|
547
|
+
tag across two codings is no strong validator (RFC 9110 § 8.8.1), and the
|
|
548
|
+
weak tag still revalidates. A `304` carries the tag and the `Vary` header
|
|
549
|
+
that the `200` response would have carried. The `304` that `createETag` answers states the
|
|
550
|
+
length of the `200` body it stands for, and compression drops that length
|
|
551
|
+
from a `304` whose `200` it would code. Before 0.0.35, a coded body kept
|
|
552
|
+
its strong tag, a `304` passed compression with the strong tag and no
|
|
553
|
+
`Vary: Accept-Encoding`, and the `304` that `createETag` answered carried
|
|
554
|
+
no `Content-Length`.
|
|
456
555
|
11. **`createBearer` sits before `createLimiter`.** The limiter's default key
|
|
457
556
|
derivation prefers a string `BearerState.token` (the `token:<value>` idiom)
|
|
458
557
|
over a client-IP fallback — bearer must have already stashed it. An object
|
|
@@ -462,24 +561,30 @@ prevents:
|
|
|
462
561
|
cached `context.body()` already resolved.
|
|
463
562
|
13. **`createSession` sits before `createCSRF`.** CSRF's session-binding —
|
|
464
563
|
the security acceptance bar's CSRF item — requires `context.state.session`
|
|
465
|
-
to already be stashed.
|
|
564
|
+
and `context.state.control` to already be stashed.
|
|
466
565
|
|
|
467
566
|
### The security acceptance bar, as documented behavior
|
|
468
567
|
|
|
469
|
-
14. **CORS.** `Vary: Origin` is merged
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
568
|
+
14. **CORS.** In list mode `Vary: Origin` is merged on every response and
|
|
569
|
+
preflight, from an allowed origin, a disallowed origin, or no `Origin`
|
|
570
|
+
alike, and never in `'*'` wildcard or fixed-string mode. A preflight from a
|
|
571
|
+
disallowed origin, or with no `Origin`, answers `204` with `Vary: Origin`
|
|
572
|
+
and no `Access-Control-*` header. The literal `Origin: null` is never
|
|
573
|
+
reflected even when the string `'null'` is allow-listed. Before 0.0.35,
|
|
574
|
+
list mode merged `Vary: Origin` only for an allowed origin, every preflight
|
|
575
|
+
carried `Access-Control-Allow-Methods` and `Access-Control-Allow-Headers`,
|
|
576
|
+
and the battery and its options were named `createCors` and `CorsOptions`.
|
|
577
|
+
15. **Headers.** A malformed `X-Request-ID` (off-charset, oversize, or
|
|
473
578
|
CRLF-bearing) is never echoed — `createSecurity` mints a fresh
|
|
474
579
|
`crypto.randomUUID()` instead; a custom `csp` string replaces the
|
|
475
580
|
default wholesale (never merges); `X-Content-Type-Options: nosniff` is
|
|
476
581
|
unconditional, with no opt-out.
|
|
477
582
|
16. **Bearer.** `createBearer` returns a `401` for a missing, wrong-scheme, or empty token
|
|
478
583
|
and for a credential `verify` refuses, and a throw from `verify` propagates
|
|
479
|
-
unchanged. With `verify: (token) => verifyToken(token,
|
|
480
|
-
total over garbage, tampered,
|
|
481
|
-
renders `401`, never a crash;
|
|
482
|
-
`
|
|
584
|
+
unchanged. With `verify: (token) => verifyToken(token, signer)`, `verifyToken` is
|
|
585
|
+
total over garbage, tampered, or expired input — every failure
|
|
586
|
+
renders `401`, never a crash; the signer that the `createSigner` function of
|
|
587
|
+
`@orkestrel/server` returns compares signature bytes only through `timingSafeEqual`. The `401` is a returned response, so each outer
|
|
483
588
|
battery decorates it and `createBoundary`'s `report` never sees it; read
|
|
484
589
|
refusals from `createTelemetry`'s status.
|
|
485
590
|
17. **Limiter.** The key derivation never reads `X-Forwarded-For` itself (only
|
|
@@ -497,15 +602,26 @@ prevents:
|
|
|
497
602
|
`prototype` scrub are the substrate's own `readBody` behavior
|
|
498
603
|
(`ServerOptions.limit`) — this battery only drives the cache eagerly and
|
|
499
604
|
maps its outcomes.
|
|
500
|
-
19. **Session.**
|
|
605
|
+
19. **Session.** `createSession` stores a session, and writes its
|
|
606
|
+
credential, only after a handler writes to it or regenerates it. A write
|
|
607
|
+
is a `set`, `delete`, or `clear` that leaves the state holding other keys,
|
|
608
|
+
or other values by `Object.is`, than it held when the handler started; a
|
|
609
|
+
`set` of the value a key already holds is none, so replace a value rather
|
|
610
|
+
than changing it in place when the store is durable. A request with no
|
|
611
|
+
credential gets a session with `control.fresh` true, and when the handler
|
|
612
|
+
writes nothing, the store and the response carry no trace of it: a flood
|
|
613
|
+
of such requests leaves every written session in place. Since 0.0.35 the
|
|
614
|
+
session cookie first appears on the response to the first write, where
|
|
615
|
+
earlier releases set it on the first response. The default `MemorySessionStore` enforces both an idle
|
|
501
616
|
timeout (`ttl`, lazy eviction on `get`) and an absolute lifetime
|
|
502
617
|
(`lifetime`, evicting even a continuously-touched session — `created`
|
|
503
618
|
is stamped once at first `set` and preserved across every later
|
|
504
619
|
re-persist); it is also capacity-capped (`capacity`, default
|
|
505
|
-
`DEFAULT_SESSION_CAPACITY`) and evicts the least
|
|
506
|
-
every `set`
|
|
507
|
-
|
|
508
|
-
|
|
620
|
+
`DEFAULT_SESSION_CAPACITY`) and evicts the least recently used id —
|
|
621
|
+
every `set` and every live `get` refreshes recency — in time that does
|
|
622
|
+
not grow with the store's size, invoking the optional
|
|
623
|
+
`evict` sink (throw-isolated) on a capacity eviction or an expired read,
|
|
624
|
+
but never for an explicit `delete`; `control.regenerate()` rotates the id while carrying the
|
|
509
625
|
session's `state` over and invalidating the old id; a signed cookie
|
|
510
626
|
transport inherits the full substrate injection-hardening matrix
|
|
511
627
|
(`__Host-` spoof rejection, `Domain`/`Path` injection throws,
|
|
@@ -514,13 +630,36 @@ prevents:
|
|
|
514
630
|
answers `404` when `required` is set and no session resolves or mints, and
|
|
515
631
|
a consumer ending a session on `DELETE` mounts its own handler over
|
|
516
632
|
`control.destroy()`.
|
|
517
|
-
20. **CSRF.**
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
633
|
+
20. **CSRF.** A token is `random.signature`, where `signature` is the
|
|
634
|
+
signer's HMAC over `CSRF_LABEL`, a binding, and `random`
|
|
635
|
+
(`signCSRFToken`), OWASP's signed double submit; it carries no form of the
|
|
636
|
+
binding. While the client holds a session (`state.session` with
|
|
637
|
+
`control.fresh` not true), the binding is the session id and the battery
|
|
638
|
+
writes no cookie, so a token minted under session A is `403` under
|
|
639
|
+
session B, and a nonce-bound token is `403` beside a session even with its
|
|
640
|
+
nonce cookie. While it holds none, the binding is the battery's own nonce:
|
|
641
|
+
a safe request without a valid nonce cookie mints one and sets it
|
|
642
|
+
HttpOnly, `SameSite=Lax`, and `Path=/` under `cookie`. Every request that
|
|
643
|
+
passes, safe or mutating, stashes a fresh token bound to the binding it
|
|
644
|
+
arrived with on `state.csrf`, so every tab's token verifies while the
|
|
645
|
+
session or the nonce holds. A mutating request submits its token in
|
|
646
|
+
`header`, or in `field` of an `application/json` or
|
|
647
|
+
`application/x-www-form-urlencoded` body; the battery reads no other body,
|
|
648
|
+
so a multipart form sends its token in the header, and its stream stays
|
|
649
|
+
unread for `createMultipart`. The token format changed in 0.0.35: a token
|
|
650
|
+
an earlier release issued stops verifying at the upgrade, so a page
|
|
651
|
+
rendered before it must reload before its next write. Before 0.0.35, the
|
|
652
|
+
`signToken` function signed the session id, or a random value without a
|
|
653
|
+
session, into the token, and every safe response wrote that token into a
|
|
654
|
+
script-readable cookie named by the `cookie` option, which a mutating
|
|
655
|
+
request's token had to equal. A handler that
|
|
656
|
+
starts a session (the first write to a fresh one), regenerates it, or
|
|
657
|
+
destroys it changes the binding: `state.csrf` in that handler holds a
|
|
658
|
+
token bound to the binding the request arrived with, and tokens minted
|
|
659
|
+
earlier stop verifying under the new one. Such a handler answers with a
|
|
660
|
+
redirect; § CSRF: redirect after a session change states the contract.
|
|
661
|
+
Before 0.0.35, the battery re-minted the token for a regenerated session,
|
|
662
|
+
and cleared it for a destroyed one, on the handler's own response.
|
|
524
663
|
21. **Static.** Every served response is opened as a `FileHandle` and its
|
|
525
664
|
headers (`Content-Length`/`ETag`) are computed from that same handle's
|
|
526
665
|
`fstat` — the bytes `streamFile` later reads can never diverge from the
|
|
@@ -534,6 +673,13 @@ prevents:
|
|
|
534
673
|
multi-range or malformed `Range` header serves the full body (`200`),
|
|
535
674
|
never a partial guess; the SPA fallback shell path is a fixed,
|
|
536
675
|
non-user-controlled join — never re-run through the traversal resolver.
|
|
676
|
+
A `Range` under any `If-Range` serves the full `200`, because no validator
|
|
677
|
+
the battery sends compares strongly. A `prefix` and a fallback `exclude`
|
|
678
|
+
hold one slash law: each compares case-sensitively, one trailing slash on
|
|
679
|
+
it is optional, so `/static/` covers `/static`, and it covers a path
|
|
680
|
+
beneath it only on a segment boundary. Before 0.0.35, a `Range` under
|
|
681
|
+
`If-Range` answered `206` whatever the validator, and a `prefix` or an
|
|
682
|
+
`exclude` written `/static/` did not cover `/static`.
|
|
537
683
|
22. **Assets.** `createAssets` decodes a browser-relative key and refuses
|
|
538
684
|
malformed escapes, backslashes, empty segments, `.`/`..`, and dotfiles
|
|
539
685
|
before it calls `AssetSourceInterface.read`. A successful value is copied
|
|
@@ -560,22 +706,41 @@ prevents:
|
|
|
560
706
|
never surfaced as an upload; staged files default to a
|
|
561
707
|
process-owned `mkdtemp` directory under `os.tmpdir()` locked to mode
|
|
562
708
|
`0o700`, with each staged file opened at mode `0o600` (both overridable
|
|
563
|
-
through `options.directory`).
|
|
709
|
+
through `options.directory`). A file the `allowed` list refuses is
|
|
710
|
+
refused before a byte of it is staged. A boundary longer than
|
|
711
|
+
`MULTIPART_MAX_BOUNDARY` is refused `400` as malformed. A header block
|
|
712
|
+
exactly at `MULTIPART_MAX_HEADER_BLOCK` is admitted however its chunks
|
|
713
|
+
arrive. When the handler settles, by a return or a throw, `createMultipart`
|
|
714
|
+
unlinks every file still at its staged path, so a handler moves or reads
|
|
715
|
+
each file it keeps before it returns. Before 0.0.35, a normal return left
|
|
716
|
+
staged files on disk, a file the `allowed` list refused was written to disk
|
|
717
|
+
first, a boundary of any length was taken, and that header block was
|
|
718
|
+
refused when it arrived in small chunks.
|
|
564
719
|
24. **Boundary.** `expose: false` leaks nothing (a non-`HTTPError` throw's
|
|
565
720
|
message never reaches the body); an `HTTPError`'s own `message` always
|
|
566
721
|
surfaces (it is the handler's deliberate signal); a `report` sink's own
|
|
567
722
|
throw is swallowed and can never alter the response.
|
|
568
|
-
25. **`only`/`except`
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
723
|
+
25. **`only`/`except` match through the router's path grammar.** Each path
|
|
724
|
+
is a route pattern compiled by `@orkestrel/router`'s `compilePath` and
|
|
725
|
+
matched against `context.url.pathname` by its `matchPath`. A pattern
|
|
726
|
+
matches case-sensitively whatever the dispatcher's `sensitive` option, with
|
|
727
|
+
one trailing slash optional, so `/admin` covers `/admin` and `/admin/`.
|
|
728
|
+
Under `createDispatcher({ sensitive: false })`, a case variant such as
|
|
729
|
+
`/ADMIN` dispatches to the `/admin` route, but it falls outside
|
|
730
|
+
`only('/admin', …)`, which skips its battery, and inside
|
|
731
|
+
`except('/admin', …)`, which runs it. A
|
|
732
|
+
pattern covers no path beneath it: `/admin` does not cover `/admin/users`.
|
|
733
|
+
To scope a subtree, list `/admin` and `/admin/*rest`; a `*name` wildcard
|
|
734
|
+
matches one or more characters across segments and must be the final
|
|
735
|
+
segment, and `:name` matches one segment. A wildcard before the final
|
|
736
|
+
segment refuses at construction with a `ContractError`. Before 0.0.35,
|
|
737
|
+
both compared the pathname by string equality, so `/admin/` fell outside
|
|
738
|
+
`only('/admin', …)` while the router still dispatched it. Prefer
|
|
739
|
+
`except()` for security batteries (CSRF, bearer, rate limiting): an
|
|
740
|
+
unlisted path still gets the battery, where an unlisted path under
|
|
741
|
+
`only()` goes without it. Keep the pattern set in lockstep with the
|
|
742
|
+
router's routes, because a route added later and left out of the set is
|
|
743
|
+
unscoped.
|
|
579
744
|
26. **Challenge.** Every `401` `createBearer` returns carries a `WWW-Authenticate`
|
|
580
745
|
challenge (RFC 9110 § 15.5.2). A missing, wrong-scheme, or empty token renders
|
|
581
746
|
the configured `challenge` auth-params, and a refused credential adds
|
|
@@ -587,23 +752,23 @@ prevents:
|
|
|
587
752
|
|
|
588
753
|
## Patterns
|
|
589
754
|
|
|
590
|
-
### Canonical onion —
|
|
755
|
+
### Canonical onion — over `compose`
|
|
591
756
|
|
|
592
757
|
The full ordering doctrine, composed directly over `compose` (no `@orkestrel/server`
|
|
593
|
-
`Server` required —
|
|
758
|
+
`Server` required — these batteries read and return `Request` and `Response`):
|
|
594
759
|
|
|
595
760
|
```ts
|
|
596
761
|
import {
|
|
597
762
|
createBearer,
|
|
598
763
|
createBody,
|
|
599
764
|
createBoundary,
|
|
600
|
-
|
|
601
|
-
createCors,
|
|
765
|
+
createCORS,
|
|
602
766
|
createCSRF,
|
|
603
767
|
createDeadline,
|
|
604
768
|
createETag,
|
|
605
769
|
createForwarded,
|
|
606
770
|
createLimiter,
|
|
771
|
+
createNodeCompression,
|
|
607
772
|
createSecurity,
|
|
608
773
|
createSession,
|
|
609
774
|
createTelemetry,
|
|
@@ -616,26 +781,25 @@ import type {
|
|
|
616
781
|
IdentifierState,
|
|
617
782
|
SessionState,
|
|
618
783
|
} from '@orkestrel/middleware'
|
|
619
|
-
import { compose, verifyToken } from '@orkestrel/server'
|
|
784
|
+
import { compose, createSigner, verifyToken } from '@orkestrel/server'
|
|
620
785
|
|
|
621
|
-
interface State extends BearerState, ClientState, CSRFState, IdentifierState, SessionState {
|
|
622
|
-
readonly connection?: { readonly ip?: string }
|
|
623
|
-
}
|
|
786
|
+
interface State extends BearerState, ClientState, CSRFState, IdentifierState, SessionState {}
|
|
624
787
|
|
|
788
|
+
const signer = createSigner('shh')
|
|
625
789
|
const onion = [
|
|
626
790
|
createTelemetry({ record: (entry) => console.log(entry) }),
|
|
627
|
-
|
|
791
|
+
createNodeCompression(),
|
|
792
|
+
createSecurity({ hsts: true }),
|
|
793
|
+
createCORS({ origin: ['https://app.example'] }),
|
|
628
794
|
createBoundary({ expose: false }),
|
|
629
795
|
createDeadline({ ms: 5_000 }),
|
|
630
|
-
createSecurity({ hsts: true }),
|
|
631
|
-
createCors({ origin: ['https://app.example'] }),
|
|
632
796
|
createForwarded({ proxies: 1 }),
|
|
633
797
|
createETag(),
|
|
634
|
-
createBearer({ verify: (token) => verifyToken(token,
|
|
798
|
+
createBearer({ verify: (token) => verifyToken(token, signer) }),
|
|
635
799
|
createLimiter({ max: 100, window: 60_000 }),
|
|
636
800
|
createBody(),
|
|
637
|
-
createSession({ transport: createCookieTransport({
|
|
638
|
-
createCSRF({
|
|
801
|
+
createSession({ transport: createCookieTransport({ signer }) }),
|
|
802
|
+
createCSRF({ signer }),
|
|
639
803
|
]
|
|
640
804
|
|
|
641
805
|
const handle = compose<State>(onion, async (_request, context) => {
|
|
@@ -645,7 +809,7 @@ const handle = compose<State>(onion, async (_request, context) => {
|
|
|
645
809
|
|
|
646
810
|
### Canonical onion — behind `@orkestrel/server`
|
|
647
811
|
|
|
648
|
-
The fence hands the same chain to `createServer` as its `middleware` option, so the server owns the listening socket and the dispatcher the chain terminates in.
|
|
812
|
+
The fence hands the same chain to `createServer` as its `middleware` option, so the server owns the listening socket and the dispatcher the chain terminates in. The batteries read connection facts (`ip`, `encrypted`) from `context.connection`, so the `state: () => ({})` factory carries none, and each calls `next()` with no argument.
|
|
649
813
|
|
|
650
814
|
```ts
|
|
651
815
|
import { createBoundary, createSecurity } from '@orkestrel/middleware'
|
|
@@ -661,7 +825,7 @@ dispatcher.add({ method: 'GET', path: '/health', handler: () => new Response('ok
|
|
|
661
825
|
const server = createServer<State>({
|
|
662
826
|
dispatcher,
|
|
663
827
|
state: () => ({}),
|
|
664
|
-
middleware: [
|
|
828
|
+
middleware: [createSecurity(), createBoundary()],
|
|
665
829
|
})
|
|
666
830
|
const port = await server.start()
|
|
667
831
|
await server.stop()
|
|
@@ -708,10 +872,17 @@ const session = createSession<import('@orkestrel/middleware').SessionInterface,
|
|
|
708
872
|
|
|
709
873
|
// Inside a handler downstream of `session`:
|
|
710
874
|
declare const context: { readonly state: State }
|
|
875
|
+
context.state.session?.set('user', 'u_1') // the first write stores the session and writes its id
|
|
711
876
|
context.state.control?.regenerate() // rotate the id after a privilege change (anti-fixation)
|
|
712
877
|
context.state.control?.destroy() // end the session outright
|
|
713
878
|
```
|
|
714
879
|
|
|
880
|
+
A request with no credential reaches the handler with a session whose `control.fresh` is
|
|
881
|
+
`true`. The battery stores it, and the transport writes its id, only after the handler writes
|
|
882
|
+
to it or regenerates it, so the session header or cookie first appears on the response to that
|
|
883
|
+
write. A request that reads a session and writes nothing leaves the store untouched beyond the
|
|
884
|
+
store's own `get`.
|
|
885
|
+
|
|
715
886
|
### Session store seam — direct calls
|
|
716
887
|
|
|
717
888
|
The fence drives a memory store's `set`, `get`, and `delete` methods directly, with no middleware chain around them.
|
|
@@ -775,20 +946,45 @@ await transport.write(response, 'abc', false) // sets the session-id header
|
|
|
775
946
|
transport.clear(response) // removes it
|
|
776
947
|
```
|
|
777
948
|
|
|
778
|
-
### CSRF:
|
|
949
|
+
### CSRF: signed double submit over one signer
|
|
779
950
|
|
|
780
|
-
The fence mounts the CSRF battery behind a cookie-transport session, which
|
|
951
|
+
The fence mounts the CSRF battery behind a cookie-transport session, which binds each token a held session mints to that session's id.
|
|
781
952
|
|
|
782
953
|
```ts
|
|
783
954
|
import { createCSRF, createSession, createCookieTransport } from '@orkestrel/middleware'
|
|
955
|
+
import { createSigner } from '@orkestrel/server'
|
|
784
956
|
import type { CSRFState, SessionState } from '@orkestrel/middleware'
|
|
785
957
|
|
|
786
958
|
interface State extends SessionState, CSRFState {}
|
|
787
959
|
|
|
960
|
+
const signer = createSigner(['current-secret', 'previous-secret'])
|
|
788
961
|
const session = createSession<import('@orkestrel/middleware').SessionInterface, State>({
|
|
789
|
-
transport: createCookieTransport({
|
|
962
|
+
transport: createCookieTransport({ signer }),
|
|
790
963
|
})
|
|
791
|
-
const csrf = createCSRF({
|
|
964
|
+
const csrf = createCSRF({ signer }) // session ahead binds the token to its id
|
|
965
|
+
```
|
|
966
|
+
|
|
967
|
+
No option takes a secret. `CookieTransportOptions.signer` and `CSRFOptions.signer` each take a
|
|
968
|
+
`SignerInterface`, and a bag that still carries `secret` refuses as an undeclared key. Create the
|
|
969
|
+
signer once per secret list with `createSigner` from `@orkestrel/server` and share it between the
|
|
970
|
+
batteries: `createSigner` creates every key at that call, so no request imports a key. One signer
|
|
971
|
+
is safe for both because a CSRF message opens with `CSRF_LABEL`, which no `signToken` payload can
|
|
972
|
+
equal, and a CSRF token sent as the session cookie resolves no session.
|
|
973
|
+
|
|
974
|
+
### CSRF: redirect after a session change
|
|
975
|
+
|
|
976
|
+
A handler that starts a session (the first write to a fresh one), regenerates it, or destroys it
|
|
977
|
+
answers with a redirect to a page, such as a `303` to `/account`. The tokens the client holds
|
|
978
|
+
were bound to the session or nonce the request arrived with, and `state.csrf` in that handler
|
|
979
|
+
still is; the page the redirect loads renders a token bound to the session or nonce the client
|
|
980
|
+
then holds.
|
|
981
|
+
|
|
982
|
+
```ts
|
|
983
|
+
import type { CSRFState, SessionState } from '@orkestrel/middleware'
|
|
984
|
+
|
|
985
|
+
declare const context: { readonly url: URL; readonly state: SessionState & CSRFState }
|
|
986
|
+
context.state.control?.regenerate() // after a login check passes
|
|
987
|
+
const response = Response.redirect(new URL('/account', context.url), 303)
|
|
792
988
|
```
|
|
793
989
|
|
|
794
990
|
### Multipart: node face, sniffed-type allow-list
|
|
@@ -796,7 +992,7 @@ const csrf = createCSRF({ secret: 'csrf-secret' }) // session ahead binds the to
|
|
|
796
992
|
The fence mounts the node-face multipart battery with a sniffed-type allow-list and narrows its parsed result on `context.state` through the shipped guards.
|
|
797
993
|
|
|
798
994
|
```ts
|
|
799
|
-
import { createMultipart } from '@orkestrel/middleware
|
|
995
|
+
import { createMultipart } from '@orkestrel/middleware'
|
|
800
996
|
import { isMultipartBody, isMultipartFile } from '@orkestrel/middleware'
|
|
801
997
|
import type { MultipartState } from '@orkestrel/middleware'
|
|
802
998
|
|
|
@@ -818,7 +1014,7 @@ if (isMultipartBody(context.state.multipart)) {
|
|
|
818
1014
|
The fence resolves one partial limits input into the effective caps, with no battery around it.
|
|
819
1015
|
|
|
820
1016
|
```ts
|
|
821
|
-
import { resolveMultipartLimits } from '@orkestrel/middleware
|
|
1017
|
+
import { resolveMultipartLimits } from '@orkestrel/middleware'
|
|
822
1018
|
|
|
823
1019
|
resolveMultipartLimits({ file: { size: 1_048_576 } }) // fills in every other default cap
|
|
824
1020
|
```
|
|
@@ -830,8 +1026,8 @@ Multipart processing reports no progress.
|
|
|
830
1026
|
The fence implements an `AssetSourceInterface` over a single in-memory entry and hands it to `createAssets`.
|
|
831
1027
|
|
|
832
1028
|
```ts
|
|
833
|
-
import type { AssetSourceInterface } from '@orkestrel/middleware
|
|
834
|
-
import { createAssets } from '@orkestrel/middleware
|
|
1029
|
+
import type { AssetSourceInterface } from '@orkestrel/middleware'
|
|
1030
|
+
import { createAssets } from '@orkestrel/middleware'
|
|
835
1031
|
|
|
836
1032
|
const source: AssetSourceInterface = {
|
|
837
1033
|
read(path) {
|
|
@@ -860,7 +1056,7 @@ is never retained, so an absent key is read again on its next request.
|
|
|
860
1056
|
The fence serves a directory over `node:fs` with the SPA fallback on, which answers an eligible miss with the shell.
|
|
861
1057
|
|
|
862
1058
|
```ts
|
|
863
|
-
import { createStatic } from '@orkestrel/middleware
|
|
1059
|
+
import { createStatic } from '@orkestrel/middleware'
|
|
864
1060
|
|
|
865
1061
|
const serveApp = createStatic({ root: '/srv/public', fallback: true }) // excludes '/api' by default
|
|
866
1062
|
```
|
|
@@ -896,9 +1092,35 @@ still served through the fallback, because the operator configured that path.
|
|
|
896
1092
|
way out.** `createSession` applies store I/O and transport writes after
|
|
897
1093
|
`next()` resolves: `destroy()` → `store.delete` + `transport.clear`;
|
|
898
1094
|
`regenerate()` → `store.set` the new session, `store.delete` the old,
|
|
899
|
-
`transport.write` the new id; otherwise → `store.set` the
|
|
900
|
-
session, `transport.write` only when
|
|
901
|
-
|
|
1095
|
+
`transport.write` the new id; otherwise, after a write → `store.set` the
|
|
1096
|
+
resolved or minted session, `transport.write` only when it was minted on
|
|
1097
|
+
this request; otherwise nothing. `destroy()` supersedes a prior
|
|
1098
|
+
`regenerate()`.
|
|
1099
|
+
|
|
1100
|
+
### Admission: option bags admitted whole
|
|
1101
|
+
|
|
1102
|
+
Every factory admits its options bag whole through the `own` method of the compiled contract its options interface declares, which reads the bag one time and refuses as the strict `admitValue` function of `@orkestrel/contract` does, against the compiled contract its options interface declares, before it reads a default. The store classes `MemorySessionStore`, `MemoryLimiterStore`, and `DatabaseSessionStore` admit in their constructors, so a direct `new` call and the factory refuse alike, and their messages lead with the class name. A bag must be a plain object: a class instance, an array, `null`, and a primitive refuse. A bag refuses on an undeclared key such as `origins` for `createCORS`, on a missing required key, on a wrong type, on an explicit `undefined`, and on a number outside its range; a `status` lies from 200 through 599, a `ms` is an integer from 1 through 2147483647 (the range `@orkestrel/timeout` enforces), a size is a non-negative finite number, a count is a non-negative integer, and `NaN` refuses everywhere. An absent bag (`undefined`) admits as `{}`, so a factory with a required key refuses it at that key.
|
|
1103
|
+
|
|
1104
|
+
Each refusal is a `ContractError`, and the message leads with the factory name. A refusal from `admitOptions` reports the first fault's path in `context.path`, every fault in `cause`, and, for an undeclared key, the declared keys in the message. `createForwarded` admits a union of its two forms, so its refusal carries the root path `[]` and a message that lists both forms. An implementation key that lacks a declared member reports the member as `context.path`, such as `['store', 'get']`, and a value that is not an object reports the key, such as `['store']`. `renderChallenge` and the `createBearer` refusal of a `challenge` that names `error` report `['scheme']` or `['challenge', name]` as `context.path`, and carry no `cause`.
|
|
1105
|
+
|
|
1106
|
+
An implementation key (`LimiterOptions.store`, `SessionOptions.transport`, `SessionOptions.store`, `CookieTransportOptions.signer`, `CSRFOptions.signer`, `AssetOptions.source`, and `AssetOptions.store`) is an `interfaceShape` member of the bag's contract. The shape declares each member the published interface lists as a function. It holds a class instance, a callable, and an object whose prototype carries the members by identity, accepts unknown members, reads each declared member one time on admission and at most two times on a refusal, and refuses a missing member or a member that is not a function with one fault per member at the member's path, such as `['store', 'get']`. The same admission that refuses a malformed bag therefore refuses a malformed implementation key. The `cookie` record of `CookieTransportOptions` is an owned plain record the caller writes: the bag's contract admits its six members (`path`, `domain`, `maxAge`, `httpOnly`, `secure`, `sameSite`) and refuses any other key, so `maxage` refuses. `maxAge` is a finite number because a non-finite value writes `Max-Age=NaN` or `Max-Age=Infinity` into `Set-Cookie`.
|
|
1107
|
+
|
|
1108
|
+
```ts
|
|
1109
|
+
import {
|
|
1110
|
+
admitOptions,
|
|
1111
|
+
CORS_CONTRACT,
|
|
1112
|
+
DEADLINE_CONTRACT,
|
|
1113
|
+
SESSION_CONTRACT,
|
|
1114
|
+
} from '@orkestrel/middleware'
|
|
1115
|
+
|
|
1116
|
+
admitOptions('createCORS', CORS_CONTRACT, { origin: ['https://app.example'] }) // returns
|
|
1117
|
+
admitOptions('createCORS', CORS_CONTRACT, { origins: ['https://app.example'] }) // throws a ContractError at ['origins']
|
|
1118
|
+
admitOptions('createDeadline', DEADLINE_CONTRACT, { ms: 1_000, status: 1000 }) // throws a ContractError at ['status']
|
|
1119
|
+
|
|
1120
|
+
const transport = { read: () => undefined, write: () => undefined, clear: () => undefined }
|
|
1121
|
+
admitOptions('createSession', SESSION_CONTRACT, { transport, store: new Map() }) // returns: a class instance with the members
|
|
1122
|
+
admitOptions('createSession', SESSION_CONTRACT, { transport, store: {} }) // throws a ContractError at ['store', 'get']
|
|
1123
|
+
```
|
|
902
1124
|
|
|
903
1125
|
### Practices
|
|
904
1126
|
|
|
@@ -915,9 +1137,6 @@ still served through the fallback, because the operator configured that path.
|
|
|
915
1137
|
depends on.
|
|
916
1138
|
- **Install a `report` sink on `createBoundary`** for observability — its
|
|
917
1139
|
own throw is swallowed, so it can never crash a response.
|
|
918
|
-
- **Pick your `createSecurity` position deliberately** — inside the
|
|
919
|
-
boundary (default; headers only on returned responses) or above it
|
|
920
|
-
(headers on every response, thrown errors included) — see Contract §7.
|
|
921
1140
|
|
|
922
1141
|
### Session control intent
|
|
923
1142
|
|
|
@@ -925,6 +1144,7 @@ still served through the fallback, because the operator configured that path.
|
|
|
925
1144
|
import { Session, SessionControl } from '@orkestrel/middleware'
|
|
926
1145
|
|
|
927
1146
|
const control = new SessionControl(new Session('original'))
|
|
1147
|
+
console.log(control.fresh) // false
|
|
928
1148
|
control.regenerate()
|
|
929
1149
|
console.log(control.successor?.id)
|
|
930
1150
|
control.destroy()
|
|
@@ -972,12 +1192,8 @@ import {
|
|
|
972
1192
|
MemoryAssetStore,
|
|
973
1193
|
readAssetRecord,
|
|
974
1194
|
resolveAssetKey,
|
|
975
|
-
} from '@orkestrel/middleware
|
|
976
|
-
import type {
|
|
977
|
-
AssetRecord,
|
|
978
|
-
AssetSourceInterface,
|
|
979
|
-
AssetStoreInterface,
|
|
980
|
-
} from '@orkestrel/middleware/server'
|
|
1195
|
+
} from '@orkestrel/middleware'
|
|
1196
|
+
import type { AssetRecord, AssetSourceInterface, AssetStoreInterface } from '@orkestrel/middleware'
|
|
981
1197
|
|
|
982
1198
|
const source: AssetSourceInterface = {
|
|
983
1199
|
read: (path) =>
|
|
@@ -1004,8 +1220,8 @@ a streamed response transfers ownership to `streamFile`.
|
|
|
1004
1220
|
```ts
|
|
1005
1221
|
import { realpath } from 'node:fs/promises'
|
|
1006
1222
|
import { join } from 'node:path'
|
|
1007
|
-
import { openStaticFile, planStaticResponse, resolveStaticFile } from '@orkestrel/middleware
|
|
1008
|
-
import type { StaticFile, StaticPlan } from '@orkestrel/middleware
|
|
1223
|
+
import { openStaticFile, planStaticResponse, resolveStaticFile } from '@orkestrel/middleware'
|
|
1224
|
+
import type { StaticFile, StaticPlan } from '@orkestrel/middleware'
|
|
1009
1225
|
|
|
1010
1226
|
const root = await realpath('./public')
|
|
1011
1227
|
const path = await resolveStaticFile(join(root, 'index.html'), root, 'index.html')
|
|
@@ -1037,44 +1253,42 @@ console.log(extractFieldToken({ csrf: 'credential' }, 'csrf'))
|
|
|
1037
1253
|
|
|
1038
1254
|
## Tests
|
|
1039
1255
|
|
|
1040
|
-
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔
|
|
1256
|
+
- [`tests/guides.test.ts`](../tests/guides.test.ts) — the `## Surface` ↔
|
|
1041
1257
|
`src/server` bijection (value and type exports), the `AssetSourceInterface`,
|
|
1042
1258
|
`SessionInterface`, `SessionControlInterface`, `SessionStoreInterface`, and
|
|
1043
1259
|
`SessionTransportInterface` method bijections, and the equality gate: every `Summary`
|
|
1044
1260
|
cell against its declaration's description paragraph, the titled `Mount a battery`
|
|
1045
1261
|
fence against the `@example` block of that title (pinned so the titled pair cannot be
|
|
1046
1262
|
retired silently), and the README pitch against this guide's tagline.
|
|
1047
|
-
- [`tests/src/
|
|
1048
|
-
`resolveKey` precedence, `buildRetryAfter`/`buildRateLimitField`/
|
|
1049
|
-
`buildRateLimitPolicyField` exact wire strings, `matchesTrustedEntry`/
|
|
1050
|
-
`resolveForwardedFor` matrices, `detectEncodings`, `compressBytes`, buffering-eligibility
|
|
1051
|
-
predicates, `transferSessionState`, `isPreflight`, `buildClient`,
|
|
1052
|
-
`validateSessionLimits`.
|
|
1053
|
-
- [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) —
|
|
1263
|
+
- [`tests/src/server/validators.test.ts`](../tests/src/server/validators.test.ts) —
|
|
1054
1264
|
the `isSession`/`isSessionControl`/`isMultipartFile`/`isMultipartBody`
|
|
1055
|
-
totality guards, each driven over a well-shaped value and over the
|
|
1265
|
+
totality guards, each driven over a well-shaped value and over the malformed
|
|
1056
1266
|
inputs it must answer `false` to.
|
|
1057
|
-
- [`tests/src/
|
|
1267
|
+
- [`tests/src/server/Session.test.ts`](../tests/src/server/Session.test.ts) —
|
|
1058
1268
|
the entity shape (`id`, an independent `state` view and its mutators per instance).
|
|
1059
|
-
- [`tests/src/
|
|
1269
|
+
- [`tests/src/server/stores/MemorySessionStore.test.ts`](../tests/src/server/stores/MemorySessionStore.test.ts) —
|
|
1060
1270
|
construction guards, get/set/delete, idle + absolute-lifetime eviction,
|
|
1061
|
-
`created` stamped once and preserved across re-set
|
|
1062
|
-
|
|
1271
|
+
`created` stamped once and preserved across re-set, recency refreshed by a
|
|
1272
|
+
live read, one eviction per insert at capacity, and the cost row that bounds
|
|
1273
|
+
the time of an insert at capacity in a store of 4n sessions against one of n.
|
|
1274
|
+
- [`tests/src/server/stores/DatabaseSessionStore.test.ts`](../tests/src/server/stores/DatabaseSessionStore.test.ts) —
|
|
1063
1275
|
get/set/delete over a real `@orkestrel/database` memory-driver table, idle +
|
|
1064
1276
|
absolute-lifetime eviction (including the underlying row's removal),
|
|
1065
1277
|
`created` stamped once and preserved across re-set, guard rejection,
|
|
1066
1278
|
construction guards, rebuild through the injected restore step, and the
|
|
1067
1279
|
propagated `DRIVER` refusal of a row stored under the earlier cursor columns.
|
|
1068
|
-
- [`tests/src/
|
|
1280
|
+
- [`tests/src/server/factories.test.ts`](../tests/src/server/factories.test.ts) —
|
|
1069
1281
|
`createCookieTransport`/`createHeaderTransport` round-trips over real
|
|
1070
1282
|
`Request`/`Response`, `createMemorySessionStore` shallow mirror,
|
|
1071
1283
|
`createRestoredSession` snapshot rebuilds and malformed refusals,
|
|
1072
1284
|
`createDatabaseSessionStore` construction guard.
|
|
1073
|
-
- [`tests/src/core/middlewares.test.ts`](../tests/src/core/middlewares.test.ts) —
|
|
1074
|
-
every battery's defaults, options, skip conditions, and the security
|
|
1075
|
-
acceptance bar's invariants; the canonical onion composed end-to-end.
|
|
1076
1285
|
- [`tests/src/server/helpers.test.ts`](../tests/src/server/helpers.test.ts) —
|
|
1077
|
-
|
|
1286
|
+
`resolveKey` precedence, `buildRetryAfter`/`buildRateLimitField`/
|
|
1287
|
+
`buildRateLimitPolicyField` exact wire strings, `matchesTrustedEntry`/
|
|
1288
|
+
`resolveForwardedFor` matrices, `detectEncodings`, `compressBytes`, buffering-eligibility
|
|
1289
|
+
predicates, `transferSessionState`, `matchesSessionState`, `generateNonce`,
|
|
1290
|
+
`signCSRFToken` and `verifyCSRFToken` over the malformed-token table, `isPreflight`, `buildClient`,
|
|
1291
|
+
`admitOptions`, traversal and SPA-fallback resolution, byte-signature matching, node zlib
|
|
1078
1292
|
compression, multipart limit resolution, boundary extraction, part-header
|
|
1079
1293
|
parsing, `streamFile`'s pull-driven backpressure and descriptor release, and
|
|
1080
1294
|
the uploaded-file operations, including `moveUploadedFile`'s cross-device
|
|
@@ -1089,6 +1303,8 @@ console.log(extractFieldToken({ csrf: 'credential' }, 'csrf'))
|
|
|
1089
1303
|
header-block cap, the total-bytes cap, the abort-mid-upload path, and the
|
|
1090
1304
|
staged-file cleanup each throw performs.
|
|
1091
1305
|
- [`tests/src/server/middlewares.test.ts`](../tests/src/server/middlewares.test.ts) —
|
|
1306
|
+
every battery's defaults, options, skip conditions, and the security
|
|
1307
|
+
acceptance bar's invariants; the canonical onion composed end-to-end;
|
|
1092
1308
|
in-memory asset ownership, key refusal, identity/Brotli negotiation,
|
|
1093
1309
|
conditional and HEAD responses, filesystem static serving, multipart
|
|
1094
1310
|
middleware, and the server-face composition.
|
|
@@ -1100,6 +1316,5 @@ console.log(extractFieldToken({ csrf: 'credential' }, 'csrf'))
|
|
|
1100
1316
|
package is built over. Its mirrored guide is [`server.md`](server.md).
|
|
1101
1317
|
- `@orkestrel/contract` — the guards backing every construction boundary.
|
|
1102
1318
|
- `@orkestrel/budget` — `createLimiter`'s per-key tally.
|
|
1103
|
-
- `@orkestrel/
|
|
1104
|
-
signal-linking and timer.
|
|
1319
|
+
- `@orkestrel/timeout` — `createDeadline`'s timer.
|
|
1105
1320
|
- [`README.md`](README.md) — the guides index.
|