From 29f9ade3bc2ea17c42011ca41ec045debb75671e Mon Sep 17 00:00:00 2001 From: opensource-elearning <159253500+opensource-elearning@users.noreply.github.com> Date: Fri, 16 Oct 2026 00:49:28 +0530 Subject: [PATCH] fix(build,docs): document expected build warnings + quiet build-phase JWT FATAL (#16320) (#16324) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit fix(build,docs): document the expected production-build warnings and suppress the JWT_SECRET FATAL log only during `next build`. POST /api/auth/login still fail-closes when the secret is missing. Closes #16320 Boarded with #16346, #16342, and #16323 on detached `62049e9cb8`. Focused tests: tests/unit/16320-build-warnings.test.ts 4 pass, tests/unit/build/known-build-warnings.test.ts 7 pass (23/23 across the batch). File-size, changelog integrity, eslint, typecheck:core, complexity (3038/3218), cognitive complexity (1400/1437), and docs-counts (retry) passed. CI Lint is the inherited `executeTargetAttempt.ts` ceiling, a file this PR does not touch, and Build was cancelled. Thanks @opensource-elearning. ⚠️ base-red inherited: #15306 --- .../fixes/16320-document-build-warnings.md | 1 + docs/ops/BUILD_WARNINGS.md | 99 +++++++++++++++++++ docs/ops/meta.json | 1 + next.config.mjs | 43 +------- scripts/build/knownBuildWarnings.mjs | 69 +++++++++++++ src/app/api/auth/login/route.ts | 16 ++- tests/unit/16320-build-warnings.test.ts | 67 +++++++++++++ tests/unit/build/known-build-warnings.test.ts | 85 ++++++++++++++++ 8 files changed, 341 insertions(+), 40 deletions(-) create mode 100644 changelog.d/fixes/16320-document-build-warnings.md create mode 100644 docs/ops/BUILD_WARNINGS.md create mode 100644 scripts/build/knownBuildWarnings.mjs create mode 100644 tests/unit/16320-build-warnings.test.ts create mode 100644 tests/unit/build/known-build-warnings.test.ts diff --git a/changelog.d/fixes/16320-document-build-warnings.md b/changelog.d/fixes/16320-document-build-warnings.md new file mode 100644 index 00000000000..c4cae8e8eab --- /dev/null +++ b/changelog.d/fixes/16320-document-build-warnings.md @@ -0,0 +1 @@ +- Build: documented the expected production-build warnings in `docs/ops/BUILD_WARNINGS.md`, stopped the login route from logging `[SECURITY] FATAL: JWT_SECRET is not set` during `next build`, and widened the Fumadocs MDX build-cache warning filter to cover the `dist/eval-*.js` bundle ([#16320](https://github.com/diegosouzapw/OmniRoute/issues/16320)). diff --git a/docs/ops/BUILD_WARNINGS.md b/docs/ops/BUILD_WARNINGS.md new file mode 100644 index 00000000000..a47006a2cee --- /dev/null +++ b/docs/ops/BUILD_WARNINGS.md @@ -0,0 +1,99 @@ +--- +title: "Build Warnings Reference" +version: 3.8.52 +lastUpdated: 2026-10-11 +--- + +# Build Warnings Reference + +`npm run build` and `npm run build:release` print a handful of warnings that are +**expected** and do not mean the artifact is broken. This page catalogs them, says +whether each one is actionable, and points at the code that owns it — so an operator can +tell known build-time noise from a real regression. + +If a message you see is not listed here, treat it as new and investigate it. + +## Webpack "Critical dependency" for `open-sse/executors/codex.ts` + +``` +./open-sse/executors/codex.ts +Critical dependency: require function is used in a way in which dependencies cannot be statically extracted +``` + +**Expected — intentional.** `open-sse/executors/codex/wreqLoader.ts` loads the optional +`wreq-js` native helper through a `createRequire()`-returned function whose specifier is +kept as a **variable** on purpose (`Reflect.apply(requireFn, undefined, [moduleName])`). A +literal specifier is statically rewritten by Turbopack into a hashed `.next`-relative +require that does not exist in the standalone Docker runtime, so the dynamic form is +required (#12491). The warning is the price of that pattern; the module still resolves at +runtime and is not a missing dependency. + +Because the loader is imported by the Codex quota service, instrumentation, and the +internal Codex WebSocket route, webpack reports the same warning once per import path. + +## Fumadocs MDX "build dependencies" cache warning + +``` +[webpack.cache.PackFileCacheStrategy/webpack.FileSystemInfo] Parsing of +.../fumadocs-mdx/dist/eval-*.js for build dependencies failed at 'import(pathToFileURL(outfile).href)'. +Build dependencies behind this expression are ignored and might cause incorrect cache invalidation. +``` + +**Upstream `fumadocs-mdx`, not actionable.** The package emits a dynamic `import()` of a +generated module that webpack's `FileSystemInfo` pass cannot statically follow. The only +consequence is that webpack may invalidate its build cache more often for that dependency; +the **emitted output is unaffected**. OmniRoute suppresses the known benign form in +`next.config.mjs` via `scripts/build/knownBuildWarnings.mjs`, which allow-lists the whole +`node_modules/fumadocs-mdx/dist/` directory (both the `load-from-file-*.js` and +`eval-*.js` bundles). + +## Runtime configuration messages during static generation + +`next build` imports application modules while collecting page data, so a few +runtime-oriented log lines appear during the build as well. They are **not** build errors. + +| Message | Owner | Meaning | +| --------------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| `[DB] Build phase detected — using no-op SQLite stub (never queried)` | `src/lib/db/core.ts` | The build never opens the real database. Expected. | +| `[REDIS] REDIS_URL is not set in production. Using in-memory rate limiting.` | `src/shared/utils/rateLimiter.ts` | Redis is optional; without it rate limiting falls back to memory. Set it only if you run Redis in production — see `REDIS_PRODUCTION_CONFIG.md`. | +| `[CREDENTIALS] No external credentials file found, using defaults.` | `open-sse/config/credentialLoader.ts` | Expected unless you ship an external credentials file. | +| `[INFO] [PLUGIN_SCANNER] scanner.dir_resolved` / `[INFO] [MEMORY_MANAGER] Registered backend` | plugin + memory registries | Informational. | + +### `[SECURITY] FATAL: JWT_SECRET is not set` + +`JWT_SECRET` is **required at runtime** — without it, login fails closed and the dashboard +is unreachable. Set it in your environment before starting the server (see +`../reference/ENVIRONMENT.md`). + +During `next build` the login route module used to be imported while collecting page data +with no `JWT_SECRET`, and printed the same `FATAL` line, which reads like a live security +failure. That message is now skipped during the build phase: the module-level warning in +`src/app/api/auth/login/route.ts` is gated on `isNextBuildPhase()` +(`src/lib/buildPhase.ts`), which matches `NEXT_PHASE=phase-production-build`, +`OMNIROUTE_BUILDING=1`, and `npm_lifecycle_event=build`. The request handler still returns +`500` when the secret is missing at runtime, so runtime behavior is unchanged. + +## Bun and dependency installation + +OmniRoute is built and run with **Node.js** (`engines.node` in `package.json`). Install +dependencies with `npm ci` (or `npm install`): + +```bash +npm ci +npm run build:release +``` + +**`bun install` is not a supported way to install OmniRoute's dependencies** for this +branch. Bun `1.4.2` is pinned as a devDependency and is used only to run a small, +allow-listed set of gate/generator scripts. If you install with Bun you may see: + +- `warn: Bun currently only supports one level of nested "overrides"` — Bun's support for + `package.json` `overrides` is shallower than npm's; npm applies the full tree. +- **Blocked lifecycle scripts** for native packages (ONNX Runtime, Playwright Chromium, + SWC, protobufjs, Parcel Watcher, unrs-resolver). Bun blocks install scripts by default; + the supported `npm ci` path runs them, and `npm run check:native-deps` verifies that + every externalized package resolves afterward. + +If a Bun-invoked gate script fails with `bun: not found`, the tree is stale — re-run +`npm install`. If `node_modules/bun/bin/bun.exe` is a tiny shell-script placeholder instead +of the real binary, its `postinstall` was skipped; run `cd node_modules/bun && node install.js`. diff --git a/docs/ops/meta.json b/docs/ops/meta.json index 8944fb781c3..aca369bd53f 100644 --- a/docs/ops/meta.json +++ b/docs/ops/meta.json @@ -3,6 +3,7 @@ "pages": [ "RELEASE_CHECKLIST", "RELEASE_GREEN", + "BUILD_WARNINGS", "BRANCHING_MODEL", "RELEASE_STRATEGY", "BRANCH_PROTECTION_MAIN", diff --git a/next.config.mjs b/next.config.mjs index 367290af674..92d9a245269 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -11,6 +11,10 @@ import { resolveDashboardEmbedMode, } from "./scripts/build/dashboardEmbed.mjs"; import { shouldBuildStandalone } from "./scripts/build/backendOnlyPages.mjs"; +import { + filterKnownInfrastructureWarnings, + isNextIntlExtractorDynamicImportWarning, +} from "./scripts/build/knownBuildWarnings.mjs"; const withNextIntl = createNextIntlPlugin("./src/i18n/request.ts"); const distDir = process.env.NEXT_DIST_DIR || ".build/next"; @@ -65,45 +69,6 @@ const securityHeaders = [ }, ]; -function isNextIntlExtractorDynamicImportWarning(warning) { - const message = typeof warning === "string" ? warning : warning?.message || ""; - const resource = warning?.module?.resource || warning?.file || ""; - const target = "next-intl/dist/esm/production/extractor/format/index.js"; - return ( - resource.includes(target) && - (message.includes("import(t)") || message.includes("dependency is an expression")) - ); -} - -const IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES = [ - "/node_modules/fumadocs-mdx/dist/load-from-file-", - "/node_modules/next-intl/dist/esm/production/extractor/format/index.js", -]; - -function isKnownInfrastructureBuildDependencyWarning(args) { - const message = args - .filter((value) => typeof value === "string") - .join(" ") - .replaceAll("\\", "/"); - return ( - message.includes("webpack.FileSystemInfo") && - message.includes("for build dependencies failed at 'import(") && - message.includes("incorrect cache invalidation") && - IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES.some((modulePath) => - message.includes(modulePath) - ) - ); -} - -function filterKnownInfrastructureWarnings(baseConsole) { - const filteredConsole = Object.create(baseConsole); - filteredConsole.warn = (...args) => { - if (isKnownInfrastructureBuildDependencyWarning(args)) return; - Reflect.apply(baseConsole.warn, baseConsole, args); - }; - return filteredConsole; -} - // OMNIROUTE_BUILD_PROFILE=minimal physically removes four optional privileged // modules (MITM cert install, Zed keychain import, Cloud Sync, 9router // installer) from the built bundle by aliasing them to feature-disabled stubs. diff --git a/scripts/build/knownBuildWarnings.mjs b/scripts/build/knownBuildWarnings.mjs new file mode 100644 index 00000000000..4e78d9c8707 --- /dev/null +++ b/scripts/build/knownBuildWarnings.mjs @@ -0,0 +1,69 @@ +/** + * Known, non-actionable Next.js/webpack build warnings. + * + * Kept in a standalone module (rather than inlined in `next.config.mjs`) so the + * matching logic is unit-testable. The #16320 report showed the Fumadocs MDX + * "build dependencies" warning escaping the allowlist because the entry only + * matched the `dist/load-from-file-*.js` bundle, never the `dist/eval-*.js` one + * that webpack actually parsed in production. + */ + +/** + * Bundled third-party files whose `import()` a webpack + * `FileSystemInfo` pass cannot statically resolve. The warning never indicates + * broken output — only coarser build-cache invalidation for that dependency. + */ +export const IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES = [ + // `fumadocs-mdx` emits both `dist/load-from-file-*.js` and `dist/eval-*.js`; + // match the whole `dist/` directory so a renamed bundle cannot re-open #16320. + "/node_modules/fumadocs-mdx/dist/", + "/node_modules/next-intl/dist/esm/production/extractor/format/index.js", +]; + +/** + * True for the `webpack.FileSystemInfo` "build dependencies failed" warning + * raised for one of the allow-listed third-party modules above. + */ +export function isKnownInfrastructureBuildDependencyWarning(args) { + const values = Array.isArray(args) ? args : [args]; + const message = values + .filter((value) => typeof value === "string") + .join(" ") + .replaceAll("\\", "/"); + return ( + message.includes("webpack.FileSystemInfo") && + message.includes("for build dependencies failed at 'import(") && + message.includes("incorrect cache invalidation") && + IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES.some((modulePath) => + message.includes(modulePath) + ) + ); +} + +/** + * True for the `next-intl` production extractor's dynamic-import webpack warning + * (matched by module resource, since the message text is generic). + */ +export function isNextIntlExtractorDynamicImportWarning(warning) { + const message = typeof warning === "string" ? warning : warning?.message || ""; + const resource = warning?.module?.resource || warning?.file || ""; + const target = "next-intl/dist/esm/production/extractor/format/index.js"; + return ( + resource.includes(target) && + (message.includes("import(t)") || message.includes("dependency is an expression")) + ); +} + +/** + * Wrap a webpack infrastructure-logging console so the known-benign build + * dependency warnings above are dropped while every other message passes + * through untouched. + */ +export function filterKnownInfrastructureWarnings(baseConsole) { + const filteredConsole = Object.create(baseConsole); + filteredConsole.warn = (...args) => { + if (isKnownInfrastructureBuildDependencyWarning(args)) return; + Reflect.apply(baseConsole.warn, baseConsole, args); + }; + return filteredConsole; +} diff --git a/src/app/api/auth/login/route.ts b/src/app/api/auth/login/route.ts index d5f626e8358..bf81cc7679e 100644 --- a/src/app/api/auth/login/route.ts +++ b/src/app/api/auth/login/route.ts @@ -10,6 +10,7 @@ import { verifyManagementPassword, } from "@/lib/auth/managementPassword"; import { isFeatureFlagEnabled } from "@/shared/utils/featureFlags"; +import { isNextBuildPhase } from "@/lib/buildPhase"; import { loginSchema } from "@/shared/validation/schemas"; import { isValidationFailure, validateBody } from "@/shared/validation/helpers"; import { @@ -30,14 +31,27 @@ import { } from "@/server/auth/loginPeer"; import { getRequestPeerLocality } from "@/shared/utils/apiAuth"; +/** + * Whether the module-level missing-JWT_SECRET warning should fire. It is + * suppressed while `next build` imports this route to collect page data, where + * the secret is legitimately absent (the operator supplies it at container + * start) and the FATAL wording is misleading rather than actionable (#16320). + * The POST handler still fails closed when the secret is missing at runtime. + */ +function shouldWarnMissingJwtSecret(): boolean { + return !process.env.JWT_SECRET && !isNextBuildPhase(); +} + // SECURITY: No hardcoded fallback — JWT_SECRET must be configured. -if (!process.env.JWT_SECRET) { +if (shouldWarnMissingJwtSecret()) { console.error("[SECURITY] FATAL: JWT_SECRET is not set. Login authentication is disabled."); } // Test seam for cookie store injection without affecting runtime behavior. export const authRouteInternals = { getCookieStore: cookies, + /** True when the module-level missing-JWT_SECRET warning should fire (#16320). */ + shouldWarnMissingJwtSecret, }; export async function POST(request: NextRequest) { diff --git a/tests/unit/16320-build-warnings.test.ts b/tests/unit/16320-build-warnings.test.ts new file mode 100644 index 00000000000..48ecbe0276d --- /dev/null +++ b/tests/unit/16320-build-warnings.test.ts @@ -0,0 +1,67 @@ +/** + * #16320 — during `next build` (page-data collection) the login route module is + * imported with no JWT_SECRET, and its module-level `console.error` printed + * `[SECURITY] FATAL: JWT_SECRET is not set. Login authentication is disabled.` + * That reads like a runtime security failure. The warning must stay for the + * runtime, and be suppressed for the build phase. + */ +import test from "node:test"; +import assert from "node:assert/strict"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; + +const TEST_DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), "omniroute-16320-")); +process.env.DATA_DIR = TEST_DATA_DIR; +process.env.JWT_SECRET = "test-jwt-secret-16320"; + +const loginRoute = await import("../../src/app/api/auth/login/route.ts"); +const shouldWarn = loginRoute.authRouteInternals.shouldWarnMissingJwtSecret; + +const BUILD_SIGNAL_KEYS = ["NEXT_PHASE", "OMNIROUTE_BUILDING", "npm_lifecycle_event"] as const; +const saved = { + JWT_SECRET: process.env.JWT_SECRET, + ...Object.fromEntries(BUILD_SIGNAL_KEYS.map((key) => [key, process.env[key]])), +} as Record; + +function clearBuildSignals() { + for (const key of BUILD_SIGNAL_KEYS) delete process.env[key]; +} + +test.after(() => { + for (const [key, value] of Object.entries(saved)) { + if (value === undefined) delete process.env[key]; + else process.env[key] = value; + } + fs.rmSync(TEST_DATA_DIR, { recursive: true, force: true }); +}); + +test("no FATAL during the Next.js build phase when JWT_SECRET is absent (#16320)", () => { + clearBuildSignals(); + delete process.env.JWT_SECRET; + process.env.NEXT_PHASE = "phase-production-build"; + + assert.equal(shouldWarn(), false); +}); + +test("OMNIROUTE_BUILDING=1 also suppresses the warning (build-worker signal)", () => { + clearBuildSignals(); + delete process.env.JWT_SECRET; + process.env.OMNIROUTE_BUILDING = "1"; + + assert.equal(shouldWarn(), false); +}); + +test("the runtime warning is preserved when JWT_SECRET is missing", () => { + clearBuildSignals(); + delete process.env.JWT_SECRET; + + assert.equal(shouldWarn(), true); +}); + +test("no warning when JWT_SECRET is configured at runtime", () => { + clearBuildSignals(); + process.env.JWT_SECRET = "configured-secret"; + + assert.equal(shouldWarn(), false); +}); diff --git a/tests/unit/build/known-build-warnings.test.ts b/tests/unit/build/known-build-warnings.test.ts new file mode 100644 index 00000000000..a39ee7049e2 --- /dev/null +++ b/tests/unit/build/known-build-warnings.test.ts @@ -0,0 +1,85 @@ +/** + * #16320 — the production build reported the Fumadocs MDX build-dependency + * warning for `fumadocs-mdx/dist/eval-*.js`, but the infrastructure-log filter + * only allow-listed `dist/load-from-file-*.js`, so the warning leaked through. + * + * These cases pin the match to the whole `dist/` directory and guard the + * passthrough behavior of the console wrapper. + */ +import { test } from "node:test"; +import assert from "node:assert/strict"; + +import { + IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES, + filterKnownInfrastructureWarnings, + isKnownInfrastructureBuildDependencyWarning, + isNextIntlExtractorDynamicImportWarning, +} from "../../../scripts/build/knownBuildWarnings.mjs"; + +const ISSUE_WARNING = [ + "[webpack.cache.PackFileCacheStrategy/webpack.FileSystemInfo] Parsing of", + "/home/temp/OmniRoute/node_modules/fumadocs-mdx/dist/eval-Cldqy98u.js", + "for build dependencies failed at 'import(pathToFileURL(outfile).href)'.", + "Build dependencies behind this expression are ignored and might cause incorrect cache invalidation.", +].join(" "); + +test("the reported fumadocs-mdx eval-*.js warning is recognized (#16320)", () => { + assert.equal(isKnownInfrastructureBuildDependencyWarning([ISSUE_WARNING]), true); +}); + +test("the load-from-file-* fumadocs-mdx bundle shape stays recognized", () => { + const warning = ISSUE_WARNING.replace("eval-Cldqy98u.js", "load-from-file-abc123.js"); + assert.equal(isKnownInfrastructureBuildDependencyWarning([warning]), true); +}); + +test("Windows-style backslash paths are normalized before matching", () => { + const warning = ISSUE_WARNING.replaceAll("/", "\\"); + assert.equal(isKnownInfrastructureBuildDependencyWarning([warning]), true); +}); + +test("an unrelated FileSystemInfo warning is not swallowed", () => { + const warning = [ + "[webpack.cache.PackFileCacheStrategy/webpack.FileSystemInfo] Parsing of", + "/repo/node_modules/some-other-lib/dist/index.js", + "for build dependencies failed at 'import(expr)'.", + "Build dependencies behind this expression are ignored and might cause incorrect cache invalidation.", + ].join(" "); + assert.equal(isKnownInfrastructureBuildDependencyWarning([warning]), false); +}); + +test("the fumadocs allowlist matches the dist directory, not a single bundle name", () => { + assert.ok( + IGNORED_INFRASTRUCTURE_BUILD_DEPENDENCY_MODULES.some((entry) => + entry.includes("/node_modules/fumadocs-mdx/dist/") + ) + ); +}); + +test("filterKnownInfrastructureWarnings drops known noise and forwards everything else", () => { + const seen = []; + const baseConsole = { warn: (...args) => seen.push(args) }; + const filtered = filterKnownInfrastructureWarnings(baseConsole); + + filtered.warn(ISSUE_WARNING); + filtered.warn("a genuine warning"); + + assert.deepEqual(seen, [["a genuine warning"]]); +}); + +test("isNextIntlExtractorDynamicImportWarning matches only the extractor resource", () => { + const resource = "node_modules/next-intl/dist/esm/production/extractor/format/index.js"; + assert.equal( + isNextIntlExtractorDynamicImportWarning({ + module: { resource }, + message: "the request of a dependency is an expression", + }), + true + ); + assert.equal( + isNextIntlExtractorDynamicImportWarning({ + module: { resource: "node_modules/other/index.js" }, + message: "the request of a dependency is an expression", + }), + false + ); +});