[feature] request module: Accept-header parsing and content negotiation

[joewiz]

[This PR was co-authored with Claude Code. -Joe]

Summary

Adds reusable HTTP content negotiation to the request module (http://exist-db.org/xquery/request), so applications no longer have to hand-roll Accept-header parsing:

request:negotiate-content-type($available as xs:string*) as xs:string?
request:negotiate-content-type($available as xs:string*, $default as xs:string?) as xs:string?
request:parse-accept-header() as map(*)*

Motivation

Content negotiation is currently left to each app developer. The request module exposes only the raw header (request:get-header("Accept")) — no quality-value parsing, no media-type matching — and the REST server does no Accept negotiation at all. This surfaced while reviewing the eXide login PR (eXist-db/eXide#801): the underlying gap is that there's no shared primitive, so every consumer either ignores Accept or re-derives a partial parser.

Notably, no XQuery platform exposes a q-weighted negotiation primitive — the RESTXQ spec stops at "absolute before wildcard" specificity, the request module and EXQuery have nothing, and BaseX's q-factor handling is an extension inside its own RESTXQ engine. The function shape here follows the convergent practice of mature HTTP frameworks: JAX-RS Request.selectVariant, Spring MediaType, Node's negotiator, Werkzeug's MIMEAccept.best_match, and Go's httputil.NegotiateContentType — all "give the server's offers, get the best match, or nothing → 406."

What the functions do

request:negotiate-content-type($available[, $default]) — selects the best media type the server can produce for the current request's Accept header (RFC 7231 §5.3.2: quality values and */* / type/* wildcards). An empty or absent Accept means "no preference," so the first offer wins. Returns the empty sequence — or $default, in the 2-arg form — when nothing is acceptable, so the caller can respond 406 Not Acceptable.

(: Accept: text/html, application/json;q=0.9, */*;q=0.8 :)
request:negotiate-content-type(("application/json", "application/xml"))   (: => "application/json" :)

(: Accept: application/json :)
request:negotiate-content-type(("application/xml"))                       (: => ()  -> caller sends 406 :)
request:negotiate-content-type(("application/xml"), "application/xml")    (: => "application/xml" :)

request:parse-accept-header() — parses the Accept header into a quality-ranked sequence of maps, for callers that want to build their own logic:

(: Accept: text/html;level=1, application/json;q=0.9 :)
request:parse-accept-header()
(: => ( map { "type": "text/html",       "quality": 1.0e0, "parameters": map { "level": "1" } },
        map { "type": "application/json", "quality": 0.9e0, "parameters": map { } } ) :)

Implementation

The parsing and negotiation logic lives in a pure, request-independent helper (org.exist.http.AcceptHeader), so the REST server, Roaster, and any other caller can reuse the exact same algorithm; the two XQuery functions are thin request-bound wrappers. A follow-up will have Roaster adopt this in place of its partial hand-rolled negotiation.

Tests

• AcceptHeaderTest — 15 unit cases over parse (ordering by quality then specificity, q defaulting, parameters, q=0 retention, malformed/empty input) and negotiate (highest-quality pick, exact-over-wildcard, q=0 rejection, type/* wildcards, no-Accept/*/* → first offer, no-match → empty, tie-break by offer order).
• RESTServiceTest — 2 integration cases exercising both functions end-to-end over HTTP with a real Accept header.

Related

Separate small PR fixes an eXist-core bug this work brushed against: RESTServer.writeResultJSON never set Content-Type (so output:media-type was ignored for JSON REST results). That one stands alone.

[line-o]

Clean - no notes.