Restore ServerBuilder.WithMiddleware and WithRoute (#5369)

* Restore ServerBuilder.WithMiddleware and WithRoute

These two methods are the only public API available to ApplyServerExtensions
hooks (the enterprise overlay uses them to inject session-auth middleware
and mount an /enterprise sub-router). #5355 dropped them as unreachable
because the only callers live behind //go:build enterprise, which upstream
CI does not exercise.

Add a unit test that exercises both methods so future deadcode passes see
them as live, and add doc comments explaining the extension-point contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Reword comments to describe the public extension contract

Reframe the doc comments and test rationale around the public extension
point itself ("ApplyServerExtensions consumers", "downstream repositories")
rather than the internal identity of any particular consumer. The behavior
of the methods is unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: reyortiz3

pkg/api/server.go

@@ -142,6 +142,35 @@ func (b *ServerBuilder) WithOtelEnabled(enabled bool) *ServerBuilder {
 	return b
 }
 
+// WithMiddleware appends HTTP middleware that runs after the default middleware
+// stack (request-ID, body-size limit, headers, update-check, auth) and before
+// route handlers. Part of the ApplyServerExtensions extension point — used by
+// downstream consumers to inject custom authentication or request-scoping
+// middleware into the API server.
+//
+// Public extension API. Do not remove based on deadcode analysis alone:
+// callers may live in repositories that are not visible to this module's
+// analyzer. The test in server_test.go intentionally exercises this method
+// to keep it reachable.
+func (b *ServerBuilder) WithMiddleware(mw ...func(http.Handler) http.Handler) *ServerBuilder {
+	b.middlewares = append(b.middlewares, mw...)
+	return b
+}
+
+// WithRoute mounts a sub-router at the given prefix. The caller is responsible
+// for any per-route timeout middleware. Part of the ApplyServerExtensions
+// extension point — used by downstream consumers to add API surface alongside
+// the built-in routes.
+//
+// Public extension API. Do not remove based on deadcode analysis alone:
+// callers may live in repositories that are not visible to this module's
+// analyzer. The test in server_test.go intentionally exercises this method
+// to keep it reachable.
+func (b *ServerBuilder) WithRoute(prefix string, handler http.Handler) *ServerBuilder {
+	b.customRoutes[prefix] = handler
+	return b
+}
+
 // Build creates and configures the HTTP router
 func (b *ServerBuilder) Build(ctx context.Context) (*chi.Mux, error) {
 	r := chi.NewRouter()

pkg/api/server_test.go

@@ -6,9 +6,11 @@ package api
 import (
 	"fmt"
 	"net"
+	"net/http"
 	"regexp"
 	"testing"
 
+	"github.com/go-chi/chi/v5"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -86,3 +88,43 @@ func TestListenURL(t *testing.T) {
 		})
 	}
 }
+
+// TestServerBuilderExtensionPoints exercises WithMiddleware and WithRoute so
+// they remain reachable to deadcode analysis. Both methods form the public
+// surface for ApplyServerExtensions consumers, whose callers may live in
+// downstream repositories that this module's analyzer cannot see. Without
+// this test, a future deadcode pass would flag them as unreachable (as
+// happened in #5355) even though external callers depend on them.
+func TestServerBuilderExtensionPoints(t *testing.T) {
+	t.Parallel()
+
+	t.Run("WithMiddleware appends to middleware chain", func(t *testing.T) {
+		t.Parallel()
+
+		b := NewServerBuilder()
+		mw := func(next http.Handler) http.Handler { return next }
+		b.WithMiddleware(mw, mw)
+
+		assert.Len(t, b.middlewares, 2)
+	})
+
+	t.Run("WithRoute registers handler at prefix", func(t *testing.T) {
+		t.Parallel()
+
+		b := NewServerBuilder()
+		b.WithRoute("/ext", chi.NewRouter())
+
+		_, ok := b.customRoutes["/ext"]
+		assert.True(t, ok, "expected /ext to be registered")
+	})
+
+	t.Run("methods chain on the builder", func(t *testing.T) {
+		t.Parallel()
+
+		b := NewServerBuilder().
+			WithMiddleware(func(next http.Handler) http.Handler { return next }).
+			WithRoute("/ext", chi.NewRouter())
+
+		assert.NotNil(t, b)
+	})
+}