Restore ServerBuilder.WithMiddleware and WithRoute

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)
+	})
+}