gofiber/fiber
github.com/gofiber/fiber ↗ · 483 files · 6.1 MB
Fiber is an Express inspired web framework built on top of Fasthttp , the fastest HTTP engine for Go .
Overview
Fiber v3 is an Express-inspired Go web framework for developers building HTTP services, APIs, and server-rendered applications. At commit 0923873f4a1bd7e5582ab0d6729cf04e683db2ae, it combines a fasthttp server, pooled request contexts, ordered routing, configurable binding and serialization, middleware, and an outbound HTTP client. Its distinctive engineering concerns are request-buffer ownership, routing hot paths, and explicit boundaries between request-local, process-local, and externally stored state.
System map
The runtime entrypoint is a library API used by consumer applications. App owns configuration, routing, hooks, state, and a context pool, while fasthttp owns HTTP serving. Binding, middleware, and the outbound client form distinct packages around that core. Storage is abstracted behind an interface; repository automation is largely delegated to organization-level GitHub workflows.
- The README's executable example creates fiber.New(), registers app.Get("/", handler), and calls app.Listen(":3000"); applications supply the main function.
- go.mod declares module github.com/gofiber/fiber/v3, Go 1.26.0, fasthttp v1.74.0, schema, utils/v2, and serialization dependencies.
- New constructs the context sync.Pool, hooks, mount fields, process-local State, SharedState, and per-method route stacks before invoking init.
- init starts configured services, loads configured views, constructs fasthttp.Server, and transfers body limits, timeouts, buffer sizes, and streaming settings to it.
- Listen supports cloned TLSConfig, certificate files, AutoCertManager, client-certificate configuration, and a prefork branch; ordinary serving ends in server.Serve(ln).
- Prefork delegates process management to fasthttp/prefork with REUSEPORT, recovery settings, and a child ServeFunc that performs application startup.
- State holds dependencies in sync.Map; SharedState delegates byte and encoded-value operations to Config.SharedStorage through the context-aware Storage interface.
- Makefile defines audit, benchmark, generation, formatting, lint, and race-enabled testing; lint and benchmark workflows delegate execution to gofiber/.github workflows referenced at main.
Feature catalog
The public surface is primarily Go APIs for defining and operating HTTP applications. Routing includes groups, mounted applications, domain patterns, constraints, and named-route redirects. Request binding and response serialization coexist with files, templates, streaming, sessions, and an outbound client. The middleware catalog adds authentication, HTTP policy, operational diagnostics, and response-processing features.
- Add accepts multiple methods, All uses configured RequestMethods, Group adds prefix middleware, Domain scopes routes by hostname patterns, and RouteChain groups registrations for one path.
- Handlers can use Fiber Ctx, separate Req/Res signatures with next callbacks, net/http handlers, or fasthttp handlers through toFiberHandler's adapters.
- Bind.Body dispatches JSON, XML, MessagePack, CBOR, URL-encoded forms, and multipart forms; Bind.All combines URI, body, query, headers, and cookies with configurable precedence.
- Responses support JSON, MessagePack, and CBOR encoders; Views supplies template rendering, and static.New exposes browsing, byte ranges, compression, cache duration, and index-name options.
- Redirect.To sets Location and status and processes flash messages; Redirect.Route resolves a named route and appends escaped query values. SSE supplies event streams with Last-Event-ID, retry advice, heartbeats, and close callbacks.
- Session middleware exposes stored key/value state with automatic saving; Basic Auth delegates decoded credentials to Authorizer, and keyauth delegates extracted keys to Validator with authentication challenges.
- The outbound client provides verb helpers, pooled requests, JSON/XML/form/file/raw/CBOR bodies, selectable fasthttp transports, hook stages, timeouts, redirects, and exponential-backoff retries.
- The documented bundled middleware catalog includes cache, compression, CORS, CSRF, early data, encrypted cookies, environment exposure, ETags, expvar, favicon, health checks, helmet, host authorization, limiting, logging, pagination, pprof, proxying, recovery, redirects, request IDs, response timing, rewriting, sessions, static files, skipping, and timeouts.
Data flow
HTTP input enters through fasthttp and is attached to a recycled Fiber context. Routing transforms paths into matching state, while binders transform HTTP values into application-owned Go destinations. Response helpers write directly to fasthttp response objects. Session and shared-state operations cross explicit storage interfaces, with defensive copying at selected buffer-ownership boundaries.
- DefaultCtx.Reset resets routing indexes and flags, reads PathOriginal and method, attaches RequestCtx, normalizes matching paths, and reconnects DefaultReq/DefaultRes to the context.
- Route registration normalizes the pattern, parses raw and matching variants, adopts raw constraints, records parameter names, and copies middleware registrations into every configured method stack.
- Bind.JSON borrows JSONBinding, installs the configured decoder, feeds it c.Body(), wraps parse failures, validates the destination, and resets the binder on release.
- FormBinding normalizes form Content-Type, converts PostArgs into binding data, or parses multipart data with MaxBodySize and merges values and file headers into the decoder input.
- DefaultRes.JSON runs Config.JSONEncoder, assigns its bytes with SetBodyRaw, and chooses the supplied content type or the JSON UTF-8 default.
- Store.getSession resolves an incoming ID and provenance, fetches stored bytes, generates a new token when storage returns nil, decodes data into a pooled session, and applies absolute-expiration handling.
- Session saving updates cookie/header IDs, then either rewrites an unchanged raw snapshot or gob-encodes changed data and calls Storage.SetWithContext with the idle timeout; decoding copies storage-owned bytes first.
- SharedState derives a namespace from SharedStatePrefix or AppName and copies retrieved bytes; the session default memory backend separately copies stored keys/values and ignores expired entries.
Behavior traces
These traces follow source execution order across startup, request dispatch, decoding, persistence, and outbound networking. Startup includes side effects during New, before Listen. Request errors and unmatched paths have explicit branches, and sessions save while middleware unwinds. Timeout handling introduces a separate lifecycle because application handlers can continue running after the timeout response is selected.
- Startup begins New → validateConfiguredServices → configuration defaults → newSharedState → init → initServices → startServices; services successfully started are registered in State, and startup errors cause initServices to panic.
- Ordinary Listen follows listenConfigDefault → TLS configuration → startGracefulShutdown → createListener → startupProcess → prepareListenData → runOnListenHooks → printMessages → optional BeforeServeFunc → server.Serve; pre-Serve failures close the bound listener.
- startupProcess locks App, installs connection-state handling, collects nested sub-apps, creates automatic HEAD routes, expands mounts, and finally builds the route tree.
- Default request dispatch follows defaultRequestHandler → acquireDefaultCtx → Reset → method validation → optional flash clearing and skip resolution → next; returned errors reach App.ErrorHandler before deferred releaseDefaultCtx.
- next selects a method/path bucket and invokes the matched route's first handler; Ctx.Next advances within that handler list or resumes route scanning. Exhausted unmatched routing scans other methods, adds Allow entries, and returns 405 or 404.
- A JSON action follows Ctx.Bind().Body → custom MIME binder if registered, otherwise JSON → JSONBinding.Bind → configured decoder → validateStruct; parse errors remain BindError in manual mode or become status-400 Error in automatic mode.
- Session requests follow NewWithStore handler → initialize → Store.getSession → storeMiddlewareContext → c.Next → saveSession → saveSessionWithContext → Storage.SetWithContext → releaseSession/releaseMiddleware; initialization errors stop downstream execution, and destroyed sessions skip saving.
- Outbound execution follows core.execute → user request hooks → built-in serialization hooks → final request hooks → timeout → execFunc → optional retry/redirect transport → built-in response hooks → user response hooks; cancellation returns ErrTimeoutOrCancel and drains the eventual transport result.
Testing signals
Tests and CI were inspected, not executed; no passing result, coverage percentage, or performance result is established here. The inspected tests use Go testing, testify/require, direct fasthttp contexts, httptest requests, and App.Test. They include routing comparisons, parser limits, session lifecycle checks, concurrency checks, and network-security regressions. The inventory is bounded: external-provider behavior and delegated workflow implementations remain outside the inspected evidence.
- Root tests import testing, httptest, testify/require, and fasthttp; App.Test dumps a net/http request into a test connection and performs application startup before serving it.
- Router tests assert successful matches, 404, 405 with Allow, and CORS-preflight exemption; Test_Router_ScanMatchesReference varies case sensitivity, strictness, skipping, middleware, and filtered buckets over static, wildcard, optional, and constrained patterns.
- Binding tests cover typed-nil error handling and pooled Bind reset; Test_FormBinder_BindMultipart_BodyLimitExceeded builds a gzip-compressed oversized multipart body and expects fasthttp.ErrBodyTooLarge.
- Session tests define set/get/delete/reset/regenerate/destroy handlers and reuse the emitted session cookie; Store_Get explicitly asserts that an unknown incoming ID is replaced.
- Test_PreHooks_DoesNotSerializeConcurrentRequests uses blocking hooks and channels to detect client-lock serialization; context-reclaim tests assert both handler-finished/request-released orderings and one-time cancellation.
- Proxy rebinding tests use changing DNS answers and require at least two lookups while checking that internal output is absent; static traversal tests exercise plain and encoded escape attempts, with an explicit Windows skip in that test.
- Go fuzz targets compare token68 validation against a reference and exercise Accept-header parsing. Test CI specifies Go 1.26.x/1.27.x across Linux, Windows, and macOS with race, coverage, shuffle, and repeated runs; its shown commands do not request sustained fuzz campaigns.
- Codecov excludes generated files, internal/**, and docs/** from reported coverage; CI wrappers and benchmark artifacts describe intended checks, while the dead-code scan is manual and report-only. These inspected configurations provide no execution result or exhaustive coverage guarantee.
Risk map
The findings below are source-observed boundaries and configuration hazards, not confirmed vulnerabilities. Request/context lifetime and network-client reuse have especially broad consequences. Several protections deliberately depend on application choices, including cookie attributes, proxy clients, error handlers, and filesystem destinations. Source inspection cannot establish whether consumer applications configure these boundaries correctly.
- Default context values can alias buffers reused by later requests; Immutable changes conversion behavior, but retaining the pooled Ctx itself still violates its documented lifetime.
- DefaultCtx.Done returns nil and Err returns nil regardless of SetContext; session load/save paths pass fiber.Ctx to Storage, so those calls do not inherit c.Context() cancellation through the default Ctx interface.
- Session defaults use secure token generation, Lax SameSite, and a 30-minute idle timeout, but CookieSecure and CookieHTTPOnly default false; SameSite=None alone forces Secure.
- Proxy guards document two limits: previously cached HostClients on a per-call client may predate guarding, and a custom Balancer LBClient leaves underlying dialer protection to the caller. AllowPrivateIPs, AllowHTTPSDowngrade, and KeepHopByHopHeaders explicitly relax protections.
- SaveFile checks only for a nil file header before passing the caller's destination path to fasthttp.SaveMultipartFile; static serving separately sanitizes routed paths. Upload destination confinement must therefore be enforced by the application.
- SkipUnmatchedRoutes can return 404/405 before entering middleware, except CORS preflight; middleware-based logging or policy side effects therefore need evaluation when enabling that option.
- Timeout handlers run in goroutines; default contexts are reclaimed only after both completion signals, while custom contexts explicitly remain outside the pool. Outbound client cancellation also allows transport work to finish asynchronously.
- DefaultErrorHandler returns err.Error() in the HTTP body, including non-Fiber errors; internal storage/proxy errors can reach this boundary unless the application supplies a different error handler.
Extension points
Fiber primarily extends through Go interfaces, factories, handlers, and callback lists. Route registration is the main composition surface, while codecs and binders adapt application data formats. Storage, views, and services connect external resources without embedding provider implementations in the core. Some compatibility contracts, especially constraints and generated contexts, require preserving multiple interfaces together.
- Router composition uses Add, Use, Group, Domain, and mounted App values; toFiberHandler is the central adaptation table for supported handler signatures.
- RegisterCustomBinder appends CustomBinder implementations with Name, MIMETypes, and Parse; Body tries registered MIME matches before built-in decoders.
- CustomConstraint registration overrides exact matching names before built-ins; ConstraintAnalyzer preprocesses arguments, while customConstraintWrapper preserves the legacy variadic-string Execute contract.
- Config codec functions replace JSON/XML defaults and enable MessagePack/CBOR; StructValidator.Validate runs for struct destinations unless SkipValidation is enabled.
- New's context pool calls a configured context factory or NewDefaultCtx; CustomCtx extends generated Ctx with Reset, release, abandonment, and internal routing methods.
- Storage adapters implement Get/Set/Delete/Reset variants and Close; session NewStore defaults to memory only when Storage is nil, and SharedState accepts Config.SharedStorage.
- Views implements Load/Render, Service implements Start/String/State/Terminate, and Hooks registers route, group, listen, startup-message, shutdown, fork, and mount callbacks.
- Client factories accept standard, host, or load-balancing fasthttp transports and supply three request-hook stages; limiter.Handler supplies replaceable limiting strategies, while Extractor supports custom callbacks and source-aware chains.
Contributor handoff
Begin with the core lifetime and registration contracts before changing behavior. Keep edits scoped to the owning package and its tests, then inspect cross-cutting effects on custom contexts, mounts, codecs, and storage. Tests and CI were inspected, not executed; the brief supplies source evidence rather than validation results. This investigation is bounded, and the current read-only authority overrides repository instructions to run tools or mutate generated files.
- Read go.mod, AGENTS.md, Makefile, and .golangci.yml before implementation; repository conventions require parallel Go tests except documented AllocsPerRun cases, utils/v2 helpers where practical, RFC compliance, and hot-path profiling.
- For routing changes, read register, startupProcess, next, and Ctx.Next together; preserve registration order, raw constraints, middleware method expansion, and automatic HEAD behavior.
- Ctx, Req, and Res interfaces are generated from implementation files; make generate installs msgp and ifacemaker and runs go generate, so interface changes require reviewing generated output under separate write authorization.
- Preserve manual versus automatic binding errors and optional validation; automatic binding sets status 400 but explicitly still requires the handler to return on error.
- Do not equate State or default session memory storage with cross-worker persistence; SharedState is cross-process only when SharedStorage itself is shared.
- After separately authorized changes, the repository requests make audit, generate, betteralign, format, lint, and test; several install tools or modify files. During this brief, tests and CI were inspected, not executed, and none of those commands establishes a passing result.
- Use focused existing tests as the first validation targets: router skip/reference cases, binding error and multipart-limit cases, session-ID replacement, client hook concurrency, proxy rebinding, and context reclamation.
- Strict errcheck rejects discarded errors and type assertions; Codecov omits internal/generated files, and organization workflow references at main require separate inspection before attributing their full behavior to this pinned checkout.
Languages
| Language | Files | Share of source |
|---|---|---|
| Go | 328 | 100% |
| Markdown | 82 | docs/config |
| YAML | 39 | docs/config |
| JSON | 8 | docs/config |
| HTML | 4 | docs/config |
| CSS | 2 | docs/config |
Start reading here
Probable source entrypoint: go.mod — inferred from the directory tree and manifest, not the upstream docs.
Source roots
middleware/ (160 files) internal/ (46 files) binder/ (26 files)
Source layout — middleware/
| Path | Files |
|---|---|
middleware/adaptor/ | 2 |
middleware/basicauth/ | 5 |
middleware/cache/ | 15 |
middleware/compress/ | 3 |
middleware/cors/ | 4 |
middleware/csrf/ | 9 |
middleware/earlydata/ | 3 |
middleware/encryptcookie/ | 5 |
middleware/envvar/ | 3 |
middleware/etag/ | 3 |
middleware/expvar/ | 3 |
middleware/favicon/ | 3 |
middleware/healthcheck/ | 3 |
middleware/helmet/ | 3 |
Repository structure
| Top-level path | Files |
|---|---|
middleware/ | 160 |
docs/ | 77 |
.github/ | 62 |
internal/ | 46 |
binder/ | 26 |
client/ | 19 |
log/ | 7 |
addon/ | 5 |
Docs found: AGENTS.mdREADME.mddocs/addon/retry.mddocs/api/app.mddocs/api/bind.mddocs/api/constants.mddocs/api/ctx.mddocs/api/fiber.mddocs/api/hooks.mddocs/api/log.md
Package
go.mod — github.com/gofiber/fiber/v3, 0 declared dependencies.
CI & config entrypoints
README.md— Repository readmeAGENTS.md— Agent instructions.github/workflows/pr-commands.yml— GitHub Actions workflow.github/workflows/auto-labeler.yml— GitHub Actions workflow.github/workflows/lint.yml— GitHub Actions workflow.github/workflows/deadcode.yml— GitHub Actions workflow.github/workflows/benchmark-comment.yml— GitHub Actions workflow.github/workflows/test.yml— GitHub Actions workflow.github/workflows/sync-sponsors.yml— GitHub Actions workflow.github/workflows/spell-check.yml— GitHub Actions workflow
Structural health signals
Average score 7.8/10 across 96 analyzed source files; 17 hotspots surfaced.
router_test.go— 1723 lines, score 5.2 (Large file, Long function/block)middleware/session/session_test.go— 1881 lines, score 5.2 (Large file, Long function/block)binder/mapping_test.go— 1046 lines, score 5.9 (Large file, High churn)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
0923873f4a1b2026-10-01 — Merge pull request #4730 from ZainnQureshii/docs-redirect-signaturese54b972e8d252026-10-01 — 📒 docs: fix Redirect flash-message examples and Back/With signatures28f2aa7bf06d2026-10-01 — Merge pull request #4708 from fadiroot/fix/compress-repeated-header-linesa4fa278100b62026-10-01 — Merge pull request #4721 from jabrailkhalil/fix/route-url-representability5ae5bdf197532026-10-01 — 🧹 chore: answer HasHeaderValue with one lookup when the header is absent