Merge branch 'main' into dependabot/github_actions/actions/create-github-app-token-2.2.1

Author: pitabwire

.github/workflows/changelog.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v6.0.1
 
       - name: Run Changelog CI
         uses: saadmk11/changelog-ci@v1.2.0

.github/workflows/gemini-cli.yml

@@ -126,7 +126,7 @@ jobs:
       - name: 'Checkout PR branch'
         if: |-
           ${{  steps.get_context.outputs.is_pr == 'true' }}
-        uses: 'actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd' # v5
+        uses: 'actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8' # v5
         with:
           token: '${{ steps.generate_token.outputs.token || secrets.GITHUB_TOKEN }}'
           repository: '${{ github.repository }}'
@@ -136,7 +136,7 @@ jobs:
       - name: 'Checkout main branch'
         if: |-
           ${{  steps.get_context.outputs.is_pr == 'false' }}
-        uses: 'actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd' # v5
+        uses: 'actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8' # v5
         with:
           token: '${{ steps.generate_token.outputs.token || secrets.GITHUB_TOKEN }}'
           repository: '${{ github.repository }}'

.github/workflows/gemini-pr-review.yml

@@ -76,7 +76,7 @@ jobs:
     runs-on: 'ubuntu-latest'
     steps:
       - name: 'Checkout PR code'
-        uses: 'actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd' # v5
+        uses: 'actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8' # v5
 
       - name: 'Generate GitHub App Token'
         id: 'generate_token'

.github/workflows/golangci-lint.yml

@@ -12,7 +12,7 @@ jobs:
     name: lint
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v6.0.1
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v9
         with:

.github/workflows/run_tests.yml

@@ -8,7 +8,7 @@ jobs:
 
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v6.0.1
       - uses: actions/setup-go@v6
         with:
           go-version: 'stable'

config/config.go

