Skip to content

fix(devframe): return complete connection metadata from dev server handles - #484

Draft
SaKaNa-Y wants to merge 11 commits into
devframes:mainfrom
SaKaNa-Y:fix/dev-server-sse-handle
Draft

SaKaNa-Y wants to merge 11 commits into
devframes:mainfrom
SaKaNa-Y:fix/dev-server-sse-handle

Conversation

@SaKaNa-Y

@SaKaNa-Y SaKaNa-Y commented Nov 5, 2026 •

Copy link
Copy Markdown
Member

Summary

With WebSocket disabled, createDevServer() opens an HTTP listener and then throws before returning the handle needed to close it. With WebSocket and SSE enabled, the handle advertises only WebSocket. HTTP discovery also omits the names of strict JSON methods, so an RPC client can send a Map to a handler that expects JSON.

Return a closable handle for each transport configuration. Both discovery paths read the strict JSON method names from the current RPC registry, including methods registered after startup. Each call to handle.connectionMeta() returns a fresh JSON snapshot, so static configuration values such as URL have the same representation as in HTTP discovery.

For a devframe mounted at /nested/tool/, callers can reach the same MCP route from either descriptor. Same-origin WebSocket and SSE paths follow the same rule. For an endpoint at the mount root, HTTP discovery and the public MCP helper return ./. The handle returns /nested/tool/. When WebSocket uses a dedicated port, resolve its path from the root of that port’s origin.

Source Advertised MCP path Resolve against
handle.connectionMeta() /nested/tool/tools/mcp handle.origin
__connection.json tools/mcp Discovery document URL

Evidence

  • Real WebSocket and SSE calls use both discovery paths. In Chrome, a strict JSON method previously rejected a plain object created in a same-origin iframe. It now accepts the object over either transport and still rejects Map and Date before the handler runs. An unflagged method round-trips the same Map.
  • Before the snapshot fix, initializing MCP through the nested handle returned 404, and reading a handle with a URL in its static configuration threw DataCloneError. The regression tests now initialize MCP through both descriptors and read the same URL string from both. Mutating a handle snapshot leaves subsequent snapshots and HTTP discovery intact.
  • With MCP at the mount root, the public helper previously sent clients to / and initialization returned 404. On this revision, the helper, HTTP discovery and the handle all led to /nested/tool/ and initialization returned 200. For a WebSocket on a dedicated port, following the revised guide connected at /__ws.
  • The lifecycle tests close the SSE-only and HTTP-only handles and verify port reuse. The SSE-only test also verifies registry cleanup.

Local lint, documentation lint, Knip, typecheck and build passed. The full Vitest run passed 1,885 tests with 14 skipped on Node 26.8.1.

On the GitHub merge build, the Ubuntu and Windows unit jobs report three diagnostic type declaration snapshot mismatches. The same three snapshots failed on the target commit before this PR. PR run, main run.

Merge Danger

Door: Two-way. The patch can be reverted without a data migration.

Blast Radius: Live connection discovery and strict JSON serialization. RPC clients using a strict JSON method now reject unsupported values before dispatch. An incorrect path or method list can prevent a connection or select the wrong encoding.

Keep the shared HTTP handle and RPC group when WebSocket is disabled. Return instance connection metadata while retaining transport JSON encoding hints.

Cover SSE-only startup and disposal, returned-descriptor RPC over both transports, nested and renamed routes, and transport-disabled controls.
@vercel

vercel Bot commented Nov 5, 2026

Copy link
Copy Markdown

@SaKaNa-Y is attempting to deploy a commit to the NuxtLabs Team on Vercel.

A member of the Team first needs to authorize it.

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

👁️‍🗨️ Review this pull request with grouped, summarized diffs at:
👉 https://pulls.review/gh/devframes/devframe/484?from=github-actions[bot]

raw result

💭 analyzed by vercel-ai-gateway/anthropic/claude-sonnet-5
🕰️ 2026-11-18 05:26 UTC
🔗 head 1cee834
🤖 automated by pulls.review

