@thoughtpivot/flight 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 3.0.1
+
+### Fixed
+
+- **Koa streaming on Bun.** A `router.routes()` backend can server-sent-event the usual Koa way (`ctx.respond = false`, `writeHead`, `write`, `end`). `flight-bun` returns a `ReadableStream` when that body starts, instead of buffering until `res.end()`. A stream that never calls `end()` no longer hangs with an empty body.
+- A Koa route that finishes the response inside the handler is kept. `flight-bun` no longer drops it and answers with the SPA `404`. A router mounted ahead of the one that handles the request is included: later routers append to `ctx.matched` with `push`, and the match is read when the stream opens or the response finishes.
+- Client disconnect emits `close` on the mock response, so `res.on('close')` can clear heartbeats and subscribers.
+- Gzip skips `text/event-stream` and any body that is still streaming, so compression cannot wait on an open stream. The response cache skips those bodies too.
+
+### Added
+
+- **`FLIGHT_IDLE_TIMEOUT`** (seconds). Default `10` (Bun's own default). An explicit `0` disables the server idle timeout. Positive fractions round up to at least `1`. Negative values and values that are not numbers use `10`. Values above `255` are clamped to Bun's maximum. Server-sent event responses disable the idle timeout for that request.
+
+### Documentation
+
+- On Bun, `FLIGHT_MAX_WORKERS` and Node's `cluster` module do not apply (`flight-bun` is one process). The Bun rate limiter is an in-memory per-process `Map` and does not use Redis.
+
 ## 3.0.0
 
 ### Breaking

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1 @@
+Copyright 2026 ThoughtPivot, Inc.

package/README.md

@@ -10,6 +10,37 @@ Think **platform-agnostic**: not framework-as-a-platform, but a clear runtime yo
 
 Flight is **open source** from **[ThoughtPivot](https://github.com/thoughtpivot)**.
 
+## ⚡ Now on Bun
+
+`flight-bun` runs Flight on `Bun.serve`. On a single pinned core, at the same commit, compared with the Node `flight` binary (hello-route micro-benchmark):
+
+|                           | Node (`flight`)             | Bun (`flight-bun`) |
+| ------------------------- | --------------------------- | ------------------ |
+| Req/s, Bun-native route   | 19,651                      | **61,110** (3.1x)  |
+| Req/s, existing Koa route | 19,651                      | **38,826** (2.0x)  |
+| p99 latency               | 10-25 ms                    | **~3 ms** (native) |
+| Start to first response   | 1.18 s (TypeScript via tsx) | **47 ms**          |
+| Idle RSS                  | 218 MB (primary + 1 worker) | **27 MB**          |
+
+**What changed:**
+
+- native `Bun.serve` routes
+- Bun-native middleware (security headers, CORS, gzip, rate limit, sessions, cache)
+- `.backend.ts` loaded directly, with no build step
+- Redis is optional and falls back to memory
+
+Existing `export default router.routes()` backends mount unchanged through the Koa-compat layer.
+
+**Note:** `flight-bun` is a single process. `FLIGHT_MAX_WORKERS` and Node's `cluster` module are not used. On 4 cores, a 4-worker Node cluster served more requests (80.7k vs 53.8k req/s), so scale `flight-bun` with replicas. The Bun rate limiter is an in-memory `Map` in that process and does not use Redis. The two sides run their own default middleware, which differs. Method and raw data: https://github.com/thoughtpivot/flight/blob/main/bench/BENCHMARKS.md (scripts in [`bench/`](https://github.com/thoughtpivot/flight/tree/main/bench)).
+
+`bun src/bun/server.ts` or `flight-bun`
+
+Early Bun research and benchmarks for Flight and Scribe by Vasilen Lyubomirov ([github.com/VasilenL](https://github.com/VasilenL)), whose work helped start this.
+
+Setup, environment variables and the backend contract: [Bun runtime](#bun-runtime).
+
+#thoughtpivot
+
 ## Highlights
 
 - **Two runtimes**: **Node / Koa** (`flight`) and **Bun** (`flight-bun`). The Bun server loads TypeScript directly, exposes `GET /healthz`, and still accepts existing Koa backends
@@ -387,6 +418,17 @@ FLIGHT_MODE=development bun src/bun/server.ts
 
 The Bun server uses `Bun.serve` and loads TypeScript directly. It exposes `GET /healthz` and the same edge jobs as the Node server (logging, security headers, CORS, gzip, rate limit, sessions, response cache) without Koa packages on the native path. Redis is optional (`FLIGHT_REDIS_URL`); without it, sessions and cache use memory.
 
+**What does not carry over from the Node server**
+
+- **Cluster and `FLIGHT_MAX_WORKERS`.** The Node server forks workers up to `FLIGHT_MAX_WORKERS` (default: one per CPU). `flight-bun` does not read that variable and does not use Node's `cluster` module. It is one process. Use more replicas to fill more cores.
+- **Rate-limit storage.** The Bun limiter keeps counters in a process-local `Map`. It does not use Redis, including when `FLIGHT_REDIS_URL` is set. That URL is for sessions and the response cache. Replicas do not share a window, so a limit of 100 across four processes allows 400 requests in the window. The Node production limiter is Redis-backed.
+
+**Streaming and server-sent events**
+
+Koa routes can stream. Set `ctx.respond = false`, send the status line with `writeHead` (for example `content-type: text/event-stream`), and write chunks with `ctx.res.write`. `flight-bun` returns that body as a `ReadableStream` as soon as the stream starts, instead of waiting for `res.end()`. Gzip skips `text/event-stream` and any other body that is still streaming. A client disconnect emits `close` on `ctx.res`; stop heartbeats and drop subscribers there. Set the headers and the first write before the first `await` so they are on the response that is already in flight.
+
+`FLIGHT_IDLE_TIMEOUT` is the `Bun.serve` idle timeout in seconds. The default is `10`, the same as Bun. An explicit `0` disables it. Positive fractions round up to at least `1` (`0.5` becomes `1`). Negative values and values that are not numbers use the default `10`. Values above `255` are clamped to Bun's maximum. Event-stream responses call `server.timeout(req, 0)` so a heartbeat slower than the idle timeout stays connected.
+
 **Two backend contracts can be mixed in one app.**
 
 Bun-native files default-export a path map. Handlers are `(req: Request) => Response`. Path params use Bun's `:id` routes.
@@ -403,16 +445,17 @@ Existing Koa files keep working. `export default router.routes()` is mounted thr
 
 In development (`FLIGHT_MODE=development`) the API stays on `FLIGHT_PORT` (default 3000) and Vite is spawned on 3001. In production the built SPA is read from `FLIGHT_DIST_PATH` (default `<app home>/dist`) with an `index.html` fallback. `/api`, `/health`, and `/healthz` do not fall back.
 
-| Variable                 | Default          | Bun runtime                                                                                      |
-| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------ |
-| `FLIGHT_SESSION_SECRET`  | unset            | Sessions stay **off** until this is set. There is no baked-in secret.                            |
-| `FLIGHT_RATE_LIMIT_MAX`  | `0`              | Rate limit stays **off** until this is greater than zero.                                        |
-| `FLIGHT_TRUST_PROXY`     | false            | When `1` / `true` / `yes`, the limiter uses `X-Forwarded-For`. Otherwise that header is ignored. |
-| `FLIGHT_REDIS_URL`       | unset            | `redis://host:6379` for shared sessions and cache.                                               |
-| `FLIGHT_CACHE_ENABLED`   | false            | Cache GET responses that send `Cache-Control: max-age`.                                          |
-| `FLIGHT_STATIC_PREFIXES` | `/assets,/fonts` | GET/HEAD under these prefixes skip the rate limit.                                               |
+| Variable                 | Default          | Bun runtime                                                                                                                                                                                       |
+| ------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FLIGHT_SESSION_SECRET`  | unset            | Sessions stay **off** until this is set. There is no baked-in secret.                                                                                                                             |
+| `FLIGHT_RATE_LIMIT_MAX`  | `0`              | Rate limit stays **off** until this is greater than zero.                                                                                                                                         |
+| `FLIGHT_TRUST_PROXY`     | false            | When `1` / `true` / `yes`, the limiter uses `X-Forwarded-For`. Otherwise that header is ignored.                                                                                                  |
+| `FLIGHT_REDIS_URL`       | unset            | `redis://host:6379` for shared sessions and cache.                                                                                                                                                |
+| `FLIGHT_CACHE_ENABLED`   | false            | Cache GET responses that send `Cache-Control: max-age`.                                                                                                                                           |
+| `FLIGHT_STATIC_PREFIXES` | `/assets,/fonts` | GET/HEAD under these prefixes skip the rate limit.                                                                                                                                                |
+| `FLIGHT_IDLE_TIMEOUT`    | `10`             | Idle seconds before Bun closes a socket. Explicit `0` disables it. Fractions round up to at least 1. Negative or invalid values use `10`. Above `255` is clamped. SSE turns this off per request. |
 
-Other `FLIGHT_*` knobs from the Node server (`FLIGHT_MODE`, `FLIGHT_PORT`, `FLIGHT_APP_HOME`, `FLIGHT_EXCLUDE_PATHS`, `FLIGHT_SPA_DENY_PREFIXES`, `FLIGHT_PAYLOAD_LIMIT`) apply here too. `GET /healthz` returns `ok` and is not rate limited.
+Other `FLIGHT_*` knobs from the Node server (`FLIGHT_MODE`, `FLIGHT_PORT`, `FLIGHT_APP_HOME`, `FLIGHT_EXCLUDE_PATHS`, `FLIGHT_SPA_DENY_PREFIXES`, `FLIGHT_PAYLOAD_LIMIT`) apply here too. `FLIGHT_MAX_WORKERS` does not: see the cluster note above. `GET /healthz` returns `ok` and is not rate limited.
 
 ## Requirements
 
@@ -455,7 +498,7 @@ Dry-run without publishing: Actions → **Publish** → **Run workflow** → lea
 
 ## License
 
-MIT
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thoughtpivot/flight",
-    "version": "3.0.0",
+    "version": "3.0.1",
     "description": "A web server designed for running full stack, component based applications at enterprise scale.",
     "main": "src/flight.ts",
     "publishConfig": {
@@ -27,7 +27,7 @@
         "url": "git+https://github.com/thoughtpivot/flight.git"
     },
     "author": "",
-    "license": "MIT",
+    "license": "Apache-2.0",
     "bugs": {
         "url": "https://github.com/thoughtpivot/flight/issues"
     },
@@ -39,6 +39,8 @@
         "src/bun",
         "README.md",
         "CHANGELOG.md",
+        "LICENSE",
+        "NOTICE",
         "readme-assets"
     ],
     "dependencies": {

package/src/bun/app.test.ts

@@ -1,10 +1,13 @@
 import { afterEach, expect, test } from 'bun:test'
-import { mkdir, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
+import Router from '@koa/router'
+
 import { openFlight, type FlightServer } from './app'
 import { loadConfig, type Config } from './config'
+import { createKoaDispatcher } from './koa-compat'
 import { safeTarget } from './static'
 
 const servers: FlightServer[] = []
@@ -189,3 +192,274 @@ test('opt-in response cache serves the second GET from the store', async () => {
     expect(hit.headers.get('x-flight-cache')).toBe('HIT')
     expect(await hit.json()).toEqual({ n: 1 })
 })
+
+/**
+ * Add a Koa backend that streams server-sent events and ends one route early.
+ * A router that does not handle these paths is mounted first, in this file, so the
+ * order does not depend on how the directory is listed.
+ */
+async function writeStreamBackend(dir: string, flagPath: string, gapMs: number): Promise<void> {
+    await writeFile(
+        join(dir, 'stream.backend.ts'),
+        `import Router from '@koa/router'
+import { writeFileSync } from 'node:fs'
+const miss = new Router()
+miss.get('/api/not-events', (ctx) => {
+    ctx.body = { ok: true }
+})
+const router = new Router()
+const flag = ${JSON.stringify(flagPath)}
+const gapMs = ${gapMs}
+
+router.get('/api/events', async (ctx) => {
+    ctx.respond = false
+    ctx.res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive'
+    })
+    ctx.res.write('data: one\\n\\n')
+    await new Promise((resolve) => setTimeout(resolve, gapMs))
+    ctx.res.write('data: two\\n\\n')
+    ctx.res.end()
+})
+
+router.get('/api/events-open', (ctx) => {
+    ctx.respond = false
+    ctx.res.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache'
+    })
+    ctx.res.write('data: hello\\n\\n')
+    const timer = setInterval(() => {
+        ctx.res.write('data: beat\\n\\n')
+    }, 400)
+    timer.unref()
+    ctx.res.on('close', () => {
+        clearInterval(timer)
+        writeFileSync(flag, 'closed')
+    })
+})
+
+router.get('/api/early-end', (ctx) => {
+    ctx.respond = false
+    ctx.res.writeHead(201, { 'content-type': 'text/plain; charset=utf-8' })
+    try {
+        ctx.res.write('from-route')
+    } finally {
+        ctx.res.end()
+    }
+})
+
+router.get('/api/big-text', (ctx) => {
+    ctx.body = 'z'.repeat(2048)
+})
+
+export default (ctx, next) => miss.routes()(ctx, () => router.routes()(ctx, next))
+`
+    )
+}
+
+/**
+ * Read from an open body until `needle` shows up, and record how long that chunk took.
+ */
+async function readUntil(
+    reader: ReadableStreamDefaultReader<Uint8Array>,
+    needle: string
+): Promise<{ text: string; firstByteMs: number }> {
+    const decoder = new TextDecoder()
+    const started = performance.now()
+    let text = ''
+    let firstByteMs = 0
+    while (!text.includes(needle)) {
+        const { value, done } = await reader.read()
+        if (done) break
+        if (!text) firstByteMs = performance.now() - started
+        text += decoder.decode(value, { stream: true })
+    }
+    return { text, firstByteMs }
+}
+
+test('FLIGHT_IDLE_TIMEOUT defaults to 10 seconds and clamps to Bun maximum', () => {
+    expect(loadConfig({}).idleTimeout).toBe(10)
+    expect(loadConfig({ FLIGHT_IDLE_TIMEOUT: '0' }).idleTimeout).toBe(0)
+    expect(loadConfig({ FLIGHT_IDLE_TIMEOUT: '0.0' }).idleTimeout).toBe(0)
+    expect(loadConfig({ FLIGHT_IDLE_TIMEOUT: '0.5' }).idleTimeout).toBe(1)
+    expect(loadConfig({ FLIGHT_IDLE_TIMEOUT: '1.2' }).idleTimeout).toBe(2)
+    expect(loadConfig({ FLIGHT_IDLE_TIMEOUT: '30' }).idleTimeout).toBe(30)
+    expect(loadConfig({ FLIGHT_IDLE_TIMEOUT: '999' }).idleTimeout).toBe(255)
+    expect(loadConfig({ FLIGHT_IDLE_TIMEOUT: '-5' }).idleTimeout).toBe(10)
+    expect(loadConfig({ FLIGHT_IDLE_TIMEOUT: 'nope' }).idleTimeout).toBe(10)
+    expect(loadConfig({ FLIGHT_IDLE_TIMEOUT: '' }).idleTimeout).toBe(10)
+})
+
+/**
+ * Two routers in a fixed order. The first does not handle the path under test.
+ * `@koa/router` assigns `ctx.matched` for that first router and only `push`es after that.
+ */
+function orderedRouters(setup: (router: Router) => void) {
+    const miss = new Router()
+    miss.get('/api/not-events', (ctx) => {
+        ctx.body = { ok: true }
+    })
+    const hit = new Router()
+    setup(hit)
+    return [miss.routes(), hit.routes()]
+}
+
+test('a non-matching router mounted first still streams the later router', async () => {
+    const dispatch = await createKoaDispatcher(
+        orderedRouters((router) => {
+            router.get('/api/events', (ctx) => {
+                ctx.respond = false
+                ctx.res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache' })
+                ctx.res.write('data: one\n\n')
+            })
+        }),
+        '1mb'
+    )
+
+    const response = await dispatch(new Request('http://127.0.0.1/api/events'))
+    expect(response).not.toBeNull()
+    expect(response!.status).toBe(200)
+    expect(response!.headers.get('content-type')).toContain('text/event-stream')
+    const reader = response!.body?.getReader()
+    if (!reader) throw new Error('expected a response body')
+    const first = await readUntil(reader, 'one')
+    expect(first.text).toContain('data: one')
+    await reader.cancel()
+
+    const missed = await dispatch(new Request('http://127.0.0.1/nowhere'))
+    expect(missed).toBeNull()
+})
+
+test('a non-matching router mounted first still returns an early end', async () => {
+    const dispatch = await createKoaDispatcher(
+        orderedRouters((router) => {
+            router.get('/api/early-end', (ctx) => {
+                ctx.respond = false
+                ctx.res.writeHead(201, { 'content-type': 'text/plain; charset=utf-8' })
+                try {
+                    ctx.res.write('from-route')
+                } finally {
+                    ctx.res.end()
+                }
+            })
+        }),
+        '1mb'
+    )
+
+    const response = await dispatch(new Request('http://127.0.0.1/api/early-end'))
+    expect(response).not.toBeNull()
+    expect(response!.status).toBe(201)
+    expect(await response!.text()).toBe('from-route')
+})
+
+test('Koa SSE chunks arrive before the stream ends', async () => {
+    const dir = await makeApp()
+    await writeStreamBackend(dir, join(dir, 'closed.flag'), 300)
+    const { url } = await boot({
+        FLIGHT_APP_HOME: dir,
+        FLIGHT_SECURITY_ENABLED: 'true',
+        FLIGHT_CORS_ENABLED: 'true'
+    })
+
+    const response = await fetch(`${url}/api/events`, { headers: { accept: 'text/event-stream' } })
+    expect(response.status).toBe(200)
+    expect(response.headers.get('content-type')).toContain('text/event-stream')
+    expect(response.headers.get('x-content-type-options')).toBe('nosniff')
+    const reader = response.body?.getReader()
+    if (!reader) throw new Error('expected a response body')
+
+    const first = await readUntil(reader, 'one')
+    expect(first.text).toContain('data: one')
+    expect(first.text).not.toContain('two')
+    expect(first.firstByteMs).toBeLessThan(250)
+
+    const rest = await readUntil(reader, 'two')
+    expect(rest.text).toContain('data: two')
+})
+
+test('closing the SSE client emits close on the Koa response', async () => {
+    const dir = await makeApp()
+    const flag = join(dir, 'closed.flag')
+    await writeStreamBackend(dir, flag, 300)
+    const { url } = await boot({ FLIGHT_APP_HOME: dir })
+
+    const controller = new AbortController()
+    const response = await fetch(`${url}/api/events-open`, { signal: controller.signal })
+    expect(response.status).toBe(200)
+    const reader = response.body?.getReader()
+    const first = await reader?.read()
+    expect(new TextDecoder().decode(first?.value)).toContain('hello')
+
+    controller.abort()
+    const started = Date.now()
+    let body = ''
+    while (Date.now() - started < 2000) {
+        try {
+            body = await readFile(flag, 'utf8')
+            break
+        } catch {
+            await new Promise((resolve) => setTimeout(resolve, 20))
+        }
+    }
+    expect(body).toBe('closed')
+})
+
+test('a Koa route that ends inside the handler is not replaced by the SPA 404', async () => {
+    const dir = await makeApp()
+    await writeStreamBackend(dir, join(dir, 'closed.flag'), 300)
+    const { url } = await boot({ FLIGHT_APP_HOME: dir })
+
+    const response = await fetch(`${url}/api/early-end`, { headers: { accept: 'text/html' } })
+    expect(response.status).toBe(201)
+    expect(await response.text()).toBe('from-route')
+})
+
+test('gzip does not buffer a Koa event stream', async () => {
+    const dir = await makeApp()
+    await writeStreamBackend(dir, join(dir, 'closed.flag'), 300)
+    const { url } = await boot({
+        FLIGHT_APP_HOME: dir,
+        FLIGHT_COMPRESS_ENABLED: 'true',
+        FLIGHT_COMPRESS_THRESHOLD: '1024'
+    })
+
+    const plain = await fetch(`${url}/api/big-text`, { headers: { 'accept-encoding': 'gzip' } })
+    expect(plain.status).toBe(200)
+    expect(plain.headers.get('content-encoding')).toBe('gzip')
+    expect((await plain.arrayBuffer()).byteLength).toBe(2048)
+
+    const events = await fetch(`${url}/api/events`, {
+        headers: { accept: 'text/event-stream', 'accept-encoding': 'gzip' }
+    })
+    expect(events.status).toBe(200)
+    expect(events.headers.get('content-encoding')).toBeNull()
+    const reader = events.body?.getReader()
+    if (!reader) throw new Error('expected a response body')
+    const first = await readUntil(reader, 'one')
+    expect(first.text).toContain('data: one')
+    expect(first.text).not.toContain('two')
+    expect(first.firstByteMs).toBeLessThan(250)
+})
+
+test(
+    'SSE stays open past FLIGHT_IDLE_TIMEOUT',
+    async () => {
+        const dir = await makeApp()
+        await writeStreamBackend(dir, join(dir, 'closed.flag'), 5000)
+        const { url } = await boot({ FLIGHT_APP_HOME: dir, FLIGHT_IDLE_TIMEOUT: '1' })
+
+        const response = await fetch(`${url}/api/events`)
+        expect(response.headers.get('content-type')).toContain('text/event-stream')
+        const reader = response.body?.getReader()
+        if (!reader) throw new Error('expected a response body')
+        const first = await readUntil(reader, 'one')
+        expect(first.text).toContain('data: one')
+        expect(first.text).not.toContain('two')
+        const rest = await readUntil(reader, 'two')
+        expect(rest.text).toContain('data: two')
+    },
+    { timeout: 12000 }
+)

package/src/bun/app.ts

@@ -7,6 +7,7 @@ import {
     compose,
     compress,
     cors,
+    isEventStream,
     logger,
     rateLimit,
     security,
@@ -24,6 +25,19 @@ export interface FlightServer extends AddressServer {
     stop(closeActiveConnections?: boolean): void
 }
 
+/** Slice of `Bun.serve`'s server used to adjust the idle timeout for one request. */
+interface BunHttpServer {
+    timeout(request: Request, seconds: number): void
+}
+
+/**
+ * Turn the idle timeout off for server-sent events so a quiet heartbeat is not cut off.
+ */
+function relaxIdleTimeout(req: Request, response: Response, bunServer?: BunHttpServer): Response {
+    if (bunServer && isEventStream(response)) bunServer.timeout(req, 0)
+    return response
+}
+
 /**
  * Wrap discovered routes so every method runs through the middleware onion.
  * OPTIONS is registered when CORS is on, otherwise Bun answers 405 before our middleware runs.
@@ -37,11 +51,13 @@ function wrapRoutes(
     for (const [path, value] of Object.entries(routes)) {
         if (typeof value === 'function') {
             const handler = value
-            wrapped[path] = (req: Request) => run(req, () => handler(req))
+            wrapped[path] = (req: Request, bunServer?: BunHttpServer) =>
+                run(req, () => handler(req)).then((response) => relaxIdleTimeout(req, response, bunServer))
         } else {
             const methods: MethodMap = {}
             for (const [method, handler] of Object.entries(value)) {
-                methods[method] = (req: Request) => run(req, () => handler(req))
+                methods[method] = (req: Request, bunServer?: BunHttpServer) =>
+                    run(req, () => handler(req)).then((response) => relaxIdleTimeout(req, response, bunServer))
             }
             if (corsEnabled && !methods.OPTIONS) {
                 methods.OPTIONS = (req: Request) => run(req, () => new Response(null, { status: 204 }))
@@ -99,12 +115,13 @@ export async function createApp(cfg: Config, server?: () => AddressServer | unde
     return {
         enabled,
         routes,
-        fetch: async (req: Request) => {
-            return run(req, async () => {
+        fetch: async (req: Request, bunServer?: BunHttpServer) => {
+            const response = await run(req, async () => {
                 const fromKoa = koa ? await koa(req) : null
                 if (fromKoa) return fromKoa
                 return (await serveStatic(req)) ?? new Response('Not Found', { status: 404 })
             })
+            return relaxIdleTimeout(req, response, bunServer)
         },
         error(err: unknown) {
             console.error('flight-bun error:', err)
@@ -125,8 +142,9 @@ export async function openFlight(
     server = Bun.serve({
         port: listen.port ?? cfg.port,
         hostname: listen.hostname ?? cfg.hostname,
+        idleTimeout: cfg.idleTimeout,
         routes: app.routes as Record<string, Handler | MethodMap>,
-        fetch: app.fetch,
+        fetch: (req: Request, bunServer: BunHttpServer) => app.fetch(req, bunServer),
         error: app.error
     }) as FlightServer
 
@@ -134,6 +152,7 @@ export async function openFlight(
     console.log(
         `flight-bun (${cfg.mode}) listening on :${server.port} — app_home=${cfg.appHome}${dist}\n` +
             `flight-bun: middleware [${app.enabled.join(', ') || 'none'}]` +
+            `, idleTimeout=${cfg.idleTimeout}s` +
             (cfg.redisUrl ? `, redis=${cfg.redisUrl}` : ', redis=(in-memory)')
     )
     return server

package/src/bun/cache.ts

@@ -1,5 +1,5 @@
 import type { CacheConfig } from './config'
-import { withHeaders, type Middleware } from './middleware'
+import { isStreamingResponse, withHeaders, type Middleware } from './middleware'
 import type { KVStore } from './store'
 
 /** Stored GET response. Only text and JSON bodies are kept. */
@@ -35,6 +35,7 @@ export function cache(cfg: CacheConfig, store: KVStore): Middleware {
         }
 
         const response = await next()
+        if (isStreamingResponse(response)) return withHeaders(response, { 'x-flight-cache': 'MISS' })
         const cacheControl = response.headers.get('cache-control') || ''
         const match = /max-age=(\d+)/.exec(cacheControl)
         if (response.status === 200 && match && req.method === 'GET') {

package/src/bun/config.ts

@@ -57,6 +57,11 @@ export interface Config {
     spaDenyPrefixes: string[]
     payloadLimit: string
     logging: boolean
+    /**
+     * Seconds `Bun.serve` waits on an idle socket.
+     * Explicit `0` disables it. Positive fractions round up to at least 1. Clamped to 255.
+     */
+    idleTimeout: number
     redisUrl?: string
     cors: CorsConfig
     security: SecurityConfig
@@ -85,6 +90,19 @@ function num(value: string | undefined, fallback: number): number {
     return Number.isFinite(parsed) ? parsed : fallback
 }
 
+/**
+ * Parse `FLIGHT_IDLE_TIMEOUT` seconds. Missing, blank, negative, and non-numeric values use 10.
+ * An explicit `0` disables the timeout. Positive fractions round up to at least 1.
+ * Anything above Bun's maximum of 255 is clamped.
+ */
+function idleSeconds(value: string | undefined): number {
+    if (value === undefined || value.trim() === '') return 10
+    const parsed = Number(value)
+    if (!Number.isFinite(parsed) || parsed < 0) return 10
+    if (parsed === 0) return 0
+    return Math.min(255, Math.max(1, Math.ceil(parsed)))
+}
+
 /**
  * Split a comma-separated prefix list and ensure each entry starts with `/`.
  */
@@ -121,6 +139,7 @@ export function loadConfig(env: Env = process.env): Config {
         spaDenyPrefixes: prefixes(env.FLIGHT_SPA_DENY_PREFIXES, '/api,/health,/healthz'),
         payloadLimit: env.FLIGHT_PAYLOAD_LIMIT || '1mb',
         logging: bool(env.FLIGHT_LOGGING, mode === 'development'),
+        idleTimeout: idleSeconds(env.FLIGHT_IDLE_TIMEOUT),
         redisUrl: env.FLIGHT_REDIS_URL || undefined,
         cors: {
             enabled: bool(env.FLIGHT_CORS_ENABLED, true),

package/src/bun/koa-compat.ts

@@ -2,6 +2,9 @@ import { EventEmitter } from 'node:events'
 import { Readable } from 'node:stream'
 
 import type { KoaMiddleware } from './backends'
+import { markStreaming } from './middleware'
+
+type WriteCallback = (error?: Error | null) => void
 
 /** Node-style response stand-in that Koa's `res.end()` can finish. */
 class MockResponse extends EventEmitter {
@@ -12,8 +15,17 @@ class MockResponse extends EventEmitter {
     /** Left unset so `on-finished` does not treat a plain object as a socket. */
     socket: EventEmitter | null = null
     flightMatched = false
+    /** Re-read whether any mounted router has matched. Runs before the dispatcher decides. */
+    refreshMatch: () => void = () => {}
     private chunks: Buffer[] = []
     private headers = new Map<string, string | string[]>()
+    /** True once `writeHead`, `write`, or `ctx.respond = false` starts a live body. */
+    private streaming = false
+    /** True while `end()` is copying its final chunk, so that write does not start a stream. */
+    private ending = false
+    private closeEmitted = false
+    private clientAborted = false
+    private controller: ReadableStreamDefaultController<Uint8Array> | null = null
 
     /** Store a response header. Repeated Set-Cookie values accumulate. */
     setHeader(name: string, value: string | number | string[]) {
@@ -38,40 +50,124 @@ class MockResponse extends EventEmitter {
         this.headers.delete(name.toLowerCase())
     }
 
-    /** Record the status line. Koa calls this before `end` when headers are flushed. */
-    writeHead(status: number, headers?: Record<string, string | string[]>) {
+    /** Record the status line. Calling this begins a streamed body. */
+    writeHead(
+        status: number,
+        reason?: string | Record<string, string | number | string[]>,
+        maybeHeaders?: Record<string, string | number | string[]>
+    ) {
         this.statusCode = status
+        const headers = typeof reason === 'string' || reason === undefined ? maybeHeaders : reason
         if (headers) {
             for (const [key, value] of Object.entries(headers)) this.setHeader(key, value)
         }
         this.headersSent = true
+        if (!this.finished && !this.ending) this.startStream()
         return this
     }
 
-    /** No-op. Koa sometimes flushes headers early. */
+    /** Flush headers and begin a streamed body. */
     flushHeaders() {
         this.headersSent = true
+        if (!this.finished && !this.ending) this.startStream()
+    }
+
+    /**
+     * Begin a streamed body without waiting for `end()`.
+     * Headers set in the same turn are included; the Fetch response resolves on the next microtask.
+     */
+    startStream() {
+        if (this.streaming || this.finished || this.writableEnded) return
+        this.streaming = true
+        this.refreshMatch()
+        queueMicrotask(() => {
+            this.emit('stream-open')
+        })
     }
 
-    /** Buffer a chunk. */
-    write(chunk?: string | Buffer) {
-        if (chunk) this.chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk))
+    /** Buffer a chunk, or enqueue it when a live stream is already open. */
+    write(chunk?: string | Buffer | Uint8Array, encoding?: BufferEncoding | WriteCallback, callback?: WriteCallback) {
+        if (this.writableEnded || this.clientAborted) return false
+        let cb: WriteCallback | undefined
+        let enc: BufferEncoding | undefined
+        if (typeof encoding === 'function') cb = encoding
+        else {
+            enc = encoding
+            if (typeof callback === 'function') cb = callback
+        }
+        if (chunk != null && chunk.length !== 0) {
+            const bytes = typeof chunk === 'string' ? Buffer.from(chunk, enc) : Buffer.from(chunk)
+            this.enqueue(bytes)
+        }
+        if (!this.ending) this.startStream()
+        if (cb) queueMicrotask(() => cb!())
         return true
     }
 
     /** Finish the response and emit the events `on-finished` listens for. */
-    end(chunk?: string | Buffer) {
-        if (chunk) this.write(chunk)
+    end(chunk?: string | Buffer | Uint8Array, encoding?: BufferEncoding | WriteCallback, callback?: WriteCallback) {
+        if (this.writableEnded) return this
+        this.ending = true
+        if (chunk != null && chunk !== '') this.write(chunk, encoding, callback)
+        else if (typeof encoding === 'function') queueMicrotask(() => encoding())
+        else if (typeof callback === 'function') queueMicrotask(() => callback())
         this.finished = true
         this.writableEnded = true
         this.headersSent = true
+        this.refreshMatch()
+        this.closeController()
         this.emit('finish')
-        this.emit('close')
+        this.emitClose()
         return this
     }
 
+    /** Client went away. `res.on('close')` handlers use this to drop heartbeats and subscribers. */
+    clientDisconnect() {
+        if (this.clientAborted) return
+        this.clientAborted = true
+        this.closeController()
+        this.emitClose()
+    }
+
     /** Build the Fetch response from the buffered status, headers, and body. */
     toResponse(): Response {
+        if (this.streaming && !this.finished) return this.liveResponse()
+        const body = this.chunks.length ? Buffer.concat(this.chunks) : null
+        return new Response(body, { status: this.statusCode, headers: this.headerInit() })
+    }
+
+    /** Push bytes into the live controller, or hold them until that controller exists. */
+    private enqueue(bytes: Buffer) {
+        if (!this.controller) {
+            this.chunks.push(bytes)
+            return
+        }
+        try {
+            this.controller.enqueue(bytes)
+        } catch {
+            // The stream is already closed.
+        }
+    }
+
+    /** Close the live body if the consumer has already attached. */
+    private closeController() {
+        if (!this.controller) return
+        try {
+            this.controller.close()
+        } catch {
+            // Already closed or cancelled.
+        }
+    }
+
+    /** Emit `close` once, whether the route finished or the client aborted. */
+    private emitClose() {
+        if (this.closeEmitted) return
+        this.closeEmitted = true
+        this.emit('close')
+    }
+
+    /** Copy stored headers into a Fetch `Headers` object. */
+    private headerInit(): Headers {
         const headers = new Headers()
         for (const [key, value] of this.headers) {
             if (Array.isArray(value)) {
@@ -80,8 +176,26 @@ class MockResponse extends EventEmitter {
                 headers.set(key, value)
             }
         }
-        const body = this.chunks.length ? Buffer.concat(this.chunks) : null
-        return new Response(body, { status: this.statusCode, headers })
+        return headers
+    }
+
+    /**
+     * Return a Fetch response whose body stays open until `end()` or the client disconnects.
+     * Chunks written before this runs are flushed first.
+     */
+    private liveResponse(): Response {
+        const stream = new ReadableStream<Uint8Array>({
+            start: (controller) => {
+                this.controller = controller
+                for (const chunk of this.chunks.splice(0)) controller.enqueue(chunk)
+                if (this.finished || this.clientAborted) this.closeController()
+            },
+            cancel: () => {
+                this.clientDisconnect()
+            }
+        })
+        markStreaming(stream)
+        return new Response(stream, { status: this.statusCode, headers: this.headerInit() })
     }
 }
 
@@ -108,6 +222,18 @@ function requestFromFetch(request: Request, body: Buffer): Readable {
     return req
 }
 
+/** Koa context fields the compat layer observes. */
+interface KoaCtx {
+    matched?: unknown
+    /** Set by `@koa/router` when the path and the method both match. */
+    _matchedRoute?: unknown
+    respond?: unknown
+    res: MockResponse
+}
+
+/** Arrays whose `push` already updates `flightMatched`. Later routers append instead of assigning. */
+const observedMatches = new WeakSet<object>()
+
 /**
  * Run one Fetch request through a Koa callback. Returns null when no route matched,
  * so the caller can still serve the SPA.
@@ -121,13 +247,33 @@ function callbackToFetch(callback: (req: Readable, res: MockResponse) => void) {
         const req = requestFromFetch(request, body)
         const res = new MockResponse()
 
+        const onAbort = () => res.clientDisconnect()
+        if (request.signal.aborted) onAbort()
+        else request.signal.addEventListener('abort', onAbort, { once: true })
+        res.once('finish', () => request.signal.removeEventListener('abort', onAbort))
+
         await new Promise<void>((resolve, reject) => {
-            res.on('finish', () => resolve())
-            res.on('error', reject)
+            let settled = false
+            const finish = () => {
+                res.refreshMatch()
+                if (settled) return
+                settled = true
+                resolve()
+            }
+            res.on('finish', finish)
+            res.on('stream-open', finish)
+            res.on('error', (err) => {
+                if (settled) return
+                settled = true
+                reject(err)
+            })
             try {
                 callback(req, res)
             } catch (err) {
-                reject(err)
+                if (!settled) {
+                    settled = true
+                    reject(err)
+                }
             }
         })
 
@@ -136,6 +282,73 @@ function callbackToFetch(callback: (req: Readable, res: MockResponse) => void) {
     }
 }
 
+/**
+ * True when this request hit a route.
+ * `@koa/router` assigns `ctx.matched` for the first router only. Every later router
+ * `push`es onto that same array, and sets `_matchedRoute` when the method matches.
+ */
+function hasMatch(ctx: KoaCtx): boolean {
+    const matched = ctx.matched
+    if (Array.isArray(matched) && matched.length > 0) return true
+    return typeof ctx._matchedRoute === 'string' && ctx._matchedRoute.length > 0
+}
+
+/**
+ * Notice routes appended with `push` after the first router assigned `ctx.matched`.
+ */
+function observePushes(ctx: KoaCtx, layers: unknown[]) {
+    if (observedMatches.has(layers)) return
+    observedMatches.add(layers)
+    const original = Array.prototype.push
+    layers.push = function (this: unknown[], ...items: unknown[]) {
+        const result = original.apply(this, items)
+        ctx.res.refreshMatch()
+        return result
+    }
+}
+
+/**
+ * Keep `flightMatched` current for every router, including ones that only `push`.
+ * The dispatcher reads it again when a stream opens or the response finishes.
+ */
+function trackMatch(ctx: KoaCtx) {
+    ctx.res.refreshMatch = () => {
+        ctx.res.flightMatched = hasMatch(ctx)
+    }
+    let matched = ctx.matched
+    if (Array.isArray(matched)) observePushes(ctx, matched)
+    Object.defineProperty(ctx, 'matched', {
+        configurable: true,
+        enumerable: true,
+        get() {
+            return matched
+        },
+        set(value: unknown) {
+            matched = value
+            if (Array.isArray(value)) observePushes(ctx, value)
+            ctx.res.refreshMatch()
+        }
+    })
+}
+
+/**
+ * `ctx.respond = false` means the route owns the raw response and Koa must not wait for `end()`.
+ */
+function trackRespond(ctx: KoaCtx) {
+    let respond = ctx.respond
+    Object.defineProperty(ctx, 'respond', {
+        configurable: true,
+        enumerable: true,
+        get() {
+            return respond
+        },
+        set(value: unknown) {
+            respond = value
+            if (value === false) ctx.res.startStream()
+        }
+    })
+}
+
 /**
  * Build a Fetch dispatcher for existing Koa `router.routes()` backends.
  * JSON bodies are parsed with `koa-bodyparser`. Unmatched paths return null.
@@ -150,7 +363,9 @@ export async function createKoaDispatcher(
     const bodyParser = bodyParserModule.default
     const app = new Koa()
 
-    app.use(async (ctx: any, next: () => Promise<void>) => {
+    app.use(async (ctx: KoaCtx, next: () => Promise<void>) => {
+        trackMatch(ctx)
+        trackRespond(ctx)
         await next()
         ctx.res.flightMatched = Array.isArray(ctx.matched) && ctx.matched.length > 0
     })

package/src/bun/middleware.ts

@@ -34,11 +34,22 @@ export function compose(middlewares: Middleware[]): (req: Request, core: Handler
 export function withHeaders(response: Response, extra: Record<string, string>): Response {
     const headers = new Headers(response.headers)
     for (const [key, value] of Object.entries(extra)) headers.set(key, value)
-    return new Response(response.body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers
-    })
+    return preserveStreaming(
+        response,
+        new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers
+        })
+    )
+}
+
+/**
+ * Keep a live-stream mark when a middleware copies the body onto a new `Response`.
+ */
+export function preserveStreaming(source: Response, target: Response): Response {
+    if (source.body && target.body && streamingBodies.has(source.body)) streamingBodies.add(target.body)
+    return target
 }
 
 /**
@@ -104,6 +115,33 @@ export function cors(cfg: CorsConfig): Middleware {
     }
 }
 
+/** Bodies that must not be read to completion. Keyed by the stream so header copies keep the mark. */
+const streamingBodies = new WeakSet<ReadableStream<Uint8Array>>()
+
+/**
+ * Remember a body that stays open until the producer ends it.
+ * Compression and the response cache must not buffer it.
+ */
+export function markStreaming(body: ReadableStream<Uint8Array>) {
+    streamingBodies.add(body)
+}
+
+/**
+ * True for `text/event-stream` and for any body marked as a live stream.
+ */
+export function isStreamingResponse(response: Response): boolean {
+    const type = response.headers.get('content-type') || ''
+    if (/text\/event-stream/i.test(type)) return true
+    return response.body != null && streamingBodies.has(response.body)
+}
+
+/**
+ * True when this response is a server-sent event stream.
+ */
+export function isEventStream(response: Response): boolean {
+    return /text\/event-stream/i.test(response.headers.get('content-type') || '')
+}
+
 /**
  * True when the content type is worth gzipping.
  */
@@ -131,6 +169,7 @@ export function compress(cfg: CompressionConfig): Middleware {
         }
         if (response.headers.get('content-encoding')) return response
         if (!(req.headers.get('accept-encoding') || '').includes('gzip')) return response
+        if (isStreamingResponse(response)) return response
         if (!compressible(response.headers.get('content-type') || '')) return response
 
         const bytes = new Uint8Array(await response.arrayBuffer())

package/src/bun/session.ts

@@ -1,7 +1,7 @@
 import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto'
 
 import type { SessionConfig } from './config'
-import type { Middleware } from './middleware'
+import { preserveStreaming, type Middleware } from './middleware'
 import type { KVStore } from './store'
 
 /** Request carrying the mutable session object. */
@@ -63,11 +63,14 @@ function serializeCookie(name: string, value: string, maxAgeSec: number): string
 function appendSetCookie(response: Response, cookie: string): Response {
     const headers = new Headers(response.headers)
     headers.append('set-cookie', cookie)
-    return new Response(response.body, {
-        status: response.status,
-        statusText: response.statusText,
-        headers
-    })
+    return preserveStreaming(
+        response,
+        new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers
+        })
+    )
 }
 
 /**

package/LICENSE.md

@@ -1,19 +0,0 @@
-# MIT License
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.