fix(devframe): publish strict JSON methods in live discovery

Read method flags from the current RPC registry when a client requests the instance descriptor. This gives SSE-only handles and HTTP discovery the same encoding hints as WebSocket handles, including methods registered after startup.

Author: SaKaNa-Y

examples/custom-hub-next/tests/next-devframe-hub.test.ts

@@ -54,6 +54,7 @@ describe('next-devframe-hub (example)', () => {
 
     expect(hub.connectionMeta()).toEqual({
       backend: 'websocket',
+      jsonSerializableMethods: expect.arrayContaining(['devframes:plugin:assets:list']),
       websocket: { port, path: '__ws' },
       sse: { path: '/__devframes/__sse' },
       mcp: { path: '__mcp' },

packages/devframe/src/adapters/__tests__/dev-transports.test.ts

@@ -9,6 +9,8 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { readDevframeInstances } from '../../node/instance-registry'
 import { createDevServer } from '../dev'
 
+const jsonHandler = vi.fn((value: unknown) => value)
+
 const definition = defineDevframe({
   id: 'dev-transports-test',
   name: 'Dev transports test',
@@ -20,13 +22,13 @@ const definition = defineDevframe({
     ctx.rpc.register(defineRpcFunction({
       name: 'test:probe',
       type: 'query',
-      handler: () => 'connected',
+      handler: (value: unknown) => value,
     }))
     ctx.rpc.register(defineRpcFunction({
       name: 'test:json',
       type: 'query',
       jsonSerializable: true,
-      handler: (value: unknown) => value,
+      handler: jsonHandler,
     }))
   },
 })
@@ -70,7 +72,8 @@ describe('dev server transport handle', () => {
           sse: { path: '__sse' },
         })
         await vi.waitFor(() => expect(readDevframeInstances({ instancesDir: registryDir })).toHaveLength(1))
-        await callThroughHandle(handle, '/', 'sse')
+        await checkRpcCalls(handle, '/', 'sse')
+        await checkRpcCalls(handle, '/', 'sse', 'http')
       }
       finally {
         await handle.close()
@@ -96,8 +99,9 @@ describe('dev server transport handle', () => {
       expect(handle.connectionMeta()).toMatchObject(httpMeta)
       expect(handle.connectionMeta().jsonSerializableMethods).toContain('test:json')
       expect(resolveClientTransport('auto', handle.connectionMeta())).toBe('websocket')
-      await callThroughHandle(handle, basePath, 'sse')
-      await callThroughHandle(handle, basePath, 'websocket')
+      await checkRpcCalls(handle, basePath, 'sse')
+      await checkRpcCalls(handle, basePath, 'websocket')
+      await checkRpcCalls(handle, basePath, 'websocket', 'http')
     }
     finally {
       await handle.close()
@@ -109,7 +113,7 @@ describe('dev server transport handle', () => {
     const handle = await createDevServer(definition, { ...options, sse: false })
     try {
       expect(handle.connectionMeta().sse).toBeUndefined()
-      await callThroughHandle(handle, '/', 'websocket')
+      await checkRpcCalls(handle, '/', 'websocket')
     }
     finally {
       await handle.close()
@@ -124,6 +128,7 @@ describe('dev server transport handle', () => {
       expect(handle.connectionMeta()).toMatchObject({ backend: 'none' })
       expect(handle.connectionMeta().websocket).toBeUndefined()
       expect(handle.connectionMeta().sse).toBeUndefined()
+      expect(handle.connectionMeta()).not.toHaveProperty('jsonSerializableMethods')
       expect((await fetch(`${handle.origin}/__connection.json`)).status).toBe(200)
     }
     finally {
@@ -133,13 +138,17 @@ describe('dev server transport handle', () => {
   })
 })
 
-async function callThroughHandle(handle: Awaited<ReturnType<typeof createDevServer>>, basePath: string, transport: 'sse' | 'websocket') {
+async function checkRpcCalls(handle: Awaited<ReturnType<typeof createDevServer>>, basePath: string, transport: 'sse' | 'websocket', source: 'handle' | 'http' = 'handle') {
   vi.stubGlobal('location', new URL(`${handle.origin}${basePath}`))
   vi.stubGlobal('navigator', { userAgent: 'vitest' })
+  const metaBaseUrl = `${handle.origin}${basePath}__connection.json`
+  const connectionMeta = source === 'http'
+    ? await fetch(metaBaseUrl).then(response => response.json())
+    : handle.connectionMeta()
   const client = await getDevframeRpcClient({
     connection: {
-      connectionMeta: handle.connectionMeta(),
-      metaBaseUrl: `${handle.origin}${basePath}__connection.json`,
+      connectionMeta,
+      metaBaseUrl,
     },
     transport,
     otpParam: false,
@@ -148,14 +157,15 @@ async function callThroughHandle(handle: Awaited<ReturnType<typeof createDevServ
   try {
     await client.ensureTrusted(2000)
     expect(client.transport).toBe(transport)
-    await expect((client.call as any)('test:probe')).resolves.toBe('connected')
+    const map = new Map([
+      ['key', 42],
+    ])
+    await expect((client.call as any)('test:probe', map)).resolves.toEqual(map)
     expect(handle.rpcGroup.clients.length).toBeGreaterThan(0)
-    if (handle.connectionMeta().jsonSerializableMethods?.includes('test:json')) {
-      await expect((client.call as any)('test:json', { value: 42 })).resolves.toEqual({ value: 42 })
-      await expect((client.call as any)('test:json', new Map([
-        ['key', 42],
-      ]))).rejects.toThrow()
-    }
+    jsonHandler.mockClear()
+    await expect((client.call as any)('test:json', { value: 42 })).resolves.toEqual({ value: 42 })
+    await expect((client.call as any)('test:json', map)).rejects.toThrow(/Map/)
+    expect(jsonHandler).toHaveBeenCalledTimes(1)
   }
   finally {
     client.close?.()

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

@@ -141,6 +141,7 @@ describe('adapters/dev', () => {
       // relative to `__connection.json`, never a baked-in host/port.
       expect(meta).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { path: '__ws' },
         sse: { path: '__sse' },
       })
@@ -250,6 +251,7 @@ describe('adapters/dev', () => {
       const meta = await (await fetch(`http://${host}:${port}/__connection.json`)).json()
       expect(meta).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { path: '__sockets' },
         sse: { path: '__sse' },
       })
@@ -290,6 +292,7 @@ describe('adapters/dev', () => {
       const meta = await (await fetch(`http://${host}:${port}/__connection.json`)).json()
       expect(meta).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { port: wsPort, path: '__ws' },
         sse: { path: '__sse' },
       })
@@ -334,6 +337,7 @@ describe('adapters/dev', () => {
       // endpoint stays same-origin and rides the tunnel like the meta itself.
       expect(meta).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: 'wss://devtools.example.com/relay/__ws',
         sse: { path: '__sse' },
       })
@@ -462,6 +466,7 @@ describe('adapters/dev', () => {
       const meta = await res.json()
       expect(meta).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { path: '__ws' },
         sse: { path: '__sse' },
       })

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

@@ -75,6 +75,7 @@ describe('adapters/handler', () => {
       // The advertised meta carries the side-car port with the unified route.
       expect(devtools.connectionMeta()).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { port: wsPort, path: '__ws' },
         sse: { path: '__sse' },
       })
@@ -84,10 +85,18 @@ describe('adapters/handler', () => {
       expect(index.status).toBe(200)
       expect(await index.text()).toContain('handler test')
 
+      const ctx = await devtools.context
+      ctx.rpc.register({
+        name: 'test:late-json',
+        type: 'query',
+        jsonSerializable: true,
+        handler: () => 'ok',
+      })
       const metaRes = await devtools.handler(new Request('http://localhost:3000/__handler-test/__connection.json'))
       expect(metaRes.status).toBe(200)
       expect(await metaRes.json()).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.arrayContaining(['test:late-json']),
         websocket: { port: wsPort, path: '__ws' },
         sse: { path: '__sse' },
       })
@@ -183,6 +192,7 @@ describe('adapters/handler', () => {
       // resolved against __connection.json's own URL.
       expect(devtoolsRef.connectionMeta()).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { path: '__ws' },
         sse: { path: '__sse' },
       })
@@ -194,6 +204,7 @@ describe('adapters/handler', () => {
       const meta = await (await fetch(`http://${host}:${port}/__handler-shared/__connection.json`)).json()
       expect(meta).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { path: '__ws' },
         sse: { path: '__sse' },
       })
@@ -272,6 +283,7 @@ describe('adapters/handler', () => {
       const meta = await (await fetch(`http://${host}:${port}/__connection.json`)).json()
       expect(meta).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { path: '__ws' },
         sse: { path: '__sse' },
       })
@@ -346,6 +358,7 @@ describe('adapters/handler', () => {
 
     try {
       await devtools.ready
+      expect(devtools.connectionMeta()).not.toHaveProperty('jsonSerializableMethods')
       expect(devtools.connectionMeta()).toEqual({
         backend: 'websocket',
         websocket: 'wss://devtools.example.com/relay/__ws',
@@ -599,6 +612,7 @@ describe('adapters/handler', () => {
       // Advertised as a same-origin route, with no port of its own.
       expect(devtools.connectionMeta()).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { path: '__ws' },
         sse: { path: '__sse' },
       })

packages/devframe/src/adapters/dev.ts

@@ -232,7 +232,6 @@ export async function createDevServer(
     ws: transport.ws,
     rpcGroup: transport.rpcGroup,
     connectionMeta: () => ({
-      ...transport.connectionMeta(),
       ...devframe.connectionMeta(),
     }),
     async close() {

packages/devframe/src/node/instance-shell.ts

@@ -9,7 +9,6 @@ import type { Duplex } from 'node:stream'
 import type { ConnectionMeta, DevframeNodeContext, DevframeNodeRpcSession, DevframeNodeRpcSessionMeta, DevframeRpcClientFunctions, DevframeRpcServerFunctions } from '../types'
 import type { DevframeSseOptions, DevframeWsOptions } from '../types/devframe'
 import type { DevframeAuthHandler } from './auth'
-import type { RpcFunctionsHostImpl } from './host-functions'
 import type { DevframeInstanceRecord, DevframeInstanceRegistration } from './instance-registry'
 import type { ContextRpcServer } from './rpc-core'
 import { createServer } from 'node:http'
@@ -74,16 +73,20 @@ interface TierBinding {
   wsAvailable: boolean
 }
 
-function websocketConnectionMeta(rpcHost: RpcFunctionsHostImpl, path: string | undefined): ConnectionMeta {
+function getJsonSerializableMethods(rpc: DevframeNodeContext['rpc']): string[] {
   const jsonSerializableMethods: string[] = []
-  for (const def of rpcHost.definitions.values()) {
+  for (const def of rpc.definitions.values()) {
     if (def.jsonSerializable === true)
       jsonSerializableMethods.push(def.name)
   }
+  return jsonSerializableMethods
+}
+
+function websocketConnectionMeta(rpc: DevframeNodeContext['rpc'], path: string | undefined): ConnectionMeta {
   return {
     backend: 'websocket',
     websocket: { path },
-    jsonSerializableMethods,
+    jsonSerializableMethods: getJsonSerializableMethods(rpc),
   }
 }
 
@@ -101,7 +104,6 @@ async function bindHttpAndWs(options: BindHttpAndWsOptions): Promise<StartedServ
   const app = new H3App()
   const ownsHttpServer = !options.server
   const httpServer = options.server ?? createServer(toNodeHandler(app))
-  const rpcHost = context.rpc as RpcFunctionsHostImpl
   const websocket = options.websocket !== false
 
   let ws: NodeAdapter | undefined
@@ -170,7 +172,7 @@ async function bindHttpAndWs(options: BindHttpAndWsOptions): Promise<StartedServ
     app,
     ws,
     rpcGroup: core.rpcGroup,
-    connectionMeta: () => websocketConnectionMeta(rpcHost, options.path),
+    connectionMeta: () => websocketConnectionMeta(context.rpc, options.path),
     async close() {
       httpServer.off('listening', publishWsEndpoint)
       await closeWs()
@@ -246,7 +248,6 @@ async function bindNativeHttpAndWs(
   const { context, port, core } = options
   const bindHost = options.host
   const app = new H3App()
-  const rpcHost = context.rpc as RpcFunctionsHostImpl
   const wsPath = options.path
 
   const fail = async (closeWs: () => Promise<void>, error: unknown): Promise<never> => {
@@ -331,7 +332,7 @@ async function bindNativeHttpAndWs(
     app,
     ws: undefined,
     rpcGroup: core.rpcGroup,
-    connectionMeta: () => websocketConnectionMeta(rpcHost, options.path),
+    connectionMeta: () => websocketConnectionMeta(context.rpc, options.path),
     async close() {
       // Stop the native server before the WS tier: closing the socket while a
       // peer is mid-disconnect (a client that just sent its close frame)
@@ -860,6 +861,17 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
     }
   }
 
+  function addLocalMethodHints(meta: ConnectionMeta): void {
+    if (tier === 'external' || meta.backend === 'none')
+      return
+    // Routes retain this descriptor. Read the registry on discovery so it
+    // includes methods registered after startup.
+    Object.defineProperty(meta, 'jsonSerializableMethods', {
+      enumerable: true,
+      get: () => getJsonSerializableMethods(ctx.rpc),
+    })
+  }
+
   async function init(): Promise<void> {
     const result = await options.init(api)
     ctx = result.context
@@ -912,6 +924,8 @@ export function createInstanceShell<TContext extends DevframeNodeContext>(
         : {}),
     }
 
+    addLocalMethodHints(meta)
+
     // Whatever `setup(ctx)` wrote to `ctx.staticConfig` during
     // `options.init(api)` (e.g. a hub aggregating each installed devframe's
     // own dock-bar preferences) is in by now; bake it into the meta

packages/hub/src/node/__tests__/initiate.test.ts

@@ -137,6 +137,7 @@ describe('initHub', () => {
       // the aggregate MCP route.
       expect(hubRef.connectionMeta()).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { path: '/__devframes/__ws' },
         sse: { path: '/__devframes/__sse' },
         mcp: { path: '__mcp' },
@@ -750,6 +751,7 @@ describe('initHub', () => {
       await hub.ready
       expect(hub.connectionMeta()).toEqual({
         backend: 'websocket',
+        jsonSerializableMethods: expect.any(Array),
         websocket: { path: '/__devframes/__ws' },
         sse: { path: '/__devframes/__sse' },
         mcp: { path: '__mcp' },