@@ -88,6 +88,9 @@ type ConfigurationDefault struct {
 	TraceRequests        bool `envDefault:"false" env:"TRACE_REQUESTS"          yaml:"trace_requests"`
 	TraceRequestsLogBody bool `envDefault:"false" env:"TRACE_REQUESTS_LOG_BODY" yaml:"trace_requests_log_body"`
 
+	ProfilerEnable   bool   `envDefault:"false" env:"PROFILER_ENABLE" yaml:"profiler_enable"`
+	ProfilerPortAddr string `envDefault:":6060" env:"PROFILER_PORT"   yaml:"profiler_port"`
+
 	OpenTelemetryDisable    bool    `envDefault:"false" env:"OPENTELEMETRY_DISABLE"        yaml:"opentelemetry_disable"`
 	OpenTelemetryTraceRatio float64 `envDefault:"1"     env:"OPENTELEMETRY_TRACE_ID_RATIO" yaml:"opentelemetry_trace_id_ratio"`
 
@@ -221,6 +224,24 @@ func (c *ConfigurationDefault) TraceReqLogBody() bool {
 	return c.TraceRequestsLogBody
 }
 
+type ConfigurationProfiler interface {
+	ProfilerEnabled() bool
+	ProfilerPort() string
+}
+
+var _ ConfigurationProfiler = new(ConfigurationDefault)
+
+func (c *ConfigurationDefault) ProfilerEnabled() bool {
+	return c.ProfilerEnable
+}
+
+func (c *ConfigurationDefault) ProfilerPort() string {
+	if c.ProfilerPortAddr != "" {
+		return c.ProfilerPortAddr
+	}
+	return ":6060"
+}
+
 type ConfigurationPorts interface {
 	Port() string
 	HTTPPort() string

profiler/README.md

@@ -0,0 +1,139 @@
+# Profiler Package
+
+The profiler package provides a clean interface for managing Go's pprof server within the frame framework.
+
+## Features
+
+- Automatic pprof server lifecycle management
+- Configuration-based enable/disable
+- Configurable port binding
+- Graceful shutdown support
+- Thread-safe operations
+
+## Usage
+
+### Basic Usage
+
+```go
+import (
+    "context"
+    "github.com/pitabwire/frame/profiler"
+    "github.com/pitabwire/frame/config"
+)
+
+func main() {
+    cfg := &config.ConfigurationDefault{
+        ProfilerEnable:   true,
+        ProfilerPortAddr: ":6060",
+    }
+    
+    server := profiler.NewServer()
+    ctx := context.Background()
+    
+    // Start the profiler if enabled
+    err := server.StartIfEnabled(ctx, cfg)
+    if err != nil {
+        panic(err)
+    }
+    
+    // ... your application logic ...
+    
+    // Gracefully stop the profiler
+    err = server.Stop(ctx)
+    if err != nil {
+        panic(err)
+    }
+}
+```
+
+### Integration with Frame Service
+
+The profiler package is automatically integrated into the frame service when using the default configuration:
+
+```go
+import "github.com/pitabwire/frame"
+
+func main() {
+    // Set PROFILER_ENABLE=true environment variable
+    ctx, svc := frame.NewService()
+    
+    // Profiler will automatically start on :6060
+    err := svc.Run(ctx, "")
+    if err != nil {
+        panic(err)
+    }
+}
+```
+
+## Configuration
+
+The profiler responds to the following configuration options:
+
+### Environment Variables
+
+- `PROFILER_ENABLE`: Set to "true" to enable the profiler (default: false)
+- `PROFILER_PORT`: Port to bind the profiler server (default: ":6060")
+
+### YAML Configuration
+
+```yaml
+profiler_enable: true
+profiler_port: ":6061"
+```
+
+## Available Endpoints
+
+When the profiler is enabled, the following endpoints are available:
+
+- `/debug/pprof/` - Index of all available profiles
+- `/debug/pprof/profile` - CPU profile (30 seconds by default)
+- `/debug/pprof/heap` - Heap profile
+- `/debug/pprof/goroutine` - Goroutine profile
+- `/debug/pprof/block` - Blocking profile
+- `/debug/pprof/mutex` - Mutex contention profile
+- `/debug/pprof/trace` - Execution trace
+
+## Command Line Tools
+
+### CPU Profiling
+```bash
+# Collect 30-second CPU profile
+go tool pprof http://localhost:6060/debug/pprof/profile
+
+# Collect 10-second CPU profile
+go tool pprof http://localhost:6060/debug/pprof/profile?seconds=10
+```
+
+### Heap Profiling
+```bash
+go tool pprof http://localhost:6060/debug/pprof/heap
+```
+
+### Web Interface
+```bash
+go tool pprof -http=:8080 http://localhost:6060/debug/pprof/profile
+```
+
+## API Reference
+
+### Server
+
+The main type for managing the pprof server.
+
+#### Methods
+
+- `NewServer() *Server` - Creates a new profiler server instance
+- `StartIfEnabled(ctx context.Context, cfg config.ConfigurationProfiler) error` - Starts the profiler if enabled in configuration
+- `Stop(ctx context.Context) error` - Gracefully stops the profiler server
+- `IsRunning() bool` - Returns true if the profiler server is currently running
+
+## Security Considerations
+
+- The profiler should only be enabled in development/staging environments
+- Consider firewall rules to restrict access to profiler endpoints
+- The profiler exposes sensitive information about your application's internals
+- Always disable the profiler in production environments
+
+## Thread Safety
+
+All methods on the Server type are thread-safe and can be called concurrently from multiple goroutines.

profiler/server.go

@@ -0,0 +1,84 @@
+package profiler
+
+import (
+	"context"
+	"errors"
+	"net/http"
+	_ "net/http/pprof" //nolint:gosec // This is a controlled profiling endpoint
+	"time"
+
+	"github.com/pitabwire/util"
+
+	"github.com/pitabwire/frame/config"
+)
+
+const (
+	// DefaultShutdownTimeout is the timeout for graceful shutdown of the pprof server.
+	DefaultShutdownTimeout = 5 * time.Second
+	// DefaultReadHeaderTimeout is the timeout for reading request headers to prevent Slowloris attacks.
+	DefaultReadHeaderTimeout = 5 * time.Second
+)
+
+// Server manages the pprof server lifecycle.
+type Server struct {
+	server *http.Server
+}
+
+// NewServer creates a new profiler server instance.
+func NewServer() *Server {
+	return &Server{}
+}
+
+// StartIfEnabled checks if profiler is enabled and starts the pprof server.
+func (s *Server) StartIfEnabled(ctx context.Context, cfg config.ConfigurationProfiler) error {
+	if !cfg.ProfilerEnabled() {
+		// Profiler is explicitly disabled
+		return nil
+	}
+
+	log := util.Log(ctx)
+	profilerPort := cfg.ProfilerPort()
+	log.WithField("port", profilerPort).Info("Starting pprof server")
+
+	// Create pprof server
+	s.server = &http.Server{
+		Addr:              profilerPort,
+		Handler:           nil, // Use default handler which includes pprof endpoints
+		ReadHeaderTimeout: DefaultReadHeaderTimeout,
+	}
+
+	// Start pprof server in a goroutine
+	go func() {
+		if err := s.server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			log.WithError(err).Error("pprof server failed")
+		}
+	}()
+
+	return nil
+}
+
+// Stop gracefully shuts down the pprof server.
+func (s *Server) Stop(ctx context.Context) error {
+	if s.server == nil {
+		return nil
+	}
+
+	log := util.Log(ctx)
+	log.Info("stopping pprof server")
+
+	shutdownCtx, cancel := context.WithTimeout(ctx, DefaultShutdownTimeout)
+	defer cancel()
+
+	if err := s.server.Shutdown(shutdownCtx); err != nil {
+		log.WithError(err).Error("failed to shutdown pprof server")
+		return err
+	}
+
+	s.server = nil
+	return nil
+}
+
+// IsRunning returns true if the profiler server is currently running.
+func (s *Server) IsRunning() bool {
+	return s.server != nil
+}