Support HTTP QUERY method (RFC 10008) end-to-end (proxy, plugins, body-keyed cache)

[ebremer]

Summary

RFC 10008 defines QUERY — a safe, idempotent, cacheable HTTP method that carries a request body whose content defines the query. It fills the gap between GET (no body / URL-length limits) and POST-as-read (unsafe, uncacheable by default).

As an API gateway, Kong sits on the path of QUERY adoption. Clients and backends are starting to use QUERY (e.g. Node/undici, Tomcat, LWS Search/Type Index). Without explicit support, gateways often reject unknown methods, strip bodies, skip retries, or cache incorrectly.

Why Kong

QUERY only works end-to-end if Kong:

1. Accepts and proxies QUERY with its body from a matching Route to the Gateway Service / upstream.
2. Treats QUERY as safe + idempotent for Service retries (same class as GET/HEAD, not POST).
3. When Proxy Cache / Proxy Cache Advanced is enabled: builds a cache key that MUST include the request content (and related metadata such as Content-Type) per RFC 10008 §2.7.

Today, Kong’s docs leave gaps:

• Service retries only list idempotent methods as GET, HEAD, PUT, DELETE, OPTIONS, and TRACE. QUERY is not included, so QUERY is treated like a non-idempotent method and will not be retried by default.
• Proxy Cache keys each entry from method, request line, query parameters, headers, consumer groups, and API/Consumer UUID — not the request body. For QUERY, the body is the query; two different bodies on the same path must not share a cache entry.

Ask

Please support RFC 10008 across Kong Gateway, in particular:

1. Proxy / routing

• Accept QUERY and proxy method + body to the upstream (HTTP/1.1, HTTP/2, HTTP/3 as applicable).
• Route methods: allow QUERY in the methods list; document it alongside GET/POST/….
• Do not default-reject QUERY as an unknown or unsupported method.

2. Service retries

• Add QUERY to the idempotent retry set used on connect/read/write timeout failures (with GET, HEAD, PUT, DELETE, OPTIONS, TRACE).
• Update Gateway Service docs accordingly.

3. Plugins that special-case methods

Audit method-sensitive plugins so QUERY is handled correctly, e.g.:

• Request size / body plugins: allow a body on QUERY (same limits as POST where applicable).
• Auth plugins (key-auth, JWT, OIDC, ACL, …): authorize QUERY; expose method (and body or a defined subset) where policy depends on the request.
• Rate limiting, logging, analytics: record QUERY distinctly.
• CORS: treat QUERY as non-safelisted (preflight expected).
• Redirect-related behaviour: preserve QUERY + body on 301/302/307/308; do not POST→GET-style downgrade that empties the body (RFC 10008 §2.5).

4. Proxy Cache / Proxy Cache Advanced

• Allow caching successful QUERY responses when plugin config / cache headers permit (include QUERY in configurable request methods if the plugin whitelists methods).
• Cache key must incorporate request body (+ Content-Type / relevant representation metadata) per §2.7.
• Current key shape (method | request | query_params | headers | …) is not enough for QUERY.
• Practical constraints welcome (max body size for keying; Bypass if body not buffered).