@thoughtpivot/flight 2.0.2 → 3.0.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # 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
+
+- **Vite 8** toolchain: `vite` `^8.3.2`, `@vitejs/plugin-react` `^6.1.1`, `@vitejs/plugin-vue` `^6.0.9`, and `vite-plugin-vuetify` `^2.1.3`. `@vitejs/plugin-react` 6 requires Vite 8 (`vite/internal`). Apps that still pin Vite 6 should stay on `@thoughtpivot/flight@2.0.2` until they upgrade.
+- **`ioredis` 6**: requires Node.js 20+ and uses **RESP3** by default. Set `protocol: 2` on the Redis client if a server still needs the ioredis v5 wire protocol.
+- **Node engines**: `^20.19.0 || >=22.12.0` (aligned with Vite 8 / ioredis 6).
+
+### Added
+
+- **Bun runtime** (`src/bun`, `flight-bun` / `bun src/bun/server.ts`): `Bun.serve`, `/healthz`, and the same middleware jobs (logging, security headers, CORS, gzip, rate limit, sessions, response cache) on the native Bun path.
+- **Koa compatibility on that runtime.** A `*.backend.ts` file may still `export default router.routes()`. Those backends are mounted through Koa and `koa-bodyparser`. Compiled `*.backend.js` files are discovered too.
+- **`FLIGHT_TRUST_PROXY` on the Bun rate limiter.** `X-Forwarded-For` is ignored unless the proxy is trusted.
+- **`@vitejs/plugin-react`** as a dependency (alongside `@vitejs/plugin-vue`) so React + Vite apps get the same style of transitive plugin coverage as Vue apps.
+- Broader Node test coverage for SPA fallback, env flags, rate-limit skips, and backend exclude paths. `npm test` runs every compiled `dist/*.test.js` file.
+- GitHub Actions **CI** (`.github/workflows/ci.yml`) and **npm publish** (`.github/workflows/publish.yml`) with provenance. CircleCI is retired.
+
+### Changed
+
+- Dependency majors also include `koa-helmet` 9 and `koa-ratelimit` 6.
+- SPA index paths with `..` stay inside the dist root; exclude paths named `..foo` stay inside `app_home`; `.` / app-root excludes warn instead of ignoring everything.
+
+### Notes
+
+- The Node / Koa `flight` binary is unchanged in role. Sessions on Bun stay off until `FLIGHT_SESSION_SECRET` is set. Rate limiting on Bun stays off until `FLIGHT_RATE_LIMIT_MAX` is greater than zero.
+- Git changelog entry **2.1.0** below was prepared in-repo but never published to npm; its React + Vite docs/plugin work ships in this 3.0.0 release together with the Vite 8 upgrade.
+
+## 2.1.0
+
+### Added
+
+- **`@vitejs/plugin-react`** as a **dependency** (alongside **`@vitejs/plugin-vue`**), so React + Vite apps that depend on `@thoughtpivot/flight` get the same style of transitive Vite plugin coverage as Vue apps. Install **`react`**, **`react-dom`**, and (for TypeScript) **`@types/react`** / **`@types/react-dom`** in your application; Flight remains the server/runtime, not the UI runtime.
+
+### Documentation
+
+- README: **React + Vite** quick path (sample `vite.config`, `index.html`, `main.tsx`, `App.tsx`), highlights updated for Vue and React, and clarification that **Flight does not pick Vue vs React**—your **`vite.config`** does.
+
+### Changed
+
+- Development log lines refer to the **Vite** dev server generically (Vue/React per app config).
+
 ## 2.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

@@ -4,17 +4,49 @@
 
 # Flight
 
-**Flight** is a Node.js application server for teams who want something **fast**, **boring in the good way**, and **ready for serious traffic**. You bring your own hosting—there is no lock-in to a proprietary edge or a single vendor’s deployment story. It fits **twelve-factor** style workflows: configuration via environment variables, horizontal scaling, and state kept where it belongs (for Flight, that includes **Redis** for sessions and cache-friendly layers).
+**Flight** is an application server for teams who want something **fast**, **boring in the good way**, and **ready for serious traffic**. You bring your own hosting—there is no lock-in to a proprietary edge or a single vendor’s deployment story. It fits **twelve-factor** style workflows: configuration via environment variables, horizontal scaling, and state kept where it belongs (for Flight, that includes **Redis** for sessions and cache-friendly layers).
 
