router.go (2)

481-503: Normalize path when pruning to avoid trailing-slash/case variants.

Comparing by raw Route.Path can miss pruning when HEAD/GET are registered with equivalent paths that differ by casing or trailing slashes under non-strict/case-insensitive configs. Compare against the normalized route.path instead.

Apply this diff:

 func (app *App) pruneAutoHeadRouteLocked(path string) {
-	headIndex := app.methodInt(MethodHead)
+	headIndex := app.methodInt(MethodHead)
 	if headIndex == -1 {
 		return
 	}
 
-	headStack := app.stack[headIndex]
+	// Normalize for consistent comparison with route.path
+	norm := app.normalizePath(path)
+	headStack := app.stack[headIndex]
 	for i := len(headStack) - 1; i >= 0; i-- {
 		headRoute := headStack[i]
-		if headRoute.Path != path || headRoute.mount || headRoute.use || !headRoute.autoHead {
+		if headRoute.mount || headRoute.use || !headRoute.autoHead || headRoute.path != norm {
 			continue
 		}
 
 		app.stack[headIndex] = append(headStack[:i], headStack[i+1:]...)
 		app.routesRefreshed = true
 		atomic.AddUint32(&app.handlersCount, ^uint32(len(headRoute.Handlers)-1)) //nolint:gosec // Not a concern
 		return
 	}
 }

---

620-674: De-dup and lookup by normalized path to avoid duplicate auto HEADs.

Use route.path (normalized) instead of Route.Path (raw) when tracking existing HEADs and checking GETs. Prevents duplicates when GET/HEAD are registered with equivalent-but-different raw strings (e.g., "/users" vs "/users/").

Apply this diff:

 func (app *App) ensureAutoHeadRoutesLocked() {
@@
-	headStack := app.stack[headIndex]
-	existing := make(map[string]struct{}, len(headStack))
-	for _, route := range headStack {
+	headStack := app.stack[headIndex]
+	existing := make(map[string]struct{}, len(headStack))
+	for _, route := range headStack {
 		if route.mount || route.use {
 			continue
 		}
-		existing[route.Path] = struct{}{}
+		existing[route.path] = struct{}{}
 	}
@@
-	for _, route := range app.stack[getIndex] {
+	for _, route := range app.stack[getIndex] {
 		if route.mount || route.use {
 			continue
 		}
-		if _, ok := existing[route.Path]; ok {
+		if _, ok := existing[route.path]; ok {
 			continue
 		}
@@
 		headStack = append(headStack, headRoute)
-		existing[route.Path] = struct{}{}
+		existing[route.path] = struct{}{}
 		app.routesRefreshed = true

Consider adding a small test for trailing-slash/case-insensitive variants to lock this in.

router_test.go (2)

320-543: Auto-HEAD suite: strong coverage; add two edge cases for path normalization.

Great end-to-end validations. To catch trailing-slash and case-insensitive variants, add focused tests so pruning/dedup works when raw paths differ but normalize to the same value.

Suggested additions:

+func TestAutoHead_PruneTrailingSlashVariant(t *testing.T) {
+  t.Parallel()
+  app := New(Config{StrictRouting: false})
+  app.Get("/trail/", func(c Ctx) error { return c.SendString("ok") })
+  // Ensure auto HEAD exists
+  app.startupProcess()
+  // Add explicit HEAD without trailing slash; should prune auto one
+  app.Head("/trail", func(c Ctx) error {
+    c.Set("X-Explicit", "1")
+    return c.SendStatus(StatusAccepted)
+  })
+  resp, err := app.Test(httptest.NewRequest(MethodHead, "/trail", nil))
+  require.NoError(t, err)
+  defer resp.Body.Close()
+  require.Equal(t, StatusAccepted, resp.StatusCode)
+  require.Equal(t, "1", resp.Header.Get("X-Explicit"))
+}
+
+func TestAutoHead_CaseInsensitiveMatch(t *testing.T) {
+  t.Parallel()
+  app := New(Config{CaseSensitive: false})
+  app.Get("/Users", func(c Ctx) error { return c.SendString("ok") })
+  app.startupProcess()
+  // Explicit HEAD with different casing should override auto HEAD
+  app.Head("/users", func(c Ctx) error { return c.SendStatus(StatusNoContent) })
+  resp, err := app.Test(httptest.NewRequest(MethodHead, "/USERS", nil))
+  require.NoError(t, err)
+  defer resp.Body.Close()
+  require.Equal(t, StatusNoContent, resp.StatusCode)
+}

---

1872-1873: Make Allow header assertion order-agnostic.

RequestMethods order can be customized; assert membership instead of exact order.

Apply this diff:

-	app.ensureAutoHeadRoutes()
+	app.ensureAutoHeadRoutes()
 	app.RebuildTree()
@@
-	require.Equal(t, "GET, HEAD", allow)
+	parts := strings.Split(strings.ReplaceAll(allow, " ", ""), ",")
+	require.ElementsMatch(t, []string{"GET", "HEAD"}, parts)

Also applies to: 1886-1887

docs/whats_new.md (1)

359-390: Consider adding fasthttp context to clarify the safety of HEAD route copying.

The documentation explains that the response body "remains empty" for auto-generated HEAD routes, but doesn't explicitly mention that this behavior is guaranteed by fasthttp (which omits bodies for HEAD responses per HTTP spec). The PR objectives include documenting this technical detail and the safety rationale for copying GET handlers.

Consider adding a brief technical note clarifying that fasthttp handles body omission automatically:

 Fiber now auto-registers a `HEAD` route whenever you add a `GET` route. The generated handler chain matches the `GET` chain so status codes and headers stay in sync while the response body remains empty, ensuring HEAD clients observe the same metadata as a GET consumer.
+
+This approach is safe because fasthttp automatically omits response bodies for HEAD requests, eliminating the need for handler-specific HEAD logic.

This addition would more explicitly satisfy the PR objective to "document that fasthttp omits bodies for HEAD responses" and clarify why copying GET handlers for HEAD is safe.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: grivera64
PR: gofiber/fiber#3807
File: adapter_test.go:118-144
Timestamp: 2025-10-16T07:15:26.529Z
Learning: In Fiber v3, net/http handlers (http.Handler, http.HandlerFunc, or raw func(http.ResponseWriter, *http.Request)) can be passed directly to routing methods like app.Get(), app.Post(), etc. The framework automatically detects and wraps them internally via toFiberHandler/collectHandlers. The github.com/gofiber/fiber/v3/middleware/adaptor package is legacy and should not be suggested for tests or code using native net/http handler support.

router.go (1)

659-662: Doc comment on fasthttp HEAD behavior is precise

Wording matches transmission‑phase suppression; no body while preserving headers/length.

router_test.go (1)

15-16: Run project formatters after import change

After adding path/filepath, run make format to enforce gofumpt import ordering.

router.go (3)

390-404: Path normalization helper matches register semantics

normalizePath mirrors register’s casing and trailing‑slash rules and removes escapes. Consider reusing this helper inside register to reduce duplication and drift risk.

---

480-503: Pruning logic is correct and case/strict aware

• Normalizes the incoming path, then removes only mount=false,use=false,autoHead=true entries.
• Updates routesRefreshed and handlersCount.

Nit: the comment could mention it’s also used when a GET route is deleted, not only when an explicit HEAD is registered.

-// pruneAutoHeadRouteLocked removes an automatically generated HEAD route so a
-// later explicit registration can take its place without duplicating handler
-// chains. The caller must already hold app.mutex.
+// pruneAutoHeadRouteLocked removes an automatically generated HEAD route.
+// Used when (a) an explicit HEAD is registered, allowing it to take precedence,
+// or (b) the originating GET route is removed, to avoid stale HEAD entries.
+// The caller must already hold app.mutex.

---

621-679: Auto‑HEAD generation uses normalized keys and respects config

• Skips when DisableAutoRegister is true.
• Uses route.path (normalized) for de‑duplication in existing map — correct for case‑insensitive/strict routing setups.
• Updates handlersCount, routesRefreshed, latestRoute, and onRoute hooks.

Minor: assigning headStack back only when added is a micro‑optimization; setting unconditionally is also fine.

router_test.go (1)

320-562: Excellent coverage for auto‑HEAD lifecycle

Covers enable/disable, override with explicit HEAD, groups, static files, 404, precedence, route listing, and no‑body semantics.

Optional enhancement: add a case‑insensitive scenario to guard against duplicates (e.g., Config{CaseSensitive:false}: GET /foo + explicit HEAD /Foo → single HEAD, no auto‑HEAD).

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: CR
PR: gofiber/fiber#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-19T15:13:10.652Z
Learning: Run `make format` to format the project when modifying code

docs/whats_new.md (1)

359-395: Backticks + example look good

Backticks for “HEAD” and “GET” and the defined handler make this section copy/paste‑safe.

docs/guide/routing.md (1)

19-55: Section reads well

Backticks and examples are consistent; override/disable behavior is clear.

docs/whats_new.md (1)

359-395: Clarify HEAD body omission (fasthttp) and headers

Add a short note that fasthttp omits bodies on HEAD responses while preserving headers like Content-Length computed by the GET chain. Improves copy/paste confidence.

- Fiber now auto-registers a `HEAD` route whenever you add a `GET` route. The generated handler chain matches the `GET` chain so status codes and headers stay in sync while the response body remains empty, ensuring `HEAD` clients observe the same metadata as a `GET` consumer.
+ Fiber now auto-registers a `HEAD` route whenever you add a `GET` route. The generated handler chain matches the `GET` chain so status codes and headers stay in sync while the response body remains empty. Fasthttp automatically suppresses response bodies for `HEAD` responses during transmission, so headers (including `Content-Length`) computed by the `GET` chain are still sent while the payload is omitted.

router.go (1)

621-679: Auto-HEAD generation logic: solid; tiny comment polish

Implementation looks correct: skips use/mount, uses normalized route.path for case-insensitive apps, updates counts, and triggers hooks. Consider expanding the fasthttp note to mention header accuracy.

-        // Fasthttp automatically omits response bodies when transmitting
-        // HEAD responses, so the copied GET handler stack can execute
-        // unchanged while still producing an empty body on the wire.
+        // Fasthttp automatically omits response bodies when transmitting HEAD responses,
+        // so the copied GET handler stack can execute unchanged while still producing
+        // an empty body on the wire. Headers (e.g., Content-Length, ETag) computed
+        // by the GET chain remain accurate and are sent.

Also optional: keeping Name identical means RemoveRouteByName(name) without methods will remove both GET and generated HEAD. If this is undesirable, consider suffixing or omitting Name for auto routes.

Would you like a follow-up patch to differentiate route names for auto-generated HEAD entries?

docs/guide/routing.md (1)

19-55: Add one sentence on fasthttp HEAD behavior

Mirror the “What’s New” note so readers know headers remain while the body is suppressed by fasthttp.

-Fiber automatically registers a `HEAD` route for every `GET` route you add. The generated handler chain mirrors the `GET` chain, so `HEAD` requests reuse middleware, status codes, and headers while the response body is suppressed.
+Fiber automatically registers a `HEAD` route for every `GET` route you add. The generated handler chain mirrors the `GET` chain, so `HEAD` requests reuse middleware, status codes, and headers while the response body is suppressed. Fasthttp omits bodies for `HEAD` responses during transmission, so headers like `Content-Length` computed by the `GET` chain are still sent.

router_test.go (2)

1475-1476: Make Allow header assertion order-insensitive

RequestMethods order could change; compare as a set to avoid flaky failures.

- require.Equal(b, MethodGet+", "+MethodHead, string(c.Response.Header.Peek("Allow")))
+ allow := string(c.Response.Header.Peek("Allow"))
+ parts := strings.Split(allow, ", ")
+ require.ElementsMatch(b, []string{MethodGet, MethodHead}, parts)

- require.Equal(t, "GET, HEAD", allow)
+ parts := strings.Split(allow, ", ")
+ require.ElementsMatch(t, []string{MethodGet, MethodHead}, parts)

Remember to import strings in the test file scope if not already.

Would you like me to push a patch updating both sites?

Also applies to: 1904-1905

---

384-388: Optional: Assert Allow header in 405 case

You can assert Allow includes GET when auto-register is disabled to strengthen the contract.

 resp, err := app.Test(httptest.NewRequest(MethodHead, "/", nil))
 require.NoError(t, err)
 registerCleanup(t, resp.Body)
 require.Equal(t, StatusMethodNotAllowed, resp.StatusCode)
+require.Contains(t, resp.Header.Get("Allow"), MethodGet)

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: grivera64
PR: gofiber/fiber#3807
File: adapter_test.go:118-144
Timestamp: 2025-10-16T07:15:26.529Z
Learning: In Fiber v3, net/http handlers (http.Handler, http.HandlerFunc, or raw func(http.ResponseWriter, *http.Request)) can be passed directly to routing methods like app.Get(), app.Post(), etc. The framework automatically detects and wraps them internally via toFiberHandler/collectHandlers. The github.com/gofiber/fiber/v3/middleware/adaptor package is legacy and should not be suggested for tests or code using native net/http handler support.

Learnt from: CR
PR: gofiber/fiber#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-07-19T15:13:10.652Z
Learning: Run `make format` to format the project when modifying code