feat(ctx): add conditional copy helpers (#3703)

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: ReneWerner87

app.go

@@ -24,8 +24,9 @@ import (
 	"strings"
 	"sync"
 	"time"
+	"unsafe"
 
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 	"github.com/valyala/fasthttp"
 
 	"github.com/gofiber/fiber/v3/binder"
@@ -74,9 +75,9 @@ type App struct {
 	// Fasthttp server
 	server *fasthttp.Server
 	// Converts string to a byte slice
-	getBytes func(s string) (b []byte)
+	toBytes func(s string) (b []byte)
 	// Converts byte slice to a string
-	getString func(b []byte) string
+	toString func(b []byte) string
 	// Hooks
 	hooks *Hooks
 	// Latest route & group
@@ -516,8 +517,8 @@ func New(config ...Config) *App {
 	app := &App{
 		// Create config
 		config:        Config{},
-		getBytes:      utils.UnsafeBytes,
-		getString:     utils.UnsafeString,
+		toBytes:       utils.UnsafeBytes,
+		toString:      utils.UnsafeString,
 		latestRoute:   &Route{},
 		customBinders: []CustomBinder{},
 		sendfiles:     []*sendFileStore{},
@@ -572,7 +573,7 @@ func New(config ...Config) *App {
 	}
 
 	if app.config.Immutable {
-		app.getBytes, app.getString = getBytesImmutable, getStringImmutable
+		app.toBytes, app.toString = toBytesImmutable, toStringImmutable
 	}
 
 	if app.config.ErrorHandler == nil {
@@ -635,6 +636,30 @@ func NewWithCustomCtx(newCtxFunc func(app *App) CustomCtx, config ...Config) *Ap
 	return app
 }
 
+// GetString returns s unchanged when Immutable is off or s is read-only (rodata).
+// Otherwise it returns a detached copy (strings.Clone).
+func (app *App) GetString(s string) string {
+	if !app.config.Immutable || len(s) == 0 {
+		return s
+	}
+	if isReadOnly(unsafe.Pointer(unsafe.StringData(s))) { //nolint:gosec // pointer check avoids unnecessary copy
+		return s // literal / rodata → safe to return as-is
+	}
+	return strings.Clone(s) // heap-backed / aliased → detach
+}
+
+// GetBytes returns b unchanged when Immutable is off or b is read-only (rodata).
+// Otherwise it returns a detached copy.
+func (app *App) GetBytes(b []byte) []byte {
+	if !app.config.Immutable || len(b) == 0 {
+		return b
+	}
+	if isReadOnly(unsafe.Pointer(unsafe.SliceData(b))) { //nolint:gosec // pointer check avoids unnecessary copy
+		return b // rodata → safe to return as-is
+	}
+	return utils.CopyBytes(b) // detach when backed by request/response memory
+}
+
 // Adds an ip address to TrustProxyConfig.ranges or TrustProxyConfig.ips based on whether it is an IP range or not
 func (app *App) handleTrustedProxy(ipAddress string) {
 	if strings.Contains(ipAddress, "/") {

app_test.go

@@ -26,8 +26,9 @@ import (
 	"sync"
 	"testing"
 	"time"
+	"unsafe"
 
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -589,7 +590,7 @@ func Test_App_Use_UnescapedPath(t *testing.T) {
 	body, err := io.ReadAll(resp.Body)
 	require.NoError(t, err, "app.Test(req)")
 	// check the param result
-	require.Equal(t, "اختبار", app.getString(body))
+	require.Equal(t, "اختبار", app.toString(body))
 
 	// with lowercase letters
 	resp, err = app.Test(httptest.NewRequest(MethodGet, "/cr%C3%A9er/%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1", nil))
@@ -625,7 +626,7 @@ func Test_App_Use_CaseSensitive(t *testing.T) {
 	body, err := io.ReadAll(resp.Body)
 	require.NoError(t, err, "app.Test(req)")
 	// check the detected path result
-	require.Equal(t, "/AbC", app.getString(body))
+	require.Equal(t, "/AbC", app.toString(body))
 }
 
 func Test_App_Not_Use_StrictRouting(t *testing.T) {
@@ -981,6 +982,56 @@ func Test_App_Config(t *testing.T) {
 	require.True(t, app.Config().StrictRouting)
 }
 
+func Test_App_GetString(t *testing.T) {
+	t.Parallel()
+
+	heap := string([]byte("fiber"))
+	appMutable := New()
+	same := appMutable.GetString(heap)
+	if unsafe.StringData(same) != unsafe.StringData(heap) { //nolint:gosec // compare pointer addresses
+		t.Errorf("expected original string when immutable is disabled")
+	}
+
+	appImmutable := New(Config{Immutable: true})
+	copied := appImmutable.GetString(heap)
+	if unsafe.StringData(copied) == unsafe.StringData(heap) { //nolint:gosec // compare pointer addresses
+		t.Errorf("expected a copy for heap-backed string when immutable is enabled")
+	}
+
+	literal := "fiber"
+	sameLit := appImmutable.GetString(literal)
+	if unsafe.StringData(sameLit) != unsafe.StringData(literal) { //nolint:gosec // compare pointer addresses
+		t.Errorf("expected original literal when immutable is enabled")
+	}
+}
+
+func Test_App_GetBytes(t *testing.T) {
+	t.Parallel()
+
+	b := []byte("fiber")
+	appMutable := New()
+	same := appMutable.GetBytes(b)
+if unsafe.SliceData(same) != unsafe.SliceData(b) {
+		t.Errorf("expected original slice when immutable is disabled")
+	}
+
+	alias := make([]byte, 10)
+	copy(alias, b)
+	sub := alias[:5]
+	appImmutable := New(Config{Immutable: true})
+	copied := appImmutable.GetBytes(sub)
+	if unsafe.SliceData(copied) == unsafe.SliceData(sub) {
+		t.Errorf("expected a copy for aliased slice when immutable is enabled")
+	}
+
+	full := make([]byte, 5)
+	copy(full, b)
+	detached := appImmutable.GetBytes(full)
+	if unsafe.SliceData(detached) == unsafe.SliceData(full) {
+		t.Errorf("expected a copy even when cap==len")
+	}
+}
+
 func Test_App_Shutdown(t *testing.T) {
 	t.Parallel()
 	t.Run("success", func(t *testing.T) {

bind.go

@@ -7,7 +7,7 @@ import (
 	"sync"
 
 	"github.com/gofiber/fiber/v3/binder"
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 )
 
 // CustomBinder An interface to register custom binders.

binder/cbor.go

@@ -1,7 +1,7 @@
 package binder
 
 import (
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 )
 
 // CBORBinding is the CBOR binder for CBOR request body.

binder/cookie.go

@@ -1,7 +1,7 @@
 package binder
 
 import (
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 	"github.com/valyala/fasthttp"
 )
 

binder/form.go

@@ -3,7 +3,7 @@ package binder
 import (
 	"mime/multipart"
 
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 	"github.com/valyala/fasthttp"
 )
 

binder/header.go

@@ -1,7 +1,7 @@
 package binder
 
 import (
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 	"github.com/valyala/fasthttp"
 )
 

binder/json.go

@@ -1,7 +1,7 @@
 package binder
 
 import (
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 )
 
 // JSONBinding is the JSON binder for JSON request body.

binder/mapping.go

@@ -9,7 +9,7 @@ import (
 	"strings"
 	"sync"
 
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 	"github.com/valyala/bytebufferpool"
 
 	"github.com/gofiber/schema"

binder/msgpack.go

@@ -1,7 +1,7 @@
 package binder
 
 import (
-	"github.com/gofiber/utils/v2"
+	utils "github.com/gofiber/utils/v2"
 )
 
 // MsgPackBinding is the MsgPack binder for MsgPack request body.