fiber/docs/api/app.md

id	title	description	sidebar_position
app	🚀 App	The app instance conventionally denotes the Fiber application.	2

import RoutingHandler from './../partials/routing/handler.md';

Static

Use the Static method to serve static files such as images, CSS, and JavaScript.

:::info By default, Static will serve index.html files in response to a request on a directory. :::

func (app *App) Static(prefix, root string, config ...Static) Router

Use the following code to serve files in a directory named ./public

app.Static("/", "./public")

// => http://localhost:3000/hello.html
// => http://localhost:3000/js/jquery.js
// => http://localhost:3000/css/style.css

// Serve files from multiple directories
app.Static("/", "./public")

// Serve files from "./files" directory:
app.Static("/", "./files")

You can use any virtual path prefix _where the path does not actually exist in the file system_ for files that are served by the Static method, specify a prefix path for the static directory, as shown below:

app.Static("/static", "./public")

// => http://localhost:3000/static/hello.html
// => http://localhost:3000/static/js/jquery.js
// => http://localhost:3000/static/css/style.css

If you want to have a little bit more control regarding the settings for serving static files. You could use the fiber.Static struct to enable specific settings.

// Static defines configuration options when defining static assets.
type Static struct {
    // When set to true, the server tries minimizing CPU usage by caching compressed files.
    // This works differently than the github.com/gofiber/compression middleware.
    // Optional. Default value false
    Compress bool `json:"compress"`

    // When set to true, enables byte range requests.
    // Optional. Default value false
    ByteRange bool `json:"byte_range"`

    // When set to true, enables directory browsing.
    // Optional. Default value false.
    Browse bool `json:"browse"`

    // When set to true, enables direct download.
    // Optional. Default value false.
    Download bool `json:"download"`

    // The name of the index file for serving a directory.
    // Optional. Default value "index.html".
    Index string `json:"index"`

    // Expiration duration for inactive file handlers.
    // Use a negative time.Duration to disable it.
    //
    // Optional. Default value 10 * time.Second.
    CacheDuration time.Duration `json:"cache_duration"`

    // The value for the Cache-Control HTTP-header
    // that is set on the file response. MaxAge is defined in seconds.
    //
    // Optional. Default value 0.
    MaxAge int `json:"max_age"`

    // ModifyResponse defines a function that allows you to alter the response.
    //
    // Optional. Default: nil
    ModifyResponse Handler

    // Next defines a function to skip this middleware when returned true.
    //
    // Optional. Default: nil
    Next func(c *Ctx) bool
}

// Custom config
app.Static("/", "./public", fiber.Static{
  Compress:      true,
  ByteRange:     true,
  Browse:        true,
  Index:         "john.html",
  CacheDuration: 10 * time.Second,
  MaxAge:        3600,
})

Route Handlers

Mount

You can Mount Fiber instance by creating a *Mount

func (a *App) Mount(prefix string, app *App) Router

func main() {
    app := fiber.New()
    micro := fiber.New()
    app.Mount("/john", micro) // GET /john/doe -> 200 OK

    micro.Get("/doe", func(c *fiber.Ctx) error {
        return c.SendStatus(fiber.StatusOK)
    })

    log.Fatal(app.Listen(":3000"))
}

MountPath

The MountPath property contains one or more path patterns on which a sub-app was mounted.

func (app *App) MountPath() string

func main() {
	app := fiber.New()
	one := fiber.New()
	two := fiber.New()
	three := fiber.New()

	two.Mount("/three", three)
	one.Mount("/two", two)
	app.Mount("/one", one)
  
	one.MountPath()   // "/one"
	two.MountPath()   // "/one/two"
	three.MountPath() // "/one/two/three"
	app.MountPath()   // ""
}

:::caution Mounting order is important for MountPath. If you want to get mount paths properly, you should start mounting from the deepest app. :::

Group

You can group routes by creating a *Group struct.

func (app *App) Group(prefix string, handlers ...Handler) Router

func main() {
  app := fiber.New()

  api := app.Group("/api", handler)  // /api

  v1 := api.Group("/v1", handler)   // /api/v1
  v1.Get("/list", handler)          // /api/v1/list
  v1.Get("/user", handler)          // /api/v1/user

  v2 := api.Group("/v2", handler)   // /api/v2
  v2.Get("/list", handler)          // /api/v2/list
  v2.Get("/user", handler)          // /api/v2/user

  log.Fatal(app.Listen(":3000"))
}

