π£ Hooks
Fiber lets you run custom callbacks at specific points in the routing lifecycle. Available hooks include:
- OnRoute
- OnName
- OnGroup
- OnGroupName
- OnListen
- OnPreStartupMessage/OnPostStartupMessage
- OnFork
- OnPreShutdown
- OnPostShutdown
- OnMount
Hooks of one kind run in the order you registered them. At startup, OnListen runs first, then OnPreStartupMessage, the banner and OnPostStartupMessage. At shutdown, OnPreShutdown runs before the server drains its connections and OnPostShutdown after. A GracefulContext that is done while the app is still starting up starts the shutdown as soon as the app has its listener, so the two sequences can overlap: the shutdown hooks can run while the startup hooks are still running, also for a context that was already done when Listen was called (see Server Shutdown). What a returned error does depends on the hook; see Errors returned by hooks.
Constantsβ
// Handlers define functions to create hooks for Fiber.
type OnRouteHandler = func(Route) error
type OnNameHandler = OnRouteHandler
type OnGroupHandler = func(Group) error
type OnGroupNameHandler = OnGroupHandler
type OnListenHandler = func(ListenData) error
type OnForkHandler = func(int) error
type OnPreStartupMessageHandler = func(*PreStartupMessageData) error
type OnPostStartupMessageHandler = func(*PostStartupMessageData) error
type OnPreShutdownHandler = func() error
type OnPostShutdownHandler = func(error) error
type OnMountHandler = func(*App) error
OnRouteβ
Runs after each route is registered. The callback receives the route so you can inspect its properties.
A registration that covers several methods runs the hook once per method: Add runs it once for each method it lists, and Use and All once for each entry of RequestMethods. Fiber also runs it for every HEAD route it generates for a GET route, which happens when the app starts or when RebuildTree runs.
func (h *Hooks) OnRoute(handler ...OnRouteHandler)
OnNameβ
Runs when a route is named. The callback receives the route.
OnName only works with named routes, not groups.
func (h *Hooks) OnName(handler ...OnNameHandler)
- OnName Example
package main
import (
"fmt"
"github.com/gofiber/fiber/v3"
)
func main() {
app := fiber.New()
app.Get("/", func(c fiber.Ctx) error {
return c.SendString(c.Route().Name)
}).Name("index")
app.Hooks().OnName(func(r fiber.Route) error {
fmt.Print("Name: " + r.Name + ", ")
return nil
})
app.Hooks().OnName(func(r fiber.Route) error {
fmt.Print("Method: " + r.Method + "\n")
return nil
})
app.Get("/add/user", func(c fiber.Ctx) error {
return c.SendString(c.Route().Name)
}).Name("addUser")
app.Delete("/destroy/user", func(c fiber.Ctx) error {
return c.SendString(c.Route().Name)
}).Name("destroyUser")
app.Listen(":5000")
}
// Results:
// Name: addUser, Method: GET
// Name: destroyUser, Method: DELETE
OnGroupβ
Runs after each group is registered. The callback receives the group.
func (h *Hooks) OnGroup(handler ...OnGroupHandler)
OnGroupNameβ
Runs when a group is named. The callback receives the group.
OnGroupName only works with named groups, not routes.
func (h *Hooks) OnGroupName(handler ...OnGroupNameHandler)
OnListenβ
Runs when the app starts listening via Listen or Listener, before the startup message is printed. With prefork enabled it runs once, in the master process after the child processes have started; the children do not run it.
func (h *Hooks) OnListen(handler ...OnListenHandler)
- OnListen Example
package main
import (
"github.com/gofiber/fiber/v3"
"github.com/gofiber/fiber/v3/log"
)
func main() {
app := fiber.New()
app.Hooks().OnListen(func(listenData fiber.ListenData) error {
scheme := "http"
if listenData.TLS {
scheme = "https"
}
log.Info(scheme + "://" + listenData.Host + ":" + listenData.Port)
return nil
})
app.Listen(":5000", fiber.ListenConfig{DisableStartupMessage: true})
}
OnPreStartupMessage/OnPostStartupMessageβ
Use OnPreStartupMessage to tweak the banner before Fiber prints it, and OnPostStartupMessage to run logic after the banner is printed (or skipped). You can use some helper functions to customize the banner inside the OnPreStartupMessage hook. Both hooks run even when ListenConfig.DisableStartupMessage is set, and with prefork they run in the master process only.
// AddInfo adds an informational entry to the startup message with "INFO" label.
func (sm *PreStartupMessageData) AddInfo(key, title, value string, priority ...int)
// AddWarning adds a warning entry to the startup message with "WARN" label.
func (sm *PreStartupMessageData) AddWarning(key, title, value string, priority ...int)
// AddError adds an error entry to the startup message with "ERROR" label.
func (sm *PreStartupMessageData) AddError(key, title, value string, priority ...int)
// EntryKeys returns all entry keys currently present in the startup message.
func (sm *PreStartupMessageData) EntryKeys() []string
// ResetEntries removes all existing entries from the startup message.
func (sm *PreStartupMessageData) ResetEntries()
// DeleteEntry removes a specific entry from the startup message by its key.
func (sm *PreStartupMessageData) DeleteEntry(key string)
- Assign
sm.BannerHeaderto override the ASCII art banner. Leave it empty to use the default banner provided by Fiber. - Set
sm.PreventDefault = trueto suppress the built-in banner without affecting other hooks. PostStartupMessageDatareports whether the banner was skipped via theDisabled,IsChild, andPreventedflags.- Entries print from the highest
priorityto the lowest. An entry added without a priority gets-1, so it prints after the built-in ones. - Adding an entry with a
keythat already exists replaces that entry, so you can change a built-in one.
The built-in entries use these keys and priorities:
| Key | Entry | Priority |
|---|---|---|
server_address | Server started on | 10 |
app_name | Application name, only when AppName is set | 9 |
total_handlers | Total handlers | 8 |
prefork | Prefork | 7 when enabled, 6 when disabled |
pid | PID | 5 |
process_count | Total process count | 4 |
Startup Message Customizationβ
package main
import (
"fmt"
"os"
"github.com/gofiber/fiber/v3"
)
func main() {
app := fiber.New()
app.Hooks().OnPreStartupMessage(func(sm *fiber.PreStartupMessageData) error {
sm.BannerHeader = "FOOBER " + sm.Version + "\n-------"
// Optional: you can also remove old entries
// sm.ResetEntries()
sm.AddInfo("git-hash", "Git hash", os.Getenv("GIT_HASH"))
sm.AddInfo("prefork", "Prefork", fmt.Sprintf("%v", sm.Prefork), 15)
return nil
})
app.Hooks().OnPostStartupMessage(func(sm *fiber.PostStartupMessageData) error {
if !sm.Disabled && !sm.IsChild && !sm.Prevented {
fmt.Println("startup completed")
}
return nil
})
app.Listen(":5000")
}
ListenDataβ
ListenData exposes runtime metadata about the listener:
| Field | Type | Description |
|---|---|---|
Host | string | Resolved hostname or IP address. |
Port | string | The bound port. |
TLS | bool | Indicates whether TLS is enabled. |
Version | string | Fiber version reported in the startup banner. |
AppName | string | Application name from the configuration. |
HandlerCount | int | Total registered handler count. |
ProcessCount | int | Number of processes Fiber will use. |
PID | int | Current process identifier. |
Prefork | bool | Whether prefork is enabled. |
ChildPIDs | []int | Child process identifiers when preforking. |
ColorScheme | Colors | Active color scheme for the startup message. |
OnForkβ
Runs in the prefork master process each time it starts a child process, including a child it starts again after a crash. The callback receives the PID of that child. The children themselves do not run it.
func (h *Hooks) OnFork(handler ...OnForkHandler)
OnPreShutdownβ
Runs when a shutdown begins, before the server stops accepting connections. It runs once per shutdown, whether Shutdown, ShutdownWithTimeout, ShutdownWithContext or a GracefulContext started it.
func (h *Hooks) OnPreShutdown(handler ...OnPreShutdownHandler)
OnPostShutdownβ
Runs once the shutdown has finished, even when it failed, and exactly once per shutdown. The callback receives the error the shutdown returned: nil after a clean shutdown, or for example context.DeadlineExceeded when the timeout expired while connections were still active.
func (h *Hooks) OnPostShutdown(handler ...OnPostShutdownHandler)
Fiber registers its own OnPostShutdown hook before yours. It terminates the configured services and then closes the SharedStorage, so both are already gone when your hooks run.
OnMountβ
Fires after a sub-app is mounted on a parent. Register it on the sub-app: the parent app is passed to the callback, and it works for app, group and Domain mounts.
func (h *Hooks) OnMount(handler ...OnMountHandler)
- OnMount Example
package main
import (
"fmt"
"github.com/gofiber/fiber/v3"
)
func main() {
app := fiber.New()
app.Get("/", testSimpleHandler).Name("x")
subApp := fiber.New()
subApp.Get("/test", testSimpleHandler)
subApp.Hooks().OnMount(func(parent *fiber.App) error {
fmt.Print("Mount path of sub-app: " + subApp.MountPath())
// Additional custom logic...
return nil
})
app.Use("/sub", subApp)
}
func testSimpleHandler(c fiber.Ctx) error {
return c.SendString("Hello, Fiber!")
}
// Result:
// Mount path of sub-app: /sub
OnName, OnRoute, OnGroup, and OnGroupName are mount-sensitive. When you mount a sub-app that registers these hooks, the route and group paths it reports include the mount prefix, but only for routes and groups registered after the mount. The parent app's hooks do not run for the routes of its sub-apps.
Errors returned by hooksβ
Every hook handler returns an error. What Fiber does with it depends on the hook:
| Hooks | When a handler returns an error |
|---|---|
OnRoute, OnName, OnGroup, OnGroupName, OnMount, OnListen | Fiber panics with the error, so the route registration, the mount or the start fails loudly. |
OnPreStartupMessage, OnPostStartupMessage | Fiber logs the error and skips the remaining hooks of that kind. The app keeps starting. |
OnPreShutdown, OnPostShutdown, OnFork | Fiber logs the error and still runs the remaining hooks. |