* 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>
37 lines
1.2 KiB
Go
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)
|
|
})
|
|
}
|
|
}
|