Route

You can define routes with a common prefix inside the common function.

func (app *App) Route(prefix string, fn func(router Router), name ...string) Router

func main() {
  app := fiber.New()

  app.Route("/test", func(api fiber.Router) {
      api.Get("/foo", handler).Name("foo") // /test/foo (name: test.foo)
    api.Get("/bar", handler).Name("bar") // /test/bar (name: test.bar)
  }, "test.")

  log.Fatal(app.Listen(":3000"))
}

Server

Server returns the underlying fasthttp server

func (app *App) Server() *fasthttp.Server

func main() {
    app := fiber.New()

    app.Server().MaxConnsPerIP = 1

    // ...
}

Server Shutdown

Shutdown gracefully shuts down the server without interrupting any active connections. Shutdown works by first closing all open listeners and then waits indefinitely for all connections to return to idle before shutting down.

ShutdownWithTimeout will forcefully close any active connections after the timeout expires.

ShutdownWithContext shuts down the server including by force if the context's deadline is exceeded.

func (app *App) Shutdown() error
func (app *App) ShutdownWithTimeout(timeout time.Duration) error
func (app *App) ShutdownWithContext(ctx context.Context) error

HandlersCount

This method returns the amount of registered handlers.

func (app *App) HandlersCount() uint32

Stack

This method returns the original router stack

func (app *App) Stack() [][]*Route

var handler = func(c *fiber.Ctx) error { return nil }

func main() {
    app := fiber.New()

    app.Get("/john/:age", handler)
    app.Post("/register", handler)

    data, _ := json.MarshalIndent(app.Stack(), "", "  ")
    fmt.Println(string(data))

    app.Listen(":3000")
}

[
  [
    {
      "method": "GET",
      "path": "/john/:age",
      "params": [
        "age"
      ]
    }
  ],
  [
    {
      "method": "HEAD",
      "path": "/john/:age",
      "params": [
        "age"
      ]
    }
  ],
  [
    {
      "method": "POST",
      "path": "/register",
      "params": null
    }
  ]
]

Name

This method assigns the name of latest created route.

func (app *App) Name(name string) Router

var handler = func(c *fiber.Ctx) error { return nil }

func main() {
    app := fiber.New()

    app.Get("/", handler)
    app.Name("index")

    app.Get("/doe", handler).Name("home")

    app.Trace("/tracer", handler).Name("tracert")

    app.Delete("/delete", handler).Name("delete")

    a := app.Group("/a")
    a.Name("fd.")

    a.Get("/test", handler).Name("test")

    data, _ := json.MarshalIndent(app.Stack(), "", "  ")
    fmt.Print(string(data))

    app.Listen(":3000")

}

[
  [
    {
      "method": "GET",
      "name": "index",
      "path": "/",
      "params": null
    },
    {
      "method": "GET",
      "name": "home",
      "path": "/doe",
      "params": null
    },
    {
      "method": "GET",
      "name": "fd.test",
      "path": "/a/test",
      "params": null
    }
  ],
  [
    {
      "method": "HEAD",
      "name": "",
      "path": "/",
      "params": null
    },
    {
      "method": "HEAD",
      "name": "",
      "path": "/doe",
      "params": null
    },
    {
      "method": "HEAD",
      "name": "",
      "path": "/a/test",
      "params": null
    }
  ],
  null,
  null,
  [
    {
      "method": "DELETE",
      "name": "delete",
      "path": "/delete",
      "params": null
    }
  ],
  null,
  null,
  [
    {
      "method": "TRACE",
      "name": "tracert",
      "path": "/tracer",
      "params": null
    }
  ],
  null
]

GetRoute

This method gets the route by name.

func (app *App) GetRoute(name string) Route

var handler = func(c *fiber.Ctx) error { return nil }

func main() {
    app := fiber.New()

    app.Get("/", handler).Name("index")
    
    data, _ := json.MarshalIndent(app.GetRoute("index"), "", "  ")
	fmt.Print(string(data))


	app.Listen(":3000")

}

{
  "method": "GET",
  "name": "index",
  "path": "/",
  "params": null
}

GetRoutes

This method gets all routes.

func (app *App) GetRoutes(filterUseOption ...bool) []Route

When filterUseOption equal to true, it will filter the routes registered by the middleware.