-Think **platform-agnostic**: not framework-as-a-platform, but a clear runtime you can run wherever Node runs—VMs, Kubernetes, bare metal, your cloud of choice. Flight is aimed at **hyperscale-friendly** designs (cluster workers out of the box), **ephemeral** processes, and **component-shaped** backends so routes stay colocated with the features they serve. **Vue** and **Vite** are first-class today; **React** support is on the roadmap.
+Think **platform-agnostic**: not framework-as-a-platform, but a clear runtime you can run wherever **Node** or **Bun** runs—VMs, Kubernetes, bare metal, your cloud of choice. The `flight` binary is the Node / Koa server. `flight-bun` is the Bun server (`Bun.serve`), and it can still mount existing Koa `router.routes()` backends while you move routes over. Flight is aimed at **hyperscale-friendly** designs (cluster workers on Node, a single Bun process with native TypeScript on the Bun path), **ephemeral** processes, and **component-shaped** backends so routes stay colocated with the features they serve. **Vue** and **React** are both supported through the same **Vite** dev and production flows (your app’s **`vite.config`** chooses the UI stack; Flight does not).
 
 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
 
-- **Performance-focused**: Cluster mode, compression, Redis-backed caching hooks, rate limiting in production
-- **Developer velocity**: Vite-powered dev server with HMR for **Vue** (React roadmap)
-- **Composable backends**: Discover `**/*.backend.ts` under your app root and mount Koa routes per component
+- **Two runtimes**: **Node / Koa** (`flight`) and **Bun** (`flight-bun`). The Bun server loads TypeScript directly, exposes `GET /healthz`, and still accepts existing Koa backends
+- **Performance-focused**: Cluster mode on Node, compression, Redis-backed caching hooks, rate limiting in production
+- **Developer velocity**: **Vite** dev server with HMR on port **3001** for **Vue** or **React** (per your project’s Vite config)
+- **Composable backends**: Discover `**/*.backend.ts` (and `**/*.backend.js` on Bun) under your app root and mount them per component
 - **Production SPA**: Built-in **`dist` + `index.html`** fallback (option B) when running **`production`** with **`disable_vite`**, with an explicit opt-out for API-only processes
 - **Configurable discovery**: `--exclude_paths` / `FLIGHT_EXCLUDE_PATHS` to skip directories when scanning backends
 - **TypeScript-native**: Written for TS projects; sensible defaults, minimal ceremony
@@ -50,6 +82,8 @@ npm init -y
 npm install @thoughtpivot/flight ioredis
 ```
 
+For a **React** UI, also install `react`, `react-dom`, and (with TypeScript) `@types/react` / `@types/react-dom` as dev dependencies. For **Vue**, install `vue` and wire **`@vitejs/plugin-vue`** in **`vite.config`**.
+
 3. Ensure Redis is running locally or set environment variables (see table below).
 
 4. Create a component with a backend route:
@@ -103,24 +137,42 @@ npx flight --mode production
 
 **`--app_home`** defaults to **`.`** (the current working directory). Pass **`--app_home path/to/app`** only when your app root is not the directory you run the command from.
 
-**Try without adding a dependency** (downloads the package for this invocation):
+**Try without adding a dependency** (downloads the package for this invocation). Use **`--package=@scope/pkg`** (equals form) and a literal **`--`** before the binary name so `npx` does not treat `flight` as a separate package or lose the install’s **`node_modules/.bin`** on your `PATH` (otherwise you can see `sh: flight: command not found`):
+
+```bash
+npx --yes --package=@thoughtpivot/flight -- flight --mode development
+```
+
+Equivalent:
 
 ```bash
