Integrate dev → main: inference routing (upstream router + remote chat) + OpenAPI describability + queued API work

go.work.sum

@@ -1,9 +1,17 @@
-github.com/golang/protobuf v1.5.0/go.mod h1:FsONVRAS9T7sI+LIUmWTfcYkHO4aIWwzhcaSAoJOfIk=
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
 github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
+github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+go.mongodb.org/mongo-driver v1.17.3 h1:TQyXhnsWfWtgAhMtOgtYHMTkZIfBTpMTsMnd9ZBeHxQ=
 golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
 golang.org/x/sync v0.11.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
 golang.org/x/sys v0.30.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
 google.golang.org/protobuf v1.26.0-rc.1/go.mod h1:jlhhOSvTdKEhbULTjvd4ARK9grFBp09yW+WbY/TyQbw=
 google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=
-rsc.io/pdf v0.1.1/go.mod h1:n8OzWcQ6Sp37PL01nO98y4iUCRdTGarVfzxY20ICaU4=

go/api.go

@@ -7,6 +7,7 @@ package api
 import (
 	"context"
 	"iter"
+	"net"      // Note: AX-6 — net.SplitHostPort/ParseIP are structural for loopback bind classification; no core primitive
 	"net/http" // Note: AX-6 — structural HTTP boundary for Handler/WebSocket contracts; no core primitive
 	"reflect"  // Note: AX-6 — reflect is structural for runtime nil-pointer detection in handler binding; no core primitive
 	"slices"
@@ -22,6 +23,17 @@ import (
 
 const defaultAddr = ":8080"
 
+var (
+	// ErrNonLoopbackBind is returned by Serve under strict bind mode when the
+	// configured listen address is not loopback and WithPublicBind was not
+	// set. Strict mode is opt-in via WithStrictBind / WithLoopbackOnly.
+	ErrNonLoopbackBind = core.NewError("api: strict bind rejects non-loopback address without WithPublicBind")
+	// ErrPublicBindNoBearer is returned by Serve under strict bind mode when a
+	// public (non-loopback) bind is requested without a bearer credential
+	// supplied via WithBearerAuth.
+	ErrPublicBindNoBearer = core.NewError("api: strict bind rejects public address without WithBearerAuth")
+)
+
 // shutdownTimeout is the maximum duration to wait for in-flight requests
 // to complete during graceful shutdown.
 const shutdownTimeout = 10 * time.Second
@@ -83,10 +95,37 @@ type Engine struct {
 	i18nConfig                     I18nConfig
 	openAPISpecEnabled             bool
 	openAPISpecPath                string
+	// strictBind, when set via WithStrictBind / WithLoopbackOnly, makes
+	// Serve refuse a non-loopback listen address unless publicBind is also
+	// set, and refuse to serve a public bind without a bearer credential.
+	// Default false preserves the historic permissive behaviour so existing
+	// consumers (go-ml, go-ai, desktop, core-agent) are not broken.
+	strictBind bool
+	// publicBind, when set via WithPublicBind, is the explicit opt-in that
+	// allows a non-loopback bind under strict mode. It carries no effect
+	// when strictBind is false. A public bind still requires a bearer.
+	publicBind bool
+	// bearerConfigured records that a bearer credential was supplied via
+	// WithBearerAuth. Strict mode refuses to serve a public listener
+	// without one.
+	bearerConfigured bool
+	// bearerToken is the static bearer credential supplied via WithBearerAuth.
+	// The chat endpoint's off-loopback gate validates the inbound request
+	// against this token directly so it fails closed independently of the
+	// bearer middleware's path coverage.
+	bearerToken string
 	// noRouteHandler is the SPA / fallback handler invoked when no
 	// registered route matches the request. Set via WithNoRoute; nil
 	// means gin returns 404 with its default body.
-	noRouteHandler                 gin.HandlerFunc
+	noRouteHandler gin.HandlerFunc
+	// upstreamRouter, when set via WithUpstreamRouter, mounts a selector-keyed
+	// reverse proxy over a pool of HTTP upstreams at the configured paths.
+	upstreamRouter *upstreamRouterConfig
+	// chatRemote, when set via WithChatCompletionsRemote, adds a remote backend
+	// to the chat completions endpoint (local-first dispatch).
+	chatRemote *chatRemoteConfig
+	// chatAllowRemote permits non-loopback chat clients when a bearer is set.
+	chatAllowRemote bool
 }
 
 // New creates an Engine with the given options.
@@ -109,7 +148,7 @@ func New(opts ...Option) (
 		opt(e)
 	}
 	// Apply calibrated defaults for optional subsystems.
-	if e.chatCompletionsResolver != nil && core.Trim(e.chatCompletionsPath) == "" {
+	if (e.chatCompletionsResolver != nil || e.chatRemote != nil) && core.Trim(e.chatCompletionsPath) == "" {
 		e.chatCompletionsPath = defaultChatCompletionsPath
 	}
 	return e, nil
@@ -247,6 +286,10 @@ func (e *Engine) Handler() http.Handler {
 func (e *Engine) Serve(ctx context.Context) (
 	_ error,
 ) {
+	if err := e.validateBind(); err != nil {
+		return err
+	}
+
 	srv := &http.Server{
 		Addr:              e.addr,
 		Handler:           e.build(),
@@ -289,6 +332,83 @@ func (e *Engine) Serve(ctx context.Context) (
 	return <-errCh
 }
 
+// validateBind enforces the strict bind invariants before Serve binds a
+// listener. It is a no-op unless WithStrictBind / WithLoopbackOnly was set, so
+// existing consumers that bind non-loopback addresses are unaffected.
+//
+// Under strict mode:
+//   - a loopback address always serves;
+//   - a non-loopback address is rejected unless WithPublicBind is set;
+//   - a non-loopback address with WithPublicBind set still requires a bearer
+//     credential (WithBearerAuth), and is otherwise rejected.
+//
+// Example:
+//
+//	e, _ := api.New(api.WithAddr("0.0.0.0:8787"), api.WithStrictBind())
+//	err := e.Serve(ctx) // err == api.ErrNonLoopbackBind
+func (e *Engine) validateBind() (
+	_ error,
+) {
+	if !e.strictBind {
+		return nil
+	}
+	if addrIsLoopback(e.addr) {
+		return nil
+	}
+	if !e.publicBind {
+		return core.E("api.bind", e.addr, ErrNonLoopbackBind)
+	}
+	if !e.bearerConfigured {
+		return core.E("api.bind", e.addr, ErrPublicBindNoBearer)
+	}
+	return nil
+}
+
+// addrIsLoopback reports whether a listen address binds only the loopback
+// interface. The host portion is parsed from "host:port"; a bare ":port" or an
+// unspecified host ("0.0.0.0", "::", empty) is treated as non-loopback because
+// it binds all interfaces. The textual host "localhost" is treated as loopback.
+//
+// Example:
+//
+//	addrIsLoopback("127.0.0.1:8787") // true
+//	addrIsLoopback("[::1]:8787")     // true
+//	addrIsLoopback("localhost:8787") // true
+//	addrIsLoopback("0.0.0.0:8787")   // false
+//	addrIsLoopback(":8787")          // false
+func addrIsLoopback(addr string) bool {
+	addr = core.Trim(addr)
+	if addr == "" {
+		return false
+	}
+
+	host, _, err := net.SplitHostPort(addr)
+	if err != nil {
+		// No port separator (or malformed); treat the whole string as the host.
+		host = addr
+	}
+
+	host = core.Trim(host)
+	if host == "" {
+		// Bare ":port" — binds every interface, not loopback.
+		return false
+	}
+	if host == "localhost" {
+		return true
+	}
+
+	ip := net.ParseIP(host)
+	if ip == nil {
+		// A named host other than localhost is not a loopback guarantee.
+		return false
+	}
+	if ip.IsUnspecified() {
+		// 0.0.0.0 / :: bind all interfaces.
+		return false
+	}
+	return ip.IsLoopback()
+}
+
 // SetNoRoute attaches or replaces the fallback handler invoked when
 // no registered route matches the incoming request. Mirrors the
 // WithNoRoute Option but is callable after construction — useful
@@ -329,10 +449,24 @@ func (e *Engine) build() *gin.Engine {
 		c.JSON(http.StatusOK, OK("healthy"))
 	})
 
-	// Mount the local OpenAI-compatible chat completion endpoint when configured.
-	if e.chatCompletionsResolver != nil {
-		h := newChatCompletionsHandler(e.chatCompletionsResolver)
-		r.POST(e.chatCompletionsPath, h.ServeHTTP)
+	// Mount the OpenAI-compatible chat completion endpoint when a local resolver
+	// and/or a remote backend is configured.
+	if e.chatCompletionsResolver != nil || e.chatRemote != nil {
+		path := e.chatCompletionsPath
+		if core.Trim(path) == "" {
+			path = defaultChatCompletionsPath
+		}
+		h := newChatCompletionsHandler(e.chatCompletionsResolver, e.chatRemote, e.chatAllowRemote, bearerValidator(e.bearerToken))
+		r.POST(path, h.ServeHTTP)
+	}
+
+	// Mount the selector-keyed upstream router when configured.
+	if e.upstreamRouter != nil {
+		proxy := e.upstreamRouter.buildProxy()
+		h := e.upstreamRouter.handler(proxy)
+		for _, p := range e.upstreamRouter.paths {
+			r.Any(p, h)
+		}
 	}
 
 	if e.sdkGenEnabled {

go/api_describable_test.go

@@ -17,10 +17,12 @@ type describableSpecGroup struct {
 	descs    []api.RouteDescription
 }
 
-func (g *describableSpecGroup) Name() string                       { return g.name }
-func (g *describableSpecGroup) BasePath() string                   { return g.basePath }
-func (g *describableSpecGroup) RegisterRoutes(rg *gin.RouterGroup) {}
-func (g *describableSpecGroup) Describe() []api.RouteDescription   { return g.descs }
+func (g *describableSpecGroup) Name() string     { return g.name }
+func (g *describableSpecGroup) BasePath() string { return g.basePath }
+func (g *describableSpecGroup) RegisterRoutes(rg *gin.RouterGroup) {
+	// Required by RouteGroup; routes are registered through the Describe path only.
+}
+func (g *describableSpecGroup) Describe() []api.RouteDescription { return g.descs }
 
 type describableHandler struct {
 	desc            api.RouteDescription
@@ -75,12 +77,12 @@ func buildDescribableOperation(t *testing.T, group api.RouteGroup, path, method
 
 	data, err := builder.Build([]api.RouteGroup{group})
 	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
+		t.Fatalf(fmtTestUnexpectedErr, err)
 	}
 
 	var spec map[string]any
 	if err := coreJSONUnmarshal(data, &spec); err != nil {
-		t.Fatalf("invalid JSON: %v", err)
+		t.Fatalf(fmtTestInvalidJSON, err)
 	}
 
 	paths := spec["paths"].(map[string]any)
@@ -146,15 +148,15 @@ func TestDescribable_Good_HandlerMetadataFlowsToOpenAPI(t *testing.T) {
 
 	tags, ok := operation["tags"].([]any)
 	if !ok {
-		t.Fatalf("expected tags array, got %T", operation["tags"])
+		t.Fatalf(fmtTestExpectedTags, operation["tags"])
 	}
 	if len(tags) != 2 || tags[0] != "widgets" || tags[1] != "catalog" {
 		t.Fatalf("expected handler tags, got %v", tags)
 	}
 
 	requestBody := operation["requestBody"].(map[string]any)
 	content := requestBody["content"].(map[string]any)
-	schema := content["application/json"].(map[string]any)["schema"].(map[string]any)
+	schema := content[mimeJSON].(map[string]any)["schema"].(map[string]any)
 	properties := schema["properties"].(map[string]any)
 	if _, ok := properties["name"]; !ok {
 		t.Fatal("expected request body schema from handler Describe")
@@ -173,7 +175,7 @@ func TestDescribable_Bad_MissingHandlerMetadataFallsBackSafely(t *testing.T) {
 		descs: []api.RouteDescription{
 			{
 				Method:      http.MethodGet,
-				Path:        "/status",
+				Path:        pathStatus,
 				Summary:     "Widget status",
 				Description: "Returns widget availability.",
 				Tags:        []string{"status"},
@@ -196,7 +198,7 @@ func TestDescribable_Bad_MissingHandlerMetadataFallsBackSafely(t *testing.T) {
 
 	tags, ok := operation["tags"].([]any)
 	if !ok {
-		t.Fatalf("expected tags array, got %T", operation["tags"])
+		t.Fatalf(fmtTestExpectedTags, operation["tags"])
 	}
 	if len(tags) != 1 || tags[0] != "status" {
 		t.Fatalf("expected route tag fallback, got %v", tags)
@@ -210,7 +212,7 @@ func TestDescribable_Ugly_NilHandlerIsIgnored(t *testing.T) {
 		descs: []api.RouteDescription{
 			{
 				Method:  http.MethodGet,
-				Path:    "/status",
+				Path:    pathStatus,
 				Handler: (*describableHandler)(nil),
 			},
 		},
@@ -224,7 +226,7 @@ func TestDescribable_Ugly_NilHandlerIsIgnored(t *testing.T) {
 
 	tags, ok := operation["tags"].([]any)
 	if !ok {
-		t.Fatalf("expected tags array, got %T", operation["tags"])
+		t.Fatalf(fmtTestExpectedTags, operation["tags"])
 	}
 	if len(tags) != 1 || tags[0] != "widgets" {
 		t.Fatalf("expected group-name tag fallback, got %v", tags)

go/api_renderable_test.go

@@ -17,10 +17,12 @@ type renderableSpecGroup struct {
 	descs    []api.RouteDescription
 }
 
-func (g *renderableSpecGroup) Name() string                       { return g.name }
-func (g *renderableSpecGroup) BasePath() string                   { return g.basePath }
-func (g *renderableSpecGroup) RegisterRoutes(rg *gin.RouterGroup) {}
-func (g *renderableSpecGroup) Describe() []api.RouteDescription   { return g.descs }
+func (g *renderableSpecGroup) Name() string     { return g.name }
+func (g *renderableSpecGroup) BasePath() string { return g.basePath }
+func (g *renderableSpecGroup) RegisterRoutes(rg *gin.RouterGroup) {
+	// Required by RouteGroup; routes are registered through the Describe path only.
+}
+func (g *renderableSpecGroup) Describe() []api.RouteDescription { return g.descs }
 
 type renderableHandler struct {
 	hints api.RenderHints
@@ -43,12 +45,12 @@ func buildRenderableOperation(t *testing.T, group api.RouteGroup, path, method s
 
 	data, err := builder.Build([]api.RouteGroup{group})
 	if err != nil {
-		t.Fatalf("unexpected error: %v", err)
+		t.Fatalf(fmtTestUnexpectedErr, err)
 	}
 
 	var spec map[string]any
 	if err := coreJSONUnmarshal(data, &spec); err != nil {
-		t.Fatalf("invalid JSON: %v", err)
+		t.Fatalf(fmtTestInvalidJSON, err)
 	}
 
 	paths := spec["paths"].(map[string]any)
@@ -144,7 +146,7 @@ func TestRenderable_Bad_EmptyHintsAreOmittedSafely(t *testing.T) {
 		descs: []api.RouteDescription{
 			{
 				Method:  http.MethodGet,
-				Path:    "/status",
+				Path:    pathStatus,
 				Handler: &renderableHandler{},
 			},
 		},
@@ -164,7 +166,7 @@ func TestRenderable_Ugly_NilHandlerIsIgnored(t *testing.T) {
 		descs: []api.RouteDescription{
 			{
 				Method:  http.MethodGet,
-				Path:    "/status",
+				Path:    pathStatus,
 				Handler: (*renderableHandler)(nil),
 			},
 		},