We are the authors of a proxying server and have the ability to proxy python packages. We additionally allow policies to be created to only allow certain packages to be fetched (licensing, malware etc)
The HTTP/1.x standards response status code also has the ability to optionally contain a reasonPhrase, this reasonPhrase we have previously used to provide additional context as to why the fetch of a component is getting blocked. We would provide a url link which would be presented to the end user who could then take the necessary action.
RFC9113 HTTP/2 does not contain a reasonPhrase and as such end users no longer have the extra context as to why a component has not been fetched (403 can have many meanings). Other formats have taken to using headers as part of the response to communicate this extra context, for example Huggingface uses X-Error-Messag.
I initially created a PR (Im a new member so cant post more than 2 links ) for the UV project (with a view to also contributing to other client tools) and was advised to see if this change could be part of a PEP. Note that PEP792 does not cover this use case as that standard covers the project and not an individual version.
I would like to see if an update to the relevant PEP could add a similar header style response for this type of communication.
Instead of a header, please consider using the RFC9457 mechanism. It’s widely supported by HTTP client libraries and offers the ability to include structured data in the response, unlike a response header.
I was actually the author of the RFC9457 implementation for Maven which is where this journey started. One downside to that standard is that it will only cater for GET requests because of the json body requirement.
I would be happy to have RFC9457 added as a PEP as long as we do not start making use of HEAD requests.
To carry over some context from the uv PR into this discussion, could you describe an error scenario (like the most common those filters emit), what it currently looks like to a user and what it could looks like with X-Error-Message or something functionally equivalent?
Certainly, so at the moment using HTTP/1.X you would see a message like the screenshot below because HTTP/1.X contains a reasonPhrase and therefore context on why the fetch failed ‘Requested item has been quarantined’ with a link for the user to take further action.
As you can see there is a 403 status code but no reason as to why the download has failed. Lack of context could signal anything from network error to component quarantined.
Please note that the HTTP standard explicitly discourages using the reasonPhrase:
The reason-phrase element exists for the sole purpose of providing a textual description associated with the numeric status code, mostly out of deference to earlier Internet application protocols that were more frequently used with interactive text clients.
[…]
A client SHOULD ignore the reason-phrase content because it is not a reliable channel for information (it might be translated for a given locale, overwritten by intermediaries, or discarded when the message is forwarded via other versions of HTTP).
(Which is why another method such as the headers as suggested by @doddi76 or Problems Details standard as suggested by @kpfleming is to be preferred.)
(I asked @doddi76 to bring the conversation here. Thanks a ton @doddi76!)
For some additional context: part of the challenge here is that the PEP 503/691 index definitions don’t describe what indexes should do if they can’t service a request for any reason (including reasons of policy, which are the use case above). So, if this is the kind of thing we want installers like pip and uv to support consistently, we need (1) consensus on an error representation form, and (2) a packaging PEP that augments the existing simple APIs to describe how error responses in the 400..600 range behave.
For my 0.02c: I like the design in RFC 9457, and it seems nice to have indices adopt an RFC rather than innovate something through the PEP process here.
Regarding HEAD requests, we do need to make a HEAD request against a wheel file if PEP 658 is not supported by the index, to check if we can use range requests. That means we need PEP 658 implemented in an index to be able to rely on RFC 9457 with GET requests.
FYI, I have created a PR for the RFC9457 implementation in the UV project to see what would be required. A colleague of mine is also looking to do the same for the PyPi project.
Is there a process we need to follow to take this idea from discussion to realisation? I am unfamiliar with the PEP process.
) for the UV project (with a view to also contributing to other client tools) and was advised to see if this change could be part of a PEP. Note that PEP792 does not cover this use case as that standard covers the project and not an individual version.
