Answer the header versioner's common Accept headers from a table built once

[ericproulx]

Summary

• version ..., using: :header ran Rack::Utils.best_q_match (which splits both strings inside Rack::Mime.match? for every candidate) and a MediaType.parse on every request: about 3.6 µs of a 12.4 µs request. Its answer depends only on the Accept header and the middleware's available_media_types, which is fixed once the middleware is built.
• Versioner::Header::MediaTypeForAcceptCache computes that answer once for every declared media type, for */* (what curl, Net::HTTP and most HTTP libraries send) and for no Accept header, and the versioner looks the header up. Any other header (q-value lists, another casing) misses and takes the unchanged full path. Only declared media types are keys, so client input cannot grow a table, and each entry is computed by the real function, so a hit answers exactly what the full path would.
• Every endpoint builds its own versioner, so the table is shared per list through Grape::Util::Cache, as ContentTypes::MimeTypesCache already is.
• Grape::Util::MediaType is now immutable, strings included.

Contract change

The strings the header versioner writes into the env (api.type, api.subtype, api.vendor, api.version, api.format) are now frozen, since requests sending the same Accept header share one parsed media type. They are frozen on the full path too, so behaviour does not depend on which Accept header came in. Code that altered one of them in place now raises FrozenError; UPGRADING has an entry. MediaType#initialize copies its arguments rather than freezing the caller's Strings.

Benchmarks

Median of 7 interleaved subprocess rounds against master, Ruby 4.0.6:

request	no JIT	YJIT
Accept: application/vnd.acme-v1+json	+55.4%	+79.6%
Accept: */*	+43.1%
no Accept header	+19.3%
path-versioned GET (control)	−0.8% (noise)

Boot, 500 header-versioned endpoints: +16 KB retained, +1 ms compile. A table built per instance cost +3.5 MB and +120 ms, which is why it is shared.

Behaviour

Byte-identical to master over a 150-case matrix, apart from the frozen strings: 5 APIs (one version, two versions, strict, cascade: false, dotted vendor and version) × 30 Accept values, including q-value lists, wildcards, other casings, surrounding whitespace, parameters, invalid bytes and binary-encoded headers.

Test plan

• Full RSpec suite passes locally.
• RuboCop clean.
• New spec, 'cannot be altered by one request for the next'. Mutation-checked: leaving the version or the subtype unfrozen fails it; making the table answer the default for every key fails 7 existing specs.
• CI green.

🤖 Generated with Claude Code

[github-actions]

Danger Report

No issues found.

View run

[ericproulx]

Closing in favour of #2936, which combines #2922–#2934 into one PR, re-benchmarked as a whole against master. The write-up here (behaviour matrix, mutation results) still describes this part of the change.