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>
This commit is contained in:
Vojtech Vitek (golang.cz) 2026-10-13 22:39:07 +02:00 committed by GitHub
parent 7f9b7448f5
commit fff8bb28cb
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
5 changed files with 229 additions and 20 deletions

View file

@ -345,6 +345,7 @@ with `net/http` can be used with chi's mux.
| [Compress] | Gzip compression for clients that accept compressed responses |
| [ContentCharset] | Ensure charset for Content-Type request headers |
| [CleanPath] | Clean double slashes from request path |
| [Deprecation] | Set the Deprecation response header (RFC 9745); see also [Sunset] |
| [GetHead] | Automatically route undefined HEAD requests to GET handlers |
| [Heartbeat] | Monitoring endpoint to check the servers pulse |
| [Logger] | Logs the start and end of each request with the elapsed processing time |
@ -361,7 +362,7 @@ with `net/http` can be used with chi's mux.
| [RouteHeaders] | Route handling for request headers |
| [SetHeader] | Short-hand middleware to set a response header key/value |
| [StripSlashes] | Strip slashes on routing paths |
| [Sunset] | Sunset set Deprecation/Sunset header to response |
| [Sunset] | Set the Sunset response header (RFC 8594); see also [Deprecation] |
| [Throttle] | Puts a ceiling on the number of concurrent requests |
| [Timeout] | Signals to the request context when the timeout deadline is reached |
| [URLFormat] | Parse extension from url and put it on request context |
@ -374,6 +375,7 @@ with `net/http` can be used with chi's mux.
[Compress]: https://pkg.go.dev/github.com/go-chi/chi/v5/middleware#Compress
[ContentCharset]: https://pkg.go.dev/github.com/go-chi/chi/v5/middleware#ContentCharset
[CleanPath]: https://pkg.go.dev/github.com/go-chi/chi/v5/middleware#CleanPath
[Deprecation]: https://pkg.go.dev/github.com/go-chi/chi/v5/middleware#Deprecation
[GetHead]: https://pkg.go.dev/github.com/go-chi/chi/v5/middleware#GetHead
[GetReqID]: https://pkg.go.dev/github.com/go-chi/chi/v5/middleware#GetReqID
[Heartbeat]: https://pkg.go.dev/github.com/go-chi/chi/v5/middleware#Heartbeat
@ -474,6 +476,30 @@ See the per-function godoc for the full semantics of each middleware, and
[adam-p's "The perils of the 'real' client IP"](https://adam-p.ca/blog/2022/03/x-forwarded-for/)
for the underlying threat model.
### Deprecating and removing a route
Use `Deprecation` first. Add `Sunset` when you know the removal date.
| Situation | Use |
| :------------------------------------------------------- | :-------------------------- |
| Route works, clients should migrate, no removal date yet | `Deprecation` |
| You know the date the route will stop working | `Deprecation` + `Sunset` |
| Route is already removed | Neither. Return `410 Gone`. |
```go
// A bad date parses to the zero time, and the middleware panics at startup.
deprecatedAt, _ := time.Parse(time.DateOnly, "2026-01-15")
sunsetAt, _ := time.Parse(time.DateOnly, "2026-07-01")
// Step 1: the route is deprecated.
r.With(middleware.Deprecation(deprecatedAt)).Get("/v1/users", listUsers)
// Step 2: the removal date is known.
r.With(middleware.Deprecation(deprecatedAt), middleware.Sunset(sunsetAt)).Get("/v1/users", listUsers)
// After sunsetAt: remove the route, or return 410 Gone.
```
### Extra middlewares & packages
Please see https://github.com/go-chi for additional packages.

40
middleware/deprecation.go Normal file
View file

@ -0,0 +1,40 @@
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)
})
}
}

View file

@ -0,0 +1,105 @@
package middleware
import (
"net/http"
"net/http/httptest"
"testing"
"time"
"github.com/go-chi/chi/v5"
)
func TestDeprecation(t *testing.T) {
deprecatedAt := time.Date(2025, 12, 24, 10, 20, 0, 0, time.UTC)
serve := func(t *testing.T, mw func(http.Handler) http.Handler) http.Header {
r := chi.NewRouter()
r.Use(mw)
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("ok"))
})
w := httptest.NewRecorder()
req, _ := http.NewRequest("GET", "/", nil)
r.ServeHTTP(w, req)
if w.Code != 200 {
t.Fatal("Response Code should be 200")
}
return w.Header()
}
t.Run("Deprecation without link", func(t *testing.T) {
h := serve(t, Deprecation(deprecatedAt))
if got, want := h.Get("Deprecation"), "@1766571600"; got != want {
t.Fatalf("Deprecation = %q, want %q", got, want)
}
if h.Get("Sunset") != "" {
t.Fatal("Deprecation should not set Sunset.")
}
if h.Get("Link") != "" {
t.Fatal("Link should be empty.")
}
})
t.Run("Deprecation with link", func(t *testing.T) {
link := `<https://example.com/v1/deprecation-details>; rel="deprecation"`
h := serve(t, Deprecation(deprecatedAt, link))
if got, want := h.Get("Deprecation"), "@1766571600"; got != want {
t.Fatalf("Deprecation = %q, want %q", got, want)
}
if got := h.Get("Link"); got != link {
t.Fatalf("Link = %q, want %q", got, link)
}
})
t.Run("Deprecation with multiple links", func(t *testing.T) {
docs := `<https://example.com/v1/deprecation-details>; rel="deprecation"`
next := `<https://example.com/v2/users>; rel="successor-version"`
h := serve(t, Deprecation(deprecatedAt, docs, next))
got := h.Values("Link")
if len(got) != 2 || got[0] != docs || got[1] != next {
t.Fatalf("Link = %q, want [%q %q]", got, docs, next)
}
})
t.Run("Zero time panics", func(t *testing.T) {
defer func() {
if recover() == nil {
t.Fatal("Deprecation should panic for zero time.")
}
}()
Deprecation(time.Time{})
})
t.Run("Combined with Sunset", func(t *testing.T) {
sunsetAt := time.Date(2026, 6, 1, 0, 0, 0, 0, time.UTC)
h := serve(t, func(next http.Handler) http.Handler {
return Deprecation(deprecatedAt)(Sunset(sunsetAt)(next))
})
if h.Get("Deprecation") != "@1766571600" {
t.Fatal("Deprecation header missing.")
}
if h.Get("Link") != "" {
t.Fatal("Link should be empty.")
}
if got, want := h.Get("Sunset"), "Mon, 01 Jun 2026 00:00:00 GMT"; got != want {
t.Fatalf("Sunset = %q, want %q", got, want)
}
})
t.Run("Combined with Sunset keeps links from both", func(t *testing.T) {
sunsetAt := time.Date(2026, 6, 1, 0, 0, 0, 0, time.UTC)
dep := `<https://example.com/deprecation>; rel="deprecation"`
sun := `<https://example.com/sunset>; rel="sunset"`
h := serve(t, func(next http.Handler) http.Handler {
return Deprecation(deprecatedAt, dep)(Sunset(sunsetAt, sun)(next))
})
got := h.Values("Link")
if len(got) != 2 || got[0] != dep || got[1] != sun {
t.Fatalf("Link = %q, want [%q %q]", got, dep, sun)
}
})
}

