From d1649c09d7bf5f7201af43b266a143627f5b2561 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 11:53:52 +0000 Subject: [PATCH 1/7] Add streamable HTTP bridge for the aitools MCP proxy Adds libs/aitools/mcp/proxy, a bridge between MCP stdio (newline-delimited JSON-RPC on stdin and stdout) and a streamable HTTP MCP endpoint. Nothing calls it yet; the `aitools mcp serve` command comes in a later change. Co-authored-by: Isaac --- libs/aitools/mcp/proxy/bridge.go | 486 +++++++++++++++++++++ libs/aitools/mcp/proxy/bridge_test.go | 543 ++++++++++++++++++++++++ libs/aitools/mcp/proxy/messages.go | 119 ++++++ libs/aitools/mcp/proxy/messages_test.go | 89 ++++ libs/aitools/mcp/proxy/sse.go | 46 ++ libs/aitools/mcp/proxy/sse_test.go | 35 ++ 6 files changed, 1318 insertions(+) create mode 100644 libs/aitools/mcp/proxy/bridge.go create mode 100644 libs/aitools/mcp/proxy/bridge_test.go create mode 100644 libs/aitools/mcp/proxy/messages.go create mode 100644 libs/aitools/mcp/proxy/messages_test.go create mode 100644 libs/aitools/mcp/proxy/sse.go create mode 100644 libs/aitools/mcp/proxy/sse_test.go diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go new file mode 100644 index 00000000000..d6cc765005d --- /dev/null +++ b/libs/aitools/mcp/proxy/bridge.go @@ -0,0 +1,486 @@ +// Package proxy bridges MCP stdio (newline-delimited JSON-RPC) to a streamable HTTP MCP endpoint. +package proxy + +import ( + "bufio" + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "net" + "net/http" + "strings" + "sync" + "time" +) + +const ( + logPrefix = "databricks aitools mcp serve: " + sessionHeader = "Mcp-Session-Id" + protocolHeader = "MCP-Protocol-Version" + acceptHeader = "application/json, text/event-stream" + eventStreamMIME = "text/event-stream" + + maxLineBytes = 64 << 20 + connectTimeout = 10 * time.Second + idleTimeout = 10 * time.Minute + shutdownGrace = 2 * time.Second + deleteTimeout = 5 * time.Second + + codeParseError = -32700 + codeInvalidParams = -32602 + codeUpstream = -32000 +) + +var ( + newline = []byte{'\n'} + errIdleTimeout = errors.New("no data from upstream for 10 minutes") + errNoResponse = errors.New("upstream sent no response") +) + +// Hooks intercepts upstream messages before they are written to stdout. +type Hooks interface { + // Result receives each upstream message for a client request, with the HTTP status (0 when the + // request failed before a response). It returns the messages to write in its place, in order: + // a single copy of message passes it through, an empty slice drops it. + Result(ctx context.Context, request []byte, status int, message []byte) ([][]byte, error) +} + +// Bridge serves MCP over stdio by forwarding each client message to Endpoint. +type Bridge struct { + In io.Reader + Out io.Writer + Err io.Writer + Endpoint string + // Authenticate sets the Authorization header on each upstream request. + Authenticate func(*http.Request) error + // Headers are set on every upstream request. + Headers map[string]string + // Instructions is appended to the initialize result's instructions when not empty. + Instructions string + // ForceListChanged sets capabilities.tools.listChanged on the initialize result. + ForceListChanged bool + // Hooks, when set, sees every upstream message before it is written. + Hooks Hooks +} + +// Run forwards stdin to the endpoint until stdin closes or ctx is done. Shutdown waits up to 2 s for +// in-flight requests, cancels the rest, and sends DELETE for the session. Run returns an error only +// when reading stdin fails. +func (b *Bridge) Run(ctx context.Context) error { + base, cancelBase := context.WithCancel(context.WithoutCancel(ctx)) + c := &conn{ + b: b, + client: newClient(), + base: base, + cancelBase: cancelBase, + inflight: map[string]context.CancelFunc{}, + } + + lines := make(chan []byte) + stop := make(chan struct{}) + defer close(stop) + var readErr error + go func() { + defer close(lines) + readErr = scanLines(b.In, lines, stop) + }() + + for { + select { + case <-ctx.Done(): + c.shutdown(ctx) + return nil + case line, ok := <-lines: + if !ok { + c.shutdown(ctx) + if readErr != nil { + return fmt.Errorf("read stdin: %w", readErr) + } + return nil + } + c.handle(line) + } + } +} + +// scanLines sends each non-blank stdin line to lines, keeping its bytes exactly as received. +func scanLines(in io.Reader, lines chan<- []byte, stop <-chan struct{}) error { + sc := bufio.NewScanner(in) + sc.Buffer(nil, maxLineBytes) + sc.Split(splitLines) + for sc.Scan() { + if len(bytes.TrimSpace(sc.Bytes())) == 0 { + continue + } + select { + case lines <- bytes.Clone(sc.Bytes()): + case <-stop: + return nil + } + } + return sc.Err() +} + +// splitLines is bufio.ScanLines without dropping a trailing carriage return. +func splitLines(data []byte, atEOF bool) (int, []byte, error) { + if i := bytes.IndexByte(data, '\n'); i >= 0 { + return i + 1, data[:i], nil + } + if atEOF && len(data) > 0 { + return len(data), data, nil + } + return 0, nil, nil +} + +// conn is the state of one Run. +type conn struct { + b *Bridge + client *http.Client + base context.Context + cancelBase context.CancelFunc + wg sync.WaitGroup + + ioMu sync.Mutex // serializes writes to Out and Err + + mu sync.Mutex // guards the fields below + sessionID string + protocolVersion string + inflight map[string]context.CancelFunc +} + +// newClient returns the upstream HTTP client: a 10 s connect timeout and the environment's proxy settings. +func newClient() *http.Client { + t := http.DefaultTransport.(*http.Transport).Clone() + t.DialContext = (&net.Dialer{Timeout: connectTimeout}).DialContext + return &http.Client{Transport: t} +} + +// handle processes one stdin line. Upstream work runs in its own goroutine. +func (c *conn) handle(line []byte) { + m, err := parseMessage(line) + if err != nil { + c.logf("invalid JSON on stdin: %v", err) + c.reply(errorResponse(nil, codeParseError, "Parse error")) + return + } + switch m.Method { + case "initialize": + var p struct { + ProtocolVersion string `json:"protocolVersion"` + } + if err := json.Unmarshal(m.Params, &p); err != nil { + c.reply(errorResponse(m.ID, codeInvalidParams, "Invalid params")) + return + } + c.setProtocol(p.ProtocolVersion) + case "notifications/cancelled": + c.cancelRequest(m.Params) + } + + ctx, cancel := context.WithCancel(c.base) + isRequest := m.isRequest() + key := string(m.ID) + if isRequest { + c.track(key, cancel) + } + c.wg.Go(func() { + defer cancel() + if isRequest { + defer c.untrack(key) + } + c.forward(ctx, line, m) + }) +} + +// forward POSTs one client message exactly as received and writes what the upstream answers. +func (c *conn) forward(ctx context.Context, line []byte, m message) { + ctx, cancel := context.WithCancelCause(ctx) + defer cancel(nil) + idle := time.AfterFunc(idleTimeout, func() { cancel(errIdleTimeout) }) + defer idle.Stop() + + x := &exchange{c: c, ctx: ctx, line: line, m: m} + protocol := "" + if m.Method != "initialize" { + protocol = c.protocol() + } + resp, err := c.post(ctx, line, protocol) + if err != nil { + x.fail(err) + return + } + defer resp.Body.Close() + x.status = resp.StatusCode + if sid := resp.Header.Get(sessionHeader); sid != "" { + c.setSession(sid) + } + resp.Body = idleBody{ReadCloser: resp.Body, idle: idle} + if err := x.read(resp); err != nil { + x.fail(err) + return + } + if x.sent == 0 && m.isRequest() { + x.fail(errNoResponse) + } +} + +// shutdown waits for in-flight requests (up to shutdownGrace), cancels the rest, then ends the session. +func (c *conn) shutdown(ctx context.Context) { + done := make(chan struct{}) + go func() { + c.wg.Wait() + close(done) + }() + select { + case <-done: + case <-time.After(shutdownGrace): + c.cancelBase() + <-done + } + c.cancelBase() + c.deleteSession(ctx) +} + +// deleteSession ends the server-side session, best effort. +func (c *conn) deleteSession(ctx context.Context) { + if c.session() == "" { + return + } + ctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), deleteTimeout) + defer cancel() + req, err := c.newRequest(ctx, http.MethodDelete, nil, c.protocol()) + if err != nil { + c.logf("session DELETE: %v", err) + return + } + resp, err := c.client.Do(req) + if err != nil { + c.logf("session DELETE: %v", err) + return + } + resp.Body.Close() +} + +func (c *conn) post(ctx context.Context, body []byte, protocol string) (*http.Response, error) { + req, err := c.newRequest(ctx, http.MethodPost, body, protocol) + if err != nil { + return nil, err + } + return c.client.Do(req) +} + +// newRequest builds an upstream request with the configured headers, the session and protocol headers, +// and the authorization set by Authenticate. A nil body means no Content-Type. +func (c *conn) newRequest(ctx context.Context, method string, body []byte, protocol string) (*http.Request, error) { + var r io.Reader + if body != nil { + r = bytes.NewReader(body) + } + req, err := http.NewRequestWithContext(ctx, method, c.b.Endpoint, r) + if err != nil { + return nil, err + } + for k, v := range c.b.Headers { + req.Header.Set(k, v) + } + req.Header.Set("Accept", acceptHeader) + if body != nil { + req.Header.Set("Content-Type", "application/json") + } + if protocol != "" { + req.Header.Set(protocolHeader, protocol) + } + if sid := c.session(); sid != "" { + req.Header.Set(sessionHeader, sid) + } + if err := c.b.Authenticate(req); err != nil { + return nil, err + } + return req, nil +} + +// write sends one message to stdout as a single line. +func (c *conn) write(msg []byte) error { + c.ioMu.Lock() + defer c.ioMu.Unlock() + if _, err := c.b.Out.Write(msg); err != nil { + return err + } + _, err := c.b.Out.Write(newline) + return err +} + +// reply writes msg to stdout, logging a failed write since there is no caller to return it to. +func (c *conn) reply(msg []byte) { + if err := c.write(msg); err != nil { + c.logf("stdout: %v", err) + } +} + +// logf writes a diagnostic to stderr. +func (c *conn) logf(format string, args ...any) { + c.ioMu.Lock() + defer c.ioMu.Unlock() + fmt.Fprintf(c.b.Err, logPrefix+format+"\n", args...) +} + +func (c *conn) session() string { + c.mu.Lock() + defer c.mu.Unlock() + return c.sessionID +} + +func (c *conn) setSession(id string) { + c.mu.Lock() + defer c.mu.Unlock() + c.sessionID = id +} + +func (c *conn) protocol() string { + c.mu.Lock() + defer c.mu.Unlock() + return c.protocolVersion +} + +func (c *conn) setProtocol(version string) { + c.mu.Lock() + defer c.mu.Unlock() + c.protocolVersion = version +} + +func (c *conn) track(key string, cancel context.CancelFunc) { + c.mu.Lock() + defer c.mu.Unlock() + c.inflight[key] = cancel +} + +func (c *conn) untrack(key string) { + c.mu.Lock() + defer c.mu.Unlock() + delete(c.inflight, key) +} + +// cancelRequest cancels the in-flight request named by a notifications/cancelled params.requestId. +func (c *conn) cancelRequest(params json.RawMessage) { + var p struct { + RequestID json.RawMessage `json:"requestId"` + } + if err := json.Unmarshal(params, &p); err != nil { + c.logf("notifications/cancelled: %v", err) + return + } + c.mu.Lock() + cancel := c.inflight[string(p.RequestID)] + c.mu.Unlock() + if cancel != nil { + cancel() + } +} + +// idleBody resets the idle timer on every read, so a response is cut only after idleTimeout without data. +type idleBody struct { + io.ReadCloser + idle *time.Timer +} + +func (b idleBody) Read(p []byte) (int, error) { + n, err := b.ReadCloser.Read(p) + b.idle.Reset(idleTimeout) + return n, err +} + +// exchange is one client request and the upstream messages answering it. +type exchange struct { + c *conn + ctx context.Context + line []byte + m message + status int + sent int +} + +// read delivers every message in an upstream response. +func (x *exchange) read(resp *http.Response) error { + switch { + case resp.StatusCode/100 != 2: + body, err := io.ReadAll(resp.Body) + if err != nil { + return err + } + if json.Valid(body) { + return x.deliverJSON(body) + } + return fmt.Errorf("HTTP %d", resp.StatusCode) + case strings.HasPrefix(resp.Header.Get("Content-Type"), eventStreamMIME): + return readEvents(resp.Body, x.deliverJSON) + default: + body, err := io.ReadAll(resp.Body) + if err != nil { + return err + } + if len(bytes.TrimSpace(body)) == 0 { + return nil + } + return x.deliverJSON(body) + } +} + +// deliverJSON writes one upstream JSON message as a single stdout line. +func (x *exchange) deliverJSON(data []byte) error { + if !json.Valid(data) { + return errors.New("upstream sent invalid JSON") + } + if bytes.ContainsAny(data, "\r\n") { + var compact bytes.Buffer + if err := json.Compact(&compact, data); err != nil { + return err + } + data = compact.Bytes() + } + return x.deliver(data) +} + +// deliver applies the initialize edit and the hooks, then writes the resulting messages. +func (x *exchange) deliver(msg []byte) error { + var err error + if x.m.Method == "initialize" && (x.c.b.Instructions != "" || x.c.b.ForceListChanged) { + if msg, err = editInitialize(msg, x.c.b.Instructions, x.c.b.ForceListChanged); err != nil { + return err + } + } + msgs := [][]byte{msg} + if x.c.b.Hooks != nil { + if msgs, err = x.c.b.Hooks.Result(x.ctx, x.line, x.status, msg); err != nil { + return err + } + } + for _, out := range msgs { + if err := x.c.write(out); err != nil { + return err + } + } + x.sent++ + return nil +} + +// fail logs err and, for a request the client still waits on, answers it with a JSON-RPC error. +func (x *exchange) fail(err error) { + cause := context.Cause(x.ctx) + if errors.Is(cause, errIdleTimeout) { + err = cause + } + x.c.logf("upstream: %v", err) + cancelled := cause != nil && !errors.Is(cause, errIdleTimeout) + if cancelled || !x.m.isRequest() || x.sent > 0 { + return + } + msg := errorResponse(x.m.ID, codeUpstream, fmt.Sprintf("MCP upstream error for request %s: %v", x.m.ID, err)) + if derr := x.deliver(msg); derr != nil { + // The hook failed too; the client still needs an answer, so write the error unhooked. + x.c.logf("upstream: %v", derr) + x.c.reply(msg) + } +} diff --git a/libs/aitools/mcp/proxy/bridge_test.go b/libs/aitools/mcp/proxy/bridge_test.go new file mode 100644 index 00000000000..697d6a3feba --- /dev/null +++ b/libs/aitools/mcp/proxy/bridge_test.go @@ -0,0 +1,543 @@ +package proxy + +import ( + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "net/http/httptest" + "slices" + "strings" + "sync" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +const testToken = "Bearer test-token" + +// recorded is one upstream request as the fake endpoint received it. +type recorded struct { + Method string + Header http.Header + Body []byte +} + +// fakeEndpoint records every upstream request and answers it with handle. +type fakeEndpoint struct { + mu sync.Mutex + reqs []recorded +} + +// newFakeEndpoint starts an httptest server that records each request before calling handle. +func newFakeEndpoint(t *testing.T, handle http.HandlerFunc) (*httptest.Server, *fakeEndpoint) { + t.Helper() + f := &fakeEndpoint{} + srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + f.mu.Lock() + f.reqs = append(f.reqs, recorded{Method: r.Method, Header: r.Header.Clone(), Body: body}) + f.mu.Unlock() + r.Body = io.NopCloser(bytes.NewReader(body)) + handle(w, r) + })) + t.Cleanup(srv.Close) + return srv, f +} + +func (f *fakeEndpoint) requests() []recorded { + f.mu.Lock() + defer f.mu.Unlock() + return slices.Clone(f.reqs) +} + +// answer replies to a request with an empty result that carries its id. +func answer(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + w.Header().Set("Content-Type", "application/json") + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) +} + +// bridgeFor returns a Bridge that posts to url with a fixed bearer token. +func bridgeFor(url string) *Bridge { + return &Bridge{ + Endpoint: url, + Authenticate: func(r *http.Request) error { + r.Header.Set("Authorization", testToken) + return nil + }, + } +} + +// syncBuffer is a bytes.Buffer that is safe to read while a bridge writes to it. +type syncBuffer struct { + mu sync.Mutex + buf bytes.Buffer +} + +func (b *syncBuffer) Write(p []byte) (int, error) { + b.mu.Lock() + defer b.mu.Unlock() + return b.buf.Write(p) +} + +func (b *syncBuffer) String() string { + b.mu.Lock() + defer b.mu.Unlock() + return b.buf.String() +} + +// outLines splits bridge output into lines. +func outLines(s string) []string { + if s == "" { + return nil + } + return strings.Split(strings.TrimSuffix(s, "\n"), "\n") +} + +// runAll runs b to completion with input as stdin and returns the stdout lines and stderr. +func runAll(t *testing.T, b *Bridge, input string) ([]string, string) { + t.Helper() + var out, errOut syncBuffer + b.In, b.Out, b.Err = strings.NewReader(input), &out, &errOut + require.NoError(t, b.Run(t.Context())) + return outLines(out.String()), errOut.String() +} + +// piped is a bridge reading from a pipe, so a test can wait for each response before sending the next message. +type piped struct { + in *io.PipeWriter + out *syncBuffer + err *syncBuffer + done chan error +} + +func startPiped(t *testing.T, ctx context.Context, b *Bridge) *piped { + t.Helper() + pr, pw := io.Pipe() + t.Cleanup(func() { pw.Close() }) + p := &piped{in: pw, out: &syncBuffer{}, err: &syncBuffer{}, done: make(chan error, 1)} + b.In, b.Out, b.Err = pr, p.out, p.err + go func() { p.done <- b.Run(ctx) }() + return p +} + +func (p *piped) send(t *testing.T, line string) { + t.Helper() + _, err := io.WriteString(p.in, line+"\n") + require.NoError(t, err) +} + +// waitLines waits until stdout has at least n lines and returns them. +func (p *piped) waitLines(t *testing.T, n int) []string { + t.Helper() + require.Eventually(t, func() bool { return len(outLines(p.out.String())) >= n }, 10*time.Second, 5*time.Millisecond) + return outLines(p.out.String()) +} + +// finish closes stdin and returns the error from Run. +func (p *piped) finish(t *testing.T) error { + t.Helper() + require.NoError(t, p.in.Close()) + select { + case err := <-p.done: + return err + case <-time.After(10 * time.Second): + t.Fatal("Run did not return") + return nil + } +} + +// rpcReply is the part of a JSON-RPC response the tests check. +type rpcReply struct { + ID json.RawMessage `json:"id"` + Result map[string]any `json:"result"` + Error *rpcError `json:"error"` +} + +func parseReply(t *testing.T, line string) rpcReply { + t.Helper() + var r rpcReply + require.NoError(t, json.Unmarshal([]byte(line), &r), line) + return r +} + +func TestRunPassesUpstreamBodyThroughUnchanged(t *testing.T) { + const body = `{"jsonrpc": "2.0", "id": 1, "result": {"tools": [], "n": 1.50, "s": "a", wantError: "invalid JSON"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(tc.status) + _, _ = io.WriteString(w, tc.body) + }) + + out, errOut := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`+"\n") + + require.Len(t, out, 1) + if tc.wantPassing != "" { + assert.Equal(t, tc.wantPassing, out[0]) + return + } + reply := parseReply(t, out[0]) + assert.JSONEq(t, `1`, string(reply.ID)) + require.NotNil(t, reply.Error) + assert.Equal(t, codeUpstream, reply.Error.Code) + assert.Contains(t, reply.Error.Message, tc.wantError) + assert.Contains(t, errOut, "upstream") + }) + } +} + +func TestRunAnswersNetworkFailureWithJSONRPCError(t *testing.T) { + srv := httptest.NewServer(http.NotFoundHandler()) + url := srv.URL + srv.Close() + + out, _ := runAll(t, bridgeFor(url), `{"jsonrpc":"2.0","id":7,"method":"tools/list"}`+"\n") + + require.Len(t, out, 1) + reply := parseReply(t, out[0]) + assert.JSONEq(t, `7`, string(reply.ID)) + require.NotNil(t, reply.Error) + assert.Equal(t, codeUpstream, reply.Error.Code) + assert.Contains(t, reply.Error.Message, "request 7") +} + +func TestRunKeepsRunningAfterMalformedLine(t *testing.T) { + srv, _ := newFakeEndpoint(t, answer) + + out, errOut := runAll(t, bridgeFor(srv.URL), + "{not json\n"+`{"jsonrpc":"2.0","id":2,"method":"tools/list"}`+"\n") + + require.Len(t, out, 2) + parseErr := parseReply(t, out[0]) + assert.JSONEq(t, `null`, string(parseErr.ID)) + require.NotNil(t, parseErr.Error) + assert.Equal(t, codeParseError, parseErr.Error.Code) + assert.JSONEq(t, `2`, string(parseReply(t, out[1]).ID)) + assert.Contains(t, errOut, "invalid JSON on stdin") +} + +func TestRunForwardsLargeMessages(t *testing.T) { + const size = 8 << 20 + line := `{"jsonrpc":"2.0","id":1,"method":"echo","params":{"text":"` + strings.Repeat("a", size) + `"}}` + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + _, _ = io.Copy(w, r.Body) + }) + + out, _ := runAll(t, bridgeFor(srv.URL), line+"\n") + + assert.Equal(t, []string{line}, out) +} + +func TestRunHandlesRequestsConcurrently(t *testing.T) { + const n = 8 + var arrived sync.WaitGroup + arrived.Add(n) + allArrived := make(chan struct{}) + go func() { + arrived.Wait() + close(allArrived) + }() + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + arrived.Done() + select { + case <-allArrived: + case <-time.After(10 * time.Second): + w.WriteHeader(http.StatusInternalServerError) + return + } + answer(w, r) + }) + var input strings.Builder + for i := 1; i <= n; i++ { + fmt.Fprintf(&input, `{"jsonrpc":"2.0","id":%d,"method":"tools/call"}`+"\n", i) + } + + out, _ := runAll(t, bridgeFor(srv.URL), input.String()) + + require.Len(t, out, n) + seen := map[string]bool{} + for _, line := range out { + reply := parseReply(t, line) + assert.Nil(t, reply.Error) + seen[string(reply.ID)] = true + } + assert.Len(t, seen, n) +} + +func TestRunCancelsUpstreamRequestOnNotification(t *testing.T) { + cancelled := make(chan struct{}) + started := make(chan struct{}) + markStarted := sync.OnceFunc(func() { close(started) }) + markCancelled := sync.OnceFunc(func() { close(cancelled) }) + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + // The notification is also POSTed upstream, so only the first request blocks. + body, _ := io.ReadAll(r.Body) + if m, _ := parseMessage(body); m.Method != "tools/call" { + return + } + markStarted() + <-r.Context().Done() + markCancelled() + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, `{"jsonrpc":"2.0","id":7,"method":"tools/call"}`) + <-started + p.send(t, `{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":7,"reason":"user"}}`) + + select { + case <-cancelled: + case <-time.After(10 * time.Second): + t.Fatal("upstream request was not cancelled") + } + require.NoError(t, p.finish(t)) + assert.Empty(t, outLines(p.out.String()), "a cancelled request gets no response") +} + +func TestRunShutsDownOnEOFAndDeletesSession(t *testing.T) { + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Mcp-Session-Id", "s1") + answer(w, r) + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}`) + p.waitLines(t, 1) + require.NoError(t, p.finish(t)) + + reqs := fake.requests() + require.NotEmpty(t, reqs) + assert.Equal(t, http.MethodDelete, reqs[len(reqs)-1].Method) + assert.Equal(t, "s1", reqs[len(reqs)-1].Header.Get("Mcp-Session-Id")) +} + +func TestRunShutsDownOnContextCancelAndDeletesSession(t *testing.T) { + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + w.Header().Set("Mcp-Session-Id", "s1") + answer(w, r) + }) + ctx, cancel := context.WithCancel(t.Context()) + defer cancel() + p := startPiped(t, ctx, bridgeFor(srv.URL)) + + p.send(t, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}`) + p.waitLines(t, 1) + cancel() + + select { + case err := <-p.done: + require.NoError(t, err) + case <-time.After(10 * time.Second): + t.Fatal("Run did not return after cancel") + } + reqs := fake.requests() + require.NotEmpty(t, reqs) + assert.Equal(t, http.MethodDelete, reqs[len(reqs)-1].Method) + assert.Equal(t, "s1", reqs[len(reqs)-1].Header.Get("Mcp-Session-Id")) +} + +func TestRunCancelsInFlightRequestsAfterShutdownGrace(t *testing.T) { + cancelled := make(chan struct{}) + started := make(chan struct{}) + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + close(started) + <-r.Context().Done() + close(cancelled) + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, `{"jsonrpc":"2.0","id":1,"method":"tools/call"}`) + <-started + require.NoError(t, p.finish(t)) + + select { + case <-cancelled: + case <-time.After(10 * time.Second): + t.Fatal("in-flight request was not cancelled") + } + assert.Empty(t, outLines(p.out.String())) +} + +// hookFunc adapts a function to Hooks. +type hookFunc func(ctx context.Context, request []byte, status int, msg []byte) ([][]byte, error) + +func (f hookFunc) Result(ctx context.Context, request []byte, status int, msg []byte) ([][]byte, error) { + return f(ctx, request, status, msg) +} + +func TestRunHooksReplaceAndInjectMessages(t *testing.T) { + const request = `{"jsonrpc":"2.0","id":2,"method":"tools/list"}` + const synthetic = `{"jsonrpc":"2.0","id":2,"result":{"tools":[]}}` + const notification = `{"jsonrpc":"2.0","method":"notifications/tools/list_changed"}` + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + http.Error(w, "unauthorized", http.StatusUnauthorized) + }) + var gotRequest []byte + var gotStatus int + b := bridgeFor(srv.URL) + b.Hooks = hookFunc(func(_ context.Context, req []byte, status int, _ []byte) ([][]byte, error) { + gotRequest, gotStatus = req, status + return [][]byte{[]byte(synthetic), []byte(notification)}, nil + }) + + out, _ := runAll(t, b, request+"\n") + + assert.Equal(t, request, string(gotRequest)) + assert.Equal(t, http.StatusUnauthorized, gotStatus) + assert.Equal(t, []string{synthetic, notification}, out) +} + +func TestRunWritesHookErrorAsJSONRPCError(t *testing.T) { + srv, _ := newFakeEndpoint(t, answer) + b := bridgeFor(srv.URL) + b.Hooks = hookFunc(func(context.Context, []byte, int, []byte) ([][]byte, error) { + return nil, errors.New("hook failed") + }) + + out, errOut := runAll(t, b, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`+"\n") + + require.Len(t, out, 1) + reply := parseReply(t, out[0]) + require.NotNil(t, reply.Error) + assert.Contains(t, reply.Error.Message, "hook failed") + assert.Contains(t, errOut, "hook failed") +} diff --git a/libs/aitools/mcp/proxy/messages.go b/libs/aitools/mcp/proxy/messages.go new file mode 100644 index 00000000000..46723f55900 --- /dev/null +++ b/libs/aitools/mcp/proxy/messages.go @@ -0,0 +1,119 @@ +package proxy + +import ( + "encoding/json" + "fmt" +) + +// message is the part of a client JSON-RPC message the bridge reads. Params stay raw and are only +// decoded for the methods that need a field from them. +type message struct { + ID json.RawMessage `json:"id"` + Method string `json:"method"` + Params json.RawMessage `json:"params"` +} + +// rpcError is the error object of a JSON-RPC error response. +type rpcError struct { + Code int `json:"code"` + Message string `json:"message"` +} + +// rpcErrorResponse is a JSON-RPC error response. +type rpcErrorResponse struct { + JSONRPC string `json:"jsonrpc"` + ID json.RawMessage `json:"id"` + Error rpcError `json:"error"` +} + +// parseMessage decodes the envelope of one JSON-RPC message. +func parseMessage(line []byte) (message, error) { + var m message + err := json.Unmarshal(line, &m) + return m, err +} + +// isRequest reports whether m is a request, which expects a response, rather than a notification. +func (m message) isRequest() bool { + return m.Method != "" && len(m.ID) > 0 && string(m.ID) != "null" +} + +// errorResponse builds a JSON-RPC error response. A nil id is sent as null. +func errorResponse(id json.RawMessage, code int, text string) []byte { + if len(id) == 0 { + id = json.RawMessage("null") + } + // Cannot fail: the id came from a parsed message and the other fields are plain values. + b, _ := json.Marshal(rpcErrorResponse{JSONRPC: "2.0", ID: id, Error: rpcError{Code: code, Message: text}}) + return b +} + +// editInitialize appends instructions to the result's instructions and, when listChanged is set, sets +// capabilities.tools.listChanged. Other members are kept. A response without a result is returned unchanged. +func editInitialize(msg []byte, instructions string, listChanged bool) ([]byte, error) { + var env map[string]json.RawMessage + if err := json.Unmarshal(msg, &env); err != nil { + return nil, err + } + if _, ok := env["result"]; !ok { + return msg, nil + } + result, err := decodeObject(env["result"]) + if err != nil { + return nil, fmt.Errorf("initialize result: %w", err) + } + if instructions != "" { + var prev string + if err := json.Unmarshal(member(result, "instructions"), &prev); err != nil { + return nil, fmt.Errorf("initialize instructions: %w", err) + } + text := instructions + if prev != "" { + text = prev + "\n\n" + instructions + } + if result["instructions"], err = json.Marshal(text); err != nil { + return nil, err + } + } + if listChanged { + caps, err := decodeObject(member(result, "capabilities")) + if err != nil { + return nil, fmt.Errorf("initialize capabilities: %w", err) + } + tools, err := decodeObject(member(caps, "tools")) + if err != nil { + return nil, fmt.Errorf("initialize capabilities.tools: %w", err) + } + tools["listChanged"] = json.RawMessage("true") + if caps["tools"], err = json.Marshal(tools); err != nil { + return nil, err + } + if result["capabilities"], err = json.Marshal(caps); err != nil { + return nil, err + } + } + if env["result"], err = json.Marshal(result); err != nil { + return nil, err + } + return json.Marshal(env) +} + +// decodeObject decodes a JSON object into its raw members. null yields an empty object. +func decodeObject(raw json.RawMessage) (map[string]json.RawMessage, error) { + var obj map[string]json.RawMessage + if err := json.Unmarshal(raw, &obj); err != nil { + return nil, err + } + if obj == nil { + obj = map[string]json.RawMessage{} + } + return obj, nil +} + +// member returns obj[key], or null when the key is absent, so it can be decoded either way. +func member(obj map[string]json.RawMessage, key string) json.RawMessage { + if raw, ok := obj[key]; ok { + return raw + } + return json.RawMessage("null") +} diff --git a/libs/aitools/mcp/proxy/messages_test.go b/libs/aitools/mcp/proxy/messages_test.go new file mode 100644 index 00000000000..a24159d2d5b --- /dev/null +++ b/libs/aitools/mcp/proxy/messages_test.go @@ -0,0 +1,89 @@ +package proxy + +import ( + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestEditInitialize(t *testing.T) { + cases := []struct { + name string + msg string + instructions string + listChanged bool + want string + }{ + { + name: "instructions created when absent", + msg: `{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18"}}`, + instructions: "Bound.", + want: `{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18","instructions":"Bound."}}`, + }, + { + name: "instructions appended to existing text", + msg: `{"jsonrpc":"2.0","id":1,"result":{"instructions":"Base."}}`, + instructions: "Bound.", + want: `{"jsonrpc":"2.0","id":1,"result":{"instructions":"Base.\n\nBound."}}`, + }, + { + name: "listChanged set and capabilities kept", + msg: `{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":{"x":1},"resources":{}}}}`, + listChanged: true, + want: `{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"resources":{},"tools":{"listChanged":true,"x":1}}}}`, + }, + { + name: "capabilities null", + msg: `{"jsonrpc":"2.0","id":1,"result":{"capabilities":null}}`, + listChanged: true, + want: `{"jsonrpc":"2.0","id":1,"result":{"capabilities":{"tools":{"listChanged":true}}}}`, + }, + { + name: "error response unchanged", + msg: `{"jsonrpc":"2.0","id":1,"error":{"code":-32006,"message":"sign in"}}`, + instructions: "Bound.", + listChanged: true, + want: `{"jsonrpc":"2.0","id":1,"error":{"code":-32006,"message":"sign in"}}`, + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + got, err := editInitialize([]byte(tc.msg), tc.instructions, tc.listChanged) + require.NoError(t, err) + assert.JSONEq(t, tc.want, string(got)) + }) + } +} + +func TestEditInitializeRejectsNonObjectResult(t *testing.T) { + _, err := editInitialize([]byte(`{"jsonrpc":"2.0","id":1,"result":5}`), "Bound.", false) + require.Error(t, err) +} + +func TestErrorResponseWithoutIDUsesNull(t *testing.T) { + got := errorResponse(nil, codeParseError, "Parse error") + + assert.JSONEq(t, `{"jsonrpc":"2.0","id":null,"error":{"code":-32700,"message":"Parse error"}}`, string(got)) +} + +func TestMessageIsRequest(t *testing.T) { + cases := []struct { + name string + line string + want bool + }{ + {name: "request", line: `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`, want: true}, + {name: "string id", line: `{"jsonrpc":"2.0","id":"a","method":"tools/list"}`, want: true}, + {name: "notification", line: `{"jsonrpc":"2.0","method":"notifications/initialized"}`}, + {name: "null id", line: `{"jsonrpc":"2.0","id":null,"method":"tools/list"}`}, + {name: "client response", line: `{"jsonrpc":"2.0","id":1,"result":{}}`}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + m, err := parseMessage([]byte(tc.line)) + require.NoError(t, err) + assert.Equal(t, tc.want, m.isRequest()) + }) + } +} diff --git a/libs/aitools/mcp/proxy/sse.go b/libs/aitools/mcp/proxy/sse.go new file mode 100644 index 00000000000..e27ff93009b --- /dev/null +++ b/libs/aitools/mcp/proxy/sse.go @@ -0,0 +1,46 @@ +package proxy + +import ( + "bufio" + "bytes" + "io" +) + +// readEvents calls fn with the data of each event in a text/event-stream body, in order. Multi-line data +// is joined with newlines. An event left open at the end of the stream is still delivered. id, event +// and comment lines are ignored. +func readEvents(r io.Reader, fn func([]byte) error) error { + sc := bufio.NewScanner(r) + sc.Buffer(nil, maxLineBytes) + var data []byte + hasData := false + for sc.Scan() { + line := sc.Bytes() + if len(line) == 0 { + if hasData { + if err := fn(data); err != nil { + return err + } + data, hasData = nil, false + } + continue + } + field, value, _ := bytes.Cut(line, []byte{':'}) + if line[0] == ':' || string(field) != "data" { + continue + } + value = bytes.TrimPrefix(value, []byte{' '}) + if hasData { + data = append(data, '\n') + } + data = append(data, value...) + hasData = true + } + if err := sc.Err(); err != nil { + return err + } + if hasData { + return fn(data) + } + return nil +} diff --git a/libs/aitools/mcp/proxy/sse_test.go b/libs/aitools/mcp/proxy/sse_test.go new file mode 100644 index 00000000000..d08284a0253 --- /dev/null +++ b/libs/aitools/mcp/proxy/sse_test.go @@ -0,0 +1,35 @@ +package proxy + +import ( + "strings" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestReadEvents(t *testing.T) { + cases := []struct { + name string + stream string + want []string + }{ + {name: "two events", stream: "data: a\n\ndata: b\n\n", want: []string{"a", "b"}}, + {name: "multi-line data is joined", stream: "data: {\ndata: x}\n\n", want: []string{"{\nx}"}}, + {name: "comments and other fields ignored", stream: ": hi\nevent: message\nid: 3\ndata: 1\n\n", want: []string{"1"}}, + {name: "CRLF line endings", stream: "data: 1\r\n\r\ndata: 2\r\n\r\n", want: []string{"1", "2"}}, + {name: "event open at end of stream", stream: "data: 1\n\ndata: 2", want: []string{"1", "2"}}, + {name: "no data", stream: "event: x\n\n"}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + var got []string + err := readEvents(strings.NewReader(tc.stream), func(data []byte) error { + got = append(got, string(data)) + return nil + }) + require.NoError(t, err) + assert.Equal(t, tc.want, got) + }) + } +} From 166df3e7fb58e88e64c6dfcf69c7e5d0eb1e6680 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 22:27:18 +0000 Subject: [PATCH 2/7] Fix review findings in the aitools MCP bridge - A stream that ends, is cut, or idles after only notifications now answers the request with -32000. Only a response with the request's id counts as an answer. - A non-2xx body passes through only when it is the response to this request. Other bodies become "HTTP : ", with the message taken from a Databricks error body or a single-line excerpt. A failed notification writes nothing. - MCP-Protocol-Version is the version the server picked in the initialize result, not the one the client asked for. - Notifications and client responses are posted before the next stdin line is read, so notifications/initialized reaches the server before the requests after it. Requests stay concurrent. - A 404 for a request that carried Mcp-Session-Id starts a new session: the client's initialize and notifications/initialized are replayed silently, then the request is posted once more. - SSE events with empty data (the priming event) are skipped. - Hook output with line breaks is compacted, so every message stays on one stdout line. - The synthesized error reaches hooks with a context the idle timeout has not cancelled. A cancelled request is neither logged nor answered. - A stdin line over 64 MiB ends Run with the limit named. - Valid JSON that is not an object gets -32600 Invalid Request. - Contexts are passed as arguments, not stored in structs. Named constants replace repeated method and member names. Co-authored-by: Isaac --- libs/aitools/mcp/proxy/bridge.go | 368 +++++++++++++++++++------- libs/aitools/mcp/proxy/bridge_test.go | 353 ++++++++++++++++++++++-- libs/aitools/mcp/proxy/messages.go | 60 +++-- libs/aitools/mcp/proxy/sse.go | 27 +- libs/aitools/mcp/proxy/sse_test.go | 2 + 5 files changed, 665 insertions(+), 145 deletions(-) diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go index d6cc765005d..89bf6c2705f 100644 --- a/libs/aitools/mcp/proxy/bridge.go +++ b/libs/aitools/mcp/proxy/bridge.go @@ -4,6 +4,7 @@ package proxy import ( "bufio" "bytes" + "cmp" "context" "encoding/json" "errors" @@ -17,25 +18,29 @@ import ( ) const ( - logPrefix = "databricks aitools mcp serve: " - sessionHeader = "Mcp-Session-Id" - protocolHeader = "MCP-Protocol-Version" - acceptHeader = "application/json, text/event-stream" - eventStreamMIME = "text/event-stream" + logPrefix = "databricks aitools mcp serve: " + sessionHeader = "Mcp-Session-Id" + protocolHeader = "MCP-Protocol-Version" + contentTypeHeader = "Content-Type" + acceptHeader = "application/json, text/event-stream" + jsonMIME = "application/json" + eventStreamMIME = "text/event-stream" maxLineBytes = 64 << 20 connectTimeout = 10 * time.Second - idleTimeout = 10 * time.Minute - shutdownGrace = 2 * time.Second deleteTimeout = 5 * time.Second + excerptRunes = 200 - codeParseError = -32700 - codeInvalidParams = -32602 - codeUpstream = -32000 + codeParseError = -32700 + codeInvalidRequest = -32600 + codeUpstream = -32000 ) var ( - newline = []byte{'\n'} + newline = []byte{'\n'} + // idleTimeout and shutdownGrace are variables so tests can shorten them. + idleTimeout = 10 * time.Minute + shutdownGrace = 2 * time.Second errIdleTimeout = errors.New("no data from upstream for 10 minutes") errNoResponse = errors.New("upstream sent no response") ) @@ -74,7 +79,6 @@ func (b *Bridge) Run(ctx context.Context) error { c := &conn{ b: b, client: newClient(), - base: base, cancelBase: cancelBase, inflight: map[string]context.CancelFunc{}, } @@ -101,7 +105,13 @@ func (b *Bridge) Run(ctx context.Context) error { } return nil } - c.handle(line) + if posted := c.handle(base, line); posted != nil { + // Wait for the notification to be posted, but do not hold up shutdown. + select { + case <-posted: + case <-ctx.Done(): + } + } } } } @@ -121,7 +131,11 @@ func scanLines(in io.Reader, lines chan<- []byte, stop <-chan struct{}) error { return nil } } - return sc.Err() + err := sc.Err() + if errors.Is(err, bufio.ErrTooLong) { + return fmt.Errorf("a stdin message exceeds the 64 MiB limit: %w", err) + } + return err } // splitLines is bufio.ScanLines without dropping a trailing carriage return. @@ -135,20 +149,28 @@ func splitLines(data []byte, atEOF bool) (int, []byte, error) { return 0, nil, nil } +// clientMsg is a client message kept so it can be replayed. +type clientMsg struct { + line []byte + m message +} + // conn is the state of one Run. type conn struct { b *Bridge client *http.Client - base context.Context cancelBase context.CancelFunc wg sync.WaitGroup - ioMu sync.Mutex // serializes writes to Out and Err + ioMu sync.Mutex // serializes writes to Out and Err + rejoinMu sync.Mutex // allows one session restart at a time mu sync.Mutex // guards the fields below sessionID string protocolVersion string inflight map[string]context.CancelFunc + initialize clientMsg // the client's initialize, for replay + initialized clientMsg // the client's notifications/initialized, for replay } // newClient returns the upstream HTTP client: a 10 s connect timeout and the environment's proxy settings. @@ -158,72 +180,60 @@ func newClient() *http.Client { return &http.Client{Transport: t} } -// handle processes one stdin line. Upstream work runs in its own goroutine. -func (c *conn) handle(line []byte) { +// handle starts one stdin message. A request runs in its own goroutine, and handle returns nil. A +// notification or client response is posted before the next stdin line is read, so the server sees the +// client's messages in order (the lifecycle needs notifications/initialized before the first request). +// handle then returns a channel that closes when that exchange has finished. +func (c *conn) handle(base context.Context, line []byte) <-chan struct{} { m, err := parseMessage(line) if err != nil { - c.logf("invalid JSON on stdin: %v", err) - c.reply(errorResponse(nil, codeParseError, "Parse error")) - return + if json.Valid(line) { + c.logf("invalid JSON-RPC message on stdin: %v", err) + c.reply(errorResponse(m.ID, codeInvalidRequest, "Invalid Request")) + } else { + c.logf("invalid JSON on stdin: %v", err) + c.reply(errorResponse(nil, codeParseError, "Parse error")) + } + return nil } switch m.Method { - case "initialize": - var p struct { - ProtocolVersion string `json:"protocolVersion"` - } - if err := json.Unmarshal(m.Params, &p); err != nil { - c.reply(errorResponse(m.ID, codeInvalidParams, "Invalid params")) - return - } - c.setProtocol(p.ProtocolVersion) - case "notifications/cancelled": + case methodCancelled: c.cancelRequest(m.Params) + case methodInitialize, methodInitialized: + c.remember(m, line) } - ctx, cancel := context.WithCancel(c.base) - isRequest := m.isRequest() - key := string(m.ID) - if isRequest { - c.track(key, cancel) + ctx, cancel := context.WithCancel(base) + if !m.isRequest() { + done := make(chan struct{}) + c.wg.Go(func() { + defer close(done) + defer cancel() + c.forward(ctx, line, m) + }) + return done } + key := string(m.ID) + c.track(key, cancel) c.wg.Go(func() { defer cancel() - if isRequest { - defer c.untrack(key) - } + defer c.untrack(key) c.forward(ctx, line, m) }) + return nil } -// forward POSTs one client message exactly as received and writes what the upstream answers. +// forward POSTs one client message exactly as received and writes what the upstream answers. The idle +// watchdog covers every response, plain JSON included (SPEC 11.3). func (c *conn) forward(ctx context.Context, line []byte, m message) { ctx, cancel := context.WithCancelCause(ctx) defer cancel(nil) idle := time.AfterFunc(idleTimeout, func() { cancel(errIdleTimeout) }) defer idle.Stop() - x := &exchange{c: c, ctx: ctx, line: line, m: m} - protocol := "" - if m.Method != "initialize" { - protocol = c.protocol() - } - resp, err := c.post(ctx, line, protocol) - if err != nil { - x.fail(err) - return - } - defer resp.Body.Close() - x.status = resp.StatusCode - if sid := resp.Header.Get(sessionHeader); sid != "" { - c.setSession(sid) - } - resp.Body = idleBody{ReadCloser: resp.Body, idle: idle} - if err := x.read(resp); err != nil { - x.fail(err) - return - } - if x.sent == 0 && m.isRequest() { - x.fail(errNoResponse) + x := &exchange{c: c, line: line, m: m, idle: idle} + if err := x.send(ctx, true); err != nil { + x.fail(ctx, err) } } @@ -264,6 +274,7 @@ func (c *conn) deleteSession(ctx context.Context) { resp.Body.Close() } +// post sends one JSON-RPC message to the endpoint. func (c *conn) post(ctx context.Context, body []byte, protocol string) (*http.Response, error) { req, err := c.newRequest(ctx, http.MethodPost, body, protocol) if err != nil { @@ -288,7 +299,7 @@ func (c *conn) newRequest(ctx context.Context, method string, body []byte, proto } req.Header.Set("Accept", acceptHeader) if body != nil { - req.Header.Set("Content-Type", "application/json") + req.Header.Set(contentTypeHeader, jsonMIME) } if protocol != "" { req.Header.Set(protocolHeader, protocol) @@ -302,8 +313,16 @@ func (c *conn) newRequest(ctx context.Context, method string, body []byte, proto return req, nil } -// write sends one message to stdout as a single line. +// write sends one message to stdout as a single line. Upstream bodies and hook output may be +// pretty-printed, so a message with line breaks is compacted first. func (c *conn) write(msg []byte) error { + if bytes.ContainsAny(msg, "\r\n") { + var compact bytes.Buffer + if err := json.Compact(&compact, msg); err != nil { + return err + } + msg = compact.Bytes() + } c.ioMu.Lock() defer c.ioMu.Unlock() if _, err := c.b.Out.Write(msg); err != nil { @@ -320,43 +339,62 @@ func (c *conn) reply(msg []byte) { } } -// logf writes a diagnostic to stderr. +// logf writes a diagnostic to stderr. It does not use libs/log: stderr is the agent's server log, which +// users see, and it has no levels to filter by. func (c *conn) logf(format string, args ...any) { c.ioMu.Lock() defer c.ioMu.Unlock() fmt.Fprintf(c.b.Err, logPrefix+format+"\n", args...) } +// session returns the Mcp-Session-Id the server assigned, or "" when there is none. func (c *conn) session() string { c.mu.Lock() defer c.mu.Unlock() return c.sessionID } +// setSession records the Mcp-Session-Id to send on later requests. func (c *conn) setSession(id string) { c.mu.Lock() defer c.mu.Unlock() c.sessionID = id } +// protocol returns the MCP protocol version the server negotiated, or "" before initialize completes. func (c *conn) protocol() string { c.mu.Lock() defer c.mu.Unlock() return c.protocolVersion } +// setProtocol records the protocol version from the initialize result, to send on later requests. func (c *conn) setProtocol(version string) { c.mu.Lock() defer c.mu.Unlock() c.protocolVersion = version } +// remember keeps the client's initialize or notifications/initialized so it can be replayed if the server +// ends the session. +func (c *conn) remember(m message, line []byte) { + c.mu.Lock() + defer c.mu.Unlock() + if m.Method == methodInitialize { + c.initialize = clientMsg{line: line, m: m} + } else { + c.initialized = clientMsg{line: line, m: m} + } +} + +// track records the cancel function of an in-flight request, keyed by its id. func (c *conn) track(key string, cancel context.CancelFunc) { c.mu.Lock() defer c.mu.Unlock() c.inflight[key] = cancel } +// untrack removes a request that has finished. func (c *conn) untrack(key string) { c.mu.Lock() defer c.mu.Unlock() @@ -386,36 +424,111 @@ type idleBody struct { idle *time.Timer } +// Read reads from the response body and resets the idle timer. func (b idleBody) Read(p []byte) (int, error) { n, err := b.ReadCloser.Read(p) b.idle.Reset(idleTimeout) return n, err } -// exchange is one client request and the upstream messages answering it. +// exchange is one client message and the upstream messages answering it. type exchange struct { - c *conn - ctx context.Context - line []byte - m message - status int - sent int + c *conn + line []byte + m message + idle *time.Timer + silent bool // a replayed handshake: its answers stay inside the bridge + status int + answered bool // the upstream sent the response to m +} + +// protocol returns the MCP-Protocol-Version to send with this message. The initialize request carries none. +func (x *exchange) protocol() string { + if x.m.Method == methodInitialize { + return "" + } + return x.c.protocol() +} + +// send posts the message and writes its answer. A 404 for a request that carried a session id means the +// server ended the session. The client then starts a new one and posts the request once more (MCP spec +// 2025-11-25, Session Management). +func (x *exchange) send(ctx context.Context, retry bool) error { + stale := x.c.session() + resp, err := x.c.post(ctx, x.line, x.protocol()) + if err != nil { + return err + } + defer resp.Body.Close() + if resp.StatusCode == http.StatusNotFound && stale != "" && retry { + resp.Body.Close() + if err := x.rejoin(ctx, stale); err != nil { + return err + } + return x.send(ctx, false) + } + x.status = resp.StatusCode + if sid := resp.Header.Get(sessionHeader); sid != "" { + x.c.setSession(sid) + } + resp.Body = idleBody{ReadCloser: resp.Body, idle: x.idle} + if err := x.read(ctx, resp); err != nil { + return err + } + if x.m.isRequest() && !x.answered { + return errNoResponse + } + return nil +} + +// rejoin starts a new session after the server ended stale. The client's initialize and +// notifications/initialized are replayed silently, since the client already has their answers. The new +// session id and negotiated protocol version are what the replay leaves behind. One rejoin runs at a +// time, and a request that finds the session already replaced just retries. +func (x *exchange) rejoin(ctx context.Context, stale string) error { + c := x.c + c.rejoinMu.Lock() + defer c.rejoinMu.Unlock() + if c.session() != stale { + return nil + } + c.logf("the server ended the session; starting a new one") + c.setSession("") + c.mu.Lock() + init, initialized := c.initialize, c.initialized + c.mu.Unlock() + if init.line == nil { + return errors.New("the server ended the session, and no initialize request was sent to replay") + } + replay := []clientMsg{init} + if initialized.line != nil { + replay = append(replay, initialized) + } + for _, msg := range replay { + s := &exchange{c: c, line: msg.line, m: msg.m, idle: x.idle, silent: true} + if err := s.send(ctx, false); err != nil { + return fmt.Errorf("start a new session: %w", err) + } + } + return nil } // read delivers every message in an upstream response. -func (x *exchange) read(resp *http.Response) error { +func (x *exchange) read(ctx context.Context, resp *http.Response) error { switch { case resp.StatusCode/100 != 2: body, err := io.ReadAll(resp.Body) if err != nil { return err } - if json.Valid(body) { - return x.deliverJSON(body) + // Only the server's own answer to this request passes through, such as a -32006 under HTTP 401. + // Any other body is an HTTP failure, and its content reaches the client only in the error message. + if msg, err := parseMessage(body); err == nil && msg.isResponseTo(x.m) { + return x.deliverJSON(ctx, body) } - return fmt.Errorf("HTTP %d", resp.StatusCode) - case strings.HasPrefix(resp.Header.Get("Content-Type"), eventStreamMIME): - return readEvents(resp.Body, x.deliverJSON) + return httpError(resp.StatusCode, body) + case strings.HasPrefix(resp.Header.Get(contentTypeHeader), eventStreamMIME): + return readEvents(resp.Body, func(data []byte) error { return x.deliverJSON(ctx, data) }) default: body, err := io.ReadAll(resp.Body) if err != nil { @@ -424,36 +537,55 @@ func (x *exchange) read(resp *http.Response) error { if len(bytes.TrimSpace(body)) == 0 { return nil } - return x.deliverJSON(body) + return x.deliverJSON(ctx, body) } } -// deliverJSON writes one upstream JSON message as a single stdout line. -func (x *exchange) deliverJSON(data []byte) error { +// deliverJSON writes one upstream JSON message. A response to the request marks it answered once the +// message has been written. +func (x *exchange) deliverJSON(ctx context.Context, data []byte) error { if !json.Valid(data) { return errors.New("upstream sent invalid JSON") } - if bytes.ContainsAny(data, "\r\n") { - var compact bytes.Buffer - if err := json.Compact(&compact, data); err != nil { - return err + msg, err := parseMessage(data) + if err != nil { + return fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) + } + answer := msg.isResponseTo(x.m) + if answer && x.m.Method == methodInitialize && msg.Result != nil { + // The version the server chose governs the requests that follow, so record it before the answer is written. + var r struct { + ProtocolVersion string `json:"protocolVersion"` + } + if err := json.Unmarshal(msg.Result, &r); err != nil { + return fmt.Errorf("initialize result: %w", err) } - data = compact.Bytes() + x.c.setProtocol(r.ProtocolVersion) } - return x.deliver(data) + if err := x.deliver(ctx, data); err != nil { + return err + } + if answer { + x.answered = true + } + return nil } -// deliver applies the initialize edit and the hooks, then writes the resulting messages. -func (x *exchange) deliver(msg []byte) error { +// deliver applies the initialize edit and the hooks, then writes the resulting messages. A silent exchange +// writes nothing. +func (x *exchange) deliver(ctx context.Context, msg []byte) error { + if x.silent { + return nil + } var err error - if x.m.Method == "initialize" && (x.c.b.Instructions != "" || x.c.b.ForceListChanged) { + if x.m.Method == methodInitialize && (x.c.b.Instructions != "" || x.c.b.ForceListChanged) { if msg, err = editInitialize(msg, x.c.b.Instructions, x.c.b.ForceListChanged); err != nil { return err } } msgs := [][]byte{msg} if x.c.b.Hooks != nil { - if msgs, err = x.c.b.Hooks.Result(x.ctx, x.line, x.status, msg); err != nil { + if msgs, err = x.c.b.Hooks.Result(ctx, x.line, x.status, msg); err != nil { return err } } @@ -462,25 +594,63 @@ func (x *exchange) deliver(msg []byte) error { return err } } - x.sent++ return nil } -// fail logs err and, for a request the client still waits on, answers it with a JSON-RPC error. -func (x *exchange) fail(err error) { - cause := context.Cause(x.ctx) - if errors.Is(cause, errIdleTimeout) { +// fail logs err and, for a request the client still waits on, answers it with a JSON-RPC error. A request +// that the client or shutdown cancelled is neither logged nor answered. +func (x *exchange) fail(ctx context.Context, err error) { + cause := context.Cause(ctx) + switch { + case errors.Is(cause, errIdleTimeout): err = cause + case cause != nil: + return } x.c.logf("upstream: %v", err) - cancelled := cause != nil && !errors.Is(cause, errIdleTimeout) - if cancelled || !x.m.isRequest() || x.sent > 0 { + if !x.m.isRequest() || x.answered { return } msg := errorResponse(x.m.ID, codeUpstream, fmt.Sprintf("MCP upstream error for request %s: %v", x.m.ID, err)) - if derr := x.deliver(msg); derr != nil { + // The hooks see the error with a context that the idle timeout has not cancelled. + if derr := x.deliver(context.WithoutCancel(ctx), msg); derr != nil { // The hook failed too; the client still needs an answer, so write the error unhooked. x.c.logf("upstream: %v", derr) x.c.reply(msg) } } + +// httpError describes a non-2xx response: its status, then the message of a JSON error body or an +// excerpt of any other body. +func httpError(status int, body []byte) error { + if s := bodySummary(body); s != "" { + return fmt.Errorf("HTTP %d: %s", status, s) + } + return fmt.Errorf("HTTP %d", status) +} + +// bodySummary returns the message of a JSON error body, either a JSON-RPC error or a Databricks error_code +// body. Any other body gives a single-line excerpt. +func bodySummary(body []byte) string { + var e struct { + Message string `json:"message"` + Error struct { + Message string `json:"message"` + } `json:"error"` + } + if json.Unmarshal(body, &e) == nil { + if msg := cmp.Or(e.Message, e.Error.Message); msg != "" { + return msg + } + } + return excerpt(body) +} + +// excerpt returns body as a single line, cut to excerptRunes characters. +func excerpt(body []byte) string { + r := []rune(strings.Join(strings.Fields(string(body)), " ")) + if len(r) > excerptRunes { + return string(r[:excerptRunes]) + "..." + } + return string(r) +} diff --git a/libs/aitools/mcp/proxy/bridge_test.go b/libs/aitools/mcp/proxy/bridge_test.go index 697d6a3feba..c9116aafa3c 100644 --- a/libs/aitools/mcp/proxy/bridge_test.go +++ b/libs/aitools/mcp/proxy/bridge_test.go @@ -1,6 +1,7 @@ package proxy import ( + "bufio" "bytes" "context" "encoding/json" @@ -12,6 +13,7 @@ import ( "slices" "strings" "sync" + "sync/atomic" "testing" "time" @@ -21,6 +23,9 @@ import ( const testToken = "Bearer test-token" +// progressEvent is a server-to-client notification, which is not an answer to any request. +const progressEvent = `{"jsonrpc":"2.0","method":"notifications/progress","params":{"progress":1}}` + // recorded is one upstream request as the fake endpoint received it. type recorded struct { Method string @@ -75,6 +80,22 @@ func bridgeFor(url string) *Bridge { } } +// setIdleTimeout shortens the idle watchdog for one test. +func setIdleTimeout(t *testing.T, d time.Duration) { + t.Helper() + old := idleTimeout + idleTimeout = d + t.Cleanup(func() { idleTimeout = old }) +} + +// setShutdownGrace sets the shutdown grace period for one test. +func setShutdownGrace(t *testing.T, d time.Duration) { + t.Helper() + old := shutdownGrace + shutdownGrace = d + t.Cleanup(func() { shutdownGrace = old }) +} + // syncBuffer is a bytes.Buffer that is safe to read while a bridge writes to it. type syncBuffer struct { mu sync.Mutex @@ -101,9 +122,11 @@ func outLines(s string) []string { return strings.Split(strings.TrimSuffix(s, "\n"), "\n") } -// runAll runs b to completion with input as stdin and returns the stdout lines and stderr. +// runAll runs b to completion with input as stdin and returns the stdout lines and stderr. The grace period +// is long so that a slow upstream round trip still completes before shutdown cancels it. func runAll(t *testing.T, b *Bridge, input string) ([]string, string) { t.Helper() + setShutdownGrace(t, 30*time.Second) var out, errOut syncBuffer b.In, b.Out, b.Err = strings.NewReader(input), &out, &errOut require.NoError(t, b.Run(t.Context())) @@ -205,6 +228,19 @@ func TestRunWritesEachSSEEventAsOneLine(t *testing.T) { }, out) } +// TestRunSkipsSSEPrimingEvent covers the event with an id and empty data that a server sends first, so a +// client can resume (MCP spec 2025-11-25, Streamable HTTP, "Sending Messages to the Server"). +func TestRunSkipsSSEPrimingEvent(t *testing.T) { + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "text/event-stream") + _, _ = io.WriteString(w, "id: 0\ndata:\n\nid: 1\ndata: {\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{}}\n\n") + }) + + out, _ := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`+"\n") + + assert.Equal(t, []string{`{"jsonrpc":"2.0","id":2,"result":{}}`}, out) +} + func TestRunSendsNothingForAcceptedNotification(t *testing.T) { srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusAccepted) @@ -216,6 +252,34 @@ func TestRunSendsNothingForAcceptedNotification(t *testing.T) { assert.Empty(t, errOut) } +// TestRunPostsNotificationBeforeNextMessage: the server rejects tools/list until notifications/initialized +// has been fully handled, as servers that enforce the lifecycle do. +func TestRunPostsNotificationBeforeNextMessage(t *testing.T) { + var ready atomic.Bool + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + w.Header().Set("Content-Type", "application/json") + switch { + case m.Method == "notifications/initialized": + time.Sleep(100 * time.Millisecond) + ready.Store(true) + w.WriteHeader(http.StatusAccepted) + case !ready.Load(): + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"error":{"code":-32600,"message":"not initialized"}}`, m.ID) + default: + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"tools":[]}}`, m.ID) + } + }) + + out, _ := runAll(t, bridgeFor(srv.URL), + `{"jsonrpc":"2.0","method":"notifications/initialized"}`+"\n"+ + `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`+"\n") + + require.Len(t, out, 1) + assert.Nil(t, parseReply(t, out[0]).Error) +} + func TestRunForwardsSessionAndProtocolHeaders(t *testing.T) { srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { if r.Method == http.MethodDelete { @@ -223,14 +287,18 @@ func TestRunForwardsSessionAndProtocolHeaders(t *testing.T) { } body, _ := io.ReadAll(r.Body) m, _ := parseMessage(body) + w.Header().Set("Content-Type", "application/json") if m.Method == "initialize" { w.Header().Set("Mcp-Session-Id", "s1") + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"protocolVersion":"2025-06-18"}}`, m.ID) + return } - answer(w, r) + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) }) p := startPiped(t, t.Context(), bridgeFor(srv.URL)) - p.send(t, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}`) + // The client asks for a newer version than the server picks; later requests carry the server's choice. + p.send(t, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}`) p.waitLines(t, 1) p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) p.waitLines(t, 2) @@ -290,9 +358,27 @@ func TestRunAnswersFailedRequestsWithJSONRPCError(t *testing.T) { wantError string wantPassing string }{ - {name: "HTTP 500", status: http.StatusInternalServerError, body: "boom", wantError: "HTTP 500"}, - {name: "HTTP 401 without JSON", status: http.StatusUnauthorized, body: "unauthorized", wantError: "HTTP 401"}, + {name: "HTTP 500", status: http.StatusInternalServerError, body: "boom", wantError: "HTTP 500: boom"}, + {name: "HTTP 401 without JSON", status: http.StatusUnauthorized, body: "unauthorized", wantError: "HTTP 401: unauthorized"}, {name: "HTTP 401 with JSON-RPC body", status: http.StatusUnauthorized, body: passthrough, wantPassing: passthrough}, + { + name: "HTTP 500 with JSON-RPC error without id", + status: http.StatusInternalServerError, + body: `{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"bad request"}}`, + wantError: "HTTP 500: bad request", + }, + { + name: "Databricks error body", + status: http.StatusForbidden, + body: `{"error_code":"PERMISSION_DENIED","message":"User lacks access"}`, + wantError: "HTTP 403: User lacks access", + }, + { + name: "HTML body is excerpted on one line", + status: http.StatusForbidden, + body: "\n

