chi/middleware/sunset.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

37 lines
1.2 KiB
Go

package middleware
import (
"net/http"
"time"
)
// Sunset announces when a route will stop working, per RFC 8594.
// https://www.rfc-editor.org/rfc/rfc8594.html
//
// Use it once you know the removal date, and keep [Deprecation] on the same
// route. Sunset alone is valid, but clients get no "stop using this" signal.
// Middleware order doesn't matter.
//
// sunsetAt is usually a future date, and should not be before the deprecation date.
// After it, remove the route or return 410 Gone.
// It panics if sunsetAt 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="sunset"`.
func Sunset(sunsetAt time.Time, links ...string) func(http.Handler) http.Handler {
if sunsetAt.IsZero() {
panic("middleware.Sunset: sunsetAt must not be zero")
}
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Sunset", sunsetAt.UTC().Format(http.TimeFormat))
for _, link := range links {
w.Header().Add("Link", link)
}
next.ServeHTTP(w, r)
})
}
}