da1839f730
- webhook.go: HMAC-SHA256 WebhookSigner matching PHP WebhookSignature — sign/verify, X-Webhook-Signature / X-Webhook-Timestamp headers, VerifyRequest middleware helper, 5-minute default tolerance, secret generator (RFC §6) - sunset.go: ApiSunsetWith(date, replacement, opts...) + WithSunsetNoticeURL; ApiSunset now emits API-Suggested-Replacement when replacement set; RouteDescription.NoticeURL surfaces API-Deprecation-Notice-URL (RFC §8) - options.go + api.go + transport.go: WithWebSocket(gin.HandlerFunc) alongside existing WithWSHandler(http.Handler); gin form wins when both supplied (RFC §2.2) - openapi.go: apiSuggestedReplacement + apiDeprecationNoticeURL as reusable header components; NoticeURL on a RouteDescription flips operation deprecated flag and emits response header doc - cmd/api/*.go: migrated from Cobra (cli.NewCommand, StringFlag) to new path-based CLI API (c.Command + core.Options.String/Int/Bool); replaces the 1,422-line Cobra test suite with _Good/_Bad/_Ugly triads on the new surface - webhook_test.go + sunset_test.go + websocket_test.go: full coverage Co-Authored-By: Virgil <virgil@lethean.io>
115 lines
3.3 KiB
Go
115 lines
3.3 KiB
Go
// SPDX-License-Identifier: EUPL-1.2
|
|
|
|
package api
|
|
|
|
import (
|
|
"net/http"
|
|
"time"
|
|
|
|
core "dappco.re/go/core"
|
|
|
|
"github.com/gin-gonic/gin"
|
|
)
|
|
|
|
// SunsetOption customises the behaviour of ApiSunsetWith. Use the supplied
|
|
// constructors (e.g. WithSunsetNoticeURL) to compose the desired metadata
|
|
// without breaking the simpler ApiSunset signature.
|
|
//
|
|
// mw := api.ApiSunsetWith("2025-06-01", "/api/v2/users",
|
|
// api.WithSunsetNoticeURL("https://docs.example.com/deprecation/billing"),
|
|
// )
|
|
type SunsetOption func(*sunsetConfig)
|
|
|
|
// sunsetConfig carries optional metadata for ApiSunsetWith.
|
|
type sunsetConfig struct {
|
|
noticeURL string
|
|
}
|
|
|
|
// WithSunsetNoticeURL adds the API-Deprecation-Notice-URL header documented
|
|
// in spec §8 to every response. The URL should point to a human-readable
|
|
// migration guide for the deprecated endpoint.
|
|
//
|
|
// api.ApiSunsetWith("2026-04-30", "POST /api/v2/billing/invoices",
|
|
// api.WithSunsetNoticeURL("https://docs.api.dappco.re/deprecation/billing"),
|
|
// )
|
|
func WithSunsetNoticeURL(url string) SunsetOption {
|
|
return func(cfg *sunsetConfig) {
|
|
cfg.noticeURL = url
|
|
}
|
|
}
|
|
|
|
// ApiSunset returns middleware that marks a route or group as deprecated.
|
|
//
|
|
// The middleware appends standard deprecation headers to every response:
|
|
// Deprecation, optional Sunset, optional Link, optional API-Suggested-Replacement,
|
|
// and X-API-Warn. Existing header values are preserved so downstream middleware
|
|
// and handlers can keep their own link relations or warning metadata.
|
|
//
|
|
// Example:
|
|
//
|
|
// rg.Use(api.ApiSunset("2025-06-01", "/api/v2/users"))
|
|
func ApiSunset(sunsetDate, replacement string) gin.HandlerFunc {
|
|
return ApiSunsetWith(sunsetDate, replacement)
|
|
}
|
|
|
|
// ApiSunsetWith is the extensible form of ApiSunset. It accepts SunsetOption
|
|
// values to attach optional metadata such as the deprecation notice URL.
|
|
//
|
|
// Example:
|
|
//
|
|
// rg.Use(api.ApiSunsetWith(
|
|
// "2026-04-30",
|
|
// "POST /api/v2/billing/invoices",
|
|
// api.WithSunsetNoticeURL("https://docs.api.dappco.re/deprecation/billing"),
|
|
// ))
|
|
func ApiSunsetWith(sunsetDate, replacement string, opts ...SunsetOption) gin.HandlerFunc {
|
|
sunsetDate = core.Trim(sunsetDate)
|
|
replacement = core.Trim(replacement)
|
|
formatted := formatSunsetDate(sunsetDate)
|
|
warning := "This endpoint is deprecated."
|
|
if sunsetDate != "" {
|
|
warning = "This endpoint is deprecated and will be removed on " + sunsetDate + "."
|
|
}
|
|
|
|
cfg := &sunsetConfig{}
|
|
for _, opt := range opts {
|
|
if opt != nil {
|
|
opt(cfg)
|
|
}
|
|
}
|
|
noticeURL := core.Trim(cfg.noticeURL)
|
|
|
|
return func(c *gin.Context) {
|
|
c.Next()
|
|
|
|
c.Writer.Header().Add("Deprecation", "true")
|
|
if formatted != "" {
|
|
c.Writer.Header().Add("Sunset", formatted)
|
|
}
|
|
if replacement != "" {
|
|
c.Writer.Header().Add("Link", "<"+replacement+">; rel=\"successor-version\"")
|
|
c.Writer.Header().Add("API-Suggested-Replacement", replacement)
|
|
}
|
|
if noticeURL != "" {
|
|
c.Writer.Header().Add("API-Deprecation-Notice-URL", noticeURL)
|
|
}
|
|
c.Writer.Header().Add("X-API-Warn", warning)
|
|
}
|
|
}
|
|
|
|
func formatSunsetDate(sunsetDate string) string {
|
|
sunsetDate = core.Trim(sunsetDate)
|
|
if sunsetDate == "" {
|
|
return ""
|
|
}
|
|
if core.Contains(sunsetDate, ",") {
|
|
return sunsetDate
|
|
}
|
|
|
|
parsed, err := time.Parse("2006-01-02", sunsetDate)
|
|
if err != nil {
|
|
return sunsetDate
|
|
}
|
|
|
|
return parsed.UTC().Format(http.TimeFormat)
|
|
}
|