Forbidden

\n", + wantError: "HTTP 403:

Forbidden

", + }, {name: "no response", status: http.StatusAccepted, wantError: "no response"}, {name: "invalid JSON", status: http.StatusOK, body: "", wantError: "invalid JSON"}, } @@ -316,24 +402,202 @@ func TestRunAnswersFailedRequestsWithJSONRPCError(t *testing.T) { require.NotNil(t, reply.Error) assert.Equal(t, codeUpstream, reply.Error.Code) assert.Contains(t, reply.Error.Message, tc.wantError) - assert.Contains(t, errOut, "upstream") + assert.Contains(t, errOut, tc.wantError) }) } } -func TestRunAnswersNetworkFailureWithJSONRPCError(t *testing.T) { - srv := httptest.NewServer(http.NotFoundHandler()) - url := srv.URL - srv.Close() +// TestRunWritesNothingForFailedNotification: a failed notification has no request to answer, and a JSON body +// on it is not forwarded as if it were a response. +func TestRunWritesNothingForFailedNotification(t *testing.T) { + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusInternalServerError) + _, _ = io.WriteString(w, `{"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"bad"}}`) + }) - out, _ := runAll(t, bridgeFor(url), `{"jsonrpc":"2.0","id":7,"method":"tools/list"}`+"\n") + out, errOut := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","method":"notifications/initialized"}`+"\n") - require.Len(t, out, 1) - reply := parseReply(t, out[0]) - assert.JSONEq(t, `7`, string(reply.ID)) + assert.Empty(t, out) + assert.Contains(t, errOut, "HTTP 500") +} + +// TestRunAnswersStreamEndingAfterNotification: a progress notification is not an answer, so the request +// still gets an error when the stream ends. +func TestRunAnswersStreamEndingAfterNotification(t *testing.T) { + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "text/event-stream") + _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") + }) + + out, _ := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":4,"method":"tools/call"}`+"\n") + + require.Len(t, out, 2) + assert.Equal(t, progressEvent, out[0]) + reply := parseReply(t, out[1]) + assert.JSONEq(t, `4`, string(reply.ID)) + require.NotNil(t, reply.Error) + assert.Equal(t, codeUpstream, reply.Error.Code) + assert.Contains(t, reply.Error.Message, "no response") +} + +// TestRunAnswersStreamIdleAfterNotification: the idle watchdog ends a stream that stops after a notification. +func TestRunAnswersStreamIdleAfterNotification(t *testing.T) { + setIdleTimeout(t, 100*time.Millisecond) + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "text/event-stream") + _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") + w.(http.Flusher).Flush() + <-r.Context().Done() + }) + + out, _ := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":4,"method":"tools/call"}`+"\n") + + require.Len(t, out, 2) + assert.Equal(t, progressEvent, out[0]) + reply := parseReply(t, out[1]) + assert.JSONEq(t, `4`, string(reply.ID)) + require.NotNil(t, reply.Error) + assert.Contains(t, reply.Error.Message, "no data from upstream") +} + +// TestRunAnswersBrokenStreamAfterNotification: a connection cut mid-stream after a notification is answered. +func TestRunAnswersBrokenStreamAfterNotification(t *testing.T) { + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "text/event-stream") + _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") + w.(http.Flusher).Flush() + panic(http.ErrAbortHandler) + }) + + out, _ := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":4,"method":"tools/call"}`+"\n") + + require.Len(t, out, 2) + reply := parseReply(t, out[1]) + assert.JSONEq(t, `4`, string(reply.ID)) + require.NotNil(t, reply.Error) + assert.Equal(t, codeUpstream, reply.Error.Code) +} + +// TestRunDeliversIdleErrorWithLiveContext: hooks see the synthesized error with a context the idle timeout +// did not cancel. +func TestRunDeliversIdleErrorWithLiveContext(t *testing.T) { + setIdleTimeout(t, 100*time.Millisecond) + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "text/event-stream") + _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") + w.(http.Flusher).Flush() + <-r.Context().Done() + }) + var mu sync.Mutex + var ctxErrs []error + b := bridgeFor(srv.URL) + b.Hooks = hookFunc(func(ctx context.Context, _ []byte, _ int, msg []byte) ([][]byte, error) { + mu.Lock() + defer mu.Unlock() + ctxErrs = append(ctxErrs, ctx.Err()) + return [][]byte{msg}, nil + }) + + out, _ := runAll(t, b, `{"jsonrpc":"2.0","id":5,"method":"tools/call"}`+"\n") + + require.Len(t, out, 2) + reply := parseReply(t, out[1]) + require.NotNil(t, reply.Error) + assert.Contains(t, reply.Error.Message, "no data from upstream") + mu.Lock() + defer mu.Unlock() + assert.Equal(t, []error{nil, nil}, ctxErrs) +} + +// expiringSession answers like a server whose first session has expired: tools/list gets 404 for session s1 +// (for every session when always is set), and each initialize starts the next session. +func expiringSession(t *testing.T, always bool) (*httptest.Server, *fakeEndpoint) { + t.Helper() + var mu sync.Mutex + starts := 0 + return newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + w.Header().Set("Content-Type", "application/json") + switch { + case m.Method == "initialize": + mu.Lock() + starts++ + sid := fmt.Sprintf("s%d", starts) + mu.Unlock() + w.Header().Set("Mcp-Session-Id", sid) + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"protocolVersion":"2025-06-18"}}`, m.ID) + case !m.isRequest(): + w.WriteHeader(http.StatusAccepted) + case m.Method == "tools/list" && (always || r.Header.Get(sessionHeader) == "s1"): + http.Error(w, "session not found", http.StatusNotFound) + default: + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"tools":[]}}`, m.ID) + } + }) +} + +// TestRunStartsNewSessionAfterSessionExpires: a 404 for a session the bridge had replays the client's +// initialize and notifications/initialized silently, then posts the request once more. +func TestRunStartsNewSessionAfterSessionExpires(t *testing.T) { + const initLine = `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}` + srv, fake := expiringSession(t, false) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initLine) + p.waitLines(t, 1) + p.send(t, `{"jsonrpc":"2.0","method":"notifications/initialized"}`) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + out := p.waitLines(t, 2) + require.NoError(t, p.finish(t)) + + require.Len(t, out, 2, "the replayed handshake writes nothing to stdout") + reply := parseReply(t, out[1]) + assert.JSONEq(t, `2`, string(reply.ID)) + assert.Nil(t, reply.Error) + + reqs := fake.requests() + require.Len(t, reqs, 7) + assert.Equal(t, "s1", reqs[2].Header.Get(sessionHeader), "the expired session was used first") + assert.Equal(t, initLine, string(reqs[3].Body), "the client's initialize is replayed as sent") + assert.Empty(t, reqs[3].Header.Get(sessionHeader)) + assert.Equal(t, "2025-06-18", reqs[4].Header.Get(protocolHeader), "the replayed handshake negotiates again") + assert.Equal(t, "s2", reqs[4].Header.Get(sessionHeader)) + assert.Equal(t, "s2", reqs[5].Header.Get(sessionHeader)) + assert.Equal(t, http.MethodDelete, reqs[6].Method) +} + +// TestRunAnswersRequestWhenNewSessionAlsoFails: the request is retried once, and an error that persists is +// answered with -32000. +func TestRunAnswersRequestWhenNewSessionAlsoFails(t *testing.T) { + srv, fake := expiringSession(t, true) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25"}}`) + p.waitLines(t, 1) + p.send(t, `{"jsonrpc":"2.0","method":"notifications/initialized"}`) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + out := p.waitLines(t, 2) + require.NoError(t, p.finish(t)) + + require.Len(t, out, 2) + reply := parseReply(t, out[1]) + assert.JSONEq(t, `2`, string(reply.ID)) require.NotNil(t, reply.Error) assert.Equal(t, codeUpstream, reply.Error.Code) - assert.Contains(t, reply.Error.Message, "request 7") + assert.Contains(t, reply.Error.Message, "HTTP 404") + + initializes := 0 + for _, r := range fake.requests() { + if strings.Contains(string(r.Body), `"method":"initialize"`) { + initializes++ + } + } + assert.Equal(t, 2, initializes, "the handshake is replayed once, not in a loop") } func TestRunKeepsRunningAfterMalformedLine(t *testing.T) { @@ -351,17 +615,51 @@ func TestRunKeepsRunningAfterMalformedLine(t *testing.T) { assert.Contains(t, errOut, "invalid JSON on stdin") } +// TestRunRejectsValidJSONThatIsNotAnObject: valid JSON that is not a message object is an invalid request, +// not a parse error. +func TestRunRejectsValidJSONThatIsNotAnObject(t *testing.T) { + srv, _ := newFakeEndpoint(t, answer) + + out, errOut := runAll(t, bridgeFor(srv.URL), "[1,2]\n5\nnull\n") + + require.Len(t, out, 3) + for _, line := range out { + reply := parseReply(t, line) + assert.JSONEq(t, `null`, string(reply.ID)) + require.NotNil(t, reply.Error) + assert.Equal(t, codeInvalidRequest, reply.Error.Code) + } + assert.Contains(t, errOut, "invalid JSON-RPC message on stdin") +} + +// TestRunReportsOversizedStdinMessage: a line over the limit ends the run with the limit named. +func TestRunReportsOversizedStdinMessage(t *testing.T) { + var out, errOut syncBuffer + b := bridgeFor("http://mcp.test/mcp") + b.In = strings.NewReader(strings.Repeat("a", maxLineBytes+1)) + b.Out, b.Err = &out, &errOut + + err := b.Run(t.Context()) + + require.ErrorIs(t, err, bufio.ErrTooLong) + assert.Contains(t, err.Error(), "64 MiB") +} + func TestRunForwardsLargeMessages(t *testing.T) { const size = 8 << 20 - line := `{"jsonrpc":"2.0","id":1,"method":"echo","params":{"text":"` + strings.Repeat("a", size) + `"}}` - srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + request := `{"jsonrpc":"2.0","id":1,"method":"echo","params":{"text":"` + strings.Repeat("a", size) + `"}}` + response := `{"jsonrpc":"2.0","id":1,"result":{"text":"` + strings.Repeat("b", size) + `"}}` + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "application/json") - _, _ = io.Copy(w, r.Body) + _, _ = io.WriteString(w, response) }) - out, _ := runAll(t, bridgeFor(srv.URL), line+"\n") + out, _ := runAll(t, bridgeFor(srv.URL), request+"\n") - assert.Equal(t, []string{line}, out) + reqs := fake.requests() + require.Len(t, reqs, 1) + assert.Equal(t, request, string(reqs[0].Body), "the request reaches the endpoint byte for byte") + assert.Equal(t, []string{response}, out, "the response reaches stdout byte for byte") } func TestRunHandlesRequestsConcurrently(t *testing.T) { @@ -428,6 +726,7 @@ func TestRunCancelsUpstreamRequestOnNotification(t *testing.T) { } require.NoError(t, p.finish(t)) assert.Empty(t, outLines(p.out.String()), "a cancelled request gets no response") + assert.NotContains(t, p.err.String(), "upstream", "a cancellation the client asked for is not an error") } func TestRunShutsDownOnEOFAndDeletesSession(t *testing.T) { @@ -476,6 +775,7 @@ func TestRunShutsDownOnContextCancelAndDeletesSession(t *testing.T) { } func TestRunCancelsInFlightRequestsAfterShutdownGrace(t *testing.T) { + setShutdownGrace(t, 100*time.Millisecond) cancelled := make(chan struct{}) started := make(chan struct{}) srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { @@ -526,6 +826,19 @@ func TestRunHooksReplaceAndInjectMessages(t *testing.T) { assert.Equal(t, []string{synthetic, notification}, out) } +// TestRunCompactsHookMessagesWithLineBreaks: a hook message with line breaks is still one stdout line. +func TestRunCompactsHookMessagesWithLineBreaks(t *testing.T) { + srv, _ := newFakeEndpoint(t, answer) + b := bridgeFor(srv.URL) + b.Hooks = hookFunc(func(context.Context, []byte, int, []byte) ([][]byte, error) { + return [][]byte{[]byte("{\n\"jsonrpc\": \"2.0\",\n\"id\": 3,\n\"result\": {}}")}, nil + }) + + out, _ := runAll(t, b, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`+"\n") + + assert.Equal(t, []string{`{"jsonrpc":"2.0","id":3,"result":{}}`}, out) +} + func TestRunWritesHookErrorAsJSONRPCError(t *testing.T) { srv, _ := newFakeEndpoint(t, answer) b := bridgeFor(srv.URL) diff --git a/libs/aitools/mcp/proxy/messages.go b/libs/aitools/mcp/proxy/messages.go index 46723f55900..8c964ff144c 100644 --- a/libs/aitools/mcp/proxy/messages.go +++ b/libs/aitools/mcp/proxy/messages.go @@ -1,16 +1,35 @@ package proxy import ( + "bytes" "encoding/json" + "errors" "fmt" ) -// message is the part of a client JSON-RPC message the bridge reads. Params stay raw and are only -// decoded for the methods that need a field from them. +// Method names and member names the bridge reads or edits. +const ( + methodInitialize = "initialize" + methodInitialized = "notifications/initialized" + methodCancelled = "notifications/cancelled" + + keyResult = "result" + keyInstructions = "instructions" + keyCapabilities = "capabilities" + keyTools = "tools" + keyListChanged = "listChanged" +) + +// errNotObject is returned for valid JSON whose top-level value is not an object. +var errNotObject = errors.New("message is not a JSON object") + +// message is the part of a JSON-RPC message the bridge reads, from either side. Params and Result stay raw +// and are only decoded for the methods that need a field from them. type message struct { ID json.RawMessage `json:"id"` Method string `json:"method"` Params json.RawMessage `json:"params"` + Result json.RawMessage `json:"result"` } // rpcError is the error object of a JSON-RPC error response. @@ -26,11 +45,17 @@ type rpcErrorResponse struct { Error rpcError `json:"error"` } -// parseMessage decodes the envelope of one JSON-RPC message. +// parseMessage decodes the envelope of one JSON-RPC message. It fails for input that is not a JSON object. func parseMessage(line []byte) (message, error) { var m message - err := json.Unmarshal(line, &m) - return m, err + if err := json.Unmarshal(line, &m); err != nil { + return m, err + } + // json.Unmarshal accepts null and leaves m empty, so check the first byte. + if !bytes.HasPrefix(bytes.TrimSpace(line), []byte{'{'}) { + return m, errNotObject + } + return m, nil } // isRequest reports whether m is a request, which expects a response, rather than a notification. @@ -38,6 +63,11 @@ func (m message) isRequest() bool { return m.Method != "" && len(m.ID) > 0 && string(m.ID) != "null" } +// isResponseTo reports whether m is a JSON-RPC response to request. Only a request can have one. +func (m message) isResponseTo(request message) bool { + return request.isRequest() && m.Method == "" && bytes.Equal(m.ID, request.ID) +} + // errorResponse builds a JSON-RPC error response. A nil id is sent as null. func errorResponse(id json.RawMessage, code int, text string) []byte { if len(id) == 0 { @@ -55,44 +85,44 @@ func editInitialize(msg []byte, instructions string, listChanged bool) ([]byte, if err := json.Unmarshal(msg, &env); err != nil { return nil, err } - if _, ok := env["result"]; !ok { + if _, ok := env[keyResult]; !ok { return msg, nil } - result, err := decodeObject(env["result"]) + result, err := decodeObject(env[keyResult]) if err != nil { return nil, fmt.Errorf("initialize result: %w", err) } if instructions != "" { var prev string - if err := json.Unmarshal(member(result, "instructions"), &prev); err != nil { + if err := json.Unmarshal(member(result, keyInstructions), &prev); err != nil { return nil, fmt.Errorf("initialize instructions: %w", err) } text := instructions if prev != "" { text = prev + "\n\n" + instructions } - if result["instructions"], err = json.Marshal(text); err != nil { + if result[keyInstructions], err = json.Marshal(text); err != nil { return nil, err } } if listChanged { - caps, err := decodeObject(member(result, "capabilities")) + caps, err := decodeObject(member(result, keyCapabilities)) if err != nil { return nil, fmt.Errorf("initialize capabilities: %w", err) } - tools, err := decodeObject(member(caps, "tools")) + tools, err := decodeObject(member(caps, keyTools)) if err != nil { return nil, fmt.Errorf("initialize capabilities.tools: %w", err) } - tools["listChanged"] = json.RawMessage("true") - if caps["tools"], err = json.Marshal(tools); err != nil { + tools[keyListChanged] = json.RawMessage("true") + if caps[keyTools], err = json.Marshal(tools); err != nil { return nil, err } - if result["capabilities"], err = json.Marshal(caps); err != nil { + if result[keyCapabilities], err = json.Marshal(caps); err != nil { return nil, err } } - if env["result"], err = json.Marshal(result); err != nil { + if env[keyResult], err = json.Marshal(result); err != nil { return nil, err } return json.Marshal(env) diff --git a/libs/aitools/mcp/proxy/sse.go b/libs/aitools/mcp/proxy/sse.go index e27ff93009b..fcabb6be432 100644 --- a/libs/aitools/mcp/proxy/sse.go +++ b/libs/aitools/mcp/proxy/sse.go @@ -7,21 +7,29 @@ import ( ) // readEvents calls fn with the data of each event in a text/event-stream body, in order. Multi-line data -// is joined with newlines. An event left open at the end of the stream is still delivered. id, event -// and comment lines are ignored. +// is joined with newlines. An event left open at the end of the stream is still delivered. An event whose +// data is empty is skipped: a server sends one with an id and no data first, to prime a client to resume +// (MCP spec 2025-11-25, Streamable HTTP, "Sending Messages to the Server"). id, event and comment lines are +// ignored. func readEvents(r io.Reader, fn func([]byte) error) error { sc := bufio.NewScanner(r) sc.Buffer(nil, maxLineBytes) var data []byte hasData := false + dispatch := func() error { + if len(bytes.TrimSpace(data)) == 0 { + data, hasData = nil, false + return nil + } + err := fn(data) + data, hasData = nil, false + return err + } for sc.Scan() { line := sc.Bytes() if len(line) == 0 { - if hasData { - if err := fn(data); err != nil { - return err - } - data, hasData = nil, false + if err := dispatch(); err != nil { + return err } continue } @@ -39,8 +47,5 @@ func readEvents(r io.Reader, fn func([]byte) error) error { if err := sc.Err(); err != nil { return err } - if hasData { - return fn(data) - } - return nil + return dispatch() } diff --git a/libs/aitools/mcp/proxy/sse_test.go b/libs/aitools/mcp/proxy/sse_test.go index d08284a0253..450b63119cf 100644 --- a/libs/aitools/mcp/proxy/sse_test.go +++ b/libs/aitools/mcp/proxy/sse_test.go @@ -20,6 +20,8 @@ func TestReadEvents(t *testing.T) { {name: "CRLF line endings", stream: "data: 1\r\n\r\ndata: 2\r\n\r\n", want: []string{"1", "2"}}, {name: "event open at end of stream", stream: "data: 1\n\ndata: 2", want: []string{"1", "2"}}, {name: "no data", stream: "event: x\n\n"}, + {name: "event with empty data is skipped", stream: "id: 1\ndata:\n\nid: 2\ndata: 2\n\n", want: []string{"2"}}, + {name: "empty data at end of stream is skipped", stream: "data: 1\n\nid: 2\ndata:", want: []string{"1"}}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { From e5304ea3427243516f615beefab69a79ea85f502 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 22:55:16 +0000 Subject: [PATCH 3/7] Fix review findings in the MCP stdio bridge (pass 2) A session restart no longer clears the session before its replay. The session and protocol version a replay negotiates are published only when the whole replay succeeds, so a failed replay is retried on the next 404. Requests read the session once per send, and a request that hits an ended session waits for the rejoin. A 404 is treated as an ended session only when its body is not the server's response to the request. Responses are matched by the decoded value of the id, and the response stream is closed once the response is written. Notifications are posted in order, but stdin is no longer blocked on them: a request waits at most notificationWait for the notification before it. Stdin EOF and cancellation are seen while a notification is pending. The idle error reaches hooks with a context that the idle timeout does not cancel. A 2xx JSON body that is not the response to the request fails the request, and a notification's JSON body is not written. Co-authored-by: Isaac --- libs/aitools/mcp/proxy/bridge.go | 425 ++++++++++------- libs/aitools/mcp/proxy/bridge_test.go | 584 +++++++++++++++++++++--- libs/aitools/mcp/proxy/messages.go | 57 ++- libs/aitools/mcp/proxy/messages_test.go | 30 ++ libs/aitools/mcp/proxy/sse.go | 61 ++- libs/aitools/mcp/proxy/sse_test.go | 15 +- 6 files changed, 887 insertions(+), 285 deletions(-) diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go index 89bf6c2705f..47b90dbf509 100644 --- a/libs/aitools/mcp/proxy/bridge.go +++ b/libs/aitools/mcp/proxy/bridge.go @@ -38,11 +38,15 @@ const ( var ( newline = []byte{'\n'} - // idleTimeout and shutdownGrace are variables so tests can shorten them. - idleTimeout = 10 * time.Minute - shutdownGrace = 2 * time.Second - errIdleTimeout = errors.New("no data from upstream for 10 minutes") - errNoResponse = errors.New("upstream sent no response") + // The idle timeout, shutdown grace and notification wait are variables so tests can shorten them. + idleTimeout = 10 * time.Minute + // shutdownGrace is how long shutdown waits for in-flight requests before it cancels them. + shutdownGrace = 2 * time.Second + // notificationWait is how long a request waits for the notification before it, so that a stalled + // notification does not hold up later messages. + notificationWait = 2 * time.Second + errIdleTimeout = errors.New("upstream idle") + errNoResponse = errors.New("upstream sent no response") ) // Hooks intercepts upstream messages before they are written to stdout. @@ -92,6 +96,8 @@ func (b *Bridge) Run(ctx context.Context) error { readErr = scanLines(b.In, lines, stop) }() + // gate closes when the latest notification has been posted. Stdin is never blocked on it. + var gate <-chan struct{} for { select { case <-ctx.Done(): @@ -105,13 +111,13 @@ func (b *Bridge) Run(ctx context.Context) error { } return nil } - if posted := c.handle(base, line); posted != nil { - // Wait for the notification to be posted, but do not hold up shutdown. - select { - case <-posted: - case <-ctx.Done(): - } + // select picks at random when several cases are ready, so a line read after ctx is cancelled is + // not handled. + if ctx.Err() != nil { + c.shutdown(ctx) + return nil } + gate = c.handle(base, gate, line) } } } @@ -155,6 +161,12 @@ type clientMsg struct { m message } +// upstreamState is the session and protocol version that requests are sent with. +type upstreamState struct { + id string // Mcp-Session-Id, "" when the server has none + protocol string // the version the server negotiated, "" before initialize completes +} + // conn is the state of one Run. type conn struct { b *Bridge @@ -165,12 +177,11 @@ type conn struct { ioMu sync.Mutex // serializes writes to Out and Err rejoinMu sync.Mutex // allows one session restart at a time - mu sync.Mutex // guards the fields below - sessionID string - protocolVersion string - inflight map[string]context.CancelFunc - initialize clientMsg // the client's initialize, for replay - initialized clientMsg // the client's notifications/initialized, for replay + mu sync.Mutex // guards the fields below + state upstreamState + inflight map[string]context.CancelFunc + initialize clientMsg // the client's initialize, for replay + initialized clientMsg // the client's notifications/initialized, for replay } // newClient returns the upstream HTTP client: a 10 s connect timeout and the environment's proxy settings. @@ -180,60 +191,75 @@ func newClient() *http.Client { return &http.Client{Transport: t} } -// handle starts one stdin message. A request runs in its own goroutine, and handle returns nil. A -// notification or client response is posted before the next stdin line is read, so the server sees the -// client's messages in order (the lifecycle needs notifications/initialized before the first request). -// handle then returns a channel that closes when that exchange has finished. -func (c *conn) handle(base context.Context, line []byte) <-chan struct{} { +// handle starts one stdin message and returns the gate for the next one. A request or notification runs in +// its own goroutine. Each message waits for the notification before it (see await), so the server sees +// notifications in order: the lifecycle needs notifications/initialized before the first request. A +// notification's gate is the channel that closes when its POST has finished. +func (c *conn) handle(base context.Context, gate <-chan struct{}, line []byte) <-chan struct{} { m, err := parseMessage(line) if err != nil { - if json.Valid(line) { - c.logf("invalid JSON-RPC message on stdin: %v", err) - c.reply(errorResponse(m.ID, codeInvalidRequest, "Invalid Request")) - } else { + if _, ok := errors.AsType[*json.SyntaxError](err); ok { c.logf("invalid JSON on stdin: %v", err) c.reply(errorResponse(nil, codeParseError, "Parse error")) + } else { + c.logf("invalid JSON-RPC message on stdin: %v", err) + c.reply(errorResponse(m.ID, codeInvalidRequest, "Invalid Request")) } - return nil + return gate } switch m.Method { case methodCancelled: - c.cancelRequest(m.Params) + c.cancelRequest(line) case methodInitialize, methodInitialized: c.remember(m, line) } ctx, cancel := context.WithCancel(base) - if !m.isRequest() { - done := make(chan struct{}) + if m.isRequest() { + key := idKey(m.ID) + c.track(key, cancel) c.wg.Go(func() { - defer close(done) defer cancel() - c.forward(ctx, line, m) + defer c.untrack(key) + c.forward(ctx, gate, line, m) }) - return done + return gate } - key := string(m.ID) - c.track(key, cancel) + done := make(chan struct{}) c.wg.Go(func() { + defer close(done) defer cancel() - defer c.untrack(key) - c.forward(ctx, line, m) + c.forward(ctx, gate, line, m) }) - return nil + return done } -// forward POSTs one client message exactly as received and writes what the upstream answers. The idle -// watchdog covers every response, plain JSON included (SPEC 11.3). -func (c *conn) forward(ctx context.Context, line []byte, m message) { - ctx, cancel := context.WithCancelCause(ctx) +// await waits for gate to close, but for at most notificationWait. A nil gate has nothing to wait for. +func await(ctx context.Context, gate <-chan struct{}) { + if gate == nil { + return + } + t := time.NewTimer(notificationWait) + defer t.Stop() + select { + case <-gate: + case <-t.C: + case <-ctx.Done(): + } +} + +// forward waits (see await), then POSTs one client message exactly as received and writes what the upstream +// answers. The idle watchdog covers every response, plain JSON included. +func (c *conn) forward(ctx context.Context, gate <-chan struct{}, line []byte, m message) { + await(ctx, gate) + idleCtx, cancel := context.WithCancelCause(ctx) defer cancel(nil) idle := time.AfterFunc(idleTimeout, func() { cancel(errIdleTimeout) }) defer idle.Stop() - x := &exchange{c: c, line: line, m: m, idle: idle} - if err := x.send(ctx, true); err != nil { - x.fail(ctx, err) + x := &exchange{c: c, line: line, m: m, req: ctx, idle: idle} + if err := x.send(idleCtx, true); err != nil { + x.fail(idleCtx, err) } } @@ -256,12 +282,13 @@ func (c *conn) shutdown(ctx context.Context) { // deleteSession ends the server-side session, best effort. func (c *conn) deleteSession(ctx context.Context) { - if c.session() == "" { + sent := c.current() + if sent.id == "" { return } ctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), deleteTimeout) defer cancel() - req, err := c.newRequest(ctx, http.MethodDelete, nil, c.protocol()) + req, err := c.newRequest(ctx, http.MethodDelete, nil, sent) if err != nil { c.logf("session DELETE: %v", err) return @@ -275,17 +302,17 @@ func (c *conn) deleteSession(ctx context.Context) { } // post sends one JSON-RPC message to the endpoint. -func (c *conn) post(ctx context.Context, body []byte, protocol string) (*http.Response, error) { - req, err := c.newRequest(ctx, http.MethodPost, body, protocol) +func (c *conn) post(ctx context.Context, body []byte, sent upstreamState) (*http.Response, error) { + req, err := c.newRequest(ctx, http.MethodPost, body, sent) if err != nil { return nil, err } return c.client.Do(req) } -// newRequest builds an upstream request with the configured headers, the session and protocol headers, -// and the authorization set by Authenticate. A nil body means no Content-Type. -func (c *conn) newRequest(ctx context.Context, method string, body []byte, protocol string) (*http.Request, error) { +// newRequest builds an upstream request with the configured headers, the session and protocol headers from +// sent, and the authorization set by Authenticate. A nil body means no Content-Type. +func (c *conn) newRequest(ctx context.Context, method string, body []byte, sent upstreamState) (*http.Request, error) { var r io.Reader if body != nil { r = bytes.NewReader(body) @@ -301,11 +328,11 @@ func (c *conn) newRequest(ctx context.Context, method string, body []byte, proto if body != nil { req.Header.Set(contentTypeHeader, jsonMIME) } - if protocol != "" { - req.Header.Set(protocolHeader, protocol) + if sent.protocol != "" { + req.Header.Set(protocolHeader, sent.protocol) } - if sid := c.session(); sid != "" { - req.Header.Set(sessionHeader, sid) + if sent.id != "" { + req.Header.Set(sessionHeader, sent.id) } if err := c.b.Authenticate(req); err != nil { return nil, err @@ -339,40 +366,40 @@ func (c *conn) reply(msg []byte) { } } -// logf writes a diagnostic to stderr. It does not use libs/log: stderr is the agent's server log, which -// users see, and it has no levels to filter by. +// logf writes a diagnostic to stderr. It does not use libs/log: the agent shows the server's stderr to the +// user, so these lines are always written. func (c *conn) logf(format string, args ...any) { c.ioMu.Lock() defer c.ioMu.Unlock() fmt.Fprintf(c.b.Err, logPrefix+format+"\n", args...) } -// session returns the Mcp-Session-Id the server assigned, or "" when there is none. -func (c *conn) session() string { +// current returns the session and protocol version that requests are sent with. +func (c *conn) current() upstreamState { c.mu.Lock() defer c.mu.Unlock() - return c.sessionID + return c.state } // setSession records the Mcp-Session-Id to send on later requests. func (c *conn) setSession(id string) { c.mu.Lock() defer c.mu.Unlock() - c.sessionID = id + c.state.id = id } -// protocol returns the MCP protocol version the server negotiated, or "" before initialize completes. -func (c *conn) protocol() string { +// setProtocol records the protocol version from the initialize result, to send on later requests. +func (c *conn) setProtocol(version string) { c.mu.Lock() defer c.mu.Unlock() - return c.protocolVersion + c.state.protocol = version } -// setProtocol records the protocol version from the initialize result, to send on later requests. -func (c *conn) setProtocol(version string) { +// publish replaces the session and protocol version with those of a replay that has finished. +func (c *conn) publish(s upstreamState) { c.mu.Lock() defer c.mu.Unlock() - c.protocolVersion = version + c.state = s } // remember keeps the client's initialize or notifications/initialized so it can be replayed if the server @@ -401,17 +428,19 @@ func (c *conn) untrack(key string) { delete(c.inflight, key) } -// cancelRequest cancels the in-flight request named by a notifications/cancelled params.requestId. -func (c *conn) cancelRequest(params json.RawMessage) { - var p struct { - RequestID json.RawMessage `json:"requestId"` +// cancelRequest cancels the in-flight request named by the requestId of a notifications/cancelled. +func (c *conn) cancelRequest(line []byte) { + var n struct { + Params struct { + RequestID json.RawMessage `json:"requestId"` + } `json:"params"` } - if err := json.Unmarshal(params, &p); err != nil { + if err := json.Unmarshal(line, &n); err != nil { c.logf("notifications/cancelled: %v", err) return } c.mu.Lock() - cancel := c.inflight[string(p.RequestID)] + cancel := c.inflight[idKey(n.Params.RequestID)] c.mu.Unlock() if cancel != nil { cancel() @@ -433,46 +462,79 @@ func (b idleBody) Read(p []byte) (int, error) { // exchange is one client message and the upstream messages answering it. type exchange struct { - c *conn - line []byte - m message - idle *time.Timer - silent bool // a replayed handshake: its answers stay inside the bridge + c *conn + line []byte + m message + // req is the request's context. Hooks get it, so an idle timeout does not cancel them, while shutdown + // and the client still do. + req context.Context + idle *time.Timer + replay *upstreamState // set for a replayed handshake: its session and protocol stay here until the replay ends + status int answered bool // the upstream sent the response to m } -// protocol returns the MCP-Protocol-Version to send with this message. The initialize request carries none. -func (x *exchange) protocol() string { - if x.m.Method == methodInitialize { - return "" +// sending returns the session and protocol version to send with x. An initialize request starts a session, +// so it carries neither (MCP transports, Session Management: +// https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management). +func (x *exchange) sending() upstreamState { + switch { + case x.m.Method == methodInitialize: + return upstreamState{} + case x.replay != nil: + return *x.replay + } + return x.c.current() +} + +// recordSession keeps the Mcp-Session-Id of a successful response. A replay keeps it until it ends. +func (x *exchange) recordSession(id string) { + switch { + case id == "": + case x.replay != nil: + x.replay.id = id + default: + x.c.setSession(id) + } +} + +// recordProtocol keeps the protocol version from an initialize result, before the result is written. +// The version the server chose governs the requests that follow. +func (x *exchange) recordProtocol(data []byte) error { + var r struct { + Result *struct { + ProtocolVersion string `json:"protocolVersion"` + } `json:"result"` } - return x.c.protocol() + if err := json.Unmarshal(data, &r); err != nil { + return fmt.Errorf("initialize result: %w", err) + } + switch { + case r.Result == nil: + case x.replay != nil: + x.replay.protocol = r.Result.ProtocolVersion + default: + x.c.setProtocol(r.Result.ProtocolVersion) + } + return nil } -// send posts the message and writes its answer. A 404 for a request that carried a session id means the -// server ended the session. The client then starts a new one and posts the request once more (MCP spec -// 2025-11-25, Session Management). +// send posts the message and writes its answer. func (x *exchange) send(ctx context.Context, retry bool) error { - stale := x.c.session() - resp, err := x.c.post(ctx, x.line, x.protocol()) + sent := x.sending() + resp, err := x.c.post(ctx, x.line, sent) if err != nil { return err } defer resp.Body.Close() - if resp.StatusCode == http.StatusNotFound && stale != "" && retry { - resp.Body.Close() - if err := x.rejoin(ctx, stale); err != nil { - return err - } - return x.send(ctx, false) - } + resp.Body = idleBody{ReadCloser: resp.Body, idle: x.idle} x.status = resp.StatusCode - if sid := resp.Header.Get(sessionHeader); sid != "" { - x.c.setSession(sid) + if resp.StatusCode/100 != 2 { + return x.httpFailure(ctx, resp, sent.id, retry) } - resp.Body = idleBody{ReadCloser: resp.Body, idle: x.idle} - if err := x.read(ctx, resp); err != nil { + x.recordSession(resp.Header.Get(sessionHeader)) + if err := x.read(resp); err != nil { return err } if x.m.isRequest() && !x.answered { @@ -481,19 +543,41 @@ func (x *exchange) send(ctx context.Context, retry bool) error { return nil } +// httpFailure handles a non-2xx response. A body that is the server's response to x.m passes through, as +// the server sent it. Otherwise a 404 for a request that carried a session id means the server ended the +// session: the client starts a new one and posts the request once more. That rule does not apply when the +// 404 body answers the request. See https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management. +func (x *exchange) httpFailure(ctx context.Context, resp *http.Response, sent string, retry bool) error { + body, err := io.ReadAll(resp.Body) + if err != nil { + return err + } + e := decodeErrorBody(body) + if e != nil && e.isResponseTo(x.m) { + return x.deliverMessage(body, e.message) + } + if resp.StatusCode == http.StatusNotFound && sent != "" && retry { + if err := x.rejoin(ctx, sent); err != nil { + return err + } + return x.send(ctx, false) + } + return httpError(resp.StatusCode, body, e) +} + // rejoin starts a new session after the server ended stale. The client's initialize and // notifications/initialized are replayed silently, since the client already has their answers. The new -// session id and negotiated protocol version are what the replay leaves behind. One rejoin runs at a -// time, and a request that finds the session already replaced just retries. +// session and protocol version replace the current ones only when the whole replay has succeeded, so a +// request sent meanwhile still uses the old session, and a later 404 starts the replay again. One rejoin runs +// at a time, and a request that finds the session already replaced just retries. func (x *exchange) rejoin(ctx context.Context, stale string) error { c := x.c c.rejoinMu.Lock() defer c.rejoinMu.Unlock() - if c.session() != stale { + if c.current().id != stale { return nil } c.logf("the server ended the session; starting a new one") - c.setSession("") c.mu.Lock() init, initialized := c.initialize, c.initialized c.mu.Unlock() @@ -504,65 +588,68 @@ func (x *exchange) rejoin(ctx context.Context, stale string) error { if initialized.line != nil { replay = append(replay, initialized) } + next := &upstreamState{} for _, msg := range replay { - s := &exchange{c: c, line: msg.line, m: msg.m, idle: x.idle, silent: true} + s := &exchange{c: c, line: msg.line, m: msg.m, req: x.req, idle: x.idle, replay: next} if err := s.send(ctx, false); err != nil { return fmt.Errorf("start a new session: %w", err) } } + c.publish(*next) return nil } -// read delivers every message in an upstream response. -func (x *exchange) read(ctx context.Context, resp *http.Response) error { - switch { - case resp.StatusCode/100 != 2: - body, err := io.ReadAll(resp.Body) - if err != nil { - return err - } - // Only the server's own answer to this request passes through, such as a -32006 under HTTP 401. - // Any other body is an HTTP failure, and its content reaches the client only in the error message. - if msg, err := parseMessage(body); err == nil && msg.isResponseTo(x.m) { - return x.deliverJSON(ctx, body) - } - return httpError(resp.StatusCode, body) - case strings.HasPrefix(resp.Header.Get(contentTypeHeader), eventStreamMIME): - return readEvents(resp.Body, func(data []byte) error { return x.deliverJSON(ctx, data) }) - default: - body, err := io.ReadAll(resp.Body) - if err != nil { - return err - } - if len(bytes.TrimSpace(body)) == 0 { - return nil - } - return x.deliverJSON(ctx, body) +// read delivers the messages in a 2xx response: an event stream, or one JSON body. +func (x *exchange) read(resp *http.Response) error { + if strings.HasPrefix(resp.Header.Get(contentTypeHeader), eventStreamMIME) { + return readEvents(resp.Body, x.deliverEvent) } + body, err := io.ReadAll(resp.Body) + if err != nil { + return err + } + if len(bytes.TrimSpace(body)) == 0 { + return nil + } + if !x.m.isRequest() { + // A notification or client response is answered with 202 and no body. + x.c.logf("upstream sent a JSON body for a notification or client response; it is not forwarded") + return nil + } + msg, err := parseMessage(body) + if err != nil { + return fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) + } + if !msg.isResponseTo(x.m) { + return fmt.Errorf("upstream sent %s instead of the response to the request", excerpt(body)) + } + return x.deliverMessage(body, msg) } -// deliverJSON writes one upstream JSON message. A response to the request marks it answered once the -// message has been written. -func (x *exchange) deliverJSON(ctx context.Context, data []byte) error { - if !json.Valid(data) { - return errors.New("upstream sent invalid JSON") - } +// deliverEvent handles one event of a 2xx event stream. It reports false once the response to the request is +// written: the server SHOULD end the stream after the response, so the bridge stops reading rather than wait +// for the stream to close. See https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server. +func (x *exchange) deliverEvent(data []byte) (bool, error) { msg, err := parseMessage(data) if err != nil { - return fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) + return false, fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) + } + if err := x.deliverMessage(data, msg); err != nil { + return false, err } + return !x.answered, nil +} + +// deliverMessage writes one upstream message, which msg is the parsed envelope of. The response to the request +// marks it answered once written. +func (x *exchange) deliverMessage(data []byte, msg message) error { answer := msg.isResponseTo(x.m) - if answer && x.m.Method == methodInitialize && msg.Result != nil { - // The version the server chose governs the requests that follow, so record it before the answer is written. - var r struct { - ProtocolVersion string `json:"protocolVersion"` - } - if err := json.Unmarshal(msg.Result, &r); err != nil { - return fmt.Errorf("initialize result: %w", err) + if answer && x.m.Method == methodInitialize { + if err := x.recordProtocol(data); err != nil { + return err } - x.c.setProtocol(r.ProtocolVersion) } - if err := x.deliver(ctx, data); err != nil { + if err := x.deliver(data); err != nil { return err } if answer { @@ -571,10 +658,10 @@ func (x *exchange) deliverJSON(ctx context.Context, data []byte) error { return nil } -// deliver applies the initialize edit and the hooks, then writes the resulting messages. A silent exchange -// writes nothing. -func (x *exchange) deliver(ctx context.Context, msg []byte) error { - if x.silent { +// deliver applies the initialize edit and the hooks, then writes the resulting messages. A replayed exchange +// writes nothing: its answers stay inside the bridge. +func (x *exchange) deliver(msg []byte) error { + if x.replay != nil { return nil } var err error @@ -585,7 +672,7 @@ func (x *exchange) deliver(ctx context.Context, msg []byte) error { } msgs := [][]byte{msg} if x.c.b.Hooks != nil { - if msgs, err = x.c.b.Hooks.Result(ctx, x.line, x.status, msg); err != nil { + if msgs, err = x.c.b.Hooks.Result(x.req, x.line, x.status, msg); err != nil { return err } } @@ -603,7 +690,7 @@ func (x *exchange) fail(ctx context.Context, err error) { cause := context.Cause(ctx) switch { case errors.Is(cause, errIdleTimeout): - err = cause + err = fmt.Errorf("no data from upstream for %s", idleTimeout) case cause != nil: return } @@ -612,38 +699,24 @@ func (x *exchange) fail(ctx context.Context, err error) { return } msg := errorResponse(x.m.ID, codeUpstream, fmt.Sprintf("MCP upstream error for request %s: %v", x.m.ID, err)) - // The hooks see the error with a context that the idle timeout has not cancelled. - if derr := x.deliver(context.WithoutCancel(ctx), msg); derr != nil { + if derr := x.deliver(msg); derr != nil { // The hook failed too; the client still needs an answer, so write the error unhooked. x.c.logf("upstream: %v", derr) x.c.reply(msg) } } -// httpError describes a non-2xx response: its status, then the message of a JSON error body or an -// excerpt of any other body. -func httpError(status int, body []byte) error { - if s := bodySummary(body); s != "" { - return fmt.Errorf("HTTP %d: %s", status, s) +// httpError describes a non-2xx response: its status, then the message of a JSON error body, or an excerpt of +// any other body. +func httpError(status int, body []byte, e *errorBody) error { + text := excerpt(body) + if e != nil { + text = cmp.Or(e.Message, e.Error.Message, text) } - return fmt.Errorf("HTTP %d", status) -} - -// bodySummary returns the message of a JSON error body, either a JSON-RPC error or a Databricks error_code -// body. Any other body gives a single-line excerpt. -func bodySummary(body []byte) string { - var e struct { - Message string `json:"message"` - Error struct { - Message string `json:"message"` - } `json:"error"` - } - if json.Unmarshal(body, &e) == nil { - if msg := cmp.Or(e.Message, e.Error.Message); msg != "" { - return msg - } + if text == "" { + return fmt.Errorf("HTTP %d", status) } - return excerpt(body) + return fmt.Errorf("HTTP %d: %s", status, text) } // excerpt returns body as a single line, cut to excerptRunes characters. diff --git a/libs/aitools/mcp/proxy/bridge_test.go b/libs/aitools/mcp/proxy/bridge_test.go index c9116aafa3c..66faec153e4 100644 --- a/libs/aitools/mcp/proxy/bridge_test.go +++ b/libs/aitools/mcp/proxy/bridge_test.go @@ -96,6 +96,24 @@ func setShutdownGrace(t *testing.T, d time.Duration) { t.Cleanup(func() { shutdownGrace = old }) } +// setNotificationWait sets how long a request waits for the notification before it, for one test. +func setNotificationWait(t *testing.T, d time.Duration) { + t.Helper() + old := notificationWait + notificationWait = d + t.Cleanup(func() { notificationWait = old }) +} + +// waitClosed fails the test unless ch is closed within 10 seconds. +func waitClosed(t *testing.T, ch <-chan struct{}, what string) { + t.Helper() + select { + case <-ch: + case <-time.After(10 * time.Second): + t.Fatal("timed out waiting for " + what) + } +} + // syncBuffer is a bytes.Buffer that is safe to read while a bridge writes to it. type syncBuffer struct { mu sync.Mutex @@ -380,7 +398,7 @@ func TestRunAnswersFailedRequestsWithJSONRPCError(t *testing.T) { wantError: "HTTP 403:

