feat(client): add DevframeRpcClient.close()

`DevframeRpcClient` has no `close()`/`dispose()` of any kind — a connection
lives until the process ends, with no way for a caller to tear it down. The
server transport already has the symmetric piece: `WsRpcTransport.close()`
(attachWsRpcTransport) detaches upgrade routing, force-closes every connected
peer, and closes any server it created itself. The client side has never had
an equivalent.

This bites any caller that races a connection attempt against its own
deadline (`Promise.race([connectDevframe(...), timeout])`) — the deadline
can't cancel the loser, so a slow-to-resolve attempt becomes a fully
connected, unreferenced client with nothing able to close it.

## Changes

- `createWsRpcChannel` (rpc/transports/ws-client.ts) returns `close()`,
  closing the underlying `WebSocket`. Widens its return type to
  `ChannelOptions & { close: () => void }`, since birpc's own `ChannelOptions`
  has no teardown of its own.
- `createWsRpcClientMode` hoists its channel to a local so it can close it,
  and exposes `close()` on `DevframeRpcClientMode`.
- `createStaticRpcClientMode` gets a no-op `close()` — a static backend has
  no live socket, every call is a local fetch — so the two modes stay
  union-compatible.
- `DevframeRpcClient.close()` delegates to the mode. No behavior change for
  anyone not calling it.

## Tests

- `ws-client.test.ts` (new): `close()` closes the underlying `WebSocket`.
- `rpc-ws-status.test.ts`: `createWsRpcClientMode`'s `close()` closes its
  socket.
- `rpc.test.ts`: `getDevframeRpcClient`'s `close()` closes the socket on a
  `websocket` backend, and is a no-op (not a throw) on a `static` one.
- `rpc-auth-gate.test.ts`: updated its hand-typed `DevframeRpcClientMode` mock
  for the new required field.

`pnpm --filter devframe exec tsc --noEmit` clean. `pnpm exec vitest run
--project devframe` — 51 files, 463 tests (was 459), all green. Also ran
`--project @devframes/hub --project @devframes/hub-ui` (129 tests) and
`tsc --noEmit` across `@devframes/hub`, `@devframes/hub-ui`, `@devframes/nuxt`
— the packages consuming `DevframeRpcClient` — clean. `eslint` clean on every
touched file.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: dvcolomban

packages/devframe/src/client/rpc-auth-gate.test.ts

@@ -37,6 +37,7 @@ vi.mock('./rpc-ws', () => ({
     call: fakeMode.call as DevframeRpcClientMode['call'],
     callOptional: fakeMode.callOptional as DevframeRpcClientMode['callOptional'],
     callEvent: fakeMode.callEvent as DevframeRpcClientMode['callEvent'],
+    close: () => {},
   })),
 }))
 

packages/devframe/src/client/rpc-static.ts

@@ -35,5 +35,7 @@ export async function createStaticRpcClientMode(
       args[0] as string,
       args.slice(1),
     ),
+    // No live socket to close — every call is a local fetch.
+    close: () => {},
   }
 }

packages/devframe/src/client/rpc-ws-status.test.ts

@@ -148,4 +148,13 @@ describe('ws client connection status', () => {
     expect(rpcErrors[0].error).toBeInstanceOf(DevframeConnectionError)
     expect(rpcErrors[0].method).toBe('demo:method')
   })
+
+  it('close() closes the underlying socket', () => {
+    const { mode, ws } = setup()
+    const closeSpy = vi.spyOn(ws, 'close')
+
+    mode.close()
+
+    expect(closeSpy).toHaveBeenCalledTimes(1)
+  })
 })

packages/devframe/src/client/rpc-ws.ts

