@fastify/sse 0.4.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.
@@ -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
@@ -1,3 +1,6 @@
1
- const neostandard = require('neostandard')
1
+ 'use strict'
2
2
 
3
- module.exports = neostandard()
3
+ module.exports = require('neostandard')({
4
+ ignores: require('neostandard').resolveIgnoresFromGitignore(),
5
+ ts: true
6
+ })