refactor(management): load Lab and routing-profile handlers per namespace

src/server/management-api.ts

@@ -61,15 +61,12 @@ import { handleConfigRoutes } from "./management/config-routes";
 import { handleLogsUsageRoutes } from "./management/logs-usage-routes";
 import { handleRequestHistoryRoutes } from "./management/request-history-routes";
 import { handleRoutingAnalyticsRoutes } from "./management/routing-analytics-routes";
-import { handleRoutingProfileRoutes } from "./management/routing-profile-routes";
 import { handleProviderRoutes } from "./management/provider-routes";
 import { handleModelRoutes } from "./management/model-routes";
 import { handleAgentSettingsRoutes } from "./management/agent-settings-routes";
 import { handleOauthAccountRoutes } from "./management/oauth-account-routes";
 import { handleComboRoutes } from "./management/combo-routes";
 import { handleSystemRoutes } from "./management/system-routes";
-import { handleLabRoutes } from "./management/lab-routes";
-import { handleLabAutomationRoutes } from "./management/lab-automation-routes";
 import { handleSidebarRoutes } from "./management/sidebar-routes";
 import { handleIntegrationRoutes } from "./management/integration-routes";
 import { handleNativeIntegrationRoutes } from "./management/native-integration-routes";
@@ -96,6 +93,41 @@ const managementConvergenceBindings = new WeakMap<object, Readonly<{
   converge: ConvergeCodex;
 }>>();
 
