http-query 0.2.0

A client and server SDK for the HTTP QUERY method (RFC 10008).
Documentation

http-query

Crates.io Documentation CI License: BSD-3-Clause

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.

[dependencies]
http-query = "0.1"

Sending a query

The async client is built on reqwest (the client feature, enabled by default).

use http_query::Client;

# async fn run() -> Result<(), http_query::Error> {
let client = Client::new();

// Raw body + content type
let resp = client
    .query_string("https://example.org/search", "application/sql", "SELECT 1")
    .await?;

// JSON in, JSON out (validates the status)
#[derive(serde::Serialize)]
struct Search<'a> { q: &'a str }
#[derive(serde::Deserialize)]
struct Results { hits: u32 }

let results: Results = client
    .query_json_into("https://example.org/search", &Search { q: "rust" })
    .await?;
# let _ = resp; let _ = results.hits; Ok(()) }

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_result follows it.
  • Location — the equivalent resource, whose GET re-runs the query. Client::fetch_equivalent follows 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 fn run() -> Result<(), http_query::Error> {
# let client = http_query::Client::new();
let discovery = client.options("https://example.org/search").await?;
if discovery.supports_query {
    println!("accepted formats: {:?}", discovery.accept_query);
}
# Ok(()) }

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 http_query::server::{check_query_request, QueryRejection};
# use http::HeaderMap;
# fn handle(method: &str, headers: &HeaderMap) {
match check_query_request(method, headers, &["application/json"]) {
    Ok(()) => { /* evaluate the query in the request body */ }
    Err(rejection) => { /* respond with rejection.status() */ }
}
# }

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 = http_query::cache_key(
    "https://example.org/search",
    http_query::MEDIA_TYPE_JSON,
    br#"{"q":"rust"}"#,
);
# assert_eq!(key.len(), 64);

Feature flags

  • client (default) — the async reqwest-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.

License

BSD-3-Clause.