View file

@ -5,19 +5,31 @@ import (
"time"
)
// Sunset set Deprecation/Sunset header to response
// This can be used to enable Sunset in a route or a route group
// For more: https://www.rfc-editor.org/rfc/rfc8594.html
// 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) {
if !sunsetAt.IsZero() {
w.Header().Set("Sunset", sunsetAt.Format(http.TimeFormat))
w.Header().Set("Deprecation", sunsetAt.Format(http.TimeFormat))
w.Header().Set("Sunset", sunsetAt.UTC().Format(http.TimeFormat))
for _, link := range links {
w.Header().Add("Link", link)
}
for _, link := range links {
w.Header().Add("Link", link)
}
next.ServeHTTP(w, r)
})

View file

@ -37,8 +37,8 @@ func TestSunset(t *testing.T) {
t.Fatal("Test get sunset error.", sunset)
}
if deprecation != "Wed, 24 Dec 2025 10:20:00 GMT" {
t.Fatal("Test get deprecation error.")
if deprecation != "" {
t.Fatal("Sunset should not set Deprecation.", deprecation)
}
})
@ -49,8 +49,8 @@ func TestSunset(t *testing.T) {
r := chi.NewRouter()
sunsetAt := time.Date(2025, 12, 24, 10, 20, 0, 0, time.UTC)
deprecationLink := "https://example.com/v1/deprecation-details"
r.Use(Sunset(sunsetAt, deprecationLink))
sunsetLink := `<https://example.com/v1/sunset-details>; rel="sunset"`
r.Use(Sunset(sunsetAt, sunsetLink))
var sunset, deprecation, link string
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
@ -72,15 +72,41 @@ func TestSunset(t *testing.T) {
t.Fatal("Test get sunset error.", sunset)
}
if deprecation != "Wed, 24 Dec 2025 10:20:00 GMT" {
t.Fatal("Test get deprecation error.")
if deprecation != "" {
t.Fatal("Sunset should not set Deprecation.", deprecation)
}
if link != deprecationLink {
t.Fatal("Test get deprecation link error.")
if link != sunsetLink {
t.Fatal("Test get sunset link error.")
}
})
t.Run("Sunset with multiple links", func(t *testing.T) {
req, _ := http.NewRequest("GET", "/", nil)
w := httptest.NewRecorder()
r := chi.NewRouter()
docs := `<https://example.com/v1/sunset-details>; rel="sunset"`
next := `<https://example.com/v2/users>; rel="successor-version"`
r.Use(Sunset(time.Date(2025, 12, 24, 10, 20, 0, 0, time.UTC), docs, next))
r.Get("/", func(w http.ResponseWriter, r *http.Request) {})
r.ServeHTTP(w, req)
got := w.Header().Values("Link")
if len(got) != 2 || got[0] != docs || got[1] != next {
t.Fatalf("Link = %q, want [%q %q]", got, docs, next)
}
})
t.Run("Zero time panics", func(t *testing.T) {
defer func() {
if recover() == nil {
t.Fatal("Sunset should panic for zero time.")
}
}()
Sunset(time.Time{})
})
}
/**
@ -91,8 +117,8 @@ func main() {
sunsetAt := time.Date(2025, 12, 24, 10, 20, 0, 0, time.UTC)
r.Use(middleware.Sunset(sunsetAt))
// can provide additional link for updated resource
// r.Use(middleware.Sunset(sunsetAt, "https://example.com/v1/deprecation-details"))
// can provide a Link header value (RFC 8288) pointing at more details
// r.Use(middleware.Sunset(sunsetAt, `<https://example.com/v1/sunset-details>; rel="sunset"`))
r.Get("/", func(w http.ResponseWriter, r *http.Request) {
w.Write([]byte("This endpoint will be removed soon"))