-npx --yes --package @thoughtpivot/flight flight --mode development
+npm exec --yes --package=@thoughtpivot/flight -- flight --mode development
 ```
 
 **Global install** (optional): `npm install -g @thoughtpivot/flight`, then run **`flight`** from your PATH the same way as **`npx flight`**.
 
+**Bun** (same app directory, [Bun](https://bun.sh) 1.x on your PATH):
+
+```bash
+# development: API on :3000, Vite on :3001
+FLIGHT_MODE=development flight-bun
+
+# production: serve dist/ plus backends
+FLIGHT_MODE=production flight-bun
+```
+
+From a clone of this repo, before the package is published, that is `bun src/bun/server.ts`. Existing `export default router.routes()` files keep working. New files can export a Web `Request` / `Response` route map. Details, env vars, and the backend contract are in [Bun runtime](#bun-runtime).
+
 ## Development vs production
 
-Flight picks **`mode`** as: **`FLIGHT_MODE`** (if set and non-empty), else **`--mode`** from argv, else **`production`**. Everything below assumes Redis is reachable unless you only use routes that avoid session/ratelimit/cache.
+The Node server picks **`mode`** as: **`FLIGHT_MODE`** (if set and non-empty), else **`--mode`** from argv, else **`production`**. The table below is that Node / Koa process. It assumes Redis is reachable unless you only use routes that avoid session, rate limit, and cache. The Bun server is documented in [Bun runtime](#bun-runtime).
 
-| Topic            | Development                                                                                   | Production                                                                                                                                  |
-| ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Vite**         | Child process: `npx vite --port 3001 --host 0.0.0.0` (HMR).                                   | If **`disable_vite` is false**: `exec('npx vite build')` is triggered once at worker startup. If **`disable_vite` is true**: no Vite build. |
-| **Listen port**  | API + sessions on **`--port`** / `FLIGHT_PORT` (default **3000**). UI dev server on **3001**. | Same **`--port`** / `FLIGHT_PORT` for the worker.                                                                                           |
-| **Static / SPA** | The Vite dev server serves UI; Flight does **not** mount the production static/SPA stack.     | See **Production SPA pipeline** below: when **`production`** + **`disable_vite`**, Flight uses **Option A** by default unless opted out.    |
-| **Typical use**  | Local full-stack with HMR.                                                                    | CI-built `dist` served by Flight (or behind a load balancer).                                                                               |
+| Topic            | Development                                                                                              | Production                                                                                                                                  |
+| ---------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Vite**         | Child process: `npx vite --port 3001 --host 0.0.0.0` (HMR for **Vue or React**, per your `vite.config`). | If **`disable_vite` is false**: `exec('npx vite build')` is triggered once at worker startup. If **`disable_vite` is true**: no Vite build. |
+| **Listen port**  | API + sessions on **`--port`** / `FLIGHT_PORT` (default **3000**). UI dev server on **3001**.            | Same **`--port`** / `FLIGHT_PORT` for the worker.                                                                                           |
+| **Static / SPA** | The Vite dev server serves UI; Flight does **not** mount the production static/SPA stack.                | See **Production SPA pipeline** below: when **`production`** + **`disable_vite`**, Flight uses **Option A** by default unless opted out.    |
+| **Typical use**  | Local full-stack with HMR.                                                                               | CI-built `dist` served by Flight (or behind a load balancer).                                                                               |
 
 **Edge cases**
 
@@ -163,6 +215,8 @@ Flight loads a **`.env`** file from the **current working directory** at startup
 | _(n/a)_                              | `FLIGHT_REDIS_PORT`                  | `6379`           | Redis port.                                                                                                                                                                                                     |
 | _(n/a)_                              | `FLIGHT_MAX_WORKERS`                 | CPU count        | Cap cluster worker count on small nodes.                                                                                                                                                                        |
 
+`1`, `true`, and `yes` are matched exactly. `TRUE` does not turn those settings on.
+
 Example `.env` fragment:
 
 ```bash
