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 { 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",