http-query
A client and server SDK for the HTTP QUERY method (RFC 10008) in Rust.
QUERY is a safe and idempotent request method that carries a request
body describing a query to run against the target resource. It combines the
best of GET (safe, cacheable, retryable) and POST (arbitrary request body):
the query travels in the body instead of the URI.
[]
= "0.1"
Sending a query
The async client is built on reqwest
(the client feature, enabled by default).
use Client;
# async
Result vs. equivalent resource
A QUERY response can advertise two distinct GET-retrievable URIs
(RFC 10008 §2.3–2.4):
Content-Location— the stored result of the query just run.Client::fetch_resultfollows it.Location— the equivalent resource, whoseGETre-runs the query.Client::fetch_equivalentfollows it.
Discovering support
Accept-Query is an RFC 9651
Structured Fields List; it is parsed and serialized correctly (quoted strings,
parameters, */* and type/* wildcards).
# async
Redirects
QUERY redirects are handled per RFC 10008 §2.5:
301/302/307/308 re-issue the QUERY with its body, while only 303
switches to GET. Client::new disables reqwest's own redirect following so
the SDK can apply these rules (the transport default would downgrade 301/302
to GET and drop the body). Configure the limit with with_max_redirects;
exceeding it returns Error::TooManyRedirects.
Serving QUERY
The [http_query::server] helpers are framework-agnostic (they work on
http::HeaderMap and a method string), so they plug into axum, hyper, actix,
etc. They enforce the RFC's rules: 400 for a missing Content-Type, 415
for an unsupported query media type, 405 for non-QUERY methods.
use ;
# use HeaderMap;
#
See examples/axum_server.rs for a complete server.
Caching
Unlike GET, a QUERY cache entry must be keyed on the request body:
let key = cache_key;
# assert_eq!;
Feature flags
client(default) — the asyncreqwest-based [Client].
Disable default features for a runtime-agnostic core (Structured Fields parsing, cache keys, response/discovery helpers, and the server helpers) with no async or client dependency.