fix(handler): support the tunnel pattern — ws.url overrides advertisement, not binding

ws.url now controls only the advertised endpoint (a relay the browser
dials verbatim); the local binding still follows server/ws.port when
given, matching createDevServer's remote-origin scenario. Only when no
explicit binding accompanies ws.url does the handler start no transport.
Drops the now-meaningless conflict diagnostic (codes renumbered:
DF0052 = memoized handler replaced, DF0053 = connectionMeta before
ready).

Author: antfubot

docs/errors/DF0052.md

@@ -2,36 +2,32 @@
 outline: deep
 ---
 
-# DF0052: Conflicting WebSocket Bindings on createHandler
+# DF0052: Memoized Handler Replaced
 
 ## Message
 
-> createHandler("`{id}`") received \`ws.url\` alongside \`server\`/\`ws.port\` — the external URL wins and no local WebSocket transport is started.
+> createHandler("`{id}`") replaced the live handler memoized under key "`{key}`": its options changed since the previous call.
 
 ## Cause
 
-`createHandler` resolves its WebSocket tier in precedence order — `ws.url` (advertise an external endpoint verbatim) > `ws.port` (explicit side-car port) > `server` (shared upgrade on the host's HTTP server) > the eager auto side-car. Passing `ws.url` together with `server` or `ws.port` is contradictory: the external URL is advertised, and the other bindings are ignored — the handler starts no transport of its own in that tier.
+`createHandler` was called with a `key` that already maps to a live handler, but the option fingerprint differs from the memoized instance's. Dev servers that re-evaluate modules on the fly (Next.js, Nitro, SvelteKit HMR) re-run `createHandler` on every reload; the `key` memoization normally returns the live instance, but when the options genuinely changed the old instance — including its side-car WebSocket server — is closed and a fresh one starts.
 
 ## Example
 
 ```ts
 import { createHandler } from 'devframe/handler'
 
-// ✗ Bad — the server is never used for devframe's socket:
-const handler = createHandler(def, {
-  server: httpServer,
-  ws: { url: 'wss://relay.example.com/__ws' },
-})
+// First evaluation:
+createHandler(def, { key: 'devtools', ws: { port: 7811 } })
 
-// ✓ Good — pick exactly one binding:
-const shared = createHandler(def, { server: httpServer })
-const external = createHandler(def, { ws: { url: 'wss://relay.example.com/__ws' } })
+// A later reload with a different port replaces the live instance:
+createHandler(def, { key: 'devtools', ws: { port: 7812 } }) // ⚠ DF0052
 ```
 
 ## Fix
 
-Pass exactly one WebSocket binding: `ws.url` when a server you run yourself owns the RPC endpoint (wire the handler's `context` into it via `startHttpAndWs`), `ws.port` for an explicit side-car port, or `server` to share the host HTTP server's port. Drop the extras.
+This is informational when you edited the options on purpose — the replacement is the intended behavior. If it fires without an intentional change, make the options stable across reloads (module-level constants rather than values recomputed per evaluation), or give genuinely different handlers distinct keys.
 
 ## Source
 
-- [`packages/devframe/src/adapters/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `createHandler`'s WebSocket tier resolution warns this when `ws.url` shadows another binding.
+- [`packages/devframe/src/adapters/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `createHandler` warns this before closing and replacing a memoized instance whose options fingerprint changed.

docs/errors/DF0053.md

@@ -2,32 +2,32 @@
 outline: deep
 ---
 
-# DF0053: Memoized Handler Replaced
+# DF0053: connectionMeta() Before Handler Ready
 
 ## Message
 
-> createHandler("`{id}`") replaced the live handler memoized under key "`{key}`": its options changed since the previous call.
+> connectionMeta() was called before createHandler("`{id}`") finished initializing.
 
 ## Cause
 
-`createHandler` was called with a `key` that already maps to a live handler, but the option fingerprint differs from the memoized instance's. Dev servers that re-evaluate modules on the fly (Next.js, Nitro, SvelteKit HMR) re-run `createHandler` on every reload; the `key` memoization normally returns the live instance, but when the options genuinely changed the old instance — including its side-car WebSocket server — is closed and a fresh one starts.
+`createHandler` is a synchronous factory that kicks off asynchronous initialization eagerly — running `def.setup`, binding the WebSocket tier, and mounting the routes. `connectionMeta()` describes the WebSocket binding, which only exists once that initialization completes; calling it earlier has nothing correct to return.
 
 ## Example
 
 ```ts
 import { createHandler } from 'devframe/handler'
 
-// First evaluation:
-createHandler(def, { key: 'devtools', ws: { port: 7811 } })
+const handler = createHandler(def)
+handler.connectionMeta() // ✗ throws DF0053 — init is still in flight
 
-// A later reload with a different port replaces the live instance:
-createHandler(def, { key: 'devtools', ws: { port: 7812 } }) // ⚠ DF0053
+await handler.ready
+handler.connectionMeta() // ✓ { backend: 'websocket', websocket: { … } }
 ```
 
 ## Fix
 
-This is informational when you edited the options on purpose — the replacement is the intended behavior. If it fires without an intentional change, make the options stable across reloads (module-level constants rather than values recomputed per evaluation), or give genuinely different handlers distinct keys.
+Await `handler.ready` (or any `handler.fetch` call — it awaits readiness internally) before reading `connectionMeta()`.
 
 ## Source
 
-- [`packages/devframe/src/adapters/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `createHandler` warns this before closing and replacing a memoized instance whose options fingerprint changed.
+- [`packages/devframe/src/adapters/handler.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/handler.ts) — `createHandler`'s `connectionMeta()` throws this while initialization is still pending.

docs/errors/DF0054.md

@@ -42,9 +42,9 @@ function defineTestDef(id: string) {
 }
 
 describe('adapters/handler', () => {
-  it('connectionMeta() before ready throws DF0054', () => {
+  it('connectionMeta() before ready throws DF0053', () => {
     const handler = createHandler(defineTestDef('handler-early'), { auth: false })
-    expect(() => handler.connectionMeta()).toThrow(/DF0054|finished initializing/)
+    expect(() => handler.connectionMeta()).toThrow(/DF0053|finished initializing/)
     return handler.close()
   })
 
@@ -228,23 +228,33 @@ describe('adapters/handler', () => {
     }
   })
 
-  it('ws.url alongside server warns DF0052 and wins', async () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
-    const server = createServer(() => {})
-    const handler = createHandler(defineTestDef('handler-conflict'), {
+  it('tunnel pattern: ws.url with a server binds locally, advertises the relay', async () => {
+    const host = '127.0.0.1'
+    const port = await getPort({ port: 18170, host })
+    let handlerRef!: ReturnType<typeof createHandler>
+    const server = createServer((req, res) => {
+      handlerRef.nodeMiddleware(req, res)
+    })
+    handlerRef = createHandler(defineTestDef('handler-tunnel'), {
+      auth: false,
       server,
       ws: { url: 'wss://devtools.example.com/relay/__ws' },
     })
+    await new Promise<void>(resolve => server.listen(port, host, resolve))
 
     try {
-      await handler.ready
-      expect(handler.connectionMeta().websocket).toBe('wss://devtools.example.com/relay/__ws')
-      expect(String(warn.mock.calls)).toContain('DF0052')
+      await handlerRef.ready
+      // The browser is told to dial the relay…
+      expect(handlerRef.connectionMeta().websocket).toBe('wss://devtools.example.com/relay/__ws')
+      // …while the local socket keeps serving (the relay's forward target).
+      const client = connectWsClient(`ws://${host}:${port}/__handler-tunnel/__ws`)
+      await expect(client.$call('test:probe' as any)).resolves.toBe('ok')
+      client.$close()
     }
     finally {
-      warn.mockRestore()
-      await handler.close()
+      await handlerRef.close()
       server.close()
+      server.closeAllConnections()
     }
   })
 
