nginx passes the new HTTP QUERY method through but cannot cache it

The web has a new HTTP method. QUERY, standardized in RFC 10008, which the IETF published in June, is meant to fix a long-standing gap in how read-only requests carry parameters. A hands-on write-up on dev.to finds that the surrounding infrastructure is only half ready: nginx, one of the most widely deployed reverse proxies, forwards QUERY requests without complaint, but its caching layer rejects the method outright, which undercuts the main reason QUERY exists.

What QUERY is for

According to the dev.to post, QUERY behaves like a GET that is allowed to carry a request body. It is safe and idempotent, it is cacheable, and the RFC adds one condition: whatever the body contains must be reflected in the cache key. The motivating case is the read whose parameters are too large or too awkward to fit sensibly in a URL. Today those requests travel as POSTs, and in practice nothing downstream ever caches the response.

The test rig

To see how much of the surrounding machinery is actually ready, the author built a search API over the RFC index, 9,836 entries, that answers only to QUERY. Any other method gets a 405 with an Allow header naming QUERY. The strictness was intentional: a server that also tolerated POST would have silently absorbed the interesting failures.

Much of the post is an experiment pointing language models at this endpoint. When the prompt explicitly named QUERY and RFC 10008, all eight models the author could reach produced working clients; Python's urllib, for instance, accepts any string as a method argument. When the prompt omitted the method, all eight defaulted to POST, and none tried an OPTIONS probe first. Shown the full 405 response, only four of the eight switched to QUERY correctly. One used QUERY but moved the filters into the URL and sent an empty body, discarding the very problem the method solves; another tried GET, which the same server had just refused. Two models, unprompted, had written clients that caught the 405 and retried with the method named in the Allow header. Interesting, but the author's more consequential finding sits a layer lower in the stack.

Where nginx stops

Proxying works: with nginx in front of the API, every QUERY request passes through untouched. Caching does not. The proxy_cache_methods directive accepts GET, HEAD and POST, and the list cannot be extended. Listing QUERY there stops the server from starting; the author's nginx -t run fails, with the error naming QUERY as an invalid value for the directive.

The obvious workaround also fails, for a subtle reason. You can rewrite the method upstream with proxy_method POST and declare POST cacheable, but nginx evaluates proxy_cache_methods against the method the client actually sent, not the one it forwards. The author verified this by holding the config and request body constant and varying only the method on the wire: four requests sent as QUERY all reached the backend while the cache did nothing, whereas of four requests sent as POST, only one reached the backend and three were served from cache. There is not even a cache-status header to hint that nginx declined to act.

One more trap for implementers

The post also documents a server-side gotcha discovered along the way. Node's http module does not set Content-Length for a method it has no opinion about and reaches for chunked transfer encoding instead. A server that only reads Content-Length sees an empty body, then chokes on the unread chunks when the keep-alive connection is reused, producing confusing parse errors that look like a client bug. Anyone writing a QUERY server needs to handle chunked bodies.

Why it matters

QUERY is one of the rare web-platform changes deployers will actually meet on the wire, and the early picture is lopsided. The parts of the stack that merely move bytes, standard libraries, clients and proxies, are essentially ready, while the caching infrastructure is not. As the dev.to author frames the irony, the method the RFC designed to be cacheable cannot be cached by the proxy much of the internet runs on, while POST, which was never meant to be cached, can be. Teams adopting QUERY behind nginx today get the semantic benefits but none of the caching payoff, and they should expect silent non-caching rather than a visible failure, at least until nginx widens the set of methods proxy_cache_methods accepts.