Dev

api.go

@@ -9,6 +9,7 @@ import (
 	"errors"
 	"iter"
 	"net/http"
+	"reflect"
 	"slices"
 	"time"
 
@@ -24,23 +25,57 @@ const defaultAddr = ":8080"
 const shutdownTimeout = 10 * time.Second
 
 // Engine is the central API server managing route groups and middleware.
+//
+// Example:
+//
+//	engine, err := api.New(api.WithAddr(":8081"))
+//	if err != nil {
+//		panic(err)
+//	}
+//	_ = engine.Handler()
 type Engine struct {
-	addr           string
-	groups         []RouteGroup
-	middlewares    []gin.HandlerFunc
-	wsHandler      http.Handler
-	sseBroker      *SSEBroker
-	swaggerEnabled bool
-	swaggerTitle   string
-	swaggerDesc    string
-	swaggerVersion string
-	pprofEnabled   bool
-	expvarEnabled  bool
-	graphql        *graphqlConfig
+	addr                           string
+	groups                         []RouteGroup
+	middlewares                    []gin.HandlerFunc
+	cacheTTL                       time.Duration
+	cacheMaxEntries                int
+	cacheMaxBytes                  int
+	wsHandler                      http.Handler
+	wsPath                         string
+	sseBroker                      *SSEBroker
+	swaggerEnabled                 bool
+	swaggerTitle                   string
+	swaggerSummary                 string
+	swaggerDesc                    string
+	swaggerVersion                 string
+	swaggerPath                    string
+	swaggerTermsOfService          string
+	swaggerServers                 []string
+	swaggerContactName             string
+	swaggerContactURL              string
+	swaggerContactEmail            string
+	swaggerLicenseName             string
+	swaggerLicenseURL              string
+	swaggerSecuritySchemes         map[string]any
+	swaggerExternalDocsDescription string
+	swaggerExternalDocsURL         string
+	authentikConfig                AuthentikConfig
+	pprofEnabled                   bool
+	expvarEnabled                  bool
+	ssePath                        string
+	graphql                        *graphqlConfig
+	i18nConfig                     I18nConfig
 }
 
 // New creates an Engine with the given options.
 // The default listen address is ":8080".
+//
+// Example:
+//
+//	engine, err := api.New(api.WithAddr(":8081"), api.WithResponseMeta())
+//	if err != nil {
+//		panic(err)
+//	}
 func New(opts ...Option) (*Engine, error) {
 	e := &Engine{
 		addr: defaultAddr,
@@ -52,27 +87,54 @@ func New(opts ...Option) (*Engine, error) {
 }
 
 // Addr returns the configured listen address.
+//
+// Example:
+//
+//	engine, _ := api.New(api.WithAddr(":9090"))
+//	addr := engine.Addr()
 func (e *Engine) Addr() string {
 	return e.addr
 }
 
-// Groups returns all registered route groups.
+// Groups returns a copy of all registered route groups.
+//
+// Example:
+//
+//	groups := engine.Groups()
 func (e *Engine) Groups() []RouteGroup {
-	return e.groups
+	return slices.Clone(e.groups)
 }
 
 // GroupsIter returns an iterator over all registered route groups.
+//
+// Example:
+//
+//	for group := range engine.GroupsIter() {
+//		_ = group
+//	}
 func (e *Engine) GroupsIter() iter.Seq[RouteGroup] {
-	return slices.Values(e.groups)
+	groups := slices.Clone(e.groups)
+	return slices.Values(groups)
 }
 
 // Register adds a route group to the engine.
+//
+// Example:
+//
+//	engine.Register(myGroup)
 func (e *Engine) Register(group RouteGroup) {
+	if isNilRouteGroup(group) {
+		return
+	}
 	e.groups = append(e.groups, group)
 }
 
 // Channels returns all WebSocket channel names from registered StreamGroups.
 // Groups that do not implement StreamGroup are silently skipped.
+//
+// Example:
+//
+//	channels := engine.Channels()
 func (e *Engine) Channels() []string {
 	var channels []string
 	for _, g := range e.groups {
@@ -84,9 +146,16 @@ func (e *Engine) Channels() []string {
 }
 
 // ChannelsIter returns an iterator over WebSocket channel names from registered StreamGroups.
+//
+// Example:
+//
+//	for channel := range engine.ChannelsIter() {
+//		_ = channel
+//	}
 func (e *Engine) ChannelsIter() iter.Seq[string] {
+	groups := slices.Clone(e.groups)
 	return func(yield func(string) bool) {
-		for _, g := range e.groups {
+		for _, g := range groups {
 			if sg, ok := g.(StreamGroup); ok {
 				for _, c := range sg.Channels() {
 					if !yield(c) {
@@ -100,12 +169,22 @@ func (e *Engine) ChannelsIter() iter.Seq[string] {
 
 // Handler builds the Gin engine and returns it as an http.Handler.
 // Each call produces a fresh handler reflecting the current set of groups.
+//
+// Example:
+//
+//	handler := engine.Handler()
 func (e *Engine) Handler() http.Handler {
 	return e.build()
 }
 
 // Serve starts the HTTP server and blocks until the context is cancelled,
 // then performs a graceful shutdown allowing in-flight requests to complete.
+//
+// Example:
+//
+//	ctx, cancel := context.WithCancel(context.Background())
+//	defer cancel()
+//	_ = engine.Serve(ctx)
 func (e *Engine) Serve(ctx context.Context) error {
 	srv := &http.Server{
 		Addr:    e.addr,
@@ -120,8 +199,18 @@ func (e *Engine) Serve(ctx context.Context) error {
 		close(errCh)
 	}()
 
-	// Block until context is cancelled.
-	<-ctx.Done()
+	// Return immediately if the listener fails before shutdown is requested.
+	select {
+	case err := <-errCh:
+		return err
+	case <-ctx.Done():
+	}
+
+	// Signal SSE clients first so their handlers can exit cleanly before the
+	// HTTP server begins its own shutdown sequence.
+	if e.sseBroker != nil {
+		e.sseBroker.Drain()
+	}
 
 	// Graceful shutdown with timeout.
 	shutdownCtx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
@@ -139,7 +228,7 @@ func (e *Engine) Serve(ctx context.Context) error {
 // user-supplied middleware, the health endpoint, and all registered route groups.
 func (e *Engine) build() *gin.Engine {
 	r := gin.New()
-	r.Use(gin.Recovery())
+	r.Use(recoveryMiddleware())
 
 	// Apply user-supplied middleware after recovery but before routes.
 	for _, mw := range e.middlewares {
@@ -153,18 +242,21 @@ func (e *Engine) build() *gin.Engine {
 
 	// Mount each registered group at its base path.
 	for _, g := range e.groups {
+		if isNilRouteGroup(g) {
+			continue
+		}
 		rg := r.Group(g.BasePath())
 		g.RegisterRoutes(rg)
 	}
 
 	// Mount WebSocket handler if configured.
 	if e.wsHandler != nil {
-		r.GET("/ws", wrapWSHandler(e.wsHandler))
+		r.GET(resolveWSPath(e.wsPath), wrapWSHandler(e.wsHandler))
 	}
 
 	// Mount SSE endpoint if configured.
 	if e.sseBroker != nil {
-		r.GET("/events", e.sseBroker.Handler())
+		r.GET(resolveSSEPath(e.ssePath), e.sseBroker.Handler())
 	}
 
 	// Mount GraphQL endpoint if configured.
@@ -174,7 +266,7 @@ func (e *Engine) build() *gin.Engine {
 
 	// Mount Swagger UI if enabled.
 	if e.swaggerEnabled {
-		registerSwagger(r, e.swaggerTitle, e.swaggerDesc, e.swaggerVersion, e.groups)
+		registerSwagger(r, e, e.groups)
 	}
 
 	// Mount pprof profiling endpoints if enabled.
@@ -189,3 +281,17 @@ func (e *Engine) build() *gin.Engine {
 
 	return r
 }
+
+func isNilRouteGroup(group RouteGroup) bool {
+	if group == nil {
+		return true
+	}
+
+	value := reflect.ValueOf(group)
+	switch value.Kind() {
+	case reflect.Chan, reflect.Func, reflect.Interface, reflect.Map, reflect.Pointer, reflect.Slice:
+		return value.IsNil()
+	default:
+		return false
+	}
+}

api_test.go

@@ -29,6 +29,16 @@ func (h *healthGroup) RegisterRoutes(rg *gin.RouterGroup) {
 	})
 }
 
+type panicGroup struct{}
+
+func (p *panicGroup) Name() string     { return "panic" }
+func (p *panicGroup) BasePath() string { return "/panic" }
+func (p *panicGroup) RegisterRoutes(rg *gin.RouterGroup) {
+	rg.GET("/boom", func(c *gin.Context) {
+		panic("boom")
+	})
+}
+
 // ── New ─────────────────────────────────────────────────────────────────
 
 func TestNew_Good(t *testing.T) {
@@ -85,6 +95,28 @@ func TestRegister_Good_MultipleGroups(t *testing.T) {
 	}
 }
 
+func TestRegister_Good_GroupsReturnsCopy(t *testing.T) {
+	e, _ := api.New()
+	first := &healthGroup{}
+	second := &stubGroup{}
+	e.Register(first)
+	e.Register(second)
+
+	groups := e.Groups()
+	groups[0] = nil
+
+	fresh := e.Groups()
+	if fresh[0] == nil {
+		t.Fatal("expected Groups to return a copy, but engine state was mutated")
+	}
+	if fresh[0].Name() != first.Name() {
+		t.Fatalf("expected first group name %q, got %q", first.Name(), fresh[0].Name())
+	}
+	if fresh[1].Name() != "stub" {
+		t.Fatalf("expected second group name %q, got %q", "stub", fresh[1].Name())
+	}
+}
+
 // ── Handler ─────────────────────────────────────────────────────────────
 
 func TestHandler_Good_HealthEndpoint(t *testing.T) {
@@ -149,6 +181,41 @@ func TestHandler_Bad_NotFound(t *testing.T) {
 	}
 }
 
+func TestHandler_Bad_PanicReturnsEnvelope(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+	e, _ := api.New(api.WithRequestID())
+	e.Register(&panicGroup{})
+
+	h := e.Handler()
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest(http.MethodGet, "/panic/boom", nil)
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusInternalServerError {
+		t.Fatalf("expected 500, got %d", w.Code)
+	}
+
+	var resp api.Response[any]
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("unmarshal error: %v", err)
+	}
+	if resp.Success {
+		t.Fatal("expected Success=false")
+	}
+	if resp.Error == nil {
+		t.Fatal("expected Error to be non-nil")
+	}
+	if resp.Error.Code != "internal_server_error" {
+		t.Fatalf("expected error code=%q, got %q", "internal_server_error", resp.Error.Code)
+	}
+	if resp.Error.Message != "Internal server error" {
+		t.Fatalf("expected error message=%q, got %q", "Internal server error", resp.Error.Message)
+	}
+	if got := w.Header().Get("X-Request-ID"); got == "" {
+		t.Fatal("expected X-Request-ID header to survive panic recovery")
+	}
+}
+
 // ── Serve + graceful shutdown ───────────────────────────────────────────
 
 func TestServe_Good_GracefulShutdown(t *testing.T) {
@@ -202,3 +269,32 @@ func TestServe_Good_GracefulShutdown(t *testing.T) {
 		t.Fatal("Serve did not return within 5 seconds after context cancellation")
 	}
 }
+
+func TestServe_Bad_ReturnsListenErrorBeforeCancel(t *testing.T) {
+	ln, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("failed to reserve port: %v", err)
+	}
+	addr := ln.Addr().String()
+	defer ln.Close()
+
+	e, _ := api.New(api.WithAddr(addr))
+
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	errCh := make(chan error, 1)
+	go func() {
+		errCh <- e.Serve(ctx)
+	}()
+
+	select {
+	case serveErr := <-errCh:
+		if serveErr == nil {
+			t.Fatal("expected Serve to return a listen error, got nil")
+		}
+	case <-time.After(2 * time.Second):
+		cancel()
+		t.Fatal("Serve did not return promptly after listener failure")
+	}
+}