@@ -227,9 +281,72 @@ router.get('/hello', async (ctx) => {
 export default router.routes()
 ```
 
+## React + Vite (same Flight commands)
+
+Flight does **not** choose Vue vs React—it runs **`vite`** / **`vite build`** from your **`app_home`**; your **`vite.config.*`** and app **`package.json`** select the framework. The `@thoughtpivot/flight` package includes **`@vitejs/plugin-react`** alongside **`@vitejs/plugin-vue`** so React+Vite apps get the same style of transitive plugin coverage as Vue apps. You still install the UI runtime in **your** app. Flight ships **Vite 8** and matching plugins; apps that stay on Vite 6 should pin **`@thoughtpivot/flight@2.0.2`** until they upgrade.
+
+```bash
+npm install react react-dom
+npm install -D @types/react @types/react-dom
+```
+
+Set **`"type": "module"`** in the app **`package.json`** (or use a `.mts` / `.mjs` Vite config) so Vite 8 loads ESM config without falling back to the deprecated CommonJS path.
+
+`vite.config.ts` (project root):
+
+```typescript
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+export default defineConfig({
+    plugins: [react()]
+})
+```
+
+`index.html`:
+
+```html
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Flight + React</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>
+```
+
+`src/main.tsx`:
+
+```tsx
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './App'
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <App />
+    </StrictMode>
+)
+```
+
+`src/App.tsx`:
+
+```tsx
+export default function App() {
+    return <h1>Hello from Flight + React</h1>
+}
+```
+
+Use the same **`npx flight --mode development`** / **`--mode production`** flow as Vue. Production **`dist`**, **`FLIGHT_DISABLE_VITE`**, and the **Production SPA pipeline** behave the same for a Vite-built React SPA.
+
 ## Development mode
 
-- **Vue** + **Vite** with HMR on port **3001**
+- **Vite** with HMR on port **3001** for **Vue or React** (whatever your `vite.config` configures)
 - Backend worker on **`--port`** (default **3000**)
 - Request logging via **`koa-logger`**
 
@@ -283,19 +400,109 @@ flowchart TD
 
 See **[CHANGELOG.md](CHANGELOG.md)** for the full **2.0.0** notes.
 
+## Bun runtime
+
+`flight-bun` is the Bun entry. `npx flight` remains the Node server. From an installed package:
+
+```bash
+FLIGHT_MODE=development flight-bun
+```
+
+From a clone of this repo:
+
+```bash
+FLIGHT_MODE=development bun src/bun/server.ts
+```
+
+`npm run test:bun` runs the Bun suite. `npm test` stays the Node suite.
+
+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.
+
+```typescript
+export default {
+    '/api/hello': {
+        GET: () => Response.json({ message: 'Hello from Flight!' })
+    }
+}
+```
+
+Existing Koa files keep working. `export default router.routes()` is mounted through Koa, including JSON body parsing. That is the on-ramp: boot the app on Bun, then rewrite routes file by file. `*.backend.js` is discovered as well as `*.backend.ts`.
+
+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.                                                                                                                                                |
+| `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. `FLIGHT_MAX_WORKERS` does not: see the cluster note above. `GET /healthz` returns `ok` and is not rate limited.
+
 ## Requirements
 
-- Node.js **16.x** or higher
-- **Redis** (sessions / rate limit / cache integrations)
+- Node.js **`^20.19.0` or `>=22.12.0`** (the `flight` binary; matches Vite 8 / ioredis 6)
+- [Bun](https://bun.sh) 1.x (only for `flight-bun` / `npm run test:bun`)
+- **Redis** (sessions / rate limit / cache integrations on the Node server; optional for the Bun runtime)
 - **TypeScript** in your app if you author `.backend.ts` modules as TS
 
+## CI and npm publish
+
+GitHub Actions is the only CI/publish path:
+
+| Workflow                                                         | When                                                     | What it does                                                    |
+| ---------------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------- |
+| [`.github/workflows/ci.yml`](.github/workflows/ci.yml)           | Pull requests and pushes to `main`                       | `npm ci`, `lint:check`, `npm test` on Node 20 and 22            |
+| [`.github/workflows/publish.yml`](.github/workflows/publish.yml) | GitHub Release published (or manual `workflow_dispatch`) | Re-runs checks, then `npm publish --access public --provenance` |
+
+### One-time npm setup (Trusted Publishing)
+
+Preferred: no long-lived npm token in GitHub.
+
+1. Sign in at [npmjs.com](https://www.npmjs.com/) as a maintainer of `@thoughtpivot/flight`.
+2. Open the package → **Settings** → **Trusted Publisher**.
+3. Add GitHub Actions with:
+    - **Organization / user:** `thoughtpivot`
+    - **Repository:** `flight`
+    - **Workflow filename:** `publish.yml`
+    - **Environment name:** `npm` (must match the workflow `environment:`)
+4. In the GitHub repo, create an **Environment** named `npm` (Settings → Environments). Optional: require reviewers before publish.
+
+Fallback if Trusted Publishing is unavailable: add a repository or environment secret **`NPM_TOKEN`** (granular token with read/write to `@thoughtpivot/flight`). The publish workflow already passes it as `NODE_AUTH_TOKEN` when present.
+
+### Cut a release
+
+1. Land the version bump on `main` (`package.json` + `CHANGELOG.md`).
+2. Create a GitHub Release whose tag is `v` + that version (example: package `3.0.0` → tag `v3.0.0`).
+3. Publishing the release runs `.github/workflows/publish.yml`. The job fails if the tag and `package.json` version disagree.
+
+Dry-run without publishing: Actions → **Publish** → **Run workflow** → leave **dry_run** checked.
+
 ## License
 
-MIT
+Apache-2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
 
 ## Contributing
 
-Issues and pull requests are welcome. Flight improves fastest with real workloads—if you hit an edge case, open an issue with a minimal repro.
+Issues and pull requests are welcome. Flight improves fastest with real workloads—if you hit an edge case, open an issue with a minimal repro. Run `npm test` and `npm run lint:check` before opening a PR.
 
 ## Acknowledgments
 

package/dist/backend-discovery.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeExcludePaths = normalizeExcludePaths;
+exports.dedupeStrings = dedupeStrings;
+exports.mergeExcludePaths = mergeExcludePaths;
+exports.backendDiscoveryIgnorePatterns = backendDiscoveryIgnorePatterns;
+const path_1 = __importDefault(require("path"));
+/** Turn a CLI value or env string into trimmed, comma-split directory names. */
+function normalizeExcludePaths(value) {
+    if (value == null || value === '')
+        return [];
+    const parts = Array.isArray(value) ? value : [value];
+    const out = [];
+    for (const p of parts) {
+        const s = String(p).trim();
+        if (!s)
+            continue;
+        out.push(...s
+            .split(',')
+            .map((x) => x.trim())
+            .filter(Boolean));
+    }
+    return out;
+}
+/** Preserve first-seen order while dropping duplicate strings. */
+function dedupeStrings(items) {
+    return [...new Set(items)];
+}
+/** Combine CLI and FLIGHT_EXCLUDE_PATHS values, CLI first, without duplicates. */
+function mergeExcludePaths(cliValue, envValue) {
+    return dedupeStrings([...normalizeExcludePaths(cliValue), ...normalizeExcludePaths(envValue)]);
+}
+/**
+ * Build fast-glob ignore globs for trees rooted under `appRootAbs`.
+ * Entries that resolve outside that root, or to the root itself, are skipped.
+ * Folder names are not escaped, so a name like `[abc]` is still a fast-glob pattern.
+ */
+function backendDiscoveryIgnorePatterns(appRootAbs, excludeRelativeDirs) {
+    const patterns = [];
+    for (const raw of excludeRelativeDirs) {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        const resolved = path_1.default.resolve(appRootAbs, trimmed);
+        const rel = path_1.default.relative(appRootAbs, resolved);
+        const relPosix = rel.replace(/\\/g, '/');
+        if (!relPosix) {
+            console.warn(`Flight: exclude_paths entry skipped (would ignore all of app_home): ${trimmed}`);
+            continue;
+        }
+        if (relPosix === '..' || relPosix.startsWith('../') || path_1.default.isAbsolute(rel)) {
+            console.warn(`Flight: exclude_paths entry skipped (outside app_home): ${trimmed}`);
+            continue;
+        }
+        patterns.push(`${relPosix}/**`);
+    }
+    return patterns;
+}