Redirect

Redirect middleware maps old URLs to new ones using simple rules.

Signatures

func New(config ...Config) fiber.Handler

Examples

package main

import (
    "github.com/gofiber/fiber/v3"
    "github.com/gofiber/fiber/v3/middleware/redirect"
)

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

    app.Use(redirect.New(redirect.Config{
      Rules: map[string]string{
        "/old":   "/new",
        "/old/*": "/new/$1",
      },
      StatusCode: fiber.StatusMovedPermanently,
    }))

    app.Get("/new", func(c fiber.Ctx) error {
      return c.SendString("Hello, World!")
    })
    app.Get("/new/*", func(c fiber.Ctx) error {
      return c.SendString("Wildcard: " + c.Params("*"))
    })

    app.Listen(":3000")
}

Test

curl http://localhost:3000/old
curl http://localhost:3000/old/hello

Config

How captures are placed

The values a rule captures come from the request path, so where a $N sits in the target decides what it is allowed to contribute.

A target with no host of its own — "/api/*": "/$1" — always redirects within this application. The composed location is read the way a browser reads it, then held to this origin: a leading run of slashes collapses to one, and a capture that turned the location into an absolute URL is rooted as a path. Without that, /api//evil.com would send Location: //evil.com, which the browser follows to evil.com.

A target naming its own host — "/ext/*": "https://cdn.example.com/$1" — redirects wherever it says. A $N after the host may hold anything, including slashes; it can only add to the path.

A target with a $N inside its host — "/cdn/*": "https://$1.cdn.example.com/" — requires the capture to be a label of that host. The rule is skipped, and the request falls through to the rest of the stack, whenever the captured value would move the host instead: one containing /, \, ?, #, @ or : in that position, or one that extends the host where the target ends in $N ("https://cdn.example.com$1" accepts /foo.png, which starts a path, but not foo.png or @evil.com).

::::caution

A target that hands the whole host to the request — "/go/*": "https://$1", "//$1", or "https:$1" — is an open redirect: anyone able to shape the path chooses where the client lands. Such a rule never fires, and Fiber logs a warning naming it at startup, since there is no way to tell the intended host from an attacker's. Pin the host in the target instead.

A capture hands over the host whenever nothing beside it in the authority is host text, so these are the same case and are refused too:

Note that "https://[email protected]" is fine — there the author's host follows the @ and the capture is only userinfo — as are "https://cdn.example.com:$1" and "https://tenant-$1.example.com".

:::danger Pin a domain you control, not just a suffix

These checks ask whether the author wrote the host, not whether the host is one you own. "https://$1.com" and "https://$1.xyz" pass — the capture is a label under a suffix the target names — but anyone can register a name under .com or .xyz, so /go/evil still reaches evil.com. The same goes for a suffix shared with other tenants.

Fiber has no list of public suffixes and cannot tell "$1.com" from "$1.example.com". Pin enough of the host that every name below it is yours, and where the set of destinations is known, prefer matching the capture against an allowlist in your own handler over interpolating it into a host at all.

:::

A capture inside the brackets of an IPv6 literal is refused separately, and for its own reason — one side of it genuinely does pin a host, so the rules above do not decide the case.

A DNS name is written least-significant label first, so either side of a capture can pin it: "https://$1.example.com" stays under example.com, and "https://cdn.example.com$1" stays on cdn.example.com. A bracketed address is written the other way round, most-significant group first. There "https://[$1::1]" leaves the routing prefix to the request — enough to reach loopback or a link-local address — while "https://[2001:db8::$1]" really does pin the network and only lets the request choose the last group.

Deciding those two apart needs a rule that is the reverse of the one used everywhere else, so rather than keep two opposite readings in step Fiber refuses both and logs a warning saying which case it is. Write the address in full and capture the port instead:

"/r/*": "https://[2001:db8::1]:$1",  // fine

A refused rule is dropped, so the request continues to the remaining rules of this middleware before reaching the rest of the stack. With {"/go/*": "https://$1", "/*": "/home"}, a request for /go/evil.com is redirected to /home by the catch-all.

This applies to every scheme, not only the ones a browser navigates by. A // opens an authority whatever the scheme is, so "mailto:$1", "myapp:$1" and any custom or deep-link scheme hand the host to a captured //evil.com exactly as "https:$1" does; for http, https, ws, wss and ftp the parser does not even need the slashes, reading "ws:evil.com" as ws://evil.com.

Because those schemes reach a host without the slashes, a target that writes one without them names an authority all the same, and every rule above applies to it unchanged: "https:cdn.example.com$1" is read exactly as "https://cdn.example.com$1" — so it too refuses a capture that would turn the author's host into userinfo (/r/@evil.com) or extend it into another domain (/r/.evil.com).

What decides it otherwise is where the capture sits, not which scheme precedes it. A capture with the author's text in front of it opens no authority, so "myapp:fixed/$1" and "https:fixed/$1" are fine. And a capture at the front is fine where the author wrote host text after it — in "mailto:[email protected]" the parser reads example.com as the host and the capture as userinfo. mailto is not one of the special schemes, so without a // it has no authority at all.

::::

Default Config

var ConfigDefault = Config{
    StatusCode: fiber.StatusFound,
}