{
  "headSha": "1cee8341da98d40d3e7beb7e5178d5d66164bbed",
  "result": {
    "overallSummary": "Fixes dev server connection handling: createDevServer() now always returns a closable handle (even with transports disabled), connectionMeta() advertises both transports and live strict-JSON method names in the same JSON shape as HTTP discovery, and mount-root/nested-mount paths resolve consistently across the handle, HTTP discovery, and MCP helper. A related RPC serialization fix lets strict JSON methods accept plain objects from other realms while still rejecting Map/Date/class instances.",
    "groups": [
      {
        "key": "dev-server-handle",
        "label": "Dev server handle metadata",
        "summary": "Fixes createDevServer()/dev server handles so a closable handle is always returned (even with WebSocket disabled), connectionMeta() always advertises both transports, strict JSON method names are read live from the RPC registry, and mount-root/nested-mount paths resolve consistently between the handle and HTTP discovery.",
        "category": "api",
        "filePaths": [
          "packages/devframe/src/adapters/_shared.ts",
          "packages/devframe/src/adapters/dev.ts",
          "packages/devframe/src/adapters/initiate.ts",
          "packages/devframe/src/node/instance-shell.ts",
          "packages/devframe/src/node/utils.ts"
        ],
        "critical": true,
        "fileNotes": [
          {
            "path": "packages/devframe/src/node/instance-shell.ts",
            "text": "Shared-server tier now also binds when WS is disabled so a closable handle and RPC group are always returned; jsonSerializableMethods is now a live getter reading the current registry instead of a snapshot taken at bind time."
          },
          {
            "path": "packages/devframe/src/adapters/dev.ts",
            "text": "connectionMeta() now returns a fresh JSON-cloned snapshot and rewrites relative websocket/sse/mcp paths with the base path, matching HTTP discovery's representation."
          }
        ]
      },
      {
        "key": "strict-json-serialization",
        "label": "Strict JSON cross-realm fix",
        "summary": "Allows strictJsonStringify to accept plain objects created in another realm (e.g. a same-origin iframe) by comparing the object's constructor source instead of identity, while still rejecting Map/Date/class instances.",
        "category": "core",
        "filePaths": [
          "packages/devframe/src/rpc/serialization.ts"
        ],
        "critical": true
      },
      {
        "key": "tests",
        "label": "Tests for handle & discovery changes",
        "summary": "Regression coverage for closable handles with WS/SSE disabled, live jsonSerializableMethods, mount-root and nested-mount path resolution parity between handle and HTTP discovery, and cross-realm plain-object JSON serialization.",
        "category": "tests",
        "filePaths": [
          "packages/devframe/src/adapters/__tests__/dev-transports.test.ts",
          "packages/devframe/src/adapters/__tests__/dev.test.ts",
          "packages/devframe/src/adapters/__tests__/initiate.test.ts",
          "packages/devframe/src/rpc/serialization.test.ts",
          "packages/hub/src/node/__tests__/initiate.test.ts",
          "examples/custom-hub-next/tests/next-devframe-hub.test.ts"
        ],
        "fileNotes": [
          {
            "path": "packages/devframe/src/adapters/__tests__/dev-transports.test.ts",
            "text": "New suite exercising real WebSocket/SSE RPC calls through both the handle and HTTP discovery descriptors, including lifecycle/port-reuse and registry cleanup checks."
          }
        ]
      },
      {
        "key": "docs",
        "label": "Dev server docs update",
        "summary": "Documents the full StartedServer shape, the fresh-snapshot semantics of connectionMeta(), and how to resolve WebSocket/SSE/MCP paths including the dedicated-port and mount-root cases.",
        "category": "docs",
        "filePaths": [
          "docs/content/2.adapters/3.dev.md"
        ]
      }
    ],
    "schemaVersion": 1,
    "source": "llm",
    "generatedAt": "2026-11-18T05:26:38.077Z",
    "model": "vercel-ai-gateway/anthropic/claude-sonnet-5",
    "locale": "en"
  }
}

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.
@SaKaNa-Y
SaKaNa-Y force-pushed the fix/dev-server-sse-handle branch from 85e31b1 to 70282fa Compare November 7, 2026 07:53
Return a fresh connection descriptor for each handle call so a viewer can edit its copy without changing HTTP discovery. Resolve local RPC paths from the mount so viewers can connect from the server origin.
Serialize connection metadata using the discovery JSON format so static configuration can supply values with toJSON methods. Resolve same-origin MCP paths against the mount base for callers that receive the handle.

Exercise both discovery paths with a real MCP initialize request and compare the published representation of a URL in static configuration.
@SaKaNa-Y SaKaNa-Y changed the title fix(devframe): return complete dev server handles for SSE fix(devframe): return complete connection metadata from dev server handles Nov 8, 2026
SaKaNa-Y and others added 7 commits November 14, 2026 16:36
Advertise the mount root as ./ so a discovery document under a nested path resolves WebSocket, SSE and MCP to the bound endpoint. Cover both discovery paths with real connections.
HTTP discovery can select strict JSON for a method called with an object from a same-origin iframe. Each window owns a different Object.prototype, so comparing the prototype by identity rejected ordinary JSON before dispatch.

Recognize the native Object constructor for the prototype from another realm. Keep rejecting class and Map instances.
Use the same relative path for hand-written and built-in discovery at a nested mount. A descriptor with its own port still uses the root of the sidecar origin.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant