Deprecation
Deprecation middleware for Fiber that tells clients a route is deprecated, or will stop working, with the Deprecation header (RFC 9745) and the Sunset header (RFC 8594).
Deprecation does not change how the route behaves. The headers are a hint: clients and API gateways can log them, warn developers, or plan a migration.
Deprecation is sent as a Structured Field Date (@ and Unix seconds), and Sunset as an HTTP-date. A date in the future announces an upcoming deprecation or sunset. Both carry whole seconds. RFC 9745 forbids a Sunset earlier than Deprecation, so New panics on that config, compared at that resolution. It also panics on a Sunset outside the years 0000 to 9999 and on a Deprecation beyond the range of a Structured Field Date, which the headers cannot express.
Link and SunsetLink may be set without their date, to publish a deprecation or sunset policy before anything is deprecated (RFC 9745 Section 3.1, RFC 8594 Section 6). Each is a URI reference (RFC 8288 Section 3): absolute, or relative to the request URI. It may hold only the characters RFC 3986 allows, so percent-encode anything else, % only as the start of a percent-encoding, and no userinfo (user:password@), which every client would see. An http or https URI, and a network-path reference starting with //, needs a host. New panics otherwise.
When the headers are writtenβ
The headers are set before the rest of the chain runs, like those of helmet and cors, so a response the handler sends itself with c.End(), and the 500 an outer recover.New() sends for a panic, carry them. A 103 Early Hints response carries only the Link lines, so it gets the deprecation and sunset links but not the two dates.
Anything later in the chain that replaces or edits the response headers wins. That includes a proxied response (proxy.Do, proxy.Forward and the other proxy helpers copy the upstream's headers over the response), a handler that calls c.Response().Reset(), the 304 and 416 responses of SendFile and static, the 503 that timeout.New sends, and a c.Set of Deprecation, Sunset or Link. With DisableHeaderNormalizing: true, a c.Set that spells the name another way, such as deprecation, adds a second line instead of replacing the middleware's. Set the headers in the handler after those calls when such a route must carry them, or add links with c.Links, which appends to the Link header instead of replacing it.
A link that the Link header already holds in the form the middleware writes (<URL>; rel="deprecation") is not added again, for example when c.RestartRouting() runs the middleware a second time. The same link written another way, such as <URL>;rel=deprecation, is not recognized, and the middleware adds its own form next to it.
Signaturesβ
func New(config ...Config) fiber.Handler
Examplesβ
Import the package:
import (
"time"
"github.com/gofiber/fiber/v3"
"github.com/gofiber/fiber/v3/middleware/deprecation"
)
The dates below are placeholders. Use the real dates of your deprecation, and keep Sunset in the future: RFC 8594 reads a past one as "now".
Deprecate a group of routesβ
v1 := app.Group("/v1", deprecation.New(deprecation.Config{
Deprecation: time.Date(2027, time.January, 1, 0, 0, 0, 0, time.UTC),
Sunset: time.Date(2027, time.July, 1, 0, 0, 0, 0, time.UTC),
Link: "https://example.com/docs/v2-migration",
}))
A response from /v1 then carries:
Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://example.com/docs/v2-migration>; rel="deprecation"
Announce a sunset onlyβ
app.Get("/legacy", deprecation.New(deprecation.Config{
Sunset: time.Date(2027, time.December, 31, 23, 59, 59, 0, time.UTC),
SunsetLink: "https://example.com/sunset-policy",
}), handler)
Publish a deprecation policy onlyβ
app.Use(deprecation.New(deprecation.Config{
Link: "/docs/deprecation-policy",
}))
Skip logicβ
app.Use(deprecation.New(deprecation.Config{
Deprecation: time.Date(2027, time.January, 1, 0, 0, 0, 0, time.UTC),
Next: func(c fiber.Ctx) bool {
return c.Path() == "/healthz"
},
}))
Orderingβ
- Register it before
cache. A cache hit returns before the middleware behind it runs, and with the defaultStoreResponseHeaders: falsethe cache replays only a fixed set of headers, so later responses would lose the headers.StoreResponseHeaders: truekeeps them too, but a hit then replays the storedDeprecation,SunsetandLinkover the ones the middleware just set: after you change a date or link, or skip the route withNext, entries stored earlier, including ones in an externalStoragethat outlives a deploy, serve the old values until they expire. - With
idempotencyregistered after it, a handler that adds links withc.Linksrewrites theLinkline, and a replayed response repeats the deprecation link. Registeridempotencyfirst. - When it is registered at two levels, such as
app.Useand a group, the inner instance replacesDeprecationandSunsetone by one, and both add their links. SetDeprecationandSunsettogether at the level that overrides, so the pair stays in order. The middleware does not check the pair across levels: an outerSunsetof 2026-03-01 with an innerDeprecationof 2026-06-01 sends aSunsetearlier thanDeprecation, which RFC 9745 Section 4 forbids. That is a known deviation, kept so an instance needs no knowledge of the others.
Configβ
| Property | Type | Description | Default |
|---|---|---|---|
| Next | func(c fiber.Ctx) bool | Defines a function to skip this middleware when it returns true. | nil |
| Deprecation | time.Time | When the route was or will be deprecated. Sent in the Deprecation header. | zero time (not sent) |
| Sunset | time.Time | When the route is expected to stop responding. Sent in the Sunset header. Must not be earlier than Deprecation. | zero time (not sent) |
| Link | string | URI reference that documents the deprecation, added to the Link header with rel="deprecation". | "" |
| SunsetLink | string | URI reference that documents the sunset policy, added to the Link header with rel="sunset". | "" |
At least one field other than Next is required. The links are appended to a Link header that is already set when the middleware runs.
Default Configβ
var ConfigDefault = Config{}
There is no useful default β you must provide at least Deprecation, Sunset, Link or SunsetLink.