diff --git a/libs/aitools/mcp/proxy/bridge.go b/libs/aitools/mcp/proxy/bridge.go new file mode 100644 index 00000000000..bc3357e7619 --- /dev/null +++ b/libs/aitools/mcp/proxy/bridge.go @@ -0,0 +1,936 @@ +// Package proxy bridges MCP stdio (newline-delimited JSON-RPC) to a streamable HTTP MCP endpoint. +package proxy + +import ( + "bufio" + "bytes" + "cmp" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "mime" + "net/http" + "strings" + "sync" + "time" +) + +const ( + logPrefix = "databricks aitools mcp serve: " + sessionHeader = "Mcp-Session-Id" + protocolHeader = "MCP-Protocol-Version" + contentTypeHeader = "Content-Type" + acceptHeader = "Accept" + acceptTypes = "application/json, text/event-stream" + 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 + deleteTimeout = 5 * time.Second + excerptRunes = 200 + excerptBytes = 4 * excerptRunes // a character takes at most four bytes + + codeParseError = -32700 + codeInvalidRequest = -32600 + codeUpstream = -32000 +) + +var ( + newline = []byte{'\n'} + // 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") + // 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. +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 is called + // concurrently, from the goroutine of each request. + 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 + // 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 +} + +// 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{ + b: b, + client: newClient(b.Transport), + cancelBase: cancelBase, + inflight: map[string]context.CancelFunc{}, + rejoinSlot: make(chan struct{}, 1), + } + + 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) + }() + + // gate closes when the latest notification has been posted. Stdin is never blocked on it. + var gate <-chan struct{} + 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 + } + // 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) + } + } +} + +// 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 + } + } + 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. +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 +} + +// clientMsg is a client message kept so it can be replayed. +type clientMsg struct { + line []byte + 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 + client *http.Client + cancelBase context.CancelFunc + wg sync.WaitGroup + + 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 + 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 over rt. A redirect is not followed: a 3xx response is a failed response +// with its status. +func newClient(rt http.RoundTripper) *http.Client { + 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. 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 { + 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 gate + } + switch m.Method { + case methodCancelled: + c.cancelRequest(line) + case methodInitialize, methodInitialized: + c.remember(m, line) + } + + ctx, cancel := context.WithCancel(base) + if m.isRequest() { + key := idKey(m.ID) + c.track(key, cancel) + c.wg.Go(func() { + defer cancel() + defer c.untrack(key) + c.forward(ctx, gate, line, m, nil) + }) + return gate + } + // 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() { + defer release() + defer cancel() + c.forward(ctx, gate, line, m, release) + }) + return done +} + +// 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 + } + select { + case <-gate: + 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. It starts before the POST, so it also +// 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) }) + defer idle.Stop() + + x := &exchange{c: c, line: line, m: m, idle: idle} + if err := x.send(idleCtx, ctx, m.isRequest()); err != nil { + x.fail(idleCtx, ctx, err) + } +} + +// 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.deleteSession(ctx, c.current()) +} + +// 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 { + return err + } + resp, err := c.client.Do(req) + if err != nil { + return err + } + resp.Body.Close() + return nil +} + +// post sends one JSON-RPC message to the endpoint. +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 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) + } + 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(acceptHeader, acceptTypes) + if body != nil { + req.Header.Set(contentTypeHeader, jsonMIME) + } + if sent.protocol != "" { + req.Header.Set(protocolHeader, sent.protocol) + } + if sent.id != "" { + req.Header.Set(sessionHeader, sent.id) + } + if err := c.b.Authenticate(req); err != nil { + return nil, err + } + return req, nil +} + +// 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() + 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 + } + } + 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.writeLines([][]byte{msg}); err != nil { + c.logf("stdout: %v", err) + } +} + +// 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...) +} + +// 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.state +} + +// 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 +// 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() + delete(c.inflight, key) +} + +// 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(line, &n); err != nil { + c.logf("notifications/cancelled: %v", err) + return + } + c.mu.Lock() + cancel := c.inflight[idKey(n.Params.RequestID)] + c.mu.Unlock() + if cancel != nil { + cancel() + } +} + +// 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 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) > maxLineBytes { + return nil, errUpstreamTooLarge + } + 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 + 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 message and the upstream messages answering it. +type exchange struct { + c *conn + line []byte + m message + idle *time.Timer // reset by every read of the response + + status int + 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, +// so it carries neither (https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management). +func (x *exchange) sending() upstreamState { + if x.m.Method == methodInitialize { + return upstreamState{} + } + return x.c.current() +} + +// 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 { + return err + } + defer resp.Body.Close() + resp.Body = idleBody{ReadCloser: resp.Body, idle: x.idle} + x.status = resp.StatusCode + if resp.StatusCode/100 != 2 { + return x.httpFailure(ctx, reqCtx, resp, sent.id, retry) + } + if x.m.Method == methodInitialize { + x.session = resp.Header.Get(sessionHeader) + } + if err := x.read(reqCtx, resp); err != nil { + return err + } + if x.m.isRequest() && !x.answered { + return errNoResponse + } + return nil +} + +// 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(io.LimitReader(resp.Body, maxErrorBytes)) + if err != nil { + return err + } + 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 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 + } + return x.send(ctx, reqCtx, false) + } + return httpError(resp.StatusCode, body, e) +} + +// 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 { + return err + } + defer c.unlockRejoin() + if c.current().id != stale { + return nil + } + c.logf("the server ended the session; starting a new one") + c.mu.Lock() + init, initialized := c.initialize, c.initialized + c.mu.Unlock() + msgs := []clientMsg{init} + if initialized.line != nil { + msgs = append(msgs, initialized) + } + 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) + 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, 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 next, 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 { + return statusError(resp) + } + if id := resp.Header.Get(sessionHeader); id != "" && msg.m.Method == methodInitialize { + next.id = id + } + + var answer []byte + if isEventStream(resp.Header.Get(contentTypeHeader)) { + err = readEvents(resp.Body, func(data []byte) (bool, error) { + m, err := parseUpstream(data) + if err != nil { + return false, err + } + 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) + if err == nil && len(bytes.TrimSpace(body)) > 0 && msg.m.isRequest() { + if _, err = responseBody(body, msg.m); err == nil { + answer = body + } + } + } + if err != nil { + return err + } + if !msg.m.isRequest() { + return nil + } + if answer == nil { + return errNoResponse + } + if msg.m.Method == methodInitialize { + return recordInitialize(answer, next) + } + 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 { + 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 !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) + if err != nil { + return err + } + if len(bytes.TrimSpace(body)) == 0 { + return nil + } + msg, err := responseBody(body, x.m) + if err != nil { + return err + } + return x.deliverMessage(reqCtx, body, msg) +} + +// 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 := parseUpstream(data) + if err != nil { + return false, err + } + if err := x.deliverMessage(reqCtx, data, msg); err != nil { + return false, err + } + return !x.answered, nil +} + +// deliverMessage writes one upstream message, whose parsed envelope is msg. The response to the request marks it +// 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.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.c.writeLines(lines); err != nil { + return err + } + if answer { + x.answered = true + } + return nil +} + +// 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 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 nil, err + } + } + lines := make([][]byte, 0, len(msgs)) + for _, out := range msgs { + line, err := oneLine(out) + if err != nil { + return nil, err + } + lines = append(lines, line) + } + 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 +// 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): + err = fmt.Errorf("no data from upstream for %s", idleTimeout) + case cause != nil: + return + } + 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.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 { + text := excerpt(body) + if e != nil { + text = cmp.Or(e.Message, e.Error.Message, text) + } + if text == "" { + return fmt.Errorf("HTTP %d", status) + } + return fmt.Errorf("HTTP %d: %s", status, text) +} + +// 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 { + 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 new file mode 100644 index 00000000000..0c3e5e09556 --- /dev/null +++ b/libs/aitools/mcp/proxy/bridge_test.go @@ -0,0 +1,2170 @@ +package proxy + +import ( + "bufio" + "bytes" + "context" + "encoding/json" + "errors" + "fmt" + "io" + "net/http" + "net/http/httptest" + "slices" + "strings" + "sync" + "sync/atomic" + "testing" + "time" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +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 + 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 + }, + } +} + +// 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 }) +} + +// 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 + 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. 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())) + 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\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-RPC message"}, + } + 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, tc.wantError) + }) + } +} + +// 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, errOut := runAll(t, bridgeFor(srv.URL), `{"jsonrpc":"2.0","method":"notifications/initialized"}`+"\n") + + assert.Empty(t, out) + assert.Contains(t, errOut, "HTTP 500") +} + +// 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", + // 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() + <-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") + + 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) + }) + } +} + +// 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) { + select { + case <-r.Context().Done(): + case <-time.After(20 * time.Second): + } + }) + 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) { + 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) + + p.send(t, `{"jsonrpc":"2.0","id":5,"method":"tools/call"}`) + waitClosed(t, entered, "the hook") + require.NoError(t, p.finish(t)) + + 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") +} + +// 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, "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) { + 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") +} + +// 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 + 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.WriteString(w, response) + }) + + out, _ := runAll(t, bridgeFor(srv.URL), request+"\n") + + 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) { + 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") + assert.NotContains(t, p.err.String(), "upstream", "a cancellation the client asked for is not an error") +} + +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) { + setShutdownGrace(t, 100*time.Millisecond) + 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) +} + +// 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) + 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") +} + +// 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,`)) +} + +// 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 + } + 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: `"asign 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") +} + +// 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 new file mode 100644 index 00000000000..2fc637d28dc --- /dev/null +++ b/libs/aitools/mcp/proxy/messages.go @@ -0,0 +1,241 @@ +package proxy + +import ( + "bytes" + "cmp" + "encoding/json" + "errors" + "fmt" + "strconv" + "strings" +) + +// Method names and member names the bridge reads or edits. +const ( + methodInitialize = "initialize" + methodInitialized = "notifications/initialized" + methodCancelled = "notifications/cancelled" + methodPing = "ping" + + keyResult = "result" + keyInstructions = "instructions" + keyCapabilities = "capabilities" + keyTools = "tools" + keyListChanged = "listChanged" +) + +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") +) + +// message is the part of a JSON-RPC message the bridge reads, from either side. The rest of the message +// is forwarded as received. +type message struct { + ID json.RawMessage `json:"id"` + Method string `json:"method"` +} + +// 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. 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. +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. A syntax error is reported as a +// *json.SyntaxError; valid JSON that is not an object is errNotObject. +func parseMessage(line []byte) (message, error) { + var m message + 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 +} + +// 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 { + return nil + } + return &e +} + +// 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 && !bytes.Equal(m.ID, jsonNull) +} + +// 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 m.Method == "" && request.isRequest() && idKey(m.ID) == idKey(request.ID) +} + +// 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 + _ = 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 json.Number: + 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) { + var r struct { + Result *struct { + ProtocolVersion string `json:"protocolVersion"` + } `json:"result"` + } + if err := json.Unmarshal(data, &r); err != nil { + return "", false, initializeResultError(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 { + 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}}) + 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[keyResult]; !ok { + return msg, nil + } + result, err := decodeObject(env[keyResult]) + if err != nil { + return nil, initializeResultError(err) + } + if instructions != "" { + var prev string + 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[keyInstructions], err = json.Marshal(text); err != nil { + return nil, err + } + } + if listChanged { + caps, err := decodeObject(member(result, keyCapabilities)) + if err != nil { + return nil, fmt.Errorf("initialize capabilities: %w", err) + } + tools, err := decodeObject(member(caps, keyTools)) + if err != nil { + return nil, fmt.Errorf("initialize capabilities.tools: %w", err) + } + tools[keyListChanged] = json.RawMessage("true") + if caps[keyTools], err = json.Marshal(tools); err != nil { + return nil, err + } + if result[keyCapabilities], err = json.Marshal(caps); err != nil { + return nil, err + } + } + if env[keyResult], 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 jsonNull +} diff --git a/libs/aitools/mcp/proxy/messages_test.go b/libs/aitools/mcp/proxy/messages_test.go new file mode 100644 index 00000000000..a217fcfcf89 --- /dev/null +++ b/libs/aitools/mcp/proxy/messages_test.go @@ -0,0 +1,157 @@ +package proxy + +import ( + "encoding/json" + "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()) + }) + } +} + +// 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) { + cases := []struct { + name string + request string + response string + want bool + }{ + {name: "same string", request: `"a 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 + data []byte + hasData bool +} + +// 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. +func (e *event) dispatch(fn func([]byte) (bool, error)) (bool, error) { + data, typ := e.data, e.typ + *e = event{} + 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 new file mode 100644 index 00000000000..1be151d6709 --- /dev/null +++ b/libs/aitools/mcp/proxy/sse_test.go @@ -0,0 +1,126 @@ +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 + 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"}, + {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) { + var got []string + err := readEvents(strings.NewReader(tc.stream), func(data []byte) (bool, error) { + got = append(got, string(data)) + return true, nil + }) + require.NoError(t, err) + assert.Equal(t, tc.want, got) + }) + } +} + +// 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 + err := readEvents(strings.NewReader("data: 1\n\ndata: 2\n\n"), func(data []byte) (bool, error) { + got = append(got, string(data)) + return false, nil + }) + require.NoError(t, err) + assert.Equal(t, []string{"1"}, got) +}