Skip to content

Commit 7e901ff

Browse files
Add docs from gofiber/fiber@2555a4f
1 parent 8f36b12 commit 7e901ff

File tree

3 files changed

+77
-2
lines changed

3 files changed

+77
-2
lines changed

docs/core/api/ctx.md

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ app.Post("/", func(c fiber.Ctx) error {
4242

4343
### Context
4444

45-
`Context` implements `context.Context`. However due to [current limitations in how fasthttp](https://github.com/valyala/fasthttp/issues/965#issuecomment-777268945) works, `Deadline()`, `Done()` and `Err()` operate as a nop.
45+
`Context` implements `context.Context`. However due to [current limitations in how fasthttp](https://github.com/valyala/fasthttp/issues/965#issuecomment-777268945) works, `Deadline()`, `Done()` and `Err()` operate as a nop. The `fiber.Ctx` instance is reused after the handler returns and must not be used for asynchronous operations once the handler has completed. Call [`Context()`](#context-1) within the handler to obtain a `context.Context` that can be used outside the handler.
4646

4747
```go title="Signature"
4848
func (c fiber.Ctx) Deadline() (deadline time.Time, ok bool)
@@ -73,6 +73,42 @@ app.Get("/", func(c fiber.Ctx) error {
7373
})
7474
```
7575

76+
### Context()
77+
78+
Returns a `context.Context` that was previously set with [`SetContext`](#setcontext).
79+
If no context was set, it returns `context.Background()`. Unlike `fiber.Ctx` itself,
80+
the returned context is safe to use after the handler completes.
81+
82+
```go title="Signature"
83+
func (c fiber.Ctx) Context() context.Context
84+
```
85+
86+
```go title="Example"
87+
app.Get("/", func(c fiber.Ctx) error {
88+
ctx := c.Context()
89+
go doWork(ctx)
90+
return nil
91+
})
92+
```
93+
94+
### SetContext
95+
96+
Sets the base `context.Context` used by [`Context()`](#context-1). Use this to
97+
propagate deadlines, cancelation signals, or values to asynchronous operations.
98+
99+
```go title="Signature"
100+
func (c fiber.Ctx) SetContext(ctx context.Context)
101+
```
102+
103+
```go title="Example"
104+
app.Get("/", func(c fiber.Ctx) error {
105+
c.SetContext(context.WithValue(context.Background(), "user", "alice"))
106+
ctx := c.Context()
107+
go doWork(ctx)
108+
return nil
109+
})
110+
```
111+
76112
### Drop
77113

78114
Terminates the client connection silently without sending any HTTP headers or response body.

docs/core/guide/context.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,15 @@ without adapters.
2121
However, `fasthttp` doesn't support cancellation yet, so
2222
`Deadline`, `Done`, and `Err` are no-ops.
2323

24+
:::caution
25+
The `fiber.Ctx` instance is only valid within the lifetime of the handler.
26+
It is reused for subsequent requests, so avoid storing `c` or using it in
27+
goroutines that outlive the handler. For asynchronous work, call
28+
`c.Context()` inside the handler to obtain a `context.Context` that can safely
29+
be used after the handler returns. By default, this returns `context.Background()`
30+
unless a custom context was provided with `c.SetContext`.
31+
:::
32+
2433
```go title="Example"
2534
func doSomething(ctx context.Context) {
2635
// ... your logic here
@@ -32,6 +41,32 @@ app.Get("/", func(c fiber.Ctx) error {
3241
})
3342
```
3443

44+
### Using context outside the handler
45+
46+
`fiber.Ctx` is recycled after each request. If you need a context that lives
47+
longer—for example, for work performed in a new goroutine—obtain it with
48+
`c.Context()` before returning from the handler.
49+
50+
```go title="Async work"
51+
app.Get("/job", func(c fiber.Ctx) error {
52+
ctx := c.Context()
53+
go performAsync(ctx)
54+
return c.SendStatus(fiber.StatusAccepted)
55+
})
56+
```
57+
58+
You can customize the base context by calling `c.SetContext` before
59+
requesting it:
60+
61+
```go
62+
app.Get("/job", func(c fiber.Ctx) error {
63+
c.SetContext(context.WithValue(context.Background(), "requestID", "123"))
64+
ctx := c.Context()
65+
go performAsync(ctx)
66+
return nil
67+
})
68+
```
69+
3570
### Retrieving Values
3671

3772
`Ctx.Value` is backed by [Locals](../api/ctx.md#locals).
@@ -190,6 +225,8 @@ you coordinate work with external APIs or databases while using Fiber's API.
190225
make it easy to retrieve request-scoped data.
191226
- Standard helpers such as `context.WithTimeout` can wrap `fiber.Ctx` to create
192227
fully featured derived contexts inside handlers.
228+
- Use `c.Context()` to obtain a `context.Context` that can outlive the handler,
229+
and `c.SetContext()` to customize it with additional values or deadlines.
193230

194231
With these tools, you can seamlessly integrate Fiber applications with
195232
Go's context-based APIs and manage request-scoped data effectively.

docs/core/whats_new.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -482,6 +482,8 @@ testConfig := fiber.TestConfig{
482482
- **SendString**: Similar to Express.js, sends a string as the response.
483483
- **String**: Similar to Express.js, converts a value to a string.
484484
- **Value**: For implementing `context.Context`. Returns request-scoped value from Locals.
485+
- **Context()**: Returns a `context.Context` that can be used outside the handler.
486+
- **SetContext**: Sets the base `context.Context` returned by `Context()` for propagating deadlines or values.
485487
- **ViewBind**: Binds data to a view, replacing the old `Bind` method.
486488
- **CBOR**: Introducing [CBOR](https://cbor.io/) binary encoding format for both request & response body. CBOR is a binary data serialization format which is both compact and efficient, making it ideal for use in web applications.
487489
- **MsgPack**: Introducing [MsgPack](https://msgpack.org/) binary encoding format for both request & response body. MsgPack is a binary serialization format that is more efficient than JSON, making it ideal for high-performance applications.
@@ -503,7 +505,7 @@ testConfig := fiber.TestConfig{
503505
- **RedirectBack**: Use `c.Redirect().Back()` instead.
504506
- **ReqHeaderParser**: Use `c.Bind().Header()` instead.
505507
- **UserContext**: Removed. `Ctx` itself now satisfies `context.Context`; pass `c` directly where a `context.Context` is required.
506-
- **SetUserContext**: Removed. Use `context.WithValue` on `c` or `c.Locals` to store additional request-scoped values.
508+
- **SetUserContext**: Removed. Use `SetContext` and `Context()` or `context.WithValue` on `c` to store additional request-scoped values.
507509

508510
### Changed Methods
509511

0 commit comments

Comments
 (0)