feat(api): add WithNoRoute(handler) Option for SPA-host fallback

The Engine builds gin's NoRoute hook from a new noRouteHandler
field, set via WithNoRoute(h gin.HandlerFunc). Mounted after every
explicit route + group so it never shadows real handlers; nil
preserves gin's default 404 behaviour (back-compat with pre-option
callers).

Use case: lthn/desktop and lthn.ai-hosted Engines both serve an
SPA whose client-router owns the URL space. Today they wrap the
gin engine via Handler() and call NoRoute() directly, which means
they bypass any auth/SSRF/cache middleware composed into the
Engine. With WithNoRoute the SPA fallback becomes part of the
canonical Engine build and inherits the middleware chain.

go:
- pkg/api: Engine gains `noRouteHandler gin.HandlerFunc`
- new option WithNoRoute(h) sets it
- build() registers it via r.NoRoute(...) when non-nil
- TestWithNoRoute_{Good,Bad,Ugly} AX-7 triplet
- ExampleWithNoRoute() showing the SPA-host pattern

Also dedupes accidentally-duplicated TestSDKGenerator_Generate_
PackageName{Accepted_Good,Rejected_Bad} from the PR #3 merge
(two identical copies of the same two tests at 199-269 and
270-339 caused the test binary to fail compile).

Author: Snider

go/api.go

@@ -83,6 +83,10 @@ type Engine struct {
 	i18nConfig                     I18nConfig
 	openAPISpecEnabled             bool
 	openAPISpecPath                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
 }
 
 // New creates an Engine with the given options.
@@ -387,6 +391,13 @@ func (e *Engine) build() *gin.Engine {
 		r.GET("/debug/vars", expvar.Handler())
 	}
 
+	// SPA / fallback handler. Registered last so all explicit routes
+	// take precedence — Gin invokes NoRoute only when no other handler
+	// matched the request path + method.
+	if e.noRouteHandler != nil {
+		r.NoRoute(e.noRouteHandler)
+	}
+
 	return r
 }
 

go/codegen_test.go

@@ -267,73 +267,3 @@ func TestSDKGenerator_Generate_PackageNameAccepted_Good(t *testing.T) {
 	}
 }
 
-// TestSDKGenerator_Generate_PackageNameRejected_Bad verifies the regex-validation
-// hardening from Mantis #322 — PackageName containing flag-injection characters
-// is rejected before exec.CommandContext is reached.
-func TestSDKGenerator_Generate_PackageNameRejected_Bad(t *testing.T) {
-	tmp := t.TempDir()
-	specPath := filepath.Join(tmp, "spec.yaml")
-	if err := os.WriteFile(specPath, []byte("openapi: 3.0.0\n"), 0o644); err != nil {
-		t.Fatalf("write spec: %v", err)
-	}
-
-	rejects := []string{
-		"foo --extra=evil",  // space + flag injection
-		"foo;rm -rf /",      // command separator
-		"foo bar",           // bare space
-		"--shell-injection", // leading dash
-		"foo$(whoami)",      // command substitution
-	}
-	for _, name := range rejects {
-		t.Run(name, func(t *testing.T) {
-			gen := &api.SDKGenerator{
-				SpecPath:    specPath,
-				OutputDir:   tmp,
-				PackageName: name,
-			}
-			err := gen.Generate(context.Background(), "go")
-			if err == nil {
-				t.Errorf("expected rejection for PackageName=%q, got nil error", name)
-				return
-			}
-			if !strings.Contains(err.Error(), "package name") {
-				t.Errorf("expected rejection error containing 'package name', got %q", err.Error())
-			}
-		})
-	}
-}
-
-// TestSDKGenerator_Generate_PackageNameAccepted_Good verifies legitimate names
-// pass the regex; any subsequent error must NOT be the regex-rejection.
-func TestSDKGenerator_Generate_PackageNameAccepted_Good(t *testing.T) {
-	accepts := []string{
-		"foo",
-		"FooBar",
-		"foo_bar",
-		"foo-bar",
-		"Foo123",
-		"a",
-	}
-	tmp := t.TempDir()
-	specPath := filepath.Join(tmp, "spec.yaml")
-	if err := os.WriteFile(specPath, []byte("openapi: 3.0.0\n"), 0o644); err != nil {
-		t.Fatalf("write spec: %v", err)
-	}
-	for _, name := range accepts {
-		t.Run(name, func(t *testing.T) {
-			gen := &api.SDKGenerator{
-				SpecPath:    specPath,
-				OutputDir:   tmp,
-				PackageName: name,
-			}
-			err := gen.Generate(context.Background(), "go")
-			// Likely fails because openapi-generator-cli isn't installed in
-			// CI; the error MUST NOT be the regex-rejection ("package name
-			// X rejected").
-			if err != nil && strings.Contains(err.Error(), "package name") &&
-				strings.Contains(err.Error(), "rejected") {
-				t.Errorf("name %q was unexpectedly rejected by regex: %v", name, err)
-			}
-		})
-	}
-}