@@ -206,34 +206,37 @@ export function createWsRpcClientMode(
   for (const name of connectionMeta.jsonSerializableMethods ?? [])
     definitions.set(name, { jsonSerializable: true })
 
+  // Hoisted out of the `createRpcClient` call so `close()` below can reach it — birpc's own
+  // `ChannelOptions` carries no reference back to what it was built from.
+  const channel = createWsRpcChannel({
+    url,
+    authToken,
+    definitions,
+    ...wsOptions,
+    onConnected(event) {
+      // Socket open — the trust handshake (already queued) settles the
+      // status to `connected`/`unauthorized`. Stay `connecting` until then.
+      wsOptions.onConnected?.(event)
+    },
+    onError(error) {
+      setStatus('error', error)
+      events.emit('connection:error', error)
+      rejectAllPending(new DevframeConnectionError('connection', '[devframe] Connection to the devframe server failed', { cause: error }))
+      wsOptions.onError?.(error)
+    },
+    onDisconnected(event) {
+      // A clean close after we were connected, or a socket that never
+      // opened — either way calls can no longer be served.
+      if (status !== 'error')
+        setStatus('disconnected')
+      rejectAllPending(new DevframeConnectionError('connection', '[devframe] Disconnected from the devframe server', { cause: connectionError ?? undefined }))
+      wsOptions.onDisconnected?.(event)
+    },
+  })
   const serverRpc = createRpcClient<DevframeRpcServerFunctions, DevframeRpcClientFunctions>(
     clientRpc.functions,
     {
-      channel: createWsRpcChannel({
-        url,
-        authToken,
-        definitions,
-        ...wsOptions,
-        onConnected(event) {
-          // Socket open — the trust handshake (already queued) settles the
-          // status to `connected`/`unauthorized`. Stay `connecting` until then.
-          wsOptions.onConnected?.(event)
-        },
-        onError(error) {
-          setStatus('error', error)
-          events.emit('connection:error', error)
-          rejectAllPending(new DevframeConnectionError('connection', '[devframe] Connection to the devframe server failed', { cause: error }))
-          wsOptions.onError?.(error)
-        },
-        onDisconnected(event) {
-          // A clean close after we were connected, or a socket that never
-          // opened — either way calls can no longer be served.
-          if (status !== 'error')
-            setStatus('disconnected')
-          rejectAllPending(new DevframeConnectionError('connection', '[devframe] Disconnected from the devframe server', { cause: connectionError ?? undefined }))
-          wsOptions.onDisconnected?.(event)
-        },
-      }),
+      channel,
       rpcOptions,
     },
   )
@@ -402,5 +405,8 @@ export function createWsRpcClientMode(
         method,
       )
     },
+    close: () => {
+      channel.close()
+    },
   }
 }

packages/devframe/src/client/rpc.test.ts

@@ -159,4 +159,39 @@ describe('getDevframeRpcClient — connection meta base', () => {
     // An explicit meta resolves against the client's own base.
     expect(lastWsUrl()).toBe('ws://localhost:5173/__foo/__ws')
   })
+
+  it('close() closes the underlying socket', async () => {
+    const served: ConnectionMeta = { backend: 'websocket', websocket: { path: '__ws' } }
+    vi.stubGlobal('fetch', vi.fn(async () => ({
+      ok: true,
+      status: 200,
+      json: async () => served,
+    }) as any))
+
+    const rpc = await getDevframeRpcClient({ baseURL: '/__foo/', otpParam: false })
+    const ws = FakeWebSocket.instances.at(-1)!
+    const closeSpy = vi.spyOn(ws, 'close')
+
+    rpc.close()
+
+    expect(closeSpy).toHaveBeenCalledTimes(1)
+  })
+
+  it('close() on a static backend is a no-op, not a throw', async () => {
+    vi.stubGlobal('fetch', vi.fn(async (url: string) => ({
+      ok: true,
+      status: 200,
+      json: async () => (
+        url.includes('__rpc-dump')
+          ? {} // an empty manifest is a valid (if trivial) StaticRpcManifest
+          : { backend: 'static' } satisfies ConnectionMeta
+      ),
+    }) as any))
+
+    const rpc = await getDevframeRpcClient({ baseURL: '/__foo/', otpParam: false })
+
+    expect(() => rpc.close()).not.toThrow()
+    // Static backends never open a socket in the first place.
+    expect(FakeWebSocket.instances).toHaveLength(0)
+  })
 })

