Skip to content

feat(gateway): IPIP-523 format query over Accept header#1074

Merged
lidel merged 7 commits intomainfrom
feat/ipip-0523-format-precedence
Feb 4, 2026
Merged

feat(gateway): IPIP-523 format query over Accept header#1074
lidel merged 7 commits intomainfrom
feat/ipip-0523-format-precedence

Conversation

@lidel
Copy link
Member

@lidel lidel commented Dec 1, 2025

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 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.

TODO

…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
@lidel lidel requested review from a team and achingbrain December 1, 2025 23:38
@codecov
Copy link

codecov bot commented Dec 1, 2025

Codecov Report

❌ Patch coverage is 96.29630% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 61.10%. Comparing base (63b6a19) to head (d17c0a2).
⚠️ Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
gateway/handler_car.go 83.33% 0 Missing and 1 partial ⚠️

Impacted file tree graph

@@            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     
Files with missing lines Coverage Δ
gateway/handler.go 78.62% <100.00%> (+0.71%) ⬆️
gateway/handler_car.go 79.71% <83.33%> (-1.45%) ⬇️

... and 5 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

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 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
Copy link
Member Author

@lidel lidel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CI with end-to-end tests at

are green.

AFAIK this PR is a low risk change (see Compatibility section in IPIP-523)

@lidel lidel marked this pull request as ready for review December 2, 2025 01:02
Copy link
Member Author

@lidel lidel left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 lidel merged commit 2688767 into main Feb 4, 2026
19 checks passed
@lidel lidel deleted the feat/ipip-0523-format-precedence branch February 4, 2026 01:18
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant