bazis-async-request 2.2.0__py3-none-any.whl

bazis/contrib/async_request/__init__.py

@@ -0,0 +1,19 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+try:
+    from importlib.metadata import PackageNotFoundError, version
+    __version__ = version('bazis-async-request')
+except PackageNotFoundError:
+    __version__ = 'dev'

bazis/contrib/async_request/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '2.2.0'
+__version_tuple__ = version_tuple = (2, 2, 0)
+
+__commit_id__ = commit_id = None

bazis/contrib/async_request/apps.py

@@ -0,0 +1,25 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from django.utils.translation import gettext_lazy as _
+
+from bazis.core.utils.apps import BaseConfig
+
+
+class AsyncRequestConfig(BaseConfig):
+    """Django AppConfig for the asynchronous background processing package (async_request)."""
+
+    name = "bazis.contrib.async_request"
+    verbose_name = _("AsyncRequest")
+    default = True

bazis/contrib/async_request/middleware.py

@@ -0,0 +1,104 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import logging
+
+from django.conf import settings
+
+from fastapi import Request
+
+from starlette.datastructures import Headers
+from starlette.responses import JSONResponse
+
+from bazis.contrib.async_background.producer import enqueue_task_async
+from bazis.contrib.async_background.routes import get_async_background_response
+from bazis.contrib.async_background.utils import ChannelNameError, resolve_channel_name_async
+
+from .utils import build_request_payload
+
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncRequestMiddleware:
+    def __init__(self, app):
+        self.app = app
+        self._no_bg_prefixes: tuple[str, ...] | None = None
+
+    def _build_no_bg_prefixes(self, app) -> tuple[str, ...]:
+        prefixes: list[str] = []
+        path = app.url_path_for(get_async_background_response.__name__, task_id="__dummy__")
+        if path:
+            prefix = str(path).replace("/__dummy__/", "/")
+            while "//" in prefix:
+                prefix = prefix.replace("//", "/")
+            prefixes.append(prefix)
+        return tuple(prefixes)
+
+    async def __call__(self, scope, receive, send) -> None:
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+
+        if self._no_bg_prefixes is None:
+            scope_app = scope.get("app")
+            print(scope_app.user_middleware)
+            self._no_bg_prefixes = self._build_no_bg_prefixes(scope_app or self.app)
+
+        path = scope.get("path", "")
+        if self._no_bg_prefixes and any(path.startswith(prefix) for prefix in self._no_bg_prefixes):
+            await self.app(scope, receive, send)
+            return
+
+        headers = Headers(scope=scope)
+        if (
+            headers.get("X-Async-Background-Internal", "").lower() == "true"
+            or "X-Async-Background" not in headers
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        if not settings.KAFKA_ENABLED:
+            logger.warning(
+                "Incorrect Kafka settings, it is impossible to execute the request in the background."
+            )
+            await self.app(scope, receive, send)
+            return
+
+        request = Request(scope, receive)
+        await request.body()
+        try:
+            channel_name = await resolve_channel_name_async(request)
+        except ChannelNameError as err:
+            response = JSONResponse(status_code=401, content={'detail': str(err)})
+            await response(scope, receive, send)
+            return
+
+        payload = build_request_payload(request)
+        message = await enqueue_task_async(
+            topic_name=settings.KAFKA_TOPIC_ASYNC_REQUEST,
+            channel_name=channel_name,
+            payload=payload,
+            partition_marker=(
+                payload.body.get("data", {}).get("id") if isinstance(payload.body, dict) else None
+            ),
+        )
+
+        response = JSONResponse(
+            status_code=202,
+            content={"data": None, "meta": {"async_request_id": message.task_id}},
+        )
+        await response(scope, receive, send)

bazis/contrib/async_request/schemas.py

@@ -0,0 +1,36 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+from pydantic import BaseModel, Field
+
+
+class AsyncRequestPayload(BaseModel):
+    """Payload of a background HTTP request serialized for Kafka."""
+
+    path: str = Field(..., description="Request path")
+    query_string: str = Field(..., description="Query string")
+    headers: list[tuple[str | bytes, str | bytes]] = Field(
+        ..., description="List of HTTP headers"
+    )  # List of tuples (header_name, header_value)
+    request_client: str | tuple | None = Field(..., description="Client address of the request")
+    method: str = Field(..., description="HTTP method")
+    type: str = Field(..., description="Request type: http or websocket")
+    http_version: str = Field(..., description="HTTP version")
+    scheme: str = Field(..., description="Request scheme")
+    body: dict | list[dict] = Field(default_factory=dict, description="Request body")
+
+    class Config:
+        json_encoders = {bytes: lambda v: v.decode("utf-8")}
+        use_enum_values = True

bazis/contrib/async_request/tasks.py

@@ -0,0 +1,133 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import logging
+from urllib.parse import urlparse
+
+from django.conf import settings
+
+from bazis.contrib.async_background.broker import get_broker_for_consumer
+from bazis.contrib.async_background.schemas import KafkaTask, TaskStatus
+from bazis.contrib.async_background.utils import set_and_publish_status_async
+from bazis.contrib.async_request.schemas import AsyncRequestPayload
+
+
+logger = logging.getLogger(__name__)
+
+
+_subscriber_kwargs: dict[str, object] = {
+    "auto_offset_reset": settings.KAFKA_AUTO_OFFSET_RESET,
+    "auto_commit": settings.KAFKA_ENABLE_AUTO_COMMIT,
+    "auto_commit_interval_ms": settings.KAFKA_AUTO_COMMIT_INTERVAL_MS,
+}
+if settings.KAFKA_GROUP_ID:
+    _subscriber_kwargs["group_id"] = settings.KAFKA_GROUP_ID
+
+
+@get_broker_for_consumer().subscriber(settings.KAFKA_TOPIC_ASYNC_REQUEST, **_subscriber_kwargs)
+async def consumer_async_requests(task: KafkaTask[AsyncRequestPayload]):
+    """Executes a background HTTP request from Kafka."""
+
+    await set_and_publish_status_async(
+        task_id=task.task_id,
+        channel_name=task.channel_name,
+        status=TaskStatus.PROCESSING,
+    )
+
+    try:
+        response = await execute_internal_request(task)
+    except Exception as err:
+        logger.exception("Failed to process task_id=%s", task.task_id)
+        await set_and_publish_status_async(
+            task_id=task.task_id,
+            channel_name=task.channel_name,
+            status=TaskStatus.FAILED,
+            response={"error": str(err)},
+        )
+        raise
+
+    await set_and_publish_status_async(
+        task_id=task.task_id,
+        channel_name=task.channel_name,
+        status=TaskStatus.COMPLETED,
+        response=response,
+    )
+
+    logger.info(
+        "Processed task_id=%s with status=%s.",
+        task.task_id,
+        response.get("status"),
+    )
+
+
+async def execute_internal_request(task: KafkaTask[AsyncRequestPayload]) -> dict:
+    """Executes an internal HTTP request and returns the result."""
+    request = task.payload
+
+    url = urlparse(request.path)
+
+    headers = []
+    for key, value in request.headers:
+        key_bytes = key if isinstance(key, bytes) else str(key).encode("utf-8")
+        value_bytes = value if isinstance(value, bytes) else str(value).encode("utf-8")
+        headers.append((key_bytes, value_bytes))
+
+    scope = {
+        "type": request.type,
+        "http_version": request.http_version,
+        "method": request.method,
+        "scheme": request.scheme,
+        "path": url.path,
+        "raw_path": url.path.encode("utf-8"),
+        "query_string": request.query_string.encode(),
+        "headers": headers,
+        "client": request.request_client,
+    }
+
+    result = {
+        "task_id": task.task_id,
+        "endpoint": request.path,
+        "status": None,
+        "headers": [],
+        "response": None,
+    }
+
+    async def receive():
+        return {
+            "type": "http.request",
+            "body": json.dumps(request.body).encode("utf-8"),
+        }
+
+    async def send(message):
+        if message["type"] == "http.response.start":
+            result["status"] = message["status"]
+            decoded_headers = []
+            for key, value in message.get("headers", []):
+                key_str = key.decode("latin-1") if isinstance(key, (bytes, bytearray)) else str(key)
+                value_str = (
+                    value.decode("latin-1") if isinstance(value, (bytes, bytearray)) else str(value)
+                )
+                decoded_headers.append([key_str, value_str])
+            result["headers"] = decoded_headers
+        elif message["type"] == "http.response.body":
+            body = message.get("body", b"")
+            try:
+                result["response"] = json.loads(body)
+            except Exception:
+                result["response"] = body.decode("utf-8", errors="replace")
+
+    from bazis.core.app import app
+    await app(scope, receive, send)
+    return result

bazis/contrib/async_request/utils.py

@@ -0,0 +1,67 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import logging
+
+from fastapi import HTTPException, Request, status
+
+from .schemas import AsyncRequestPayload
+
+
+logger = logging.getLogger(__name__)
+
+
+def build_request_payload(request: Request) -> AsyncRequestPayload:
+    """Creates a payload for sending to Kafka."""
+    body_raw: bytes = request.scope.get("_cached_body") or getattr(request, "_body", b"")
+    try:
+        body: dict = json.loads(body_raw.decode("utf-8")) if body_raw else {}
+    except json.JSONDecodeError:
+        body = {}
+
+    headers: list[tuple[str, str]] = []
+    for k, v in request.scope.get("headers", []):
+        try:
+            k_val, v_val = k.decode(), v.decode()
+            if k_val.lower() not in ("x-async-background",):
+                headers.append((k_val, v_val))
+        except Exception as e:
+            logger.exception("Error decoding header: %s", e)
+
+    headers.append(("x-async-background-internal", "true"))
+
+    return AsyncRequestPayload(
+        path=request.url.path,
+        query_string=request.url.query,
+        headers=headers,
+        request_client=request.client,
+        method=request.method,
+        type=request.scope["type"],
+        http_version=request.scope["http_version"],
+        scheme=request.scope["scheme"],
+        body=body,
+    )
+
+
+async def require_async(request: Request) -> None:
+    """Allow only async-request or internal async-request requests."""
+    if request.headers.get("X-Async-Background-Internal", "").lower() == "true":
+        return
+    if "X-Async-Background" in request.headers:
+        return
+    raise HTTPException(
+        status_code=status.HTTP_409_CONFLICT,
+        detail="This endpoint is available only via async request.",
+    )

bazis_async_request-2.2.0.dist-info/METADATA

@@ -0,0 +1,706 @@
+Metadata-Version: 2.4
+Name: bazis-async-request
+Version: 2.2.0
+Summary: Async Background Requests module for Bazis framework.
+Author-email: Ilya Kharyn <ilya.tt07@gmail.com>
+Maintainer-email: Ilya Kharyn <ilya.tt07@gmail.com>
+Project-URL: Home, https://github.com/ecofuture-tech/bazis-async-request
+Keywords: bazis,django,fastapi,async,background,kafka,framework
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: bazis-async-background
+Provides-Extra: test
+Requires-Dist: bazis-test-utils; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+
+# Bazis Async Request
+
+[![PyPI version](https://img.shields.io/pypi/v/bazis-async-request.svg)](https://pypi.org/project/bazis-async-request/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/bazis-async-request.svg)](https://pypi.org/project/bazis-async-request/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+An extension package for Bazis that provides background processing for "heavy" HTTP requests on top of bazis-async-background.
+
+## Quick Start
+
+```bash
+# Install the package
+uv add bazis-async-request
+
+# Configure environment variables / settings (.env uses BS_ prefix)
+BS_INSTALLED_APPS='["bazis.contrib.async_request", "bazis.contrib.async_background", ...]'
+BS_BAZIS_CONFIG_APPS='["bazis.contrib.async_request", "bazis.contrib.async_background", ...]'
+BS_KAFKA_TASKS='["bazis.contrib.async_request.tasks"]'
+BS_KAFKA_BOOTSTRAP_SERVERS=localhost:9093
+BS_KAFKA_TOPIC_ASYNC_REQUEST=my_app_develop_async_request
+BS_KAFKA_GROUP_ID=my_app_develop
+
+# Run consumer in Kubernetes
+python manage.py kafka_consumer_single
+
+# Run multiple consumers locally
+python manage.py kafka_consumer_multiple --consumers-count=5
+```
+
+## Table of Contents
+
+- [Description](#description)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+  - [Environment Variables / Settings](#environment-variables--settings)
+  - [Route Registration](#route-registration)
+- [Usage](#usage)
+  - [Project-Level Middleware](#project-level-middleware)
+  - [Running Consumers](#running-consumers)
+- [Working with Frontend](#working-with-frontend)
+  - [Sending a Request](#sending-a-request)
+  - [Getting Result via WebSocket](#getting-result-via-websocket)
+  - [Getting Result via API](#getting-result-via-api)
+- [Examples](#examples)
+- [License](#license)
+- [Links](#links)
+
+## Description
+
+**Bazis Async Request** is an extension package for the Bazis framework that allows processing "heavy" requests in the background. The package includes:
+
+- **AsyncRequestMiddleware** — project-level middleware for automatic background processing of any request
+- **Kafka Producer** — sending tasks to Kafka queue
+- **Kafka Consumer** — processing tasks from the queue
+- **Redis storage** — storing task execution results
+- **WebSocket notifications** — automatic user notification about task status
+- **API endpoint** — retrieving results by task_id
+
+**How it works**: When sending a request with the `X-Async-Request: true` header, the request is not executed immediately but is placed in the Kafka queue. The consumer retrieves the task from the queue, executes it, saves the result in Redis, and sends a notification to the user via WebSocket.
+
+**This package requires the installation of `bazis`, `bazis-users`, `bazis-ws` packages and running Kafka and Redis servers.**
+
+## Requirements
+
+- **Python**: 3.12+
+- **bazis**: latest version
+- **bazis-async-background**: latest version
+- **bazis-ws**: latest version (for WebSocket notifications)
+- **PostgreSQL**: 12+
+- **Redis**: For storing results and caching
+- **Kafka**: For task queue
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add bazis-async-request
+```
+
+### Using pip
+
+```bash
+pip install bazis-async-request
+```
+
+## Running Tests
+
+Run from the project root:
+
+```bash
+docker compose -f sample/docker-compose.test.yml up --build --exit-code-from bazis-async-request-pytest --attach bazis-async-request-pytest --attach bazis-async-request-consumer-test
+```
+
+This waits for the pytest container to finish and streams logs only from the Python containers, so test completion and output are easy to follow.
+
+## Architecture
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │ POST + X-Async-Request: true
+       ▼
+┌─────────────────────┐
+│   API Endpoint      │
+│  (AsyncRequestMiddleware)│
+└──────┬──────────────┘
+       │ 1. Return task_id (202)
+       │ 2. Send to Kafka
+       ▼
+┌─────────────────────┐
+│   Kafka Topic       │
+│   (async_request)        │
+└──────┬──────────────┘
+       │
+       │ Consumer polls
+       ▼
+┌─────────────────────┐
+│  Kafka Consumer     │
+│  (Background Worker)│
+└──────┬──────────────┘
+       │ 3. Process request
+       │ 4. Save result to Redis
+       │ 5. Send WebSocket notification
+       ▼
+┌─────────────────────┐         ┌──────────────┐
+│      Redis          │◄────────┤  WebSocket   │
+│   (Results Store)   │         │              │
+└──────┬──────────────┘         └───────┬──────┘
+       │                                │
+       │ 6. GET /async_request_         │ 6. Receive notification
+       │    response/{task_id}/         │    {status: "completed"}
+       ▼                                ▼
+┌─────────────────────┐         ┌──────────────┐
+│   API Endpoint      │────────►│   Client     │
+│   (Get Result)      │         │              │
+└─────────────────────┘         └──────────────┘
+```
+
+## Configuration
+
+### Environment Variables / Settings
+
+Add to your `.env` (use `BS_` prefix for Bazis settings) or `settings.py`:
+
+```bash
+# Required settings
+INSTALLED_APPS='["bazis.contrib.async_request", "bazis.contrib.async_background", ...]'
+BAZIS_CONFIG_APPS='["bazis.contrib.async_request", "bazis.contrib.async_background", ...]'
+KAFKA_TASKS='["bazis.contrib.async_request.tasks"]'
+
+# Kafka settings
+KAFKA_BOOTSTRAP_SERVERS=localhost:9093
+KAFKA_TOPIC_ASYNC_REQUEST=my_app_develop_async_request
+KAFKA_GROUP_ID=my_app_develop
+
+# Optional settings
+KAFKA_CONSUMER_LIFETIME_SEC=900           # Consumer lifetime (15 minutes)
+KAFKA_CONSUMER_LIFETIME_JITTER_SEC=180    # Random deviation (3 minutes)
+KAFKA_AUTO_OFFSET_RESET=latest
+KAFKA_ENABLE_AUTO_COMMIT=true
+KAFKA_AUTO_COMMIT_INTERVAL_MS=5000
+KAFKA_LOG_LEVEL=INFO
+```
+
+When placing these in a `.env` file, prefix them with `BS_`, for example:
+
+```bash
+BS_INSTALLED_APPS='["bazis.contrib.async_request", "bazis.contrib.async_background", ...]'
+BS_BAZIS_CONFIG_APPS='["bazis.contrib.async_request", "bazis.contrib.async_background", ...]'
+BS_KAFKA_TASKS='["bazis.contrib.async_request.tasks"]'
+```
+
+**Parameters**:
+
+- `KAFKA_TASKS` — dotted module paths imported by the consumer to register tasks
+- `KAFKA_BOOTSTRAP_SERVERS` — Kafka broker address
+- `KAFKA_TOPIC_ASYNC_REQUEST` — topic for async tasks
+- `KAFKA_GROUP_ID` — consumer group
+- `KAFKA_CONSUMER_LIFETIME_SEC` — consumer working time before restart
+- `KAFKA_CONSUMER_LIFETIME_JITTER_SEC` — random deviation to avoid simultaneous restart
+- `KAFKA_AUTO_OFFSET_RESET` — Kafka auto offset reset policy
+- `KAFKA_ENABLE_AUTO_COMMIT` — Kafka auto-commit toggle
+- `KAFKA_AUTO_COMMIT_INTERVAL_MS` — auto-commit interval in ms
+- `KAFKA_LOG_LEVEL` — log level for consumers
+
+### Route Registration
+
+Add the route for getting results to your `router.py`:
+
+```python
+from bazis.core.routing import BazisRouter
+
+router = BazisRouter(prefix='/api/v1')
+
+# Register background task results route
+router.register('bazis.contrib.async_background.router')
+```
+
+This adds the endpoint: `GET /api/v1/async_background_response/{task_id}/`
+
+## Usage
+
+### Project-Level Middleware
+
+AsyncRequestMiddleware is registered automatically when `bazis.contrib.async_request` is loaded.
+Any request can be moved to background using the `X-Async-Request: true` header.
+
+**Location**: `bazis.contrib.async_request.middleware.AsyncRequestMiddleware`
+
+### Endpoint-Only Async Request (Dependency)
+
+Use a dependency to mark specific endpoints as async-only. Such routes will return `409 Conflict`
+unless the request includes `X-Async-Request` (or an internal background call with
+`X-Async-Request-Internal: true`).
+
+**Location**: `bazis.contrib.async_request.dependencies.require_async`
+
+#### Attach to a Single Route
+
+```python
+from fastapi import Depends
+from bazis.contrib.async_request.dependencies import require_async
+
+@router.post(
+    "/reports/generate/",
+    dependencies=[Depends(require_async)],
+)
+async def generate_report(...):
+    ...
+```
+
+#### Attach via Function Signature
+
+```python
+from fastapi import Depends
+from bazis.contrib.async_request.dependencies import require_async
+
+@router.post("/reports/generate/")
+async def generate_report(
+    ...,
+    _async_request: None = Depends(require_async),
+):
+    ...
+```
+### Running Consumers
+
+#### For Kubernetes (one consumer per pod)
+
+```bash
+python manage.py kafka_consumer_single
+```
+
+Runs one consumer that processes tasks from Kafka. Suitable for horizontal scaling in Kubernetes.
+
+#### For Local Development (multiple consumers)
+
+```bash
+python manage.py kafka_consumer_multiple --consumers-count=5
+```
+
+Runs 5 consumers in separate processes. Suitable for local development or deployment without orchestration.
+
+**Parameters**:
+
+- `--consumers-count` — number of consumers to run (default: 1)
+
+## Working with Frontend
+
+### Sending a Request
+
+Add the `X-Async-Request: true` header to your request:
+
+```bash
+curl -X POST \
+  http://localhost/api/v1/orders/order/ \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -H "Content-Type: application/vnd.api+json" \
+  -H "X-Async-Request: true" \
+  -d '{
+    "data": {
+      "type": "myapp.order",
+      "attributes": {
+        "description": "New Order",
+        "amount": 1000
+      }
+    }
+  }'
+```
+
+**Response** (status 202 Accepted):
+
+```json
+{
+  "data": null,
+  "meta": {
+    "async_request_id": "371564b0-29a5-457a-aabb-9c43661148a7"
+  }
+}
+```
+
+If the request has no `Authorization` header, pass a channel name directly:
+
+```bash
+X-Async-Request: <channel_name>
+```
+
+Save the `async_request_id` — this is the task identifier for retrieving the result.
+
+### Getting Result via WebSocket
+
+After sending the task, connect to WebSocket (requires `bazis-ws` package) and wait for notifications:
+
+```javascript
+// Connect to WebSocket (see bazis-ws documentation)
+const ws = new WebSocket(`ws://api.example.com/ws?token=${jwtToken}`);
+
+ws.onmessage = (event) => {
+  const data = JSON.parse(event.data);
+  
+  if (data.type === 'data') {
+    const message = JSON.parse(data.data);
+    
+    if (message.action === 'async_bg') {
+      console.log('Task ID:', message.task_id);
+      console.log('Status:', message.status);
+      
+      if (message.status === 'completed') {
+        // Task completed, get result
+        fetchResult(message.task_id);
+      } else if (message.status === 'failed') {
+        // Task failed
+        console.error('Task failed');
+      }
+    }
+  }
+};
+```
+
+**WebSocket Notification Format**:
+
+```json
+{
+  "type": "data",
+  "data": "{\"task_id\": \"371564b0-29a5-457a-aabb-9c43661148a7\", \"status\": \"completed\", \"action\": \"async_request\"}"
+}
+```
+
+**Task Statuses**:
+
+- `completed` — task successfully completed
+- `failed` — task failed with error
+
+### Getting Result via API
+
+After receiving notification about task completion, request the result:
+
+```bash
+GET /api/v1/async_background_response/{task_id}/
+Authorization: Bearer YOUR_JWT_TOKEN
+```
+
+**Example Request**:
+
+```bash
+curl -X GET \
+  http://localhost/api/v1/async_background_response/371564b0-29a5-457a-aabb-9c43661148a7/ \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+**Success Response** (status 200):
+
+```json
+{
+  "task_id": "371564b0-29a5-457a-aabb-9c43661148a7",
+  "status": 200,
+  "endpoint": "/api/v1/orders/order/e7cc4c8c-3ed1-4576-96ad-b3fd7c0b2a5a/",
+  "headers": [
+    ["content-length", "217"],
+    ["content-type", "application/vnd.api+json"]
+  ],
+  "response": {
+    "data": {
+      "type": "myapp.order",
+      "id": "e7cc4c8c-3ed1-4576-96ad-b3fd7c0b2a5a",
+      "attributes": {
+        "description": "New Order",
+        "amount": 1000,
+        "status": "draft"
+      }
+    }
+  }
+}
+```
+
+**Error Response** (status 403):
+
+```json
+{
+  "task_id": "371564b0-29a5-457a-aabb-9c43661148a7",
+  "status": 403,
+  "endpoint": "/api/v1/orders/order/e7cc4c8c-3ed1-4576-96ad-b3fd7c0b2a5a/",
+  "headers": [
+    ["content-length", "4496"],
+    ["content-type", "application/json"]
+  ],
+  "response": {
+    "errors": [
+      {
+        "detail": "Permission denied: check access",
+        "status": 403
+      }
+    ]
+  }
+}
+```
+
+## Examples
+
+### Complete Example with Frontend
+
+**Backend (models.py)**:
+
+```python
+from bazis.core.models_abstract import DtMixin, UuidMixin, JsonApiMixin
+from django.db import models
+
+class Report(DtMixin, UuidMixin, JsonApiMixin):
+    """Report whose generation takes time"""
+    title = models.CharField('Title', max_length=255)
+    date_from = models.DateField('Date From')
+    date_to = models.DateField('Date To')
+    status = models.CharField('Status', max_length=50, default='pending')
+    result_data = models.JSONField('Report Data', null=True, blank=True)
+    
+    class Meta:
+        verbose_name = 'Report'
+        verbose_name_plural = 'Reports'
+```
+
+**Frontend (JavaScript)**:
+
+```javascript
+class AsyncReportClient {
+  constructor(apiUrl, wsUrl, token) {
+    this.apiUrl = apiUrl;
+    this.token = token;
+    this.ws = null;
+    this.pendingTasks = new Map();
+    
+    // Connect to WebSocket
+    this.connectWebSocket(wsUrl);
+  }
+
+  connectWebSocket(wsUrl) {
+    this.ws = new WebSocket(`${wsUrl}?token=${this.token}`);
+    
+    this.ws.onmessage = (event) => {
+      const data = JSON.parse(event.data);
+      
+      if (data.type === 'data') {
+        const message = JSON.parse(data.data);
+        
+        if (message.action === 'async_bg') {
+          this.handleTaskUpdate(message.task_id, message.status);
+        }
+      }
+    };
+  }
+
+  async createReport(title, dateFrom, dateTo) {
+    // Send request to create report
+    const response = await fetch(`${this.apiUrl}/reports/report/`, {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${this.token}`,
+        'Content-Type': 'application/vnd.api+json',
+        'X-Async-Request': 'true'
+      },
+      body: JSON.stringify({
+        data: {
+          type: 'myapp.report',
+          attributes: {
+            title: title,
+            date_from: dateFrom,
+            date_to: dateTo
+          }
+        }
+      })
+    });
+
+    const result = await response.json();
+    const taskId = result.meta.async_request_id;
+    
+    // Save promise to wait for result
+    return new Promise((resolve, reject) => {
+      this.pendingTasks.set(taskId, { resolve, reject });
+    });
+  }
+
+  async handleTaskUpdate(taskId, status) {
+    if (!this.pendingTasks.has(taskId)) return;
+
+    const { resolve, reject } = this.pendingTasks.get(taskId);
+
+    if (status === 'completed') {
+      // Get result
+      const result = await this.getResult(taskId);
+      this.pendingTasks.delete(taskId);
+      resolve(result);
+    } else if (status === 'failed') {
+      const error = await this.getResult(taskId);
+      this.pendingTasks.delete(taskId);
+      reject(error);
+    }
+  }
+
+  async getResult(taskId) {
+    const response = await fetch(
+      `${this.apiUrl}/async_background_response/${taskId}/`,
+      {
+        headers: {
+          'Authorization': `Bearer ${this.token}`
+        }
+      }
+    );
+    return await response.json();
+  }
+}
+
+// Usage
+const client = new AsyncReportClient(
+  'http://api.example.com/api/v1',
+  'ws://api.example.com/ws',
+  jwtToken
+);
+
+// Create report
+client.createReport('Monthly Report', '2024-01-01', '2024-01-31')
+  .then(result => {
+    console.log('Report created:', result);
+    // Display result to user
+  })
+  .catch(error => {
+    console.error('Report generation failed:', error);
+  });
+```
+
+### Example for Custom Endpoint
+
+**Backend**:
+
+```python
+from fastapi import Request, Depends
+from django.contrib.auth import get_user_model
+from bazis.core.routing import BazisRouter
+from bazis.contrib.users.service import get_user_from_token
+import time
+
+User = get_user_model()
+router = BazisRouter(tags=["Analytics"])
+
+@router.post('/generate-analytics/', response_model=dict)
+async def generate_analytics(
+    report_type: str,
+    date_from: str,
+    date_to: str,
+    request: Request,
+    user: User = Depends(get_user_from_token)
+):
+    """
+    Generate analytics report (long operation)
+    """
+    # Simulate long processing
+    time.sleep(10)
+    
+    # Generate report
+    analytics_data = {
+        'report_type': report_type,
+        'period': f'{date_from} - {date_to}',
+        'total_orders': 1250,
+        'revenue': 125000.50,
+        'average_order': 100.00
+    }
+    
+    return {
+        'status': 'success',
+        'data': analytics_data
+    }
+```
+
+**Frontend**:
+
+```bash
+# Synchronous request (will wait 10 seconds)
+POST /api/v1/generate-analytics/
+Content-Type: application/json
+
+{
+  "report_type": "sales",
+  "date_from": "2024-01-01",
+  "date_to": "2024-01-31"
+}
+
+# Asynchronous request (returns task_id immediately)
+POST /api/v1/generate-analytics/
+Content-Type: application/json
+X-Async-Request: true
+
+{
+  "report_type": "sales",
+  "date_from": "2024-01-01",
+  "date_to": "2024-01-31"
+}
+```
+
+### Error Handling Example
+
+```python
+from bazis.core.routes_abstract.jsonapi import JsonapiRouteBase
+from django.apps import apps
+
+class OrderRouteSet(JsonapiRouteBase):
+    model = apps.get_model("myapp", "Order")
+    
+    def hook_before_update(self, item):
+        """Check before update"""
+        if item.status == 'draft' and not self.inject.user.is_staff:
+            from fastapi import HTTPException
+            raise HTTPException(
+                status_code=403,
+                detail="Permission denied: check access"
+            )
+        super().hook_before_update(item)
+```
+
+**Result with async processing**:
+
+```json
+{
+  "task_id": "371564b0-29a5-457a-aabb-9c43661148a7",
+  "status": 403,
+  "response": {
+    "errors": [
+      {
+        "detail": "Permission denied: check access",
+        "status": 403
+      }
+    ]
+  }
+}
+```
+
+## License
+
+Apache License 2.0
+
+See [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [Bazis Documentation](https://github.com/ecofuture-tech/bazis) — main repository
+- [Bazis WS](https://github.com/ecofuture-tech/bazis-ws) — WebSocket package
+- [Bazis Async Background Repository](https://github.com/ecofuture-tech/bazis-async-background) — core background framework
+- [Bazis Async Request Repository](https://github.com/ecofuture-tech/bazis-async-request) — package repository
+- [Issue Tracker](https://github.com/ecofuture-tech/bazis-async-request/issues) — report bugs or request features
+- [Apache Kafka](https://kafka.apache.org/) — Kafka documentation
+
+## Support
+
+If you have questions or issues:
+- Review the [Bazis documentation](https://github.com/ecofuture-tech/bazis)
+- Search [existing issues](https://github.com/ecofuture-tech/bazis-async-request/issues)
+- Create a [new issue](https://github.com/ecofuture-tech/bazis-async-request/issues/new) with detailed information
+
+---
+
+Made with ❤️ by the Bazis team

bazis_async_request-2.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+bazis/contrib/async_request/__init__.py,sha256=tDikAsHzuK1HXEh-EQ8aJzt0uqn1AWzIlR--C-AvhqA,787
+bazis/contrib/async_request/_version.py,sha256=6OGz4a0gjMGlckPyPCNiJDWyFDO-tWO8O_ZNx4ajT2Y,704
+bazis/contrib/async_request/apps.py,sha256=le2m51a2rSh1Yj6m75xWrWWBQqDdjMw3XvCSYx0pajU,949
+bazis/contrib/async_request/middleware.py,sha256=LWKGTLEBPOeeM_ZbARg-_ylmbrDU4ELBemBxsFSsHs8,3731
+bazis/contrib/async_request/schemas.py,sha256=rE1C3fkLZfsZU1DwIJ2o5wPcrpEGGqzxIew1Yg9VdKY,1588
+bazis/contrib/async_request/tasks.py,sha256=04gW2yWJ6T23HQWL1TRgFvRbgcLqg0tf_gxFtK0WjWY,4552
+bazis/contrib/async_request/utils.py,sha256=ql6FDhAN2sjWtqsyWi2Ql_XLWU9R7R4s3SqkZK-OzNw,2319
+bazis_async_request-2.2.0.dist-info/METADATA,sha256=MhK1-s6LTJNoWgnwtoYsIQHbrS9dutjIRfB34OZlO4M,20538
+bazis_async_request-2.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+bazis_async_request-2.2.0.dist-info/top_level.txt,sha256=WgdrPZTZBMG8i_EqxA3vU5qI4ETQ_RsqKqSqsfIApHY,6
+bazis_async_request-2.2.0.dist-info/RECORD,,

bazis_async_request-2.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

bazis_async_request-2.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bazis