From eb09e894cbeb5f121fb0a49bcf8fc3271a1c016e Mon Sep 17 00:00:00 2001 From: Paco Cartones <253313177+pacocartones@users.noreply.github.com> Date: Wed, 2 Sep 2026 08:13:31 +0200 Subject: [PATCH] docs: align env and troubleshooting docs with the code (#12404) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four documentation claims contradicted the code: .env.example called OMNIROUTE_USE_TURBOPACK dev-only and said the production build still uses webpack (it reads the same flag and defaults to Turbopack); the README's Bun section said `bun run build` auto-detects Bun and switches to Webpack (only `bun run dev` does — the production bundler is decided by the flag alone); TROUBLESHOOTING.md gave OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT a default of 1 when unset means no request-count cap; and it quoted the pre-#12223 wording of the structural 503 chat_admission_busy message. The Retry-After bullet in the same section is deliberately untouched because #12395 rewrites it. Validated in a combined worktree with all 25 PRs of this batch boarded together: typecheck:core clean, 443/443 node-runner tests plus 14/14 vitest across every test file the batch touches, and check-changelog-integrity, check:cycles (418 files), check:provider-consistency (272 REGISTRY entries, 355 canonical providers), check:docs-counts, check:docs-sync (42 locales) and check-file-size all green. Thanks @pacocartones. --- .env.example | 7 ++++--- README.md | 2 +- .../maintenance/12404-env-and-troubleshooting-drift.md | 1 + docs/guides/TROUBLESHOOTING.md | 6 +++--- 4 files changed, 9 insertions(+), 7 deletions(-) create mode 100644 changelog.d/maintenance/12404-env-and-troubleshooting-drift.md diff --git a/.env.example b/.env.example index 9b93361457..e4ef62f091 100644 --- a/.env.example +++ b/.env.example @@ -240,7 +240,7 @@ PORT=20128 # Used by: src/app/api/v1/relay/chat/completions/route.ts # RELAY_IP_PER_MINUTE=30 -# Bundler selection for `npm run dev`. Set to 0 to fall back to webpack. +# Bundler selection for `npm run dev` and `npm run build`. Set to 0 to fall back to webpack. # Default is 1 (Turbopack). PR #4092 had forced webpack because earlier # Turbopack 16.2.x panicked on the OmniRoute module graph with "internal error: # entered unreachable code: there must be a path to a root" @@ -250,8 +250,9 @@ PORT=20128 # /api/v1/models, /api/mcp) and repeated HMR rebuilds: zero panics. Turbopack # also keeps dev memory far lower on the edit→rebuild loop (HMR rebuild RSS stays # ~flat vs webpack's monotonic growth), which mitigates the dev-server OOM on -# this 60+ route app. The production build still uses webpack (build pipeline is -# unaffected by this dev-only flag). +# this 60+ route app. The production build (scripts/build/build-next-isolated.mjs) +# reads the same flag: Turbopack by default, 0 builds with webpack (`npm run +# build:contributor` sets it for you). OMNIROUTE_USE_TURBOPACK=1 # Disable systemd sd_notify (Type=notify / WatchdogSec=) even when running diff --git a/README.md b/README.md index cec7cb1924..8fe723c816 100644 --- a/README.md +++ b/README.md @@ -1020,7 +1020,7 @@ Full table: [Docker Guide — runtime RAM](docs/guides/DOCKER_GUIDE.md#runtime-r Standard `bun install` and global installation (`bun install -g omniroute`) are supported via Bun runtime detection: - **Built-in `bun:sqlite`**: OmniRoute uses Bun's built-in `bun:sqlite` driver when running under Bun, falling back to `better-sqlite3` on Node.js or `sql.js`. -- **Automatic Webpack bundler selection**: Development (`bun run dev`) and production builds (`bun run build`) automatically detect Bun and disable Turbopack in favor of Webpack to prevent native V8 binding incompatibilities. +- **Automatic Webpack bundler selection in dev**: Development (`bun run dev`) automatically detects Bun and disables Turbopack in favor of Webpack to prevent native V8 binding incompatibilities. Production builds (`bun run build`) follow `OMNIROUTE_USE_TURBOPACK` exactly as on Node: Turbopack by default, `OMNIROUTE_USE_TURBOPACK=0` to build with Webpack (`Dockerfile.bun` exposes it as a `--build-arg`). - **Dedicated Bun Dockerfile**: Multi-stage `Dockerfile.bun` for native Bun production deployments (`docker build -f Dockerfile.bun -t omniroute:bun .`). ```bash diff --git a/changelog.d/maintenance/12404-env-and-troubleshooting-drift.md b/changelog.d/maintenance/12404-env-and-troubleshooting-drift.md new file mode 100644 index 0000000000..527943736e --- /dev/null +++ b/changelog.d/maintenance/12404-env-and-troubleshooting-drift.md @@ -0,0 +1 @@ +- **docs(env):** align `.env.example`, the README Bun section, and the troubleshooting guide with the code: `OMNIROUTE_USE_TURBOPACK` also governs `npm run build` (not dev-only), `bun run build` follows that flag instead of auto-selecting Webpack, `OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT` is unset by default (no request-count cap), and the structural `503 chat_admission_busy` message matches `chatAdmissionResponses.ts` (#12404 — thanks @pacocartones) diff --git a/docs/guides/TROUBLESHOOTING.md b/docs/guides/TROUBLESHOOTING.md index c08476b5f3..4e0cb8883b 100644 --- a/docs/guides/TROUBLESHOOTING.md +++ b/docs/guides/TROUBLESHOOTING.md @@ -52,7 +52,7 @@ Common problems and solutions for OmniRoute. ```bash export OMNIROUTE_ROTATE_ON_400=true # hop to another model/provider on 400/401 (skips broken passthrough models) -export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4 # raise the heavyweight admission ceiling (default 1) so long-context bursts are not rejected +export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4 # explicit heavyweight admission ceiling (unset by default: no request-count cap, see note below) export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # longer bounded wait for heavyweight capacity instead of an immediate retryable 503 ``` @@ -556,8 +556,8 @@ The byte-based response body is: ``` The structure-based response uses the same type and code, with the message -`Structurally heavy chat request capacity is busy; retry shortly.` and -`reason: "structure_limit"`. +`Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly.` +and `reason: "structure_limit"`. At the default thresholds, a request is structurally heavy when it has at least `200` messages, at least `64` tools, or at least `32,000` estimated tokens, or when bounded structure estimation exhausts its bounds of `10,000` visited nodes or depth `12`.