@dokebi/web 0.4.6 → 0.4.7
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 +2 -1
- package/dist/connections.d.ts +10 -0
- package/dist/connections.js +18 -1
- package/dist/index.js +100 -2
- package/package.json +1 -1
package/AI.md
CHANGED
|
@@ -244,12 +244,13 @@ With @dokebi/seal and @dokebi/app, requests to a seal host behave like this: JSO
|
|
|
244
244
|
|
|
245
245
|
- **A page navigation is HTML, its errors too.** A GET or HEAD without a body whose `Accept` prefers HTML and that carries no script marker (`X-Inertia`, `X-Requested-With`, Bearer, `x-dokebi-sealed`, a `Sec-Fetch-Mode` other than `navigate`) is answered like on a plain host: the page, and an error as the HTML page (an app's `errors/<status>.ejs`, an Inertia `errorPage`, else web's small page). Every JSON answer of a sealed request stays sealed.
|
|
246
246
|
- **A sealed form** is a request with `x-dokebi-form: 1` (sent by `@dokebi/seal/forms`). Its sealed body must open to the shape the urlencoded parser gives — an object of strings, a repeated name an array of two or more strings, at most `formMaxFields` values — and the handler gets it as such an object without a prototype (`formBody` off: 415 `FORM_BODY_DISABLED`; another shape, a marker other than `1`, or the marker on a body that is neither sealed nor multipart: 400 `FORM_BODY_INVALID`). `isFormSubmission` is true for it, so its errors take the HTML form flow: a 422 (or a 4xx with `data.formErrors`) goes back with `errors` and `old` (@dokebi/app with a session), any other error is the HTML error page. With files the module sends multipart with the same marker.
|
|
247
|
+
- **Header values are ASCII.** Node refuses a header value with a character past U+00FF or a line break when the head is written. A redirect address is the exception web handles: `reply.redirect('/검색?q=가')` leaves with spaces and non-ASCII characters percent-encoded as UTF-8 (`%XX` already there stays). Any other such header (`reply.header('x-name', '홍길동')`) is a programming error: the answer is 500 `INTERNAL_SERVER_ERROR` without that header, logged as `WEB_REQUEST_FAILED` with the header's name (before 0.4.7 the connection was dropped). Encode such values yourself (`encodeURIComponent`, RFC 8187 for file names). <!-- docs-check: allow-hangul -->
|
|
247
248
|
- **Redirects of a sealed form are told, not followed**: a 3xx answer to `x-dokebi-form: 1` leaves as **204 with `x-dokebi-location: <target>`** (and `Cache-Control: no-store`), and the forms module navigates there. The browser's fetch would otherwise follow the redirect itself — render the next page and take its session flash for an answer it throws away, and fail on another origin. Success redirects of handlers and the form-back redirect both go this way.
|
|
248
249
|
- **A native form post** (urlencoded, a page without its seal script or without JavaScript) is still refused with 415 `SEAL_REQUIRED`, now with fixed words (`This page needs its seal script to send forms`, hint `Reload the page and send the form again.`): an HTML page for a browser navigation, the JSON 415 for a script. Asking for sealing without a provider fails the start with `SEAL_PROVIDER_MISSING`. Sealing is obfuscation and replay protection; confidentiality comes from TLS.
|
|
249
250
|
|
|
250
251
|
## 4. Shutdown (drain)
|
|
251
252
|
|
|
252
|
-
- Single process: new requests get 503, and drain waits for responses in progress, handler Promises (including the part that continues after the response was sent), request hooks, after-response hooks (`onResponse`, `onError`, `onTimeout`, `onRequestAbort`) and `track` work. When a client disconnects first, drain still waits for that request's hooks and handler (D-0023). Requests are counted without a Promise each (D-0068). When the core drain deadline (default 20 s) passes or on `stop({ force: true })`, remaining connections are cut and drain returns (core records `DRAIN_TIMEOUT`). After every drain succeeded, cleanup calls `Fastify.close` (onClose runs). Cleanup first ends every connection that answers no request: idle keep-alive connections, a connection on which no request ever arrived (a browser's preconnect, the spare connection an HTTP client opens after it aborted a request), one whose next request is still arriving, a TLS connection before its handshake, and an HTTP/2 session without streams, including one whose client never sent its preface. Node's own sweep leaves these, and `server.close()` waited for them until `headersTimeout` or for ever, past the cleanup deadline (`CLEANUP_TIMEOUT`). A response still under way is left to finish and its connection is ended once it has; an HTTP/2 session with streams under way gets GOAWAY and ends after them; an upgraded connection (WebSocket) is left to its plugin; a connection accepted after cleanup began is ended at once. Connections are judged from public server events only (`connection`, `secureConnection`, `session`, `request` and the response's `close`, `upgrade`): per connection one Set entry and one shared listener (plus one Map entry behind TLS or HTTP/2), per HTTP/1 request one property write (the connection's newest response), per HTTP/2 request a counter on the session and one shared listener. Measured against the previous reads of Node's private fields: no difference on the empty-route benchmark (web/fastify 0.933 against 0.931, three alternating rounds each). At the drain deadline the same tracking cuts every connection but upgraded ones (HTTP/2 servers have no `closeAllConnections`), and a draining cluster worker sends GOAWAY to its HTTP/2 sessions.
|
|
253
|
+
- Single process: new requests get 503, and drain waits for responses in progress, handler Promises (including the part that continues after the response was sent), request hooks, after-response hooks (`onResponse`, `onError`, `onTimeout`, `onRequestAbort`) and `track` work. When a client disconnects first, drain still waits for that request's hooks and handler (D-0023). A request body the client did not finish sending (its connection closed, or its HTTP/2 stream was reset before the end of the body) is never handed to a parser or a handler as a complete one: whoever reads it gets an error (`ECONNRESET`, answered 400 to nobody), also a reader that starts after the client left (a hook before the parsers was still running), so such a request ends instead of holding the drain. Requests are counted without a Promise each (D-0068). When the core drain deadline (default 20 s) passes or on `stop({ force: true })`, remaining connections are cut and drain returns (core records `DRAIN_TIMEOUT`). After every drain succeeded, cleanup calls `Fastify.close` (onClose runs). Cleanup first ends every connection that answers no request: idle keep-alive connections, a connection on which no request ever arrived (a browser's preconnect, the spare connection an HTTP client opens after it aborted a request), one whose next request is still arriving, a TLS connection before its handshake, and an HTTP/2 session without streams, including one whose client never sent its preface. Node's own sweep leaves these, and `server.close()` waited for them until `headersTimeout` or for ever, past the cleanup deadline (`CLEANUP_TIMEOUT`). A response still under way is left to finish and its connection is ended once it has; an HTTP/2 session with streams under way gets GOAWAY and ends after them; an upgraded connection (WebSocket) is left to its plugin; a connection accepted after cleanup began is ended at once. Connections are judged from public server events only (`connection`, `secureConnection`, `session`, `request` and the response's `close`, `upgrade`): per connection one Set entry and one shared listener (plus one Map entry behind TLS or HTTP/2), per HTTP/1 request one property write (the connection's newest response, cleared when that response closes so an idle connection holds nothing of the request it answered), per HTTP/2 request a counter on the session and one shared listener. Measured against the previous reads of Node's private fields: no difference on the empty-route benchmark (web/fastify 0.933 against 0.931, three alternating rounds each). At the drain deadline the same tracking cuts every connection but upgraded ones (HTTP/2 servers have no `closeAllConnections`), and a draining cluster worker sends GOAWAY to its HTTP/2 sessions.
|
|
253
254
|
- Cluster worker (D-0036): the listen socket closes first so the primary sends new connections to other workers, and HTTP/2 sessions are told GOAWAY. HTTP/1 has no such signal: a keep-alive connection the server answered with `Keep-Alive: timeout=…` may carry the client's next request at any moment, and closing it then loses that request (`ECONNRESET`; Node's agent never resends, undici only idempotent methods — the M50 review lost 2 of 588 paced POSTs per 10 replacements). So the open connections stay up to `drainIdleMs` (2 s): a request on one is served with `Connection: close` and the client's next one opens a connection to another worker; the wait ends as soon as no connection is left. Then the connections still idle are closed (once, `closeIdleConnections`, which leaves a connection whose next request has begun to arrive), and a response still under way closes its connection when it ends; after that only the ending response's own connection is looked at, so a drain costs O(connections) ([D-0107](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0107-stream-and-render-bounds.md) §1). The worker stays up at least `drainGraceMs` (100 ms). What stays: a client that stays idle longer than `drainIdleMs` and sends its request at the very moment the connection closes can still see `ECONNRESET` (no HTTP/1 server can prevent that); a client that pauses longer than 2 s between requests needs a larger `drainIdleMs`, or a retry of the requests it can repeat.
|
|
254
255
|
|
|
255
256
|
## 5. Ownership rules (important)
|
package/dist/connections.d.ts
CHANGED
|
@@ -39,6 +39,16 @@ export declare class WebConnections {
|
|
|
39
39
|
* response's session went away in goAway(). Returns the ended socket.
|
|
40
40
|
*/
|
|
41
41
|
endIfIdle(response: ServerResponse): Socket | undefined;
|
|
42
|
+
/**
|
|
43
|
+
* A response closed: its HTTP/1 connection forgets it, unless a newer request took its place.
|
|
44
|
+
* Left there, a keep-alive socket held its last response — and through it the request, the
|
|
45
|
+
* Fastify request and reply, their headers and body — until the client's next request: under
|
|
46
|
+
* load every scavenge found one such graph per open connection alive and copied it, and V8 grew
|
|
47
|
+
* the young generation to its maximum (64 connections: new space 53.5 MB, 15.5 MB without the
|
|
48
|
+
* reference, as Fastify alone; audit r9 group 2). A closed response answers nothing, so every
|
|
49
|
+
* reader of the mark sees the same as before.
|
|
50
|
+
*/
|
|
51
|
+
released(response: ServerResponse): void;
|
|
42
52
|
/** The drain deadline or a forced stop: every connection but upgraded ones is cut. */
|
|
43
53
|
cut(): number;
|
|
44
54
|
}
|
package/dist/connections.js
CHANGED
|
@@ -5,7 +5,8 @@
|
|
|
5
5
|
* listener (plus one Map entry behind TLS or HTTP/2, to pair the accepted socket with its TLS
|
|
6
6
|
* socket or session by remote address). Per HTTP/1 request: one property write (the newest
|
|
7
7
|
* response of the connection; it is answering while that response has not finished, since
|
|
8
|
-
* Node answers a connection's requests in order)
|
|
8
|
+
* Node answers a connection's requests in order), cleared again when that response closes
|
|
9
|
+
* (`released`, from web's own 'close' listener). Per HTTP/2 request: a counter on the session
|
|
9
10
|
* and one shared 'close' listener on the response (streams of a session run side by side).
|
|
10
11
|
*
|
|
11
12
|
* Node's own sweep (closeIdleConnections) leaves a connection on which no request ever arrived
|
|
@@ -265,6 +266,22 @@ export class WebConnections {
|
|
|
265
266
|
socket.destroy();
|
|
266
267
|
return socket;
|
|
267
268
|
}
|
|
269
|
+
/**
|
|
270
|
+
* A response closed: its HTTP/1 connection forgets it, unless a newer request took its place.
|
|
271
|
+
* Left there, a keep-alive socket held its last response — and through it the request, the
|
|
272
|
+
* Fastify request and reply, their headers and body — until the client's next request: under
|
|
273
|
+
* load every scavenge found one such graph per open connection alive and copied it, and V8 grew
|
|
274
|
+
* the young generation to its maximum (64 connections: new space 53.5 MB, 15.5 MB without the
|
|
275
|
+
* reference, as Fastify alone; audit r9 group 2). A closed response answers nothing, so every
|
|
276
|
+
* reader of the mark sees the same as before.
|
|
277
|
+
*/
|
|
278
|
+
released(response) {
|
|
279
|
+
if (response[HOLDER] !== undefined)
|
|
280
|
+
return;
|
|
281
|
+
const socket = response.req?.socket;
|
|
282
|
+
if (socket != null && socket[LAST] === response)
|
|
283
|
+
socket[LAST] = undefined;
|
|
284
|
+
}
|
|
268
285
|
/** The drain deadline or a forced stop: every connection but upgraded ones is cut. */
|
|
269
286
|
cut() {
|
|
270
287
|
let cut = 0;
|
package/dist/index.js
CHANGED
|
@@ -166,6 +166,72 @@ function endStreamAfterAnswer(request, ms) {
|
|
|
166
166
|
else
|
|
167
167
|
stream.once('finish', end);
|
|
168
168
|
}
|
|
169
|
+
/** What the reader of a body gets once its client has left: Node's own HTTP/1 error. */
|
|
170
|
+
function bodyAborted() {
|
|
171
|
+
return Object.assign(new Error('aborted'), { code: 'ECONNRESET' });
|
|
172
|
+
}
|
|
173
|
+
/**
|
|
174
|
+
* The client left before its answer was written and the request body had not been read to its
|
|
175
|
+
* end: that body never arrives, and whoever reads it must be told (audit r9 group 2).
|
|
176
|
+
*
|
|
177
|
+
* A reader that attaches later (the client left while a hook before the parsers was still
|
|
178
|
+
* running) listens to a destroyed stream that emits nothing, for ever: the request stayed held
|
|
179
|
+
* and a stop waited for it until the drain deadline. The first 'data' listener added from now on
|
|
180
|
+
* gets the error on the next tick, as a reader already listening got it from Node (HTTP/1) or
|
|
181
|
+
* from `abortedStream` (HTTP/2).
|
|
182
|
+
*
|
|
183
|
+
* Returns whether the body was abandoned (for the debug record). Rare path: no cost per request.
|
|
184
|
+
*/
|
|
185
|
+
function abandonBody(request) {
|
|
186
|
+
if (request.readableEnded || !request.destroyed)
|
|
187
|
+
return false;
|
|
188
|
+
const late = (event) => {
|
|
189
|
+
if (event !== 'data')
|
|
190
|
+
return;
|
|
191
|
+
request.removeListener('newListener', late);
|
|
192
|
+
// The reader adds its 'error' listener in the same turn (Fastify's: data, end, error).
|
|
193
|
+
process.nextTick(() => {
|
|
194
|
+
if (request.listenerCount('error') > 0)
|
|
195
|
+
request.emit('error', bodyAborted());
|
|
196
|
+
});
|
|
197
|
+
};
|
|
198
|
+
request.on('newListener', late);
|
|
199
|
+
return true;
|
|
200
|
+
}
|
|
201
|
+
/**
|
|
202
|
+
* The shared 'aborted' listener of an HTTP/2 request with a body (`this` is the raw request): the
|
|
203
|
+
* client reset the stream, or its connection went, before the body's END_STREAM. Node's compat
|
|
204
|
+
* request ends such a stream like a complete one ('end' after the bytes that came), and an HTTP/2
|
|
205
|
+
* request needs no Content-Length, so Fastify's reader has nothing to compare: the parser took
|
|
206
|
+
* the part that had arrived and the handler ran with a truncated form or upload (audit r9 group
|
|
207
|
+
* 2). The request is destroyed instead, with the error HTTP/1 gives its reader (to listeners
|
|
208
|
+
* only: a plain Readable throws an 'error' nobody listens to; a later reader: `abandonBody`).
|
|
209
|
+
*/
|
|
210
|
+
function abortedStream() {
|
|
211
|
+
if (this.readableEnded || this.destroyed)
|
|
212
|
+
return;
|
|
213
|
+
this.destroy(this.listenerCount('error') > 0 ? bodyAborted() : undefined);
|
|
214
|
+
}
|
|
215
|
+
/** A space or anything past ASCII: what a `Location` cannot carry as written. */
|
|
216
|
+
const NOT_HEADER_ASCII = /[ \u0080-\uffff]+/g;
|
|
217
|
+
/**
|
|
218
|
+
* A redirect address Node can write (audit r9, R9-g13-8): spaces and non-ASCII characters
|
|
219
|
+
* percent-encoded as UTF-8, everything else as written (`%XX` stays, never encoded twice). Node
|
|
220
|
+
* refuses a header value past U+00FF, so `reply.redirect('/검색')` failed when the head was
|
|
221
|
+
* written. Control characters are left for Node to refuse, and so is a lone surrogate.
|
|
222
|
+
*/
|
|
223
|
+
function asciiLocation(location) {
|
|
224
|
+
try {
|
|
225
|
+
return location.replace(NOT_HEADER_ASCII, encodeURIComponent);
|
|
226
|
+
}
|
|
227
|
+
catch (error) {
|
|
228
|
+
// A lone surrogate has no UTF-8 form (URIError): the value goes on as it is and Node refuses
|
|
229
|
+
// it, which is answered and logged as the 500 it is (#fail).
|
|
230
|
+
if (error instanceof URIError)
|
|
231
|
+
return location;
|
|
232
|
+
throw error;
|
|
233
|
+
}
|
|
234
|
+
}
|
|
169
235
|
/** The shared 'end' listener of a request whose body is timed (`this` is the raw request). */
|
|
170
236
|
function clearBodyTimer() {
|
|
171
237
|
if (this[BODY_TIMER] !== undefined) {
|
|
@@ -636,8 +702,12 @@ class WebOwner {
|
|
|
636
702
|
// requestTimeoutMs bounds the body: one timer while a body is arriving, so the answer is
|
|
637
703
|
// web's 408 REQUEST_TIMEOUT on time (Node's own check runs every 30 s and is set past
|
|
638
704
|
// every body time at start, see #nodeTimeouts; HTTP/2 has none at all).
|
|
639
|
-
if (!request.raw.complete && bodyFollows(request))
|
|
705
|
+
if (!request.raw.complete && bodyFollows(request)) {
|
|
640
706
|
owner.#timeBody(request, reply, options.requestTimeoutMs);
|
|
707
|
+
// HTTP/2: an aborted stream must not read as a complete body (abortedStream).
|
|
708
|
+
if (!http1(request))
|
|
709
|
+
request.raw.once('aborted', abortedStream);
|
|
710
|
+
}
|
|
641
711
|
// A sealed form marker on a body that is not sealed (or multipart) is refused before any
|
|
642
712
|
// parser too (D-0092 §1.3): the marker promises a body of the urlencoded shape.
|
|
643
713
|
if (request.headers[FORM_SUBMISSION_HEADER] !== undefined) {
|
|
@@ -678,6 +748,14 @@ class WebOwner {
|
|
|
678
748
|
lingerOnClose(request.raw, options.linger, this.context.logger);
|
|
679
749
|
}
|
|
680
750
|
const status = reply.statusCode;
|
|
751
|
+
if (status >= 300 && status < 400) {
|
|
752
|
+
// An address with spaces or non-ASCII characters is written percent-encoded (R9-g13-8).
|
|
753
|
+
const location = reply.getHeader('location');
|
|
754
|
+
if (typeof location === 'string' && NOT_HEADER_ASCII.test(location)) {
|
|
755
|
+
NOT_HEADER_ASCII.lastIndex = 0;
|
|
756
|
+
reply.header('location', asciiLocation(location));
|
|
757
|
+
}
|
|
758
|
+
}
|
|
681
759
|
// A redirect of a sealed form (D-0092 §1.2) is told, not followed: the forms module's fetch
|
|
682
760
|
// would follow it itself — rendering the next page (and taking its flash) for nothing, and
|
|
683
761
|
// failing on another origin — so the answer is 204 with the target in x-dokebi-location.
|
|
@@ -1103,6 +1181,9 @@ class WebOwner {
|
|
|
1103
1181
|
// 'close' fires once per response, so the listener is not removed (one call saved).
|
|
1104
1182
|
if (this.#draining && this.#worker)
|
|
1105
1183
|
this.#closeAfterResponse(response);
|
|
1184
|
+
// The connection no longer points at this response (it kept the whole request alive until
|
|
1185
|
+
// the client's next one: connections.ts `released`).
|
|
1186
|
+
this.#connections.released(response);
|
|
1106
1187
|
const reply = response[REPLY];
|
|
1107
1188
|
// Written (finished, or at least its head: the rest needs no user code) or hijacked: done.
|
|
1108
1189
|
if (response.writableFinished || response.headersSent || reply === undefined || reply.sent) {
|
|
@@ -1121,6 +1202,13 @@ class WebOwner {
|
|
|
1121
1202
|
handler: response[HANDLER] !== undefined,
|
|
1122
1203
|
sending: response[SENDING] === true,
|
|
1123
1204
|
});
|
|
1205
|
+
// Its body, if still unread, never arrives: the reader fails instead of taking the part that
|
|
1206
|
+
// came (HTTP/2) or waiting for ever on a dead stream (a reader that attaches later).
|
|
1207
|
+
if (incoming !== undefined && abandonBody(incoming) && logger.isEnabled('debug'))
|
|
1208
|
+
logger.log('debug', 'HTTP request body abandoned: the client left', {
|
|
1209
|
+
method: reply.request.method,
|
|
1210
|
+
route: reply.request.routeOptions.url ?? 'unmatched',
|
|
1211
|
+
});
|
|
1124
1212
|
response[ABORTED] = new AbortedResponse(response, (reason) => {
|
|
1125
1213
|
if (logger.isEnabled('debug'))
|
|
1126
1214
|
logger.log('debug', 'HTTP request without client finished', {
|
|
@@ -1653,6 +1741,16 @@ class WebOwner {
|
|
|
1653
1741
|
const pass = (raw[ERROR_PASS] ?? 0) + 1;
|
|
1654
1742
|
raw[ERROR_PASS] = pass;
|
|
1655
1743
|
this.#nextHandler(reply, pass);
|
|
1744
|
+
// A header Node refused when the head was written (`reply.header('x-name', '홍길동')`: past
|
|
1745
|
+
// U+00FF, or a line break) is still on the reply: the error answer failed on it again and the
|
|
1746
|
+
// client got a dropped connection. It is left out of the error answer; the error is logged
|
|
1747
|
+
// below with the header's name (audit r9, R9-g13-8).
|
|
1748
|
+
const refusal = thrown?.code;
|
|
1749
|
+
if (refusal === 'ERR_INVALID_CHAR' || refusal === 'ERR_INVALID_HTTP_TOKEN') {
|
|
1750
|
+
const name = /\["([^"]+)"\]/.exec(String(thrown.message))?.[1];
|
|
1751
|
+
if (name !== undefined && reply.hasHeader(name))
|
|
1752
|
+
reply.removeHeader(name);
|
|
1753
|
+
}
|
|
1656
1754
|
if (pass > 1) {
|
|
1657
1755
|
if (logger.isEnabled('debug'))
|
|
1658
1756
|
logger.log('debug', 'HTTP error raised while sending an error answer', {
|
|
@@ -2496,7 +2594,7 @@ class WebRuntime {
|
|
|
2496
2594
|
}
|
|
2497
2595
|
export const createPlugin = definePlugin({
|
|
2498
2596
|
name: 'dokebi-web',
|
|
2499
|
-
version: '0.4.
|
|
2597
|
+
version: '0.4.7',
|
|
2500
2598
|
core: '^0.4.2',
|
|
2501
2599
|
options: declaration,
|
|
2502
2600
|
entry: (input) => new WebEntryInput(input),
|