feat(gateway): IPIP-523 format query over Accept header#1074
Merged
Conversation
…pt header this change simplifies precedence rules by making the ?format= URL query parameter always take priority over the Accept HTTP header when both are present. in practice, this is largely compatible with existing browser use cases since browsers send Accept headers with wildcards which were already treated as non-specific. prioritizing ?format= also ensures deterministic HTTP caching behavior, protecting against CDNs that comingle different response types under the same cache key. the only breaking change is for edge cases where a client sends both a specific Accept header and a different ?format= value. previously Accept would win, now ?format= wins. this scenario is rare and arguably represents client misconfiguration. when detected, gateway returns HTTP 400 to signal the ambiguity. specs: ipfs/specs#523 tests: ipfs/gateway-conformance#252
Codecov Report❌ Patch coverage is
@@ Coverage Diff @@
## main #1074 +/- ##
==========================================
+ Coverage 61.06% 61.10% +0.03%
==========================================
Files 264 264
Lines 26221 26237 +16
==========================================
+ Hits 16013 16031 +18
+ Misses 8527 8526 -1
+ Partials 1681 1680 -1
... and 5 files with indirect coverage changes 🚀 New features to boost your workflow:
|
lidel
added a commit
to ipfs/kubo
that referenced
this pull request
Dec 2, 2025
update boxo to ipfs/boxo#1074 and gateway-conformance tests to ipfs/gateway-conformance#252 for testing IPIP-523 changes where ?format= URL query parameter takes precedence over Accept HTTP header
2 tasks
lidel
added a commit
to ipfs/kubo
that referenced
this pull request
Dec 2, 2025
update boxo to ipfs/boxo#1074 and gateway-conformance tests to ipfs/gateway-conformance#252 for testing IPIP-523 changes where ?format= URL query parameter takes precedence over Accept HTTP header
remove HTTP 400 error for conflicting ?format and Accept values. instead, ?format silently takes precedence, which is simpler and less breaking for browser clients that send Accept headers automatically.
lidel
added a commit
to ipfs/kubo
that referenced
this pull request
Dec 2, 2025
update boxo to ipfs/boxo#1074 and gateway-conformance tests to ipfs/gateway-conformance#252 for testing IPIP-523 changes where ?format= URL query parameter takes precedence over Accept HTTP header
lidel
commented
Dec 2, 2025
3 tasks
temporary switch to ipfs/gateway-conformance#252
lidel
commented
Feb 4, 2026
Member
Author
There was a problem hiding this comment.
Switched to gateway-conformance@v0.9, merging.
This is low risk change, we will test on gateway staging with Kubo 0.40.0-rc1.
lidel
added a commit
to ipfs/kubo
that referenced
this pull request
Feb 4, 2026
lidel
added a commit
to ipfs/kubo
that referenced
this pull request
Feb 4, 2026
* test: IPIP-523 format query precedence over Accept header update boxo to ipfs/boxo#1074 and gateway-conformance tests to ipfs/gateway-conformance#252 for testing IPIP-523 changes where ?format= URL query parameter takes precedence over Accept HTTP header * chore: update boxo and gateway-conformance for IPIP-523 testing - boxo@9aeb0c835899fedb4f886040a4ccf3ba09fd97d4 - gateway-conformance@c82a2a9bc79303e0f07216a80cf454ef2a1e042c * chore(ci): switch to gateway-conformance@v0.9 * chore: update boxo with IPIP-523 changes * chore: update boxo to main after ipfs/boxo#1074 merge * docs: add gateway-conformance v0.9 to changelog
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
this change simplifies precedence rules by making the
?format=URL query parameter always take priority over the Accept HTTP header when both are present.in practice, this is largely compatible with existing browser use cases since browsers send Accept headers with wildcards which were already treated as non-specific. prioritizing
?format=also ensures deterministic HTTP caching behavior, protecting against CDNs that commingle different response types under the same cache key.the only breaking change is for edge cases where a client sends both a specific
Acceptheader and a different?format=value. previouslyAcceptwould win, now?format=wins. this scenario is rare and arguably represents client misconfiguration. when detected, gateway returns HTTP 400 to signal the ambiguity.TODO