Feat/query

README.md

@@ -51,7 +51,7 @@ Key features:
 - **Simple** — define HTTP requests as decorated async functions, no boilerplate.
 - **Typed** — full type annotations throughout; validate responses with <a href="https://docs.pydantic.dev/" target="_blank">Pydantic</a> models.
 - **Logged** — colorful, structured request/response logs with timing, built-in.
-- **Complete** — GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, GraphQL, and **WebSocket** out of the box.
+- **Complete** — GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, QUERY, GraphQL, and **WebSocket** out of the box.
 - **Extensible** — middleware, dependency injection, routers, lifespan hooks.
 - **Interactive** — built-in Swagger UI via `app.web_run()` to browse and execute requests in the browser.
 - **HTTP/2** — optional HTTP/2 support, with automatic fallback to HTTP/1.1.

docs/en/api-reference.md

@@ -17,6 +17,7 @@ app = FastHTTP(
     debug: bool = False,
     http2: bool = False,
     get_request: dict = {},
+    query_request: dict = {},
     post_request: dict = {},
     put_request: dict = {},
     patch_request: dict = {},
@@ -34,6 +35,7 @@ app = FastHTTP(
 | `debug` | `bool` | `False` | Debug mode |
 | `http2` | `bool` | `False` | Use HTTP/2 |
 | `get_request` | `dict` | `{}` | GET settings |
+| `query_request` | `dict` | `{}` | QUERY settings |
 | `post_request` | `dict` | `{}` | POST settings |
 | `put_request` | `dict` | `{}` | PUT settings |
 | `patch_request` | `dict` | `{}` | PATCH settings |
@@ -129,6 +131,25 @@ async def lifespan(app):
 )
 ```
 
+### @app.query()
+
+Safe and idempotent like GET, but accepts a `json`/`data` body (like POST). See [HTTP Methods](tutorial/http-methods.md#query-complex-reads-with-a-body).
+
+```python
+@app.query(
+    url: str,
+    json: dict = None,
+    data: bytes = None,
+    params: dict = None,
+    tags: list = [],
+    dependencies: list = [],
+    response_model: type = None,
+    request_model: type = None,
+    responses: dict = None,
+    query_request: dict = None,
+)
+```
+
 ### @app.post()
 
 ```python
@@ -510,7 +531,7 @@ The Route object represents a registered HTTP request. It contains all informati
 
 | Attribute | Type | Description |
 |-----------|------|-------------|
-| `method` | `str` | HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) |
+| `method` | `str` | HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, QUERY) |
 | `url` | `str` | Full URL of the request |
 | `params` | `dict` | Query parameters |
 | `json` | `dict` | JSON body sent with request |

docs/en/index.md

@@ -36,7 +36,7 @@ The key features are:
 * **Simple**: define HTTP requests as decorated async functions, no boilerplate.
 * **Typed**: full type annotations throughout; validate responses with <a href="https://docs.pydantic.dev/" target="_blank">Pydantic</a> models.
 * **Logged**: colorful, structured request/response logs with timing, built-in.
-* **Complete**: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, and GraphQL out of the box.
+* **Complete**: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, QUERY, and GraphQL out of the box.
 * **Extensible**: middleware, dependency injection, routers, lifespan hooks.
 * **Interactive**: built-in Swagger UI via `app.web_run()` to browse and execute requests in the browser.
 * **HTTP/2**: optional HTTP/2 support, with automatic fallback to HTTP/1.1.

docs/en/reference/fasthttp.md

@@ -16,6 +16,7 @@ app = FastHTTP(
     middleware: list = [],
     base_url: str = None,
     get_request: dict = {},
+    query_request: dict = {},
     post_request: dict = {},
     put_request: dict = {},
     patch_request: dict = {},
@@ -36,6 +37,7 @@ app = FastHTTP(
 | `middleware` | `list` | `[]` | Middleware list |
 | `base_url` | `str` | `None` | Default base URL for decorators and routers |
 | `get_request` | `dict` | `{}` | Default GET settings |
+| `query_request` | `dict` | `{}` | Default QUERY settings |
 | `post_request` | `dict` | `{}` | Default POST settings |
 | `put_request` | `dict` | `{}` | Default PUT settings |
 | `patch_request` | `dict` | `{}` | Default PATCH settings |
@@ -123,6 +125,24 @@ Decorator for GET requests.
 )
 ```
 
+### query()
+
+Decorator for QUERY requests. Safe and idempotent like GET, but accepts a `json`/`data` body (like POST).
+
+```python
+@app.query(
+    url: str,
+    json: dict = None,
+    data: bytes = None,
+    params: dict = None,
+    tags: list = [],
+    dependencies: list = [],
+    response_model: type = None,
+    request_model: type = None,
+    responses: dict = None,
+)
+```
+
 ### post()
 
 Decorator for POST requests.
@@ -227,6 +247,7 @@ AsyncSession(
 | Method | Signature |
 |--------|-----------|
 | `get` | `(url, *, params, headers, timeout) → Response \| None` |
+| `query` | `(url, *, json, data, headers, timeout) → Response \| None` |
 | `post` | `(url, *, json, data, headers, timeout) → Response \| None` |
 | `put` | `(url, *, json, data, headers, timeout) → Response \| None` |
 | `patch` | `(url, *, json, data, headers, timeout) → Response \| None` |

docs/en/tutorial/http-methods.md

@@ -49,6 +49,22 @@ async def patch_user(resp: Response) -> dict:
     return resp.json()
 ```
 
+## QUERY - Complex Reads with a Body
+
+`QUERY` is a newer HTTP method (proposed in an IETF draft, `draft-ietf-httpbis-safe-method-w-body`) for read operations that don't fit in a URL. It's safe and idempotent like `GET`, but carries a JSON body like `POST` — useful for complex search/filter requests.
+
+```python
+@app.query(
+    url="https://api.example.com/users/search",
+    json={"role": "admin", "active": True}
+)
+async def search_users(resp: Response) -> dict:
+    return resp.json()
+```
+
+!!! note
+    `QUERY` is not yet universally supported by servers and proxies — only use it against APIs that explicitly document `QUERY` support. It also isn't part of the standard OpenAPI Path Item Object method set, so `QUERY` routes won't be rendered in Swagger UI (see [OpenAPI](openapi/index.md)), even though they're included in the generated `/openapi.json`.
+
 ## DELETE - Remove Data
 
 ```python
@@ -83,7 +99,7 @@ async def allowed_methods(resp: Response) -> dict:
 |-----------|-------------|
 | `url` | Request URL (required) |
 | `params` | Query parameters |
-| `json` | JSON body (for POST, PUT, PATCH) |
+| `json` | JSON body (for POST, PUT, PATCH, QUERY) |
 | `data` | Raw bytes body |
 | `files` | File uploads (multipart/form-data) |
 | `tags` | Tags for grouping |

docs/en/tutorial/index.md

@@ -8,7 +8,7 @@ The tutorial is divided into several sections:
 
 ### Getting Started
 - [First Steps](first-steps.md) - Installation and basic concepts
-- [HTTP Methods](http-methods.md) - GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
+- [HTTP Methods](http-methods.md) - GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, QUERY
 - [Request Parameters](request-parameters.md) - Query, JSON, headers
 - [Response Handling](response-handling.md) - Working with responses
 

docs/index.md

@@ -39,7 +39,7 @@ The key features are:
 * **Simple**: define HTTP requests as decorated async functions, no boilerplate.
 * **Typed**: full type annotations throughout; validate responses with <a href="https://docs.pydantic.dev/" target="_blank">Pydantic</a> models.
 * **Logged**: colorful, structured request/response logs with timing, built-in.
-* **Complete**: GET, POST, PUT, PATCH, DELETE, and GraphQL out of the box.
+* **Complete**: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, QUERY, and GraphQL out of the box.
 * **Extensible**: middleware, dependency injection, routers, lifespan hooks.
 * **Interactive**: built-in Swagger UI via `app.web_run()` to browse and execute requests in the browser.
 * **HTTP/2**: optional HTTP/2 support, with automatic fallback to HTTP/1.1.

docs/ru/api-reference.md

@@ -17,6 +17,7 @@ app = FastHTTP(
     debug: bool = False,
     http2: bool = False,
     get_request: dict = {},
+    query_request: dict = {},
     post_request: dict = {},
     put_request: dict = {},
     patch_request: dict = {},
@@ -36,6 +37,7 @@ app = FastHTTP(
 | `debug` | `bool` | `False` | Режим отладки |
 | `http2` | `bool` | `False` | Использовать HTTP/2 |
 | `get_request` | `dict` | `{}` | Настройки для GET |
+| `query_request` | `dict` | `{}` | Настройки для QUERY |
 | `post_request` | `dict` | `{}` | Настройки для POST |
 | `put_request` | `dict` | `{}` | Настройки для PUT |
 | `patch_request` | `dict` | `{}` | Настройки для PATCH |
@@ -131,6 +133,25 @@ async def lifespan(app):
 )
 ```
 
+### @app.query()
+
+Безопасен и идемпотентен как GET, но принимает тело `json`/`data` (как POST). См. [HTTP методы](tutorial/http-methods.md).
+
+```python
+@app.query(
+    url: str,
+    json: dict = None,
+    data: bytes = None,
+    params: dict = None,
+    tags: list = [],
+    dependencies: list = [],
+    response_model: type = None,
+    request_model: type = None,
+    responses: dict = None,
+    query_request: dict = None,
+)
+```
+
 ### @app.post()
 
 ```python

docs/ru/index.md

@@ -36,7 +36,7 @@ FastHTTP — это современная **асинхронная HTTP-кли
 * **Простой**: определяйте HTTP-запросы как декорированные async-функции, без лишнего кода.
 * **Типизированный**: полные аннотации типов; валидация ответов через <a href="https://docs.pydantic.dev/" target="_blank">Pydantic</a>.
 * **Логирует**: красочные структурированные логи запросов/ответов со временем выполнения, встроено.
-* **Полный**: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS и GraphQL из коробки.
+* **Полный**: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, QUERY и GraphQL из коробки.
 * **Расширяемый**: middleware, dependency injection, роутеры, lifespan-хуки.
 * **Интерактивный**: встроенный Swagger UI через `app.web_run()` для просмотра и выполнения запросов в браузере.
 * **HTTP/2**: опциональная поддержка HTTP/2 с автоматическим fallback на HTTP/1.1.

docs/ru/reference/fasthttp.md

@@ -16,6 +16,7 @@ app = FastHTTP(
     middleware: list = [],
     base_url: str = None,
     get_request: dict = {},
+    query_request: dict = {},
     post_request: dict = {},
     put_request: dict = {},
     patch_request: dict = {},
@@ -36,6 +37,7 @@ app = FastHTTP(
 | `middleware` | `list` | `[]` | Список middleware |
 | `base_url` | `str` | `None` | Базовый URL для декораторов и роутеров |
 | `get_request` | `dict` | `{}` | Настройки GET |
+| `query_request` | `dict` | `{}` | Настройки QUERY |
 | `post_request` | `dict` | `{}` | Настройки POST |
 | `put_request` | `dict` | `{}` | Настройки PUT |
 | `patch_request` | `dict` | `{}` | Настройки PATCH |
@@ -97,6 +99,24 @@ app.include_router(
 
 Декораторы для HTTP методов.
 
+### query()
+
+Декоратор для QUERY-запросов. Безопасен и идемпотентен как GET, но принимает тело `json`/`data` (как POST).
+
+```python
+@app.query(
+    url: str,
+    json: dict = None,
+    data: bytes = None,
+    params: dict = None,
+    tags: list = [],
+    dependencies: list = [],
+    response_model: type = None,
+    request_model: type = None,
+    responses: dict = None,
+)
+```
+
 ### graphql()
 
 Декоратор для GraphQL.
@@ -173,6 +193,7 @@ AsyncSession(
 | Метод | Сигнатура |
 |-------|-----------|
 | `get` | `(url, *, params, headers, timeout) → Response \| None` |
+| `query` | `(url, *, json, data, headers, timeout) → Response \| None` |
 | `post` | `(url, *, json, data, headers, timeout) → Response \| None` |
 | `put` | `(url, *, json, data, headers, timeout) → Response \| None` |
 | `patch` | `(url, *, json, data, headers, timeout) → Response \| None` |

docs/ru/tutorial/http-methods.md

@@ -49,6 +49,22 @@ async def patch_user(resp: Response) -> dict:
     return resp.json()
 ```
 
+## QUERY - сложные запросы на чтение с телом
+
+`QUERY` — более новый HTTP-метод (предложен в IETF-черновике `draft-ietf-httpbis-safe-method-w-body`) для операций чтения, которые не помещаются в URL. Он безопасен и идемпотентен как `GET`, но несёт JSON-тело как `POST` — удобно для сложных запросов поиска/фильтрации.
+
+```python
+@app.query(
+    url="https://api.example.com/users/search",
+    json={"role": "admin", "active": True}
+)
+async def search_users(resp: Response) -> dict:
+    return resp.json()
+```
+
+!!! note
+    `QUERY` пока поддерживается не всеми серверами и прокси — используйте его только для API, которые явно документируют поддержку `QUERY`. Также этот метод не входит в стандартный набор методов OpenAPI Path Item Object, поэтому `QUERY`-маршруты не отображаются в Swagger UI (см. [OpenAPI](openapi/index.md)), хотя и попадают в сгенерированный `/openapi.json`.
+
 ## DELETE - удаление данных
 
 ```python
@@ -83,7 +99,7 @@ async def allowed_methods(resp: Response) -> dict:
 |----------|----------|
 | `url` | URL запроса (обязательный) |
 | `params` | Query параметры |
-| `json` | JSON тело (для POST, PUT, PATCH) |
+| `json` | JSON тело (для POST, PUT, PATCH, QUERY) |
 | `data` | Сырые байты |
 | `files` | Загрузка файлов (multipart/form-data) |
 | `tags` | Теги для группировки |

docs/ru/tutorial/index.md

@@ -8,7 +8,7 @@
 
 ### Начало работы
 - [Первые шаги](first-steps.md) - Установка и основные понятия
-- [HTTP методы](http-methods.md) - GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
+- [HTTP методы](http-methods.md) - GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, QUERY
 - [Параметры запроса](request-parameters.md) - Query, JSON, заголовки
 - [Обработка ответа](response-handling.md) - Работа с ответами
 

fasthttp/app.py

@@ -143,6 +143,19 @@ def __init__(
                 ),
             ]
         ) = None,
+        query_request: (
+            Annotated[
+                RequestsOptional | None,
+                Doc(
+                    """
+                Default configuration for QUERY requests.
+
+                Allows setting headers, timeout and other request-level
+                options that will be applied to all QUERY requests.
+                """
+                ),
+            ]
+        ) = None,
         post_request: (
             Annotated[
                 RequestsOptional | None,
@@ -532,6 +545,7 @@ async def lifespan(app: FastHTTP):
 
         self.request_configs = {
             "GET": get_request or {},
+            "QUERY": query_request or {},
             "POST": post_request or {},
             "PUT": put_request or {},
             "PATCH": patch_request or {},
@@ -831,6 +845,41 @@ def get(
             responses=responses,
         )
 
+    def query(
+        self,
+        url: str,
+        *,
+        json: dict[str, Any] | None = None,
+        data: object | None = None,
+        files: FileUpload | None = None,
+        response_model: type | None = None,
+        request_model: type[BaseModel] | None = None,
+        tags: list[str] | None = None,
+        dependencies: list[Any] | None = None,
+        raise_for_status: bool = False,
+        auth: BasicAuth | DigestAuth | BearerAuth | OAuth2ClientCredentials | None = None,
+        responses: dict[int, dict[Literal["model"], type[BaseModel]]] | None = None,
+    ) -> Callable[[Callable[..., object]], Callable[..., object]]:
+        """Decorator for registering a QUERY route.
+
+        QUERY is safe and idempotent like GET, but carries a request body
+        (per the IETF QUERY method draft), so it accepts ``json``/``data``.
+        """
+        return self._add_route(
+            method="QUERY",
+            url=url,
+            json=json,
+            data=data,
+            files=files,
+            response_model=response_model,
+            request_model=request_model,
+            tags=tags,
+            dependencies=dependencies,
+            raise_for_status=raise_for_status,
+            auth=auth,
+            responses=responses,
+        )
+
     def post(
         self,
         url: str,

fasthttp/client.py

@@ -442,9 +442,9 @@ async def _follow_redirect(
                 "follow_redirects": False,
                 "auth": resolve_auth(route.auth),
             }
-            if new_method in ("POST", "PUT", "PATCH") and route.json:
+            if new_method in ("POST", "PUT", "PATCH", "QUERY") and route.json:
                 req_kwargs["json"] = route.json
-            elif new_method in ("POST", "PUT", "PATCH") and route.data:
+            elif new_method in ("POST", "PUT", "PATCH", "QUERY") and route.data:
                 req_kwargs["content"] = route.data
 
             new_resp = await client.request(**req_kwargs)

fasthttp/helpers/route_inspect.py

@@ -100,7 +100,7 @@ def validate_handler(func: Callable[..., object]) -> None:
 
 def create_route_params(
     *,
-    method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"],
+    method: Literal["GET", "POST", "PUT", "PATCH", "DELETE", "QUERY"],
     url: str,
     params: dict | None = None,
     json: dict | None = None,