Fiber Admin Guide

This guide is the operational and architectural reference for Fiber v3 (github.com/gofiber/fiber/v3), the Express-inspired Go web framework built on fasthttp. It is written for the engineers who deploy, secure, tune, and extend Fiber-based services, and for architects and contributors who need to understand how the framework is put together internally.

Where the User Guide shows how to build with Fiber, this guide covers the complete configuration surface, the request lifecycle, security hardening, performance tuning, the middleware internals, and the repository layout. Everything here is derived directly from the v3 source at commit dec796e.

1. Executive Summary

What Fiber is. A web framework — a library you import into a Go program, not a server you install and run. It provides an HTTP router, a request/response context, a binder, a centralized error model, and ~30 first-party middleware packages. It has no CLI, no daemon, and no configuration files: configuration is Go code (fiber.Config{} and fiber.ListenConfig{}).

What it is built on. fasthttp v1.71.0, a high-performance HTTP engine that minimizes allocations by pooling and reusing request/response/context objects. Fiber is a thin, ergonomic layer over fasthttp; most network and performance behavior ultimately comes from fasthttp's Server struct, which Fiber exposes via app.Server().

Operational shape. A Fiber service is a single Go binary. You scale it vertically with goroutine concurrency (the default), horizontally with multiple instances behind a load balancer, or with prefork (multiple processes on one host sharing a port). There is no built-in clustering, message broker, or shared cache — state that must be shared across instances or prefork workers belongs in an external store.

Key dependencies.

Minimum runtime: Go 1.25.0.

2. Architecture

Request lifecycle

            ┌──────────────────────────────────────────────────────────┐
   client → │  fasthttp.Server  (app.Server())                         │
            │    • connection pooling, keep-alive, read/write buffers   │
            │    • acquires a pooled *fasthttp.RequestCtx               │
            └───────────────────────────┬──────────────────────────────┘
                                         │ RequestHandler (app.Handler())
                                         ▼
            ┌──────────────────────────────────────────────────────────┐
            │  Fiber app                                               │
            │    1. acquire fiber.Ctx from pool, wrap the RequestCtx    │
            │    2. router match: method + path → handler chain         │
            │       (radix-style route tree, built at registration)     │
            │    3. run middleware → handler chain via c.Next()         │
            │    4. handler returns error?                              │
            │         └─ yes → Config.ErrorHandler                      │
            │    5. write response into the pooled RequestCtx           │
            │    6. release fiber.Ctx back to the pool                  │
            └──────────────────────────────────────────────────────────┘
                                         │
                                         ▼
                                     response → client

The defining characteristic is object reuse: the fiber.Ctx and the underlying *fasthttp.RequestCtx are drawn from a sync.Pool and returned after the handler completes. This is what makes Fiber allocation-light, and it is the reason every value returned by Ctx is valid only within the handler. The timeout middleware interacts with this directly via c.Abandon()/c.ForceRelease() to keep a context alive past a timeout without corrupting the pool.

Core components

Handler model

Fiber's native handler is fiber.Handler = func(c fiber.Ctx) error. The router also adapts, at registration time, several other shapes so they can be mixed freely:

• Express-style: func(req fiber.Req, res fiber.Res) error and 3-argument middleware forms with a next callback.
• net/http: http.Handler and http.HandlerFunc are accepted directly.
• fasthttp: raw fasthttp.RequestHandler callbacks.

Adapted net/http handlers run with standard-library semantics and pay a compatibility cost; native fiber.Handler callbacks are the fastest path.

3. Requirements

Important

Because Fiber relies on unsafe for zero-allocation optimizations, it may lag the very latest Go release. v3 is validated against Go 1.25+. Pin your toolchain accordingly.

4. Configuration Reference

Configuration is passed as a value to fiber.New(config ...Config). Listen-time options are passed to app.Listen(addr, config ...ListenConfig).

app := fiber.New(fiber.Config{
    CaseSensitive: true,
    StrictRouting: true,
    ServerHeader:  "Fiber",
    AppName:       "Test App v1.0.1",
})

