* 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>
40 lines
1.3 KiB
Go
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)
|
|
})
|
|
}
|
|
}
|