internal/mcp: rename Stream->Connection

After implementing the Streamable transport, it is apparent to me that
the name 'Stream' is confusing, as it can refer either to a stream in
the streamable transport, or to a JSON-RPC stream.

But the name 'Connection' is available, and a natural name for the
result of the Transport.Connect interface method. Therefore, rename
Stream to Connection, and update the streamable implementation to refer
to its HTTP connections as 'streams', consistent with other SDKs.

Change-Id: Ica55f84caabcbfa5a2fe029cc0c2db57da574875
Reviewed-on: https://go-review.googlesource.com/c/tools/+/682376
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Jonathan Amsterdam <jba@google.com>
This commit is contained in:
Rob Findley 2025-06-17 16:56:36 +00:00 • committed by Robert Findley
commit 1fead0ba64

View file

@ -28,10 +28,10 @@ var ErrConnectionClosed = errors.New("connection closed")
// Transports should be used for at most one call to [Server.Connect] or
// [Client.Start].
type Transport interface {
// Connect returns the logical stream.
// Connect returns the logical JSON-RPC connection..
//
// It is called exactly once by [Server.Connect] or [Client.Connect].
Connect(ctx context.Context) (Stream, error)
Connect(ctx context.Context) (Connection, error)
}
type (
@ -47,8 +47,8 @@ type (
JSONRPCResponse = jsonrpc2.Response
)
// A Stream is a bidirectional jsonrpc2 Stream.
type Stream interface {
// A Connection is a logical bidirectional JSON-RPC connection.
type Connection interface {
Read(context.Context) (JSONRPCMessage, error)
Write(context.Context, JSONRPCMessage) error
Close() error // may be called concurrently by both peers
@ -66,8 +66,8 @@ type ioTransport struct {
rwc io.ReadWriteCloser
}
func (t *ioTransport) Connect(context.Context) (Stream, error) {
return newIOStream(t.rwc), nil
func (t *ioTransport) Connect(context.Context) (Connection, error) {
return newIOConn(t.rwc), nil
}
// NewStdIOTransport constructs a transport that communicates over
@ -100,12 +100,12 @@ type handler interface {
func connect[H handler](ctx context.Context, t Transport, b binder[H]) (H, error) {
var zero H
stream, err := t.Connect(ctx)
conn, err := t.Connect(ctx)
if err != nil {
return zero, err
}
// If logging is configured, write message logs.
reader, writer := jsonrpc2.Reader(stream), jsonrpc2.Writer(stream)
reader, writer := jsonrpc2.Reader(conn), jsonrpc2.Writer(conn)
var (
h H
preempter canceller
@ -118,7 +118,7 @@ func connect[H handler](ctx context.Context, t Transport, b binder[H]) (H, error
_ = jsonrpc2.NewConnection(ctx, jsonrpc2.ConnectionConfig{
Reader: reader,
Writer: writer,
Closer: stream,
Closer: conn,
Bind: bind,
Preempter: &preempter,
OnDone: func() {
@ -187,23 +187,23 @@ func NewLoggingTransport(delegate Transport, w io.Writer) *LoggingTransport {
return &LoggingTransport{delegate, w}
}
// Connect connects the underlying transport, returning a [Stream] that writes
// Connect connects the underlying transport, returning a [Connection] that writes
// logs to the configured destination.
func (t *LoggingTransport) Connect(ctx context.Context) (Stream, error) {
func (t *LoggingTransport) Connect(ctx context.Context) (Connection, error) {
delegate, err := t.delegate.Connect(ctx)
if err != nil {
return nil, err
}
return &loggingStream{delegate, t.w}, nil
return &loggingConn{delegate, t.w}, nil
}
type loggingStream struct {
delegate Stream
type loggingConn struct {
delegate Connection
w io.Writer
}
// loggingReader is a stream middleware that logs incoming messages.
func (s *loggingStream) Read(ctx context.Context) (jsonrpc2.Message, error) {
func (s *loggingConn) Read(ctx context.Context) (jsonrpc2.Message, error) {
msg, err := s.delegate.Read(ctx)
if err != nil {
fmt.Fprintf(s.w, "read error: %v", err)
@ -218,7 +218,7 @@ func (s *loggingStream) Read(ctx context.Context) (jsonrpc2.Message, error) {
}
// loggingWriter is a stream middleware that logs outgoing messages.
func (s *loggingStream) Write(ctx context.Context, msg jsonrpc2.Message) error {
func (s *loggingConn) Write(ctx context.Context, msg jsonrpc2.Message) error {
err := s.delegate.Write(ctx, msg)
if err != nil {
fmt.Fprintf(s.w, "write error: %v", err)
@ -232,7 +232,7 @@ func (s *loggingStream) Write(ctx context.Context, msg jsonrpc2.Message) error {
return err
}
func (s *loggingStream) Close() error {
func (s *loggingConn) Close() error {
return s.delegate.Close()
}
@ -255,14 +255,14 @@ func (r rwc) Close() error {
return errors.Join(r.rc.Close(), r.wc.Close())
}
// An ioStream is a transport that delimits messages with newlines across
// An ioConn is a transport that delimits messages with newlines across
// a bidirectional stream, and supports JSONRPC2 message batching.
//
// See https://github.com/ndjson/ndjson-spec for discussion of newline
// delimited JSON.
//
// See [msgBatch] for more discussion of message batching.
type ioStream struct {
type ioConn struct {
rwc io.ReadWriteCloser // the underlying stream
in *json.Decoder // a decoder bound to rwc
@ -280,23 +280,18 @@ type ioStream struct {
batches map[jsonrpc2.ID]*msgBatch // lazily allocated
}
func newIOStream(rwc io.ReadWriteCloser) *ioStream {
return &ioStream{
func newIOConn(rwc io.ReadWriteCloser) *ioConn {
return &ioConn{
rwc: rwc,
in: json.NewDecoder(rwc),
}
}
// Connect returns the receiver, as a streamTransport is a logical stream.
func (t *ioStream) Connect(ctx context.Context) (Stream, error) {
return t, nil
}
// addBatch records a msgBatch for an incoming batch payload.
// It returns an error if batch is malformed, containing previously seen IDs.
//
// See [msgBatch] for more.
func (t *ioStream) addBatch(batch *msgBatch) error {
func (t *ioConn) addBatch(batch *msgBatch) error {
t.batchMu.Lock()
defer t.batchMu.Unlock()
for id := range batch.unresolved {
@ -319,7 +314,7 @@ func (t *ioStream) addBatch(batch *msgBatch) error {
// The second result reports whether resp was part of a batch. If this is true,
// the first result is nil if the batch is still incomplete, or the full set of
// batch responses if resp completed the batch.
func (t *ioStream) updateBatch(resp *jsonrpc2.Response) ([]*jsonrpc2.Response, bool) {
func (t *ioConn) updateBatch(resp *jsonrpc2.Response) ([]*jsonrpc2.Response, bool) {
t.batchMu.Lock()
defer t.batchMu.Unlock()
@ -357,11 +352,11 @@ type msgBatch struct {
responses []*jsonrpc2.Response
}
func (t *ioStream) Read(ctx context.Context) (jsonrpc2.Message, error) {
func (t *ioConn) Read(ctx context.Context) (jsonrpc2.Message, error) {
return t.read(ctx, t.in)
}
func (t *ioStream) read(ctx context.Context, in *json.Decoder) (jsonrpc2.Message, error) {
func (t *ioConn) read(ctx context.Context, in *json.Decoder) (jsonrpc2.Message, error) {
select {
case <-ctx.Done():
return nil, ctx.Err()
@ -432,7 +427,7 @@ func readBatch(data []byte) (msgs []jsonrpc2.Message, isBatch bool, _ error) {
return []jsonrpc2.Message{msg}, false, err
}
func (t *ioStream) Write(ctx context.Context, msg jsonrpc2.Message) error {
func (t *ioConn) Write(ctx context.Context, msg jsonrpc2.Message) error {
select {
case <-ctx.Done():
return ctx.Err()
@ -479,7 +474,7 @@ func (t *ioStream) Write(ctx context.Context, msg jsonrpc2.Message) error {
return err
}
func (t *ioStream) Close() error {
func (t *ioConn) Close() error {
return t.rwc.Close()
}