From 7ed84686bc8b7570e982debe34ad47ec8bc247e3 Mon Sep 17 00:00:00 2001 From: Steve McDougall Date: Fri, 30 Oct 2026 09:43:13 +0000 Subject: [PATCH 1/2] api-toolbox ^0.3.3 Reviewed and trusted in Vet by Steve. 0.3.3 brings the apiguide.dev catalogue's endpoint-sunset type, which the next commit uses. --- composer.json | 2 +- composer.lock | 14 +++++++------- vet.json | 4 ++-- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/composer.json b/composer.json index ca441bb..0c41e28 100644 --- a/composer.json +++ b/composer.json @@ -13,7 +13,7 @@ "license": "MIT", "require": { "php": "^8.5", - "juststeveking/api-toolbox": "^0.3.2", + "juststeveking/api-toolbox": "^0.3.3", "laravel/framework": "^13.30", "laravel/octane": "^2.21", "laravel/sanctum": "^4.3", diff --git a/composer.lock b/composer.lock index 2ca6c4f..203be35 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "4b814c4cf046e17e177a5ae998331468", + "content-hash": "aee1a1ef2a33027a8a78b7ff527e7b3e", "packages": [ { "name": "brick/math", @@ -1060,16 +1060,16 @@ }, { "name": "juststeveking/api-toolbox", - "version": "v0.3.2", + "version": "v0.3.3", "source": { "type": "git", "url": "https://github.com/JustSteveKing/api-toolbox.git", - "reference": "ed77856cc169af66260223e500e3822f852784c8" + "reference": "5f1978fa4d5d8e90806e3a9394524f3ae9ce5398" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/JustSteveKing/api-toolbox/zipball/ed77856cc169af66260223e500e3822f852784c8", - "reference": "ed77856cc169af66260223e500e3822f852784c8", + "url": "https://api.github.com/repos/JustSteveKing/api-toolbox/zipball/5f1978fa4d5d8e90806e3a9394524f3ae9ce5398", + "reference": "5f1978fa4d5d8e90806e3a9394524f3ae9ce5398", "shasum": "" }, "require": { @@ -1120,9 +1120,9 @@ ], "support": { "issues": "https://github.com/JustSteveKing/api-toolbox/issues", - "source": "https://github.com/JustSteveKing/api-toolbox/tree/v0.3.2" + "source": "https://github.com/JustSteveKing/api-toolbox/tree/v0.3.3" }, - "time": "2026-10-20T19:55:31+00:00" + "time": "2026-10-29T13:27:48+00:00" }, { "name": "laminas/laminas-diactoros", diff --git a/vet.json b/vet.json index f2fc7bc..36ca2c0 100644 --- a/vet.json +++ b/vet.json @@ -53,8 +53,8 @@ "hash": "tree-v2:c5f332afdb641a8e51865f5fe4448a3c4c2d9ec959e76360003b5489525deaf6" }, "juststeveking/api-toolbox": { - "version": "v0.3.2", - "hash": "tree-v2:922ab467587f40da7d9c80cc6e528ca53351d190c2388857cbf9569476231a97" + "version": "v0.3.3", + "hash": "tree-v2:9702f3be02ea51ac9774e538e51e6c06b902058440c22b41cbceeaf17e678d5a" }, "laminas/laminas-diactoros": { "version": "3.9.0", From c8b5178daf50b5e8bb7816580e8ddf00dc4e9706 Mon Sep 17 00:00:00 2001 From: Steve McDougall Date: Fri, 30 Oct 2026 09:44:34 +0000 Subject: [PATCH 2/2] A sunset endpoint answers apiguide.dev's endpoint-sunset RetireSunsetEndpoints answered plain gone, which also fits a deleted record. apiguide.dev now has endpoint-sunset for exactly this, an interface retired on purpose, which tells a client the fault is in its code and asks for the replacement in the body. The 410 throws the new App\Problems\EndpointSunset (made with make:api-problem --apiguide) carrying deprecatedAt, sunsetAt and migrationGuide, the #[Sunset] link or else the #[Deprecation] one. --- AGENTS.md | 2 +- app/Http/Middleware/RetireSunsetEndpoints.php | 21 +++++++++++++++---- app/Problems/EndpointSunset.php | 16 ++++++++++++++ docs/http-standards.md | 6 +++++- tests/Feature/DeprecationTest.php | 11 ++++++++-- 5 files changed, 48 insertions(+), 8 deletions(-) create mode 100644 app/Problems/EndpointSunset.php diff --git a/AGENTS.md b/AGENTS.md index 191702c..8323288 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -132,7 +132,7 @@ api-toolbox is configured in `config/api-toolbox.php`. Before hand-rolling any o | Cheap re-fetches of a resource | `conditional` middleware (ETag, `304`) | | Stop lost updates | the model implements `HasValidators` and is bound to the route, which adds `conditional` and `preconditions.required`: the first gives the `412`, the second only the `428` | | A `PATCH` | `merge-patch` and `consumes:application/merge-patch+json`, which replaces the group's `consumes:` | -| Retire an endpoint | `#[Deprecation]` and `#[Sunset]` on the controller class; Kit answers `410` after the sunset date | +| Retire an endpoint | `#[Deprecation]` and `#[Sunset]` on the controller class; Kit answers `410` (`endpoint-sunset`) after the sunset date | | Work that outlives the request | Async operations; switched off in the config, and turning it on adds a route to document | | Signed webhooks | Message signatures; keys go in the config, never in code | diff --git a/app/Http/Middleware/RetireSunsetEndpoints.php b/app/Http/Middleware/RetireSunsetEndpoints.php index f236975..9f9f532 100644 --- a/app/Http/Middleware/RetireSunsetEndpoints.php +++ b/app/Http/Middleware/RetireSunsetEndpoints.php @@ -4,18 +4,23 @@ namespace App\Http\Middleware; +use App\Problems\EndpointSunset; use Closure; use DateTimeImmutable; use Illuminate\Http\Request; use Illuminate\Routing\Route; use JustSteveKing\Toolbox\Deprecation\Contracts\DeprecationSource; +use JustSteveKing\Toolbox\Deprecation\Notice; use Symfony\Component\HttpFoundation\Response; /** * Answers 410 Gone once a route's #[Sunset] date has passed. * * RFC 8594 section 1 says a resource is expected to become unresponsive at its sunset. api-toolbox - * sends the Deprecation and Sunset headers; this enforces the date those headers announce. + * sends the Deprecation and Sunset headers; this enforces the date those headers announce. The + * problem is apiguide.dev's endpoint-sunset rather than plain gone: the interface was retired on + * purpose, so the fault is in the client's code, not its data, and the body says when and where to + * go instead, as that entry asks. */ final readonly class RetireSunsetEndpoints { @@ -31,11 +36,19 @@ public function handle(Request $request, Closure $next): Response $route = $request->route(); if ($route instanceof Route) { - $sunsetAt = $this->deprecations->forRoute($route)?->sunsetAt; + $notice = $this->deprecations->forRoute($route); + $sunsetAt = $notice?->sunsetAt; // Laravel's clock rather than the system's, so a test can travel past a sunset. - if ($sunsetAt instanceof DateTimeImmutable && $sunsetAt <= now()->toDateTimeImmutable()) { - abort(Response::HTTP_GONE, __('api.sunset.endpoint_unavailable')); + if ($notice instanceof Notice && $sunsetAt instanceof DateTimeImmutable && $sunsetAt <= now()->toDateTimeImmutable()) { + throw new EndpointSunset( + detail: __('api.sunset.endpoint_unavailable'), + extensions: array_filter([ + 'deprecatedAt' => $notice->deprecatedAt?->format(DATE_ATOM), + 'sunsetAt' => $sunsetAt->format(DATE_ATOM), + 'migrationGuide' => $notice->sunsetLink ?? $notice->deprecationLink, + ], static fn(?string $value): bool => null !== $value), + ); } } diff --git a/app/Problems/EndpointSunset.php b/app/Problems/EndpointSunset.php new file mode 100644 index 0000000..3dfb45f --- /dev/null +++ b/app/Problems/EndpointSunset.php @@ -0,0 +1,16 @@ +get($path, RetiredEndpoint::class); $this->getJson($path) - ->assertProblemType('https://apiguide.dev/errors/gone', 410) + ->assertProblemType('https://apiguide.dev/errors/endpoint-sunset', 410) + ->assertJsonPath('title', 'Endpoint Sunset') ->assertJsonPath('detail', __('api.sunset.endpoint_unavailable')) + ->assertJsonPath('deprecatedAt', '2000-01-01T00:00:00+00:00') + ->assertJsonPath('sunsetAt', '2001-01-01T00:00:00+00:00') + ->assertJsonMissingPath('migrationGuide') ->assertDeprecated('2000-01-01T00:00:00Z') ->assertSunset('2001-01-01T00:00:00Z'); }); @@ -40,7 +44,10 @@ $this->travelTo(new DateTimeImmutable('2099-01-01T00:00:01Z')); - $this->getJson($path)->assertProblemType('https://apiguide.dev/errors/gone', 410); + // The sunset's link is where to go instead (apiguide.dev's endpoint-sunset asks for it). + $this->getJson($path) + ->assertProblemType('https://apiguide.dev/errors/endpoint-sunset', 410) + ->assertJsonPath('migrationGuide', 'https://docs.example.com/sunset-policy'); }); it('serves deprecated endpoints that have no sunset date', function (): void {