@fastify/sse 0.5.0 → 0.6.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.
@@ -34,6 +34,7 @@ updates:
34
34
  - dependency-name: "eslint"
35
35
  - dependency-name: "neostandard"
36
36
  - dependency-name: "@stylistic/*"
37
+ - dependency-name: "typescript"
37
38
  open-pull-requests-limit: 10
38
39
  groups:
39
40
  # Production dependencies with breaking changes
@@ -27,7 +27,7 @@ jobs:
27
27
  permissions:
28
28
  contents: write
29
29
  pull-requests: write
30
- uses: fastify/workflows/.github/workflows/plugins-ci.yml@v6
30
+ uses: fastify/workflows/.github/workflows/plugins-ci.yml@2073dc8e1f9e172bf42daa3843c9dbd31af1e8cb # v6.0.0
31
31
  with:
32
32
  license-check: true
33
33
  lint: true
@@ -16,4 +16,4 @@ jobs:
16
16
  permissions:
17
17
  issues: write
18
18
  pull-requests: write
19
- uses: fastify/workflows/.github/workflows/lock-threads.yml@v6
19
+ uses: fastify/workflows/.github/workflows/lock-threads.yml@2073dc8e1f9e172bf42daa3843c9dbd31af1e8cb # v6.0.0
package/README.md CHANGED
@@ -263,13 +263,35 @@ fastify.get('/events', { sse: true }, async (request, reply) => {
263
263
  - `reply.sse.close()`: Manually close the connection
264
264
  - `reply.sse.replay(callback)`: Handle message replay using Last-Event-ID
265
265
  - `reply.sse.onClose(callback)`: Register callback for when connection closes
266
- - `reply.sse.sendHeaders()`: Manually send headers (called automatically on first write)
266
+ - `reply.sse.sendHeaders(statusCode?)`: Manually send headers (called automatically on first write)
267
+
268
+ ### Custom Response Status Code
269
+
270
+ The SSE response defaults to `200 OK`. To use a different status, either call
271
+ `reply.code()` before the first SSE write, or pass the status directly to a
272
+ manual `reply.sse.sendHeaders()` call:
273
+
274
+ ```javascript
275
+ fastify.get('/events', { sse: 'only' }, async (request, reply) => {
276
+ reply.code(201)
277
+ await reply.sse.send({ data: 'created' })
278
+ })
279
+
280
+ fastify.get('/events-explicit', { sse: 'only' }, async (request, reply) => {
281
+ reply.sse.sendHeaders(201)
282
+ await reply.sse.send({ data: 'created' })
283
+ })
284
+ ```
285
+
286
+ An explicit `sendHeaders()` argument takes precedence over `reply.code()`.
287
+ Once the first SSE write commits the response headers, later `reply.code()`
288
+ or `sendHeaders()` calls have no effect.
267
289
 
268
290
  ## Advanced Usage
269
291
 
270
292
  ### Accept-Header Negotiation
271
293
 
272
- The plugin parses the `Accept` header per [RFC 9110 §12.5.1](https://www.rfc-editor.org/rfc/rfc9110#name-accept)
294
+ The plugin parses the `Accept` header per [RFC 9110 §12.5.1](https://www.rfc-editor.org/rfc/rfc9110.html#name-accept)
273
295
  to decide whether to serve a request as SSE. The decision depends on the
274
296
  route's declared kind:
275
297
 
package/index.js CHANGED
@@ -416,14 +416,19 @@ class SSEContext {
416
416
  /**
417
417
  * Sends HTTP headers for the SSE response if not already sent.
418
418
  * Applies the SSE-specific response headers, transfers any headers set
419
- * via reply.header(), and calls writeHead(200). Called automatically
420
- * before the first SSE data is sent, but can also be called manually.
419
+ * via reply.header(), and writes the response head. The status code is
420
+ * resolved in order: the explicit `statusCode` argument, then the value
421
+ * set via reply.code(), then 200. The automatic call before the first
422
+ * SSE write passes no argument, so an explicit status only takes effect
423
+ * on manual calls made before any data is sent.
421
424
  *
422
425
  * Until this fires, the response is not yet committed as SSE — a handler
423
426
  * that never writes SSE data will return through Fastify's normal
424
427
  * serialization path.
428
+ *
429
+ * @param {number} [statusCode] - HTTP status for the SSE response.
425
430
  */
426
- sendHeaders () {
431
+ sendHeaders (statusCode) {
427
432
  if (!this.#headersSent) {
428
433
  this.reply.raw.setHeader('Content-Type', 'text/event-stream')
429
434
  this.reply.raw.setHeader('Cache-Control', 'no-cache')
@@ -436,7 +441,10 @@ class SSEContext {
436
441
  this.reply.raw.setHeader(name, value)
437
442
  }
438
443
 
439
- this.reply.raw.writeHead(200)
444
+ // Status precedence: explicit sendHeaders() argument, then the value
445
+ // the handler set via reply.code() (stored on raw.statusCode), then
446
+ // 200 as the final fallback.
447
+ this.reply.raw.writeHead(statusCode ?? this.reply.raw.statusCode ?? 200)
440
448
  this.#headersSent = true
441
449
 
442
450
  // Start the heartbeat only once the response is committed as SSE.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fastify/sse",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "Server-Sent Events plugin for Fastify",
5
5
  "main": "index.js",
6
6
  "types": "types/index.d.ts",
@@ -0,0 +1,130 @@
1
+ 'use strict'
2
+
3
+ const { test } = require('node:test')
4
+ const { strict: assert } = require('node:assert')
5
+ const Fastify = require('fastify')
6
+ const fastifySSE = require('../index.js')
7
+
8
+ test('SSE response should default to status 200', async (t) => {
9
+ const fastify = Fastify({ logger: false })
10
+
11
+ t.after(async () => {
12
+ await fastify.close()
13
+ })
14
+
15
+ await fastify.register(fastifySSE)
16
+
17
+ fastify.get('/events', { sse: 'only' }, async (request, reply) => {
18
+ await reply.sse.send({ data: 'hello' })
19
+ })
20
+
21
+ const response = await fastify.inject({
22
+ method: 'GET',
23
+ url: '/events',
24
+ headers: { accept: 'text/event-stream' }
25
+ })
26
+
27
+ assert.strictEqual(response.statusCode, 200)
28
+ assert.strictEqual(response.headers['content-type'], 'text/event-stream')
29
+ assert.ok(response.body.includes('data: "hello"'))
30
+ })
31
+
32
+ test('reply.code() before first SSE write should set the response status', async (t) => {
33
+ const fastify = Fastify({ logger: false })
34
+
35
+ t.after(async () => {
36
+ await fastify.close()
37
+ })
38
+
39
+ await fastify.register(fastifySSE)
40
+
41
+ fastify.get('/events', { sse: 'only' }, async (request, reply) => {
42
+ reply.code(201)
43
+ await reply.sse.send({ data: 'created' })
44
+ })
45
+
46
+ const response = await fastify.inject({
47
+ method: 'GET',
48
+ url: '/events',
49
+ headers: { accept: 'text/event-stream' }
50
+ })
51
+
52
+ assert.strictEqual(response.statusCode, 201)
53
+ assert.strictEqual(response.headers['content-type'], 'text/event-stream')
54
+ assert.ok(response.body.includes('data: "created"'))
55
+ })
56
+
57
+ test('reply.sse.sendHeaders(statusCode) should set the response status', async (t) => {
58
+ const fastify = Fastify({ logger: false })
59
+
60
+ t.after(async () => {
61
+ await fastify.close()
62
+ })
63
+
64
+ await fastify.register(fastifySSE)
65
+
66
+ fastify.get('/events', { sse: 'only' }, async (request, reply) => {
67
+ reply.sse.sendHeaders(202)
68
+ await reply.sse.send({ data: 'accepted' })
69
+ })
70
+
71
+ const response = await fastify.inject({
72
+ method: 'GET',
73
+ url: '/events',
74
+ headers: { accept: 'text/event-stream' }
75
+ })
76
+
77
+ assert.strictEqual(response.statusCode, 202)
78
+ assert.strictEqual(response.headers['content-type'], 'text/event-stream')
79
+ assert.ok(response.body.includes('data: "accepted"'))
80
+ })
81
+
82
+ test('explicit sendHeaders(statusCode) should take precedence over reply.code()', async (t) => {
83
+ const fastify = Fastify({ logger: false })
84
+
85
+ t.after(async () => {
86
+ await fastify.close()
87
+ })
88
+
89
+ await fastify.register(fastifySSE)
90
+
91
+ fastify.get('/events', { sse: 'only' }, async (request, reply) => {
92
+ reply.code(201)
93
+ reply.sse.sendHeaders(202)
94
+ await reply.sse.send({ data: 'accepted' })
95
+ })
96
+
97
+ const response = await fastify.inject({
98
+ method: 'GET',
99
+ url: '/events',
100
+ headers: { accept: 'text/event-stream' }
101
+ })
102
+
103
+ assert.strictEqual(response.statusCode, 202)
104
+ })
105
+
106
+ test('status changes after headers are committed should have no effect', async (t) => {
107
+ const fastify = Fastify({ logger: false })
108
+
109
+ t.after(async () => {
110
+ await fastify.close()
111
+ })
112
+
113
+ await fastify.register(fastifySSE)
114
+
115
+ fastify.get('/events', { sse: 'only' }, async (request, reply) => {
116
+ await reply.sse.send({ data: 'first' })
117
+ reply.sse.sendHeaders(500)
118
+ await reply.sse.send({ data: 'second' })
119
+ })
120
+
121
+ const response = await fastify.inject({
122
+ method: 'GET',
123
+ url: '/events',
124
+ headers: { accept: 'text/event-stream' }
125
+ })
126
+
127
+ assert.strictEqual(response.statusCode, 200)
128
+ assert.ok(response.body.includes('data: "first"'))
129
+ assert.ok(response.body.includes('data: "second"'))
130
+ })
package/types/index.d.ts CHANGED
@@ -138,11 +138,14 @@ export interface SSEReplyInterface {
138
138
  /**
139
139
  * Send HTTP headers for the SSE response if not already sent.
140
140
  * This method ensures headers set via reply.header() are transferred
141
- * to the raw response before calling writeHead(200).
142
- * Called automatically before the first SSE data is sent, but can
143
- * also be called manually if needed.
144
- */
145
- sendHeaders(): void
141
+ * to the raw response before writing the response head. The status code
142
+ * is resolved in order: the explicit `statusCode` argument, then the
143
+ * value set via reply.code(), then 200.
144
+ * Called automatically (without arguments) before the first SSE data is
145
+ * sent, but can also be called manually — call it before any data is
146
+ * written for an explicit status to take effect.
147
+ */
148
+ sendHeaders(statusCode?: number): void
146
149
  }
147
150
 
148
151
  export declare const fastifySSE: FastifyPluginAsync<SSEPluginOptions>
@@ -1,344 +0,0 @@
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()
@@ -1,210 +0,0 @@
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 DELETED
@@ -1,106 +0,0 @@
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.