+/**
+ * Namespace match for management route prefixes: exact hit or a child path, never a
+ * prefix collision (`/api/labfoo` must not match `/api/lab`).
+ */
+function pathInManagementNamespace(pathname: string, prefix: string): boolean {
+  return pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+
+/**
+ * Routing-profile and Compatibility Lab handlers statically import the Lab module graph,
+ * so mounting them eagerly would pull ~70 `src/lab/` modules into every management
+ * request -- including installs that never opted into Lab. Loading them per namespace
+ * keeps `management-api.ts` on the same footing as the three protected core files.
+ *
+ * Cherry-picked from @Wibias's PR #1676, which solved this before the boundary work
+ * reached it. See devlog/_plan/260814_lab_core_decoupling/.
+ */
+async function handleRoutingProfileRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (!pathInManagementNamespace(ctx.url.pathname, "/api/routing-profiles")) return null;
+  const { handleRoutingProfileRoutes } = await import("./management/routing-profile-routes");
+  return handleRoutingProfileRoutes(ctx);
+}
+
+async function handleLabRoutesOnDemand(ctx: ManagementContext): Promise<Response | null> {
+  if (!pathInManagementNamespace(ctx.url.pathname, "/api/lab")) return null;
+  // Automation is checked first so its narrower namespace keeps its own handler, matching
+  // the eager chain's ordering.
+  if (pathInManagementNamespace(ctx.url.pathname, "/api/lab/automation")) {
+    const { handleLabAutomationRoutes } = await import("./management/lab-automation-routes");
+    return handleLabAutomationRoutes(ctx);
+  }
+  const { handleLabRoutes } = await import("./management/lab-routes");
+  return handleLabRoutes(ctx);
+}
+
 export async function handleManagementAPI(
   req: Request,
   url: URL,
@@ -180,7 +212,7 @@ export async function handleManagementAPI(
     ??     (await handleLogsUsageRoutes(ctx))
     ??     (await handleRequestHistoryRoutes(ctx))
     ??     (await handleRoutingAnalyticsRoutes(ctx))
-    ??     (await handleRoutingProfileRoutes(ctx))
+    ??     (await handleRoutingProfileRoutesOnDemand(ctx))
     ??     (await handleProviderRoutes(ctx))
     ??     (await handleModelRoutes(ctx))
     ??     (await handleIntegrationRoutes(ctx))
@@ -189,8 +221,7 @@ export async function handleManagementAPI(
     ??     (await handleOauthAccountRoutes(ctx))
     ??     (await handleComboRoutes(ctx))
     ??     (await handleSystemRoutes(ctx))
-    ??     (await handleLabAutomationRoutes(ctx))
-    ??     (await handleLabRoutes(ctx))
+    ??     (await handleLabRoutesOnDemand(ctx))
       ?? (await handleSidebarRoutes(ctx));
   } catch (error) {
     const tooLarge = managementBodyTooLargeResponse(error, req, config);

tests/core-lab-boundary.test.ts

@@ -19,6 +19,10 @@ const PROTECTED = [
   "src/router.ts",
   "src/server/lifecycle.ts",
   "src/server/responses/core.ts",
+  // The management API is mounted for every dashboard request, so eagerly importing the
+  // Lab and routing-profile handlers put ~70 Lab modules on that path too. Its handlers
+  // now load per namespace.
+  "src/server/management-api.ts",
 ] as const;
 
 const repoRoot = resolve(dirname(new URL(import.meta.url).pathname), "..");
@@ -61,6 +65,12 @@ function firstLabPath(entry: string): string[] | null {
     while ((match = IMPORT_RE.exec(source)) !== null) {
       const spec = match[1] ?? match[2] ?? match[3] ?? match[4];
       if (!spec) continue;
+      // A dynamic `import()` is a deferred edge, not a load-time one: the module graph is
+      // only entered if that branch actually runs. Lazy loading behind a namespace or
+      // activation check is precisely the remedy this guard exists to encourage, so a
+      // dynamic specifier does not propagate the walk. Guard 1 still forbids a DIRECT
+      // dynamic Lab import in a protected file, which is what stops it being a loophole.
+      if (match[4] !== undefined) continue;
       const next = resolveSpec(spec, current);
       if (!next || previous.has(next)) continue;
       previous.set(next, current);
@@ -84,7 +94,10 @@ describe("core / Compatibility Lab boundary", () => {
   test.each(PROTECTED)("%s has no direct src/lab import", file => {
     const source = readFileSync(resolve(repoRoot, file), "utf8");
     const direct = /^\s*(?:import|export)\s+(?!type\b)[^;]*?["'][^"']*\/lab\//m.test(source)
-      || /^\s*import\s+["'][^"']*\/lab\//m.test(source);
+      || /^\s*import\s+["'][^"']*\/lab\//m.test(source)
+      // A protected file may lazily reach Lab through a handler it imports, but must not
+      // name Lab itself -- not even dynamically.
+      || /\bimport\s*\(\s*["'][^"']*\/lab\//.test(source);
     expect(direct).toBe(false);
   });
 
@@ -108,11 +121,11 @@ describe("core / Compatibility Lab boundary", () => {
  * in a protected file passed the original guard while loading Lab at runtime.
  */
 describe("boundary guard cannot be defeated", () => {
+  // Load-time edges: the graph walk must follow these.
   const attacks: Array<[string, string]> = [
     ["static import", 'import { labRoot } from "../lab/paths";'],
     ["side-effect import", 'import "../lab/paths";'],
     ["runtime re-export", 'export { labRoot } from "../lab/paths";'],
-    ["top-level dynamic import", 'void import("../lab/paths");'],
   ];
 
   test.each(attacks)("detects a %s", (_label, line) => {
@@ -127,6 +140,19 @@ describe("boundary guard cannot be defeated", () => {
     }
   });
 
+
+  // A dynamic import is a DEFERRED edge, so the graph walk deliberately does not follow it
+  // -- lazy loading is the remedy, not the defect. Guard 1 is what stops a protected file
+  // from naming Lab dynamically, so the coverage moves there rather than disappearing.
+  test("guard 1 forbids a direct dynamic Lab import in a protected file", () => {
+    const direct = (source: string) => /\bimport\s*\(\s*["'][^"']*\/lab\//.test(source);
+    expect(direct('void import("../lab/paths");')).toBe(true);
+    expect(direct('const m = await import("./management/lab-routes");')).toBe(false);
+    for (const file of PROTECTED) {
+      expect(direct(readFileSync(resolve(repoRoot, file), "utf8"))).toBe(false);
+    }
+  });
+
   // `import type` is erased at build time, so it must NOT be treated as a runtime edge.
   test("ignores type-only imports", () => {
     const probe = join(repoRoot, "src", "server", `__boundary_probe_type_${Math.random().toString(36).slice(2)}.ts`);