fix: Add support for the Deprecation header

[aaa2000]

Q	A
Branch?	4.2
Tickets	Closes #5889
License	MIT

Add support for the Deprecation header

Uses the headers property of the APIResource directly to send the headers.

It is not configured like the sunset header; the sunset header can also be overridden via the headers.
If both the sunset property and the header are configured, the sunset property takes precedence.

#[ApiResource(
    operations: [new GetCollection(provider: [self::class, 'provide'])],
    headers: [
        'Deprecation' => '@1688169599',
        'Sunset' => 'Sun, 30 Jun 2024 23:59:59 UTC',
        'Link' => '<https://developer.example.com/deprecation>; rel="deprecation"; type="text/html"',
    ],
)]

The developer experience is less enjoyable because it's necessary to ensure the correct formatting of date.

curl -X 'GET' \
  'http://127.0.0.1:40185/deprecation_headers?page=1&itemsPerPage=3' \
  -H 'accept: application/ld+json'

cache-control: max-age=60,public,s-maxage=3600  
cache-tags: /deprecation_headers/1,/deprecation_headers/2,/deprecation_headers  
deprecation: @1688169599  
link: <http://127.0.0.1:40185/docs.jsonld>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation",<https://developer.example.com/deprecation>; rel="deprecation"; type="text/html" 
...

This can be seen as a bug fix because the header link could not be defined; it was being overridden by src/State/Processor/AddLinkHeaderProcessor.php

[soyuka]

Interesting, note that we also have the $operation->getSunset() and the $operation->getDeprecationReason() (for docs).

but we don't support yet the Deprecation header (https://datatracker.ietf.org/doc/rfc9745/).

By looking into this we should support web links through $operation->getLinks :

core/src/Metadata/HttpOperation.php

Line 93 in 64768a6

* @param WebLink[]|null $links

like this it's easier to compose with multiple links, I note that we're missing some docs on this (and I don't see any functional test where user defines links so we may have a bug after all).

[aaa2000]

This works with the link property of HttpOperation.

This doesn't seem problematic; the type of link cannot be defined. I updated the unit test

deprecation: @1688169599 
link: <https://developer.example.com/deprecation>; rel="deprecation",<http://127.0.0.1:8000/docs.jsonld>; rel="http://www.w3.org/ns/hydra/core#apiDocumentation"  
sunset: Sun,30 Jun 2024 23:59:59 UTC 

So, can the PR be closed, or should the "deprecation" property be promoted as a property of HttpOperation ?

[soyuka]

Thanks I'll merge the test anyway, maybe that we're missing some documentation on the subject

I think headers is more explicit, if you think we'd need an HTTP abstraction layer for deprecation we can add it on the resource, not sure about this one...