Repository navigation
Return correlated errors for hosted MCP gateway failures - #328
khaliqgant merged 3 commits into
Conversation
Composal Verify · PR #328Warning This request is merged; previous verification results remain in the history. Backend-only diff: automatic browser tests were skipped. Relevant scenarios are available to run manually against the configured test environment. Diff assessment: Adds server-side MCP gateway error handling for POST requests: correlated JSON-RPC errors for uncorrelated 5xx responses and dispatch exceptions, diagnostic logging, and maintenance-response preservation. Changes include backend tests and documentation, with no frontend or browser-rendered modifications. Why no scenarios were selectedNo saved scenario matched this change. Recent verification history
|
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars.
|
khaliqgant
left a comment
There was a problem hiding this comment.
neonexit-reviewer @ 2da8353: SHIP (router: correlated hosted-MCP gateway failures).
- Scope: it applies only to
POSTon hostnameagentrelay.comfor/mcp,/api/v1/mcp/shared-sessions,/api/v1/mcp/relay-eventsand/api/v1/replicas/mcp(an optional/cloudprefix and trailing slash are normalized). Every other request goes throughforward()exactly as before, including rethrowing on failure. - Never replays:
forward()is called once. A thrown dispatch failure becomes a correlated 503 for these MCP paths only. - Untouched pass-through: any status below 500, and any 5xx that already carries
x-correlation-id(which cloud's MCP diagnostics now add), is returned unread. Successful streams are never buffered. - The cutover contract is preserved. A 5xx carrying
x-agent-relay-database-read-only: enabled(cloud'sworker-read-only-cutover.mjs:110) orx-agent-relay-database-target: unavailable(worker-request-lifecycle.mjs:55and the proactive runtime'sworker.ts:158) is passed through with its body, status and every header, Retry-After included, plus onlyx-correlation-idandcache-control: no-store. Any other uncorrelated 5xx keeps its status and headers, including Retry-After, but gets a fixed JSON-RPC body. The upstream body is cancelled, not read, and content headers are dropped. - No PII: the log is
{event, endpoint, status, correlationId, cfRay (format-validated, colo stripped), failure category}, with no URL, headers, bodies or exception text. The id iscrypto.randomUUID().
What I ran (fresh worktree at 2da8353, npm ci):
| Check | Result |
|---|---|
router: npm test |
13 files, 344/344 |
router: npm run typecheck |
0 |
Non-blocking: the hostname check is exact (agentrelay.com), so www. or any other alias won't get the fallback. That's fine if the apex is the only MCP host, as the README says.
A hosted MCP call can receive an empty HTTP 5xx when the application Worker terminates before its handler can respond. The gateway currently forwards that response unchanged, leaving clients with an empty transport error.
Wrap the existing router dispatch for canonical-host MCP POST endpoints. Uncorrelated 5xx responses and thrown dispatch failures now return a safe JSON-RPC message with a correlation ID in the body and header. Fixed-category logs join that ID to the validated platform request ID. Application-correlated errors and successful streams pass through unchanged; maintenance responses retain their original body and retry contract. Calls are forwarded once, without reading or replaying their request bodies. This improves diagnostics outside the application isolate; it does not fix the underlying memory allocation.
Validation at
2da8353b7051c9fb73fa730154627067dc7d8193:npm --workspace router run test: 344 tests across 13 files. Removing the outer dispatch wrapper makes 13 integration assertions fail, including empty failures, thrown dispatch, maintenance preservation and correlation behavior.npm run typecheck: both web and router typechecks pass.npm run lint: zero errors; four warnings in unchanged web files.router/index.ts: succeeds (53,615 bytes).Tests and typecheckandTypecheck, lint, test, buildpass, including the full web/router suites and production build. Independent reviewer SHIP is posted on this commit; automated checks alone are not review approval.npm test: the web suite has two unchanged path-encoding fixture failures when the checkout path contains a space (635/637); the router suite passes. The fixtures use URL pathname text as a shell path; decoding the path resolves their syntax/help probes. No web source or test was changed.Opened from a fork so the existing same-repository preview guard skips deployment. No routing flags, infrastructure, credentials or workflows change. Keep
merge-train:holduntil owner approval; no merge or deployment is requested.