@@ -285,7 +295,7 @@ describe('adapters/handler', () => {
       const c = createHandler(def, { auth: false, key: 'memo-test', host: '127.0.0.1', ws: { port: wsPort2 } })
       try {
         expect(c).not.toBe(a)
-        expect(String(warn.mock.calls)).toContain('DF0053')
+        expect(String(warn.mock.calls)).toContain('DF0052')
         await c.ready
         expect(c.connectionMeta()).toEqual({
           backend: 'websocket',

packages/devframe/src/adapters/__tests__/handler.test.ts

@@ -46,9 +46,12 @@ export interface CreateHandlerOptions {
   /**
    * Explicit control over how the browser reaches the RPC WebSocket —
    * advertised in `__connection.json`. Precedence `url` > `port` > `route`
-   * (see {@link DevframeWsOptions}); `url` advertises an external endpoint
-   * verbatim and the handler starts **no transport of its own** (run
-   * `startHttpAndWs({ context, server, path })` against
+   * (see {@link DevframeWsOptions}). `url` controls the *advertisement*
+   * only: the browser dials it verbatim (a tunnel/relay). The local
+   * binding still follows `server`/`ws.port` when given — the tunnel
+   * pattern, where the relay forwards to the locally-bound socket — and
+   * when neither is given, the handler starts **no transport of its own**
+   * (run `startHttpAndWs({ context, server, path })` against
    * {@link DevframeHandler.context} to serve RPC from your own server).
    */
   ws?: DevframeWsOptions
@@ -80,7 +83,7 @@ export interface CreateHandlerOptions {
    * `createHandler` on every reload — without a key each run would leak an
    * eager side-car WebSocket server. With a key, a re-run returns the live
    * instance; if the options changed, the old instance is closed and
-   * replaced (reported as `DF0053`).
+   * replaced (reported as `DF0052`).
    */
   key?: string
   /**
@@ -144,7 +147,7 @@ export interface DevframeHandler {
   context: Promise<DevframeNodeContext>
   /**
    * The `ConnectionMeta` this handler serves at `<base>__connection.json`.
-   * Only readable after initialization (`DF0054` otherwise).
+   * Only readable after initialization (`DF0053` otherwise).
    */
   connectionMeta: () => ConnectionMeta
   /** Tear down: WS transport/side-car, MCP sessions, memo-registry entry. */
@@ -217,7 +220,7 @@ export function createHandler(
     if (existing) {
       if (existing.hash === hash)
         return existing.handler
-      diagnostics.DF0053({ key: options.key, id: def.id })
+      diagnostics.DF0052({ key: options.key, id: def.id })
       void existing.handler.close().catch(() => {})
     }
     const handler = instantiateHandler(def, options)
@@ -302,9 +305,12 @@ function instantiateHandler(
       mcpDispose = mounted.dispose
     }
 
-    // WebSocket tier resolution — `url` > `port` > shared `server` > Bun
-    // fetch-upgrade > eager auto side-car. The advertised meta always
-    // matches the tier that actually serves RPC.
+    // WebSocket binding resolution — explicit `ws.port` side-car > shared
+    // `server` > Bun fetch-upgrade > eager auto side-car; `ws.url`, when
+    // set, overrides only the *advertised* endpoint (the tunnel pattern:
+    // the relay forwards to whatever local binding the rest configured),
+    // and suppresses the default binding entirely when no explicit
+    // `server`/`ws.port` is given (an external server owns the transport).
     const ws = options.ws ?? def.cli?.ws ?? {}
     const route = withoutLeadingSlash(ws.route ?? DEVFRAME_WS_ROUTE)
 
@@ -325,22 +331,13 @@ function instantiateHandler(
     }
 
     let websocketMeta: ConnectionMeta['websocket']
-    if (ws.url) {
-      // External endpoint — the server behind it owns transport and auth.
-      if (options.server || ws.port != null)
-        diagnostics.DF0052({ id: def.id })
-      authHandler = undefined
-      websocketMeta = ws.url
-    }
-    else if (ws.port != null || (!options.server && typeof (globalThis as any).Bun === 'undefined')) {
-      // Side-car: an explicit port, or the eager default when no host
-      // server is shared (and we're not under Bun).
+    if (ws.port != null) {
+      // Explicit side-car port.
       const sidecarHost = options.host ?? def.cli?.host ?? 'localhost'
-      const port = ws.port ?? await resolveDevServerPort(def, { host: sidecarHost })
       started = await startHttpAndWs({
         context: ctx,
         host: sidecarHost,
-        port,
+        port: ws.port,
         path: withLeadingSlash(route),
         auth: resolvedAuth,
         allowedOrigins: options.allowedOrigins,
@@ -360,6 +357,26 @@ function instantiateHandler(
       })
       websocketMeta = { path: route }
     }
+    else if (ws.url) {
+      // Advertise-only: an external server owns transport and auth.
+      authHandler = undefined
+      websocketMeta = ws.url
+    }
+    else if (typeof (globalThis as any).Bun === 'undefined') {
+      // Eager auto side-car on a free port — the default when no host
+      // server is shared (and we're not under Bun).
+      const sidecarHost = options.host ?? def.cli?.host ?? 'localhost'
+      const port = await resolveDevServerPort(def, { host: sidecarHost })
+      started = await startHttpAndWs({
+        context: ctx,
+        host: sidecarHost,
+        port,
+        path: withLeadingSlash(route),
+        auth: resolvedAuth,
+        allowedOrigins: options.allowedOrigins,
+      })
+      websocketMeta = { port: started.port, path: route }
+    }
     else {
       // Bun fetch-upgrade — same-origin upgrades completed through
       // `fetch(request, server)`, handlers exposed via `websocket`.
@@ -370,6 +387,10 @@ function instantiateHandler(
       bunUpgradePath = joinURL(base, route)
       websocketMeta = { path: route }
     }
+    // The tunnel pattern: `ws.url` overrides the advertisement while the
+    // local binding above keeps serving (the relay forwards to it).
+    if (ws.url)
+      websocketMeta = ws.url
 
     // Discovery meta before the SPA mount so its SPA-fallback can't swallow
     // the route; both sit at the SPA root for relative `./__connection.json`
@@ -471,7 +492,7 @@ function instantiateHandler(
     context: contextPromise,
     connectionMeta: () => {
       if (!meta)
-        throw diagnostics.DF0054({ id: def.id })
+        throw diagnostics.DF0053({ id: def.id })
       return meta
     },
     close: async () => {

packages/devframe/src/adapters/handler.ts

@@ -113,14 +113,10 @@ export const diagnostics = defineDiagnostics({
       fix: 'Restart the instance with the --mcp flag (or set `cli.mcp: true` on its definition) to expose its tools, then list instances again.',
     },
     DF0052: {
-      why: (p: { id: string }) => `createHandler("${p.id}") received \`ws.url\` alongside \`server\`/\`ws.port\` — the external URL wins and no local WebSocket transport is started.`,
-      fix: 'Pass exactly one WebSocket binding: `ws.url` (advertise an external endpoint you run yourself), `ws.port` (explicit side-car port), or `server` (share the host HTTP server). Drop the extras.',
-    },
-    DF0053: {
       why: (p: { key: string, id: string }) => `createHandler("${p.id}") replaced the live handler memoized under key "${p.key}": its options changed since the previous call.`,
       fix: 'A dev-time module reload re-ran createHandler with different options, so the old instance (and its side-car WebSocket server) was closed and a new one started. If this is unexpected, keep the options stable across reloads — or use distinct keys for genuinely different handlers.',
     },
-    DF0054: {
+    DF0053: {
       why: (p: { id: string }) => `connectionMeta() was called before createHandler("${p.id}") finished initializing.`,
       fix: 'Await `handler.ready` (or any `handler.fetch` call) before reading `connectionMeta()` — the WebSocket binding it describes is only known once initialization completes.',
     },