Skip to content

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

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

SaKaNa-Y wants to merge 7 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. If the endpoint is the mount root, HTTP discovery advertises ./ and the handle advertises /nested/tool/.

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. A strict JSON method accepts a plain object and rejects a Map 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 a mount-root route, HTTP discovery previously sent clients to /. The regression tests now make WebSocket and SSE calls and initialize MCP through both descriptors at the nested mount root.
  • 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,869 tests with 14 skipped on Node 26.8.1.

Merge Danger

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

Blast Radius: Live connection discovery. 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-16 04:59 UTC
🔗 head 0a4222d
🤖 automated by pulls.review

{
  "headSha": "0a4222d847d787a629f3fda15c5599a094d356fa",
  "result": {
    "overallSummary": "Fixes `createDevServer()` so it always returns a usable, closable handle and so `handle.connectionMeta()` matches HTTP discovery (`__connection.json`): strict JSON RPC method names are included and kept live, static config values are serialized consistently, and relative WebSocket/SSE/MCP paths resolve correctly at nested and mount-root bases. Includes a large new regression test suite and a docs update describing the clarified contract.",
    "groups": [
      {
        "key": "core-fix",
        "label": "Dev server handle fix",
        "summary": "Makes `createDevServer()` always return a closable handle (even with WebSocket disabled), aligns `handle.connectionMeta()` snapshots with HTTP discovery (including strict JSON method names read live from the RPC registry), and fixes relative path resolution for mount-root WebSocket/SSE/MCP endpoints.",
        "category": "api",
        "filePaths": [
          "packages/devframe/src/adapters/dev.ts",
          "packages/devframe/src/adapters/initiate.ts",
          "packages/devframe/src/node/instance-shell.ts"
        ],
        "critical": true,
        "lineNotes": [
          {
            "path": "packages/devframe/src/node/instance-shell.ts",
            "side": "additions",
            "line": 822,
            "text": "Shared HTTP servers now keep a handle/RPC group even when WS is disabled, fixing the previous throw-before-return bug for WebSocket-disabled configurations.",
            "critical": true
          },
          {
            "path": "packages/devframe/src/adapters/dev.ts",
            "side": "additions",
            "line": 237,
            "text": "Deep-clones the devframe's connectionMeta via a JSON round-trip so static config values (e.g. `URL` instances) match HTTP discovery's JSON form, and mutating one snapshot can't affect later ones.",
            "critical": true
          }
        ]
      },
      {
        "key": "tests",
        "label": "Transport & discovery tests",
        "summary": "New and updated regression tests covering SSE-only/HTTP-only handle lifecycle and port reuse, strict JSON method discovery (including methods registered after startup), nested mount-root path resolution, and parity between `handle.connectionMeta()` and `__connection.json`.",
        "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/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 test file exercising real WebSocket/SSE/HTTP calls against both discovery descriptors, mount-root path resolution, snapshot immutability, and handle lifecycle/port release."
          }
        ]
      },
      {
        "key": "docs",
        "label": "Dev server docs update",
        "summary": "Documents the full `StartedServer` shape, the fresh-snapshot behavior of `connectionMeta()`, and the relative-path resolution rules for discovery vs. the handle.",
        "category": "docs",
        "filePaths": [
          "docs/content/2.adapters/3.dev.md"
        ]
      }
    ],
    "schemaVersion": 1,
    "source": "llm",
    "generatedAt": "2026-11-16T04:59:22.051Z",
    "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 3 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.

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