feat: add support for HTTP QUERY method

The HTTP QUERY method is a means of making a safe, idempotent request
that contains content. The primary motivator for this case is graphql,
replacing HTTP POST for read only requests, however it is application
agnostic.

This method is still in draft but since 2025-01-07 it has reached consensus
so it should be stable enough to make it unlikely to change this implementation.

https://datatracker.ietf.org/doc/draft-ietf-httpbis-safe-method-w-body/

CHANGELOG.md

@@ -1,3 +1,7 @@
+# Unreleased
+
+* Add 'QUERY' method support along with its new 'accept-query' standard header.
+
 # 1.2.0 (December 3, 2024)
 
 * Add `StatusCode::TOO_EARLY` constant for 425 status.

benches/src/header_name.rs

@@ -68,6 +68,7 @@ fn make_all_known_headers() -> Vec<Vec<u8>> {
     // standard_response_headers
     b"Accept-Patch".to_vec(),
     b"Accept-Ranges".to_vec(),
+    b"Accept-Query".to_vec(),
     b"Access-Control-Allow-Credentials".to_vec(),
     b"Access-Control-Allow-Headers".to_vec(),
     b"Access-Control-Allow-Methods".to_vec(),
@@ -191,6 +192,7 @@ static ALL_KNOWN_HEADERS: &[&str] = &[
     // standard_response_headers
     "accept-patch",
     "accept-ranges",
+    "accept-query",
     "access-control-allow-credentials",
     "access-control-allow-headers",
     "access-control-allow-methods",

src/header/mod.rs

@@ -90,6 +90,7 @@ pub use self::name::{
     ACCEPT_ENCODING,
     ACCEPT_LANGUAGE,
     ACCEPT_RANGES,
+    ACCEPT_QUERY,
     ACCESS_CONTROL_ALLOW_CREDENTIALS,
     ACCESS_CONTROL_ALLOW_HEADERS,
     ACCESS_CONTROL_ALLOW_METHODS,

src/header/name.rs

@@ -244,6 +244,17 @@ standard_headers! {
     /// interrupted download, rather than to start it from the start again.
     (AcceptRanges, ACCEPT_RANGES, b"accept-ranges");
 
+    /// Advertises which query formats the server is able to understand.
+    ///
+    /// Accept-Query should appear in the OPTIONS response for any resource that
+    /// supports the use of the QUERY method. The presence of the
+    /// Accept-Query header in response to any method is an implicit indication
+    /// that QUERY is allowed on the resource identified by the URI. The
+    /// presence of a specific query document format in this header indicates
+    /// that that specific format is allowed on the resource identified by the
+    /// URI.
+    (AcceptQuery, ACCEPT_QUERY, b"accept-query");
+
     /// Preflight response indicating if the response to the request can be
     /// exposed to the page.
     ///

src/method.rs

@@ -30,7 +30,7 @@ use std::{fmt, str};
 ///
 /// Currently includes 8 variants representing the 8 methods defined in
 /// [RFC 7230](https://tools.ietf.org/html/rfc7231#section-4.1), plus PATCH,
-/// and an Extension variant for all extensions.
+/// QUERY, and an Extension variant for all extensions.
 ///
 /// # Examples
 ///
@@ -60,6 +60,7 @@ enum Inner {
     Trace,
     Connect,
     Patch,
+    Query,
     // If the extension is short enough, store it inline
     ExtensionInline(InlineExtension),
     // Otherwise, allocate it
@@ -94,6 +95,9 @@ impl Method {
     /// TRACE
     pub const TRACE: Method = Method(Trace);
 
+    /// QUERY
+    pub const QUERY: Method = Method(Query);
+
     /// Converts a slice of bytes to an HTTP method.
     pub fn from_bytes(src: &[u8]) -> Result<Method, InvalidMethod> {
         match src.len() {
@@ -111,6 +115,7 @@ impl Method {
             5 => match src {
                 b"PATCH" => Ok(Method(Patch)),
                 b"TRACE" => Ok(Method(Trace)),
+                b"QUERY" => Ok(Method(Query)),
                 _ => Method::extension_inline(src),
             },
             6 => match src {
@@ -146,7 +151,7 @@ impl Method {
     /// See [the spec](https://tools.ietf.org/html/rfc7231#section-4.2.1)
     /// for more words.
     pub fn is_safe(&self) -> bool {
-        matches!(self.0, Get | Head | Options | Trace)
+        matches!(self.0, Get | Head | Options | Trace | Query)
     }
 
     /// Whether a method is considered "idempotent", meaning the request has
@@ -174,6 +179,7 @@ impl Method {
             Trace => "TRACE",
             Connect => "CONNECT",
             Patch => "PATCH",
+            Query => "QUERY",
             ExtensionInline(ref inline) => inline.as_str(),
             ExtensionAllocated(ref allocated) => allocated.as_str(),
         }
@@ -452,6 +458,7 @@ mod test {
         assert!(Method::DELETE.is_idempotent());
         assert!(Method::HEAD.is_idempotent());
         assert!(Method::TRACE.is_idempotent());
+        assert!(Method::QUERY.is_idempotent());
 
         assert!(!Method::POST.is_idempotent());
         assert!(!Method::CONNECT.is_idempotent());

src/request.rs

@@ -413,6 +413,28 @@ impl Request<()> {
     {
         Builder::new().method(Method::TRACE).uri(uri)
     }
+
+    /// Creates a new `Builder` initialized with a QUERY method and the given URI.
+    ///
+    /// This method returns an instance of `Builder` which can be used to
+    /// create a `Request`.
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// # use http::*;
+    ///
+    /// let request = Request::query("https://www.rust-lang.org/")
+    ///     .body(())
+    ///     .unwrap();
+    /// ```
+    pub fn query<T>(uri: T) -> Builder
+    where
+        T: TryInto<Uri>,
+        <T as TryInto<Uri>>::Error: Into<crate::Error>,
+    {
+        Builder::new().method(Method::QUERY).uri(uri)
+    }
 }
 
 impl<T> Request<T> {

util/src/main.rs

@@ -127,6 +127,19 @@ standard_headers! {
     "#,
     "accept-ranges";
 
+    r#"
+    /// Advertises which query formats the server is able to understand.
+    ///
+    /// Accept-Query should appear in the OPTIONS response for any resource that
+    /// supports the use of the QUERY method. The presence of the
+    /// Accept-Query header in response to any method is an implicit indication
+    /// that QUERY is allowed on the resource identified by the URI. The
+    /// presence of a specific query document format in this header indicates
+    /// that that specific format is allowed on the resource identified by the
+    /// URI.
+    "#,
+    "accept-query";
+
     r#"
     /// Preflight response indicating if the response to the request can be
     /// exposed to the page.