Skip to content

Content negotiation treats an Accept q-weight as a media type parameter, so Accept: application/vnd.api+json;q=0.9 gets a spurious 406 #101

Closed

Description

@thomasfosterau

What's wrong

Middleware.acceptIsAcceptable parses each Accept entry with parseMediaType and then runs every parameter it finds through parametersAreAcceptable, which rejects anything that isn't ext or profile:

https://github.com/thomasfosterau/effect-jsonapi/blob/main/src/Middleware.ts — parametersAreAcceptable:

for (const [name, value] of parameters) {
  if (name === "profile") continue
  if (name === "ext") { /* … */ continue }
  // Any parameter other than ext / profile is unacceptable.
  return false
}

But q is not a media type parameter. Per RFC 9110 §12.4.2, q is the weight of an Accept entry, and it terminates the media type's own parameter list — everything before q is a media type parameter, q and everything after it are accept-extension parameters belonging to the header field, not to the representation. JSON:API §Content Negotiation constrains the media type's parameters (ext / profile), so a weight must not be counted against that rule.

Repro

Running the current parseMediaType / parametersAreAcceptable / acceptIsAcceptable logic verbatim:

"application/vnd.api+json"                        => acceptable: true
"application/vnd.api+json;q=0.9"                  => acceptable: false   ❌ should be true
"application/vnd.api+json; q=1"                   => acceptable: false   ❌ should be true
"application/vnd.api+json;q=0"                    => acceptable: false   ✅ but for the wrong reason
"text/html;q=0.9, application/vnd.api+json;q=0.8" => acceptable: false   ❌ should be true
"application/vnd.api+json, text/html;q=0.9"       => acceptable: true

The third case is the one that bites hardest: any client that expresses a preference between HTML and JSON:API on a shared origin gets a 406 from an API that does in fact serve JSON:API.

The same bug is latent in contentTypeIsAcceptable, though a q on Content-Type is meaningless so it matters much less there.

Expected

  • q (and any accept-extension parameter following it) is stripped before the ext / profile check.
  • q=0 on the JSON:API instance is an explicit refusal of that representation — it should make the entry not count as acceptable, rather than being rejected as a bad parameter. If it is the only JSON:API instance, that is a genuine 406.
  • Non-zero q values are accepted.

Ideally Middleware.negotiate would also expose the resolved weight so a host that serves more than one representation on a URL can choose between them, rather than only answering "acceptable / not".

Why it matters here

All three application repos audited (thomasfosterau/website, thomasfosterau/preferenceflow, thomasfosterau/gardeneria) serve HTML and JSON:API on the same origin, so they receive Accept headers with weights on every request. All three therefore opt out of the package's negotiation entirely — they wire Middleware.layerHostNegotiated (whose ContentNegotiationPassthrough performs no §5 check) and hand-roll ~420 lines of packages/api/src/negotiate.ts, which contains this comment:

/** The `q=` quality of an `Accept` instance (default 1; `q` is not a media-type param). */

and treats q=0 as "an explicit refusal, not a §6 parameterisation".

That is three independent consumers reimplementing the header parsing the package already ships, because the shipped one can't be used against real Accept headers. Fixing this is the single highest-leverage change for making Middleware.ContentNegotiationLive usable by a host that isn't JSON:API-only.

Suggested tests

src/Middleware.test.ts currently has no coverage for q at all. Worth pinning:

  • application/vnd.api+json;q=0.9 → acceptable
  • application/vnd.api+json;q=0 → not acceptable
  • text/html;q=0.9, application/vnd.api+json;q=0.8 → acceptable
  • application/vnd.api+json;profile="…";q=0.8 → acceptable (parameter and weight)
  • application/vnd.api+json;charset=utf-8;q=0.8 → not acceptable (a real bad parameter, weight notwithstanding)

Metadata

Metadata

Assignees

No one assigned

    Labels

    P1bugSomething isn't working

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions