Fiber — Structure#

Layout pattern#

Framework-specific / Flat with nested feature dirs

Fiber does not follow the conventional cmd/internal/pkg Go layout. There is no cmd/ directory — Fiber is purely a library. The root package is the framework itself (all core files live at the module root as package fiber). Feature domains are broken out into top-level subdirectories (binder/, client/, middleware/, etc.) each with their own package. This flat-library-at-root + feature-subpackage layout is characteristic of web framework projects (similar to Echo or Gin).

Directory map#

repositories/fiber/
├── *.go                  — Core framework package (fiber): App, Ctx, Router, Group, etc.
├── addon/
│   └── retry/            — Retry middleware addon with exponential backoff
├── binder/               — Request body/param binding (JSON, XML, CBOR, form, query, header, cookie, msgpack, URI)
├── client/               — Built-in HTTP client (request, response, transport, cookiejar, hooks)
├── docs/                 — Docusaurus documentation source (not Go)
│   ├── addon/
│   ├── api/
│   ├── client/
│   ├── extra/
│   ├── guide/
│   └── middleware/
├── extractors/           — Single-file package for extracting values from Ctx (used by middleware)
├── internal/
│   ├── memory/           — Internal in-memory storage implementation
│   ├── storage/          — Internal storage interface wrapper (used by middleware)
│   └── tlstest/          — TLS test helper certificates
├── log/                  — Logging abstraction (log.go interface + fiberlog.go + default.go)
├── middleware/            — 30 production-ready middleware packages (one subdir each):
│   ├── adaptor/          — net/http ↔ Fiber bridge
│   ├── basicauth/
│   ├── cache/
│   ├── compress/
│   ├── cors/
│   ├── csrf/
│   ├── earlydata/
│   ├── encryptcookie/
│   ├── envvar/
│   ├── etag/
│   ├── expvar/
│   ├── favicon/
│   ├── healthcheck/
│   ├── helmet/
│   ├── idempotency/
│   ├── keyauth/
│   ├── limiter/
│   ├── logger/
│   ├── paginate/
│   ├── pprof/
│   ├── proxy/
│   ├── recover/
│   ├── redirect/
│   ├── requestid/
│   ├── responsetime/
│   ├── rewrite/
│   ├── session/
│   ├── skip/
│   ├── static/
│   └── timeout/
├── .github/
│   └── workflows/        — CI (test, lint, benchmark, CodeQL, vuln, docs sync)
├── Makefile              — Build, test, lint, coverage, generate targets
└── go.mod / go.sum

Entry points#

There are no cmd/ binaries. Fiber is a pure library framework. Users import github.com/gofiber/fiber/v3 and call fiber.New() in their own application’s main.go.

The effective entry point for library users is:

  • app.go — New(config ...Config) *App — creates and configures an App instance
  • listen.go — (*App).Listen(addr string, ...) — starts the HTTP server (wraps fasthttp)
  • prefork.go — (*App).prefork(...) — alternative multi-process start via SO_REUSEPORT

