@fastify/sse 0.3.0 → 0.5.0
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/.github/dependabot.yml +42 -2
- package/.github/workflows/ci.yml +6 -1
- package/.github/workflows/lock-threads.yml +19 -0
- package/LICENSE +22 -0
- package/README.md +149 -40
- package/bench/accept-header.js +344 -0
- package/bench/in-context.js +210 -0
- package/benching.md +106 -0
- package/eslint.config.js +5 -2
- package/examples/basic.js +130 -88
- package/examples/manual-streaming.js +81 -0
- package/index.js +355 -84
- package/package.json +13 -12
- package/test/basic.test.js +264 -16
- package/test/custom-headers.test.js +0 -6
- package/test/imports.test.js +50 -0
- package/test/lifecycle.test.js +0 -10
- package/test/manual.test.js +205 -0
- package/test/send-headers.test.js +263 -0
- package/types/index.d.ts +56 -11
- package/types/index.tst.ts +233 -0
- package/.github/.stale.yml +0 -21
- package/.github/tests_checker.yml +0 -8
- package/.github/workflows/package-manager-ci.yml +0 -24
- package/test-types/index.test-d.ts +0 -192
|
@@ -0,0 +1,344 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
// Isolated micro-benchmark for clientAcceptsSSE (the gate function only,
|
|
4
|
+
// no fastify request handling — see bench/in-context.js for that).
|
|
5
|
+
//
|
|
6
|
+
// Compares:
|
|
7
|
+
// before — implementation as it existed before the optimization commit
|
|
8
|
+
// (split / toLowerCase / trim / rest-params / parseFloat)
|
|
9
|
+
// after — current optimized implementation (zero-alloc fast path +
|
|
10
|
+
// char-walking slow path)
|
|
11
|
+
// without — `() => true`, baseline showing the cost of not gating
|
|
12
|
+
//
|
|
13
|
+
// Methodology: for each impl × input combination, we
|
|
14
|
+
// 1. warm up,
|
|
15
|
+
// 2. calibrate iterations so a single sample takes ~CALIBRATION_TARGET_MS,
|
|
16
|
+
// 3. collect SAMPLE_COUNT independent samples,
|
|
17
|
+
// 4. report mean / median / p5 / p95 / stddev / RSD over the samples.
|
|
18
|
+
//
|
|
19
|
+
// Run with: `node bench/accept-header.js`
|
|
20
|
+
|
|
21
|
+
const { performance } = require('perf_hooks')
|
|
22
|
+
|
|
23
|
+
// =============================================================================
|
|
24
|
+
// Implementations
|
|
25
|
+
// =============================================================================
|
|
26
|
+
|
|
27
|
+
// ---- main: substring gate as shipped on `main` before this PR ----
|
|
28
|
+
// `acceptHeader.includes('text/event-stream')` — not spec-compliant (refuses
|
|
29
|
+
// `*/*`, admits anything containing the substring even mid-token, ignores
|
|
30
|
+
// q=0) but very cheap. Included for "what does the gate alone cost on main".
|
|
31
|
+
function main (acceptHeader) {
|
|
32
|
+
return (acceptHeader || '').includes('text/event-stream')
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
// ---- before: this branch's first iteration of spec-compliant parsing ----
|
|
36
|
+
// Heavy: split / toLowerCase / trim / rest-params / parseFloat.
|
|
37
|
+
|
|
38
|
+
function before (acceptHeader, options) {
|
|
39
|
+
const strict = options?.strict === true
|
|
40
|
+
if (!acceptHeader) return !strict
|
|
41
|
+
|
|
42
|
+
let bestSpecificity = -1
|
|
43
|
+
let bestQuality = 0
|
|
44
|
+
|
|
45
|
+
for (const part of acceptHeader.split(',')) {
|
|
46
|
+
const [rawType, ...params] = part.split(';')
|
|
47
|
+
const type = rawType.trim().toLowerCase()
|
|
48
|
+
|
|
49
|
+
let specificity
|
|
50
|
+
if (type === 'text/event-stream') specificity = 3
|
|
51
|
+
else if (!strict && type === 'text/*') specificity = 2
|
|
52
|
+
else if (!strict && type === '*/*') specificity = 1
|
|
53
|
+
else continue
|
|
54
|
+
|
|
55
|
+
let quality = 1
|
|
56
|
+
for (const p of params) {
|
|
57
|
+
const eq = p.indexOf('=')
|
|
58
|
+
if (eq === -1) continue
|
|
59
|
+
const key = p.slice(0, eq).trim().toLowerCase()
|
|
60
|
+
if (key !== 'q') continue
|
|
61
|
+
const parsed = Number.parseFloat(p.slice(eq + 1).trim())
|
|
62
|
+
if (Number.isFinite(parsed) && parsed >= 0 && parsed <= 1) {
|
|
63
|
+
quality = parsed
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
if (specificity > bestSpecificity) {
|
|
68
|
+
bestSpecificity = specificity
|
|
69
|
+
bestQuality = quality
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
return bestSpecificity >= 0 && bestQuality > 0
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
// ---- after: current optimized implementation (mirrors index.js) ----
|
|
77
|
+
|
|
78
|
+
const CC_SP = 32
|
|
79
|
+
const CC_HT = 9
|
|
80
|
+
const CC_COMMA = 44
|
|
81
|
+
const CC_SEMI = 59
|
|
82
|
+
const CC_EQ = 61
|
|
83
|
+
const CC_DOT = 46
|
|
84
|
+
const CC_ZERO = 48
|
|
85
|
+
const CC_LOWER_Q = 113
|
|
86
|
+
const CC_UPPER_Q = 81
|
|
87
|
+
|
|
88
|
+
function ciEqualsAt (s, start, end, lower) {
|
|
89
|
+
if (end - start !== lower.length) return false
|
|
90
|
+
for (let j = 0; j < lower.length; j++) {
|
|
91
|
+
let c = s.charCodeAt(start + j)
|
|
92
|
+
if (c >= 65 && c <= 90) c |= 32
|
|
93
|
+
if (c !== lower.charCodeAt(j)) return false
|
|
94
|
+
}
|
|
95
|
+
return true
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
function isQValueZero (s, start, end) {
|
|
99
|
+
if (end <= start) return false
|
|
100
|
+
if (s.charCodeAt(start) !== CC_ZERO) return false
|
|
101
|
+
let i = start + 1
|
|
102
|
+
if (i < end && s.charCodeAt(i) === CC_DOT) {
|
|
103
|
+
i++
|
|
104
|
+
while (i < end) {
|
|
105
|
+
if (s.charCodeAt(i) !== CC_ZERO) return false
|
|
106
|
+
i++
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
return i === end
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
function after (acceptHeader, options) {
|
|
113
|
+
const strict = options !== undefined && options.strict === true
|
|
114
|
+
if (!acceptHeader) return !strict
|
|
115
|
+
|
|
116
|
+
if (acceptHeader === 'text/event-stream') return true
|
|
117
|
+
if (!strict && (acceptHeader === '*/*' || acceptHeader === 'text/*')) return true
|
|
118
|
+
|
|
119
|
+
const len = acceptHeader.length
|
|
120
|
+
let bestSpec = -1
|
|
121
|
+
let bestRefused = false
|
|
122
|
+
let i = 0
|
|
123
|
+
|
|
124
|
+
while (i < len) {
|
|
125
|
+
while (i < len) {
|
|
126
|
+
const c = acceptHeader.charCodeAt(i)
|
|
127
|
+
if (c !== CC_SP && c !== CC_HT) break
|
|
128
|
+
i++
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
const typeStart = i
|
|
132
|
+
while (i < len) {
|
|
133
|
+
const c = acceptHeader.charCodeAt(i)
|
|
134
|
+
if (c === CC_SEMI || c === CC_COMMA) break
|
|
135
|
+
i++
|
|
136
|
+
}
|
|
137
|
+
let typeEnd = i
|
|
138
|
+
while (typeEnd > typeStart) {
|
|
139
|
+
const c = acceptHeader.charCodeAt(typeEnd - 1)
|
|
140
|
+
if (c !== CC_SP && c !== CC_HT) break
|
|
141
|
+
typeEnd--
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
let spec = -1
|
|
145
|
+
if (ciEqualsAt(acceptHeader, typeStart, typeEnd, 'text/event-stream')) spec = 3
|
|
146
|
+
else if (!strict && ciEqualsAt(acceptHeader, typeStart, typeEnd, 'text/*')) spec = 2
|
|
147
|
+
else if (!strict && ciEqualsAt(acceptHeader, typeStart, typeEnd, '*/*')) spec = 1
|
|
148
|
+
|
|
149
|
+
let refused = false
|
|
150
|
+
if (spec === -1) {
|
|
151
|
+
while (i < len && acceptHeader.charCodeAt(i) !== CC_COMMA) i++
|
|
152
|
+
} else {
|
|
153
|
+
while (i < len && acceptHeader.charCodeAt(i) === CC_SEMI) {
|
|
154
|
+
i++
|
|
155
|
+
while (i < len) {
|
|
156
|
+
const c = acceptHeader.charCodeAt(i)
|
|
157
|
+
if (c !== CC_SP && c !== CC_HT) break
|
|
158
|
+
i++
|
|
159
|
+
}
|
|
160
|
+
const keyStart = i
|
|
161
|
+
while (i < len) {
|
|
162
|
+
const c = acceptHeader.charCodeAt(i)
|
|
163
|
+
if (c === CC_EQ || c === CC_SEMI || c === CC_COMMA) break
|
|
164
|
+
i++
|
|
165
|
+
}
|
|
166
|
+
const keyEnd = i
|
|
167
|
+
|
|
168
|
+
if (i < len && acceptHeader.charCodeAt(i) === CC_EQ) {
|
|
169
|
+
i++
|
|
170
|
+
const valStart = i
|
|
171
|
+
while (i < len) {
|
|
172
|
+
const c = acceptHeader.charCodeAt(i)
|
|
173
|
+
if (c === CC_SEMI || c === CC_COMMA) break
|
|
174
|
+
i++
|
|
175
|
+
}
|
|
176
|
+
const valEnd = i
|
|
177
|
+
|
|
178
|
+
if (keyEnd - keyStart === 1) {
|
|
179
|
+
const kc = acceptHeader.charCodeAt(keyStart)
|
|
180
|
+
if ((kc === CC_LOWER_Q || kc === CC_UPPER_Q) &&
|
|
181
|
+
isQValueZero(acceptHeader, valStart, valEnd)) {
|
|
182
|
+
refused = true
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
if (spec === 3 && !refused) return true
|
|
190
|
+
|
|
191
|
+
if (spec > bestSpec) {
|
|
192
|
+
bestSpec = spec
|
|
193
|
+
bestRefused = refused
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
if (i < len && acceptHeader.charCodeAt(i) === CC_COMMA) i++
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
return bestSpec >= 0 && !bestRefused
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
// ---- without: baseline ----
|
|
203
|
+
|
|
204
|
+
function without () { return true }
|
|
205
|
+
|
|
206
|
+
// =============================================================================
|
|
207
|
+
// Correctness sanity-check
|
|
208
|
+
// =============================================================================
|
|
209
|
+
|
|
210
|
+
const correctnessCases = [
|
|
211
|
+
undefined,
|
|
212
|
+
'',
|
|
213
|
+
'text/event-stream',
|
|
214
|
+
'*/*',
|
|
215
|
+
'text/*',
|
|
216
|
+
'application/json',
|
|
217
|
+
'text/event-stream;q=0',
|
|
218
|
+
'*/*, text/event-stream;q=0',
|
|
219
|
+
'text/event-stream, application/json;q=0.5',
|
|
220
|
+
'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8',
|
|
221
|
+
'Text/Event-Stream',
|
|
222
|
+
' text/event-stream '
|
|
223
|
+
]
|
|
224
|
+
|
|
225
|
+
for (const input of correctnessCases) {
|
|
226
|
+
for (const opts of [undefined, { strict: true }]) {
|
|
227
|
+
const b = before(input, opts)
|
|
228
|
+
const a = after(input, opts)
|
|
229
|
+
if (b !== a) {
|
|
230
|
+
console.error(`DISAGREE on ${JSON.stringify(input)} strict=${!!opts?.strict}: before=${b}, after=${a}`)
|
|
231
|
+
process.exit(1)
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
console.log('correctness: before and after agree on all sample inputs')
|
|
236
|
+
|
|
237
|
+
// =============================================================================
|
|
238
|
+
// Statistical bench harness
|
|
239
|
+
// =============================================================================
|
|
240
|
+
|
|
241
|
+
const WARMUP_ITER = 200_000
|
|
242
|
+
const CALIBRATION_TARGET_MS = 8
|
|
243
|
+
const SAMPLE_COUNT = 200
|
|
244
|
+
|
|
245
|
+
function calibrateIterations (fn, input) {
|
|
246
|
+
// Find how many iterations take ~CALIBRATION_TARGET_MS, given a quick probe.
|
|
247
|
+
let iter = 10_000
|
|
248
|
+
let elapsed = 0
|
|
249
|
+
while (elapsed < 2) {
|
|
250
|
+
const start = performance.now()
|
|
251
|
+
for (let i = 0; i < iter; i++) fn(input)
|
|
252
|
+
elapsed = performance.now() - start
|
|
253
|
+
if (elapsed < 0.5) iter *= 10
|
|
254
|
+
else break
|
|
255
|
+
}
|
|
256
|
+
// Scale iter to hit target.
|
|
257
|
+
const scaled = Math.max(1000, Math.round(iter * (CALIBRATION_TARGET_MS / Math.max(elapsed, 0.001))))
|
|
258
|
+
return scaled
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
function sample (fn, input, iterations) {
|
|
262
|
+
const start = performance.now()
|
|
263
|
+
for (let i = 0; i < iterations; i++) fn(input)
|
|
264
|
+
return iterations / ((performance.now() - start) / 1000)
|
|
265
|
+
}
|
|
266
|
+
|
|
267
|
+
function stats (samples) {
|
|
268
|
+
const sorted = samples.slice().sort((a, b) => a - b)
|
|
269
|
+
const n = sorted.length
|
|
270
|
+
const mean = samples.reduce((s, v) => s + v, 0) / n
|
|
271
|
+
const variance = samples.reduce((s, v) => s + (v - mean) ** 2, 0) / n
|
|
272
|
+
const stddev = Math.sqrt(variance)
|
|
273
|
+
return {
|
|
274
|
+
n,
|
|
275
|
+
mean,
|
|
276
|
+
median: sorted[Math.floor(n / 2)],
|
|
277
|
+
p5: sorted[Math.floor(n * 0.05)],
|
|
278
|
+
p95: sorted[Math.floor(n * 0.95)],
|
|
279
|
+
min: sorted[0],
|
|
280
|
+
max: sorted[n - 1],
|
|
281
|
+
stddev,
|
|
282
|
+
rsd: stddev / mean
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
|
|
286
|
+
function bench (fn, input) {
|
|
287
|
+
for (let i = 0; i < WARMUP_ITER; i++) fn(input)
|
|
288
|
+
const iter = calibrateIterations(fn, input)
|
|
289
|
+
// Extra warmup at the calibrated iteration count.
|
|
290
|
+
sample(fn, input, iter)
|
|
291
|
+
const samples = new Array(SAMPLE_COUNT)
|
|
292
|
+
for (let s = 0; s < SAMPLE_COUNT; s++) {
|
|
293
|
+
samples[s] = sample(fn, input, iter)
|
|
294
|
+
}
|
|
295
|
+
return { stats: stats(samples), iterPerSample: iter }
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
// =============================================================================
|
|
299
|
+
// Run
|
|
300
|
+
// =============================================================================
|
|
301
|
+
|
|
302
|
+
const benchCases = [
|
|
303
|
+
['undefined', undefined],
|
|
304
|
+
['text/event-stream', 'text/event-stream'],
|
|
305
|
+
['*/*', '*/*'],
|
|
306
|
+
['text/event-stream;q=0', 'text/event-stream;q=0'],
|
|
307
|
+
['mixed q-values', 'text/event-stream, application/json;q=0.5'],
|
|
308
|
+
['browser-like', 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8'],
|
|
309
|
+
['*/*, t/e-s;q=0', '*/*, text/event-stream;q=0']
|
|
310
|
+
]
|
|
311
|
+
|
|
312
|
+
const impls = [
|
|
313
|
+
['without', without],
|
|
314
|
+
['main ', main],
|
|
315
|
+
['before ', before],
|
|
316
|
+
['after ', after]
|
|
317
|
+
]
|
|
318
|
+
|
|
319
|
+
function fmtOps (n) { return Math.round(n).toLocaleString().padStart(15) }
|
|
320
|
+
function fmtPct (n) { return (n * 100).toFixed(2) + '%' }
|
|
321
|
+
function fmtNs (opsPerSec) { return (1e9 / opsPerSec).toFixed(1) + ' ns/op' }
|
|
322
|
+
|
|
323
|
+
console.log(`\nsamples per case: ${SAMPLE_COUNT} target ~${CALIBRATION_TARGET_MS}ms/sample warmup: ${WARMUP_ITER.toLocaleString()} iter\n`)
|
|
324
|
+
console.log('Each row: mean (median, p5..p95) ± stddev RSD ns/op (median) speedup-vs-before')
|
|
325
|
+
console.log('─'.repeat(120))
|
|
326
|
+
|
|
327
|
+
for (const [caseName, header] of benchCases) {
|
|
328
|
+
console.log(`\n=== ${caseName} ===`)
|
|
329
|
+
let beforeMedian = 0
|
|
330
|
+
for (const [implName, fn] of impls) {
|
|
331
|
+
const { stats: s, iterPerSample } = bench(fn, header)
|
|
332
|
+
if (implName.trim() === 'before') beforeMedian = s.median
|
|
333
|
+
const speedup = (implName.trim() === 'after' && beforeMedian > 0)
|
|
334
|
+
? ` ${(s.median / beforeMedian).toFixed(2)}x vs before`
|
|
335
|
+
: ''
|
|
336
|
+
console.log(
|
|
337
|
+
` ${implName} ${fmtOps(s.mean)} ` +
|
|
338
|
+
`(med ${fmtOps(s.median)}, p5 ${fmtOps(s.p5)}, p95 ${fmtOps(s.p95)}) ` +
|
|
339
|
+
`±${fmtOps(s.stddev)} RSD ${fmtPct(s.rsd).padStart(7)} ` +
|
|
340
|
+
`${fmtNs(s.median).padStart(11)} iter/sample=${iterPerSample.toLocaleString()}${speedup}`
|
|
341
|
+
)
|
|
342
|
+
}
|
|
343
|
+
}
|
|
344
|
+
console.log()
|
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
'use strict'
|
|
2
|
+
|
|
3
|
+
// In-context benchmark: full HTTP request roundtrip against a running
|
|
4
|
+
// fastify server. The isolated bench (bench/accept-header.js) measures
|
|
5
|
+
// the gate function in nanoseconds; this one shows what that gate costs
|
|
6
|
+
// as a *fraction of total request handling time*.
|
|
7
|
+
//
|
|
8
|
+
// Compared:
|
|
9
|
+
// pre-PR — the simple `acceptHeader.includes('text/event-stream')` gate
|
|
10
|
+
// that existed on `main` before the spec-compliant-header
|
|
11
|
+
// branch. Same plugin shape, no quality / specificity logic.
|
|
12
|
+
// current — the current optimized plugin loaded from ../index.js.
|
|
13
|
+
//
|
|
14
|
+
// Both routes are registered with `sse: true`. The handler returns
|
|
15
|
+
// `{ ok: true }` without writing SSE data, so we measure the gate path
|
|
16
|
+
// (and the surrounding fastify machinery) without paying for streaming
|
|
17
|
+
// on every iteration.
|
|
18
|
+
//
|
|
19
|
+
// We use a real localhost HTTP server with undici as the client rather
|
|
20
|
+
// than `fastify.inject` — inject accumulates significant heap across
|
|
21
|
+
// millions of calls, and a real socket roundtrip is closer to production.
|
|
22
|
+
//
|
|
23
|
+
// Run with: `node bench/in-context.js`
|
|
24
|
+
|
|
25
|
+
const { performance } = require('perf_hooks')
|
|
26
|
+
const Fastify = require('fastify')
|
|
27
|
+
const fp = require('fastify-plugin')
|
|
28
|
+
const { Client } = require('undici')
|
|
29
|
+
|
|
30
|
+
const currentPlugin = require('..')
|
|
31
|
+
|
|
32
|
+
// =============================================================================
|
|
33
|
+
// Pre-PR plugin: substring gate from `main` before this branch. Same shape
|
|
34
|
+
// as the current plugin's `onRoute` hook so the surrounding cost is equal.
|
|
35
|
+
// =============================================================================
|
|
36
|
+
|
|
37
|
+
async function prePRPlugin (fastify) {
|
|
38
|
+
fastify.addHook('onRoute', (routeOptions) => {
|
|
39
|
+
if (!routeOptions.sse) return
|
|
40
|
+
const originalHandler = routeOptions.handler
|
|
41
|
+
|
|
42
|
+
routeOptions.handler = async function sseHandler (request, reply) {
|
|
43
|
+
const acceptHeader = request.headers.accept || ''
|
|
44
|
+
if (!acceptHeader.includes('text/event-stream')) {
|
|
45
|
+
return await originalHandler.call(this, request, reply)
|
|
46
|
+
}
|
|
47
|
+
// Minimal SSE shim — handler returns immediately without streaming.
|
|
48
|
+
reply.sse = { send () {}, close () {}, get shouldKeepAlive () { return false } }
|
|
49
|
+
return await originalHandler.call(this, request, reply)
|
|
50
|
+
}
|
|
51
|
+
})
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
const prePRWrapped = fp(prePRPlugin, { fastify: '5.x', name: 'prePR-sse-bench' })
|
|
55
|
+
|
|
56
|
+
// =============================================================================
|
|
57
|
+
// Build apps + clients
|
|
58
|
+
// =============================================================================
|
|
59
|
+
|
|
60
|
+
async function buildApp (plugin) {
|
|
61
|
+
const fastify = Fastify({ logger: false, disableRequestLogging: true })
|
|
62
|
+
await fastify.register(plugin)
|
|
63
|
+
fastify.get('/events', { sse: true }, async () => ({ ok: true }))
|
|
64
|
+
await fastify.listen({ host: '127.0.0.1', port: 0 })
|
|
65
|
+
const address = fastify.server.address()
|
|
66
|
+
const origin = `http://127.0.0.1:${address.port}`
|
|
67
|
+
const client = new Client(origin, { pipelining: 1, keepAliveTimeout: 60_000 })
|
|
68
|
+
return { fastify, client }
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// =============================================================================
|
|
72
|
+
// Statistical sampler
|
|
73
|
+
// =============================================================================
|
|
74
|
+
|
|
75
|
+
const WARMUP_REQUESTS = 1_000
|
|
76
|
+
const SAMPLE_COUNT = 200
|
|
77
|
+
const CALIBRATION_TARGET_MS = 50
|
|
78
|
+
|
|
79
|
+
async function fireN (client, opts, n) {
|
|
80
|
+
for (let i = 0; i < n; i++) {
|
|
81
|
+
const res = await client.request(opts)
|
|
82
|
+
// Drain body so the socket can be reused.
|
|
83
|
+
await res.body.dump()
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
async function calibrate (client, opts) {
|
|
88
|
+
let iter = 200
|
|
89
|
+
let elapsed = 0
|
|
90
|
+
while (elapsed < 10) {
|
|
91
|
+
const start = performance.now()
|
|
92
|
+
await fireN(client, opts, iter)
|
|
93
|
+
elapsed = performance.now() - start
|
|
94
|
+
if (elapsed < 5) iter *= 4
|
|
95
|
+
else break
|
|
96
|
+
}
|
|
97
|
+
return Math.max(50, Math.round(iter * (CALIBRATION_TARGET_MS / Math.max(elapsed, 0.001))))
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
async function sample (client, opts, n) {
|
|
101
|
+
const start = performance.now()
|
|
102
|
+
await fireN(client, opts, n)
|
|
103
|
+
return n / ((performance.now() - start) / 1000)
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
function stats (samples) {
|
|
107
|
+
const sorted = samples.slice().sort((a, b) => a - b)
|
|
108
|
+
const n = sorted.length
|
|
109
|
+
const mean = samples.reduce((s, v) => s + v, 0) / n
|
|
110
|
+
const variance = samples.reduce((s, v) => s + (v - mean) ** 2, 0) / n
|
|
111
|
+
const stddev = Math.sqrt(variance)
|
|
112
|
+
return {
|
|
113
|
+
n,
|
|
114
|
+
mean,
|
|
115
|
+
median: sorted[Math.floor(n / 2)],
|
|
116
|
+
p5: sorted[Math.floor(n * 0.05)],
|
|
117
|
+
p95: sorted[Math.floor(n * 0.95)],
|
|
118
|
+
min: sorted[0],
|
|
119
|
+
max: sorted[n - 1],
|
|
120
|
+
stddev,
|
|
121
|
+
rsd: stddev / mean
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
async function bench (client, opts) {
|
|
126
|
+
await fireN(client, opts, WARMUP_REQUESTS)
|
|
127
|
+
const iter = await calibrate(client, opts)
|
|
128
|
+
await sample(client, opts, iter) // settle at calibrated size
|
|
129
|
+
const samples = new Array(SAMPLE_COUNT)
|
|
130
|
+
for (let s = 0; s < SAMPLE_COUNT; s++) {
|
|
131
|
+
samples[s] = await sample(client, opts, iter)
|
|
132
|
+
}
|
|
133
|
+
return { stats: stats(samples), iterPerSample: iter, totalRequests: iter * SAMPLE_COUNT }
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
// =============================================================================
|
|
137
|
+
// Cases — headers that yield equivalent behavior in both plugins (so we
|
|
138
|
+
// measure gate cost rather than behavior divergence).
|
|
139
|
+
// - `text/event-stream` and `t/e-s, app/json;q=0.5` both admit in both
|
|
140
|
+
// plugins; the handler is invoked through the SSE-admit path.
|
|
141
|
+
// - `*/*` and the browser-like header refuse in pre-PR (no substring
|
|
142
|
+
// match) and refuse in current (no explicit `text/event-stream`
|
|
143
|
+
// token under the strict legacy gate). In both, originalHandler runs
|
|
144
|
+
// and the gate cost is fully observed.
|
|
145
|
+
// =============================================================================
|
|
146
|
+
|
|
147
|
+
const cases = [
|
|
148
|
+
['text/event-stream ', 'text/event-stream'],
|
|
149
|
+
['t/e-s, app/json;q=0.5 ', 'text/event-stream, application/json;q=0.5'],
|
|
150
|
+
['*/* (refuse, fallthrough) ', '*/*'],
|
|
151
|
+
['browser-like (fallthrough)', 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8']
|
|
152
|
+
]
|
|
153
|
+
|
|
154
|
+
function mkOpts (accept) {
|
|
155
|
+
return { method: 'GET', path: '/events', headers: { accept, 'accept-encoding': 'identity' } }
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
function fmtOps (n) { return Math.round(n).toLocaleString().padStart(12) }
|
|
159
|
+
function fmtPct (n) { return (n * 100).toFixed(2) + '%' }
|
|
160
|
+
function fmtUs (opsPerSec) { return (1e6 / opsPerSec).toFixed(2) + ' µs/req' }
|
|
161
|
+
|
|
162
|
+
async function main () {
|
|
163
|
+
const pre = await buildApp(prePRWrapped)
|
|
164
|
+
const cur = await buildApp(currentPlugin)
|
|
165
|
+
|
|
166
|
+
// Sanity-check: both servers return 200 for every input.
|
|
167
|
+
for (const [, accept] of cases) {
|
|
168
|
+
const opts = mkOpts(accept)
|
|
169
|
+
const r1 = await pre.client.request(opts); await r1.body.dump()
|
|
170
|
+
const r2 = await cur.client.request(opts); await r2.body.dump()
|
|
171
|
+
if (r1.statusCode !== 200 || r2.statusCode !== 200) {
|
|
172
|
+
console.error(`unexpected status: pre=${r1.statusCode} cur=${r2.statusCode} for ${accept}`)
|
|
173
|
+
process.exit(1)
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
console.log('sanity-check: both servers return 200 for all sample inputs\n')
|
|
177
|
+
|
|
178
|
+
console.log(`samples per case: ${SAMPLE_COUNT} target ~${CALIBRATION_TARGET_MS}ms/sample warmup: ${WARMUP_REQUESTS.toLocaleString()} requests`)
|
|
179
|
+
console.log('Each row: mean (median, p5..p95) ± stddev RSD µs/req (median)')
|
|
180
|
+
console.log('─'.repeat(135))
|
|
181
|
+
|
|
182
|
+
for (const [name, accept] of cases) {
|
|
183
|
+
const opts = mkOpts(accept)
|
|
184
|
+
console.log(`\n=== ${name.trim()} ===`)
|
|
185
|
+
let preMedian = 0
|
|
186
|
+
for (const [label, app] of [['pre-PR ', pre], ['current', cur]]) {
|
|
187
|
+
const { stats: s, totalRequests } = await bench(app.client, opts)
|
|
188
|
+
if (label === 'pre-PR ') preMedian = s.median
|
|
189
|
+
const diff = (label === 'current' && preMedian > 0)
|
|
190
|
+
? ` ${(s.median / preMedian).toFixed(3)}x vs pre-PR (Δ ${((1e6 / s.median) - (1e6 / preMedian)).toFixed(2)} µs/req)`
|
|
191
|
+
: ''
|
|
192
|
+
console.log(
|
|
193
|
+
` ${label} ${fmtOps(s.mean)} req/s ` +
|
|
194
|
+
`(med ${fmtOps(s.median)}, p5 ${fmtOps(s.p5)}, p95 ${fmtOps(s.p95)}) ` +
|
|
195
|
+
`±${fmtOps(s.stddev)} RSD ${fmtPct(s.rsd).padStart(7)} ` +
|
|
196
|
+
`${fmtUs(s.median).padStart(14)} n=${totalRequests.toLocaleString()}${diff}`
|
|
197
|
+
)
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
await pre.client.close()
|
|
202
|
+
await cur.client.close()
|
|
203
|
+
await pre.fastify.close()
|
|
204
|
+
await cur.fastify.close()
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
main().catch((err) => {
|
|
208
|
+
console.error(err)
|
|
209
|
+
process.exit(1)
|
|
210
|
+
})
|
package/benching.md
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
# Benchmarking summary — spec-compliant Accept header handling
|
|
2
|
+
|
|
3
|
+
Captures the perf impact of replacing `main`'s substring `.includes('text/event-stream')` gate with an RFC 9110 §12.5.1 spec-compliant Accept-header parser, then optimizing the parser.
|
|
4
|
+
|
|
5
|
+
## TL;DR
|
|
6
|
+
|
|
7
|
+
- **Hot path** (literal `text/event-stream` — what 99%+ of real SSE clients send): **~7 ns/op, ~2x faster than `main`'s `.includes()` check.** A single `===` beats a substring search on a short string.
|
|
8
|
+
- **Slow path** (multi-entry headers / qvalues): 57–180 ns/op. 4–7x slower than `main`'s substring in raw function cost, but ≤0.04% of a request in context.
|
|
9
|
+
- **In context (full HTTP request)**: every case lands within **±2 % of `main`**. The new gate adds no measurable overhead to a real request.
|
|
10
|
+
- **Routes registered without `sse: …`**: **zero per-request cost.** The plugin's `onRoute` hook fires once at registration and returns immediately for non-SSE routes.
|
|
11
|
+
|
|
12
|
+
## What changed vs `main`
|
|
13
|
+
|
|
14
|
+
| Aspect | `main` | this branch |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| Algorithm | `acceptHeader.includes('text/event-stream')` | RFC 9110 §12.5.1 media-range parser |
|
|
17
|
+
| Admits `*/*` (lenient mode) | ❌ no | ✅ yes |
|
|
18
|
+
| Admits `text/*` (lenient mode) | ❌ no | ✅ yes |
|
|
19
|
+
| Honors `q=0` refuse | ❌ no (would still admit `text/event-stream;q=0`) | ✅ yes |
|
|
20
|
+
| Specificity tie-breaking (`*/*, text/event-stream;q=0`) | ❌ no | ✅ yes |
|
|
21
|
+
| Modes | only `sse: true` | `sse: true` (legacy) + `sse: 'only'` + `sse: 'dual'` |
|
|
22
|
+
|
|
23
|
+
## Methodology
|
|
24
|
+
|
|
25
|
+
Two benches under `bench/`. Both use the same statistical harness: warm up, calibrate iteration count so each sample takes ~target ms, take 200 independent samples, report mean / median / p5 / p95 / stddev / RSD.
|
|
26
|
+
|
|
27
|
+
- **`bench/accept-header.js`** — isolated function timing. Four implementations compared:
|
|
28
|
+
- `without` — `() => true` baseline. V8 dead-code-eliminates the call body, so this is the "no upper bound" reference point.
|
|
29
|
+
- `main` — `(acceptHeader || '').includes('text/event-stream')`. Shipped on `main`.
|
|
30
|
+
- `before` — this branch's first spec-compliant iteration (`.split()`, `.toLowerCase()`, `.trim()`, `parseFloat`).
|
|
31
|
+
- `after` — current optimized implementation (zero-alloc fast path + char-walking slow path).
|
|
32
|
+
- **`bench/in-context.js`** — real HTTP localhost server + undici client. Two plugin variants compared (`pre-PR` substring gate vs `current` optimized). Same route shape, same handler (`return { ok: true }`), same harness.
|
|
33
|
+
|
|
34
|
+
Run with `node bench/accept-header.js` and `node bench/in-context.js`.
|
|
35
|
+
|
|
36
|
+
## Isolated function timing — ns/op (median)
|
|
37
|
+
|
|
38
|
+
200 samples per case, ~8 ms per sample. RSD 1.5–6.6% across all rows.
|
|
39
|
+
|
|
40
|
+
### Hot path (literal Accept values that real clients emit)
|
|
41
|
+
|
|
42
|
+
| Input | `main` | `before` | `after` | `after` vs `main` |
|
|
43
|
+
|---|---:|---:|---:|---:|
|
|
44
|
+
| `undefined` (no header) | 3.9 | 5.9 | 6.0 | 0.65x |
|
|
45
|
+
| `text/event-stream` | 14.7 | 81.6 | **7.3** | **2.01x faster** |
|
|
46
|
+
| `*/*` | 4.2 | 74.6 | 6.9 | 0.61x (but `main` rejects this — not equivalent behavior) |
|
|
47
|
+
|
|
48
|
+
The `text/event-stream` row is the headline: a `===` against a 17-char literal beats `.includes()` of the same literal because V8 doesn't need to scan for occurrences when both lengths are equal. This is the input ~99% of real EventSource clients send.
|
|
49
|
+
|
|
50
|
+
The `*/*` row looks worse for `after`, but `main` and `after` answer different questions: `main` returns false (no substring), `after` returns true (RFC-compliant admit). Comparing them is a behavior comparison, not a perf comparison.
|
|
51
|
+
|
|
52
|
+
### Slow path (multi-entry / qvalue inputs)
|
|
53
|
+
|
|
54
|
+
| Input | `main` | `before` | `after` | `after` vs `main` | `after` vs `before` |
|
|
55
|
+
|---|---:|---:|---:|---:|---:|
|
|
56
|
+
| `text/event-stream;q=0` | 14.7 | 110.9 | 67.7 | 0.22x | 1.64x faster |
|
|
57
|
+
| `text/event-stream, app/json;q=0.5` | 14.7 | 157.0 | 57.1 | 0.26x | 2.75x faster |
|
|
58
|
+
| browser-like (6 entries) | 36.7 | 361.0 | 176.4 | 0.21x | 2.05x faster |
|
|
59
|
+
| `*/*, text/event-stream;q=0` | 15.9 | 176.1 | 101.0 | 0.16x | 1.74x faster |
|
|
60
|
+
|
|
61
|
+
`main` is faster here because `.includes()` is a single string scan; the new gate has to actually parse entries, identify media types, and check qvalues. The raw cost ratio looks large, but the absolute numbers are tiny (the worst case is 176 ns/op on a header no client actually sends to an SSE endpoint).
|
|
62
|
+
|
|
63
|
+
The "after vs before" column shows what the optimization work within this PR bought us: **1.6–2.8x speedup** versus the first spec-compliant iteration.
|
|
64
|
+
|
|
65
|
+
### Optimization win within this PR (`after` vs `before`)
|
|
66
|
+
|
|
67
|
+
| Input | `before` | `after` | speedup |
|
|
68
|
+
|---|---:|---:|---:|
|
|
69
|
+
| `text/event-stream` | 81.6 ns | 7.3 ns | **11.22x** |
|
|
70
|
+
| `*/*` | 74.6 ns | 6.9 ns | **10.78x** |
|
|
71
|
+
| `text/event-stream;q=0` | 110.9 ns | 67.7 ns | 1.64x |
|
|
72
|
+
| mixed q-values | 157.0 ns | 57.1 ns | 2.75x |
|
|
73
|
+
| browser-like | 361.0 ns | 176.4 ns | 2.05x |
|
|
74
|
+
| `*/*, t/e-s;q=0` | 176.1 ns | 101.0 ns | 1.74x |
|
|
75
|
+
|
|
76
|
+
## In-context timing — full HTTP request, µs/req (median)
|
|
77
|
+
|
|
78
|
+
200 samples per case, ~50 ms per sample. Real fastify HTTP server + undici client.
|
|
79
|
+
|
|
80
|
+
| Input | `main` (substring gate) | current (optimized) | Δ vs main |
|
|
81
|
+
|---|---:|---:|---:|
|
|
82
|
+
| `text/event-stream` | 465.0 | 468.3 | +3.3 µs (+0.7 %) |
|
|
83
|
+
| `text/event-stream, app/json;q=0.5` | 465.9 | 468.6 | +2.7 µs (+0.6 %) |
|
|
84
|
+
| `*/*` (refuse, fallthrough) | 462.3 | 453.4 | −8.8 µs (−1.9 %) |
|
|
85
|
+
| browser-like (fallthrough) | 454.4 | 459.7 | +5.4 µs (+1.2 %) |
|
|
86
|
+
|
|
87
|
+
RSD 1.7–3.1 % across all rows; the ±2 % differences are at the edge of statistical significance and in practice are noise from the rest of the request pipeline. The headline: **the new gate is indistinguishable from `main` at the request level.**
|
|
88
|
+
|
|
89
|
+
## Why the iso 4–7x slowdown disappears in context
|
|
90
|
+
|
|
91
|
+
A fastify request roundtrip is ~460 µs. Even the worst slow-path input (browser-like at 176 ns/op) is 0.04 % of that. Everything else — Node socket I/O, HTTP parsing, fastify hook dispatch, JSON serialization, response framing — dominates. The gate is so cheap that improving or worsening it by 100 ns/op moves the request time by amounts below the noise floor.
|
|
92
|
+
|
|
93
|
+
## What was optimized (vs `before`)
|
|
94
|
+
|
|
95
|
+
1. **Zero-allocation hot path.** Three `acceptHeader === 'literal'` checks at the top catch >99 % of real-world inputs without ever entering the parser. Single `===` against the 17-char `text/event-stream` literal even beats `main`'s `.includes()`.
|
|
96
|
+
2. **Char-walking slow path.** Replaced `.split(',')`, `.split(';')`, rest-params, `.toLowerCase()`, `.trim()`, `.slice()`, `parseFloat()` with a single non-allocating pass driven by `charCodeAt`.
|
|
97
|
+
3. **Binary q=0 detection** instead of full qvalue parsing. The function only needs to know `q == 0` vs `q > 0` — it picks the winning media range by specificity, not by comparing fractional qvalues. Saves `parseFloat` entirely; pathological inputs like `q=-0.5` or `q=2` are now treated as `q > 0` (admit), which is fine because no real client emits them.
|
|
98
|
+
4. **Skip-ahead on non-matching entries.** When an entry's media type isn't one of our candidates, we jump directly to the next `,` without parsing its parameters.
|
|
99
|
+
5. **Early-return on max specificity.** `text/event-stream` with non-zero quality has specificity 3 — nothing later in the list can outrank it, so we return `true` immediately without scanning the rest of the header.
|
|
100
|
+
6. **Removed param-internal whitespace handling.** RFC 9110 §5.6.6 doesn't allow OWS inside `parameter` (no `q = 0`), and Node's HTTP parser doesn't add it. Kept the OWS handling that browsers actually emit (after `,` and after `;`).
|
|
101
|
+
|
|
102
|
+
## Files
|
|
103
|
+
|
|
104
|
+
- `index.js` — production code (the `clientAcceptsSSE` function and the surrounding plugin).
|
|
105
|
+
- `bench/accept-header.js` — isolated function bench.
|
|
106
|
+
- `bench/in-context.js` — full-request bench.
|
package/eslint.config.js
CHANGED