Skip to content

Commit 5803148

Browse files
github-actions[bot]github-actions[bot]
committed
Add docs from gofiber/fiber@eb677ac 
1 parent 1d05064 commit 5803148

File tree

3 files changed

+75
-0
lines changed

3 files changed

+75
-0
lines changed

‎docs/core/api/fiber.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ app := fiber.New(fiber.Config{
5555
| <Reference id="disableheadernormalizing">DisableHeaderNormalizing</Reference> | `bool` | By default all header names are normalized: conteNT-tYPE -&gt; Content-Type | `false` |
5656
| <Reference id="disablekeepalive">DisableKeepalive</Reference> | `bool` | Disables keep-alive connections so the server closes each connection after the first response. | `false` |
5757
| <Reference id="disablepreparsemultipartform">DisablePreParseMultipartForm</Reference> | `bool` | Will not pre parse Multipart Form data if set to true. This option is useful for servers that desire to treat multipart form data as a binary blob, or choose when to parse the data. | `false` |
58+
| <Reference id="disableheadautoregister">DisableHeadAutoRegister</Reference> | `bool` | Prevents Fiber from automatically registering `HEAD` routes for each `GET` route so you can supply custom `HEAD` handlers; manual `HEAD` routes still override the generated ones. | `false` |
5859
| <Reference id="enableipvalidation">EnableIPValidation</Reference> | `bool` | If set to true, `c.IP()` and `c.IPs()` will validate IP addresses before returning them. Also, `c.IP()` will return only the first valid IP rather than just the raw header value that may be a comma separated string.<br /><br />**WARNING:** There is a small performance cost to doing this validation. Keep disabled if speed is your only concern and your application is behind a trusted proxy that already validates this header. | `false` |
5960
| <Reference id="enablesplittingonparsers">EnableSplittingOnParsers</Reference> | `bool` | Splits query, body, and header parameters on commas when enabled.<br /><br />For example, `/api?foo=bar,baz` becomes `foo[]=bar&foo[]=baz`. | `false` |
6061
| <Reference id="trustproxy">TrustProxy</Reference> | `bool` | When true, Fiber validates the proxy IP against `TrustProxyConfig.Proxies`. <br /><br />By default, `c.Protocol()`, `c.IP()`, and `c.Hostname()` read values from standard X-Forwarded headers. If the remote IP matches a trusted proxy, these methods behave as if `TrustProxy` were disabled. Otherwise, `c.Protocol()` reflects the connection scheme, `c.IP()` uses `RemoteIP()` from Fasthttp, and `c.Hostname()` uses `fasthttp.Request.URI().Host()` | `false` |

‎docs/core/guide/routing.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,43 @@ import RoutingHandler from './../partials/routing/handler.md';
1616

1717
<RoutingHandler />
1818

19+
## Automatic HEAD routes
20+
21+
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.
22+
23+
```go title="GET handlers automatically expose HEAD"
24+
app := fiber.New()
25+
26+
app.Get("/users/:id", func(c fiber.Ctx) error {
27+
c.Set("X-User", c.Params("id"))
28+
return c.SendStatus(fiber.StatusOK)
29+
})
30+
31+
// HEAD /users/:id now returns the same headers and status without a body.
32+
```
33+
34+
You can still register dedicated `HEAD` handlers—even with auto-registration enabled—and Fiber replaces the generated route so your implementation wins:
35+
36+
```go title="Override the generated HEAD handler"
37+
app.Head("/users/:id", func(c fiber.Ctx) error {
38+
return c.SendStatus(fiber.StatusNoContent)
39+
})
40+
```
41+
42+
To opt out globally, start the app with `DisableHeadAutoRegister`:
43+
44+
```go title="Disable automatic HEAD registration"
45+
handler := func(c fiber.Ctx) error {
46+
c.Set("X-User", c.Params("id"))
47+
return c.SendStatus(fiber.StatusOK)
48+
}
49+
50+
app := fiber.New(fiber.Config{DisableHeadAutoRegister: true})
51+
app.Get("/users/:id", handler) // HEAD /users/:id now returns 405 unless you add it manually.
52+
```
53+
54+
Auto-generated `HEAD` routes participate in every router scope, including `Group` hierarchies, mounted sub-apps, parameterized and wildcard paths, and static file helpers. They also appear in route listings such as `app.Stack()` so tooling sees both the `GET` and `HEAD` entries.
55+
1956
## Paths
2057

2158
A route path paired with an HTTP method defines an endpoint. It can be a plain **string** or a **pattern**.

‎docs/core/whats_new.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -356,6 +356,43 @@ app.RouteChain("/api").RouteChain("/user/:id?")
356356

357357
You can find more information about `app.RouteChain` and `app.Route` in the API documentation ([RouteChain](./api/app#routechain), [Route](./api/app#route)).
358358

359+
### Automatic HEAD routes for GET
360+
361+
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.
362+
363+
```go title="GET now enables HEAD automatically"
364+
app := fiber.New()
365+
366+
app.Get("/health", func(c fiber.Ctx) error {
367+
c.Set("X-Service", "api")
368+
return c.SendString("OK")
369+
})
370+
371+
// HEAD /health reuses the GET middleware chain and returns headers only.
372+
```
373+
374+
You can still register explicit `HEAD` handlers for any `GET` route, and they continue to win when you add them:
375+
376+
```go title="Override the generated HEAD handler"
377+
app.Head("/health", func(c fiber.Ctx) error {
378+
return c.SendStatus(fiber.StatusNoContent)
379+
})
380+
```
381+
382+
Prefer to manage `HEAD` routes yourself? Disable the feature through `fiber.Config.DisableHeadAutoRegister`:
383+
384+
```go title="Disable automatic HEAD registration"
385+
handler := func(c fiber.Ctx) error {
386+
c.Set("X-Service", "api")
387+
return c.SendString("OK")
388+
}
389+
390+
app := fiber.New(fiber.Config{DisableHeadAutoRegister: true})
391+
app.Get("/health", handler) // HEAD /health now returns 405 unless you add it manually.
392+
```
393+
394+
Auto-generated `HEAD` routes appear in tooling such as `app.Stack()` and cover the same routing scenarios as their `GET` counterparts, including groups, mounted apps, dynamic parameters, and static file handlers.
395+
359396
### Middleware registration
360397

361398
We have aligned our method for middlewares closer to [`Express`](https://expressjs.com/en/api.html#app.use) and now also support the [`Use`](./api/app#use) of multiple prefixes.

0 commit comments

Comments
 (0)