@dokebi/web 0.4.2 → 0.4.3
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 +248 -39
- package/README.md +31 -10
- package/dist/app-routes.d.ts +20 -0
- package/dist/app-routes.js +137 -0
- package/dist/before-hijack.d.ts +24 -0
- package/dist/before-hijack.js +73 -0
- package/dist/body.d.ts +14 -0
- package/dist/body.js +30 -0
- package/dist/cluster-ready.d.ts +67 -0
- package/dist/cluster-ready.js +123 -0
- package/dist/compilers.d.ts +16 -0
- package/dist/compilers.js +25 -0
- package/dist/compression.d.ts +40 -0
- package/dist/compression.js +435 -0
- package/dist/connections.d.ts +44 -0
- package/dist/connections.js +282 -0
- package/dist/define-errors.d.ts +76 -0
- package/dist/define-errors.js +161 -0
- package/dist/describe.d.ts +37 -0
- package/dist/describe.js +96 -0
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +24 -3
- package/dist/forms.d.ts +23 -7
- package/dist/forms.js +53 -13
- package/dist/index.d.ts +134 -4
- package/dist/index.js +1518 -91
- package/dist/options.d.ts +56 -0
- package/dist/options.js +320 -1
- package/dist/points.d.ts +159 -0
- package/dist/points.js +162 -1
- package/dist/responses.d.ts +31 -6
- package/dist/responses.js +68 -6
- package/dist/route-config.d.ts +38 -0
- package/dist/route-config.js +222 -0
- package/dist/route-hooks.d.ts +75 -0
- package/dist/route-hooks.js +118 -0
- package/dist/route-table.d.ts +55 -0
- package/dist/route-table.js +142 -0
- package/dist/seal.d.ts +49 -1
- package/dist/seal.js +259 -24
- package/dist/security-headers.d.ts +121 -0
- package/dist/security-headers.js +298 -0
- package/dist/transient-log.d.ts +42 -0
- package/dist/transient-log.js +95 -0
- package/options.schema.json +488 -1
- package/package.json +22 -9
package/dist/compilers.js
CHANGED
|
@@ -38,6 +38,31 @@ function once(name) {
|
|
|
38
38
|
return builder;
|
|
39
39
|
};
|
|
40
40
|
}
|
|
41
|
+
/**
|
|
42
|
+
* Fastify's symbols of the error handler chain (lib/symbols.js of the pinned fastify):
|
|
43
|
+
* `kErrorHandler` holds an instance's handler object, `kReplyNextErrorHandler` the one a reply's
|
|
44
|
+
* next error goes to (lib/error-handler.js). dokebi-web points the latter back at itself while it
|
|
45
|
+
* sends its own error answer, so an error raised then (an onSend step's) is answered by it too.
|
|
46
|
+
*/
|
|
47
|
+
export function errorHandlerSymbols() {
|
|
48
|
+
const { kErrorHandler, kReplyNextErrorHandler } = fromFastify('./lib/symbols.js');
|
|
49
|
+
if (typeof kErrorHandler !== 'symbol' || typeof kReplyNextErrorHandler !== 'symbol')
|
|
50
|
+
// Only a Fastify other than the pinned one gets here.
|
|
51
|
+
throw new Error('Fastify error handler symbols not found: @dokebi/web needs the fastify version it pins');
|
|
52
|
+
return { kErrorHandler, kReplyNextErrorHandler };
|
|
53
|
+
}
|
|
54
|
+
/**
|
|
55
|
+
* `kRouteContext` holds a reply's route context (lib/symbols.js); its `config` is the route's
|
|
56
|
+
* config as Fastify copied it. `request.routeOptions` builds a new object on every read, so the
|
|
57
|
+
* per-request read of a route's `completed` observers goes through the context.
|
|
58
|
+
*/
|
|
59
|
+
export function routeContextSymbol() {
|
|
60
|
+
const { kRouteContext } = fromFastify('./lib/symbols.js');
|
|
61
|
+
if (typeof kRouteContext !== 'symbol')
|
|
62
|
+
// Only a Fastify other than the pinned one gets here.
|
|
63
|
+
throw new Error('Fastify route context symbol not found: @dokebi/web needs the fastify version it pins');
|
|
64
|
+
return kRouteContext;
|
|
65
|
+
}
|
|
41
66
|
/**
|
|
42
67
|
* After `fastify()`: when the server uses `controller` (not an extension's own), mark its compilers
|
|
43
68
|
* as the defaults again so header schemas keep Fastify's case-insensitive names.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import type { Logger } from '@dokebi/core';
|
|
2
|
+
import type { FastifyReply, FastifyRequest } from 'fastify';
|
|
3
|
+
/** A content coding dokebi-web can produce. */
|
|
4
|
+
export type WebCompressionEncoding = 'br' | 'gzip';
|
|
5
|
+
/** The parsed `compression` options of dokebi-web. */
|
|
6
|
+
export interface WebCompressionOptions {
|
|
7
|
+
readonly enabled: boolean;
|
|
8
|
+
readonly thresholdBytes: number;
|
|
9
|
+
readonly brotliQuality: number;
|
|
10
|
+
readonly gzipLevel: number;
|
|
11
|
+
readonly encodings: readonly WebCompressionEncoding[];
|
|
12
|
+
readonly maxBufferBytes: number;
|
|
13
|
+
readonly maxPending: number;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Leaves this one response uncompressed (D-0125), for example a page that reflects request input
|
|
17
|
+
* next to a secret of its own (BREACH). Call it before the reply is sent.
|
|
18
|
+
*/
|
|
19
|
+
export declare function skipCompression(reply: FastifyReply): FastifyReply;
|
|
20
|
+
/** Whether a media type (lower case, no parameters) is worth compressing. */
|
|
21
|
+
export declare function compressibleType(type: string): boolean;
|
|
22
|
+
/**
|
|
23
|
+
* The coding to answer with for an Accept-Encoding value (RFC 9110 §12.5.3), or undefined for
|
|
24
|
+
* identity. The client's highest q wins; equal q values go to the first of `encodings` (the
|
|
25
|
+
* server's order). `*` stands for every coding not named; q=0 refuses one. An `identity` the
|
|
26
|
+
* client names with a higher q than every coding is honoured. No header: identity.
|
|
27
|
+
*/
|
|
28
|
+
export declare function negotiateEncoding(header: string | undefined, encodings: readonly WebCompressionEncoding[]): WebCompressionEncoding | undefined;
|
|
29
|
+
type Done = (error: Error | null, payload?: unknown) => void;
|
|
30
|
+
export declare class ResponseCompression {
|
|
31
|
+
#private;
|
|
32
|
+
readonly options: WebCompressionOptions;
|
|
33
|
+
/** The onSend hook, bound once (route-level, after every scope hook). */
|
|
34
|
+
readonly hook: (request: FastifyRequest, reply: FastifyReply, payload: unknown, done: Done) => void;
|
|
35
|
+
constructor(options: WebCompressionOptions, logger: Logger, hooks: {
|
|
36
|
+
readonly draining: () => boolean;
|
|
37
|
+
readonly sealType: () => string | undefined;
|
|
38
|
+
}, logRepeatWindowMs: number);
|
|
39
|
+
}
|
|
40
|
+
export {};
|
|
@@ -0,0 +1,435 @@
|
|
|
1
|
+
import { pipeline, Readable } from 'node:stream';
|
|
2
|
+
import zlib from 'node:zlib';
|
|
3
|
+
import { diagnostics } from '@dokebi/core/libraries';
|
|
4
|
+
const { describeError, Repeats } = diagnostics;
|
|
5
|
+
/** Marks a response that must leave uncompressed (`skipCompression`). */
|
|
6
|
+
const SKIP = Symbol('dokebi.web.compression.skip');
|
|
7
|
+
/** The coding this step put on a response, so a second onSend pass (an error answer) undoes it. */
|
|
8
|
+
const APPLIED = Symbol('dokebi.web.compression.applied');
|
|
9
|
+
/**
|
|
10
|
+
* Leaves this one response uncompressed (D-0125), for example a page that reflects request input
|
|
11
|
+
* next to a secret of its own (BREACH). Call it before the reply is sent.
|
|
12
|
+
*/
|
|
13
|
+
export function skipCompression(reply) {
|
|
14
|
+
reply.raw[SKIP] = true;
|
|
15
|
+
return reply;
|
|
16
|
+
}
|
|
17
|
+
/** Media types that compress (text, JSON, JS, CSS, SVG, XML, wasm). */
|
|
18
|
+
const COMPRESSIBLE_APPLICATION = new Set([
|
|
19
|
+
'application/json',
|
|
20
|
+
'application/javascript',
|
|
21
|
+
'application/x-javascript',
|
|
22
|
+
'application/ecmascript',
|
|
23
|
+
'application/xml',
|
|
24
|
+
'application/xhtml+xml',
|
|
25
|
+
'application/wasm',
|
|
26
|
+
'application/graphql',
|
|
27
|
+
'application/x-www-form-urlencoded',
|
|
28
|
+
]);
|
|
29
|
+
/** SSE needs every event flushed as it is written (D-0125): never compressed here. */
|
|
30
|
+
const EVENT_STREAM = 'text/event-stream';
|
|
31
|
+
/** Whether a media type (lower case, no parameters) is worth compressing. */
|
|
32
|
+
export function compressibleType(type) {
|
|
33
|
+
if (type === '' || type === EVENT_STREAM)
|
|
34
|
+
return false;
|
|
35
|
+
if (type.startsWith('text/'))
|
|
36
|
+
return true;
|
|
37
|
+
if (type === 'image/svg+xml')
|
|
38
|
+
return true;
|
|
39
|
+
if (!type.startsWith('application/'))
|
|
40
|
+
return false;
|
|
41
|
+
if (COMPRESSIBLE_APPLICATION.has(type))
|
|
42
|
+
return true;
|
|
43
|
+
return type.endsWith('+json') || type.endsWith('+xml');
|
|
44
|
+
}
|
|
45
|
+
/** The media type of a Content-Type value: lower case, without parameters. */
|
|
46
|
+
function mediaTypeOf(value) {
|
|
47
|
+
const text = Array.isArray(value) ? value[0] : value;
|
|
48
|
+
if (typeof text !== 'string')
|
|
49
|
+
return '';
|
|
50
|
+
const end = text.indexOf(';');
|
|
51
|
+
return (end === -1 ? text : text.slice(0, end)).trim().toLowerCase();
|
|
52
|
+
}
|
|
53
|
+
/** A qvalue (RFC 9110 §12.4.2): 0 to 1 with at most three decimals; NaN when malformed. */
|
|
54
|
+
const QVALUE = /^(?:0(?:\.\d{0,3})?|1(?:\.0{0,3})?)$/;
|
|
55
|
+
/**
|
|
56
|
+
* The coding to answer with for an Accept-Encoding value (RFC 9110 §12.5.3), or undefined for
|
|
57
|
+
* identity. The client's highest q wins; equal q values go to the first of `encodings` (the
|
|
58
|
+
* server's order). `*` stands for every coding not named; q=0 refuses one. An `identity` the
|
|
59
|
+
* client names with a higher q than every coding is honoured. No header: identity.
|
|
60
|
+
*/
|
|
61
|
+
export function negotiateEncoding(header, encodings) {
|
|
62
|
+
if (header === undefined || header === '')
|
|
63
|
+
return undefined;
|
|
64
|
+
let star;
|
|
65
|
+
let identity;
|
|
66
|
+
let br;
|
|
67
|
+
let gzip;
|
|
68
|
+
for (const part of header.split(',')) {
|
|
69
|
+
const semicolon = part.indexOf(';');
|
|
70
|
+
const token = (semicolon === -1 ? part : part.slice(0, semicolon)).trim().toLowerCase();
|
|
71
|
+
if (token === '')
|
|
72
|
+
continue;
|
|
73
|
+
let q = 1;
|
|
74
|
+
if (semicolon !== -1) {
|
|
75
|
+
const parameter = /^\s*q\s*=\s*([^\s;]*)\s*$/i.exec(part.slice(semicolon + 1));
|
|
76
|
+
// A malformed or foreign parameter makes the entry unusable: it is left out.
|
|
77
|
+
if (!parameter || !QVALUE.test(parameter[1]))
|
|
78
|
+
continue;
|
|
79
|
+
q = Number(parameter[1]);
|
|
80
|
+
}
|
|
81
|
+
if (token === 'br')
|
|
82
|
+
br = Math.max(br ?? 0, q);
|
|
83
|
+
else if (token === 'gzip' || token === 'x-gzip')
|
|
84
|
+
gzip = Math.max(gzip ?? 0, q);
|
|
85
|
+
else if (token === 'identity')
|
|
86
|
+
identity = Math.max(identity ?? 0, q);
|
|
87
|
+
else if (token === '*')
|
|
88
|
+
star = Math.max(star ?? 0, q);
|
|
89
|
+
}
|
|
90
|
+
let best;
|
|
91
|
+
let bestQ = 0;
|
|
92
|
+
for (const encoding of encodings) {
|
|
93
|
+
const q = (encoding === 'br' ? br : gzip) ?? star ?? 0;
|
|
94
|
+
if (q > bestQ) {
|
|
95
|
+
best = encoding;
|
|
96
|
+
bestQ = q;
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
if (best !== undefined && identity !== undefined && identity > bestQ)
|
|
100
|
+
return undefined;
|
|
101
|
+
return best;
|
|
102
|
+
}
|
|
103
|
+
/** Appends `Accept-Encoding` to Vary unless it (or `*`) is already there. */
|
|
104
|
+
function addVary(reply) {
|
|
105
|
+
const existing = reply.getHeader('vary');
|
|
106
|
+
if (existing === undefined || existing === '') {
|
|
107
|
+
reply.header('vary', 'Accept-Encoding');
|
|
108
|
+
return;
|
|
109
|
+
}
|
|
110
|
+
const text = Array.isArray(existing) ? existing.join(', ') : String(existing);
|
|
111
|
+
for (const part of text.split(',')) {
|
|
112
|
+
const name = part.trim().toLowerCase();
|
|
113
|
+
if (name === '*' || name === 'accept-encoding')
|
|
114
|
+
return;
|
|
115
|
+
}
|
|
116
|
+
reply.header('vary', `${text}, Accept-Encoding`);
|
|
117
|
+
}
|
|
118
|
+
/** Headers of a compressed answer: coding, no length, a weak validator, no ranges. */
|
|
119
|
+
function markCompressed(reply, encoding) {
|
|
120
|
+
reply.header('content-encoding', encoding);
|
|
121
|
+
reply.removeHeader('content-length');
|
|
122
|
+
// The compressed bytes are another representation: a strong ETag would claim byte equality
|
|
123
|
+
// with the identity one (RFC 9110 §8.8.1), and its ranges are not served (206 stays identity).
|
|
124
|
+
const etag = reply.getHeader('etag');
|
|
125
|
+
if (typeof etag === 'string' && etag.startsWith('"'))
|
|
126
|
+
reply.header('etag', `W/${etag}`);
|
|
127
|
+
reply.removeHeader('accept-ranges');
|
|
128
|
+
reply.raw[APPLIED] = encoding;
|
|
129
|
+
}
|
|
130
|
+
export class ResponseCompression {
|
|
131
|
+
options;
|
|
132
|
+
#logger;
|
|
133
|
+
#draining;
|
|
134
|
+
/** The sealed-body media type (a ciphertext: never compressed), once a codec is registered. */
|
|
135
|
+
#sealType;
|
|
136
|
+
#failures;
|
|
137
|
+
#busy;
|
|
138
|
+
/** Compressions under way: one-shot jobs and open zlib streams. */
|
|
139
|
+
#pending = 0;
|
|
140
|
+
/** Content-Type value → compressible (a handful of values per app). */
|
|
141
|
+
#types = new Map();
|
|
142
|
+
/** Accept-Encoding value → coding (browsers send a few distinct values). */
|
|
143
|
+
#negotiated = new Map();
|
|
144
|
+
/** Compressed copies of immutable Buffers sent again (built assets): one per coding. */
|
|
145
|
+
#immutable = new WeakMap();
|
|
146
|
+
/** The onSend hook, bound once (route-level, after every scope hook). */
|
|
147
|
+
hook;
|
|
148
|
+
constructor(options, logger, hooks, logRepeatWindowMs) {
|
|
149
|
+
this.options = options;
|
|
150
|
+
this.#logger = logger;
|
|
151
|
+
this.#draining = hooks.draining;
|
|
152
|
+
this.#sealType = hooks.sealType;
|
|
153
|
+
this.#failures = new Repeats({ intervalMs: logRepeatWindowMs });
|
|
154
|
+
this.#busy = new Repeats({ intervalMs: logRepeatWindowMs });
|
|
155
|
+
this.hook = (request, reply, payload, done) => this.#onSend(request, reply, payload, done);
|
|
156
|
+
}
|
|
157
|
+
#onSend(request, reply, payload, done) {
|
|
158
|
+
const raw = reply.raw;
|
|
159
|
+
// A second pass over one response (an error answer after a failed stream or hook): the
|
|
160
|
+
// coding of the first pass no longer describes this body.
|
|
161
|
+
if (raw[APPLIED] !== undefined && reply.getHeader('content-encoding') === raw[APPLIED]) {
|
|
162
|
+
reply.removeHeader('content-encoding');
|
|
163
|
+
delete raw[APPLIED];
|
|
164
|
+
}
|
|
165
|
+
const head = request.method === 'HEAD';
|
|
166
|
+
const encoding = this.#verdict(request, reply, payload, head);
|
|
167
|
+
if (encoding === undefined) {
|
|
168
|
+
done(null, payload);
|
|
169
|
+
return;
|
|
170
|
+
}
|
|
171
|
+
if (head) {
|
|
172
|
+
// The headers a GET would get, no body: the compressed length is not known without the
|
|
173
|
+
// work, so there is no Content-Length (RFC 9110 §9.3.2 allows that).
|
|
174
|
+
markCompressed(reply, encoding);
|
|
175
|
+
done(null, payload !== null && typeof payload === 'object' && !Buffer.isBuffer(payload)
|
|
176
|
+
? payload
|
|
177
|
+
: null);
|
|
178
|
+
return;
|
|
179
|
+
}
|
|
180
|
+
if (typeof payload === 'string' || Buffer.isBuffer(payload)) {
|
|
181
|
+
const body = typeof payload === 'string' ? Buffer.from(payload) : payload;
|
|
182
|
+
if (body.length <= this.options.maxBufferBytes)
|
|
183
|
+
this.#compressBuffer(request, reply, body, encoding, done);
|
|
184
|
+
else
|
|
185
|
+
this.#compressStream(request, reply, Readable.from([body], { objectMode: false }), encoding, done, body.length);
|
|
186
|
+
return;
|
|
187
|
+
}
|
|
188
|
+
const stream = typeof payload.pipe === 'function'
|
|
189
|
+
? payload
|
|
190
|
+
: Readable.fromWeb(payload);
|
|
191
|
+
this.#compressStream(request, reply, stream, encoding, done, undefined);
|
|
192
|
+
}
|
|
193
|
+
/**
|
|
194
|
+
* The coding to compress this response with, or undefined: left alone, or sent as identity
|
|
195
|
+
* with `Vary: Accept-Encoding` (no coding accepted, draining, too many under way).
|
|
196
|
+
*/
|
|
197
|
+
#verdict(request, reply, payload, head) {
|
|
198
|
+
const raw = reply.raw;
|
|
199
|
+
if (raw[SKIP])
|
|
200
|
+
return undefined;
|
|
201
|
+
const status = reply.statusCode;
|
|
202
|
+
if (status < 200 || status === 204 || status === 206 || status === 304)
|
|
203
|
+
return undefined;
|
|
204
|
+
if (payload === null || payload === undefined) {
|
|
205
|
+
// Only Fastify's HEAD twin of a GET goes on without a body: it dropped the body and set
|
|
206
|
+
// the GET's length, which the threshold reads below.
|
|
207
|
+
if (!head)
|
|
208
|
+
return undefined;
|
|
209
|
+
}
|
|
210
|
+
else if (typeof payload === 'object' &&
|
|
211
|
+
!Buffer.isBuffer(payload) &&
|
|
212
|
+
typeof payload.pipe !== 'function' &&
|
|
213
|
+
typeof payload.getReader !== 'function')
|
|
214
|
+
// A fetch Response or anything else Fastify unpacks itself: left alone.
|
|
215
|
+
return undefined;
|
|
216
|
+
// Size first: most small answers end here, before any header is read.
|
|
217
|
+
const size = this.#size(reply, payload);
|
|
218
|
+
if (size === undefined
|
|
219
|
+
? payload === null || payload === undefined
|
|
220
|
+
: size < this.options.thresholdBytes)
|
|
221
|
+
return undefined;
|
|
222
|
+
const contentType = reply.getHeader('content-type');
|
|
223
|
+
if (!this.#compressible(contentType))
|
|
224
|
+
return undefined;
|
|
225
|
+
const coding = reply.getHeader('content-encoding');
|
|
226
|
+
if (coding !== undefined && coding !== '')
|
|
227
|
+
return undefined;
|
|
228
|
+
if (reply.hasHeader('content-range'))
|
|
229
|
+
return undefined;
|
|
230
|
+
const cacheControl = reply.getHeader('cache-control');
|
|
231
|
+
if (cacheControl !== undefined &&
|
|
232
|
+
/(?:^|[\s,])no-transform(?:$|[\s,;=])/i.test(String(cacheControl)))
|
|
233
|
+
return undefined;
|
|
234
|
+
// From here the answer depends on Accept-Encoding: caches must know.
|
|
235
|
+
addVary(reply);
|
|
236
|
+
const encoding = this.#encoding(request);
|
|
237
|
+
const debug = this.#logger.isEnabled('debug');
|
|
238
|
+
if (encoding === undefined)
|
|
239
|
+
return undefined;
|
|
240
|
+
if (this.#draining()) {
|
|
241
|
+
if (debug)
|
|
242
|
+
this.#logger.log('debug', 'Web compression skipped', { reason: 'draining', encoding });
|
|
243
|
+
return undefined;
|
|
244
|
+
}
|
|
245
|
+
if (this.#pending >= this.options.maxPending) {
|
|
246
|
+
const repeated = this.#busy.take('busy');
|
|
247
|
+
if (repeated !== undefined)
|
|
248
|
+
this.#logger.log('warn', 'Web compression skipped: too many under way', {
|
|
249
|
+
code: 'WEB_COMPRESSION_BUSY',
|
|
250
|
+
pending: this.#pending,
|
|
251
|
+
maxPending: this.options.maxPending,
|
|
252
|
+
fix: 'Answers go out uncompressed while maxPending compressions run. Raise compression.maxPending of dokebi-web, lower compression.brotliQuality / gzipLevel, or let a front proxy compress (compression.enabled: false).',
|
|
253
|
+
...(repeated ? { repeated } : {}),
|
|
254
|
+
});
|
|
255
|
+
return undefined;
|
|
256
|
+
}
|
|
257
|
+
return encoding;
|
|
258
|
+
}
|
|
259
|
+
/**
|
|
260
|
+
* The body size when known (a buffered body, else a Content-Length header), as far as the
|
|
261
|
+
* threshold needs it: a string answers a bound on the same side of the threshold.
|
|
262
|
+
*/
|
|
263
|
+
#size(reply, payload) {
|
|
264
|
+
if (typeof payload === 'string') {
|
|
265
|
+
// UTF-8 takes one to three bytes per UTF-16 unit: only a length between threshold ÷ 3 and
|
|
266
|
+
// the threshold needs the byte count (a scan of the whole body, 5 % of a 30 KB page's CPU).
|
|
267
|
+
const length = payload.length;
|
|
268
|
+
if (length >= this.options.thresholdBytes || length * 3 < this.options.thresholdBytes)
|
|
269
|
+
return length;
|
|
270
|
+
return Buffer.byteLength(payload);
|
|
271
|
+
}
|
|
272
|
+
if (Buffer.isBuffer(payload))
|
|
273
|
+
return payload.length;
|
|
274
|
+
const declared = reply.getHeader('content-length');
|
|
275
|
+
if (declared === undefined)
|
|
276
|
+
return undefined;
|
|
277
|
+
const length = Number(declared);
|
|
278
|
+
return Number.isSafeInteger(length) && length >= 0 ? length : undefined;
|
|
279
|
+
}
|
|
280
|
+
#compressible(contentType) {
|
|
281
|
+
if (contentType === undefined)
|
|
282
|
+
return false;
|
|
283
|
+
const key = String(contentType);
|
|
284
|
+
let known = this.#types.get(key);
|
|
285
|
+
if (known === undefined) {
|
|
286
|
+
const type = mediaTypeOf(contentType);
|
|
287
|
+
known = compressibleType(type) && type !== this.#sealType();
|
|
288
|
+
if (this.#types.size >= 256)
|
|
289
|
+
this.#types.clear();
|
|
290
|
+
this.#types.set(key, known);
|
|
291
|
+
}
|
|
292
|
+
return known;
|
|
293
|
+
}
|
|
294
|
+
#encoding(request) {
|
|
295
|
+
const header = request.headers['accept-encoding'];
|
|
296
|
+
if (header === undefined)
|
|
297
|
+
return undefined;
|
|
298
|
+
const text = Array.isArray(header) ? header.join(', ') : header;
|
|
299
|
+
const known = this.#negotiated.get(text);
|
|
300
|
+
if (known !== undefined)
|
|
301
|
+
return known ?? undefined;
|
|
302
|
+
const chosen = negotiateEncoding(text, this.options.encodings);
|
|
303
|
+
if (this.#negotiated.size >= 256)
|
|
304
|
+
this.#negotiated.clear();
|
|
305
|
+
if (text.length <= 256)
|
|
306
|
+
this.#negotiated.set(text, chosen ?? null);
|
|
307
|
+
return chosen;
|
|
308
|
+
}
|
|
309
|
+
#zlibOptions(encoding, size, stream) {
|
|
310
|
+
if (encoding === 'gzip')
|
|
311
|
+
return {
|
|
312
|
+
level: this.options.gzipLevel,
|
|
313
|
+
...(stream ? { flush: zlib.constants.Z_SYNC_FLUSH } : {}),
|
|
314
|
+
};
|
|
315
|
+
return {
|
|
316
|
+
...(stream ? { flush: zlib.constants.BROTLI_OPERATION_FLUSH } : {}),
|
|
317
|
+
params: {
|
|
318
|
+
[zlib.constants.BROTLI_PARAM_QUALITY]: this.options.brotliQuality,
|
|
319
|
+
[zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
|
|
320
|
+
...(size === undefined ? {} : { [zlib.constants.BROTLI_PARAM_SIZE_HINT]: size }),
|
|
321
|
+
},
|
|
322
|
+
};
|
|
323
|
+
}
|
|
324
|
+
/** One asynchronous zlib call (thread pool); identity when it fails or does not shrink the body. */
|
|
325
|
+
#compressBuffer(request, reply, body, encoding, done) {
|
|
326
|
+
const immutable = this.#immutableCopy(reply, body, encoding);
|
|
327
|
+
if (immutable !== undefined) {
|
|
328
|
+
markCompressed(reply, encoding);
|
|
329
|
+
done(null, immutable);
|
|
330
|
+
return;
|
|
331
|
+
}
|
|
332
|
+
this.#pending++;
|
|
333
|
+
const started = performance.now();
|
|
334
|
+
const finish = (error, result) => {
|
|
335
|
+
this.#pending--;
|
|
336
|
+
if (error) {
|
|
337
|
+
this.#failed(request, encoding, error);
|
|
338
|
+
done(null, body);
|
|
339
|
+
return;
|
|
340
|
+
}
|
|
341
|
+
const debug = this.#logger.isEnabled('debug');
|
|
342
|
+
if (result.length >= body.length) {
|
|
343
|
+
if (debug)
|
|
344
|
+
this.#logger.log('debug', 'Web compression skipped', {
|
|
345
|
+
reason: 'not-smaller',
|
|
346
|
+
encoding,
|
|
347
|
+
bytes: body.length,
|
|
348
|
+
compressed: result.length,
|
|
349
|
+
});
|
|
350
|
+
done(null, body);
|
|
351
|
+
return;
|
|
352
|
+
}
|
|
353
|
+
if (debug)
|
|
354
|
+
this.#logger.log('debug', 'Web response compressed', {
|
|
355
|
+
encoding,
|
|
356
|
+
bytes: body.length,
|
|
357
|
+
compressed: result.length,
|
|
358
|
+
ms: Math.round((performance.now() - started) * 100) / 100,
|
|
359
|
+
});
|
|
360
|
+
this.#remember(reply, body, encoding, result);
|
|
361
|
+
markCompressed(reply, encoding);
|
|
362
|
+
done(null, result);
|
|
363
|
+
};
|
|
364
|
+
if (encoding === 'br')
|
|
365
|
+
zlib.brotliCompress(body, this.#zlibOptions('br', body.length, false), finish);
|
|
366
|
+
else
|
|
367
|
+
zlib.gzip(body, this.#zlibOptions('gzip', undefined, false), finish);
|
|
368
|
+
}
|
|
369
|
+
/** The kept copy of an immutable Buffer (`Cache-Control: immutable`, sent again and again). */
|
|
370
|
+
#immutableCopy(reply, body, encoding) {
|
|
371
|
+
if (!this.#isImmutable(reply))
|
|
372
|
+
return undefined;
|
|
373
|
+
return this.#immutable.get(body)?.[encoding];
|
|
374
|
+
}
|
|
375
|
+
#remember(reply, body, encoding, result) {
|
|
376
|
+
if (!this.#isImmutable(reply))
|
|
377
|
+
return;
|
|
378
|
+
const copies = this.#immutable.get(body) ?? {};
|
|
379
|
+
copies[encoding] = result;
|
|
380
|
+
this.#immutable.set(body, copies);
|
|
381
|
+
}
|
|
382
|
+
#isImmutable(reply) {
|
|
383
|
+
const cacheControl = reply.getHeader('cache-control');
|
|
384
|
+
return (typeof cacheControl === 'string' && /(?:^|[\s,])immutable(?:$|[\s,])/i.test(cacheControl));
|
|
385
|
+
}
|
|
386
|
+
/** A zlib stream between the body and the response; Fastify pipes it (backpressure). */
|
|
387
|
+
#compressStream(request, reply, source, encoding, done, size) {
|
|
388
|
+
const options = this.#zlibOptions(encoding, size, true);
|
|
389
|
+
const compressor = encoding === 'br' ? zlib.createBrotliCompress(options) : zlib.createGzip(options);
|
|
390
|
+
this.#pending++;
|
|
391
|
+
const started = performance.now();
|
|
392
|
+
pipeline(source, compressor, (error) => {
|
|
393
|
+
this.#pending--;
|
|
394
|
+
// zlib counts what it was given; the compressed side is what the client received.
|
|
395
|
+
const bytes = compressor.bytesWritten;
|
|
396
|
+
if (!error) {
|
|
397
|
+
if (this.#logger.isEnabled('debug'))
|
|
398
|
+
this.#logger.log('debug', 'Web response stream compressed', {
|
|
399
|
+
encoding,
|
|
400
|
+
bytes,
|
|
401
|
+
ms: Math.round(performance.now() - started),
|
|
402
|
+
});
|
|
403
|
+
return;
|
|
404
|
+
}
|
|
405
|
+
// The client left (Fastify destroys the stream when the response closes): not a failure.
|
|
406
|
+
if (error.code === 'ERR_STREAM_PREMATURE_CLOSE') {
|
|
407
|
+
if (this.#logger.isEnabled('debug'))
|
|
408
|
+
this.#logger.log('debug', 'Web response stream compression ended early', {
|
|
409
|
+
encoding,
|
|
410
|
+
bytes,
|
|
411
|
+
});
|
|
412
|
+
return;
|
|
413
|
+
}
|
|
414
|
+
// The body stream failed: the response is cut (its head is out); the cause is logged here
|
|
415
|
+
// because Fastify's own logger is off (D-0047).
|
|
416
|
+
this.#failed(request, encoding, error);
|
|
417
|
+
});
|
|
418
|
+
markCompressed(reply, encoding);
|
|
419
|
+
done(null, compressor);
|
|
420
|
+
}
|
|
421
|
+
#failed(request, encoding, error) {
|
|
422
|
+
// The route pattern, read only on this failure path (no query values in the log).
|
|
423
|
+
const route = request.routeOptions.url ?? 'unmatched';
|
|
424
|
+
const repeated = this.#failures.take(`${request.method} ${route} ${encoding}`);
|
|
425
|
+
if (repeated !== undefined)
|
|
426
|
+
this.#logger.log('error', 'Web response compression failed', {
|
|
427
|
+
code: 'WEB_COMPRESSION_FAILED',
|
|
428
|
+
method: request.method,
|
|
429
|
+
route,
|
|
430
|
+
encoding,
|
|
431
|
+
error: describeError(error),
|
|
432
|
+
...(repeated ? { repeated } : {}),
|
|
433
|
+
});
|
|
434
|
+
}
|
|
435
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { EventEmitter } from 'node:events';
|
|
2
|
+
import type { ServerResponse } from 'node:http';
|
|
3
|
+
import type { Socket } from 'node:net';
|
|
4
|
+
import type { Logger } from '@dokebi/core';
|
|
5
|
+
export interface ConnectionsSettings {
|
|
6
|
+
/** HTTPS (HTTP runs on TLS sockets). */
|
|
7
|
+
readonly secure: boolean;
|
|
8
|
+
/** HTTP/2 (h2c, or TLS with or without allowHTTP1). */
|
|
9
|
+
readonly http2: boolean;
|
|
10
|
+
readonly logger: Logger;
|
|
11
|
+
}
|
|
12
|
+
/** The counts of a sweep: connections ended, and kept (a request under way, or upgraded). */
|
|
13
|
+
export interface SweepCounts {
|
|
14
|
+
readonly ended: number;
|
|
15
|
+
readonly kept: number;
|
|
16
|
+
}
|
|
17
|
+
export declare class WebConnections {
|
|
18
|
+
#private;
|
|
19
|
+
constructor(server: EventEmitter, settings: ConnectionsSettings);
|
|
20
|
+
/** Open connections (tests, logs and a draining worker's idle wait). */
|
|
21
|
+
get size(): number;
|
|
22
|
+
/** Resolves when the next connection ends. */
|
|
23
|
+
changed(): Promise<void>;
|
|
24
|
+
/**
|
|
25
|
+
* Close (after the drain): ends every connection that answers no request and was not
|
|
26
|
+
* upgraded, tells an HTTP/2 session with streams under way to go away (GOAWAY: it ends once
|
|
27
|
+
* they end), and from now on ends a connection once its last response ends and every
|
|
28
|
+
* connection accepted at once. A response under way is left to finish.
|
|
29
|
+
*/
|
|
30
|
+
close(): SweepCounts;
|
|
31
|
+
/**
|
|
32
|
+
* A draining node:cluster worker (D-0036, D-0107 §1), once per drain: every HTTP/2 session is
|
|
33
|
+
* told to go away (its streams under way finish); the caller sweeps idle HTTP/1 connections.
|
|
34
|
+
*/
|
|
35
|
+
goAway(): number;
|
|
36
|
+
/**
|
|
37
|
+
* A draining worker's response ended: its HTTP/1 connection is ended when it answers no
|
|
38
|
+
* other request (a socket Node is already ending, or that is gone, is left alone). An HTTP/2
|
|
39
|
+
* response's session went away in goAway(). Returns the ended socket.
|
|
40
|
+
*/
|
|
41
|
+
endIfIdle(response: ServerResponse): Socket | undefined;
|
|
42
|
+
/** The drain deadline or a forced stop: every connection but upgraded ones is cut. */
|
|
43
|
+
cut(): number;
|
|
44
|
+
}
|