@aws-blocks/core 0.4.0 → 0.5.0

package/src/raw-route.test.ts

@@ -1,8 +1,14 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { describe, it, beforeEach } from 'node:test';
+import { describe, it, before, beforeEach } from 'node:test';
 import assert from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { buildSync } from 'esbuild';
 import {
   compilePath,
   registerRoute,
@@ -15,6 +21,7 @@ import {
   derivePathFromScope,
   resolveRoutePath,
 } from './raw-route.js';
+import type { RegisteredRoute } from './raw-route.js';
 import type { BlocksContext } from './api.js';
 
 const noop = async (_ctx: BlocksContext) => {};
@@ -817,3 +824,422 @@ describe('resolveRoutePath', () => {
     assert.strictEqual(path, '/v1/users');
   });
 });
+
+// ── Cross-copy registry sharing ─────────────────────────────────────────────
+//
+// A bundle can contain more than one physical copy of @aws-blocks/core (an
+// unlucky dependency tree, no dedupe). With module-local registry state, every
+// copy gets its own route table: Building Blocks register into theirs, the
+// dispatcher reads its own, and the routes 404 silently.
+//
+// These tests stand in for a second copy: they poke the shared state directly
+// through globalThis, exactly as a second copy of the module would see it.
+// The key is spelled out as a literal on purpose — it IS the cross-copy
+// contract, so changing it must break a test.
+
+const REGISTRY_KEY = '__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__';
+
+interface SharedRegistryState {
+  routes: RegisteredRoute[];
+  locked: boolean;
+  copies: number;
+}
+
+type GlobalWithRegistry = typeof globalThis & { [REGISTRY_KEY]?: SharedRegistryState };
+
+/** Read the registry state that a second core copy would share with us. */
+function sharedState(): SharedRegistryState {
+  const state = (globalThis as GlobalWithRegistry)[REGISTRY_KEY];
+  assert.ok(state, `route registry state must live on globalThis['${REGISTRY_KEY}']`);
+  return state;
+}
+
+describe('registry state is shared across core copies', () => {
+  it('matchRoute() resolves a route registered by another core copy', () => {
+    const { pattern, paramNames } = compilePath('/from-other-copy');
+    sharedState().routes.push({
+      method: 'GET',
+      path: '/from-other-copy',
+      pattern,
+      paramNames,
+      handler: noop,
+    });
+
+    const result = matchRoute('GET', '/from-other-copy');
+    assert.ok(result, 'route registered by another copy must be dispatchable');
+    assert.strictEqual(result.route.path, '/from-other-copy');
+  });
+
+  it('getRegisteredRoutes() reports routes registered by another core copy', () => {
+    const { pattern, paramNames } = compilePath('/synth-visible');
+    sharedState().routes.push({
+      method: 'GET',
+      path: '/synth-visible',
+      pattern,
+      paramNames,
+      handler: noop,
+    });
+
+    // Synth-time consumers (CloudFront behaviors in hosting.ts) iterate this.
+    assert.ok(getRegisteredRoutes().some((r) => r.path === '/synth-visible'));
+  });
+
+  it('registerRoute() publishes the route into the shared state', () => {
+    registerRoute({ method: 'POST', path: '/published', handler: noop });
+
+    assert.ok(
+      sharedState().routes.some((r) => r.method === 'POST' && r.path === '/published'),
+      'another copy must be able to see routes we registered',
+    );
+  });
+
+  it('registerRoute() honours a lock set by another core copy', () => {
+    sharedState().locked = true;
+
+    assert.throws(
+      () => registerRoute({ method: 'GET', path: '/after-foreign-lock', handler: noop }),
+      (err: Error) => {
+        assert.ok(err.message.includes('Cannot register routes after handler creation'));
+        return true;
+      },
+    );
+  });
+
+  it('lockRouteRegistry() locks the shared state, not a module-local flag', () => {
+    lockRouteRegistry();
+    assert.strictEqual(sharedState().locked, true);
+  });
+
+  it('clearRouteRegistry() clears the shared state and releases the shared lock', () => {
+    registerRoute({ method: 'GET', path: '/leftover', handler: noop });
+    lockRouteRegistry();
+
+    clearRouteRegistry();
+
+    assert.deepStrictEqual(sharedState().routes, []);
+    assert.strictEqual(sharedState().locked, false);
+  });
+
+  it('clearRouteRegistry() does not reset the copy counter', () => {
+    const before = sharedState().copies;
+    clearRouteRegistry();
+    assert.strictEqual(sharedState().copies, before, 'copies counts module loads, not routes');
+  });
+
+  // Behavior change, deliberately kept: with a shared registry, duplicate
+  // detection reaches across copies for the first time. An app with two core
+  // copies AND two instances of the same Building Block used to split the
+  // routes silently (half of them 404ing); it now fails loudly at startup.
+  // The app was already broken — this only makes it say so.
+  it('rejects a duplicate of a route another core copy registered', () => {
+    const { pattern, paramNames } = compilePath('/shared-path');
+    sharedState().routes.push({
+      method: 'GET',
+      path: '/shared-path',
+      pattern,
+      paramNames,
+      handler: noop,
+    });
+
+    assert.throws(
+      () => registerRoute({ method: 'GET', path: '/shared-path', handler: noop }),
+      (err: Error) => {
+        assert.strictEqual(err.name, RawRouteErrors.DuplicateRoute);
+        return true;
+      },
+    );
+  });
+});
+
+describe('duplicate core copies are announced', () => {
+  /**
+   * Use raw-route.js in a fresh process, optionally pre-seeding the shared
+   * state as an earlier copy would have left it, and return stderr.
+   *
+   * The copy must be *used*, not merely imported: the counter increments on
+   * first registry access, so a copy that never touches the registry is never
+   * counted — deliberately, since only routing copies matter here.
+   */
+  function useInFreshProcess(preSeededCopies: number | null): string {
+    const moduleUrl = new URL('./raw-route.js', import.meta.url).href;
+    const seed =
+      preSeededCopies === null
+        ? ''
+        : `globalThis[${JSON.stringify(REGISTRY_KEY)}] = { routes: [], locked: false, copies: ${preSeededCopies} };`;
+    const script = `${seed}const m = await import(${JSON.stringify(moduleUrl)}); m.registerRoute({ method: 'GET', path: '/probe', handler: async () => {} });`;
+    const result = spawnSync(process.execPath, ['--input-type=module', '-e', script], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, `using raw-route.js failed: ${result.stderr}`);
+    return result.stderr;
+  }
+
+  it('warns when a second copy of @aws-blocks/core joins the shared registry', () => {
+    const stderr = useInFreshProcess(1);
+    assert.match(stderr, /2 copies of @aws-blocks\/core/);
+  });
+
+  it('stays silent for a healthy single-copy install', () => {
+    const stderr = useInFreshProcess(null);
+    assert.doesNotMatch(stderr, /copies of @aws-blocks\/core/);
+  });
+
+  it('warns once per copy, not once per registry access', () => {
+    const moduleUrl = new URL('./raw-route.js', import.meta.url).href;
+    const script = `globalThis[${JSON.stringify(REGISTRY_KEY)}] = { routes: [], locked: false, copies: 1 };
+      const m = await import(${JSON.stringify(moduleUrl)});
+      m.registerRoute({ method: 'GET', path: '/a', handler: async () => {} });
+      m.registerRoute({ method: 'GET', path: '/b', handler: async () => {} });
+      m.matchRoute('GET', '/a');`;
+    const result = spawnSync(process.execPath, ['--input-type=module', '-e', script], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, result.stderr);
+
+    const warnings = result.stderr.split('\n').filter((line) => line.includes('copies of @aws-blocks/core'));
+    assert.strictEqual(warnings.length, 1, `expected exactly one warning, got: ${JSON.stringify(warnings)}`);
+  });
+});
+
+// ── A peer copy's state is adopted, not trusted ─────────────────────────────
+//
+// The registry key is a permanent contract: copies sharing a process are
+// usually different *versions* of @aws-blocks/core, so the shape may only grow
+// — a copy that renamed the key would re-split the registry silently, each key
+// holding its own copy counter. The other half of that contract is this side:
+// a copy must cope with a state a peer left without the fields it expects.
+describe('registry state from a peer copy is adopted, not trusted', () => {
+  /**
+   * Import raw-route.js in a fresh process on top of a pre-seeded shared state
+   * and report what the copy made of it.
+   *
+   * `seed` stands in for a copy whose registry shape differs from this one's.
+   * Fields are omitted, never renamed — that is exactly the evolution the key's
+   * contract permits.
+   */
+  function useOnTopOf(seed: string): { matched: boolean; copies: number | null } {
+    const moduleUrl = new URL('./raw-route.js', import.meta.url).href;
+    const script = `globalThis[${JSON.stringify(REGISTRY_KEY)}] = ${seed};
+      const m = await import(${JSON.stringify(moduleUrl)});
+      m.registerRoute({ method: 'GET', path: '/probe', handler: async () => {} });
+      console.log(JSON.stringify({
+        matched: m.matchRoute('GET', '/probe') !== null,
+        copies: m.getLoadedCoreCopies(),
+      }));`;
+    const result = spawnSync(process.execPath, ['--input-type=module', '-e', script], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, `using raw-route.js failed: ${result.stderr}`);
+    // NaN serializes to null — which is the point of reporting it this way.
+    return JSON.parse(result.stdout.trim());
+  }
+
+  it('registers into a state that arrived without a route table', () => {
+    const { matched } = useOnTopOf('{ locked: false, copies: 1 }');
+    assert.strictEqual(matched, true, 'a missing route table must be created, not thrown on');
+  });
+
+  it('keeps the copy count a number when the state arrived without one', () => {
+    const { copies } = useOnTopOf('{ routes: [], locked: false }');
+    assert.strictEqual(copies, 1, 'a missing counter must restart at a number — NaN would mute the warning');
+  });
+});
+
+// ── A real duplicate install: two physical copies of the package ────────────
+//
+// Everything above stands in for a second core copy by writing to globalThis
+// directly. That pins the contract, but it cannot tell a working fix apart
+// from one that only appears to work because both "copies" were the same
+// module instance all along — which is precisely the mistake that produced the
+// original defect. This block loads two genuinely separate copies (two
+// directory trees, two module instances, the shape a bundler emits from a
+// nested `node_modules/@aws-blocks/core`) and replays the production sequence:
+// a Building Block registers its route through one copy, the dispatcher looks
+// it up through the other.
+//
+// Against the pre-fix implementation this returns no match and an empty route
+// table — the silent 404 reported in aws-blocks#355.
+
+interface TwoCopyProbe {
+  /** Whether the two imports really produced separate module instances. */
+  distinctInstances: boolean;
+  /** Path the dispatcher copy resolved, or null when nothing matched. */
+  matchedPath: string | null;
+  /** Size of the route table the dispatcher copy consulted. */
+  routesSeenByDispatcher: number;
+  /** Copy count the dispatcher copy reports, or null if it cannot report one. */
+  copiesReported: number | null;
+  /** Everything the probe wrote to stderr (carries the duplicate warning). */
+  stderr: string;
+  /** The bundled source, when the probe was bundled first; otherwise null. */
+  bundleText: string | null;
+}
+
+/**
+ * The probe itself: a Building Block registers its route through one copy of
+ * the package, the dispatcher looks it up through the other.
+ *
+ * Kept as a standalone ES module with static imports so the very same source
+ * can be run as-is and, in the test below, sent through a bundler first.
+ */
+const TWO_COPY_ENTRY = `
+import * as a from './copy-a/dist/raw-route.js';
+import * as b from './copy-b/dist/raw-route.js';
+
+a.registerRoute({ method: 'GET', path: '/aws-blocks/auth/signin/google', handler: async () => {} });
+const matched = b.matchRoute('GET', '/aws-blocks/auth/signin/google');
+
+const observed = {
+  distinctInstances: a !== b,
+  matchedPath: matched ? matched.route.path : null,
+  routesSeenByDispatcher: b.getRegisteredRoutes().length,
+  copiesReported: null,
+};
+// Report the routing facts even if the diagnostics helper is missing or
+// throws — whether the route resolves is what this probe is about, and a
+// build that lost the helper must not hide that behind a crashed child.
+try {
+  observed.copiesReported = b.getLoadedCoreCopies();
+} catch {}
+console.log(JSON.stringify(observed));
+`;
+
+/**
+ * Install two physical copies of this package and route a request across them.
+ *
+ * Runs in a child process so the copies start from a clean `globalThis` and
+ * cannot leak registry state into this test run. The whole directory is copied
+ * rather than the two files currently needed, so the probe keeps working when
+ * `raw-route.js` grows an import.
+ *
+ * With `bundle`, the probe is first bundled the way a deployed handler is —
+ * `NodejsFunction` runs esbuild with `--conditions=aws-runtime` — before it is
+ * executed.
+ */
+function runTwoCopyProbe({ bundle }: { bundle: boolean }): TwoCopyProbe {
+  const distDir = dirname(fileURLToPath(import.meta.url));
+  const packageDir = dirname(distDir);
+  const root = mkdtempSync(join(tmpdir(), 'aws-blocks-two-copies-'));
+  try {
+    // Copy A belongs to the Building Block, copy B to the dispatcher. Each is
+    // laid out as an installed package — `package.json` beside `dist/`, the
+    // shape npm produces for a nested `node_modules/@aws-blocks/core`. The
+    // manifest has to come along: a real install has one, and it is what a
+    // bundler reads for `type` and `sideEffects` — without it the bundle here
+    // would be built under different rules than the deployed one.
+    for (const copy of ['copy-a', 'copy-b']) {
+      cpSync(distDir, join(root, copy, 'dist'), { recursive: true });
+      cpSync(join(packageDir, 'package.json'), join(root, copy, 'package.json'));
+    }
+
+    const entry = join(root, 'entry.mjs');
+    writeFileSync(entry, TWO_COPY_ENTRY);
+
+    let script = entry;
+    let bundleText: string | null = null;
+    if (bundle) {
+      const outfile = join(root, 'bundle.mjs');
+      buildSync({
+        entryPoints: [entry],
+        outfile,
+        bundle: true,
+        format: 'esm',
+        platform: 'node',
+        conditions: ['aws-runtime'],
+        minify: true,
+        logLevel: 'silent',
+      });
+      bundleText = readFileSync(outfile, 'utf8');
+      script = outfile;
+    }
+
+    const result = spawnSync(process.execPath, [script], { encoding: 'utf8' });
+    assert.strictEqual(result.status, 0, `two-copy probe failed: ${result.stderr}`);
+    return {
+      ...(JSON.parse(result.stdout) as Omit<TwoCopyProbe, 'stderr' | 'bundleText'>),
+      stderr: result.stderr,
+      bundleText,
+    };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+describe('two physical core copies share one registry', () => {
+  let probe: TwoCopyProbe;
+
+  before(() => {
+    probe = runTwoCopyProbe({ bundle: false });
+  });
+
+  it('loads two separate module instances', () => {
+    // Guards the probe itself: if this ever collapses to one instance, the
+    // tests below would pass without exercising anything.
+    assert.strictEqual(probe.distinctInstances, true);
+  });
+
+  it('dispatches a route the other copy registered', () => {
+    assert.strictEqual(
+      probe.matchedPath,
+      '/aws-blocks/auth/signin/google',
+      'the dispatcher copy must resolve a route registered through the other copy',
+    );
+  });
+
+  it('shows the route in the table the dispatcher consults', () => {
+    // A zero here is the fingerprint of the original defect: registration
+    // succeeded, and the dispatcher looked at an empty table.
+    assert.strictEqual(probe.routesSeenByDispatcher, 1);
+  });
+
+  it('counts and announces both copies', () => {
+    assert.strictEqual(probe.copiesReported, 2);
+    assert.match(probe.stderr, /2 copies of @aws-blocks\/core/);
+  });
+});
+
+// ── The same thing, but bundled ─────────────────────────────────────────────
+//
+// Duplicate copies are a bundling phenomenon: the reported defect was found in
+// a deployed bundle, not in a node_modules tree at rest. A deployed handler is
+// built by `NodejsFunction`, which runs esbuild with `--conditions=aws-runtime`
+// (see cdk/blocks-backend.ts), so this repeats that step and then runs the
+// result. Minified on purpose — it is the harsher case, and passing it implies
+// the unminified one.
+//
+// What this pins down that the unbundled probe cannot:
+//
+//   - that a bundler keeps two copies of the same file at different paths
+//     rather than collapsing them, i.e. that the failure mode reaches the
+//     deployed artifact at all;
+//   - that reaching the registry through `globalThis[<string key>]` survives
+//     minification, so the two copies still meet;
+//   - that the key stays a greppable literal, which is the documented way to
+//     diagnose a duplicate install in a deployed bundle (and the reason it is
+//     a plain string rather than a `Symbol.for()` key).
+//
+// What it deliberately does *not* claim: that counting copies on first use
+// rather than at module load is required to survive tree-shaking. That was
+// measured — with `sideEffects` honoured and `--minify` on, esbuild retains a
+// top-level counter here, because a module whose exports are used is kept
+// whole. Counting on first use stands on its other stated reason: it counts the
+// copies that take part in routing, not the ones merely imported.
+
+describe('the shared registry survives bundling', () => {
+  let probe: TwoCopyProbe;
+
+  before(() => {
+    probe = runTwoCopyProbe({ bundle: true });
+  });
+
+  it('keeps two participating copies in one bundle', () => {
+    // Also guards the test: were the two copies collapsed into one module
+    // scope, the assertions below would pass without ever crossing a copy
+    // boundary — and there would be no defect left to protect against.
+    assert.strictEqual(probe.copiesReported, 2, 'the bundle must still contain two participating copies');
+    assert.strictEqual(probe.distinctInstances, true);
+  });
+
+  it('dispatches a route the other copy registered', () => {
+    assert.strictEqual(probe.matchedPath, '/aws-blocks/auth/signin/google');
+    assert.strictEqual(probe.routesSeenByDispatcher, 1);
+  });
+
+  it('keeps the registry key greppable in the bundle', () => {
+    assert.ok(probe.bundleText?.includes('__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__'));
+  });
+});

package/src/raw-route.ts

@@ -105,19 +105,126 @@ export interface RegisteredRoute {
   handler: (context: BlocksContext) => Promise<void>;
 }
 
-const routeRegistry: RegisteredRoute[] = [];
-let registrationLocked = false;
+/**
+ * Registry state shared by every copy of `@aws-blocks/core` in the process.
+ *
+ * A bundle can end up carrying more than one physical copy of this package
+ * (an unlucky dependency tree, no dedupe). With module-local state each copy
+ * would keep its own route table: Building Blocks register into theirs, the
+ * dispatcher reads its own, and every route registered through the "wrong"
+ * copy answers 404 without a log line. The synth path has the same split —
+ * `hosting.ts` builds CloudFront behaviors from `getRegisteredRoutes()`.
+ *
+ * `locked` travels with `routes` on purpose: splitting them would let one copy
+ * lock the shared table while another is still registering, trading a silent
+ * loss for a spurious throw.
+ */
+interface RawRouteRegistryState {
+  routes: RegisteredRoute[];
+  locked: boolean;
+  /** Number of core copies that have joined this registry (1 = healthy). */
+  copies: number;
+}
+
+/**
+ * Well-known `globalThis` key holding the shared registry state.
+ *
+ * A plain string rather than a `Symbol.for()` key, deliberately: duplicate
+ * copies are diagnosed by counting strings in the deployed bundle, and a
+ * symbol would be invisible to that. It also matches the existing
+ * `__BLOCKS_LAMBDA_EVENT_HANDLERS__` precedent.
+ *
+ * **The key is a permanent contract — do not bump it.** `_V1_` names the shape
+ * this file introduced; it is not a license to mint `_V2_`. The copies that
+ * share a process are usually *different versions* of `@aws-blocks/core` — that
+ * is how a tree ends up with duplicates in the first place — so a copy reading
+ * a different key does not get a private namespace, it re-splits the registry:
+ * routes registered through one key, dispatched through the other, 404. And
+ * silently, because each key carries its own `copies` counter, so both sides
+ * report `copies: 1` and the duplicate warning never fires. That is the bug
+ * this module exists to fix, reintroduced with its own diagnostic switched off.
+ *
+ * Evolve the shape **additively** instead: add optional fields, and tolerate
+ * fields a peer copy did not write (`getState()` does). If a `_V2_` key ever
+ * proves unavoidable, it has to adopt the V1 state — read it, and keep writing
+ * it — so that a mixed tree still routes through one table.
+ */
+const REGISTRY_KEY = '__AWS_BLOCKS_RAW_ROUTE_REGISTRY_V1__';
+
+type GlobalWithRegistry = typeof globalThis & { [REGISTRY_KEY]?: RawRouteRegistryState };
+
+/** Whether *this* module copy has already counted itself. Intentionally module-local. */
+let thisCopyCounted = false;
+
+/**
+ * Resolve the shared registry state, creating it on first access.
+ *
+ * The copy count is incremented here rather than at module load so that it
+ * counts the copies actually taking part in routing, not every copy a bundle
+ * happens to carry. Bundled code is where duplicate copies occur, and a copy
+ * that is imported but never routes is not what the diagnostic is about.
+ *
+ * Tree-shaking is not the reason. `sideEffects` in package.json lets a bundler
+ * drop this module whole when nothing it exports is used, but a module that
+ * *is* used keeps its top-level statements — measured with esbuild under
+ * `--bundle --minify`, and covered by the bundling test in `raw-route.test.ts`.
+ */
+function getState(): RawRouteRegistryState {
+  const g = globalThis as GlobalWithRegistry;
+  let state = g[REGISTRY_KEY];
+  if (!state) {
+    state = { routes: [], locked: false, copies: 0 };
+    g[REGISTRY_KEY] = state;
+  }
+
+  // The state may have been left by a copy that evolved the shape (see the
+  // contract on REGISTRY_KEY), so fill in what this copy needs rather than
+  // assume it is there. A missing `routes` would throw on the first
+  // registration, and a missing `copies` would go NaN on the increment below —
+  // silencing the duplicate warning, which is the failure this module exists to
+  // report. `locked` needs no default: absent reads as unlocked, which is what
+  // a registry still accepting registrations means.
+  if (!Array.isArray(state.routes)) state.routes = [];
+  if (typeof state.copies !== 'number') state.copies = 0;
+
+  if (!thisCopyCounted) {
+    thisCopyCounted = true;
+    state.copies += 1;
+    if (state.copies > 1) {
+      console.warn(
+        `AWS Blocks: ${state.copies} copies of @aws-blocks/core loaded in this process. ` +
+          'They now share one RawRoute registry, but duplicate copies indicate a ' +
+          'dependency-tree problem — deduplicate @aws-blocks/core.',
+      );
+    }
+  }
+
+  return state;
+}
+
+/**
+ * Number of `@aws-blocks/core` copies taking part in the shared route registry.
+ *
+ * `1` for a healthy install. A higher number means the dependency tree carries
+ * duplicates — routes still work (the registry is shared), but it is worth
+ * reporting in diagnostics.
+ *
+ * **Internal.** Not re-exported from the package entry point.
+ */
+export function getLoadedCoreCopies(): number {
+  return getState().copies;
+}
 
 const VALID_METHODS = new Set<string>(['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'HEAD', 'OPTIONS']);
 
 /** Prevent further route registration. Call after initialization is complete. */
 export function lockRouteRegistry(): void {
-  registrationLocked = true;
+  getState().locked = true;
 }
 
 /** Re-allow route registration (useful in tests after lock). */
 export function unlockRouteRegistry(): void {
-  registrationLocked = false;
+  getState().locked = false;
 }
 
 /**
@@ -132,7 +239,8 @@ export function unlockRouteRegistry(): void {
  * @throws {RawRouteErrors.DuplicateRoute} If the same method+path is registered twice.
  */
 export function registerRoute(options: RawRouteOptions & { path: string }): void {
-  if (registrationLocked) {
+  const state = getState();
+  if (state.locked) {
     throw new Error('Routes must be registered during initialization. Cannot register routes after handler creation.');
   }
 
@@ -150,7 +258,7 @@ export function registerRoute(options: RawRouteOptions & { path: string }): void
     throw new Error(`Cannot register RawRoute at ${BLOCKS_NAMESPACE} or ${BLOCKS_RPC_PREFIX}/* — these paths are reserved for RPC dispatch`);
   }
 
-  const existing = routeRegistry.find(
+  const existing = state.routes.find(
     (r) => r.method === options.method && r.path === normalizedPath,
   );
   if (existing) {
@@ -163,7 +271,7 @@ export function registerRoute(options: RawRouteOptions & { path: string }): void
 
   const { pattern, paramNames } = compilePath(normalizedPath);
 
-  routeRegistry.push({
+  state.routes.push({
     method: options.method,
     path: normalizedPath,
     pattern,
@@ -174,13 +282,18 @@ export function registerRoute(options: RawRouteOptions & { path: string }): void
 
 /** Return a read-only snapshot of all registered routes. */
 export function getRegisteredRoutes(): readonly RegisteredRoute[] {
-  return routeRegistry;
+  return getState().routes;
 }
 
-/** Remove all registered routes and unlock registration (used by tests). */
+/**
+ * Remove all registered routes and unlock registration (used by tests).
+ *
+ * Leaves the copy counter alone — it tracks module copies, not routes.
+ */
 export function clearRouteRegistry(): void {
-  routeRegistry.length = 0;
-  registrationLocked = false;
+  const state = getState();
+  state.routes.length = 0;
+  state.locked = false;
 }
 
 /**
@@ -195,7 +308,7 @@ export function matchRoute(
   // Normalize incoming path: collapse double slashes
   path = path.replace(/\/+/g, '/');
 
-  for (const route of routeRegistry) {
+  for (const route of getState().routes) {
     if (route.method !== method) continue;
     const match = route.pattern.exec(path);
     if (match) {

package/src/scripts/dev-server.ts

@@ -6,7 +6,8 @@ import { pathToFileURL, URL } from 'node:url';
 import { resolve, dirname, join } from 'node:path';
 import { writeFileSync, mkdirSync, readFileSync, unlinkSync, renameSync } from 'node:fs';
 import { spawn, type ChildProcess } from 'node:child_process';
-import { createConnection } from 'node:net';
+import { createConnection, type Socket } from 'node:net';
+import type { Duplex } from 'node:stream';
 import httpProxy from 'http-proxy';
 import { writeClientCode } from './generate-client.js';
 import { ApiError } from '../errors.js';
@@ -952,6 +953,10 @@ export async function startDevServer(options: DevServerOptions) {
 
   // WebSocket upgrade — route to frontend (HMR) or dev attachments
   server.on('upgrade', (req, socket, head) => {
+    // A stale client can reset the connection mid-upgrade (ECONNRESET). The raw
+    // socket has no 'error' listener at this point, so Node's default handler
+    // would kill the dev server. Attach one before any parsing/routing.
+    socket.on('error', () => socket.destroy());
     const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
     if (url.pathname === '/realtime') return; // handled by dev attachment (noServer mode)
     if (frontendProxy) {
@@ -1043,6 +1048,12 @@ export async function startDevServer(options: DevServerOptions) {
     onExhausted: () => process.exit(1),
     warn: (msg) => console.error(msg),
   });
+  // Malformed/aborted requests must not become unhandled socket errors.
+  server.on('clientError', (_err: Error, socket: Duplex) => {
+    if ((socket as Socket).writable) socket.end('HTTP/1.1 400 Bad Request\r\n\r\n');
+    else socket.destroy();
+  });
+
   server.on('error', (err: NodeJS.ErrnoException) => {
     if (err.code === 'EADDRINUSE') {
       // Keep the telemetry signal (unchanged) …