Forbidden

", }, {name: "no response", status: http.StatusAccepted, wantError: "no response"}, - {name: "invalid JSON", status: http.StatusOK, body: "", wantError: "invalid JSON"}, + {name: "invalid JSON", status: http.StatusOK, body: "", wantError: "invalid JSON-RPC message"}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { @@ -422,92 +440,96 @@ func TestRunWritesNothingForFailedNotification(t *testing.T) { assert.Contains(t, errOut, "HTTP 500") } -// TestRunAnswersStreamEndingAfterNotification: a progress notification is not an answer, so the request -// still gets an error when the stream ends. -func TestRunAnswersStreamEndingAfterNotification(t *testing.T) { - srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { - w.Header().Set("Content-Type", "text/event-stream") - _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") - }) - - out, _ := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":4,"method":"tools/call"}`+"\n") - - require.Len(t, out, 2) - assert.Equal(t, progressEvent, out[0]) - reply := parseReply(t, out[1]) - assert.JSONEq(t, `4`, string(reply.ID)) - require.NotNil(t, reply.Error) - assert.Equal(t, codeUpstream, reply.Error.Code) - assert.Contains(t, reply.Error.Message, "no response") -} - -// TestRunAnswersStreamIdleAfterNotification: the idle watchdog ends a stream that stops after a notification. -func TestRunAnswersStreamIdleAfterNotification(t *testing.T) { - setIdleTimeout(t, 100*time.Millisecond) - srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { - w.Header().Set("Content-Type", "text/event-stream") - _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") - w.(http.Flusher).Flush() - <-r.Context().Done() - }) - - out, _ := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":4,"method":"tools/call"}`+"\n") - - require.Len(t, out, 2) - assert.Equal(t, progressEvent, out[0]) - reply := parseReply(t, out[1]) - assert.JSONEq(t, `4`, string(reply.ID)) - require.NotNil(t, reply.Error) - assert.Contains(t, reply.Error.Message, "no data from upstream") -} - -// TestRunAnswersBrokenStreamAfterNotification: a connection cut mid-stream after a notification is answered. -func TestRunAnswersBrokenStreamAfterNotification(t *testing.T) { - srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { - w.Header().Set("Content-Type", "text/event-stream") - _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") - w.(http.Flusher).Flush() - panic(http.ErrAbortHandler) - }) +// TestRunAnswersStreamsThatEndWithoutResponse: a stream that ends after only a notification, goes idle, or is cut +// is answered with an error, since the progress notification is not the answer. +func TestRunAnswersStreamsThatEndWithoutResponse(t *testing.T) { + cases := []struct { + name string + idle time.Duration + finish http.HandlerFunc + wantMsg string + }{ + { + name: "stream ends", + wantMsg: "no response", + finish: func(http.ResponseWriter, *http.Request) {}, + }, + { + name: "stream goes idle", + idle: 100 * time.Millisecond, + wantMsg: "no data from upstream", + finish: func(w http.ResponseWriter, r *http.Request) { + w.(http.Flusher).Flush() + <-r.Context().Done() + }, + }, + { + name: "connection cut", + wantMsg: "MCP upstream error", + finish: func(http.ResponseWriter, *http.Request) { panic(http.ErrAbortHandler) }, + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + if tc.idle > 0 { + setIdleTimeout(t, tc.idle) + } + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "text/event-stream") + _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") + w.(http.Flusher).Flush() + tc.finish(w, r) + }) - out, _ := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":4,"method":"tools/call"}`+"\n") + out, _ := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":4,"method":"tools/call"}`+"\n") - require.Len(t, out, 2) - reply := parseReply(t, out[1]) - assert.JSONEq(t, `4`, string(reply.ID)) - require.NotNil(t, reply.Error) - assert.Equal(t, codeUpstream, reply.Error.Code) + require.Len(t, out, 2) + assert.Equal(t, progressEvent, out[0]) + reply := parseReply(t, out[1]) + assert.JSONEq(t, `4`, string(reply.ID)) + require.NotNil(t, reply.Error) + assert.Equal(t, codeUpstream, reply.Error.Code) + assert.Contains(t, reply.Error.Message, tc.wantMsg) + }) + } } -// TestRunDeliversIdleErrorWithLiveContext: hooks see the synthesized error with a context the idle timeout -// did not cancel. -func TestRunDeliversIdleErrorWithLiveContext(t *testing.T) { +// TestRunHookOutlivesIdleTimeout: the hook for the idle error keeps its context after the idle timeout, so it +// is cancelled only by shutdown (or the client), and a hook that waits for its context does not hold Run. +func TestRunHookOutlivesIdleTimeout(t *testing.T) { setIdleTimeout(t, 100*time.Millisecond) + setShutdownGrace(t, 100*time.Millisecond) srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { - w.Header().Set("Content-Type", "text/event-stream") - _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") - w.(http.Flusher).Flush() - <-r.Context().Done() + select { + case <-r.Context().Done(): + case <-time.After(20 * time.Second): + } }) - var mu sync.Mutex - var ctxErrs []error + entered := make(chan struct{}) + cancelled := make(chan bool, 1) b := bridgeFor(srv.URL) b.Hooks = hookFunc(func(ctx context.Context, _ []byte, _ int, msg []byte) ([][]byte, error) { - mu.Lock() - defer mu.Unlock() - ctxErrs = append(ctxErrs, ctx.Err()) + close(entered) + select { + case <-ctx.Done(): + cancelled <- true + case <-time.After(10 * time.Second): + cancelled <- false + } return [][]byte{msg}, nil }) + p := startPiped(t, t.Context(), b) - out, _ := runAll(t, b, `{"jsonrpc":"2.0","id":5,"method":"tools/call"}`+"\n") + p.send(t, `{"jsonrpc":"2.0","id":5,"method":"tools/call"}`) + waitClosed(t, entered, "the hook") + require.NoError(t, p.finish(t)) - require.Len(t, out, 2) - reply := parseReply(t, out[1]) + assert.True(t, <-cancelled, "the hook's context was cancelled by shutdown, not by the idle timeout") + out := outLines(p.out.String()) + require.Len(t, out, 1) + reply := parseReply(t, out[0]) require.NotNil(t, reply.Error) assert.Contains(t, reply.Error.Message, "no data from upstream") - mu.Lock() - defer mu.Unlock() - assert.Equal(t, []error{nil, nil}, ctxErrs) } // expiringSession answers like a server whose first session has expired: tools/list gets 404 for session s1 @@ -854,3 +876,421 @@ func TestRunWritesHookErrorAsJSONRPCError(t *testing.T) { assert.Contains(t, reply.Error.Message, "hook failed") assert.Contains(t, errOut, "hook failed") } + +// endingServer is an endpoint whose first session ends on the first tools/list it sees, as a server does when it +// drops sessions. Each initialize starts the next session (s1, s2, ...) once beforeStart returns true for its +// number; false answers 503. Only a request that carries the current session id is answered, and any other +// request gets 404. onStale, when set, runs for each request that still carries s1 after s1 has ended. +type endingServer struct { + beforeStart func(n int, r *http.Request) bool + onStale func() +} + +func newEndingServer(t *testing.T, es endingServer) (*httptest.Server, *fakeEndpoint) { + t.Helper() + var mu sync.Mutex + starts := 0 + current := "" + return newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + w.Header().Set("Content-Type", "application/json") + if m.Method == methodInitialize { + mu.Lock() + starts++ + n := starts + mu.Unlock() + if es.beforeStart != nil && !es.beforeStart(n, r) { + http.Error(w, "unavailable", http.StatusServiceUnavailable) + return + } + mu.Lock() + current = fmt.Sprintf("s%d", n) + sid := current + mu.Unlock() + w.Header().Set(sessionHeader, sid) + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"protocolVersion":"2025-06-18"}}`, m.ID) + return + } + sid := r.Header.Get(sessionHeader) + mu.Lock() + if m.Method == "tools/list" && current == "s1" { + current = "" + } + accepted := current != "" && sid == current + mu.Unlock() + if !accepted { + if sid == "s1" && es.onStale != nil { + es.onStale() + } + http.Error(w, "session not found", http.StatusNotFound) + return + } + if !m.isRequest() { + w.WriteHeader(http.StatusAccepted) + return + } + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"tools":[]}}`, m.ID) + }) +} + +const ( + initializeLine = `{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}` + initializedLine = `{"jsonrpc":"2.0","method":"notifications/initialized"}` +) + +// sessionsSent returns the Mcp-Session-Id of each upstream POST whose body contains marker, in order. +func sessionsSent(fake *fakeEndpoint, marker string) []string { + var sessions []string + for _, r := range fake.requests() { + if r.Method == http.MethodPost && strings.Contains(string(r.Body), marker) { + sessions = append(sessions, r.Header.Get(sessionHeader)) + } + } + return sessions +} + +// TestRunRecoversAfterFailedReplay: when the replayed initialize fails, the session id is kept, so the next +// request that hits the ended session starts a new one. +func TestRunRecoversAfterFailedReplay(t *testing.T) { + srv, fake := newEndingServer(t, endingServer{beforeStart: func(n int, _ *http.Request) bool { return n != 2 }}) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + p.waitLines(t, 2) + p.send(t, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`) + require.NoError(t, p.finish(t)) + + out := outLines(p.out.String()) + require.Len(t, out, 3) + failed := parseReply(t, out[1]) + assert.JSONEq(t, `2`, string(failed.ID)) + require.NotNil(t, failed.Error) + assert.Contains(t, failed.Error.Message, "start a new session") + recovered := parseReply(t, out[2]) + assert.JSONEq(t, `3`, string(recovered.ID)) + assert.Nil(t, recovered.Error) + assert.Equal(t, []string{"s1", "s3"}, sessionsSent(fake, `"id":3,`), "the request first hits the ended session, then the new one") +} + +// TestRunRecoversWhenReplayIsCancelled: the client cancels the request that started a replay. The replay stops +// without an answer for that request, and the next request starts a new session. +func TestRunRecoversWhenReplayIsCancelled(t *testing.T) { + replaying := make(chan struct{}) + srv, _ := newEndingServer(t, endingServer{beforeStart: func(n int, r *http.Request) bool { + if n == 2 { + close(replaying) + <-r.Context().Done() + return false + } + return true + }}) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + waitClosed(t, replaying, "the replayed initialize") + p.send(t, `{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":2}}`) + p.send(t, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`) + p.waitLines(t, 2) + require.NoError(t, p.finish(t)) + + out := outLines(p.out.String()) + require.Len(t, out, 2, "the cancelled request gets no answer") + reply := parseReply(t, out[1]) + assert.JSONEq(t, `3`, string(reply.ID)) + assert.Nil(t, reply.Error) +} + +// TestRunRequestDuringRejoinUsesNewSession: a request sent while a rejoin is running still uses the old session, +// gets 404, waits for the rejoin, and is posted again on the new session. +func TestRunRequestDuringRejoinUsesNewSession(t *testing.T) { + replayStarted := make(chan struct{}) + release := make(chan struct{}) + releaseOnce := sync.OnceFunc(func() { close(release) }) + staleSeen := make(chan struct{}) + var stale atomic.Int32 + srv, fake := newEndingServer(t, endingServer{ + beforeStart: func(n int, _ *http.Request) bool { + if n == 2 { + close(replayStarted) + <-release + } + return true + }, + onStale: func() { + if stale.Add(1) == 2 { + close(staleSeen) + } + }, + }) + t.Cleanup(releaseOnce) // registered after the server, so it runs first and the held handler returns + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + waitClosed(t, replayStarted, "the replayed initialize") + p.send(t, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`) + waitClosed(t, staleSeen, "the request sent during the rejoin to get its 404") + releaseOnce() + out := p.waitLines(t, 3) + require.NoError(t, p.finish(t)) + + for _, line := range out[1:] { + assert.Nil(t, parseReply(t, line).Error, line) + } + assert.Equal(t, []string{"s1", "s2"}, sessionsSent(fake, `"id":3,`)) + assert.Equal(t, []string{"s1", "s2"}, sessionsSent(fake, `"id":2,`)) +} + +// TestRunAnswersRequestEndedBy404WithResponse: a 404 whose body is the server's response to the request is not an +// ended session, so the request is not posted again and no new session starts. +func TestRunAnswersRequestEndedBy404WithResponse(t *testing.T) { + const response = `{"jsonrpc":"2.0","id":2,"error":{"code":-32001,"message":"unknown tool"}}` + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + w.Header().Set("Content-Type", "application/json") + switch m.Method { + case methodInitialize: + w.Header().Set(sessionHeader, "s1") + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"protocolVersion":"2025-06-18"}}`, m.ID) + case "tools/call": + w.WriteHeader(http.StatusNotFound) + _, _ = io.WriteString(w, response) + default: + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + } + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/call"}`) + p.waitLines(t, 2) + require.NoError(t, p.finish(t)) + + assert.Equal(t, []string{response}, outLines(p.out.String())[1:]) + assert.Len(t, sessionsSent(fake, `"method":"initialize"`), 1, "no new session was started") + assert.Len(t, sessionsSent(fake, `"method":"tools/call"`), 1, "the request was posted once") +} + +// TestRunMatchesResponseIDsByValue: a server may re-encode a request id, so the response is matched by the value +// of the id, and the protocol version is recorded from it. +func TestRunMatchesResponseIDsByValue(t *testing.T) { + cases := []struct { + name string + requestID string + responseID string + }{ + {name: "string with an escaped character", requestID: `"a 0 && string(m.ID) != "null" } -// isResponseTo reports whether m is a JSON-RPC response to request. Only a request can have one. +// isResponseTo reports whether m is a JSON-RPC response to request. Only a request can have one. The ids +// are compared by value (see idKey), since a server may re-encode them. func (m message) isResponseTo(request message) bool { - return request.isRequest() && m.Method == "" && bytes.Equal(m.ID, request.ID) + return m.Method == "" && request.isRequest() && idKey(m.ID) == idKey(request.ID) +} + +// idKey returns the key that identifies a JSON-RPC id by its decoded value: a string by its text, and a +// number by its value, so 7 and 7.0 match. An id that is not a string or number is keyed by its bytes. +func idKey(raw json.RawMessage) string { + var v any + _ = json.Unmarshal(raw, &v) // an empty or invalid id has no value and keeps its bytes as the key + switch v := v.(type) { + case string: + return "s" + v + case float64: + return "n" + strconv.FormatFloat(v, 'g', -1, 64) + } + return string(raw) } // errorResponse builds a JSON-RPC error response. A nil id is sent as null. func errorResponse(id json.RawMessage, code int, text string) []byte { if len(id) == 0 { - id = json.RawMessage("null") + id = jsonNull } // Cannot fail: the id came from a parsed message and the other fields are plain values. b, _ := json.Marshal(rpcErrorResponse{JSONRPC: "2.0", ID: id, Error: rpcError{Code: code, Message: text}}) @@ -145,5 +182,5 @@ func member(obj map[string]json.RawMessage, key string) json.RawMessage { if raw, ok := obj[key]; ok { return raw } - return json.RawMessage("null") + return jsonNull } diff --git a/libs/aitools/mcp/proxy/messages_test.go b/libs/aitools/mcp/proxy/messages_test.go index a24159d2d5b..bd225dbeb3b 100644 --- a/libs/aitools/mcp/proxy/messages_test.go +++ b/libs/aitools/mcp/proxy/messages_test.go @@ -87,3 +87,33 @@ func TestMessageIsRequest(t *testing.T) { }) } } + +func TestIsResponseToComparesIDsByValue(t *testing.T) { + request := func(id string) message { + m, err := parseMessage([]byte(`{"jsonrpc":"2.0","id":` + id + `,"method":"tools/call"}`)) + require.NoError(t, err) + return m + } + response := func(id string) message { + m, err := parseMessage([]byte(`{"jsonrpc":"2.0","id":` + id + `,"result":{}}`)) + require.NoError(t, err) + return m + } + cases := []struct { + name string + request string + response string + want bool + }{ + {name: "same string", request: `"a Date: Thu, 12 Nov 2026 23:20:35 +0000 Subject: [PATCH 4/7] Refactor the MCP bridge replay and context handling No behavior change. The session replay is a function that posts the saved initialize and notifications/initialized and returns the session and protocol version they establish, instead of an exchange with a replay mode. Hooks receive the request context as an argument; exchange no longer stores it. Shutdown cancels and waits once after the grace period. The Accept header name is a constant, and isRequest compares the null id by bytes. Co-authored-by: Isaac --- libs/aitools/mcp/proxy/bridge.go | 236 +++++++++++++++--------- libs/aitools/mcp/proxy/messages.go | 19 +- libs/aitools/mcp/proxy/messages_test.go | 28 +-- 3 files changed, 180 insertions(+), 103 deletions(-) diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go index 47b90dbf509..b08d7e071eb 100644 --- a/libs/aitools/mcp/proxy/bridge.go +++ b/libs/aitools/mcp/proxy/bridge.go @@ -22,7 +22,8 @@ const ( sessionHeader = "Mcp-Session-Id" protocolHeader = "MCP-Protocol-Version" contentTypeHeader = "Content-Type" - acceptHeader = "application/json, text/event-stream" + acceptHeader = "Accept" + acceptTypes = "application/json, text/event-stream" jsonMIME = "application/json" eventStreamMIME = "text/event-stream" @@ -53,7 +54,8 @@ var ( type Hooks interface { // Result receives each upstream message for a client request, with the HTTP status (0 when the // request failed before a response). It returns the messages to write in its place, in order: - // a single copy of message passes it through, an empty slice drops it. + // a single copy of message passes it through, an empty slice drops it. Result is called + // concurrently, from the goroutine of each request. Result(ctx context.Context, request []byte, status int, message []byte) ([][]byte, error) } @@ -257,9 +259,9 @@ func (c *conn) forward(ctx context.Context, gate <-chan struct{}, line []byte, m idle := time.AfterFunc(idleTimeout, func() { cancel(errIdleTimeout) }) defer idle.Stop() - x := &exchange{c: c, line: line, m: m, req: ctx, idle: idle} - if err := x.send(idleCtx, true); err != nil { - x.fail(idleCtx, err) + x := &exchange{c: c, line: line, m: m, idle: idle} + if err := x.send(idleCtx, ctx, true); err != nil { + x.fail(idleCtx, ctx, err) } } @@ -273,10 +275,9 @@ func (c *conn) shutdown(ctx context.Context) { select { case <-done: case <-time.After(shutdownGrace): - c.cancelBase() - <-done } c.cancelBase() + <-done c.deleteSession(ctx) } @@ -324,7 +325,7 @@ func (c *conn) newRequest(ctx context.Context, method string, body []byte, sent for k, v := range c.b.Headers { req.Header.Set(k, v) } - req.Header.Set("Accept", acceptHeader) + req.Header.Set(acceptHeader, acceptTypes) if body != nil { req.Header.Set(contentTypeHeader, jsonMIME) } @@ -465,63 +466,35 @@ type exchange struct { c *conn line []byte m message - // req is the request's context. Hooks get it, so an idle timeout does not cancel them, while shutdown - // and the client still do. - req context.Context - idle *time.Timer - replay *upstreamState // set for a replayed handshake: its session and protocol stay here until the replay ends + idle *time.Timer // reset by every read of the response status int answered bool // the upstream sent the response to m } // sending returns the session and protocol version to send with x. An initialize request starts a session, -// so it carries neither (MCP transports, Session Management: -// https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management). +// so it carries neither (https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management). func (x *exchange) sending() upstreamState { - switch { - case x.m.Method == methodInitialize: + if x.m.Method == methodInitialize { return upstreamState{} - case x.replay != nil: - return *x.replay } return x.c.current() } -// recordSession keeps the Mcp-Session-Id of a successful response. A replay keeps it until it ends. -func (x *exchange) recordSession(id string) { - switch { - case id == "": - case x.replay != nil: - x.replay.id = id - default: - x.c.setSession(id) - } -} - // recordProtocol keeps the protocol version from an initialize result, before the result is written. // The version the server chose governs the requests that follow. func (x *exchange) recordProtocol(data []byte) error { - var r struct { - Result *struct { - ProtocolVersion string `json:"protocolVersion"` - } `json:"result"` - } - if err := json.Unmarshal(data, &r); err != nil { - return fmt.Errorf("initialize result: %w", err) - } - switch { - case r.Result == nil: - case x.replay != nil: - x.replay.protocol = r.Result.ProtocolVersion - default: - x.c.setProtocol(r.Result.ProtocolVersion) + v, ok, err := initializeProtocol(data) + if err != nil || !ok { + return err } + x.c.setProtocol(v) return nil } -// send posts the message and writes its answer. -func (x *exchange) send(ctx context.Context, retry bool) error { +// send posts the message and writes its answer. ctx is cancelled by the idle timeout; reqCtx is the request's +// context, which hooks receive. +func (x *exchange) send(ctx, reqCtx context.Context, retry bool) error { sent := x.sending() resp, err := x.c.post(ctx, x.line, sent) if err != nil { @@ -531,10 +504,12 @@ func (x *exchange) send(ctx context.Context, retry bool) error { resp.Body = idleBody{ReadCloser: resp.Body, idle: x.idle} x.status = resp.StatusCode if resp.StatusCode/100 != 2 { - return x.httpFailure(ctx, resp, sent.id, retry) + return x.httpFailure(ctx, reqCtx, resp, sent.id, retry) } - x.recordSession(resp.Header.Get(sessionHeader)) - if err := x.read(resp); err != nil { + if id := resp.Header.Get(sessionHeader); id != "" { + x.c.setSession(id) + } + if err := x.read(reqCtx, resp); err != nil { return err } if x.m.isRequest() && !x.answered { @@ -543,33 +518,29 @@ func (x *exchange) send(ctx context.Context, retry bool) error { return nil } -// httpFailure handles a non-2xx response. A body that is the server's response to x.m passes through, as -// the server sent it. Otherwise a 404 for a request that carried a session id means the server ended the -// session: the client starts a new one and posts the request once more. That rule does not apply when the -// 404 body answers the request. See https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management. -func (x *exchange) httpFailure(ctx context.Context, resp *http.Response, sent string, retry bool) error { +// httpFailure handles a non-2xx response. A body that is the server's response to x.m passes through. Otherwise +// a 404 for a request that carried a session id means the server ended the session, so the client starts a new +// one and posts the request once more. +func (x *exchange) httpFailure(ctx, reqCtx context.Context, resp *http.Response, sent string, retry bool) error { body, err := io.ReadAll(resp.Body) if err != nil { return err } e := decodeErrorBody(body) if e != nil && e.isResponseTo(x.m) { - return x.deliverMessage(body, e.message) + return x.deliverMessage(reqCtx, body, e.message) } if resp.StatusCode == http.StatusNotFound && sent != "" && retry { if err := x.rejoin(ctx, sent); err != nil { return err } - return x.send(ctx, false) + return x.send(ctx, reqCtx, false) } return httpError(resp.StatusCode, body, e) } -// rejoin starts a new session after the server ended stale. The client's initialize and -// notifications/initialized are replayed silently, since the client already has their answers. The new -// session and protocol version replace the current ones only when the whole replay has succeeded, so a -// request sent meanwhile still uses the old session, and a later 404 starts the replay again. One rejoin runs -// at a time, and a request that finds the session already replaced just retries. +// rejoin starts a new session after the server ended stale. The new session replaces the current one only when the +// replay succeeds. One rejoin runs at a time, and a request that finds the session already replaced just retries. func (x *exchange) rejoin(ctx context.Context, stale string) error { c := x.c c.rejoinMu.Lock() @@ -584,25 +555,112 @@ func (x *exchange) rejoin(ctx context.Context, stale string) error { if init.line == nil { return errors.New("the server ended the session, and no initialize request was sent to replay") } - replay := []clientMsg{init} + msgs := []clientMsg{init} if initialized.line != nil { - replay = append(replay, initialized) + msgs = append(msgs, initialized) + } + next, err := c.replay(ctx, x.idle, msgs) + if err != nil { + return fmt.Errorf("start a new session: %w", err) } - next := &upstreamState{} - for _, msg := range replay { - s := &exchange{c: c, line: msg.line, m: msg.m, req: x.req, idle: x.idle, replay: next} - if err := s.send(ctx, false); err != nil { - return fmt.Errorf("start a new session: %w", err) + c.publish(next) + return nil +} + +// replay posts the client's handshake messages, in order, to a new session. Their answers are read here and not +// written to stdout. It returns the session and protocol version they establish. +func (c *conn) replay(ctx context.Context, idle *time.Timer, msgs []clientMsg) (upstreamState, error) { + var next upstreamState + for _, msg := range msgs { + if err := c.replayOne(ctx, idle, msg, &next); err != nil { + return upstreamState{}, err + } + } + return next, nil +} + +// replayOne posts one handshake message with the session and protocol version replayed so far, and records what its +// answer establishes in next: the session id from the response headers, the protocol version from an initialize result. +func (c *conn) replayOne(ctx context.Context, idle *time.Timer, msg clientMsg, next *upstreamState) error { + resp, err := c.post(ctx, msg.line, *next) + if err != nil { + return err + } + defer resp.Body.Close() + resp.Body = idleBody{ReadCloser: resp.Body, idle: idle} + if resp.StatusCode/100 != 2 { + body, err := io.ReadAll(resp.Body) + if err != nil { + return err + } + e := decodeErrorBody(body) + if e == nil || !e.isResponseTo(msg.m) { + return httpError(resp.StatusCode, body, e) } + return recordProtocol(msg.m, body, next) } - c.publish(*next) + if id := resp.Header.Get(sessionHeader); id != "" { + next.id = id + } + + var answer []byte + if strings.HasPrefix(resp.Header.Get(contentTypeHeader), eventStreamMIME) { + err = readEvents(resp.Body, func(data []byte) (bool, error) { + m, err := parseMessage(data) + if err != nil { + return false, fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) + } + if m.isResponseTo(msg.m) { + answer = data + return false, nil + } + return true, nil + }) + } else { + var body []byte + body, err = io.ReadAll(resp.Body) + if err == nil && len(bytes.TrimSpace(body)) > 0 && msg.m.isRequest() { + m, perr := parseMessage(body) + if perr != nil { + return fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", perr) + } + if !m.isResponseTo(msg.m) { + return fmt.Errorf("upstream sent %s instead of the response to the request", excerpt(body)) + } + answer = body + } + } + if err != nil { + return err + } + if !msg.m.isRequest() { + return nil + } + if answer == nil { + return errNoResponse + } + return recordProtocol(msg.m, answer, next) +} + +// recordProtocol sets next's protocol version from the result of an initialize response. +func recordProtocol(m message, data []byte, next *upstreamState) error { + if m.Method != methodInitialize { + return nil + } + v, ok, err := initializeProtocol(data) + if err != nil || !ok { + return err + } + next.protocol = v return nil } // read delivers the messages in a 2xx response: an event stream, or one JSON body. -func (x *exchange) read(resp *http.Response) error { +func (x *exchange) read(reqCtx context.Context, resp *http.Response) error { if strings.HasPrefix(resp.Header.Get(contentTypeHeader), eventStreamMIME) { - return readEvents(resp.Body, x.deliverEvent) + return readEvents(resp.Body, func(data []byte) (bool, error) { + return x.deliverEvent(reqCtx, data) + }) } body, err := io.ReadAll(resp.Body) if err != nil { @@ -623,33 +681,32 @@ func (x *exchange) read(resp *http.Response) error { if !msg.isResponseTo(x.m) { return fmt.Errorf("upstream sent %s instead of the response to the request", excerpt(body)) } - return x.deliverMessage(body, msg) + return x.deliverMessage(reqCtx, body, msg) } -// deliverEvent handles one event of a 2xx event stream. It reports false once the response to the request is -// written: the server SHOULD end the stream after the response, so the bridge stops reading rather than wait -// for the stream to close. See https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server. -func (x *exchange) deliverEvent(data []byte) (bool, error) { +// deliverEvent handles one event of a 2xx event stream. It reports false once the response is written, since the +// server SHOULD end the stream after it (https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server). +func (x *exchange) deliverEvent(reqCtx context.Context, data []byte) (bool, error) { msg, err := parseMessage(data) if err != nil { return false, fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) } - if err := x.deliverMessage(data, msg); err != nil { + if err := x.deliverMessage(reqCtx, data, msg); err != nil { return false, err } return !x.answered, nil } -// deliverMessage writes one upstream message, which msg is the parsed envelope of. The response to the request -// marks it answered once written. -func (x *exchange) deliverMessage(data []byte, msg message) error { +// deliverMessage writes one upstream message, whose parsed envelope is msg. The response to the request marks it +// answered once written. +func (x *exchange) deliverMessage(reqCtx context.Context, data []byte, msg message) error { answer := msg.isResponseTo(x.m) if answer && x.m.Method == methodInitialize { if err := x.recordProtocol(data); err != nil { return err } } - if err := x.deliver(data); err != nil { + if err := x.deliver(reqCtx, data); err != nil { return err } if answer { @@ -658,12 +715,8 @@ func (x *exchange) deliverMessage(data []byte, msg message) error { return nil } -// deliver applies the initialize edit and the hooks, then writes the resulting messages. A replayed exchange -// writes nothing: its answers stay inside the bridge. -func (x *exchange) deliver(msg []byte) error { - if x.replay != nil { - return nil - } +// deliver applies the initialize edit and the hooks, then writes the resulting messages. +func (x *exchange) deliver(reqCtx context.Context, msg []byte) error { var err error if x.m.Method == methodInitialize && (x.c.b.Instructions != "" || x.c.b.ForceListChanged) { if msg, err = editInitialize(msg, x.c.b.Instructions, x.c.b.ForceListChanged); err != nil { @@ -672,7 +725,7 @@ func (x *exchange) deliver(msg []byte) error { } msgs := [][]byte{msg} if x.c.b.Hooks != nil { - if msgs, err = x.c.b.Hooks.Result(x.req, x.line, x.status, msg); err != nil { + if msgs, err = x.c.b.Hooks.Result(reqCtx, x.line, x.status, msg); err != nil { return err } } @@ -685,8 +738,9 @@ func (x *exchange) deliver(msg []byte) error { } // fail logs err and, for a request the client still waits on, answers it with a JSON-RPC error. A request -// that the client or shutdown cancelled is neither logged nor answered. -func (x *exchange) fail(ctx context.Context, err error) { +// that the client or shutdown cancelled is neither logged nor answered. ctx is the idle-watched context; reqCtx is +// the request's context, which hooks receive. +func (x *exchange) fail(ctx, reqCtx context.Context, err error) { cause := context.Cause(ctx) switch { case errors.Is(cause, errIdleTimeout): @@ -699,7 +753,7 @@ func (x *exchange) fail(ctx context.Context, err error) { return } msg := errorResponse(x.m.ID, codeUpstream, fmt.Sprintf("MCP upstream error for request %s: %v", x.m.ID, err)) - if derr := x.deliver(msg); derr != nil { + if derr := x.deliver(reqCtx, msg); derr != nil { // The hook failed too; the client still needs an answer, so write the error unhooked. x.c.logf("upstream: %v", derr) x.c.reply(msg) diff --git a/libs/aitools/mcp/proxy/messages.go b/libs/aitools/mcp/proxy/messages.go index bcea50c67e3..e67a7a96e65 100644 --- a/libs/aitools/mcp/proxy/messages.go +++ b/libs/aitools/mcp/proxy/messages.go @@ -82,7 +82,7 @@ func decodeErrorBody(body []byte) *errorBody { // isRequest reports whether m is a request, which expects a response, rather than a notification. func (m message) isRequest() bool { - return m.Method != "" && len(m.ID) > 0 && string(m.ID) != "null" + return m.Method != "" && len(m.ID) > 0 && !bytes.Equal(m.ID, jsonNull) } // isResponseTo reports whether m is a JSON-RPC response to request. Only a request can have one. The ids @@ -105,6 +105,23 @@ func idKey(raw json.RawMessage) string { return string(raw) } +// initializeProtocol returns the protocol version in the result of an initialize response. ok is false when the +// response has no result. +func initializeProtocol(data []byte) (version string, ok bool, err error) { + var r struct { + Result *struct { + ProtocolVersion string `json:"protocolVersion"` + } `json:"result"` + } + if err := json.Unmarshal(data, &r); err != nil { + return "", false, fmt.Errorf("initialize result: %w", err) + } + if r.Result == nil { + return "", false, nil + } + return r.Result.ProtocolVersion, true, nil +} + // errorResponse builds a JSON-RPC error response. A nil id is sent as null. func errorResponse(id json.RawMessage, code int, text string) []byte { if len(id) == 0 { diff --git a/libs/aitools/mcp/proxy/messages_test.go b/libs/aitools/mcp/proxy/messages_test.go index bd225dbeb3b..c835b946579 100644 --- a/libs/aitools/mcp/proxy/messages_test.go +++ b/libs/aitools/mcp/proxy/messages_test.go @@ -88,17 +88,23 @@ func TestMessageIsRequest(t *testing.T) { } } +// parseRequestWithID parses a tools/call request with the given id, written as JSON. +func parseRequestWithID(t *testing.T, id string) message { + t.Helper() + m, err := parseMessage([]byte(`{"jsonrpc":"2.0","id":` + id + `,"method":"tools/call"}`)) + require.NoError(t, err) + return m +} + +// parseResponseWithID parses a result response with the given id, written as JSON. +func parseResponseWithID(t *testing.T, id string) message { + t.Helper() + m, err := parseMessage([]byte(`{"jsonrpc":"2.0","id":` + id + `,"result":{}}`)) + require.NoError(t, err) + return m +} + func TestIsResponseToComparesIDsByValue(t *testing.T) { - request := func(id string) message { - m, err := parseMessage([]byte(`{"jsonrpc":"2.0","id":` + id + `,"method":"tools/call"}`)) - require.NoError(t, err) - return m - } - response := func(id string) message { - m, err := parseMessage([]byte(`{"jsonrpc":"2.0","id":` + id + `,"result":{}}`)) - require.NoError(t, err) - return m - } cases := []struct { name string request string @@ -113,7 +119,7 @@ func TestIsResponseToComparesIDsByValue(t *testing.T) { } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { - assert.Equal(t, tc.want, response(tc.response).isResponseTo(request(tc.request))) + assert.Equal(t, tc.want, parseResponseWithID(t, tc.response).isResponseTo(parseRequestWithID(t, tc.request))) }) } } From 47201325d7a54bcb65325c3919a73e07c5b28bca Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 23:28:18 +0000 Subject: [PATCH 5/7] Fix review findings in the MCP stdio bridge (pass 3) A replayed initialize answered with a JSON-RPC error no longer counts as a replay that succeeded: the session needs a result. The session id is taken only from the initialize response, so a late answer on an ended session cannot replace the new one. A 404 ends the session unless its body is the result for the request, and only requests start a new session. Notifications and client responses are not reposted after a rejoin. SSE events are delivered only when their type is message or empty, so a keepalive no longer ends a request. The media type is matched without regard to case. The upstream client takes an optional Transport, so a profile's TLS settings apply. It does not follow redirects: a 3xx is a failed response. A notification's gate closes after notificationWait from when the notification starts, and a request waits only for the gate or its context. Request ids compare by exact numeric value, so integers above 2^53 stay distinct. A retried request reports status 0 to the hooks when it fails before a response. A rejoin waiting for the slot honors the request's context. A failed replay deletes the session it created. A 2xx body is limited to 64 MiB, and an error body is read up to 1 MiB and excerpted. Co-authored-by: Isaac --- libs/aitools/mcp/proxy/bridge.go | 170 +++++--- libs/aitools/mcp/proxy/bridge_test.go | 505 +++++++++++++++++++++++- libs/aitools/mcp/proxy/messages.go | 19 +- libs/aitools/mcp/proxy/messages_test.go | 2 + libs/aitools/mcp/proxy/sse.go | 29 +- libs/aitools/mcp/proxy/sse_test.go | 1 + 6 files changed, 659 insertions(+), 67 deletions(-) diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go index b08d7e071eb..1cfa6766fae 100644 --- a/libs/aitools/mcp/proxy/bridge.go +++ b/libs/aitools/mcp/proxy/bridge.go @@ -10,6 +10,7 @@ import ( "errors" "fmt" "io" + "mime" "net" "net/http" "strings" @@ -28,9 +29,11 @@ const ( eventStreamMIME = "text/event-stream" maxLineBytes = 64 << 20 + maxErrorBytes = 1 << 20 // a non-2xx body is read up to this many bytes; its error message is an excerpt connectTimeout = 10 * time.Second deleteTimeout = 5 * time.Second excerptRunes = 200 + excerptBytes = 4 * excerptRunes // a character takes at most four bytes codeParseError = -32700 codeInvalidRequest = -32600 @@ -75,6 +78,8 @@ type Bridge struct { ForceListChanged bool // Hooks, when set, sees every upstream message before it is written. Hooks Hooks + // Transport performs the upstream requests. Nil uses the default transport with a 10 s connect timeout. + Transport http.RoundTripper } // Run forwards stdin to the endpoint until stdin closes or ctx is done. Shutdown waits up to 2 s for @@ -84,9 +89,10 @@ func (b *Bridge) Run(ctx context.Context) error { base, cancelBase := context.WithCancel(context.WithoutCancel(ctx)) c := &conn{ b: b, - client: newClient(), + client: newClient(b.Transport), cancelBase: cancelBase, inflight: map[string]context.CancelFunc{}, + rejoinSlot: make(chan struct{}, 1), } lines := make(chan []byte) @@ -176,8 +182,8 @@ type conn struct { cancelBase context.CancelFunc wg sync.WaitGroup - ioMu sync.Mutex // serializes writes to Out and Err - rejoinMu sync.Mutex // allows one session restart at a time + ioMu sync.Mutex // serializes writes to Out and Err + rejoinSlot chan struct{} // holds the slot of the one rejoin that runs at a time mu sync.Mutex // guards the fields below state upstreamState @@ -186,11 +192,18 @@ type conn struct { initialized clientMsg // the client's notifications/initialized, for replay } -// newClient returns the upstream HTTP client: a 10 s connect timeout and the environment's proxy settings. -func newClient() *http.Client { - t := http.DefaultTransport.(*http.Transport).Clone() - t.DialContext = (&net.Dialer{Timeout: connectTimeout}).DialContext - return &http.Client{Transport: t} +// newClient returns the upstream HTTP client over rt, or over the default transport when rt is nil. A redirect is +// not followed: a 3xx response is a failed response with its status. +func newClient(rt http.RoundTripper) *http.Client { + if rt == nil { + t := http.DefaultTransport.(*http.Transport).Clone() + t.DialContext = (&net.Dialer{Timeout: connectTimeout}).DialContext + rt = t + } + return &http.Client{ + Transport: rt, + CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }, + } } // handle starts one stdin message and returns the gate for the next one. A request or notification runs in @@ -227,25 +240,27 @@ func (c *conn) handle(base context.Context, gate <-chan struct{}, line []byte) < }) return gate } + // The gate closes when the POST finishes or after notificationWait, whichever is first, so a stalled notification + // holds later messages for at most that long. done := make(chan struct{}) + release := sync.OnceFunc(func() { close(done) }) c.wg.Go(func() { - defer close(done) + timer := time.AfterFunc(notificationWait, release) + defer timer.Stop() + defer release() defer cancel() c.forward(ctx, gate, line, m) }) return done } -// await waits for gate to close, but for at most notificationWait. A nil gate has nothing to wait for. +// await waits for gate to close or ctx to be done. A nil gate has nothing to wait for. func await(ctx context.Context, gate <-chan struct{}) { if gate == nil { return } - t := time.NewTimer(notificationWait) - defer t.Stop() select { case <-gate: - case <-t.C: case <-ctx.Done(): } } @@ -260,7 +275,7 @@ func (c *conn) forward(ctx context.Context, gate <-chan struct{}, line []byte, m defer idle.Stop() x := &exchange{c: c, line: line, m: m, idle: idle} - if err := x.send(idleCtx, ctx, true); err != nil { + if err := x.send(idleCtx, ctx, m.isRequest()); err != nil { x.fail(idleCtx, ctx, err) } } @@ -278,12 +293,11 @@ func (c *conn) shutdown(ctx context.Context) { } c.cancelBase() <-done - c.deleteSession(ctx) + c.deleteSession(ctx, c.current()) } -// deleteSession ends the server-side session, best effort. -func (c *conn) deleteSession(ctx context.Context) { - sent := c.current() +// deleteSession ends the server-side session that sent names, best effort. +func (c *conn) deleteSession(ctx context.Context, sent upstreamState) { if sent.id == "" { return } @@ -448,6 +462,40 @@ func (c *conn) cancelRequest(line []byte) { } } +// lockRejoin takes the slot for a rejoin. A request queued behind a rejoin that is still running returns when its +// context is done. +func (c *conn) lockRejoin(ctx context.Context) error { + select { + case c.rejoinSlot <- struct{}{}: + return nil + case <-ctx.Done(): + return ctx.Err() + } +} + +// unlockRejoin releases the slot taken by lockRejoin. +func (c *conn) unlockRejoin() { + <-c.rejoinSlot +} + +// isEventStream reports whether a Content-Type is text/event-stream. The media type is case-insensitive. +func isEventStream(contentType string) bool { + mt, _, err := mime.ParseMediaType(contentType) + return err == nil && mt == eventStreamMIME +} + +// readBody reads a 2xx body of at most limit bytes. A longer body is an error, as an oversized stdin message is. +func readBody(r io.Reader, limit int) ([]byte, error) { + body, err := io.ReadAll(io.LimitReader(r, int64(limit)+1)) + if err != nil { + return nil, err + } + if len(body) > limit { + return nil, fmt.Errorf("an upstream message exceeds the %d MiB limit", limit>>20) + } + return body, nil +} + // idleBody resets the idle timer on every read, so a response is cut only after idleTimeout without data. type idleBody struct { io.ReadCloser @@ -495,6 +543,7 @@ func (x *exchange) recordProtocol(data []byte) error { // send posts the message and writes its answer. ctx is cancelled by the idle timeout; reqCtx is the request's // context, which hooks receive. func (x *exchange) send(ctx, reqCtx context.Context, retry bool) error { + x.status = 0 // an attempt that fails before a response has no status of its own sent := x.sending() resp, err := x.c.post(ctx, x.line, sent) if err != nil { @@ -506,7 +555,7 @@ func (x *exchange) send(ctx, reqCtx context.Context, retry bool) error { if resp.StatusCode/100 != 2 { return x.httpFailure(ctx, reqCtx, resp, sent.id, retry) } - if id := resp.Header.Get(sessionHeader); id != "" { + if id := resp.Header.Get(sessionHeader); id != "" && x.m.Method == methodInitialize { x.c.setSession(id) } if err := x.read(reqCtx, resp); err != nil { @@ -522,12 +571,14 @@ func (x *exchange) send(ctx, reqCtx context.Context, retry bool) error { // a 404 for a request that carried a session id means the server ended the session, so the client starts a new // one and posts the request once more. func (x *exchange) httpFailure(ctx, reqCtx context.Context, resp *http.Response, sent string, retry bool) error { - body, err := io.ReadAll(resp.Body) + body, err := io.ReadAll(io.LimitReader(resp.Body, maxErrorBytes)) if err != nil { return err } e := decodeErrorBody(body) - if e != nil && e.isResponseTo(x.m) { + // A 404 ends the session, unless its body is the result for the request. An error under 404 is the server's + // session-not-found answer, even when it carries the request's id. + if e != nil && e.isResponseTo(x.m) && (resp.StatusCode != http.StatusNotFound || e.Result != nil) { return x.deliverMessage(reqCtx, body, e.message) } if resp.StatusCode == http.StatusNotFound && sent != "" && retry { @@ -543,8 +594,10 @@ func (x *exchange) httpFailure(ctx, reqCtx context.Context, resp *http.Response, // replay succeeds. One rejoin runs at a time, and a request that finds the session already replaced just retries. func (x *exchange) rejoin(ctx context.Context, stale string) error { c := x.c - c.rejoinMu.Lock() - defer c.rejoinMu.Unlock() + if err := c.lockRejoin(ctx); err != nil { + return err + } + defer c.unlockRejoin() if c.current().id != stale { return nil } @@ -561,6 +614,10 @@ func (x *exchange) rejoin(ctx context.Context, stale string) error { } next, err := c.replay(ctx, x.idle, msgs) if err != nil { + if next.id != "" { + // The replay created a session that is not used. + c.deleteSession(ctx, next) + } return fmt.Errorf("start a new session: %w", err) } c.publish(next) @@ -568,12 +625,13 @@ func (x *exchange) rejoin(ctx context.Context, stale string) error { } // replay posts the client's handshake messages, in order, to a new session. Their answers are read here and not -// written to stdout. It returns the session and protocol version they establish. +// written to stdout. It returns the session and protocol version they establish, and on failure the session +// created so far. func (c *conn) replay(ctx context.Context, idle *time.Timer, msgs []clientMsg) (upstreamState, error) { var next upstreamState for _, msg := range msgs { if err := c.replayOne(ctx, idle, msg, &next); err != nil { - return upstreamState{}, err + return next, err } } return next, nil @@ -589,22 +647,18 @@ func (c *conn) replayOne(ctx context.Context, idle *time.Timer, msg clientMsg, n defer resp.Body.Close() resp.Body = idleBody{ReadCloser: resp.Body, idle: idle} if resp.StatusCode/100 != 2 { - body, err := io.ReadAll(resp.Body) + body, err := io.ReadAll(io.LimitReader(resp.Body, maxErrorBytes)) if err != nil { return err } - e := decodeErrorBody(body) - if e == nil || !e.isResponseTo(msg.m) { - return httpError(resp.StatusCode, body, e) - } - return recordProtocol(msg.m, body, next) + return httpError(resp.StatusCode, body, decodeErrorBody(body)) } - if id := resp.Header.Get(sessionHeader); id != "" { + if id := resp.Header.Get(sessionHeader); id != "" && msg.m.Method == methodInitialize { next.id = id } var answer []byte - if strings.HasPrefix(resp.Header.Get(contentTypeHeader), eventStreamMIME) { + if isEventStream(resp.Header.Get(contentTypeHeader)) { err = readEvents(resp.Body, func(data []byte) (bool, error) { m, err := parseMessage(data) if err != nil { @@ -618,7 +672,7 @@ func (c *conn) replayOne(ctx context.Context, idle *time.Timer, msg clientMsg, n }) } else { var body []byte - body, err = io.ReadAll(resp.Body) + body, err = readBody(resp.Body, maxLineBytes) if err == nil && len(bytes.TrimSpace(body)) > 0 && msg.m.isRequest() { m, perr := parseMessage(body) if perr != nil { @@ -639,30 +693,45 @@ func (c *conn) replayOne(ctx context.Context, idle *time.Timer, msg clientMsg, n if answer == nil { return errNoResponse } - return recordProtocol(msg.m, answer, next) + if msg.m.Method == methodInitialize { + return recordInitialize(answer, next) + } + return nil } -// recordProtocol sets next's protocol version from the result of an initialize response. -func recordProtocol(m message, data []byte, next *upstreamState) error { - if m.Method != methodInitialize { - return nil - } - v, ok, err := initializeProtocol(data) - if err != nil || !ok { +// recordInitialize sets next's protocol version from the result of an initialize answer. Without a result the +// session is not usable, so the replay fails. +func recordInitialize(answer []byte, next *upstreamState) error { + v, ok, err := initializeProtocol(answer) + if err != nil { return err } + if !ok { + return rejectedInitialize(answer) + } next.protocol = v return nil } +// rejectedInitialize is the error for an initialize answer without a result: the server's message when it has one. +func rejectedInitialize(answer []byte) error { + var r struct { + Error *rpcError `json:"error"` + } + if err := json.Unmarshal(answer, &r); err == nil && r.Error != nil { + return fmt.Errorf("the server rejected initialize: %s", r.Error.Message) + } + return fmt.Errorf("initialize has no result: %s", excerpt(answer)) +} + // read delivers the messages in a 2xx response: an event stream, or one JSON body. func (x *exchange) read(reqCtx context.Context, resp *http.Response) error { - if strings.HasPrefix(resp.Header.Get(contentTypeHeader), eventStreamMIME) { + if isEventStream(resp.Header.Get(contentTypeHeader)) { return readEvents(resp.Body, func(data []byte) (bool, error) { return x.deliverEvent(reqCtx, data) }) } - body, err := io.ReadAll(resp.Body) + body, err := readBody(resp.Body, maxLineBytes) if err != nil { return err } @@ -773,11 +842,20 @@ func httpError(status int, body []byte, e *errorBody) error { return fmt.Errorf("HTTP %d: %s", status, text) } -// excerpt returns body as a single line, cut to excerptRunes characters. +// excerpt returns the start of body as a single line of at most excerptRunes characters. Only the first excerptBytes +// bytes are converted. func excerpt(body []byte) string { + cut := len(body) > excerptBytes + if cut { + body = body[:excerptBytes] + } r := []rune(strings.Join(strings.Fields(string(body)), " ")) if len(r) > excerptRunes { - return string(r[:excerptRunes]) + "..." + r = r[:excerptRunes] + cut = true + } + if cut { + return string(r) + "..." } return string(r) } diff --git a/libs/aitools/mcp/proxy/bridge_test.go b/libs/aitools/mcp/proxy/bridge_test.go index 66faec153e4..537706761aa 100644 --- a/libs/aitools/mcp/proxy/bridge_test.go +++ b/libs/aitools/mcp/proxy/bridge_test.go @@ -1053,10 +1053,10 @@ func TestRunRequestDuringRejoinUsesNewSession(t *testing.T) { assert.Equal(t, []string{"s1", "s2"}, sessionsSent(fake, `"id":2,`)) } -// TestRunAnswersRequestEndedBy404WithResponse: a 404 whose body is the server's response to the request is not an -// ended session, so the request is not posted again and no new session starts. -func TestRunAnswersRequestEndedBy404WithResponse(t *testing.T) { - const response = `{"jsonrpc":"2.0","id":2,"error":{"code":-32001,"message":"unknown tool"}}` +// TestRunAnswers404ResultWithoutNewSession: a 404 whose body is the server's result for the request is the answer, +// so the request is not posted again and no new session starts. +func TestRunAnswers404ResultWithoutNewSession(t *testing.T) { + const response = `{"jsonrpc":"2.0","id":2,"result":{"content":[]}}` srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { if r.Method == http.MethodDelete { return @@ -1294,3 +1294,500 @@ func TestRunSendsInitializeWithoutSession(t *testing.T) { assert.Empty(t, reqs[1].Header.Get(sessionHeader)) assert.Empty(t, reqs[1].Header.Get(protocolHeader)) } + +// writeInit answers an initialize request with the given session id and protocol version 2025-06-18. +func writeInit(w http.ResponseWriter, m message, sid string) { + w.Header().Set(contentTypeHeader, jsonMIME) + w.Header().Set(sessionHeader, sid) + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"protocolVersion":"2025-06-18"}}`, m.ID) +} + +// TestRunRecoversAfterReplayAnswerIsAnError: an initialize answered with a JSON-RPC error is not a replay that +// succeeded, whether it comes with 200 or with a 401. The next request starts the replay again. +func TestRunRecoversAfterReplayAnswerIsAnError(t *testing.T) { + cases := []struct { + name string + status int + body string + wantError string + }{ + { + name: "200 with a JSON-RPC error", + status: http.StatusOK, + body: `{"jsonrpc":"2.0","id":%s,"error":{"code":-32602,"message":"unsupported protocol version"}}`, + wantError: "unsupported protocol version", + }, + { + name: "401 with a JSON-RPC error", + status: http.StatusUnauthorized, + body: `{"jsonrpc":"2.0","id":%s,"error":{"code":-32006,"message":"sign in"}}`, + wantError: "HTTP 401: sign in", + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + var mu sync.Mutex + starts := 0 + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + sid := r.Header.Get(sessionHeader) + switch { + case m.Method == methodInitialize: + mu.Lock() + starts++ + n := starts + mu.Unlock() + if n == 2 { + w.Header().Set(contentTypeHeader, jsonMIME) + w.WriteHeader(tc.status) + fmt.Fprintf(w, tc.body, m.ID) + return + } + writeInit(w, m, fmt.Sprintf("s%d", n)) + case !m.isRequest(): + w.WriteHeader(http.StatusAccepted) + case sid == "s1": + http.Error(w, "session not found", http.StatusNotFound) + default: + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + } + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + p.waitLines(t, 2) + p.send(t, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`) + out := p.waitLines(t, 3) + require.NoError(t, p.finish(t)) + + failed := parseReply(t, out[1]) + assert.JSONEq(t, `2`, string(failed.ID)) + require.NotNil(t, failed.Error) + assert.Contains(t, failed.Error.Message, "start a new session") + assert.Contains(t, failed.Error.Message, tc.wantError) + recovered := parseReply(t, out[2]) + assert.JSONEq(t, `3`, string(recovered.ID)) + assert.Nil(t, recovered.Error) + assert.Equal(t, []string{"s1", "s3"}, sessionsSent(fake, `"id":3,`), + "the second replay starts after the first failed; the request is posted to each session once") + }) + } +} + +// TestRunTakesSessionOnlyFromInitialize: a late answer on an ended session carries that session's id. The id must +// not replace the session that a rejoin has started. +func TestRunTakesSessionOnlyFromInitialize(t *testing.T) { + held := make(chan struct{}) + release := make(chan struct{}) + releaseOnce := sync.OnceFunc(func() { close(release) }) + t.Cleanup(releaseOnce) + var mu sync.Mutex + starts := 0 + current := "s1" + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + if m.Method == methodInitialize { + mu.Lock() + starts++ + current = fmt.Sprintf("s%d", starts) + sid := current + mu.Unlock() + writeInit(w, m, sid) + return + } + if !m.isRequest() { + w.WriteHeader(http.StatusAccepted) + return + } + mu.Lock() + if string(m.ID) == "2" && current == "s1" && r.Header.Get(sessionHeader) == "s1" { + current = "" // the server ends s1 on request 2 + } + accepted := current != "" && r.Header.Get(sessionHeader) == current + mu.Unlock() + if !accepted { + http.Error(w, "session not found", http.StatusNotFound) + return + } + w.Header().Set(contentTypeHeader, jsonMIME) + if string(m.ID) == "5" { + close(held) + <-release + w.Header().Set(sessionHeader, "s1") + } + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":5,"method":"tools/call"}`) + waitClosed(t, held, "request 5 to reach the endpoint") + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/call"}`) + p.waitLines(t, 2) + releaseOnce() + p.waitLines(t, 3) + p.send(t, `{"jsonrpc":"2.0","id":6,"method":"tools/call"}`) + p.waitLines(t, 4) + require.NoError(t, p.finish(t)) + + assert.Equal(t, []string{"s2"}, sessionsSent(fake, `"id":6,`), "request 6 uses the session the rejoin started") +} + +// TestRunDoesNotRejoinForNotificationOrClientResponse: a 404 for a notification or a client response is reported, +// and the session is not restarted to post it again. +func TestRunDoesNotRejoinForNotificationOrClientResponse(t *testing.T) { + cases := []struct { + name string + line string + marker string + }{ + {name: "notification", line: initializedLine, marker: `"method":"notifications/initialized"`}, + {name: "client response", line: `{"jsonrpc":"2.0","id":9,"result":{}}`, marker: `"id":9,`}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + switch { + case m.Method == methodInitialize: + writeInit(w, m, "s1") + case r.Header.Get(sessionHeader) == "s1": + http.Error(w, "session not found", http.StatusNotFound) + default: + w.WriteHeader(http.StatusAccepted) + } + }) + + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, tc.line) + require.NoError(t, p.finish(t)) + + require.Len(t, outLines(p.out.String()), 1, "only the initialize answer is written") + assert.Contains(t, p.err.String(), "HTTP 404: session not found") + assert.Len(t, sessionsSent(fake, `"method":"initialize"`), 1, "the session was not restarted") + assert.Len(t, sessionsSent(fake, tc.marker), 1, "the message was posted once") + }) + } +} + +// TestRunSkipsEventsOfOtherTypes: an event whose type is not message is not a JSON-RPC message, so a keepalive does +// not end the request. +func TestRunSkipsEventsOfOtherTypes(t *testing.T) { + const response = `{"jsonrpc":"2.0","id":1,"result":{}}` + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set(contentTypeHeader, "text/event-stream") + _, _ = io.WriteString(w, "event: ping\ndata: ping\n\nevent: keepalive\ndata: {}\n\ndata: "+response+"\n\n") + }) + + out, errOut := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`+"\n") + + assert.Equal(t, []string{response}, out) + assert.Empty(t, errOut) +} + +// TestRunReadsEventStreamWithAnyCaseMediaType: the media type of a stream is case-insensitive. +func TestRunReadsEventStreamWithAnyCaseMediaType(t *testing.T) { + const response = `{"jsonrpc":"2.0","id":1,"result":{}}` + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set(contentTypeHeader, "Text/Event-Stream; charset=utf-8") + _, _ = io.WriteString(w, "data: "+response+"\n\n") + }) + + out, errOut := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`+"\n") + + assert.Equal(t, []string{response}, out) + assert.Empty(t, errOut) +} + +// TestRunDoesNotFollowRedirects: a redirect is a failed response with its status. Following it would post the +// message to the target, or turn a POST into a GET of a login page. +func TestRunDoesNotFollowRedirects(t *testing.T) { + for _, status := range []int{ + http.StatusMovedPermanently, http.StatusFound, http.StatusSeeOther, + http.StatusTemporaryRedirect, http.StatusPermanentRedirect, + } { + t.Run(http.StatusText(status), func(t *testing.T) { + var loginHit atomic.Bool + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path == "/login" { + loginHit.Store(true) + w.Header().Set(contentTypeHeader, "text/html") + _, _ = io.WriteString(w, "sign in") + return + } + w.Header().Set("Location", "/login") + w.WriteHeader(status) + }) + + out, _ := runAll(t, bridgeFor(srv.URL+"/mcp"), `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`+"\n") + + require.Len(t, out, 1) + reply := parseReply(t, out[0]) + require.NotNil(t, reply.Error) + assert.Contains(t, reply.Error.Message, fmt.Sprintf("HTTP %d", status)) + assert.False(t, loginHit.Load(), "the redirect target was not requested") + }) + } +} + +// TestAwaitWaitsOnlyForGateOrContext: a request waits for the notification before it and nothing else. A timer of +// its own would release it while the notification is still pending. +func TestAwaitWaitsOnlyForGateOrContext(t *testing.T) { + setNotificationWait(t, time.Millisecond) + gate := make(chan struct{}) + returned := make(chan struct{}) + go func() { + await(t.Context(), gate) + close(returned) + }() + select { + case <-returned: + t.Fatal("await returned while the notification was still pending") + case <-time.After(100 * time.Millisecond): + } + close(gate) + waitClosed(t, returned, "await to return once the gate is closed") +} + +// TestRunStartsNewSessionWhen404CarriesError: a session-not-found answer carries the request's id with an error, and it +// still ends the session. The request is answered by the new session. +func TestRunStartsNewSessionWhen404CarriesError(t *testing.T) { + var mu sync.Mutex + starts := 0 + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + switch { + case m.Method == methodInitialize: + mu.Lock() + starts++ + sid := fmt.Sprintf("s%d", starts) + mu.Unlock() + writeInit(w, m, sid) + case !m.isRequest(): + w.WriteHeader(http.StatusAccepted) + case r.Header.Get(sessionHeader) == "s1": + w.Header().Set(contentTypeHeader, jsonMIME) + w.WriteHeader(http.StatusNotFound) + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"error":{"code":-32001,"message":"Session not found"}}`, m.ID) + default: + w.Header().Set(contentTypeHeader, jsonMIME) + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + } + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + out := p.waitLines(t, 2) + require.NoError(t, p.finish(t)) + + reply := parseReply(t, out[1]) + assert.JSONEq(t, `2`, string(reply.ID)) + assert.Nil(t, reply.Error, out[1]) + assert.Equal(t, []string{"s1", "s2"}, sessionsSent(fake, `"id":2,`)) +} + +// TestRunCancelsRequestByExactID: request ids that differ only above 2^53 are distinct, so cancelling one does not +// cancel the other. +func TestRunCancelsRequestByExactID(t *testing.T) { + const idA = "9007199254740993" // 2^53 + 1 + const idB = "9007199254740992" // 2^53 + started := make(chan struct{}) + cancelled := make(chan struct{}) + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + if !m.isRequest() { + w.WriteHeader(http.StatusAccepted) + return + } + w.Header().Set(contentTypeHeader, jsonMIME) + if string(m.ID) == idA { + close(started) + <-r.Context().Done() + close(cancelled) + return + } + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, `{"jsonrpc":"2.0","id":`+idA+`,"method":"tools/call"}`) + waitClosed(t, started, "request A to reach the endpoint") + p.send(t, `{"jsonrpc":"2.0","id":`+idB+`,"method":"tools/call"}`) + out := p.waitLines(t, 1) + p.send(t, `{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":`+idA+`}}`) + waitClosed(t, cancelled, "request A to be cancelled") + require.NoError(t, p.finish(t)) + + require.Len(t, out, 1) + assert.JSONEq(t, idB, string(parseReply(t, out[0]).ID)) +} + +// TestRunReportsStatusOfRetriedRequest: a retry that fails before any response reports status 0 to the hooks, not +// the 404 of the first attempt. +func TestRunReportsStatusOfRetriedRequest(t *testing.T) { + statuses := make(chan int, 2) + var mu sync.Mutex + starts := 0 + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + switch { + case m.Method == methodInitialize: + mu.Lock() + starts++ + sid := fmt.Sprintf("s%d", starts) + mu.Unlock() + writeInit(w, m, sid) + case !m.isRequest(): + w.WriteHeader(http.StatusAccepted) + case r.Header.Get(sessionHeader) == "s1": + http.Error(w, "session not found", http.StatusNotFound) + default: + panic(http.ErrAbortHandler) // the connection is cut before any response + } + }) + b := bridgeFor(srv.URL) + b.Hooks = hookFunc(func(_ context.Context, _ []byte, status int, msg []byte) ([][]byte, error) { + if bytes.Contains(msg, []byte(`"error"`)) { + statuses <- status + } + return [][]byte{msg}, nil + }) + p := startPiped(t, t.Context(), b) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + out := p.waitLines(t, 2) + require.NoError(t, p.finish(t)) + + assert.Contains(t, parseReply(t, out[1]).Error.Message, "MCP upstream error") + assert.Equal(t, 0, <-statuses, "the retry had no response") +} + +// TestRunDeletesSessionOfFailedReplay: a replay whose initialize created a session and whose initialized +// notification failed leaves that session on the server, so the bridge deletes it. +func TestRunDeletesSessionOfFailedReplay(t *testing.T) { + var mu sync.Mutex + starts := 0 + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + sid := r.Header.Get(sessionHeader) + switch { + case m.Method == methodInitialize: + mu.Lock() + starts++ + n := starts + mu.Unlock() + writeInit(w, m, fmt.Sprintf("s%d", n)) + case m.Method == methodInitialized && sid == "s2": + http.Error(w, "boom", http.StatusInternalServerError) + case !m.isRequest(): + w.WriteHeader(http.StatusAccepted) + case sid == "s1": + http.Error(w, "session not found", http.StatusNotFound) + default: + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + } + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + out := p.waitLines(t, 2) + require.NoError(t, p.finish(t)) + + assert.Contains(t, parseReply(t, out[1]).Error.Message, "start a new session") + var deleted []string + for _, r := range fake.requests() { + if r.Method == http.MethodDelete { + deleted = append(deleted, r.Header.Get(sessionHeader)) + } + } + assert.Contains(t, deleted, "s2", "the session of the failed replay is deleted") +} + +// TestRunUsesConfiguredTransport: the upstream requests go through Transport, so a profile's TLS settings apply. +func TestRunUsesConfiguredTransport(t *testing.T) { + srv := httptest.NewTLSServer(http.HandlerFunc(answer)) + t.Cleanup(srv.Close) + b := bridgeFor(srv.URL) + b.Transport = srv.Client().Transport + + out, errOut := runAll(t, b, `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`+"\n") + + require.Len(t, out, 1) + assert.JSONEq(t, `1`, string(parseReply(t, out[0]).ID)) + assert.Empty(t, errOut) +} + +// TestLockRejoinHonorsContext: a request queued behind a rejoin that is still running returns when its context is +// cancelled, rather than waiting for the rejoin. +func TestLockRejoinHonorsContext(t *testing.T) { + c := &conn{rejoinSlot: make(chan struct{}, 1)} + c.rejoinSlot <- struct{}{} // a rejoin is running + ctx, cancel := context.WithCancel(t.Context()) + locked := make(chan error, 1) + go func() { locked <- c.lockRejoin(ctx) }() + cancel() + + select { + case err := <-locked: + require.ErrorIs(t, err, context.Canceled) + case <-time.After(10 * time.Second): + t.Fatal("lockRejoin did not return after the context was cancelled") + } +} + +// TestRunAnswersOversizedUpstreamBody: a 2xx JSON body is limited like a stdin message, so an oversized one is an +// error for its request and is not written. +func TestRunAnswersOversizedUpstreamBody(t *testing.T) { + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set(contentTypeHeader, jsonMIME) + _, _ = io.WriteString(w, `{"jsonrpc":"2.0","id":1,"result":{"text":"`+strings.Repeat("a", maxLineBytes)+`"}}`) + }) + + out, _ := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","id":1,"method":"tools/list"}`+"\n") + + require.Len(t, out, 1) + reply := parseReply(t, out[0]) + require.NotNil(t, reply.Error) + assert.Contains(t, reply.Error.Message, "64 MiB limit") +} diff --git a/libs/aitools/mcp/proxy/messages.go b/libs/aitools/mcp/proxy/messages.go index e67a7a96e65..5ebe26824b0 100644 --- a/libs/aitools/mcp/proxy/messages.go +++ b/libs/aitools/mcp/proxy/messages.go @@ -5,7 +5,7 @@ import ( "encoding/json" "errors" "fmt" - "strconv" + "math/big" ) // Method names and member names the bridge reads or edits. @@ -35,13 +35,14 @@ type message struct { } // errorBody is a non-2xx response body: the envelope of a JSON-RPC response, and the message of either a -// JSON-RPC error or a Databricks error body. +// JSON-RPC error or a Databricks error body. Result is set when the body is a JSON-RPC result. type errorBody struct { message Message string `json:"message"` Error struct { Message string `json:"message"` } `json:"error"` + Result json.RawMessage `json:"result"` } // rpcError is the error object of a JSON-RPC error response. @@ -91,16 +92,20 @@ func (m message) isResponseTo(request message) bool { return m.Method == "" && request.isRequest() && idKey(m.ID) == idKey(request.ID) } -// idKey returns the key that identifies a JSON-RPC id by its decoded value: a string by its text, and a -// number by its value, so 7 and 7.0 match. An id that is not a string or number is keyed by its bytes. +// idKey returns the key that identifies a JSON-RPC id by its value: a string by its text, and a number by its exact +// value, so 7 and 7.0 match while integers above 2^53 stay distinct. Any other id is keyed by its bytes. func idKey(raw json.RawMessage) string { + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.UseNumber() var v any - _ = json.Unmarshal(raw, &v) // an empty or invalid id has no value and keeps its bytes as the key + _ = dec.Decode(&v) // an empty or invalid id has no value and keeps its bytes as the key switch v := v.(type) { case string: return "s" + v - case float64: - return "n" + strconv.FormatFloat(v, 'g', -1, 64) + case json.Number: + if r, ok := new(big.Rat).SetString(v.String()); ok { + return "n" + r.RatString() + } } return string(raw) } diff --git a/libs/aitools/mcp/proxy/messages_test.go b/libs/aitools/mcp/proxy/messages_test.go index c835b946579..bb8af49406d 100644 --- a/libs/aitools/mcp/proxy/messages_test.go +++ b/libs/aitools/mcp/proxy/messages_test.go @@ -116,6 +116,8 @@ func TestIsResponseToComparesIDsByValue(t *testing.T) { {name: "number with fraction", request: `7`, response: `7.0`, want: true}, {name: "string is not a number", request: `"7"`, response: `7`}, {name: "different id", request: `1`, response: `2`}, + {name: "large integers that differ", request: `9007199254740993`, response: `9007199254740992`}, + {name: "large integers that are equal", request: `9007199254740993`, response: `9007199254740993.0`, want: true}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { diff --git a/libs/aitools/mcp/proxy/sse.go b/libs/aitools/mcp/proxy/sse.go index 3202a1a3866..e480f791c7d 100644 --- a/libs/aitools/mcp/proxy/sse.go +++ b/libs/aitools/mcp/proxy/sse.go @@ -6,11 +6,13 @@ import ( "io" ) +// messageEvent is the event type of a JSON-RPC message. An event with no type is a message too. +const messageEvent = "message" + // readEvents calls fn with the data of each event in a text/event-stream body, in order, until fn returns -// false. Multi-line data is joined with newlines. An event left open at the end of the stream is still -// delivered. An event whose data is empty is skipped: a server sends one with an id and no data first, to -// prime a client to resume (https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server). id, -// event and comment lines are ignored. +// false. Multi-line data is joined with newlines, and an event left open at the end is still delivered. Only +// events of type message, or with no type, are delivered. An event with empty data is skipped, such as the +// priming event a server sends before a resumable stream. func readEvents(r io.Reader, fn func([]byte) (bool, error)) error { sc := bufio.NewScanner(r) sc.Buffer(nil, maxLineBytes) @@ -23,11 +25,17 @@ func readEvents(r io.Reader, fn func([]byte) (bool, error)) error { } continue } - field, value, _ := bytes.Cut(line, []byte{':'}) - if line[0] == ':' || string(field) != "data" { + if line[0] == ':' { continue } - ev.add(bytes.TrimPrefix(value, []byte{' '})) + field, value, _ := bytes.Cut(line, []byte{':'}) + value = bytes.TrimPrefix(value, []byte{' '}) + switch string(field) { + case "data": + ev.add(value) + case "event": + ev.typ = string(value) + } } if err := sc.Err(); err != nil { return err @@ -36,8 +44,9 @@ func readEvents(r io.Reader, fn func([]byte) (bool, error)) error { return err } -// event collects the data lines of one text/event-stream event. +// event collects the data lines and the type of one text/event-stream event. type event struct { + typ string data []byte hasData bool } @@ -53,9 +62,9 @@ func (e *event) add(line []byte) { // dispatch passes the event's data to fn and clears the event. It reports whether fn wants more events. func (e *event) dispatch(fn func([]byte) (bool, error)) (bool, error) { - data := e.data + data, typ := e.data, e.typ *e = event{} - if len(bytes.TrimSpace(data)) == 0 { + if (typ != "" && typ != messageEvent) || len(bytes.TrimSpace(data)) == 0 { return true, nil } return fn(data) diff --git a/libs/aitools/mcp/proxy/sse_test.go b/libs/aitools/mcp/proxy/sse_test.go index 0eec2d7ea27..1d7ddb09c66 100644 --- a/libs/aitools/mcp/proxy/sse_test.go +++ b/libs/aitools/mcp/proxy/sse_test.go @@ -22,6 +22,7 @@ func TestReadEvents(t *testing.T) { {name: "no data", stream: "event: x\n\n"}, {name: "event with empty data is skipped", stream: "id: 1\ndata:\n\nid: 2\ndata: 2\n\n", want: []string{"2"}}, {name: "empty data at end of stream is skipped", stream: "data: 1\n\nid: 2\ndata:", want: []string{"1"}}, + {name: "events of other types are skipped", stream: "event: ping\ndata: ping\n\nevent: message\ndata: 1\n\n", want: []string{"1"}}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { From 656011afc8cabafb332544743ac0297170650495 Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Thu, 12 Nov 2026 23:53:14 +0000 Subject: [PATCH 6/7] Refactor the MCP bridge helpers and comments (pass 4) No behavior change, except that an id number is keyed from its text, which keeps a large exponent short. Upstream message parsing and the response check are one helper each, the replay and the session DELETE share their error paths, the unused rejoin branch for a missing initialize is gone, and doc comments are trimmed. The rejoin and idle-watchdog docs say what the replay restores and when the watchdog starts. Co-authored-by: Isaac --- libs/aitools/mcp/proxy/bridge.go | 104 +++++++++++++++--------- libs/aitools/mcp/proxy/messages.go | 48 +++++++++-- libs/aitools/mcp/proxy/messages_test.go | 21 +++++ 3 files changed, 126 insertions(+), 47 deletions(-) diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go index 1cfa6766fae..5d50cf3501c 100644 --- a/libs/aitools/mcp/proxy/bridge.go +++ b/libs/aitools/mcp/proxy/bridge.go @@ -82,9 +82,8 @@ type Bridge struct { Transport http.RoundTripper } -// Run forwards stdin to the endpoint until stdin closes or ctx is done. Shutdown waits up to 2 s for -// in-flight requests, cancels the rest, and sends DELETE for the session. Run returns an error only -// when reading stdin fails. +// Run forwards stdin to the endpoint until stdin closes or ctx is done. It returns an error only when reading stdin +// fails. func (b *Bridge) Run(ctx context.Context) error { base, cancelBase := context.WithCancel(context.WithoutCancel(ctx)) c := &conn{ @@ -206,10 +205,8 @@ func newClient(rt http.RoundTripper) *http.Client { } } -// handle starts one stdin message and returns the gate for the next one. A request or notification runs in -// its own goroutine. Each message waits for the notification before it (see await), so the server sees -// notifications in order: the lifecycle needs notifications/initialized before the first request. A -// notification's gate is the channel that closes when its POST has finished. +// handle starts one stdin message and returns the gate for the next one. Each message waits for the notification +// before it (see await), so the server sees the lifecycle in order. func (c *conn) handle(base context.Context, gate <-chan struct{}, line []byte) <-chan struct{} { m, err := parseMessage(line) if err != nil { @@ -266,7 +263,8 @@ func await(ctx context.Context, gate <-chan struct{}) { } // forward waits (see await), then POSTs one client message exactly as received and writes what the upstream -// answers. The idle watchdog covers every response, plain JSON included. +// answers. The idle watchdog covers every response, plain JSON included. It starts before the POST, so it also +// bounds the wait for response headers, and the run time of a hook counts toward it. func (c *conn) forward(ctx context.Context, gate <-chan struct{}, line []byte, m message) { await(ctx, gate) idleCtx, cancel := context.WithCancelCause(ctx) @@ -296,24 +294,30 @@ func (c *conn) shutdown(ctx context.Context) { c.deleteSession(ctx, c.current()) } -// deleteSession ends the server-side session that sent names, best effort. +// deleteSession ends the session sent, best effort. func (c *conn) deleteSession(ctx context.Context, sent upstreamState) { if sent.id == "" { return } ctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), deleteTimeout) defer cancel() + if err := c.sendDelete(ctx, sent); err != nil { + c.logf("session DELETE: %v", err) + } +} + +// sendDelete sends the DELETE that ends the session sent. +func (c *conn) sendDelete(ctx context.Context, sent upstreamState) error { req, err := c.newRequest(ctx, http.MethodDelete, nil, sent) if err != nil { - c.logf("session DELETE: %v", err) - return + return err } resp, err := c.client.Do(req) if err != nil { - c.logf("session DELETE: %v", err) - return + return err } resp.Body.Close() + return nil } // post sends one JSON-RPC message to the endpoint. @@ -592,6 +596,8 @@ func (x *exchange) httpFailure(ctx, reqCtx context.Context, resp *http.Response, // rejoin starts a new session after the server ended stale. The new session replaces the current one only when the // replay succeeds. One rejoin runs at a time, and a request that finds the session already replaced just retries. +// The replay sends only initialize and notifications/initialized, so session state set later (a logging level, +// subscriptions) is not restored. func (x *exchange) rejoin(ctx context.Context, stale string) error { c := x.c if err := c.lockRejoin(ctx); err != nil { @@ -605,9 +611,6 @@ func (x *exchange) rejoin(ctx context.Context, stale string) error { c.mu.Lock() init, initialized := c.initialize, c.initialized c.mu.Unlock() - if init.line == nil { - return errors.New("the server ended the session, and no initialize request was sent to replay") - } msgs := []clientMsg{init} if initialized.line != nil { msgs = append(msgs, initialized) @@ -647,11 +650,7 @@ func (c *conn) replayOne(ctx context.Context, idle *time.Timer, msg clientMsg, n defer resp.Body.Close() resp.Body = idleBody{ReadCloser: resp.Body, idle: idle} if resp.StatusCode/100 != 2 { - body, err := io.ReadAll(io.LimitReader(resp.Body, maxErrorBytes)) - if err != nil { - return err - } - return httpError(resp.StatusCode, body, decodeErrorBody(body)) + return statusError(resp) } if id := resp.Header.Get(sessionHeader); id != "" && msg.m.Method == methodInitialize { next.id = id @@ -660,9 +659,9 @@ func (c *conn) replayOne(ctx context.Context, idle *time.Timer, msg clientMsg, n var answer []byte if isEventStream(resp.Header.Get(contentTypeHeader)) { err = readEvents(resp.Body, func(data []byte) (bool, error) { - m, err := parseMessage(data) + m, err := parseUpstream(data) if err != nil { - return false, fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) + return false, err } if m.isResponseTo(msg.m) { answer = data @@ -674,14 +673,9 @@ func (c *conn) replayOne(ctx context.Context, idle *time.Timer, msg clientMsg, n var body []byte body, err = readBody(resp.Body, maxLineBytes) if err == nil && len(bytes.TrimSpace(body)) > 0 && msg.m.isRequest() { - m, perr := parseMessage(body) - if perr != nil { - return fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", perr) + if _, err = responseBody(body, msg.m); err == nil { + answer = body } - if !m.isResponseTo(msg.m) { - return fmt.Errorf("upstream sent %s instead of the response to the request", excerpt(body)) - } - answer = body } } if err != nil { @@ -743,12 +737,9 @@ func (x *exchange) read(reqCtx context.Context, resp *http.Response) error { x.c.logf("upstream sent a JSON body for a notification or client response; it is not forwarded") return nil } - msg, err := parseMessage(body) + msg, err := responseBody(body, x.m) if err != nil { - return fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) - } - if !msg.isResponseTo(x.m) { - return fmt.Errorf("upstream sent %s instead of the response to the request", excerpt(body)) + return err } return x.deliverMessage(reqCtx, body, msg) } @@ -756,9 +747,9 @@ func (x *exchange) read(reqCtx context.Context, resp *http.Response) error { // deliverEvent handles one event of a 2xx event stream. It reports false once the response is written, since the // server SHOULD end the stream after it (https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#sending-messages-to-the-server). func (x *exchange) deliverEvent(reqCtx context.Context, data []byte) (bool, error) { - msg, err := parseMessage(data) + msg, err := parseUpstream(data) if err != nil { - return false, fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) + return false, err } if err := x.deliverMessage(reqCtx, data, msg); err != nil { return false, err @@ -817,18 +808,53 @@ func (x *exchange) fail(ctx, reqCtx context.Context, err error) { case cause != nil: return } - x.c.logf("upstream: %v", err) + x.c.logUpstream(err) if !x.m.isRequest() || x.answered { return } msg := errorResponse(x.m.ID, codeUpstream, fmt.Sprintf("MCP upstream error for request %s: %v", x.m.ID, err)) if derr := x.deliver(reqCtx, msg); derr != nil { // The hook failed too; the client still needs an answer, so write the error unhooked. - x.c.logf("upstream: %v", derr) + x.c.logUpstream(derr) x.c.reply(msg) } } +// logUpstream logs an error from the upstream. +func (c *conn) logUpstream(err error) { + c.logf("upstream: %v", err) +} + +// parseUpstream parses one message the upstream sent. +func parseUpstream(data []byte) (message, error) { + m, err := parseMessage(data) + if err != nil { + return m, fmt.Errorf("upstream sent an invalid JSON-RPC message: %w", err) + } + return m, nil +} + +// responseBody parses a JSON body that must be the response to request. Any other message is an error that names it. +func responseBody(body []byte, request message) (message, error) { + m, err := parseUpstream(body) + if err != nil { + return m, err + } + if !m.isResponseTo(request) { + return m, fmt.Errorf("upstream sent %s instead of the response to the request", excerpt(body)) + } + return m, nil +} + +// statusError is the error for a non-2xx response, read as httpFailure reads one. +func statusError(resp *http.Response) error { + body, err := io.ReadAll(io.LimitReader(resp.Body, maxErrorBytes)) + if err != nil { + return err + } + return httpError(resp.StatusCode, body, decodeErrorBody(body)) +} + // httpError describes a non-2xx response: its status, then the message of a JSON error body, or an excerpt of // any other body. func httpError(status int, body []byte, e *errorBody) error { diff --git a/libs/aitools/mcp/proxy/messages.go b/libs/aitools/mcp/proxy/messages.go index 5ebe26824b0..63e26bb3069 100644 --- a/libs/aitools/mcp/proxy/messages.go +++ b/libs/aitools/mcp/proxy/messages.go @@ -2,10 +2,12 @@ package proxy import ( "bytes" + "cmp" "encoding/json" "errors" "fmt" - "math/big" + "strconv" + "strings" ) // Method names and member names the bridge reads or edits. @@ -21,8 +23,8 @@ const ( keyListChanged = "listChanged" ) -// errNotObject is returned for valid JSON whose top-level value is not an object. var ( + // errNotObject is returned for valid JSON whose top-level value is not an object. errNotObject = errors.New("message is not a JSON object") jsonNull = json.RawMessage("null") ) @@ -72,7 +74,8 @@ func parseMessage(line []byte) (message, error) { return m, nil } -// decodeErrorBody decodes a non-2xx body. It returns nil when the body is not a JSON object. +// decodeErrorBody decodes a non-2xx body. It returns nil when the body does not decode as an object; a null body +// decodes to an empty errorBody. func decodeErrorBody(body []byte) *errorBody { var e errorBody if json.Unmarshal(body, &e) != nil { @@ -103,13 +106,42 @@ func idKey(raw json.RawMessage) string { case string: return "s" + v case json.Number: - if r, ok := new(big.Rat).SetString(v.String()); ok { - return "n" + r.RatString() - } + return "n" + numberKey(v.String()) } return string(raw) } +// numberKey returns the key of a JSON number by its value: its significant digits and the power of ten they are +// scaled by, so 7, 7.0 and 70e-1 share one key and -0 is 0. It works on the text, so an exponent such as 1e1000000 +// costs no more than its digits. An exponent that does not fit an int64 is keyed by the text. +func numberKey(s string) string { + s = strings.ToLower(s) + neg := strings.HasPrefix(s, "-") + mant, exp, _ := strings.Cut(strings.TrimPrefix(s, "-"), "e") + whole, frac, _ := strings.Cut(mant, ".") + scale, err := strconv.ParseInt(cmp.Or(exp, "0"), 10, 64) + if err != nil { + return s + } + scale -= int64(len(frac)) + digits := strings.TrimLeft(whole+frac, "0") + if digits == "" { + return "0" + } + trimmed := strings.TrimRight(digits, "0") + scale += int64(len(digits) - len(trimmed)) + sign := "" + if neg { + sign = "-" + } + return sign + trimmed + "e" + strconv.FormatInt(scale, 10) +} + +// initializeResultError wraps an error found while reading an initialize result. +func initializeResultError(err error) error { + return fmt.Errorf("initialize result: %w", err) +} + // initializeProtocol returns the protocol version in the result of an initialize response. ok is false when the // response has no result. func initializeProtocol(data []byte) (version string, ok bool, err error) { @@ -119,7 +151,7 @@ func initializeProtocol(data []byte) (version string, ok bool, err error) { } `json:"result"` } if err := json.Unmarshal(data, &r); err != nil { - return "", false, fmt.Errorf("initialize result: %w", err) + return "", false, initializeResultError(err) } if r.Result == nil { return "", false, nil @@ -149,7 +181,7 @@ func editInitialize(msg []byte, instructions string, listChanged bool) ([]byte, } result, err := decodeObject(env[keyResult]) if err != nil { - return nil, fmt.Errorf("initialize result: %w", err) + return nil, initializeResultError(err) } if instructions != "" { var prev string diff --git a/libs/aitools/mcp/proxy/messages_test.go b/libs/aitools/mcp/proxy/messages_test.go index bb8af49406d..0676fd76cb7 100644 --- a/libs/aitools/mcp/proxy/messages_test.go +++ b/libs/aitools/mcp/proxy/messages_test.go @@ -1,6 +1,7 @@ package proxy import ( + "encoding/json" "testing" "github.com/stretchr/testify/assert" @@ -125,3 +126,23 @@ func TestIsResponseToComparesIDsByValue(t *testing.T) { }) } } + +// TestIDKeyComparesNumbersByValue: numbers match by value in any spelling, and a large exponent is keyed by its +// digits, so the key stays short. +func TestIDKeyComparesNumbersByValue(t *testing.T) { + same := [][2]string{ + {"7", "7.0"}, {"7", "70e-1"}, {"7", "7E0"}, {"-0", "0"}, {"0.0", "0e5"}, + {"1.5", "15e-1"}, {"100", "1e2"}, {"1e1000000", "1E1000000"}, + } + for _, tc := range same { + assert.Equal(t, idKey(json.RawMessage(tc[0])), idKey(json.RawMessage(tc[1])), tc) + } + different := [][2]string{ + {"9007199254740993", "9007199254740992"}, {"1", "10"}, {"-1", "1"}, {"0.1", "0.10001"}, + {"1e1000000", "1e1000001"}, + } + for _, tc := range different { + assert.NotEqual(t, idKey(json.RawMessage(tc[0])), idKey(json.RawMessage(tc[1])), tc) + } + assert.Less(t, len(idKey(json.RawMessage("1e1000000"))), 32, "the key is built from the digits, not the expanded value") +} From 5c42df0ded469a334241746f52fc4c6b93076d9d Mon Sep 17 00:00:00 2001 From: Simon Faltum Date: Fri, 13 Nov 2026 00:06:38 +0000 Subject: [PATCH 7/7] Fix review findings in the MCP stdio bridge (pass 4) Each change has a test. The SSE reader limits an event's data to 64 MiB, reads bare CR and CRLF line endings and a leading BOM, and answers a ping the server sends during a session replay. A 404 whose body is the server's JSON-RPC error passes through when the request carried no session id. The session id and protocol version come only from an initialize answer with a result, and a session that a new initialize replaces is deleted. A notification's gate opens notificationWait after its POST starts. A hook output is checked before any of it is written, and a hook error on a message other than the response is logged and dropped. A notification's answer is closed unread, not forwarded. The stale 404 response is closed before the replay. Bridge.Transport nil now means http.DefaultTransport, with no 10 s connect timeout. A test that relied on a 100 ms idle timeout now uses 1 s. Co-authored-by: Isaac --- libs/aitools/mcp/proxy/bridge.go | 233 +++++++++------ libs/aitools/mcp/proxy/bridge_test.go | 381 +++++++++++++++++++++++- libs/aitools/mcp/proxy/messages.go | 1 + libs/aitools/mcp/proxy/messages_test.go | 15 +- libs/aitools/mcp/proxy/sse.go | 64 +++- libs/aitools/mcp/proxy/sse_test.go | 77 +++++ 6 files changed, 671 insertions(+), 100 deletions(-) diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go index 5d50cf3501c..bc3357e7619 100644 --- a/libs/aitools/mcp/proxy/bridge.go +++ b/libs/aitools/mcp/proxy/bridge.go @@ -11,7 +11,6 @@ import ( "fmt" "io" "mime" - "net" "net/http" "strings" "sync" @@ -28,12 +27,11 @@ const ( jsonMIME = "application/json" eventStreamMIME = "text/event-stream" - maxLineBytes = 64 << 20 - maxErrorBytes = 1 << 20 // a non-2xx body is read up to this many bytes; its error message is an excerpt - connectTimeout = 10 * time.Second - deleteTimeout = 5 * time.Second - excerptRunes = 200 - excerptBytes = 4 * excerptRunes // a character takes at most four bytes + maxLineBytes = 64 << 20 + maxErrorBytes = 1 << 20 // a non-2xx body is read up to this many bytes; its error message is an excerpt + deleteTimeout = 5 * time.Second + excerptRunes = 200 + excerptBytes = 4 * excerptRunes // a character takes at most four bytes codeParseError = -32700 codeInvalidRequest = -32600 @@ -51,6 +49,8 @@ var ( notificationWait = 2 * time.Second errIdleTimeout = errors.New("upstream idle") errNoResponse = errors.New("upstream sent no response") + // errUpstreamTooLarge is the error for an upstream message over maxLineBytes, whether it is a body or an event. + errUpstreamTooLarge = fmt.Errorf("an upstream message exceeds the %d MiB limit", maxLineBytes>>20) ) // Hooks intercepts upstream messages before they are written to stdout. @@ -78,7 +78,8 @@ type Bridge struct { ForceListChanged bool // Hooks, when set, sees every upstream message before it is written. Hooks Hooks - // Transport performs the upstream requests. Nil uses the default transport with a 10 s connect timeout. + // Transport performs the upstream requests. Nil means http.DefaultTransport, which has a 30 s dial timeout. A caller + // that needs the profile's TLS settings or a shorter connect timeout sets it. Transport http.RoundTripper } @@ -191,14 +192,9 @@ type conn struct { initialized clientMsg // the client's notifications/initialized, for replay } -// newClient returns the upstream HTTP client over rt, or over the default transport when rt is nil. A redirect is -// not followed: a 3xx response is a failed response with its status. +// newClient returns the upstream HTTP client over rt. A redirect is not followed: a 3xx response is a failed response +// with its status. func newClient(rt http.RoundTripper) *http.Client { - if rt == nil { - t := http.DefaultTransport.(*http.Transport).Clone() - t.DialContext = (&net.Dialer{Timeout: connectTimeout}).DialContext - rt = t - } return &http.Client{ Transport: rt, CheckRedirect: func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }, @@ -233,20 +229,18 @@ func (c *conn) handle(base context.Context, gate <-chan struct{}, line []byte) < c.wg.Go(func() { defer cancel() defer c.untrack(key) - c.forward(ctx, gate, line, m) + c.forward(ctx, gate, line, m, nil) }) return gate } - // The gate closes when the POST finishes or after notificationWait, whichever is first, so a stalled notification - // holds later messages for at most that long. + // The gate closes when the POST finishes or notificationWait after it starts, whichever is first, so a stalled + // notification holds later messages for at most that long. done := make(chan struct{}) release := sync.OnceFunc(func() { close(done) }) c.wg.Go(func() { - timer := time.AfterFunc(notificationWait, release) - defer timer.Stop() defer release() defer cancel() - c.forward(ctx, gate, line, m) + c.forward(ctx, gate, line, m, release) }) return done } @@ -264,9 +258,14 @@ func await(ctx context.Context, gate <-chan struct{}) { // forward waits (see await), then POSTs one client message exactly as received and writes what the upstream // answers. The idle watchdog covers every response, plain JSON included. It starts before the POST, so it also -// bounds the wait for response headers, and the run time of a hook counts toward it. -func (c *conn) forward(ctx context.Context, gate <-chan struct{}, line []byte, m message) { +// bounds the wait for response headers, and the run time of a hook counts toward it. For a notification, release +// opens its gate notificationWait after the POST starts. +func (c *conn) forward(ctx context.Context, gate <-chan struct{}, line []byte, m message, release func()) { await(ctx, gate) + if release != nil { + timer := time.AfterFunc(notificationWait, release) + defer timer.Stop() + } idleCtx, cancel := context.WithCancelCause(ctx) defer cancel(nil) idle := time.AfterFunc(idleTimeout, func() { cancel(errIdleTimeout) }) @@ -359,28 +358,37 @@ func (c *conn) newRequest(ctx context.Context, method string, body []byte, sent return req, nil } -// write sends one message to stdout as a single line. Upstream bodies and hook output may be -// pretty-printed, so a message with line breaks is compacted first. -func (c *conn) write(msg []byte) error { - if bytes.ContainsAny(msg, "\r\n") { - var compact bytes.Buffer - if err := json.Compact(&compact, msg); err != nil { - return err - } - msg = compact.Bytes() +// oneLine returns msg as a single line. Upstream bodies and hook output may be pretty-printed, so a message with line +// breaks is compacted, which also checks that it is JSON. +func oneLine(msg []byte) ([]byte, error) { + if !bytes.ContainsAny(msg, "\r\n") { + return msg, nil + } + var compact bytes.Buffer + if err := json.Compact(&compact, msg); err != nil { + return nil, err } + return compact.Bytes(), nil +} + +// writeLines writes each line to stdout, each followed by a newline, without interleaving with other writes. +func (c *conn) writeLines(lines [][]byte) error { c.ioMu.Lock() defer c.ioMu.Unlock() - if _, err := c.b.Out.Write(msg); err != nil { - return err + for _, line := range lines { + if _, err := c.b.Out.Write(line); err != nil { + return err + } + if _, err := c.b.Out.Write(newline); err != nil { + return err + } } - _, err := c.b.Out.Write(newline) - return err + return nil } // reply writes msg to stdout, logging a failed write since there is no caller to return it to. func (c *conn) reply(msg []byte) { - if err := c.write(msg); err != nil { + if err := c.writeLines([][]byte{msg}); err != nil { c.logf("stdout: %v", err) } } @@ -400,25 +408,13 @@ func (c *conn) current() upstreamState { return c.state } -// setSession records the Mcp-Session-Id to send on later requests. -func (c *conn) setSession(id string) { - c.mu.Lock() - defer c.mu.Unlock() - c.state.id = id -} - -// setProtocol records the protocol version from the initialize result, to send on later requests. -func (c *conn) setProtocol(version string) { - c.mu.Lock() - defer c.mu.Unlock() - c.state.protocol = version -} - -// publish replaces the session and protocol version with those of a replay that has finished. -func (c *conn) publish(s upstreamState) { +// publish replaces the session and protocol version with s, and returns the ones it replaces. +func (c *conn) publish(s upstreamState) upstreamState { c.mu.Lock() defer c.mu.Unlock() + old := c.state c.state = s + return old } // remember keeps the client's initialize or notifications/initialized so it can be replayed if the server @@ -488,14 +484,14 @@ func isEventStream(contentType string) bool { return err == nil && mt == eventStreamMIME } -// readBody reads a 2xx body of at most limit bytes. A longer body is an error, as an oversized stdin message is. -func readBody(r io.Reader, limit int) ([]byte, error) { - body, err := io.ReadAll(io.LimitReader(r, int64(limit)+1)) +// readBody reads a 2xx body of at most maxLineBytes. A longer body is an error, as an oversized stdin message is. +func readBody(r io.Reader) ([]byte, error) { + body, err := io.ReadAll(io.LimitReader(r, maxLineBytes+1)) if err != nil { return nil, err } - if len(body) > limit { - return nil, fmt.Errorf("an upstream message exceeds the %d MiB limit", limit>>20) + if len(body) > maxLineBytes { + return nil, errUpstreamTooLarge } return body, nil } @@ -521,7 +517,8 @@ type exchange struct { idle *time.Timer // reset by every read of the response status int - answered bool // the upstream sent the response to m + answered bool // the upstream sent the response to m + session string // the Mcp-Session-Id of an initialize response, taken only when its answer has a result } // sending returns the session and protocol version to send with x. An initialize request starts a session, @@ -533,17 +530,6 @@ func (x *exchange) sending() upstreamState { return x.c.current() } -// recordProtocol keeps the protocol version from an initialize result, before the result is written. -// The version the server chose governs the requests that follow. -func (x *exchange) recordProtocol(data []byte) error { - v, ok, err := initializeProtocol(data) - if err != nil || !ok { - return err - } - x.c.setProtocol(v) - return nil -} - // send posts the message and writes its answer. ctx is cancelled by the idle timeout; reqCtx is the request's // context, which hooks receive. func (x *exchange) send(ctx, reqCtx context.Context, retry bool) error { @@ -559,8 +545,8 @@ func (x *exchange) send(ctx, reqCtx context.Context, retry bool) error { if resp.StatusCode/100 != 2 { return x.httpFailure(ctx, reqCtx, resp, sent.id, retry) } - if id := resp.Header.Get(sessionHeader); id != "" && x.m.Method == methodInitialize { - x.c.setSession(id) + if x.m.Method == methodInitialize { + x.session = resp.Header.Get(sessionHeader) } if err := x.read(reqCtx, resp); err != nil { return err @@ -581,11 +567,14 @@ func (x *exchange) httpFailure(ctx, reqCtx context.Context, resp *http.Response, } e := decodeErrorBody(body) // A 404 ends the session, unless its body is the result for the request. An error under 404 is the server's - // session-not-found answer, even when it carries the request's id. - if e != nil && e.isResponseTo(x.m) && (resp.StatusCode != http.StatusNotFound || e.Result != nil) { + // session-not-found answer when the request carried a session id. Without one, a 404 cannot mean the session + // ended, so the error is the server's answer to the request. + if e != nil && e.isResponseTo(x.m) && (resp.StatusCode != http.StatusNotFound || e.Result != nil || sent == "") { return x.deliverMessage(reqCtx, body, e.message) } if resp.StatusCode == http.StatusNotFound && sent != "" && retry { + // The stale response is closed before the replay, so its connection is not held open through it. + resp.Body.Close() if err := x.rejoin(ctx, sent); err != nil { return err } @@ -663,15 +652,19 @@ func (c *conn) replayOne(ctx context.Context, idle *time.Timer, msg clientMsg, n if err != nil { return false, err } - if m.isResponseTo(msg.m) { + switch { + case m.isResponseTo(msg.m): answer = data return false, nil + case m.Method == methodPing && m.isRequest(): + // The server waits for this answer before it sends the response to initialize. + return true, c.answerPing(ctx, m.ID, *next) } return true, nil }) } else { var body []byte - body, err = readBody(resp.Body, maxLineBytes) + body, err = readBody(resp.Body) if err == nil && len(bytes.TrimSpace(body)) > 0 && msg.m.isRequest() { if _, err = responseBody(body, msg.m); err == nil { answer = body @@ -693,6 +686,19 @@ func (c *conn) replayOne(ctx context.Context, idle *time.Timer, msg clientMsg, n return nil } +// answerPing answers a ping the server sent during a replay, on the session being started. +func (c *conn) answerPing(ctx context.Context, id json.RawMessage, next upstreamState) error { + resp, err := c.post(ctx, fmt.Appendf(nil, `{"jsonrpc":"2.0","id":%s,"result":{}}`, id), next) + if err != nil { + return err + } + defer resp.Body.Close() + if resp.StatusCode/100 != 2 { + return statusError(resp) + } + return nil +} + // recordInitialize sets next's protocol version from the result of an initialize answer. Without a result the // session is not usable, so the replay fails. func recordInitialize(answer []byte, next *upstreamState) error { @@ -720,23 +726,26 @@ func rejectedInitialize(answer []byte) error { // read delivers the messages in a 2xx response: an event stream, or one JSON body. func (x *exchange) read(reqCtx context.Context, resp *http.Response) error { + if !x.m.isRequest() { + // A notification or client response is answered with 202 and no body. A body is not forwarded, and it is + // closed unread. + if resp.ContentLength != 0 { + x.c.logf("upstream sent a body for a notification or client response; it is not forwarded") + } + return nil + } if isEventStream(resp.Header.Get(contentTypeHeader)) { return readEvents(resp.Body, func(data []byte) (bool, error) { return x.deliverEvent(reqCtx, data) }) } - body, err := readBody(resp.Body, maxLineBytes) + body, err := readBody(resp.Body) if err != nil { return err } if len(bytes.TrimSpace(body)) == 0 { return nil } - if !x.m.isRequest() { - // A notification or client response is answered with 202 and no body. - x.c.logf("upstream sent a JSON body for a notification or client response; it is not forwarded") - return nil - } msg, err := responseBody(body, x.m) if err != nil { return err @@ -758,15 +767,24 @@ func (x *exchange) deliverEvent(reqCtx context.Context, data []byte) (bool, erro } // deliverMessage writes one upstream message, whose parsed envelope is msg. The response to the request marks it -// answered once written. +// answered once written. When a hook fails on any other message, that message is logged and dropped, since the +// response is still coming. func (x *exchange) deliverMessage(reqCtx context.Context, data []byte, msg message) error { answer := msg.isResponseTo(x.m) if answer && x.m.Method == methodInitialize { - if err := x.recordProtocol(data); err != nil { + if err := x.startSession(reqCtx, data); err != nil { + return err + } + } + lines, err := x.lines(reqCtx, data) + if err != nil { + if answer { return err } + x.c.logUpstream(err) + return nil } - if err := x.deliver(reqCtx, data); err != nil { + if err := x.c.writeLines(lines); err != nil { return err } if answer { @@ -775,26 +793,57 @@ func (x *exchange) deliverMessage(reqCtx context.Context, data []byte, msg messa return nil } -// deliver applies the initialize edit and the hooks, then writes the resulting messages. -func (x *exchange) deliver(reqCtx context.Context, msg []byte) error { +// startSession makes the session of an initialize answer that has a result the one that requests use, and ends the +// session it replaces. The protocol version the server chose governs the requests that follow. An answer that is not +// 2xx, or has no result, starts no session. +func (x *exchange) startSession(reqCtx context.Context, data []byte) error { + if x.status/100 != 2 { + return nil + } + v, ok, err := initializeProtocol(data) + if err != nil || !ok { + return err + } + old := x.c.publish(upstreamState{id: x.session, protocol: v}) + if old.id != "" && old.id != x.session { + x.c.deleteSession(reqCtx, old) + } + return nil +} + +// lines returns the lines to write for an upstream message: the initialize edit, then the hooks. Every line is ready +// before any is written, so an error writes nothing. +func (x *exchange) lines(reqCtx context.Context, msg []byte) ([][]byte, error) { var err error if x.m.Method == methodInitialize && (x.c.b.Instructions != "" || x.c.b.ForceListChanged) { if msg, err = editInitialize(msg, x.c.b.Instructions, x.c.b.ForceListChanged); err != nil { - return err + return nil, err } } msgs := [][]byte{msg} if x.c.b.Hooks != nil { if msgs, err = x.c.b.Hooks.Result(reqCtx, x.line, x.status, msg); err != nil { - return err + return nil, err } } + lines := make([][]byte, 0, len(msgs)) for _, out := range msgs { - if err := x.c.write(out); err != nil { - return err + line, err := oneLine(out) + if err != nil { + return nil, err } + lines = append(lines, line) } - return nil + return lines, nil +} + +// deliver writes the lines for msg, a message the bridge builds itself. +func (x *exchange) deliver(reqCtx context.Context, msg []byte) error { + lines, err := x.lines(reqCtx, msg) + if err != nil { + return err + } + return x.c.writeLines(lines) } // fail logs err and, for a request the client still waits on, answers it with a JSON-RPC error. A request diff --git a/libs/aitools/mcp/proxy/bridge_test.go b/libs/aitools/mcp/proxy/bridge_test.go index 537706761aa..0c3e5e09556 100644 --- a/libs/aitools/mcp/proxy/bridge_test.go +++ b/libs/aitools/mcp/proxy/bridge_test.go @@ -455,8 +455,9 @@ func TestRunAnswersStreamsThatEndWithoutResponse(t *testing.T) { finish: func(http.ResponseWriter, *http.Request) {}, }, { - name: "stream goes idle", - idle: 100 * time.Millisecond, + name: "stream goes idle", + // The progress event must arrive before the idle timeout, so the timeout is long enough for a slow runner. + idle: time.Second, wantMsg: "no data from upstream", finish: func(w http.ResponseWriter, r *http.Request) { w.(http.Flusher).Flush() @@ -1791,3 +1792,379 @@ func TestRunAnswersOversizedUpstreamBody(t *testing.T) { require.NotNil(t, reply.Error) assert.Contains(t, reply.Error.Message, "64 MiB limit") } + +// TestRunAnswersPingDuringReplay: a server may ping the client before it answers the replayed initialize, and it waits +// for the ping answer before it sends that answer. The answer is posted on the session being started. +func TestRunAnswersPingDuringReplay(t *testing.T) { + const pingID = `"ping-1"` + pingAnswered := make(chan struct{}) + markAnswered := sync.OnceFunc(func() { close(pingAnswered) }) + var mu sync.Mutex + starts := 0 + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + switch { + case m.Method == "" && string(m.ID) == pingID: + markAnswered() + w.WriteHeader(http.StatusAccepted) + case m.Method == methodInitialize: + mu.Lock() + starts++ + n := starts + mu.Unlock() + if n == 1 { + writeInit(w, m, "s1") + return + } + w.Header().Set(contentTypeHeader, eventStreamMIME) + w.Header().Set(sessionHeader, "s2") + _, _ = io.WriteString(w, "data: "+`{"jsonrpc":"2.0","id":`+pingID+`,"method":"ping"}`+"\n\n") + w.(http.Flusher).Flush() + select { + case <-pingAnswered: + case <-time.After(5 * time.Second): + } + fmt.Fprintf(w, "data: "+`{"jsonrpc":"2.0","id":%s,"result":{"protocolVersion":"2025-06-18"}}`+"\n\n", m.ID) + case !m.isRequest(): + w.WriteHeader(http.StatusAccepted) + case r.Header.Get(sessionHeader) == "s1": + http.Error(w, "session not found", http.StatusNotFound) + default: + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + } + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + out := p.waitLines(t, 2) + require.NoError(t, p.finish(t)) + + require.Len(t, out, 2) + assert.Nil(t, parseReply(t, out[1]).Error) + assert.Equal(t, []string{"s2"}, sessionsSent(fake, pingID), "the ping was answered on the session being started") +} + +// TestRunPassesThroughErrorOf404WithoutSession: without a session id a 404 cannot mean the session ended, so a JSON-RPC +// error for the request is passed through as the server sent it. +func TestRunPassesThroughErrorOf404WithoutSession(t *testing.T) { + const errFormat = `{"jsonrpc":"2.0","id":%s,"error":{"code":-32002,"message":"Resource not found","data":{"uri":"x"}}}` + cases := []struct { + name string + // initOK makes initialize succeed without a session id; otherwise every request gets the 404. + initOK bool + input string + marker string // the request whose POST count is checked + want []string + }{ + { + name: "initialize", + input: initializeLine + "\n", + marker: `"method":"initialize"`, + want: []string{`{"jsonrpc":"2.0","id":1,"error":{"code":-32002,"message":"Resource not found","data":{"uri":"x"}}}`}, + }, + { + name: "request after an initialize that set no session", + initOK: true, + input: initializeLine + "\n" + `{"jsonrpc":"2.0","id":2,"method":"tools/list"}` + "\n", + marker: `"method":"tools/list"`, + want: []string{ + `{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2025-06-18"}}`, + `{"jsonrpc":"2.0","id":2,"error":{"code":-32002,"message":"Resource not found","data":{"uri":"x"}}}`, + }, + }, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + w.Header().Set(contentTypeHeader, jsonMIME) + if m.Method == methodInitialize && tc.initOK { + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"protocolVersion":"2025-06-18"}}`, m.ID) + return + } + w.WriteHeader(http.StatusNotFound) + fmt.Fprintf(w, errFormat, m.ID) + }) + + out, errOut := runAll(t, bridgeFor(srv.URL), tc.input) + + assert.ElementsMatch(t, tc.want, out, "requests run concurrently, so the order of answers is not fixed") + assert.Empty(t, errOut) + assert.Len(t, sessionsSent(fake, tc.marker), 1, "a request without a session id is not posted again") + }) + } +} + +// TestRunRecordsSessionOnlyFromInitializeResult: an initialize answer without a result starts no session, so the +// session header it carries is not sent with later requests. +func TestRunRecordsSessionOnlyFromInitializeResult(t *testing.T) { + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + w.Header().Set(contentTypeHeader, jsonMIME) + if m.Method == methodInitialize { + w.Header().Set(sessionHeader, "s1") + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"error":{"code":-32600,"message":"not now"}}`, m.ID) + return + } + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + }) + + out, _ := runAll(t, bridgeFor(srv.URL), initializeLine+"\n"+`{"jsonrpc":"2.0","id":2,"method":"tools/list"}`+"\n") + + require.Len(t, out, 2) + assert.Equal(t, []string{""}, sessionsSent(fake, `"id":2,`)) + assert.Empty(t, deletedSessions(fake), "no session was started, so none is deleted") +} + +// deletedSessions returns the Mcp-Session-Id of each DELETE the fake endpoint received, in order. +func deletedSessions(fake *fakeEndpoint) []string { + var sessions []string + for _, r := range fake.requests() { + if r.Method == http.MethodDelete { + sessions = append(sessions, r.Header.Get(sessionHeader)) + } + } + return sessions +} + +// TestRunDeletesSessionReplacedByInitialize: a second initialize whose answer has a new session ends the session it +// replaces. An answer with the same session keeps it. +func TestRunDeletesSessionReplacedByInitialize(t *testing.T) { + cases := []struct { + name string + second string // the session of the second initialize's answer + status int // the status of the second answer; 0 is 200 + // wantSent is the session the request after the second initialize is sent with. + wantSent string + wantDeleted []string // the replaced session, then the one shutdown ends + }{ + {name: "new session", second: "s2", wantSent: "s2", wantDeleted: []string{"s1", "s2"}}, + {name: "same session", second: "s1", wantSent: "s1", wantDeleted: []string{"s1"}}, + // A failed answer with a result starts no session, so the current one stays and is not deleted. + {name: "failed answer keeps session", second: "s2", status: http.StatusInternalServerError, wantSent: "s1", wantDeleted: []string{"s1"}}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + var mu sync.Mutex + starts := 0 + srv, fake := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + if m.Method == methodInitialize { + mu.Lock() + starts++ + n := starts + mu.Unlock() + if n == 1 { + writeInit(w, m, "s1") + return + } + w.Header().Set(contentTypeHeader, jsonMIME) + w.Header().Set(sessionHeader, tc.second) + if tc.status != 0 { + w.WriteHeader(tc.status) + } + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{"protocolVersion":"2025-06-18"}}`, m.ID) + return + } + if !m.isRequest() { + w.WriteHeader(http.StatusAccepted) + return + } + w.Header().Set(contentTypeHeader, jsonMIME) + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}`) + p.waitLines(t, 2) + p.send(t, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`) + p.waitLines(t, 3) + require.NoError(t, p.finish(t)) + + assert.Equal(t, []string{tc.wantSent}, sessionsSent(fake, `"id":3,`)) + assert.Equal(t, tc.wantDeleted, deletedSessions(fake)) + }) + } +} + +// TestRunHoldsRequestUntilNotificationWaitFromItsPost: a notification's gate opens notificationWait after its own POST +// starts, not after the message is read. The second notification waits for a stalled first one, and the request +// waits for the second one's gate, so the request is posted about one wait after the second notification. +func TestRunHoldsRequestUntilNotificationWaitFromItsPost(t *testing.T) { + const wait = 400 * time.Millisecond + setNotificationWait(t, wait) + setShutdownGrace(t, 100*time.Millisecond) + firstPosted := make(chan struct{}) + secondPosted := make(chan time.Time, 1) + requested := make(chan time.Time, 1) + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + switch m.Method { + case "notifications/first": + close(firstPosted) + <-r.Context().Done() + case "notifications/second": + secondPosted <- time.Now() + <-r.Context().Done() + case "tools/list": + requested <- time.Now() + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + default: + w.WriteHeader(http.StatusAccepted) + } + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, `{"jsonrpc":"2.0","method":"notifications/first"}`) + waitClosed(t, firstPosted, "the first notification to be posted") + p.send(t, `{"jsonrpc":"2.0","method":"notifications/second"}`) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + out := p.waitLines(t, 1) + require.NoError(t, p.finish(t)) + + require.Len(t, out, 1) + assert.Nil(t, parseReply(t, out[0]).Error) + secondAt := <-secondPosted + requestedAt := <-requested + assert.GreaterOrEqual(t, requestedAt.Sub(secondAt), wait/2, "the request did not wait for the second notification's gate") +} + +// TestRunWritesNothingWhenHookOutputIsInvalid: when a hook returns a message that is not JSON after a valid one, nothing +// is written for the response, and the request gets one error. +func TestRunWritesNothingWhenHookOutputIsInvalid(t *testing.T) { + srv, _ := newFakeEndpoint(t, answer) + b := bridgeFor(srv.URL) + b.Hooks = hookFunc(func(_ context.Context, _ []byte, _ int, msg []byte) ([][]byte, error) { + if bytes.Contains(msg, []byte(`"result"`)) { + return [][]byte{msg, []byte("{\n\"jsonrpc\":")}, nil + } + return [][]byte{msg}, nil + }) + + out, errOut := runAll(t, b, `{"jsonrpc":"2.0","id":3,"method":"tools/list"}`+"\n") + + require.Len(t, out, 1) + reply := parseReply(t, out[0]) + assert.JSONEq(t, `3`, string(reply.ID)) + require.NotNil(t, reply.Error) + assert.Equal(t, codeUpstream, reply.Error.Code) + assert.Contains(t, errOut, "upstream:") +} + +// TestRunKeepsReadingWhenHookFailsOnProgress: a hook error on a message other than the response is logged and that +// message is dropped. The response still comes. +func TestRunKeepsReadingWhenHookFailsOnProgress(t *testing.T) { + const response = `{"jsonrpc":"2.0","id":1,"result":{}}` + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set(contentTypeHeader, eventStreamMIME) + _, _ = io.WriteString(w, "data: "+progressEvent+"\n\ndata: "+response+"\n\n") + }) + b := bridgeFor(srv.URL) + b.Hooks = hookFunc(func(_ context.Context, _ []byte, _ int, msg []byte) ([][]byte, error) { + if bytes.Contains(msg, []byte("notifications/progress")) { + return nil, errors.New("progress hook failed") + } + return [][]byte{msg}, nil + }) + + out, errOut := runAll(t, b, `{"jsonrpc":"2.0","id":1,"method":"tools/call"}`+"\n") + + assert.Equal(t, []string{response}, out) + assert.Contains(t, errOut, "progress hook failed") +} + +// TestRunDoesNotReadStreamOfNotification: the answer to a notification has no body. An event stream on it is closed +// unread, so nothing is forwarded and the connection is not held open. +func TestRunDoesNotReadStreamOfNotification(t *testing.T) { + closed := make(chan struct{}) + markClosed := sync.OnceFunc(func() { close(closed) }) + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set(contentTypeHeader, eventStreamMIME) + _, _ = io.WriteString(w, "data: "+progressEvent+"\n\n") + w.(http.Flusher).Flush() + <-r.Context().Done() + markClosed() + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializedLine) + waitClosed(t, closed, "the bridge to close the stream") + require.NoError(t, p.finish(t)) + + assert.Empty(t, outLines(p.out.String())) +} + +// TestRunClosesStaleResponseBeforeReplay: the 404 that ended a session is closed before the replay starts, so its +// connection does not wait for the replay. The body is longer than the 1 MiB the bridge reads, so it stays open until +// the bridge closes it. +func TestRunClosesStaleResponseBeforeReplay(t *testing.T) { + staleClosed := make(chan struct{}) + markStaleClosed := sync.OnceFunc(func() { close(staleClosed) }) + var sawClosed atomic.Bool + var mu sync.Mutex + starts := 0 + srv, _ := newFakeEndpoint(t, func(w http.ResponseWriter, r *http.Request) { + if r.Method == http.MethodDelete { + return + } + body, _ := io.ReadAll(r.Body) + m, _ := parseMessage(body) + switch { + case m.Method == methodInitialize: + mu.Lock() + starts++ + n := starts + mu.Unlock() + if n == 2 { + select { + case <-staleClosed: + sawClosed.Store(true) + case <-time.After(5 * time.Second): + } + } + writeInit(w, m, fmt.Sprintf("s%d", n)) + case !m.isRequest(): + w.WriteHeader(http.StatusAccepted) + case r.Header.Get(sessionHeader) == "s1": + w.WriteHeader(http.StatusNotFound) + _, _ = io.WriteString(w, strings.Repeat("x", maxErrorBytes+1)) + w.(http.Flusher).Flush() + <-r.Context().Done() + markStaleClosed() + default: + w.Header().Set(contentTypeHeader, jsonMIME) + fmt.Fprintf(w, `{"jsonrpc":"2.0","id":%s,"result":{}}`, m.ID) + } + }) + p := startPiped(t, t.Context(), bridgeFor(srv.URL)) + + p.send(t, initializeLine) + p.waitLines(t, 1) + p.send(t, initializedLine) + p.send(t, `{"jsonrpc":"2.0","id":2,"method":"tools/list"}`) + out := p.waitLines(t, 2) + require.NoError(t, p.finish(t)) + + assert.True(t, sawClosed.Load(), "the stale response was closed before the replay") + require.Len(t, out, 2) + assert.Nil(t, parseReply(t, out[1]).Error) +} diff --git a/libs/aitools/mcp/proxy/messages.go b/libs/aitools/mcp/proxy/messages.go index 63e26bb3069..2fc637d28dc 100644 --- a/libs/aitools/mcp/proxy/messages.go +++ b/libs/aitools/mcp/proxy/messages.go @@ -15,6 +15,7 @@ const ( methodInitialize = "initialize" methodInitialized = "notifications/initialized" methodCancelled = "notifications/cancelled" + methodPing = "ping" keyResult = "result" keyInstructions = "instructions" diff --git a/libs/aitools/mcp/proxy/messages_test.go b/libs/aitools/mcp/proxy/messages_test.go index 0676fd76cb7..a217fcfcf89 100644 --- a/libs/aitools/mcp/proxy/messages_test.go +++ b/libs/aitools/mcp/proxy/messages_test.go @@ -131,14 +131,23 @@ func TestIsResponseToComparesIDsByValue(t *testing.T) { // digits, so the key stays short. func TestIDKeyComparesNumbersByValue(t *testing.T) { same := [][2]string{ - {"7", "7.0"}, {"7", "70e-1"}, {"7", "7E0"}, {"-0", "0"}, {"0.0", "0e5"}, - {"1.5", "15e-1"}, {"100", "1e2"}, {"1e1000000", "1E1000000"}, + {"7", "7.0"}, + {"7", "70e-1"}, + {"7", "7E0"}, + {"-0", "0"}, + {"0.0", "0e5"}, + {"1.5", "15e-1"}, + {"100", "1e2"}, + {"1e1000000", "1E1000000"}, } for _, tc := range same { assert.Equal(t, idKey(json.RawMessage(tc[0])), idKey(json.RawMessage(tc[1])), tc) } different := [][2]string{ - {"9007199254740993", "9007199254740992"}, {"1", "10"}, {"-1", "1"}, {"0.1", "0.10001"}, + {"9007199254740993", "9007199254740992"}, + {"1", "10"}, + {"-1", "1"}, + {"0.1", "0.10001"}, {"1e1000000", "1e1000001"}, } for _, tc := range different { diff --git a/libs/aitools/mcp/proxy/sse.go b/libs/aitools/mcp/proxy/sse.go index e480f791c7d..09ce34fefa4 100644 --- a/libs/aitools/mcp/proxy/sse.go +++ b/libs/aitools/mcp/proxy/sse.go @@ -3,12 +3,17 @@ package proxy import ( "bufio" "bytes" + "errors" + "fmt" "io" ) // messageEvent is the event type of a JSON-RPC message. An event with no type is a message too. const messageEvent = "message" +// utf8BOM is the byte order mark that an event stream may start with. +var utf8BOM = []byte("\xEF\xBB\xBF") + // readEvents calls fn with the data of each event in a text/event-stream body, in order, until fn returns // false. Multi-line data is joined with newlines, and an event left open at the end is still delivered. Only // events of type message, or with no type, are delivered. An event with empty data is skipped, such as the @@ -16,6 +21,7 @@ const messageEvent = "message" func readEvents(r io.Reader, fn func([]byte) (bool, error)) error { sc := bufio.NewScanner(r) sc.Buffer(nil, maxLineBytes) + sc.Split(eventLines()) var ev event for sc.Scan() { line := sc.Bytes() @@ -32,18 +38,62 @@ func readEvents(r io.Reader, fn func([]byte) (bool, error)) error { value = bytes.TrimPrefix(value, []byte{' '}) switch string(field) { case "data": - ev.add(value) + if err := ev.add(value); err != nil { + return err + } case "event": ev.typ = string(value) } } if err := sc.Err(); err != nil { + if errors.Is(err, bufio.ErrTooLong) { + return fmt.Errorf("%w: %w", errUpstreamTooLarge, err) + } return err } _, err := ev.dispatch(fn) return err } +// eventLines returns the split function for the lines of an event stream. A line ends at CR, LF or CRLF. A CR ends its +// line at once, so a blank line is read without waiting for the next byte, and the LF of a CRLF that follows is +// skipped. One byte order mark at the start of the stream is skipped. +// +// The skipped bytes are dropped in the same call that finds the line, never in a call of their own. Once the reader +// has reached EOF, bufio.Scanner stops at a call that returns no token, even if data remains. +func eventLines() bufio.SplitFunc { + first, afterCR := true, false + return func(data []byte, atEOF bool) (int, []byte, error) { + skipped := 0 + if first { + // Wait until the bytes can be told apart from a byte order mark. + if len(data) < len(utf8BOM) && !atEOF && bytes.HasPrefix(utf8BOM, data) { + return 0, nil, nil + } + first = false + if bytes.HasPrefix(data, utf8BOM) { + data = data[len(utf8BOM):] + skipped += len(utf8BOM) + } + } + if afterCR && len(data) > 0 { + afterCR = false + if data[0] == '\n' { + data = data[1:] + skipped++ + } + } + if i := bytes.IndexAny(data, "\r\n"); i >= 0 { + afterCR = data[i] == '\r' + return skipped + i + 1, data[:i], nil + } + if atEOF && len(data) > 0 { + return skipped + len(data), data, nil + } + return skipped, nil, nil + } +} + // event collects the data lines and the type of one text/event-stream event. type event struct { typ string @@ -51,13 +101,21 @@ type event struct { hasData bool } -// add appends one data line. -func (e *event) add(line []byte) { +// add appends one data line. The data of an event is limited to maxLineBytes, as one line is. +func (e *event) add(line []byte) error { + n := len(e.data) + len(line) + if e.hasData { + n++ + } + if n > maxLineBytes { + return errUpstreamTooLarge + } if e.hasData { e.data = append(e.data, '\n') } e.data = append(e.data, line...) e.hasData = true + return nil } // dispatch passes the event's data to fn and clears the event. It reports whether fn wants more events. diff --git a/libs/aitools/mcp/proxy/sse_test.go b/libs/aitools/mcp/proxy/sse_test.go index 1d7ddb09c66..1be151d6709 100644 --- a/libs/aitools/mcp/proxy/sse_test.go +++ b/libs/aitools/mcp/proxy/sse_test.go @@ -1,13 +1,27 @@ package proxy import ( + "bufio" + "io" "strings" "testing" + "testing/iotest" + "time" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) +// fill is an endless reader of 'a' bytes, so a test can stream a body of any size without holding it. +type fill struct{} + +func (fill) Read(p []byte) (int, error) { + for i := range p { + p[i] = 'a' + } + return len(p), nil +} + func TestReadEvents(t *testing.T) { cases := []struct { name string @@ -23,6 +37,10 @@ func TestReadEvents(t *testing.T) { {name: "event with empty data is skipped", stream: "id: 1\ndata:\n\nid: 2\ndata: 2\n\n", want: []string{"2"}}, {name: "empty data at end of stream is skipped", stream: "data: 1\n\nid: 2\ndata:", want: []string{"1"}}, {name: "events of other types are skipped", stream: "event: ping\ndata: ping\n\nevent: message\ndata: 1\n\n", want: []string{"1"}}, + {name: "bare CR line endings", stream: "data: a\r\rdata: b\r\r", want: []string{"a", "b"}}, + {name: "CR and LF mixed", stream: "data: a\r\n\rdata: b\n\n", want: []string{"a", "b"}}, + {name: "one leading BOM is ignored", stream: "\xEF\xBB\xBFdata: 1\n\n", want: []string{"1"}}, + {name: "only one leading BOM is ignored", stream: "\xEF\xBB\xBF\xEF\xBB\xBFdata: 1\n\n"}, } for _, tc := range cases { t.Run(tc.name, func(t *testing.T) { @@ -37,6 +55,65 @@ func TestReadEvents(t *testing.T) { } } +// TestReadEventsSplitReads: a BOM and a CRLF split across reads are read as they are in one read. +func TestReadEventsSplitReads(t *testing.T) { + var got []string + err := readEvents(iotest.OneByteReader(strings.NewReader("\xEF\xBB\xBFdata: 1\r\n\r\ndata: 2\r\r")), func(data []byte) (bool, error) { + got = append(got, string(data)) + return true, nil + }) + require.NoError(t, err) + assert.Equal(t, []string{"1", "2"}, got) +} + +// TestReadEventsDispatchesBareCRBeforeNextBytes: a blank line ending in a bare CR dispatches its event without +// waiting for the next byte, so a server that keeps the stream open still gets its response delivered. +func TestReadEventsDispatchesBareCRBeforeNextBytes(t *testing.T) { + pr, pw := io.Pipe() + t.Cleanup(func() { pw.Close() }) + got := make(chan string, 2) + done := make(chan error, 1) + go func() { + done <- readEvents(pr, func(data []byte) (bool, error) { + got <- string(data) + return true, nil + }) + }() + + _, err := io.WriteString(pw, "data: 1\r\r") + require.NoError(t, err) + select { + case data := <-got: + assert.Equal(t, "1", data) + case <-time.After(10 * time.Second): + t.Fatal("the event was not dispatched before the next bytes arrived") + } + _, err = io.WriteString(pw, "data: 2\r\r") + require.NoError(t, err) + require.NoError(t, pw.Close()) + require.NoError(t, <-done) + assert.Equal(t, "2", <-got) +} + +// TestReadEventsLimitsEventData: the 64 MiB limit applies to the whole event, not only to each of its lines. +func TestReadEventsLimitsEventData(t *testing.T) { + var parts []io.Reader + for range 70 { + parts = append(parts, strings.NewReader("data: "), io.LimitReader(fill{}, 1<<20), strings.NewReader("\n")) + } + err := readEvents(io.MultiReader(parts...), func([]byte) (bool, error) { return true, nil }) + require.Error(t, err) + assert.ErrorContains(t, err, "an upstream message exceeds the 64 MiB limit") +} + +// TestReadEventsLimitsLine: a line over the limit fails with the limit named, and the scanner's error stays in the chain. +func TestReadEventsLimitsLine(t *testing.T) { + stream := io.MultiReader(strings.NewReader("data: "), io.LimitReader(fill{}, maxLineBytes)) + err := readEvents(stream, func([]byte) (bool, error) { return true, nil }) + require.ErrorIs(t, err, bufio.ErrTooLong) + assert.ErrorContains(t, err, "an upstream message exceeds the 64 MiB limit") +} + // TestReadEventsStopsWhenFnReturnsFalse: an event after the one that ends reading is not read. func TestReadEventsStopsWhenFnReturnsFalse(t *testing.T) { var got []string