http-query 0.2.0

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

[![Crates.io](https://img.shields.io/crates/v/http-query.svg)](https://crates.io/crates/http-query)
[![Documentation](https://docs.rs/http-query/badge.svg)](https://docs.rs/http-query)
[![CI](https://github.com/thatwasyahya/http-query/actions/workflows/ci.yml/badge.svg)](https://github.com/thatwasyahya/http-query/actions/workflows/ci.yml)
[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD--3--Clause-blue.svg)](LICENSE)

A client and server SDK for the **HTTP `QUERY` method** ([RFC 10008](https://www.rfc-editor.org/rfc/rfc10008.html)) 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.

```toml
[dependencies]
http-query = "0.1"
```

## Sending a query

The async client is built on [`reqwest`](https://crates.io/crates/reqwest)
(the `client` feature, enabled by default).

```rust,no_run
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](https://www.rfc-editor.org/rfc/rfc10008.html#section-2.3)):

- **`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](https://www.rfc-editor.org/rfc/rfc9651.html)
Structured Fields List; it is parsed and serialized correctly (quoted strings,
parameters, `*/*` and `type/*` wildcards).

```rust,no_run
# 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](https://www.rfc-editor.org/rfc/rfc10008.html#section-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.

```rust,no_run
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`](examples/axum_server.rs) for a complete server.

## Caching

Unlike `GET`, a QUERY cache entry must be keyed on the request body:

```rust
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](LICENSE).