@dokebi/web 0.4.4 → 0.4.6

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/AI.md CHANGED
@@ -142,6 +142,7 @@ http.route({ method: 'POST', url: '/import', handler: async (request, reply) =>
142
142
  | `contentSecurityPolicy({ plugin, directives })` | adds CSP sources for the pages of a plugin (D-0149, §2.4): `{ plugin: 'dokebi-seal', directives: { 'script-src': ["'wasm-unsafe-eval'"] } }`, appended to each directive. Setup only; a malformed one is `INVALID_ARGUMENT` |
143
143
  | `route({ ..., config: { securityHeaders } })` · `route({ ..., config: { overload: false } })` · `route({ ..., config: { readiness: false } })` | per route: `securityHeaders: false` or the settings to change (D-0149, §2.4); `overload: false` serves the route while the server sheds load (D-0150, §2.5); `readiness: false` serves it while a required dependency is down and while the app drains (§3). Checked at start (`INVALID_ROUTE_CONFIG`) |
144
144
  | `route({ ..., config: { requestTimeoutMs } })` | this route's time to receive its body after the headers, in whole ms (1..2147483647), instead of the `requestTimeoutMs` option: give upload routes the time their largest file needs on a slow link. Checked at start (`INVALID_ROUTE_CONFIG`); past it 408 `REQUEST_TIMEOUT` (`data.timeoutMs`) |
145
+ | `route({ ..., config: { requestIdleMs } })` | (0.4.5) the longest gap without a byte of this route's body, in whole ms (1..2147483647): a large upload is never cut while bytes keep arriving, a stalled one is 408 `REQUEST_TIMEOUT` one gap after its last byte. With `requestTimeoutMs` too, that still bounds the whole body. Progress is the connection's bytes read (HTTP/2: the session's). A route with it lifts Node's own whole-request bound to the largest timer (web's per-request timers still apply to every route). Checked at start (`INVALID_ROUTE_CONFIG`) |
145
146
  | `route({ ..., config: { compress: false } })` · `skipCompression(reply)` | keep a route's answers, or one response, uncompressed (D-0125): a page that reflects request input next to a secret of its own (§7, BREACH). `compress` must be a boolean (otherwise `INVALID_ROUTE_CONFIG` at start); `skipCompression` returns the reply and is called before `send` |
146
147
  | `route({ ..., config: { id: 'API-12' } })` | the route's id (D-0077): 1 to 64 letters, digits, `.`, `_` or `-`, starting with a letter. dokebi-web owns the key: a wrong value or a misspelt key (`ID`) fails the start with `INVALID_ROUTE_CONFIG`, and the same id on two routes of one app (the same constraints) fails it with `DUPLICATE_ROUTE_ID` (`details.duplicates`, error log `WEB_ROUTE_ID_DUPLICATE`). One route registered twice counts once: the HEAD twin of a GET, and a path with and without its trailing slash (dokebi-app answers a module root both ways). The same id in two apps (other constraint values) is allowed: a module mounted in both apps is one route of the design. The handler reads it as `request.routeOptions.config.id` (typed `id?: string`; route config stays open to other keys) |
147
148
  | `routes()` | every route added so far (D-0077), frozen: `[{ method, url, id?, constraints, configKeys }]` (`WebRouteEntry`: `method` like `GET` or `GET,POST`, `url` with the scope prefix, `constraints` as text such as `{ dokebiApp: 'admin' }`, `configKeys` the names of its config keys without `url`/`method`). The HEAD twin Fastify adds to a GET is left out; health routes are in it (`configKeys: ['dokebiHealth']`). The same array is returned until another route is added (no copy per call). Complete once the server is ready (after start, or `ready()`), when the routes of Fastify plugin scopes exist too |
@@ -149,7 +150,7 @@ http.route({ method: 'POST', url: '/import', handler: async (request, reply) =>
149
150
 
150
151
  - `dependency` of `@dokebi/web/dependency` (also exported from the root) is the provider descriptor for plugins and app code that always install web (D-0063 §6; a small module that does not load Fastify).
151
152
  - `@dokebi/web/points` exports the contribution points `viewEngines` (`dokebi-web:view-engine`) and `realtime` (`dokebi-web:realtime`) and their value types (`WebViewEngine`, `WebRealtimeTransport`, `WebRealtimeScope`): template-ejs and template-inertia contribute view engines, websocket and sse contribute realtime transports, and @dokebi/app collects them.
152
- - `viewData` (`dokebi-web:view-data`, D-0076 §5) carries values a plugin adds to every rendered page: contribute `{ key, value(request) }` (list the point under `contributes`). @dokebi/app puts it in the EJS data of every app page and error view (`data.<key>`: after `sealed` and the flash, before the app's `shared` and the page data, so those win), template-inertia in the shared props (before the entry's `shared` and the page props). `value` runs only when a page renders (JSON routes never call it) and may return a Promise. `collectViewData(contributions, { plugin, reserved })` is the collectors' check: a key twice, a key the collector sets itself (app: `sealed`, `seal`, `errors`, `old`, `flash`; template-inertia: `errors`, `flash`) or an invalid entry refuses the setup with `VIEW_DATA_CONFLICT` (`plugin` is the collector).
153
+ - `viewData` (`dokebi-web:view-data`, D-0076 §5) carries values a plugin adds to every rendered page: contribute `{ key, value(request) }` (list the point under `contributes`). @dokebi/app puts it in the EJS data of every app page and error view (`data.<key>`: after `sealed` and the flash, before the app's `shared` and the page data, so those win), template-inertia in the shared props (before the entry's `shared` and the page props). `value` runs only when a page renders (JSON routes never call it) and may return a Promise. **Public values (0.4.6, D-0195)**: a contribution with `public: true` says its value is the same for every visitor of a URL and language (@dokebi/i18n `locale` and `i18n`), never the visitor's own (`auth`, `csrf`). Only those go into the first HTML of a template-inertia public page (`render(…, { public: true })`); `value(request, { public: true })` is then called, and must not depend on what the browser sent besides the URL and its language. `collectViewData` returns `publicKeys`, and `values(request, { public: true })` calls only the public contributors. `collectViewData(contributions, { plugin, reserved })` is the collectors' check: a key twice, a key the collector sets itself (app: `sealed`, `seal`, `errors`, `old`, `flash`; template-inertia: `errors`, `flash`) or an invalid entry refuses the setup with `VIEW_DATA_CONFLICT` (`plugin` is the collector).
153
154
  - `errorTranslators` (`dokebi-web:error-translator`, D-0093) is collected by web itself: contribute `{ translate(error, request) }` (type `WebErrorTranslator`; list the point under `contributes`, and core sets the contributor up before web). An error that would answer 500 is offered to every contribution in setup order: an uncoded error (`INTERNAL_SERVER_ERROR`, no Fastify 4xx), and a Dokebi error answering 500, thrown in a handler or any hook: a plugin's coded failure around a driver error (dokebi-auth's HOOK_FAILED of a `findById` on a full pool, dokebi-session's STORE_FAILED over a full Redis connection), or a plugin's own error its translator knows (a bare @dokebi/redis `QUEUE_FULL`, D-0102); for these only a translation answering 5xx counts. The first `DokebiError` returned answers instead, through the normal path of §6 (its status and code, JSON or HTML, `errorBody`, the error responders, sealed JSON). `translate` is synchronous, returns undefined to pass, puts the thrown value in the result's `cause` and no driver text, values or names in its message, hint or data; a numeric `data.retryAfterMs` also sets `Retry-After` (seconds, rounded up). @dokebi/db contributes one from its adapters' `classifyError` (`DB_CONFLICT` 409, `DB_INVALID_DATA` 422, `DB_TIMEOUT`/`DB_BUSY`/`DB_UNAVAILABLE` 503, db AI.md §4.1); @dokebi/redis one for its transient errors (`REDIS_BUSY`/`REDIS_TIMEOUT`/`REDIS_UNAVAILABLE` 503, redis AI.md §4). A contribution without a `translate` function fails the setup with `INVALID_ERROR_TRANSLATOR`; a translator that throws or returns anything else is logged and skipped (§6).
154
155
  - `@dokebi/web/points` also has the shared pieces of app binding (D-0132, §2.1): `appOption(description)` (the `app` option of a plugin that adds routes, for `defineOptions`), `appUrlMatch(routing, url, apps)` (whether a URL a plugin publishes is a domain of the apps that serve it), `APP_NAME`, `APP_NAMES_MAX` and the types `WebAppSetting`, `WebAppRouting`, `WebAppUrlMatch` (also exported from the root, with `appNames`).
155
156
  - **Before-hijack steps** (D-0089, `@dokebi/web/points`, also from the root): a hijacked reply (an SSE stream, a WebSocket upgrade) runs no `onSend`, so plugins that finish work there (@dokebi/session saves the session and writes its cookie, @dokebi/auth its cookies) also push a step onto `beforeHijackSteps(scope)` (one list per server, under `BEFORE_HIJACK` = `Symbol.for('dokebi.web.beforeHijack')`, shared by name), and a transport calls `runBeforeHijack(request, reply, timeoutMs, timeoutError)` before it writes its own head: `undefined` when nothing is to be waited for (no Promise, no timer), else a Promise of the number of steps waited for, rejecting with the first failure or `timeoutError()` (`WebBeforeHijackStep`: `(request, reply) => PromiseLike<void> | undefined`).
@@ -385,7 +386,7 @@ dokebi-web knows no session: the caller flashes `errors` and `old` and answers `
385
386
  | `ROUTE_APP_UNAVAILABLE` | start: a route is bound to apps (`app`, a plugin's `<plugin>.app`) but no app routing is registered (@dokebi/app missing; `data.route`, `data.apps`) (D-0132) |
386
387
  | `ROUTE_APP_UNKNOWN` | start: a route is bound to a name that is not an app (`data.app`, `data.apps`) (D-0132) |
387
388
  | `ROUTE_APP_CONFLICT` | start: two routes with the same method and path answer on one app (`data.route`, `data.app`) (D-0132) |
388
- | `VIEW_DATA_CONFLICT` | setup of a collector (@dokebi/app, template-inertia): two plugins contribute one `dokebi-web:view-data` key, a key is the collector's own, or a contribution is not `{ key, value }` (thrown by `collectViewData`) |
389
+ | `VIEW_DATA_CONFLICT` | setup of a collector (@dokebi/app, template-inertia): two plugins contribute one `dokebi-web:view-data` key, a key is the collector's own, or a contribution is not `{ key, value, public? }` (thrown by `collectViewData`) |
389
390
 
390
391
  Option errors are core `INVALID_PLUGIN_OPTIONS` (cause `INVALID_OPTIONS` with paths such as `trustProxy[0]` in `details.issues`). A 500 leaves the `error` log `HTTP request failed` (`code: WEB_REQUEST_FAILED`, `requestId`, `method`, `route` (the route pattern, no query), `status`, `errorCode`, `error` (name, full message, stack and `Caused by:` causes; only URL credentials are removed as `//***@`, cut above 16 KB)). The same route and error is logged once per `logRepeatWindowMs` (10 seconds) and the count in between appears as `repeated` in the next record (D-0047). A 4xx is debug `HTTP request rejected` (`status`, `route`, the full `error` text, `errorCode`). A translated error (D-0093), whatever its status, is the `error` log `HTTP request error translated` (`code: WEB_ERROR_TRANSLATED`, `requestId`, `method`, `route`, `status`, `errorCode`, `translator` (the plugin), `error`: the translated error with the thrown value as its `Caused by:`), once per route, code and 10 seconds with `repeated` like the 500 log, which it replaces. **Retryable 503s under a burst ([D-0113](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0113-overload-log-and-storage-wait.md)).** A translated error that answers 503, and a coded error that answers 503 with `data.retryAfterMs` (`Retry-After`), is an expected refusal: a burst of them must not write a full stack per request (AI-M25: 193,466 records, about 200 MB in 65 s, rotated every other log out). The first one of each status, error code, method and route in a window of `transientLogWindowMs` is logged in full as above (`WEB_ERROR_TRANSLATED` or `WEB_REQUEST_FAILED`, at `transientLogLevel`; not the seal refusals whose own layer writes their one record: `SEAL_NONCES_LOST`, `SEAL_BUSY`, and `SEAL_NONCE_STORE_UNAVAILABLE` of dokebi-seal's shared stores (see the error code table)); the rest are counted, and when the window ends, or when the server closes, one line per pair gives the exact count: `HTTP transient errors repeated` (`code: WEB_TRANSIENT_REPEATED`, `method`, `route`, `status`, `errorCode`, `translator` when translated, `repeated` (the ones after the logged first), `windowMs`). The next window logs its first one in full again. Past `transientLogMaxKeys` pairs in one window, new pairs are only counted, in one `WEB_TRANSIENT_REPEATED` line with `overflow: true`, `repeated`, `maxKeys` and a `fix`. Every other 5xx (a 500, a 503 without `Retry-After`) and a translated 4xx keep the rule above. A translator that throws or returns something else is the `error` log `Web error translator failed` (`code: WEB_ERROR_TRANSLATOR_FAILED`, `route`, `translator`, `fix`, `error`), once per translator, route and interval; the next translator, finally the 500 answer, takes the error. If you register your own error handler, its security is your responsibility.
391
392
 
package/dist/index.d.ts CHANGED
@@ -55,6 +55,12 @@ declare module 'fastify' {
55
55
  * is 408 REQUEST_TIMEOUT. Checked at start (INVALID_ROUTE_CONFIG).
56
56
  */
57
57
  requestTimeoutMs?: number;
58
+ /**
59
+ * The longest gap without a byte of this route's request body, in ms: a large upload is never
60
+ * cut while it keeps arriving (with `requestTimeoutMs` too, that bounds the whole body).
61
+ * Past it the answer is 408 REQUEST_TIMEOUT. Checked at start (INVALID_ROUTE_CONFIG).
62
+ */
63
+ requestIdleMs?: number;
58
64
  /**
59
65
  * Security headers of this route (D-0149): `false` sends none (an answer embedded by other
60
66
  * sites on purpose), an object changes some (`{ frameOptions: false, contentSecurityPolicy:
package/dist/index.js CHANGED
@@ -128,6 +128,13 @@ const ERROR_PASS = Symbol('dokebi.web.errorPass');
128
128
  const BODY_TIMER = Symbol('dokebi.web.bodyTimer');
129
129
  /** On the raw request whose body did not arrive in time (answered 408 or cut). */
130
130
  const TIMED_OUT = Symbol('dokebi.web.timedOut');
131
+ /** On a raw request of a route with `config.requestIdleMs`: what its idle timer compares. */
132
+ const BODY_IDLE = Symbol('dokebi.web.bodyIdle');
133
+ /** Bytes the request's connection has read (HTTP/2: the session's socket). */
134
+ function bytesRead(raw) {
135
+ const value = raw.socket?.bytesRead;
136
+ return typeof value === 'number' ? value : 0;
137
+ }
131
138
  /** The error of a body that did not arrive in time: the 408 answer, and what its reader gets. */
132
139
  function bodyTimeout(ms) {
133
140
  return new WebError('REQUEST_TIMEOUT', `The request body did not arrive within ${ms} ms`, {
@@ -751,14 +758,25 @@ class WebOwner {
751
758
  }
752
759
  // A route's own requestTimeoutMs (an upload route): its first onRequest step times the body
753
760
  // again with it (the global hook ran first, with the dokebi-web option). Checked at start.
754
- const bodyMs = config?.requestTimeoutMs;
755
- if (typeof bodyMs === 'number' && Number.isSafeInteger(bodyMs) && bodyMs >= 1) {
756
- // Node's own request timeout is set past the longest body time at start.
757
- if (bodyMs <= MAX_TIMEOUT_MS)
758
- owner.#longestBodyMs = Math.max(owner.#longestBodyMs, bodyMs);
761
+ // requestIdleMs instead bounds the gaps between bytes (requestTimeoutMs, when set too, the
762
+ // whole body).
763
+ const timing = config;
764
+ const whole = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 1;
765
+ const bodyMs = timing?.requestTimeoutMs;
766
+ const idleMs = timing?.requestIdleMs;
767
+ if (whole(bodyMs) || whole(idleMs)) {
768
+ // Node's own request timeout is set past the longest body time at start (an idle route
769
+ // has no longest time: Node's whole-request bound becomes the largest timer).
770
+ const longest = whole(idleMs)
771
+ ? whole(bodyMs)
772
+ ? bodyMs
773
+ : MAX_TIMEOUT_MS
774
+ : bodyMs;
775
+ if (longest <= MAX_TIMEOUT_MS)
776
+ owner.#longestBodyMs = Math.max(owner.#longestBodyMs, longest);
759
777
  const retime = (request, reply, done) => {
760
778
  if (request.raw[BODY_TIMER] !== undefined)
761
- owner.#timeBody(request, reply, bodyMs);
779
+ owner.#timeBody(request, reply, whole(idleMs) ? idleMs : bodyMs, whole(idleMs) ? (whole(bodyMs) ? bodyMs : undefined) : undefined, whole(idleMs));
762
780
  done();
763
781
  };
764
782
  const fields = route;
@@ -1113,13 +1131,20 @@ class WebOwner {
1113
1131
  this.#release();
1114
1132
  });
1115
1133
  }
1116
- /** The timer of a body that is arriving: `ms` from now (re-armed by a route's own setting). */
1117
- #timeBody(request, reply, ms) {
1134
+ /**
1135
+ * The timer of a body that is arriving: `ms` from now (re-armed by a route's own setting).
1136
+ * `idle`: `ms` is the longest gap without a byte (config.requestIdleMs): the timer re-arms while
1137
+ * the connection keeps reading, up to `wholeMs` when the route bounds the whole body too.
1138
+ */
1139
+ #timeBody(request, reply, ms, wholeMs, idle = false) {
1118
1140
  const raw = request.raw;
1119
1141
  if (raw[BODY_TIMER] === undefined)
1120
1142
  raw.once('end', clearBodyTimer);
1121
1143
  else
1122
1144
  clearTimeout(raw[BODY_TIMER]);
1145
+ raw[BODY_IDLE] = idle
1146
+ ? { bytes: bytesRead(raw), started: performance.now(), wholeMs }
1147
+ : undefined;
1123
1148
  const timer = setTimeout(this.#bodyTimedOut, ms, request, reply, ms);
1124
1149
  timer.unref();
1125
1150
  raw[BODY_TIMER] = timer;
@@ -1134,6 +1159,19 @@ class WebOwner {
1134
1159
  raw[BODY_TIMER] = undefined;
1135
1160
  if (raw.complete || raw.destroyed)
1136
1161
  return;
1162
+ const idle = raw[BODY_IDLE];
1163
+ if (idle !== undefined) {
1164
+ const bytes = bytesRead(raw);
1165
+ const within = idle.wholeMs === undefined || performance.now() - idle.started < idle.wholeMs;
1166
+ // Bytes arrived since the timer was armed: the body is still coming, wait another gap.
1167
+ if (bytes > idle.bytes && within) {
1168
+ idle.bytes = bytes;
1169
+ const timer = setTimeout(this.#bodyTimedOut, ms, request, reply, ms);
1170
+ timer.unref();
1171
+ raw[BODY_TIMER] = timer;
1172
+ return;
1173
+ }
1174
+ }
1137
1175
  raw[TIMED_OUT] = ms;
1138
1176
  const answered = reply.sent || reply.raw.headersSent;
1139
1177
  if (this.context.logger.isEnabled('debug'))
@@ -2458,7 +2496,7 @@ class WebRuntime {
2458
2496
  }
2459
2497
  export const createPlugin = definePlugin({
2460
2498
  name: 'dokebi-web',
2461
- version: '0.4.4',
2499
+ version: '0.4.6',
2462
2500
  core: '^0.4.2',
2463
2501
  options: declaration,
2464
2502
  entry: (input) => new WebEntryInput(input),
package/dist/points.d.ts CHANGED
@@ -58,8 +58,25 @@ export interface WebRealtimeTransport<TRoute = unknown, THandle = unknown> {
58
58
  export interface WebViewData {
59
59
  /** The name the value appears under. Two contributors with the same key refuse the setup. */
60
60
  readonly key: string;
61
- /** The value for one request; may be a Promise. Must not throw for an ordinary request. */
62
- value(request: FastifyRequest): unknown;
61
+ /**
62
+ * D-0195: the value is the same for every visitor of a URL (a language, the site's settings),
63
+ * never the visitor's own (a user, a token). Only such values go into the first HTML of a
64
+ * public page (template-inertia `render(…, { public: true })`), which a shared cache may keep;
65
+ * the others reach the page afterwards. Default false.
66
+ */
67
+ readonly public?: boolean;
68
+ /**
69
+ * The value for one request; may be a Promise. Must not throw for an ordinary request. `view`
70
+ * says what it is for: `public: true` for the first HTML of a public page (D-0195), where the
71
+ * value must not depend on what this browser sent besides the URL and its language (cookies
72
+ * that only save bytes, for example).
73
+ */
74
+ value(request: FastifyRequest, view?: WebViewDataRequest): unknown;
75
+ }
76
+ /** What one view data value is computed for (D-0195). */
77
+ export interface WebViewDataRequest {
78
+ /** The first HTML of a public page: the same for every visitor of the URL and language. */
79
+ readonly public: boolean;
63
80
  }
64
81
  /**
65
82
  * Turns an unhandled error into a coded one (`dokebi-web:error-translator`, D-0093): dokebi-db
@@ -93,8 +110,13 @@ export declare const errorTranslators: import("@dokebi/core").ContributionPoint<
93
110
  export interface WebViewDataCollection {
94
111
  /** Contributed keys in setup order; empty when nothing was contributed (then `values` is never needed). */
95
112
  readonly keys: readonly string[];
96
- /** Every contributor's value for this request, computed together. */
97
- values(request: FastifyRequest): Promise<Record<string, unknown>>;
113
+ /** The keys whose contributors said `public: true` (D-0195), in setup order. */
114
+ readonly publicKeys: readonly string[];
115
+ /**
116
+ * The contributors' values for this request, computed together. `{ public: true }` (D-0195):
117
+ * only the public contributors, each told so; the others are not called.
118
+ */
119
+ values(request: FastifyRequest, view?: WebViewDataRequest): Promise<Record<string, unknown>>;
98
120
  }
99
121
  /**
100
122
  * Checks the contributions of `dokebi-web:view-data` for one collector (dokebi-app for EJS,
package/dist/points.js CHANGED
@@ -17,11 +17,14 @@ const VIEW_DATA_KEY = /^[A-Za-z_$][A-Za-z0-9_$]{0,63}$/;
17
17
  export function collectViewData(contributions, collector) {
18
18
  const entries = new Map();
19
19
  for (const { plugin, value: contribution } of contributions) {
20
- const { key, value } = (contribution ?? {});
20
+ const { key, value, public: shared } = (contribution ?? {});
21
21
  const refuse = (message, fix) => {
22
22
  throw new DokebiError('VIEW_DATA_CONFLICT', message, { plugin: collector.plugin, fix });
23
23
  };
24
- if (typeof key !== 'string' || !VIEW_DATA_KEY.test(key) || typeof value !== 'function')
24
+ if (typeof key !== 'string' ||
25
+ !VIEW_DATA_KEY.test(key) ||
26
+ typeof value !== 'function' ||
27
+ (shared !== undefined && typeof shared !== 'boolean'))
25
28
  refuse(`${plugin} contributed invalid view data`, `Contribute { key: 'name', value: (request) => value } to dokebi-web:view-data (${plugin}).`);
26
29
  const name = key;
27
30
  if (collector.reserved.includes(name))
@@ -32,12 +35,19 @@ export function collectViewData(contributions, collector) {
32
35
  entries.set(name, { plugin, source: contribution });
33
36
  }
34
37
  const list = [...entries];
38
+ const publicList = list.filter(([, entry]) => entry.source.public === true);
39
+ const ALL = Object.freeze({ public: false });
40
+ const PUBLIC = Object.freeze({ public: true });
35
41
  return Object.freeze({
36
42
  keys: Object.freeze(list.map(([key]) => key)),
37
- values: async (request) => {
38
- const values = await Promise.all(list.map(([, entry]) => entry.source.value(request)));
43
+ publicKeys: Object.freeze(publicList.map(([key]) => key)),
44
+ values: async (request, view) => {
45
+ const only = view?.public === true;
46
+ const chosen = only ? publicList : list;
47
+ const told = only ? PUBLIC : ALL;
48
+ const values = await Promise.all(chosen.map(([, entry]) => entry.source.value(request, told)));
39
49
  const result = {};
40
- list.forEach(([key], index) => {
50
+ chosen.forEach(([key], index) => {
41
51
  result[key] = values[index];
42
52
  });
43
53
  return result;
@@ -28,7 +28,7 @@ export declare function routeIdProblem(value: unknown): string | undefined;
28
28
  export declare const MAX_TIMEOUT_MS = 2147483647;
29
29
  export declare class RouteConfigKeys {
30
30
  #private;
31
- /** Keys declared by other plugins (dokebi-web's own six not counted). */
31
+ /** Keys declared by other plugins (dokebi-web's own seven not counted). */
32
32
  get size(): number;
33
33
  add(definition: WebRouteConfigKey): void;
34
34
  /** Called from onRoute for every route (start-up cost only). */
@@ -70,6 +70,17 @@ const REQUEST_TIMEOUT_KEY = Object.freeze({
70
70
  ? undefined
71
71
  : `must be whole milliseconds from 1 to ${MAX_TIMEOUT_MS} (the time this route's body may take to arrive), not ${value === null ? 'null' : typeof value === 'number' ? value : typeof value}`,
72
72
  });
73
+ /**
74
+ * `config.requestIdleMs` (2026-11-07): this route's body may take any time while bytes keep
75
+ * arriving; a gap of this many ms without a byte is 408 (a large upload over a slow link).
76
+ */
77
+ const REQUEST_IDLE_KEY = Object.freeze({
78
+ key: 'requestIdleMs',
79
+ plugin: 'dokebi-web',
80
+ check: (value) => typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_TIMEOUT_MS
81
+ ? undefined
82
+ : `must be whole milliseconds from 1 to ${MAX_TIMEOUT_MS} (the longest gap without a byte of this route's body), not ${value === null ? 'null' : typeof value === 'number' ? value : typeof value}`,
83
+ });
73
84
  /**
74
85
  * Options of `web.route()` itself that read like route config keys. The per-route switches
75
86
  * `overload`, `readiness`, `compress`, `securityHeaders` and `requestTimeoutMs` live in `config`;
@@ -89,11 +100,12 @@ export class RouteConfigKeys {
89
100
  ['overload', OVERLOAD_KEY],
90
101
  ['readiness', READINESS_KEY],
91
102
  ['requestTimeoutMs', REQUEST_TIMEOUT_KEY],
103
+ ['requestIdleMs', REQUEST_IDLE_KEY],
92
104
  ]);
93
105
  #routes = [];
94
- /** Keys declared by other plugins (dokebi-web's own six not counted). */
106
+ /** Keys declared by other plugins (dokebi-web's own seven not counted). */
95
107
  get size() {
96
- return this.#keys.size - 6;
108
+ return this.#keys.size - 7;
97
109
  }
98
110
  add(definition) {
99
111
  const { key, plugin, check, routes } = (definition ?? {});
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dokebi/web",
3
- "version": "0.4.4",
3
+ "version": "0.4.6",
4
4
  "description": "Fastify 5 HTTP server owned by a Dokebi app: 503 before ready, health routes, drain and cluster handover.",
5
5
  "keywords": [
6
6
  "dokebi",