Skip to main content

http_query/
lib.rs

1//! `http-query` is a client and server SDK for the **HTTP `QUERY` method**
2//! ([RFC 10008]).
3//!
4//! `QUERY` is a safe, idempotent request method that carries a request body
5//! describing a query to be evaluated against the target resource. Unlike GET,
6//! the query travels in the body rather than the URI; unlike POST, the request
7//! is safe and may be retried and cached.
8//!
9//! # Sending a query (requires the `client` feature, enabled by default)
10//!
11//! ```no_run
12//! # async fn run() -> Result<(), http_query::Error> {
13//! use http_query::Client;
14//!
15//! let client = Client::new();
16//! let resp = client
17//!     .query_string("https://example.org/search", "application/sql", "SELECT 1")
18//!     .await?;
19//! println!("status: {}", resp.status());
20//! # Ok(()) }
21//! ```
22//!
23//! # Discovering support
24//!
25//! [`Client::options`] issues an `OPTIONS` request and reports QUERY support
26//! from the `Allow` and `Accept-Query` header fields. `Accept-Query` is parsed
27//! as an [RFC 9651] Structured Fields list.
28//!
29//! # Result vs. equivalent resource
30//!
31//! A response may advertise two distinct URIs (RFC 10008 §2.3–2.4):
32//! `Content-Location` (the stored result, [`Client::fetch_result`]) and
33//! `Location` (the equivalent resource whose GET re-runs the query,
34//! [`Client::fetch_equivalent`]).
35//!
36//! # Serving QUERY
37//!
38//! The [`server`] module provides framework-agnostic helpers to validate an
39//! incoming QUERY request and advertise support. See `examples/axum_server.rs`.
40//!
41//! [RFC 10008]: https://www.rfc-editor.org/rfc/rfc10008.html
42//! [RFC 9651]: https://www.rfc-editor.org/rfc/rfc9651.html
43
44#![forbid(unsafe_code)]
45#![warn(missing_docs)]
46
47mod accept_query;
48mod cache;
49mod consts;
50mod error;
51mod response;
52
53pub mod server;
54
55#[cfg(feature = "client")]
56mod client;
57
58pub use accept_query::{format_accept_query, matches_media_range, parse_accept_query};
59pub use cache::cache_key;
60pub use consts::{
61    query_method, HEADER_ACCEPT, HEADER_ACCEPT_QUERY, HEADER_ALLOW, HEADER_CONTENT_LOCATION,
62    HEADER_CONTENT_TYPE, HEADER_LOCATION, MEDIA_TYPE_FORM, MEDIA_TYPE_JSON, METHOD_QUERY,
63};
64pub use error::{Error, Result};
65pub use response::{supports_query, Discovery, ResponseInfo};
66
67#[cfg(feature = "client")]
68pub use client::{check_status, Client};