go/no_route_example_test.go

@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+package api_test
+
+import (
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+
+	api "dappco.re/go/api"
+	"github.com/gin-gonic/gin"
+)
+
+// ExampleWithNoRoute shows the canonical SPA-host pattern: every
+// request whose path doesn't match a registered route is served the
+// SPA's index.html, letting the client-side router take over.
+func ExampleWithNoRoute() {
+	gin.SetMode(gin.ReleaseMode)
+	e, _ := api.New(api.WithNoRoute(func(c *gin.Context) {
+		// Real SPA host calls c.File("dist/index.html"); the example
+		// writes a string so the test output stays deterministic.
+		c.String(http.StatusOK, "<!doctype html><html>SPA shell</html>")
+	}))
+
+	w := httptest.NewRecorder()
+	e.Handler().ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/anywhere/the/client/router/cares-about", nil))
+	fmt.Println(w.Code, w.Body.String())
+	// Output: 200 <!doctype html><html>SPA shell</html>
+}

go/no_route_test.go

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+package api
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// TestWithNoRoute_Good_FiresOnUnknownPath verifies the canonical SPA-host
+// path: a handler set via WithNoRoute catches a request whose path doesn't
+// match any registered route, and the response body is whatever the
+// handler writes (not gin's default 404 body).
+func TestWithNoRoute_Good_FiresOnUnknownPath(t *testing.T) {
+	const payload = "SPA-INDEX"
+
+	e, err := New(WithNoRoute(func(c *gin.Context) {
+		c.String(http.StatusOK, payload)
+	}))
+	if err != nil {
+		t.Fatalf("api.New: %v", err)
+	}
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/nonexistent/spa/route", nil)
+	e.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	if got := w.Body.String(); got != payload {
+		t.Fatalf("body = %q, want %q", got, payload)
+	}
+}
+
+// TestWithNoRoute_Bad_DoesNotShadowExplicitRoutes verifies the registration
+// order — an explicit route handler must win over the NoRoute fallback even
+// when both could plausibly serve the request.
+func TestWithNoRoute_Bad_DoesNotShadowExplicitRoutes(t *testing.T) {
+	e, err := New(WithNoRoute(func(c *gin.Context) {
+		c.String(http.StatusOK, "fallback")
+	}))
+	if err != nil {
+		t.Fatalf("api.New: %v", err)
+	}
+
+	// /health is always registered by build().
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/health", nil)
+	e.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("status = %d, want 200", w.Code)
+	}
+	if got := w.Body.String(); got == "fallback" {
+		t.Fatalf("NoRoute shadowed /health — body = %q", got)
+	}
+}
+
+// TestWithNoRoute_Ugly_NilStaysAsDefault404 verifies the degenerate path —
+// no NoRoute set means gin's default 404 surfaces unchanged. This protects
+// the contract that WithNoRoute is opt-in and unset Engines stay
+// compatible with the pre-WithNoRoute API.
+func TestWithNoRoute_Ugly_NilStaysAsDefault404(t *testing.T) {
+	e, err := New() // no WithNoRoute
+	if err != nil {
+		t.Fatalf("api.New: %v", err)
+	}
+
+	w := httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/nope", nil)
+	e.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("status = %d, want 404", w.Code)
+	}
+}

go/options.go

@@ -62,6 +62,26 @@ func WithHTTP3(addr string) Option {
 	}
 }
 
+// WithNoRoute sets a fallback handler invoked when no registered
+// route matches the incoming request. The typical use is an SPA host
+// rewriting unknown GETs to index.html, but any gin.HandlerFunc is
+// valid — pass nil to clear and let Gin return its default 404.
+//
+// Registration order: NoRoute is mounted after every explicit route +
+// group + middleware, so it never shadows real handlers. Method
+// mismatches still surface as 405 when HandleMethodNotAllowed is on.
+//
+// Example:
+//
+//	api.New(api.WithNoRoute(func(c *gin.Context) {
+//	    c.File("dist/index.html")
+//	}))
+func WithNoRoute(h gin.HandlerFunc) Option {
+	return func(e *Engine) {
+		e.noRouteHandler = h
+	}
+}
+
 // WithBearerAuth adds bearer token authentication middleware.
 // Requests to /health and the Swagger UI path are exempt.
 //