packages/devframe/src/client/rpc.ts

@@ -195,6 +195,16 @@ export interface DevframeRpcClient {
     <NS extends string>(namespace: NS): DevframeScopedClientContext<NS, SettingsForNamespace<NS>>
     (namespace?: null | ''): DevframeRpcClient
   }
+
+  /**
+   * Close the connection. A `static` backend is a no-op (there is no live socket to close);
+   * a `websocket` backend closes the underlying `WebSocket`, which the server observes as a
+   * normal disconnect. Mirrors {@link WsRpcTransport.close} on the server side.
+   *
+   * There is no corresponding "reconnect" — a closed client is done. Discard it and call
+   * {@link getDevframeRpcClient} again to reconnect.
+   */
+  close: () => void
 }
 
 export interface DevframeRpcClientMode {
@@ -212,6 +222,8 @@ export interface DevframeRpcClientMode {
   call: DevframeRpcClient['call']
   callEvent: DevframeRpcClient['callEvent']
   callOptional: DevframeRpcClient['callOptional']
+  /** See {@link DevframeRpcClient.close}. */
+  close: () => void
 }
 
 export async function getDevframeRpcClient(
@@ -375,6 +387,7 @@ export async function getDevframeRpcClient(
     streaming: undefined!,
     cacheManager,
     scope: undefined!,
+    close: () => mode.close(),
   }
 
   rpc.sharedState = createRpcSharedStateClientHost(rpc)

packages/devframe/src/rpc/transports/ws-client.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createWsRpcChannel } from './ws-client'
+
+// A minimal fake WebSocket — only what `createWsRpcChannel` touches.
+class FakeWebSocket {
+  static OPEN = 1
+  static instances: FakeWebSocket[] = []
+
+  readyState = FakeWebSocket.OPEN
+
+  constructor(public url: string) {
+    FakeWebSocket.instances.push(this)
+  }
+
+  addEventListener(): void {}
+  removeEventListener(): void {}
+  send(): void {}
+  close(): void {}
+}
+
+describe('createWsRpcChannel', () => {
+  beforeEach(() => {
+    FakeWebSocket.instances = []
+    vi.stubGlobal('WebSocket', FakeWebSocket)
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('close() closes the underlying socket', () => {
+    const channel = createWsRpcChannel({ url: 'ws://localhost:5173/__ws' })
+    const ws = FakeWebSocket.instances.at(-1)!
+    const closeSpy = vi.spyOn(ws, 'close')
+
+    channel.close()
+
+    expect(closeSpy).toHaveBeenCalledTimes(1)
+  })
+})

packages/devframe/src/rpc/transports/ws-client.ts

@@ -27,8 +27,11 @@ const EMPTY_DEFS: ReadonlyMap<string, Pick<RpcFunctionDefinitionAny, 'jsonSerial
 /**
  * Build a birpc `ChannelOptions` object backed by a browser `WebSocket`.
  * Pass the result straight to `createRpcClient`'s `channel` option.
+ *
+ * Also returns `close()`, closing the underlying socket — mirroring the server transport's
+ * existing `WsRpcTransport.close()`. `birpc`'s own `ChannelOptions` has no teardown of its own.
  */
-export function createWsRpcChannel(options: WsRpcChannelOptions): ChannelOptions {
+export function createWsRpcChannel(options: WsRpcChannelOptions): ChannelOptions & { close: () => void } {
   let url = options.url
   if (options.authToken) {
     url = `${url}?${DEVFRAME_AUTH_TOKEN_QUERY_PARAM}=${encodeURIComponent(options.authToken)}`
@@ -59,6 +62,9 @@ export function createWsRpcChannel(options: WsRpcChannelOptions): ChannelOptions
   // method up in `definitions` and pick the right encoder.
   const pendingRequestMethods = new Map<string, string>()
   return {
+    close: () => {
+      ws.close()
+    },
     on: (handler: (data: string) => void) => {
       ws.addEventListener('message', (e) => {
         handler(e.data)