cleaner implementation and ensure autofree works as intended

Author: olekukonko

.github/workflows/go.yml

@@ -1,6 +1,3 @@
-# This workflow will build a golang project
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
-
 name: Go
 
 on:
@@ -10,20 +7,28 @@ on:
     branches: [ "main" ]
 
 jobs:
-
-  build:
+  test:
+    name: Test (Go ${{ matrix.go-version }})
     runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        go-version:
+          - '1.21'   # Represents the pool_below_1_24 path (SetFinalizer)
+          - '1.24'   # Represents the pool_above_1_24 path (AddCleanup)
+
     steps:
-    - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-    - name: Set up Go
-      uses: actions/setup-go@v4
-      with:
-        go-version: '1.21'
-        cache: false
+      - name: Set up Go ${{ matrix.go-version }}
+        uses: actions/setup-go@v4
+        with:
+          go-version: ${{ matrix.go-version }}
+          cache: false
 
-    - name: Build
-      run: go build -v ./...
+      - name: Build
+        run: go build -v ./...
 
-    - name: Test
-      run: go test -v ./...
+      - name: Test (race + cover)
+        run: go test -count=1 -race -timeout 120s -cover -v ./...

base.go

@@ -0,0 +1,178 @@
+package errors
+
+import (
+	"bytes"
+	"fmt"
+	"regexp"
+	"sync"
+)
+
+// Constants defining default configuration and context keys.
+const (
+	ctxTimeout = "[error] timeout" // Context key marking timeout errors.
+	ctxRetry   = "[error] retry"   // Context key marking retryable errors.
+
+	contextSize = 4   // Initial size of fixed-size context array for small contexts.
+	bufferSize  = 256 // Initial buffer size for JSON marshaling.
+	warmUpSize  = 100 // Number of errors to pre-warm the pool for efficiency.
+	stackDepth  = 32  // Maximum stack trace depth to prevent excessive memory use.
+
+	DefaultCode = 500 // Default HTTP status code for errors if not specified.
+)
+
+// spaceRe is a precompiled regex for normalizing whitespace in error messages.
+var spaceRe = regexp.MustCompile(`\s+`)
+
+// jsonBufferPool manages reusable buffers for JSON marshaling to reduce allocations.
+var (
+	jsonBufferPool = sync.Pool{
+		New: func() interface{} {
+			return bytes.NewBuffer(make([]byte, 0, bufferSize))
+		},
+	}
+)
+
+// ErrorCategory is a string type for categorizing errors (e.g., "network", "validation").
+type ErrorCategory string
+
+// ErrorOpts provides options for customizing error creation.
+type ErrorOpts struct {
+	SkipStack int // Number of stack frames to skip when capturing the stack trace.
+}
+
+// Config defines the global configuration for the errors package, controlling
+// stack depth, context size, pooling, and frame filtering.
+type Config struct {
+	StackDepth     int  // Maximum stack trace depth; 0 uses default (32).
+	ContextSize    int  // Initial context map size; 0 uses default (4).
+	DisablePooling bool // If true, disables object pooling for errors.
+	FilterInternal bool // If true, filters internal package frames from stack traces.
+	AutoFree       bool // If true, automatically returns errors to pool when GC collects them.
+}
+
+// cachedConfig holds the current configuration, updated only by Configure().
+// Protected by configMu for thread-safety.
+type cachedConfig struct {
+	stackDepth     int
+	contextSize    int
+	disablePooling bool
+	filterInternal bool
+	autoFree       bool
+}
+
+var (
+	// currentConfig stores the active configuration, read frequently and updated rarely.
+	currentConfig cachedConfig
+	// configMu protects updates to currentConfig for thread-safety.
+	configMu sync.RWMutex
+	// errorPool manages reusable Error instances to reduce allocations.
+	errorPool = NewErrorPool()
+	// stackPool manages reusable stack trace slices for efficiency.
+	stackPool = sync.Pool{
+		New: func() interface{} {
+			return make([]uintptr, currentConfig.stackDepth)
+		},
+	}
+	// emptyError is a pre-allocated empty error for lightweight reuse.
+	emptyError = &Error{
+		smallContext: [contextSize]contextItem{},
+		msg:          "",
+		name:         "",
+		template:     "",
+		cause:        nil,
+	}
+)
+
+// contextItem holds a single key-value pair in the smallContext array.
+type contextItem struct {
+	key   string
+	value interface{}
+}
+
+// init sets up the package with default configuration and pre-warms the error pool.
+func init() {
+	currentConfig = cachedConfig{
+		stackDepth:     stackDepth,
+		contextSize:    contextSize,
+		disablePooling: false,
+		filterInternal: true,
+		autoFree:       false, // opt-in; explicit Free() is the safe default
+	}
+	WarmPool(warmUpSize) // Pre-allocate errors for performance.
+}
+
+// Configure updates the global configuration for the errors package.
+// It is thread-safe and should be called early to avoid race conditions.
+// Changes apply to all subsequent error operations.
+// Example:
+//
+//	errors.Configure(errors.Config{StackDepth: 16, DisablePooling: true})
+func Configure(cfg Config) {
+	configMu.Lock()
+	defer configMu.Unlock()
+
+	if cfg.StackDepth != 0 {
+		currentConfig.stackDepth = cfg.StackDepth
+	}
+	if cfg.ContextSize != 0 {
+		currentConfig.contextSize = cfg.ContextSize
+	}
+	currentConfig.disablePooling = cfg.DisablePooling
+	currentConfig.filterInternal = cfg.FilterInternal
+	currentConfig.autoFree = cfg.AutoFree
+}
+
+// WarmPool pre-populates the error pool with count instances.
+// Improves performance by reducing initial allocations.
+// No-op if pooling is disabled.
+// Example:
+//
+//	errors.WarmPool(1000)
+func WarmPool(count int) {
+	if currentConfig.disablePooling {
+		return
+	}
+	for i := 0; i < count; i++ {
+		e := &Error{
+			smallContext: [contextSize]contextItem{},
+			stack:        nil,
+		}
+		errorPool.Put(e)
+		stackPool.Put(make([]uintptr, 0, currentConfig.stackDepth))
+	}
+}
+
+// WarmStackPool pre-populates the stack pool with count slices.
+// Improves performance for stack-intensive operations.
+// No-op if pooling is disabled.
+// Example:
+//
+//	errors.WarmStackPool(500)
+func WarmStackPool(count int) {
+	if currentConfig.disablePooling {
+		return
+	}
+	for i := 0; i < count; i++ {
+		stackPool.Put(make([]uintptr, 0, currentConfig.stackDepth))
+	}
+}
+
+// FmtErrorCheck safely formats a string using fmt.Sprintf, catching panics.
+// Returns the formatted string and any error encountered.
+// Internal use by Newf to validate format strings.
+// Example:
+//
+//	result, err := FmtErrorCheck("value: %s", "test")
+func FmtErrorCheck(format string, args ...interface{}) (result string, err error) {
+	defer func() {
+		if r := recover(); r != nil {
+			if e, ok := r.(error); ok {
+				err = e
+			} else {
+				err = fmt.Errorf("panic during formatting: %v", r)
+			}
+		}
+	}()
+	result = fmt.Sprintf(format, args...)
+	return result, nil
+}

