feat: copy on immutable boundary

ReneWerner87 · ReneWerner87 · commit c0daafad1d83 · 2025-08-22T13:03:28.000+02:00
diff --git a/app.go b/app.go
@@ -636,26 +636,28 @@ func NewWithCustomCtx(newCtxFunc func(app *App) CustomCtx, config ...Config) *Ap
 	return app
 }
 
-// SafeString returns s when it already owns its memory or `Immutable` is enabled.
-// Otherwise, a copy is allocated to ensure the caller can safely reuse the value.
-func (app *App) SafeString(s string) string {
-	if len(s) == 0 || app.config.Immutable {
+// ImmutableString ensures the returned string doesn't reference request or response
+// memory when `Immutable` is enabled. If immutability is disabled, the input is
+// returned without modification.
+func (app *App) ImmutableString(s string) string {
+	if !app.config.Immutable || len(s) == 0 {
 		return s
 	}
-	b := app.getBytes(s)
+	b := utils.UnsafeBytes(s)
 	if len(b) > 0 && unsafe.StringData(s) == &b[0] {
 		return utils.CopyString(s)
 	}
 	return s
 }
 
-// SafeBytes returns b when it already owns its memory or `Immutable` is enabled.
-// Otherwise, a copy is allocated to ensure the caller can safely reuse the value.
-func (app *App) SafeBytes(b []byte) []byte {
-	if len(b) == 0 || app.config.Immutable {
+// ImmutableBytes ensures the returned slice doesn't reference request or response
+// memory when `Immutable` is enabled. If immutability is disabled, the input is
+// returned without modification.
+func (app *App) ImmutableBytes(b []byte) []byte {
+	if !app.config.Immutable || len(b) == 0 {
 		return b
 	}
-	s := app.getString(b)
+	s := utils.UnsafeString(b)
 	if unsafe.StringData(s) == &b[0] {
 		return utils.CopyBytes(b)
 	}
diff --git a/app_test.go b/app_test.go
@@ -982,37 +982,37 @@ func Test_App_Config(t *testing.T) {
 	require.True(t, app.Config().StrictRouting)
 }
 
-func Test_App_SafeString(t *testing.T) {
+func Test_App_ImmutableString(t *testing.T) {
 	t.Parallel()
 
 	s := "fiber"
 	app := New()
-	copied := app.SafeString(s)
-	if unsafe.StringData(copied) == unsafe.StringData(s) {
-		t.Errorf("expected a copy when immutable is disabled")
+	same := app.ImmutableString(s)
+	if unsafe.StringData(same) != unsafe.StringData(s) {
+		t.Errorf("expected original string when immutable is disabled")
 	}
 
 	appImmutable := New(Config{Immutable: true})
-	same := appImmutable.SafeString(s)
-	if unsafe.StringData(same) != unsafe.StringData(s) {
-		t.Errorf("expected original string when immutable is enabled")
+	copied := appImmutable.ImmutableString(s)
+	if unsafe.StringData(copied) == unsafe.StringData(s) {
+		t.Errorf("expected a copy when immutable is enabled")
 	}
 }
 
-func Test_App_SafeBytes(t *testing.T) {
+func Test_App_ImmutableBytes(t *testing.T) {
 	t.Parallel()
 
 	b := []byte("fiber")
 	app := New()
-	copied := app.SafeBytes(b)
-	if &copied[0] == &b[0] {
-		t.Errorf("expected a copy when immutable is disabled")
+	same := app.ImmutableBytes(b)
+	if &same[0] != &b[0] {
+		t.Errorf("expected original slice when immutable is disabled")
 	}
 
 	appImmutable := New(Config{Immutable: true})
-	same := appImmutable.SafeBytes(b)
-	if &same[0] != &b[0] {
-		t.Errorf("expected original slice when immutable is enabled")
+	copied := appImmutable.ImmutableBytes(b)
+	if &copied[0] == &b[0] {
+		t.Errorf("expected a copy when immutable is enabled")
 	}
 }
 
diff --git a/docs/api/app.md b/docs/api/app.md
@@ -9,20 +9,20 @@ import Reference from '@site/src/components/reference';
 
 ## Helpers
 
-### SafeString
+### ImmutableString
 
-Returns `s` unless it still references request or response memory, in which case a safe copy is allocated. Within handlers, call via `c.App().SafeString(...)`. When [`Immutable`](./fiber.md#immutable) is enabled, context helpers already return owned values so this usually yields the original string.
+When [`Immutable`](./fiber.md#immutable) is enabled, returns a detached copy of `s` if it still references request or response memory. If immutability is disabled, `s` is returned unchanged.
 
 ```go title="Signature"
-func (app *App) SafeString(s string) string
+func (app *App) ImmutableString(s string) string
 ```
 
-### SafeBytes
+### ImmutableBytes
 
-Returns `b` unless it shares underlying memory with the current request or response, in which case a safe copy is allocated. Within handlers, call via `c.App().SafeBytes(...)`. With [`Immutable`](./fiber.md#immutable) enabled, values are already copied and this method simply returns the input.
+When [`Immutable`](./fiber.md#immutable) is enabled, returns a detached copy of `b` if it still references request or response memory. If immutability is disabled, `b` is returned unchanged.
 
 ```go title="Signature"
-func (app *App) SafeBytes(b []byte) []byte
+func (app *App) ImmutableBytes(b []byte) []byte
 ```
 
 ## Routing
diff --git a/docs/api/ctx.md b/docs/api/ctx.md
@@ -627,7 +627,7 @@ app.Get("/", func(c fiber.Ctx) error {
 
 :::info
 Returned value is only valid within the handler. Do not store any references.
-Use [`App.SafeString`](./app.md#safestring) or [`App.SafeBytes`](./app.md#safebytes) to create copies when needed, or enable the [**`Immutable`**](./fiber.md#immutable) setting. [Read more...](../#zero-allocation)
+Use [`App.ImmutableString`](./app.md#immutablestring) or [`App.ImmutableBytes`](./app.md#immutablebytes) to create copies when needed, or enable the [**`Immutable`**](./fiber.md#immutable) setting. [Read more...](../#zero-allocation)
 :::
 ### FormFile
 
diff --git a/docs/intro.md b/docs/intro.md
@@ -52,12 +52,12 @@ func handler(c fiber.Ctx) error {
 }
 ```
 
-Fiber provides `SafeString` and `SafeBytes` methods on the app that perform the above when needed.
+Fiber provides `ImmutableString` and `ImmutableBytes` methods on the app that perform the above when `Immutable` is enabled.
 
 ```go
 app.Get("/:foo", func(c fiber.Ctx) error {
     // Variable is now immutable
-    result := c.App().SafeString(c.Params("foo"))
+    result := c.App().ImmutableString(c.Params("foo"))
 
     // ...
 })
diff --git a/docs/middleware/cache.md b/docs/middleware/cache.md
@@ -50,6 +50,7 @@ Import the middleware package that is part of the Fiber web framework
 import (
     "github.com/gofiber/fiber/v3"
     "github.com/gofiber/fiber/v3/middleware/cache"
+    "github.com/gofiber/utils/v2"
 )
 ```
 
@@ -78,7 +79,7 @@ app.Use(cache.New(cache.Config{
         return time.Second * time.Duration(newCacheTime)
     },
     KeyGenerator: func(c fiber.Ctx) string {
-        return c.App().SafeString(c.Path())
+        return utils.CopyString(c.Path())
     },
 }))
 
@@ -109,7 +110,7 @@ The `CacheInvalidator` function allows you to define custom conditions for cache
 | CacheHeader          | `string`                                       | CacheHeader is the header on the response header that indicates the cache status, with the possible return values "hit," "miss," or "unreachable."                                                                                                                                                             | `X-Cache`                                                        |
 | CacheControl         | `bool`                                         | CacheControl enables client-side caching if set to true.                                                                                                                                                                                                                                                       | `false`                                                          |
 | CacheInvalidator     | `func(fiber.Ctx) bool`                         | CacheInvalidator defines a function that is executed before checking the cache entry. It can be used to invalidate the existing cache manually by returning true.                                                                                                                                              | `nil`                                                            |
-| KeyGenerator         | `func(fiber.Ctx) string`                       | Key allows you to generate custom keys. The HTTP method is appended automatically.                                                                                                                                                                                                                                                                        | `func(c fiber.Ctx) string { return c.App().SafeString(c.Path()) }` |
+| KeyGenerator         | `func(fiber.Ctx) string`                       | Key allows you to generate custom keys. The HTTP method is appended automatically.                                                                                                                                                                                                                                                                        | `func(c fiber.Ctx) string { return utils.CopyString(c.Path()) }` |
 | ExpirationGenerator  | `func(fiber.Ctx, *cache.Config) time.Duration` | ExpirationGenerator allows you to generate custom expiration keys based on the request.                                                                                                                                                                                                                        | `nil`                                                            |
 | Storage              | `fiber.Storage`                                | Storage is used to store the state of the middleware.                                                                                                                                                                                                                                                            | In-memory store                                                  |
 | StoreResponseHeaders | `bool`                                         | StoreResponseHeaders allows you to store additional headers generated by next middlewares & handler.                                                                                                                                                                                                           | `false`                                                          |
@@ -126,7 +127,7 @@ var ConfigDefault = Config{
     CacheControl: false,
     CacheInvalidator: nil,
     KeyGenerator: func(c fiber.Ctx) string {
-        return c.App().SafeString(c.Path())
+        return utils.CopyString(c.Path())
     },
     ExpirationGenerator:  nil,
     StoreResponseHeaders: false,
diff --git a/docs/whats_new.md b/docs/whats_new.md
@@ -71,7 +71,7 @@ We have made several changes to the Fiber app, including:
 - **NewWithCustomCtx**: Initialize an app with a custom context in one step.
 - **State**: Provides a global state for the application, which can be used to store and retrieve data across the application. Check out the [State](./api/state) method for further details.
 - **NewErrorf**: Allows variadic parameters when creating formatted errors.
-- **SafeBytes / SafeString**: Conditional copy helpers that allocate only when a value still references request or response memory. If it already owns its data (e.g. with `Immutable` enabled), the value is returned as-is. Access via `c.App().SafeString` and `c.App().SafeBytes`.
+- **ImmutableBytes / ImmutableString**: Helpers that copy values only when `Immutable` is enabled and data still references request or response buffers. Access via `c.App().ImmutableString` and `c.App().ImmutableBytes`.
 
 #### Custom Route Constraints
 
diff --git a/middleware/cache/cache.go b/middleware/cache/cache.go
@@ -236,10 +236,10 @@ func New(config ...Config) fiber.Handler {
 
 		e = manager.acquire()
 		// Cache response
-		e.body = c.App().SafeBytes(c.Response().Body())
+		e.body = utils.CopyBytes(c.Response().Body())
 		e.status = c.Response().StatusCode()
-		e.ctype = c.App().SafeBytes(c.Response().Header.ContentType())
-		e.cencoding = c.App().SafeBytes(c.Response().Header.Peek(fiber.HeaderContentEncoding))
+		e.ctype = utils.CopyBytes(c.Response().Header.ContentType())
+		e.cencoding = utils.CopyBytes(c.Response().Header.Peek(fiber.HeaderContentEncoding))
 
 		ageVal := uint64(0)
 		if b := c.Response().Header.Peek(fiber.HeaderAge); len(b) > 0 {
@@ -259,7 +259,7 @@ func New(config ...Config) fiber.Handler {
 				// create real copy
 				keyS := string(key)
 				if _, ok := ignoreHeaders[keyS]; !ok {
-					e.headers[keyS] = c.App().SafeBytes(value)
+					e.headers[keyS] = utils.CopyBytes(value)
 				}
 			}
 		}
diff --git a/middleware/cache/cache_test.go b/middleware/cache/cache_test.go
@@ -16,6 +16,7 @@ import (
 	"github.com/gofiber/fiber/v3"
 	"github.com/gofiber/fiber/v3/internal/storage/memory"
 	"github.com/gofiber/fiber/v3/middleware/etag"
+	"github.com/gofiber/utils/v2"
 	"github.com/stretchr/testify/require"
 	"github.com/valyala/fasthttp"
 )
@@ -563,7 +564,7 @@ func Test_CustomKey(t *testing.T) {
 	var called bool
 	app.Use(New(Config{KeyGenerator: func(c fiber.Ctx) string {
 		called = true
-		return c.App().SafeString(c.Path())
+		return utils.CopyString(c.Path())
 	}}))
 
 	app.Get("/", func(c fiber.Ctx) error {
diff --git a/middleware/cache/config.go b/middleware/cache/config.go
@@ -4,6 +4,7 @@ import (
 	"time"
 
 	"github.com/gofiber/fiber/v3"
+	"github.com/gofiber/utils/v2"
 )
 
 // Config defines the config for middleware.
@@ -26,7 +27,7 @@ type Config struct {
 	// Key allows you to generate custom keys, by default c.Path() is used
 	//
 	// Default: func(c fiber.Ctx) string {
-	//   return c.App().SafeString(c.Path())
+	//   return utils.CopyString(c.Path())
 	// }
 	KeyGenerator func(fiber.Ctx) string
 
@@ -81,7 +82,7 @@ var ConfigDefault = Config{
 	CacheControl:     false,
 	CacheInvalidator: nil,
 	KeyGenerator: func(c fiber.Ctx) string {
-		return c.App().SafeString(c.Path())
+		return utils.CopyString(c.Path())
 	},
 	ExpirationGenerator:  nil,
 	StoreResponseHeaders: false,
diff --git a/middleware/idempotency/idempotency.go b/middleware/idempotency/idempotency.go
@@ -76,7 +76,7 @@ func New(config ...Config) fiber.Handler {
 		}
 
 		// Don't execute middleware if the idempotency key is empty
-		key := c.App().SafeString(c.Get(cfg.KeyHeader))
+		key := utils.CopyString(c.Get(cfg.KeyHeader))
 		if key == "" {
 			return c.Next()
 		}
@@ -119,7 +119,7 @@ func New(config ...Config) fiber.Handler {
 		res := &response{
 			StatusCode: c.Response().StatusCode(),
 
-			Body: c.App().SafeBytes(c.Response().Body()),
+			Body: utils.CopyBytes(c.Response().Body()),
 		}
 		{
 			headers := make(map[string][]string)
diff --git a/middleware/proxy/proxy.go b/middleware/proxy/proxy.go
@@ -182,10 +182,10 @@ func doAction(
 
 	req := c.Request()
 	res := c.Response()
-	originalURL := c.App().SafeString(c.OriginalURL())
+	originalURL := utils.CopyString(c.OriginalURL())
 	defer req.SetRequestURI(originalURL)
 
-	copiedURL := c.App().SafeString(addr)
+	copiedURL := utils.CopyString(addr)
 	req.SetRequestURI(copiedURL)
 	// NOTE: if req.isTLS is true, SetRequestURI keeps the scheme as https.
 	// Reference: https://github.com/gofiber/fiber/issues/1762
diff --git a/req.go b/req.go
@@ -590,7 +590,7 @@ func (r *DefaultReq) Params(key string, defaultValue ...string) string {
 				break
 			}
 			val := values[i]
-			return r.c.app.SafeString(val)
+			return r.c.app.ImmutableString(val)
 		}
 	}
 	return defaultString("", defaultValue)
diff --git a/res.go b/res.go
@@ -775,7 +775,7 @@ func (r *DefaultRes) SendFile(file string, config ...SendFile) error {
 	}
 
 	// Keep original path for mutable params
-	r.c.pathOriginal = r.c.app.SafeString(r.c.pathOriginal)
+	r.c.pathOriginal = utils.CopyString(r.c.pathOriginal)
 
 	request := &r.c.fasthttp.Request
 
@@ -805,7 +805,7 @@ func (r *DefaultRes) SendFile(file string, config ...SendFile) error {
 	file = filepath.ToSlash(file)
 
 	// Restore the original requested URL
-	originalURL := r.c.app.SafeString(r.c.OriginalURL())
+	originalURL := utils.CopyString(r.c.OriginalURL())
 	defer request.SetRequestURI(originalURL)
 
 	// Set new URI for fileHandler
