IPIP-0548: Sunset X-Ipfs-Path header

1. Summary

Replace X-Ipfs-Path header with Ipfs-Uri version that can correctly encode any special characters likely to be found in an IPFS Path.

2. Motivation

HTTP header values can only include characters from a limited set.

There is a gap in the existing gateway specification in that it does not say how characters from outside this set are to be treated.

Values already arrive broken: browser fetch() garbles raw UTF-8, and Go's net/http replaces CR and LF with spaces.

The spec is implemented and consumed widely so retrospectively adding encoding rules would be disruptive, and we would have to agree on an encoding format.

URIs already have a well-defined encoding format (percent encoding, defined in RFC 3986), so introduce an Ipfs-Uri header to be used in preference to X-Ipfs-Path which can handle any and all characters found in an IPFS path, and can be losslessly converted back into an IPFS Path if the client desires it.

3. Detailed design

The Ipfs-Uri header should be added which contains the IPFS/IPNS path as a URI (e.g. ipfs://... or ipns://...) with any special characters percent-encoded as per RFC 3986.

The URI schemes are defined by [ipfs-uri] and [ipns-uri]; the Ipfs-Uri section of [path-gateway] defines the exact serialization.

This IPIP also updates [unixfs]: names containing / join the restricted names list, and the path escaping section defines the HTTP gateway and URI behavior while leaving other contexts unspecified.

Ipfs-Uri deprecates X-Ipfs-Path, and clients SHOULD prefer Ipfs-Uri when both are present. The X-Ipfs-Path section says when the legacy header MUST be omitted to avoid issues with unsafe byte ranges.

4. Design rationale

Retroactively adding encoding rules to X-Ipfs-Path would be too disruptive to existing clients so adding a new header and deprecating the old one seems like the least worst way forward.

Path escaping was previously undefined across the stack: the UnixFS spec explicitly declared it out of scope, and nothing said how gateways decode request paths or how a content path becomes a header-safe string. This IPIP locks that behavior down: request path components are percent-decoded once (so %2F is a component separator), Ipfs-Uri is the canonical encoded form, and names containing / are formally not path-addressable.

5. Test fixtures

A UnixFS directory under bafybeiflhd5aimv4xavauidbetge3v3uadbqfibu5lfo4b26yyieqvnvae (dir-with-tricky-filenames.car in ipip-0548-test-fixtures.zip), and the header returned for each file in it:

A second fixture, the preexisting dir-with-percent-encoded-filename.car directory under bafybeig675grnxcmshiuzdaz2xalm6ef4thxxds6o6ypakpghm5kghpc34, holds a name that already looks percent-encoded. The literal %2C is encoded again (%252C), never decoded into a comma, and + and = do not pass through raw:

A third fixture, dir-with-slash-in-filename.car under bafybeihuqitp4tzukehqfyaozl6zexd7szyzeywojuynfxopnn7dqjepv4, holds a real subdirectory a with b.txt inside, plus a sibling link literally named a/b.txt. Such a link is legal in dag-pb but not addressable by any content path: %2F decodes to a separator, so every spelling resolves to the nested file:

The gateway-conformance test suite uses these directories to test Ipfs-Uri and the legacy X-Ipfs-Path behavior.