func main() {
	app := fiber.New()
	app.Post("/", func (c *fiber.Ctx) error {
		return c.SendString("Hello, World!")
	}).Name("index")
	data, _ := json.MarshalIndent(app.GetRoutes(true), "", "  ")
	fmt.Print(string(data))
}

[
    {
        "method": "POST",
        "name": "index",
        "path": "/",
        "params": null
    }
]

Config

Config returns the app config as value read-only.

func (app *App) Config() Config

Handler

Handler returns the server handler that can be used to serve custom *fasthttp.RequestCtx requests.

func (app *App) Handler() fasthttp.RequestHandler

Listen

Listen serves HTTP requests from the given address.

func (app *App) Listen(addr string) error

// Listen on port :8080 
app.Listen(":8080")

// Custom host
app.Listen("127.0.0.1:8080")

ListenTLS

ListenTLS serves HTTPs requests from the given address using certFile and keyFile paths to as TLS certificate and key file.

func (app *App) ListenTLS(addr, certFile, keyFile string) error

app.ListenTLS(":443", "./cert.pem", "./cert.key");

Using ListenTLS defaults to the following config use `Listener` to provide your own config

&tls.Config{
    MinVersion:               tls.VersionTLS12,
    Certificates: []tls.Certificate{
        cert,
    },
}

ListenTLSWithCertificate

func (app *App) ListenTLS(addr string, cert tls.Certificate) error

app.ListenTLSWithCertificate(":443", cert);

Using ListenTLSWithCertificate defaults to the following config use `Listener` to provide your own config

&tls.Config{
    MinVersion:               tls.VersionTLS12,
    Certificates: []tls.Certificate{
        cert,
    },
}

ListenMutualTLS

ListenMutualTLS serves HTTPs requests from the given address using certFile, keyFile and clientCertFile are the paths to TLS certificate and key file

func (app *App) ListenMutualTLS(addr, certFile, keyFile, clientCertFile string) error

app.ListenMutualTLS(":443", "./cert.pem", "./cert.key", "./ca-chain-cert.pem");

Using ListenMutualTLS defaults to the following config use `Listener` to provide your own config

&tls.Config{
	MinVersion: tls.VersionTLS12,
	ClientAuth: tls.RequireAndVerifyClientCert,
	ClientCAs:  clientCertPool,
	Certificates: []tls.Certificate{
		cert,
	},
}

ListenMutualTLSWithCertificate

ListenMutualTLSWithCertificate serves HTTPs requests from the given address using certFile, keyFile and clientCertFile are the paths to TLS certificate and key file

func (app *App) ListenMutualTLSWithCertificate(addr string, cert tls.Certificate, clientCertPool *x509.CertPool) error

app.ListenMutualTLSWithCertificate(":443", cert, clientCertPool);

Using ListenMutualTLSWithCertificate defaults to the following config use `Listener` to provide your own config

&tls.Config{
	MinVersion: tls.VersionTLS12,
	ClientAuth: tls.RequireAndVerifyClientCert,
	ClientCAs:  clientCertPool,
	Certificates: []tls.Certificate{
		cert,
	},
}

Listener

You can pass your own net.Listener using the Listener method. This method can be used to enable TLS/HTTPS with a custom tls.Config.

func (app *App) Listener(ln net.Listener) error

ln, _ := net.Listen("tcp", ":3000")

cer, _:= tls.LoadX509KeyPair("server.crt", "server.key")

ln = tls.NewListener(ln, &tls.Config{Certificates: []tls.Certificate{cer}})

app.Listener(ln)

Test

Testing your application is done with the Test method. Use this method for creating _test.go files or when you need to debug your routing logic. The default timeout is 1s if you want to disable a timeout altogether, pass -1 as a second argument.

func (app *App) Test(req *http.Request, msTimeout ...int) (*http.Response, error)

// Create route with GET method for test:
app.Get("/", func(c *fiber.Ctx) error {
  fmt.Println(c.BaseURL())              // => http://google.com
  fmt.Println(c.Get("X-Custom-Header")) // => hi

  return c.SendString("hello, World!")
})

// http.Request
req := httptest.NewRequest("GET", "http://google.com", nil)
req.Header.Set("X-Custom-Header", "hi")

// http.Response
resp, _ := app.Test(req)

// Do something with results:
if resp.StatusCode == fiber.StatusOK {
  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body)) // => Hello, World!
}

Hooks

Hooks is a method to return hooks property.

func (app *App) Hooks() *Hooks