Apply stateless mode to all transports

Move stateless configuration outside the remote-URL guard so
--stateless works for both remote URLs and local container
workloads. Add Allow header to 405 responses per RFC 9110.
Update comments and flag text to remove remote-only language.

Signed-off-by: Greg Katz <gkatz@indeed.com>

Author: gkatz2

cmd/thv/app/run_flags.go

@@ -58,7 +58,7 @@ type RunFlags struct {
 	// Remote MCP server support
 	RemoteURL string
 
-	// Stateless indicates the remote server is stateless (POST-only, no SSE)
+	// Stateless indicates the server is stateless (POST-only, no SSE)
 	Stateless bool
 
 	// Security and audit
@@ -257,7 +257,7 @@ func AddRunFlags(cmd *cobra.Command, config *RunFlags) {
 		"Trust X-Forwarded-* headers from reverse proxies (X-Forwarded-Proto, X-Forwarded-Host, X-Forwarded-Port, X-Forwarded-Prefix) "+
 			"(default false)")
 	cmd.Flags().BoolVar(&config.Stateless, "stateless", false,
-		"Declare the remote server as stateless (POST-only, no SSE). "+
+		"Declare the server as stateless (POST-only, no SSE). "+
 			"Use for MCP servers implementing streamable-HTTP stateless mode.")
 	cmd.Flags().StringVar(&config.EndpointPrefix, "endpoint-prefix", "",
 		"Path prefix to prepend to SSE endpoint URLs (e.g., /playwright)")

docs/cli/thv_run.md

@@ -191,10 +191,10 @@ type RunConfig struct {
 	// TrustProxyHeaders indicates whether to trust X-Forwarded-* headers from reverse proxies
 	TrustProxyHeaders bool `json:"trust_proxy_headers,omitempty" yaml:"trust_proxy_headers,omitempty"`
 
-	// Stateless indicates the remote server only supports POST (no SSE/GET).
+	// Stateless indicates the server only supports POST (no SSE/GET).
 	// When true, the proxy returns 405 for incoming GET requests and uses a
 	// POST-based health check instead of the default GET probe.
-	// Only meaningful when RemoteURL is set.
+	// Applies to both remote URLs and local container workloads.
 	Stateless bool `json:"stateless,omitempty" yaml:"stateless,omitempty"`
 
 	// ProxyMode is the effective HTTP protocol the proxy uses.

docs/server/docs.go

@@ -319,7 +319,7 @@ func WithTrustProxyHeaders(trust bool) RunConfigBuilderOption {
 	}
 }
 
-// WithStateless declares the remote server is stateless (POST-only, no SSE).
+// WithStateless declares the server is stateless (POST-only, no SSE).
 func WithStateless(stateless bool) RunConfigBuilderOption {
 	return func(b *runConfigBuilder) error {
 		b.config.Stateless = stateless

docs/server/swagger.json

@@ -305,12 +305,6 @@ func (r *Runner) Run(ctx context.Context) error {
 	// Set up the transport
 	slog.Debug("setting up transport", "transport", r.Config.Transport)
 
-	// Warn if stateless mode is set for a non-remote workload — it has no effect.
-	if r.Config.Stateless && r.Config.RemoteURL == "" {
-		slog.Warn("--stateless has no effect for local container workloads; use it only with remote URLs",
-			"server", r.Config.BaseName)
-	}
-
 	// Prepare transport options based on workload type
 	var transportOpts []transport.Option
 	var setupResult *runtime.SetupResult
@@ -431,16 +425,6 @@ func (r *Runner) Run(ctx context.Context) error {
 			}
 		})
 
-		// Configure stateless mode if requested. Remote workloads always use
-		// HTTPTransport, so a failed cast here is a programming error.
-		if r.Config.Stateless {
-			httpT, ok := transportHandler.(*transport.HTTPTransport)
-			if !ok {
-				return fmt.Errorf("internal error: remote transport is not an HTTPTransport")
-			}
-			httpT.SetStateless(true)
-		}
-
 		// Set the unauthorized response callback for bearer token authentication
 		errorMsg := "Bearer token authentication failed. Please restart the server with a new token"
 		transportHandler.SetOnUnauthorizedResponse(func() {
@@ -459,6 +443,17 @@ func (r *Runner) Run(ctx context.Context) error {
 		})
 	}
 
+	// Configure stateless mode if requested. Stateless mode applies to any
+	// streamable-HTTP server (remote or local container) where the upstream
+	// only accepts POST and does not support SSE-based sessions.
+	if r.Config.Stateless {
+		httpT, ok := transportHandler.(*transport.HTTPTransport)
+		if !ok {
+			return fmt.Errorf("--stateless requires streamable-HTTP or SSE transport, got %T", transportHandler)
+		}
+		httpT.SetStateless(true)
+	}
+
 	// Start the transport (which also starts the container and monitoring)
 	slog.Debug("starting transport", "transport", r.Config.Transport, "container", r.Config.ContainerName)
 	if err := transportHandler.Start(ctx); err != nil {

docs/server/swagger.yaml

@@ -58,7 +58,7 @@ type HTTPTransport struct {
 	// Remote MCP server support
 	remoteURL string
 
-	// stateless indicates the remote server is POST-only (no SSE/GET support)
+	// stateless indicates the server is POST-only (no SSE/GET support)
 	stateless bool
 
 	// tokenSource is the OAuth token source for remote authentication
@@ -155,7 +155,7 @@ func (t *HTTPTransport) SetOnHealthCheckFailed(callback types.HealthCheckFailedC
 	t.onHealthCheckFailed = callback
 }
 
-// SetStateless configures the transport for a stateless remote server.
+// SetStateless configures the transport for a stateless server.
 func (t *HTTPTransport) SetStateless(stateless bool) {
 	t.stateless = stateless
 }

pkg/runner/config.go

@@ -22,21 +22,25 @@ func TestStatelessMethodGate(t *testing.T) {
 		name           string
 		method         string
 		expectedStatus int
+		expectAllow    bool
 	}{
 		{
-			name:           "GET returns 405",
+			name:           "GET returns 405 with Allow header",
 			method:         http.MethodGet,
 			expectedStatus: http.StatusMethodNotAllowed,
+			expectAllow:    true,
 		},
 		{
-			name:           "HEAD returns 405",
+			name:           "HEAD returns 405 with Allow header",
 			method:         http.MethodHead,
 			expectedStatus: http.StatusMethodNotAllowed,
+			expectAllow:    true,
 		},
 		{
-			name:           "DELETE returns 405",
+			name:           "DELETE returns 405 with Allow header",
 			method:         http.MethodDelete,
 			expectedStatus: http.StatusMethodNotAllowed,
+			expectAllow:    true,
 		},
 		{
 			name:           "POST is forwarded",
@@ -61,6 +65,9 @@ func TestStatelessMethodGate(t *testing.T) {
 			handler.ServeHTTP(rec, req)
 
 			assert.Equal(t, tc.expectedStatus, rec.Code)
+			if tc.expectAllow {
+				assert.Equal(t, "POST, OPTIONS", rec.Header().Get("Allow"))
+			}
 		})
 	}
 }