chi/middleware/deprecation.go
Vojtech Vitek (golang.cz) fff8bb28cb
middleware: add Deprecation (RFC 9745), make Sunset RFC 8594 only (#1195)
* middleware: add Deprecation (RFC 9745), make Sunset RFC 8594 only

Sunset used to set Deprecation to an HTTP-date, following the old draft.
RFC 9745 defines Deprecation as a Structured Field Date (e.g. @1766571600),
so that value was unparseable for compliant clients. It also conflated the
deprecation date with the sunset date.

- Add Deprecation(deprecatedAt, links...) per RFC 9745.
- Sunset now sets only the Sunset header per RFC 8594.
- Sunset formats the date in UTC so non-UTC times emit a valid GMT date.

Breaking for anyone relying on Sunset to also set Deprecation: add
Deprecation to the chain explicitly.

* middleware: cross-link Sunset and Deprecation in docs

* middleware: address review on Sunset/Deprecation docs and Link examples

* middleware: recommend deprecate-then-sunset lifecycle in docs

* middleware: cite RFC 9651 for the Structured Field Date type

* middleware: panic on zero time in Sunset and Deprecation

A zero time is almost always an unset value (ignored parse error, missing
config field). Failing at router construction surfaces it at startup
instead of silently dropping the header.

* middleware: document how to fix the zero-time panic

* middleware: fix placeholder in zero-time panic godoc

* middleware: shorten zero-time panic messages

* middleware: guide users on choosing Deprecation and Sunset

* middleware: test multiple Link values for Sunset and Deprecation

* middleware: pass subtest t into Deprecation test helper

serve closed over the parent t, so a failure inside a subtest reported
"subtest may have called FailNow on a parent test" instead of naming it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-13 22:39:07 +02:00

40 lines
1.3 KiB
Go

package middleware
import (
"net/http"
"strconv"
"time"
)
// Deprecation marks a route as deprecated, per RFC 9745.
// https://www.rfc-editor.org/rfc/rfc9745.html
//
// Use it from the day you decide to retire a route. The route keeps working,
// and clients are told to migrate. When you know the removal date, add [Sunset].
// Middleware order doesn't matter.
//
// deprecatedAt is when the route was, or will be, deprecated. A past date is fine.
// It panics if deprecatedAt is the zero time, which is usually an unset value.
// Pass a real date, or skip the middleware when no date is set.
//
// Each link is added as-is as a Link header, so it must be a full RFC 8288
// value, e.g. `<https://example.com/migrate>; rel="deprecation"`.
func Deprecation(deprecatedAt time.Time, links ...string) func(http.Handler) http.Handler {
if deprecatedAt.IsZero() {
panic("middleware.Deprecation: deprecatedAt must not be zero")
}
// RFC 9745 uses a Structured Field Date (RFC 9651), not an HTTP-date.
value := "@" + strconv.FormatInt(deprecatedAt.Unix(), 10)
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Deprecation", value)
for _, link := range links {
w.Header().Add("Link", link)
}
next.ServeHTTP(w, r)
})
}
}