mcp: allow disabling stream replay; disable by default (#585)

This CL implements two changes that must be logically connected.

The first is to provide a mechanism for disabling stream replay.
Previously, our documentation stated that if
StreamableServerTransport.EventStore was nil, a default in-memory event
store would be used. In that case, there would be no way to completely
disable stream replay, and as described in #576, there are many cases
where replay is undesirable.

But of course changing the behavior of the transport zero value
implicitly affects its default behavior, and so this CL also implements
the proposal #580: stream replay is disabled by default.

Implementing this change required a significant refactoring, as
previously we were relying on the event store for serialized message
delivery from the JSON-RPC layer to the MCP layer: the connection would
write to the event store, and independently the stream (be it an
incoming POST or replay GET) would iterate and serve messages in the
stream.

In order to achieve the goals of this CL, it was necessary to decouple
storage from delivery. The 'stream' abstraction now tracks a delivery
callback that writes straight to the HTTP response. It would have been
convenient to store the ongoing http.ResponseWriter directly in the
stream (this is how typescript does it), but due to the design of our
EventStore API, only the HTTP handler knows the next event index, so a
'deliver' abstraction was an unfortunate requirement (suggestions for
how to further simplify this are welcome).

More simplification is possible: in particular, as a result of this
refactoring it should be entirely possible to clean up streams once
we've received all responses. Any replay would only need access to the
EventStore, if at all. This is left to a follow-up CL, to limit this
already significant change.

Furthermore, a nice consequence of this refactoring is that, when not
using event storage, servers can get synchronous feedback that message
delivery failed, which should avoid unnecessary work. We can
additionally cancel ongoing requests on early client termination, but
that is also left to a follow-up CL.

Throughout, the terminology 'standalone SSE stream' replaced 'hanging
GET' when referring to the non-replay GET request issued by the client.
This is consistent with other SDKs.

Fixes #576
Updates #580
This commit is contained in:
Robert Findley 2025-10-16 12:11:49 -04:00 • committed by GitHub
commit 104d39c609
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -41,8 +41,18 @@ func TestStreamableTransports(t *testing.T) {
ctx := context.Background()
for _, useJSON := range []bool{false, true} {
t.Run(fmt.Sprintf("JSONResponse=%v", useJSON), func(t *testing.T) {
tests := []struct {
useJSON bool
replay bool
}{
{false, false},
{false, true},
{true, false},
{true, true},
}
for _, test := range tests {
t.Run(fmt.Sprintf("JSONResponse=%v;replay=%v", test.useJSON, test.replay), func(t *testing.T) {
// Create a server with some simple tools.
server := NewServer(testImpl, nil)
AddTool(server, &Tool{Name: "greet", Description: "say hi"}, sayHi)
@ -86,7 +96,12 @@ func TestStreamableTransports(t *testing.T) {
// Start an httptest.Server with the StreamableHTTPHandler, wrapped in a
// cookie-checking middleware.
handler := NewStreamableHTTPHandler(func(req *http.Request) *Server { return server }, &StreamableHTTPOptions{
JSONResponse: useJSON,
JSONResponse: test.useJSON,
configureTransport: func(_ *http.Request, transport *StreamableServerTransport) {
if test.replay {
transport.EventStore = NewMemoryEventStore(nil)
}
},
})
var (
@ -370,7 +385,11 @@ func testClientReplay(t *testing.T, test clientReplayTest) {
return new(CallToolResult), nil, nil
})
realServer := httptest.NewServer(mustNotPanic(t, NewStreamableHTTPHandler(func(*http.Request) *Server { return server }, nil)))
realServer := httptest.NewServer(mustNotPanic(t, NewStreamableHTTPHandler(func(*http.Request) *Server { return server }, &StreamableHTTPOptions{
configureTransport: func(_ *http.Request, t *StreamableServerTransport) {
t.EventStore = NewMemoryEventStore(nil) // necessary for replay
},
})))
t.Cleanup(func() {
t.Log("Closing real HTTP server")
realServer.Close()
@ -543,7 +562,16 @@ func TestServerInitiatedSSE(t *testing.T) {
notifications := make(chan string)
server := NewServer(testImpl, nil)
httpServer := httptest.NewServer(mustNotPanic(t, NewStreamableHTTPHandler(func(*http.Request) *Server { return server }, nil)))
opts := &StreamableHTTPOptions{
// TODO(#583): for now, this is required for guaranteed message delivery.
// However, it shouldn't be necessary to use replay here, as we should be
// guaranteed that the standalone SSE stream is started by the time the
// client is connected.
configureTransport: func(_ *http.Request, transport *StreamableServerTransport) {
transport.EventStore = NewMemoryEventStore(nil)
},
}
httpServer := httptest.NewServer(mustNotPanic(t, NewStreamableHTTPHandler(func(*http.Request) *Server { return server }, opts)))
defer httpServer.Close()
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
@ -640,6 +668,7 @@ func TestStreamableServerTransport(t *testing.T) {
tests := []struct {
name string
replay bool // if set, use a MemoryEventStore to enable stream replay
tool func(*testing.T, context.Context, *ServerSession)
requests []streamableRequest // http requests
}{
@ -804,10 +833,15 @@ func TestStreamableServerTransport(t *testing.T) {
},
{
name: "background",
// Enabling replay is necessary here because the standalone "GET" request
// is fully asynronous. Replay is needed to guarantee message delivery.
replay: true,
tool: func(t *testing.T, _ context.Context, ss *ServerSession) {
// Perform operations on a background context, and ensure the client
// receives it.
ctx := context.Background()
ctx, cancel := context.WithTimeout(context.Background(), 1*time.Second)
defer cancel()
if err := ss.NotifyProgress(ctx, &ProgressNotificationParams{}); err != nil {
t.Errorf("Notify failed: %v", err)
}
@ -816,7 +850,7 @@ func TestStreamableServerTransport(t *testing.T) {
// t.Errorf("Logging failed: %v", err)
// }
if _, err := ss.ListRoots(ctx, &ListRootsParams{}); err != nil {
t.Errorf("Notify failed: %v", err)
t.Errorf("ListRoots failed: %v", err)
}
},
requests: []streamableRequest{
@ -906,8 +940,14 @@ func TestStreamableServerTransport(t *testing.T) {
return &CallToolResult{}, nil
})
opts := &StreamableHTTPOptions{}
if test.replay {
opts.configureTransport = func(_ *http.Request, t *StreamableServerTransport) {
t.EventStore = NewMemoryEventStore(nil)
}
}
// Start the streamable handler.
handler := NewStreamableHTTPHandler(func(req *http.Request) *Server { return server }, nil)
handler := NewStreamableHTTPHandler(func(req *http.Request) *Server { return server }, opts)
defer handler.closeAll()
testStreamableHandler(t, handler, test.requests)