Package organization#

  • Internal packages (internal/):

    • internal/memory — In-process cache/storage map used by middleware like cache and session
    • internal/storage — Thin wrapper around the Storage interface for middleware that accepts pluggable storage backends
    • internal/tlstest — Pre-generated TLS certs for integration tests only

  • Public packages (non-root):

    • binder/ — All request-binding logic (decoupled from core Ctx); supports JSON, XML, CBOR, form, query, header, cookie, URI, msgpack
    • client/ — Full HTTP client implementation (request builder, response, transport, cookiejar, lifecycle hooks)
    • extractors/ — Tiny utility for extracting token/key values from Ctx; used by auth middleware
    • log/ — Logger interface (log.CommonLogger) and Fiber-specific default adapter
    • addon/retry/ — Retry wrapper with exponential backoff (uses the Handler type from root)
    • middleware/* — 30 self-contained middleware packages, each with its own Config struct and New() constructor

  • Root package (fiber): The core of the framework — all primary types live here:

    • app.go — App struct + Config + constructor
    • router.go — Router interface + radix tree route matching
    • ctx.go — DefaultCtx struct (fasthttp wrapper) implementing Ctx
    • ctx_interface_gen.go — Generated Ctx interface (via ifacemaker)
    • req.go / req_interface_gen.go — Request abstraction + generated Req interface
    • res.go / res_interface_gen.go — Response abstraction + generated Res interface
    • group.go — Group struct implementing Router for route grouping
    • register.go — Register interface + Registering struct for method-chained route builder
    • bind.go — Bind struct bridging binder subpackage into Ctx
    • hooks.go — Application lifecycle hooks (OnRoute, OnListen, OnShutdown, OnFork)
    • mount.go — App mounting/sub-app composition
    • domain.go — Domain-based routing support
    • services.go — Service interface for managed long-running app services
    • state.go — State map for app-level key/value store
    • listen.go — Server listen/shutdown logic
    • prefork.go — Multi-process forking via SO_REUSEPORT
    • path.go — Route path parser and parameter extraction
    • error.go — Error type + NewError + DefaultErrorHandler
    • storage_interface.go — Public Storage interface definition
    • adapter.go — Low-level fasthttp ↔ net/http request/response adaption
    • helpers.go — Misc utility functions
    • color.go — Terminal color helpers for startup banner
    • constants.go — HTTP status codes, MIME types, method constants
    • redirect.go / redirect_msgp.go — Redirect response helpers with msgpack-encoded state

  • Layering:

    • The root fiber package is the hub; all subpackages (binder, log, client, middleware) depend on it — they import fiber.Ctx, fiber.Handler, fiber.App, etc.
    • Reverse dependency is prevented: the root never imports its own middleware or client packages.
    • internal/ packages are used by both root and middleware but are not exported.
    • There is no strict “domain model” or “service layer” separation — Fiber is a framework, not an application, so the layering is handler → middleware → core App/Router/Ctx rather than business layers.

Build system#

  • Build tool: make (GNU Make, Makefile at root)
  • Key targets:
    • make test — Run all tests with gotestsum (race, shuffle)
    • make longtest — Run all tests 15x (race, shuffle) for flakiness detection
    • make benchmark — Run benchmarks
    • make lint — golangci-lint v2
    • make coverage — Race-enabled coverage with HTML report
    • make generate — Regenerate *_msgp.go and *_interface_gen.go files (via msgp + ifacemaker)
    • make audit — go mod verify + govulncheck
    • make format — gofumpt
    • make betteralign — Optimize struct field alignment
  • Docker: No Dockerfile in the repository (it’s a library, not a deployable service)
  • CI: GitHub Actions workflows for tests, linting, benchmarks, CodeQL analysis, vulnerability scanning, and documentation sync

Notable structural decisions#

  1. Root-as-core, not cmd-as-core: All framework types are in the root fiber package rather than a pkg/fiber or internal/core location. This means the import path is github.com/gofiber/fiber/v3 — clean and idiomatic for a library, but puts substantial code surface at the module root.

  2. Generated interfaces (*_interface_gen.go): Ctx, Req, and Res are defined as generated interfaces via ifacemaker. This allows mock implementations for testing and stable API contracts without hand-writing boilerplate. It’s an unusual but pragmatic pattern — the generator is declared as a dependency in the generate Makefile target.

  3. Middleware as first-class citizens in the monorepo: Rather than separate repositories per middleware (like some frameworks), Fiber bundles 30+ middleware packages in the same repo. Each has its own package and test suite. This ensures version cohesion but means the repo is substantially larger than the core framework alone.

  4. Bundled HTTP client: The client/ package is a full HTTP client alongside the server. This is unusual — most frameworks only solve the server side. Fiber bundles client functionality to share serialization infrastructure and provide a symmetric API for request/response handling.

  5. No dependency injection framework: There is no Wire, Dig, or Fx usage. The services.go Service interface is a lightweight managed-lifecycle pattern, and app-level state is handled by the State map. Fiber is explicitly anti-framework-within-a-framework for DI.

Backward Fiber — Overview Fiber — Dependencies Forward