chain.go

@@ -6,6 +6,7 @@ import (
 	"log/slog" // Standard structured logging package
 	"reflect"
 	"strings"
+	"sync"
 	"time"
 )
 
@@ -18,6 +19,8 @@ type Chain struct {
 	lastStep   *chainStep         // Pointer to the last added step for configuration
 	logHandler slog.Handler       // Optional logging handler (nil means no logging)
 	cancel     context.CancelFunc // Function to cancel the context
+	runCtx     context.Context    // Active context for Run/RunAll; shared with StepCtx closures
+	configMu   sync.RWMutex       // Protects chainConfig against concurrent Timeout() calls
 }
 
 // chainStep represents a single step in the chain.
@@ -136,9 +139,14 @@ func (c *Chain) StepCtx(fn func(ctx context.Context) error) *Chain {
 	}
 	// Wrap fn so it satisfies the internal func() error signature used by
 	// executeStep. The context is captured at execution time via getContextAndCancel.
+	// Close over c.runCtx — set by Run/RunAll to the chain-level context.
+	// This ensures StepCtx steps share the same deadline as the chain,
+	// rather than each getting a fresh full-duration context.
 	wrapped := func() error {
-		ctx, cancel := c.getContextAndCancel()
-		defer cancel()
+		ctx := c.runCtx
+		if ctx == nil {
+			ctx = context.Background()
+		}
 		return fn(ctx)
 	}
 	step := chainStep{execute: wrapped, config: stepConfig{}}
@@ -186,8 +194,11 @@ func (c *Chain) WithLog(attrs ...slog.Attr) *Chain {
 }
 
 // Timeout sets a timeout for the entire chain.
+// Thread-safe: protected by configMu.
 func (c *Chain) Timeout(d time.Duration) *Chain {
+	c.configMu.Lock()
 	c.config.timeout = d
+	c.configMu.Unlock()
 	return c
 }
 
@@ -293,6 +304,7 @@ func (c *Chain) Run() error {
 	ctx, cancel := c.getContextAndCancel()
 	defer cancel()
 	c.cancel = cancel
+	c.runCtx = ctx // share deadline with StepCtx closures
 	// Clear any previous errors
 	c.errors = c.errors[:0]
 
@@ -342,6 +354,7 @@ func (c *Chain) RunAll() error {
 	ctx, cancel := c.getContextAndCancel()
 	defer cancel()
 	c.cancel = cancel
+	c.runCtx = ctx // share deadline with StepCtx closures
 	c.errors = c.errors[:0]
 	multi := NewMultiError()
 
@@ -437,11 +450,12 @@ func (c *Chain) Unwrap() []error {
 // It returns a context and its cancellation function.
 func (c *Chain) getContextAndCancel() (context.Context, context.CancelFunc) {
 	parentCtx := context.Background()
-	if c.config.timeout > 0 {
-		// Create a context with a timeout
-		return context.WithTimeout(parentCtx, c.config.timeout)
+	c.configMu.RLock()
+	timeout := c.config.timeout
+	c.configMu.RUnlock()
+	if timeout > 0 {
+		return context.WithTimeout(parentCtx, timeout)
 	}
-	// Create a cancellable context
 	return context.WithCancel(parentCtx)
 }