feat: add WithPprof runtime profiling endpoints

Registers Go pprof handlers at /debug/pprof/ via gin-contrib/pprof
when the WithPprof() option is enabled. Uses the same flag-in-build()
pattern as WithSwagger() — routes are only mounted when explicitly
opted in.

Co-Authored-By: Virgil <virgil@lethean.io>

api.go

@@ -10,6 +10,7 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/gin-contrib/pprof"
 	"github.com/gin-gonic/gin"
 )
 
@@ -30,6 +31,7 @@ type Engine struct {
 	swaggerTitle   string
 	swaggerDesc    string
 	swaggerVersion string
+	pprofEnabled   bool
 	graphql        *graphqlConfig
 }
 
@@ -151,5 +153,10 @@ func (e *Engine) build() *gin.Engine {
 		registerSwagger(r, e.swaggerTitle, e.swaggerDesc, e.swaggerVersion)
 	}
 
+	// Mount pprof profiling endpoints if enabled.
+	if e.pprofEnabled {
+		pprof.Register(r)
+	}
+
 	return r
 }

go.mod

@@ -12,6 +12,7 @@ require (
 	github.com/gin-contrib/gzip v1.2.5
 	github.com/gin-contrib/httpsign v1.0.3
 	github.com/gin-contrib/location/v2 v2.0.0
+	github.com/gin-contrib/pprof v1.5.3
 	github.com/gin-contrib/secure v1.1.2
 	github.com/gin-contrib/sessions v1.0.4
 	github.com/gin-contrib/slog v1.2.0

go.sum

@@ -54,6 +54,8 @@ github.com/gin-contrib/httpsign v1.0.3 h1:NpeDQjmUV0qFjGCm/rkXSp3HH0hU7r84q1v+Vt
 github.com/gin-contrib/httpsign v1.0.3/go.mod h1:n4GC7StmHNBhIzWzuW2njKbZMeEWh4tDbmn3bD1ab+k=
 github.com/gin-contrib/location/v2 v2.0.0 h1:iLx5RatHQHSxgC0tm2AG0sIuQKecI7FhREessVd6RWY=
 github.com/gin-contrib/location/v2 v2.0.0/go.mod h1:276TDNr25NENBA/NQZUuEIlwxy/I5CYVFIr/d2TgOdU=
+github.com/gin-contrib/pprof v1.5.3 h1:Bj5SxJ3kQDVez/s/+f9+meedJIqLS+xlkIVDe/lcvgM=
+github.com/gin-contrib/pprof v1.5.3/go.mod h1:0+LQSZ4SLO0B6+2n6JBzaEygpTBxe/nI+YEYpfQQ6xY=
 github.com/gin-contrib/secure v1.1.2 h1:6G8/NCOTSywWY7TeaH/0Yfaa6bfkE5ukkqtIm7lK11U=
 github.com/gin-contrib/secure v1.1.2/go.mod h1:xI3jI5/BpOYMCBtjgmIVrMA3kI7y9LwCFxs+eLf5S3w=
 github.com/gin-contrib/sessions v1.0.4 h1:ha6CNdpYiTOK/hTp05miJLbpTSNfOnFg5Jm2kbcqy8U=

options.go

@@ -121,6 +121,19 @@ func WithSwagger(title, description, version string) Option {
 	}
 }
 
+// WithPprof enables Go runtime profiling endpoints at /debug/pprof/.
+// The standard pprof handlers (index, cmdline, profile, symbol, trace,
+// allocs, block, goroutine, heap, mutex, threadcreate) are registered
+// via gin-contrib/pprof.
+//
+// WARNING: pprof exposes sensitive runtime data and should only be
+// enabled in development or behind authentication in production.
+func WithPprof() Option {
+	return func(e *Engine) {
+		e.pprofEnabled = true
+	}
+}
+
 // WithSecure adds security headers middleware via gin-contrib/secure.
 // Default policy sets HSTS (1 year, includeSubDomains), X-Frame-Options DENY,
 // X-Content-Type-Options nosniff, and Referrer-Policy strict-origin-when-cross-origin.

pprof_test.go

@@ -0,0 +1,124 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+package api_test
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+
+	api "forge.lthn.ai/core/go-api"
+)
+
+// ── Pprof profiling endpoints ─────────────────────────────────────────
+
+func TestWithPprof_Good_IndexAccessible(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	e, err := api.New(api.WithPprof())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	srv := httptest.NewServer(e.Handler())
+	defer srv.Close()
+
+	resp, err := http.Get(srv.URL + "/debug/pprof/")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 for /debug/pprof/, got %d", resp.StatusCode)
+	}
+}
+
+func TestWithPprof_Good_ProfileEndpointExists(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	e, err := api.New(api.WithPprof())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	srv := httptest.NewServer(e.Handler())
+	defer srv.Close()
+
+	resp, err := http.Get(srv.URL + "/debug/pprof/heap")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 for /debug/pprof/heap, got %d", resp.StatusCode)
+	}
+}
+
+func TestWithPprof_Good_CombinesWithOtherMiddleware(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	e, err := api.New(api.WithRequestID(), api.WithPprof())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	srv := httptest.NewServer(e.Handler())
+	defer srv.Close()
+
+	resp, err := http.Get(srv.URL + "/debug/pprof/")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 for /debug/pprof/ with middleware, got %d", resp.StatusCode)
+	}
+
+	// Verify the request ID middleware is still active.
+	rid := resp.Header.Get("X-Request-ID")
+	if rid == "" {
+		t.Fatal("expected X-Request-ID header from WithRequestID middleware")
+	}
+}
+
+func TestWithPprof_Bad_NotMountedWithoutOption(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	e, _ := api.New()
+
+	h := e.Handler()
+	w := httptest.NewRecorder()
+	req, _ := http.NewRequest(http.MethodGet, "/debug/pprof/", nil)
+	h.ServeHTTP(w, req)
+
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("expected 404 for /debug/pprof/ without WithPprof, got %d", w.Code)
+	}
+}
+
+func TestWithPprof_Good_CmdlineEndpointExists(t *testing.T) {
+	gin.SetMode(gin.TestMode)
+
+	e, err := api.New(api.WithPprof())
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+
+	srv := httptest.NewServer(e.Handler())
+	defer srv.Close()
+
+	resp, err := http.Get(srv.URL + "/debug/pprof/cmdline")
+	if err != nil {
+		t.Fatalf("request failed: %v", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("expected 200 for /debug/pprof/cmdline, got %d", resp.StatusCode)
+	}
+}