fiber.Config — application settings

Note

The CBOR and MsgPack encoders default to unimplemented stubs. You must wire in a real codec (or follow the framework's setup docs) before c.CBOR()/c.MsgPack() and the corresponding binders work. JSON and XML work out of the box.

fiber.ListenConfig — listen-time settings

TLS precedence: TLSConfig wins and ignores CertFile/CertKeyFile/CertClientFile/AutoCertManager/TLSMinVersion/TLSConfigFunc. AutoCertManager cannot be combined with CertFile/CertKeyFile.

5. Middleware Internals

All first-party middleware live under middleware/<name>/ and follow the same pattern: a New(config ...Config) fiber.Handler constructor, a Config struct, and a ConfigDefault that configDefault() merges user overrides onto. Storage-backed middleware (limiter, cache, session, csrf, idempotency) default to an in-process memory store and accept any fiber.Storage implementation (e.g. a gofiber/storage Redis/Postgres driver) for shared/persistent state.

Selected middleware reference

cors — defaults that matter:

limiter — fixed-window by default:

csrf — defaults and a built-in safety check:

Caution

The CSRF middleware panics at startup if you configure an Extractor that reads the token from the same cookie used to store it — that configuration would completely defeat CSRF protection. It also logs a warning when you extract the token from the query string or a route param (URLs may be logged). Keep the default header extractor for APIs, or use extractors.FromForm("_csrf") for HTML forms.

Other notable middleware: helmet (security headers), encryptcookie (AES cookie value encryption, needs a 32-byte key), keyauth/basicauth (auth), idempotency (dedupe unsafe requests by key), healthcheck (liveness/readiness probes), pprof/expvar (diagnostics — keep them off public interfaces), compress (gzip/br/zstd/deflate), etag/cache (conditional/cached responses), proxy (reverse proxy), static (file serving), paginate, requestid, responsetime, hostauthorization, earlydata, sse, timeout, recover, logger, skip, rewrite, redirect, favicon, envvar, adaptor.

6. Security

Fiber gives you the primitives for a secure service, but several defaults favor developer convenience and must be hardened for production. The items below correspond to real, currently-tracked issues in the project.

Trusted proxies and client IP

By default c.IP() returns the TCP remote address. Behind a reverse proxy/CDN, you must opt in to header-based client IP and validate which proxies you trust — otherwise clients can spoof X-Forwarded-For to bypass IP-based controls.

app := fiber.New(fiber.Config{
    TrustProxy: true,
    ProxyHeader: fiber.HeaderXForwardedFor,
    TrustProxyConfig: fiber.TrustProxyConfig{
        Proxies: []string{"10.10.0.58", "192.168.0.0/24"}, // your proxies only
        // or: Private: true / Loopback: true / LinkLocal: true / UnixSocket: true
    },
})

TrustProxyConfig fields: Proxies (IPs/CIDRs), Loopback (127.0.0.0/8, ::1/128), Private (RFC1918 + fc00::/7), LinkLocal (169.254.0.0/16, fe80::/10), UnixSocket. When the remote IP is trusted, Fiber reads c.IP() from ProxyHeader, c.Scheme() from X-Forwarded-Proto (and siblings), and c.Hostname() from X-Forwarded-Host; untrusted peers fall back to the connection values. Enable EnableIPValidation if you need c.IP() to return a single validated IP rather than the raw header chain.

Warning

Setting ProxyHeader without TrustProxy has no effect. Both are required. Never enable TrustProxy with an unrestricted TrustProxyConfig in a hostile network — that re-opens IP spoofing.

Cookie hardening checklist

The session and CSRF middleware ship with Secure=false and HTTPOnly=false cookies by default. For any HTTPS deployment:

• [ ] Session: CookieSecure: true, CookieHTTPOnly: true, an appropriate CookieSameSite.
• [ ] CSRF: CookieSecure: true, CookieHTTPOnly: true.
• [ ] Set explicit cors.Config.AllowOrigins (never ship the "*" default to production).
• [ ] If you set cookies manually, prefer HTTPOnly: true, Secure: true, SameSite: "Lax" (or "Strict").

Important

Fiber forces Secure: true automatically only for SameSite: "None" cookies. For all other cookies you are responsible for setting Secure and HTTPOnly.

Logging and injection

The logger middleware writes user-controlled values (path, headers, user agent) without sanitization, so untrusted input can inject control characters or forged lines into your logs. Sanitize or structure your log sink, and avoid logging raw user input into formats where newlines are significant.

Panics, timeouts, and resource leaks

• Panics are not recovered by default — always mount recover.New(), or a single panic takes down the worker (or, under prefork, restarts a child and counts against PreforkRecoverThreshold).
• The timeout middleware works by abandoning the context and returning early while the handler goroutine continues; long-running handlers behind a timeout can accumulate in-flight goroutines/contexts under load. Bound the work itself (pass c.Context() deadlines into downstream calls), don't rely on the timeout middleware alone to reclaim resources.
• Background goroutines started by your handlers must not capture c; they must use c.Context() and have a shutdown path.

Open redirects

Redirect().Back() falls back to a referer-derived target; validate redirect destinations against an allowlist rather than trusting Referer/user-supplied next parameters.

Prefork security

Prefork changes the port-ownership model from single-owner to multi-listener. On shared hosts a co-resident process could race for binds or receive a share of traffic (platform-dependent). Run prefork only within a single trust boundary, under a dedicated service account, ideally with container/VM isolation. If strict single-owner port semantics are required, do not use prefork.

Diagnostics exposure

pprof, expvar, and envvar middleware expose internal runtime data. Never mount them on a public interface — bind them to an internal admin port or guard them behind auth.

7. Performance Tuning

Fiber's speed comes from fasthttp and the pooled-context model. Tuning is mostly about not undoing those wins and about matching buffers/timeouts to your traffic.

• Keep handlers allocation-light. Do not retain Ctx values; copy only when necessary. Leave Immutable off unless you specifically need retained values — it adds per-call cost.

• Buffers. Raise ReadBufferSize if clients send large headers/cookies/URIs (it also caps max header size). Raise WriteBufferSize for large responses.

• Timeouts. The defaults are unlimited (ReadTimeout/WriteTimeout = 0). Set them in production to bound slow-client and slow-loris exposure.

• Concurrency. Concurrency (default 256K) caps simultaneous connections; tune with ReduceMemoryUsage if memory-constrained.

• Direct fasthttp tuning. For knobs Fiber does not surface, reach the server directly:

  app := fiber.New()
  app.Server().MaxConnsPerIP = 100
  app.Server().MaxRequestsPerConn = 1000
  

• Prefork for CPU-bound throughput on multi-core hosts. Each child runs effectively GOMAXPROCS=1, reducing cross-core runtime overhead. Remember: no shared in-process memory between children — use app.SharedState() or external storage. Distinguish processes with fiber.IsChild().

• Compression (compress middleware) trades CPU for bandwidth; SendFile can cache compressed variants (Compress: true, suffixes from CompressedFileSuffixes).

• Custom JSON codec. Swap in a faster JSON library via Config.JSONEncoder/JSONDecoder if encoding dominates your profile.

The project tracks several performance issues worth knowing: storage-backed middleware (limiter, cache, session) share a global mutex that can serialize under high concurrency, and the binder allocates per-request maps. If you run at very high RPS with these middleware, benchmark them specifically and consider sharded/external storage.

8. Operations

Graceful shutdown

go func() {
    sigint := make(chan os.Signal, 1)
    signal.Notify(sigint, os.Interrupt, syscall.SIGTERM)
    <-sigint
    if err := app.ShutdownWithTimeout(10 * time.Second); err != nil {
        log.Printf("graceful shutdown failed: %v", err)
    }
}()

if err := app.Listen(":3000"); err != nil {
    log.Fatal(err)
}

Shutdown() waits indefinitely for connections to drain; ShutdownWithTimeout force-closes after the deadline; ShutdownWithContext ties drain to a context. Shutdown hooks (registered via app.Hooks()) always run, even on error. Alternatively set ListenConfig.GracefulContext.

Health checks

Mount the healthcheck middleware for orchestrators (Kubernetes liveness/readiness, load-balancer probes):

import "github.com/gofiber/fiber/v3/middleware/healthcheck"

app.Get("/livez", healthcheck.NewHealthChecker())
app.Get("/readyz", healthcheck.NewHealthChecker(healthcheck.Config{
    Probe: func(c fiber.Ctx) bool { return dbIsReachable() },
}))

Observability

• Request logging: logger.New() (sanitize inputs — see §6).
• Request IDs: requestid.New() adds a correlation ID; read it with c.RequestID().
• Profiling: pprof.New() exposes Go profiles (internal interface only).
• Runtime vars: expvar.New() for expvar-format metrics (internal only).
• Response time: responsetime.New() writes handling duration to a header.

Inspecting the running app

app.Stack() returns the full route tree; app.GetRoutes() lists routes (pass true to exclude middleware-registered routes); app.HandlersCount() returns the handler count. These are useful for startup audits and admin endpoints.

Caution

Runtime route mutation — app.RebuildTree(), app.RemoveRoute(), app.RemoveRouteByName(), app.RemoveRouteFunc() — is not thread-safe and is performance-intensive. Use it only in development, never concurrently with live traffic.

9. Repository Structure (for Contributors)

fiber/
├── app.go              App, Config, TrustProxyConfig, lifecycle
├── ctx.go              DefaultCtx — the context implementation
├── ctx_interface.go    The Ctx interface (+ generated ctx_interface_gen.go)
├── req.go / res.go     Request / Response method groups (+ *_interface_gen.go)
├── router.go           Route tree, matching, Route struct
├── path.go             Route parsing, segments, constraints
├── bind.go             Bind entrypoint and BindError
├── group.go            Group / sub-router
├── domain.go           Hostname-scoped routing
├── listen.go           Listen, Listener, ListenConfig, startup banner
├── prefork.go          Multi-process serving
├── hooks.go            Lifecycle hooks
├── redirect.go         Redirect + flash messages (+ msgp codecs)
├── state.go            In-process State
├── shared_state.go     Storage-backed SharedState (prefork-safe)
├── services.go         Service lifecycle management
├── error.go            fiber.Error + predefined ErrXxx
├── helpers.go          Internal helpers, generic parsers
├── color.go            Color scheme
├── constants.go        HTTP methods, headers, MIME, status codes
├── binder/             json, xml, form, query, header, cookie, uri, cbor, msgpack binders
├── client/             fasthttp-backed HTTP client (request, response, hooks, cookiejar, transport)
├── extractors/         Token extractors (FromHeader/Form/Query/Param/Chain) — used by csrf/keyauth
├── log/                Pluggable logging facade
├── middleware/         ~30 first-party middleware packages
├── internal/           memory store, storage adapters, redaction, tls test helpers
└── docs/               Docusaurus documentation source (api/, guide/, middleware/)

Extraction note for maintainers/tooling: Fiber is a pure library with no CLI and no HTTP route registry of its own, so AST/regex extraction of "commands", "endpoints", and "config keys" yields essentially nothing (the framework's only os.Getenv read is TERM in the startup banner). The real surfaces are the public method sets of App and Ctx, the Config/ListenConfig structs, the per-middleware Config structs, and the struct tags the binder consumes (json/xml/form/query/header/cookie/uri/msgpack/validate/default). Document from those, not from any extracted table.

Code generation

Several files are generated (*_interface_gen.go, *_msgp.go). The Req/Res interfaces are generated from the Ctx method set; the *_msgp.go files are MessagePack codecs produced by tinylib/msgp for internal structs (redirect data, cache/limiter/idempotency/session entries). Regenerate via the Makefile targets — do not hand-edit generated files.

Contributing workflow

The Makefile exposes the standard quality gates:

make help        # list commands
make format      # gofumpt / formatting
make lint        # golangci-lint (config in .golangci.yml)
make test        # full test suite
make coverage    # coverage report
make benchmark   # benchmarks
make audit       # combined quality checks
make tidy        # go mod tidy

Run make audit before opening a PR. The repo enforces lint (.golangci.yml), spell-check (.cspell.json), and markdown lint (.markdownlint.yml).

10. Testing Strategy

Fiber apps are tested without binding a socket using app.Test(req *http.Request, config ...TestConfig), which drives the full router/middleware stack against an *http.Request and returns an *http.Response:

func TestRoot(t *testing.T) {
    app := fiber.New()
    app.Get("/", func(c fiber.Ctx) error { return c.SendString("hello") })

    req := httptest.NewRequest("GET", "http://example.com/", nil)
    resp, err := app.Test(req)
    if err != nil {
        t.Fatal(err)
    }
    if resp.StatusCode != fiber.StatusOK {
        t.Fatalf("got %d", resp.StatusCode)
    }
}

TestConfig defaults to {Timeout: time.Second, FailOnTimeout: true}. Pass fiber.TestConfig{Timeout: 0} to disable the timeout (for streaming/long handlers).

Warning

app.Test(req) (no config) uses the 1-second default. Passing an empty fiber.TestConfig{} is not the same — it means Timeout: 0, FailOnTimeout: false (no timeout at all). Be explicit when overriding.

The framework's own suite mirrors the source layout (*_test.go next to each file), including fuzz tests (helpers_fuzz_test.go), security tests (middleware/cache/cache_security_test.go), and per-middleware tests. Aim for the same: a test file beside each unit, exercising both success and error paths through app.Test.

11. Known Issues & Improvement Areas

These are tracked in the project at this commit and are useful for risk assessment and contribution:

Improvement directions the maintainers are pursuing: sharding the memory store and idempotency locker to reduce lock contention, narrowing client hook lock scope, unifying internal and custom route constraints behind one interface, and reducing binder allocations.

12. Quick Reference

Create & serve

app := fiber.New(fiber.Config{ /* ... */ })
app.Listen(":3000")
app.Listen(":443", fiber.ListenConfig{CertFile: "c.pem", CertKeyFile: "k.pem"})
app.Listen(":8080", fiber.ListenConfig{EnablePrefork: true})
app.ShutdownWithTimeout(10 * time.Second)

Routing

app.Get/Post/Put/Patch/Delete/Head/Options(path, handler)
app.All(path, handler)              app.Add([]string{...}, path, handler)
app.Group(prefix, mw...)            app.Route(prefix, fn, name...)
app.RouteChain(path).Get(h).Post(h) app.Domain(host).Get(path, h)
app.Use(mw)  app.Use(prefix, mw)    app.Use(prefix, subApp)  // mount

Context (selected)

c.Params/Query/Get/Cookies(key)     c.Body()/BodyRaw()  c.IP()/IPs()
c.Bind().Body/JSON/Query/URI/Header/Cookie/All(&v)
c.JSON/XML/CBOR/MsgPack(v)  c.SendString/Send/SendFile/Download/Render
c.Status(code).SendString(...)  c.SendStatus(code)  c.Set(k,v)  c.Cookie(&Cookie{})
c.Next()  c.Locals(k, v)  c.Context()  c.RequestCtx()  c.Redirect().To(path)

Introspection / lifecycle

app.Stack()  app.GetRoutes(true)  app.HandlersCount()  app.Config()
app.Server()  app.Handler()  app.Hooks()  app.State()  app.SharedState()
fiber.NewError(code, msg)  fiber.IsChild()  app.Test(req, cfg...)

Must-have production middleware

app.Use(recover.New())
app.Use(logger.New())
app.Use(cors.New(cors.Config{AllowOrigins: []string{"https://you.example"}}))
app.Use(limiter.New(limiter.Config{Max: 100, Expiration: time.Minute}))
// + TrustProxy config, hardened session/csrf cookies, healthcheck probes