refactor(server): introduce improved option system for HTTP servers

- Replace variadic interface{} options in NewSSEServer with a type-safe
  SSEOption interface.
- Add HTTPServerOption, SSEOption, StreamableHTTPOption, and
  CommonHTTPServerOption interfaces to support extensible, type-safe
  server configuration.
- Refactor all With* option constructors in sse.go and
  http_transport_options.go to use the new option interfaces and
  wrappers.
- Update NewSSEServer and NewTestServer to accept ...SSEOption.
- Prepare codebase for future server types (e.g., StreamableHTTPServer)
  and shared/common options.

Author: rwjblue-glean

server/http_transport_options.go

@@ -25,11 +25,69 @@ type httpTransportConfigurable interface {
 // HTTPTransportOption is a function that configures an httpTransportConfigurable.
 type HTTPTransportOption func(httpTransportConfigurable)
 
+// Option interfaces and wrappers for server configuration
+// Base option interface
+type HTTPServerOption interface {
+	isHTTPServerOption()
+}
+
+// SSE-specific option interface
+type SSEOption interface {
+	HTTPServerOption
+	applyToSSE(*SSEServer)
+}
+
+// StreamableHTTP-specific option interface
+type StreamableHTTPOption interface {
+	HTTPServerOption
+	applyToStreamableHTTP(*StreamableHTTPServer)
+}
+
+// Common options that work with both server types
+type CommonHTTPServerOption interface {
+	SSEOption
+	StreamableHTTPOption
+}
+
+// Wrapper for SSE-specific functional options
+type sseOption func(*SSEServer)
+
+func (o sseOption) isHTTPServerOption()     {}
+func (o sseOption) applyToSSE(s *SSEServer) { o(s) }
+
+// Wrapper for StreamableHTTP-specific functional options
+type streamableHTTPOption func(*StreamableHTTPServer)
+
+func (o streamableHTTPOption) isHTTPServerOption()                           {}
+func (o streamableHTTPOption) applyToStreamableHTTP(s *StreamableHTTPServer) { o(s) }
+
+// Refactor commonOption to use a single apply func(httpTransportConfigurable)
+type commonOption struct {
+	apply func(httpTransportConfigurable)
+}
+
+func (o commonOption) isHTTPServerOption()                           {}
+func (o commonOption) applyToSSE(s *SSEServer)                       { o.apply(s) }
+func (o commonOption) applyToStreamableHTTP(s *StreamableHTTPServer) { o.apply(s) }
+
+// TODO: Implement StreamableHTTPServer in the future
+type StreamableHTTPServer struct{}
+
+// Add stub methods to satisfy httpTransportConfigurable
+
+func (s *StreamableHTTPServer) setBasePath(string)                     {}
+func (s *StreamableHTTPServer) setDynamicBasePath(DynamicBasePathFunc) {}
+func (s *StreamableHTTPServer) setKeepAliveInterval(time.Duration)     {}
+func (s *StreamableHTTPServer) setKeepAlive(bool)                      {}
+func (s *StreamableHTTPServer) setContextFunc(HTTPContextFunc)         {}
+
 // WithStaticBasePath adds a new option for setting a static base path.
 // This is useful for mounting the server at a known, fixed path.
-func WithStaticBasePath(basePath string) HTTPTransportOption {
-	return func(c httpTransportConfigurable) {
-		c.setBasePath(basePath)
+func WithStaticBasePath(basePath string) CommonHTTPServerOption {
+	return commonOption{
+		apply: func(c httpTransportConfigurable) {
+			c.setBasePath(basePath)
+		},
 	}
 }
 
@@ -43,71 +101,80 @@ type DynamicBasePathFunc func(r *http.Request, sessionID string) string
 // WithDynamicBasePath accepts a function for generating the base path.
 // This is useful for cases where the base path is not known at the time of server creation,
 // such as when using a reverse proxy or when the server is mounted at a dynamic path.
-func WithDynamicBasePath(fn DynamicBasePathFunc) HTTPTransportOption {
-	return func(c httpTransportConfigurable) {
-		c.setDynamicBasePath(fn)
+func WithDynamicBasePath(fn DynamicBasePathFunc) CommonHTTPServerOption {
+	return commonOption{
+		apply: func(c httpTransportConfigurable) {
+			c.setDynamicBasePath(fn)
+		},
 	}
 }
 
 // WithKeepAliveInterval sets the keep-alive interval for the transport.
 // When enabled, the server will periodically send ping events to keep the connection alive.
-func WithKeepAliveInterval(interval time.Duration) HTTPTransportOption {
-	return func(c httpTransportConfigurable) {
-		c.setKeepAliveInterval(interval)
+func WithKeepAliveInterval(interval time.Duration) CommonHTTPServerOption {
+	return commonOption{
+		apply: func(c httpTransportConfigurable) {
+			c.setKeepAliveInterval(interval)
+		},
 	}
 }
 
 // WithKeepAlive enables or disables keep-alive for the transport.
 // When enabled, the server will send periodic keep-alive events to clients.
-func WithKeepAlive(keepAlive bool) HTTPTransportOption {
-	return func(c httpTransportConfigurable) {
-		c.setKeepAlive(keepAlive)
+func WithKeepAlive(keepAlive bool) CommonHTTPServerOption {
+	return commonOption{
+		apply: func(c httpTransportConfigurable) {
+			c.setKeepAlive(keepAlive)
+		},
 	}
 }
 
 // WithHTTPContextFunc sets a function that will be called to customize the context
 // for the server using the incoming request. This is useful for injecting
 // context values from headers or other request properties.
-func WithHTTPContextFunc(fn HTTPContextFunc) HTTPTransportOption {
-	return func(c httpTransportConfigurable) {
-		c.setContextFunc(fn)
+func WithHTTPContextFunc(fn HTTPContextFunc) CommonHTTPServerOption {
+	return commonOption{
+		apply: func(c httpTransportConfigurable) {
+			c.setContextFunc(fn)
+		},
 	}
 }
 
 // WithBaseURL sets the base URL for the HTTP transport server.
 // This is useful for configuring the externally visible base URL for clients.
-func WithBaseURL(baseURL string) HTTPTransportOption {
-	return func(c httpTransportConfigurable) {
-		if s, ok := c.(*SSEServer); ok {
-			if baseURL != "" {
-				u, err := url.Parse(baseURL)
-				if err != nil {
-					return
-				}
-				if u.Scheme != "http" && u.Scheme != "https" {
-					return
-				}
-				if u.Host == "" || strings.HasPrefix(u.Host, ":") {
-					return
-				}
-				if len(u.Query()) > 0 {
-					return
+func WithBaseURL(baseURL string) CommonHTTPServerOption {
+	return commonOption{
+		apply: func(c httpTransportConfigurable) {
+			if s, ok := c.(*SSEServer); ok {
+				if baseURL != "" {
+					u, err := url.Parse(baseURL)
+					if err != nil {
+						return
+					}
+					if u.Scheme != "http" && u.Scheme != "https" {
+						return
+					}
+					if u.Host == "" || strings.HasPrefix(u.Host, ":") {
+						return
+					}
+					if len(u.Query()) > 0 {
+						return
+					}
 				}
+				s.baseURL = strings.TrimSuffix(baseURL, "/")
 			}
-			s.baseURL = strings.TrimSuffix(baseURL, "/")
-		}
-		// For future protocols, add similar logic here
+		},
 	}
 }
 
 // WithHTTPServer sets the HTTP server instance for the transport.
 // This is useful for advanced scenarios where you want to provide your own http.Server.
-func WithHTTPServer(srv *http.Server) HTTPTransportOption {
-	return func(c httpTransportConfigurable) {
-		if s, ok := c.(*SSEServer); ok {
-			s.srv = srv
-		}
-		// For future protocols, add similar logic here
+func WithHTTPServer(srv *http.Server) CommonHTTPServerOption {
+	return commonOption{
+		apply: func(c httpTransportConfigurable) {
+			if s, ok := c.(*SSEServer); ok {
+				s.srv = srv
+			}
+		},
 	}
 }
-

server/sse.go

@@ -136,14 +136,20 @@ func (s *SSEServer) setContextFunc(fn HTTPContextFunc) {
 	s.contextFunc = fn
 }
 
-// SSEOption defines a function type for configuring SSEServer
-type SSEOption func(*SSEServer)
+// WithBasePath adds a new option for setting a static base path.
+//
+// Deprecated: Use WithStaticBasePath instead. This will be removed in a future version.
+//
+//go:deprecated
+func WithBasePath(basePath string) SSEOption {
+	return WithStaticBasePath(basePath)
+}
 
 // WithMessageEndpoint sets the message endpoint path
 func WithMessageEndpoint(endpoint string) SSEOption {
-	return func(s *SSEServer) {
+	return sseOption(func(s *SSEServer) {
 		s.messageEndpoint = endpoint
-	}
+	})
 }
 
 // WithAppendQueryToMessageEndpoint configures the SSE server to append the original request's
@@ -152,25 +158,25 @@ func WithMessageEndpoint(endpoint string) SSEOption {
 // SSE connection request and carry them over to subsequent message requests, maintaining
 // context or authentication details across the communication channel.
 func WithAppendQueryToMessageEndpoint() SSEOption {
-	return func(s *SSEServer) {
+	return sseOption(func(s *SSEServer) {
 		s.appendQueryToMessageEndpoint = true
-	}
+	})
 }
 
 // WithUseFullURLForMessageEndpoint controls whether the SSE server returns a complete URL (including baseURL)
 // or just the path portion for the message endpoint. Set to false when clients will concatenate
 // the baseURL themselves to avoid malformed URLs like "http://localhost/mcphttp://localhost/mcp/message".
 func WithUseFullURLForMessageEndpoint(useFullURLForMessageEndpoint bool) SSEOption {
-	return func(s *SSEServer) {
+	return sseOption(func(s *SSEServer) {
 		s.useFullURLForMessageEndpoint = useFullURLForMessageEndpoint
-	}
+	})
 }
 
 // WithSSEEndpoint sets the SSE endpoint path
 func WithSSEEndpoint(endpoint string) SSEOption {
-	return func(s *SSEServer) {
+	return sseOption(func(s *SSEServer) {
 		s.sseEndpoint = endpoint
-	}
+	})
 }
 
 // WithSSEContextFunc sets a function that will be called to customise the context
@@ -179,13 +185,13 @@ func WithSSEEndpoint(endpoint string) SSEOption {
 // Deprecated: Use WithContextFunc instead. This will be removed in a future version.
 //go:deprecated
 func WithSSEContextFunc(fn SSEContextFunc) SSEOption {
-	return func(s *SSEServer) {
-		WithHTTPContextFunc(HTTPContextFunc(fn))(s)
-	}
+	return sseOption(func(s *SSEServer) {
+		WithHTTPContextFunc(HTTPContextFunc(fn)).applyToSSE(s)
+	})
 }
 
 // NewSSEServer creates a new SSE server instance with the given MCP server and options.
-func NewSSEServer(server *MCPServer, opts ...interface{}) *SSEServer {
+func NewSSEServer(server *MCPServer, opts ...SSEOption) *SSEServer {
 	s := &SSEServer{
 		server:                       server,
 		sseEndpoint:                  "/sse",
@@ -197,22 +203,15 @@ func NewSSEServer(server *MCPServer, opts ...interface{}) *SSEServer {
 
 	// Apply all options
 	for _, opt := range opts {
-		switch o := opt.(type) {
-		case SSEOption:
-			o(s)
-		case HTTPTransportOption:
-			o(s)
-		default:
-			// Optionally: log or panic for unknown option type
-		}
+		opt.applyToSSE(s)
 	}
 
 	return s
 }
 
 // NewTestServer creates a test server for testing purposes.
 // It takes the same options as NewSSEServer (variadic ...interface{}).
-func NewTestServer(server *MCPServer, opts ...interface{}) *httptest.Server {
+func NewTestServer(server *MCPServer, opts ...SSEOption) *httptest.Server {
 	sseServer := NewSSEServer(server, opts...)
 	testServer := httptest.NewServer(sseServer)
 	sseServer.baseURL = testServer.URL

server/sse_test.go

@@ -715,7 +715,7 @@ func TestSSEServer(t *testing.T) {
 		sseEndpoint := "/sse-test"
 		useFullURLForMessageEndpoint := false
 		srv := &http.Server{}
-		rands := []interface {}{
+		rands := []SSEOption{
 			WithStaticBasePath(basePath),
 			WithBaseURL(baseURL),
 			WithMessageEndpoint(messageEndpoint),
@@ -725,7 +725,7 @@ func TestSSEServer(t *testing.T) {
 		}
 		for i := 0; i < 100; i++ {
 
-			var options []interface {}
+			var options []SSEOption
 			for i2 := 0; i2 < 100; i2++ {
 				index := rand.Intn(len(rands))
 				options = append(options, rands[index])