bazis-async-request 2.2.3__tar.gz → 2.4.0__tar.gz

bazis_async_request-2.4.0/.github/workflows/build-publish.yml

@@ -0,0 +1,20 @@
+name: Build and Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  # started by the Release workflow on the tag it creates: a tag pushed with the
+  # workflow token does not trigger the push event above
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    if: startsWith(github.ref, 'refs/tags/v')
+    uses: ecofuture-tech/.github/.github/workflows/reusable-build-publish.yml@main
+    secrets:
+      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+      TEST_PYPI_TOKEN: ${{ secrets.TEST_PYPI_TOKEN }}

bazis_async_request-2.4.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+# Creates the release tag vX.Y.Z on the current main commit and starts Build and Publish
+# for it. Run it from the Actions tab (or through the GitHub API) on the main branch.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version without the "v" prefix, e.g. 2.3.0 or 2.4.0-rc1'
+        required: true
+        type: string
+
+permissions:
+  contents: write
+  actions: write
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    if: github.ref == 'refs/heads/main'
+    env:
+      GH_TOKEN: ${{ github.token }}
+      VERSION: ${{ inputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Validate the version
+        run: |
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)[0-9]+)?$ ]]; then
+            echo "::error::Invalid version '$VERSION', expected e.g. 2.3.0 or 2.4.0-rc1"
+            exit 1
+          fi
+          if git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null; then
+            echo "::error::Tag v$VERSION already exists"
+            exit 1
+          fi
+          # versionsort.suffix: a pre-release (v2.4.0-rc1) sorts before its release (v2.4.0)
+          LAST_TAG=$(git -c versionsort.suffix=- tag --list 'v*' --sort=-v:refname | head -n 1)
+          echo "Last release: ${LAST_TAG:-none}, new release: v$VERSION"
+          # sort -V orders "~" before anything, as versionsort.suffix does with "-"
+          NEWEST=$(printf '%s\n%s\n' "${LAST_TAG#v}" "$VERSION" | sed 's/-/~/' | sort -V | tail -n 1)
+          if [ -n "$LAST_TAG" ] && [ "$NEWEST" != "${VERSION/-/\~}" ]; then
+            echo "::error::Version $VERSION is not newer than $LAST_TAG"
+            exit 1
+          fi
+
+      - name: Require green tests on this commit
+        run: |
+          CONCLUSION=$(gh run list --workflow tests.yml --commit "$GITHUB_SHA" --status completed \
+            --json conclusion --jq 'map(.conclusion) | first // "none"')
+          echo "Tests on $GITHUB_SHA: $CONCLUSION"
+          if [ "$CONCLUSION" != "success" ]; then
+            echo "::error::The Tests workflow has not succeeded on $GITHUB_SHA ($CONCLUSION)"
+            exit 1
+          fi
+
+      - name: Create the tag
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+          git tag -a "v$VERSION" -m "${{ github.event.repository.name }} $VERSION" "$GITHUB_SHA"
+          git push origin "v$VERSION"
+
+      - name: Start Build and Publish
+        run: gh workflow run build-publish.yml --ref "v$VERSION"
+
+      - name: Summary
+        run: |
+          echo "Tagged \`v$VERSION\` at \`$GITHUB_SHA\` and started Build and Publish." >> "$GITHUB_STEP_SUMMARY"

bazis_async_request-2.4.0/.github/workflows/tests.yml

@@ -0,0 +1,131 @@
+name: Tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uvx ruff check bazis tests sample
+
+  tests:
+    name: tests (python ${{ matrix.python }}, ${{ matrix.resolution }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ['3.12', '3.13', '3.14']
+        resolution: [highest]
+        include:
+          # the lowest versions allowed by pyproject.toml
+          - python: '3.12'
+            resolution: lowest-direct
+
+    services:
+      postgres:
+        image: postgis/postgis:16-3.4
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: bazis
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+      redis:
+        image: redis:7
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+      kafka:
+        image: apache/kafka:3.9.1
+        ports:
+          - 9092:9092
+        options: >-
+          --health-cmd "/opt/kafka/bin/kafka-broker-api-versions.sh --bootstrap-server localhost:9092"
+          --health-interval 10s
+          --health-timeout 10s
+          --health-retries 15
+    env:
+      BS_DEBUG: 'true'
+      BS_SECRET_KEY: ci-only-secret-key-that-is-long-enough-0123456789
+      BS_DATABASES__DEFAULT__HOST: localhost
+      BS_DATABASES__DEFAULT__PORT: '5432'
+      BS_DATABASES__DEFAULT__NAME: bazis
+      BS_DATABASES__DEFAULT__USER: postgres
+      BS_DATABASES__DEFAULT__PASSWORD: postgres
+      BS_CACHES__DEFAULT__LOCATION: redis://localhost:6379/1
+      BS_MEDIA_ROOT: /tmp/bazis/media
+      BS_STATIC_ROOT: /tmp/bazis/static
+      BS_WEBAPP_ROOT: /tmp/bazis/webapp
+      BS_KAFKA_BOOTSTRAP_SERVERS: localhost:9092
+      BS_KAFKA_TOPIC_ASYNC_BG: sample_local_async_request
+      BS_KAFKA_GROUP_ID: sample_local
+      BS_KAFKA_AUTO_OFFSET_RESET: earliest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install GDAL (required by the PostGIS database backend)
+        # a stalled Ubuntu mirror must fail the step quickly instead of hanging the job
+        timeout-minutes: 10
+        run: |
+          APT="sudo apt-get -o Acquire::Retries=3 -o Acquire::http::Timeout=30 -o Acquire::https::Timeout=30"
+          $APT update
+          $APT install -y --no-install-recommends gdal-bin
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+          activate-environment: true
+
+      - name: Install dependencies
+        run: uv pip install --resolution ${{ matrix.resolution }} -e '.[test]'
+
+      - name: Check for missing migrations
+        working-directory: sample
+        run: python manage.py makemigrations --check --dry-run
+
+      - name: Migrate the database shared by the tests and the consumer
+        # sample/settings.py sets TEST.NAME to the database name, so that the consumer sees
+        # the data of the tests; pytest runs with --reuse-db
+        working-directory: sample
+        run: |
+          python manage.py migrate -v0
+          python manage.py pgtrigger install
+
+      - name: Start a Kafka consumer
+        working-directory: sample
+        run: |
+          nohup python manage.py kafka_consumer_single > "$RUNNER_TEMP/consumer.log" 2>&1 &
+          sleep 15
+          cat "$RUNNER_TEMP/consumer.log"
+
+      - name: Run tests
+        working-directory: sample
+        run: python -m pytest ../tests -o addopts="--reuse-db" -p no:cacheprovider
+
+      - name: Consumer log
+        if: failure()
+        run: cat "$RUNNER_TEMP/consumer.log"

bazis_async_request-2.4.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# bazis-async-request
+
+Background HTTP requests for Bazis: `AsyncRequestMiddleware` puts a request with
+`X-Async-Background: true` into Kafka (bazis-async-background) and answers 202 with the task
+id; the consumer (`tasks.py`) replays the request through the ASGI application, marked as
+internal in the ASGI scope (`SCOPE_INTERNAL_KEY`), and stores the response for
+`GET /async_background_response/{task_id}/`. `require_async` limits an endpoint to such
+requests.
+
+Never trust a header to recognize the requests of the consumer: clients can send any header.
+
+The package code is in `bazis/contrib/async_request`, the sample project used by the tests is in `sample/`,
+the tests are in `tests/`.
+
+## Running the tests
+
+The tests need PostgreSQL with PostGIS and Redis and Kafka (see `.github/workflows/tests.yml`).
+Run them from the `sample` directory:
+
+```bash
+cd sample
+BS_DEBUG=true \
+BS_SECRET_KEY=local-secret-key-that-is-long-enough-0123456789 \
+BS_DATABASES__DEFAULT__HOST=localhost BS_DATABASES__DEFAULT__PORT=5432 \
+BS_DATABASES__DEFAULT__NAME=bazis BS_DATABASES__DEFAULT__USER=postgres \
+BS_DATABASES__DEFAULT__PASSWORD=postgres \
+BS_CACHES__DEFAULT__LOCATION=redis://localhost:6379/1 \
+BS_MEDIA_ROOT=/tmp/bazis/media BS_STATIC_ROOT=/tmp/bazis/static BS_WEBAPP_ROOT=/tmp/bazis/webapp \
+BS_KAFKA_BOOTSTRAP_SERVERS=localhost:9092 BS_KAFKA_TOPIC_ASYNC_BG=sample_local_async_request \
+BS_KAFKA_GROUP_ID=sample_local \
+python -m pytest ../tests -o addopts="--reuse-db" -p no:cacheprovider
+```
+
+The tests and the consumer share one database (`sample/sample/settings.py` sets `TEST.NAME`
+to the database name): migrate it first (`python manage.py migrate` and
+`python manage.py pgtrigger install` in `sample`), start a consumer with the same variables
+(`python manage.py kafka_consumer_single &`) and run pytest with `-o addopts="--reuse-db"`.
+The tests marked `run_with_consumer` are skipped without Kafka settings. A local Kafka
+without Docker: download the Kafka binaries and start a single KRaft node.
+
+Lint: `ruff check bazis tests sample`. CI also runs `python manage.py makemigrations --check
+--dry-run` in `sample`: commit the migrations of model changes, including the sample apps.
+
+## Releasing
+
+A release is the tag `vX.Y.Z` on `main`: the Build and Publish workflow builds the package
+(the version comes from the tag through setuptools-scm) and publishes it to PyPI
+(pre-releases `-alphaN`/`-betaN`/`-rcN` go to Test PyPI) and creates the GitHub release.
+
+Claude Code sessions cannot push tags. Release through the **Release** workflow instead:
+
+1. Make sure the changes are merged into `main` and the Tests workflow is green on the
+   `main` head commit (the Release workflow checks this and refuses otherwise).
+2. Add the release notes as `docs/releases/X.Y.Z.md` in the change being released.
+3. Start the workflow `release.yml` on `ref: main` with the input `version: X.Y.Z`
+   (GitHub API: `POST /repos/ecofuture-tech/bazis-async-request/actions/workflows/release.yml/dispatches`;
+   with the GitHub MCP tools: `actions_run_trigger`, method `run_workflow`).
+4. The Release run creates the annotated tag and starts Build and Publish on it. Check
+   that both runs succeed and that the version appears on https://pypi.org/project/bazis-async-request/.
+
+Release the Bazis packages in dependency order: a package is tested in CI against the
+versions of its Bazis dependencies published on PyPI. Pick the version by semver:
+breaking changes (settings renamed or required, dependency removed, behavior changed)
+bump the minor version while the project is below 3.0.

{bazis_async_request-2.2.3 → bazis_async_request-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bazis-async-request
-Version: 2.2.3
+Version: 2.4.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>
@@ -17,9 +17,14 @@ Classifier: Framework :: Django
 Classifier: Framework :: FastAPI
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: bazis-async-background
+Requires-Dist: bazis>=2.4.0
+Requires-Dist: bazis-async-background>=2.3.0
 Provides-Extra: test
-Requires-Dist: bazis-test-utils>=2.2.0; extra == "test"
+Requires-Dist: bazis-test-utils>=2.3.0; extra == "test"
+Requires-Dist: bazis-users>=2.3.0; extra == "test"
+Requires-Dist: bazis-author>=2.3.0; extra == "test"
+Requires-Dist: bazis-permit>=2.3.0; extra == "test"
+Requires-Dist: bazis-ws>=2.3.0; extra == "test"
 Provides-Extra: dev
 Requires-Dist: ruff; extra == "dev"
 
@@ -83,7 +88,7 @@ python manage.py kafka_consumer_multiple --consumers-count=5
 - **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.
+**How it works**: When sending a request with the `X-Async-Background: 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.**
 
@@ -127,7 +132,7 @@ This waits for the pytest container to finish and streams logs only from the Pyt
 ┌─────────────┐
 │   Client    │
 └──────┬──────┘
-       │ POST + X-Async-Request: true
+       │ POST + X-Async-Background: true
        ▼
 ┌─────────────────────┐
 │   API Endpoint      │
@@ -231,24 +236,34 @@ This adds the endpoint: `GET /api/v1/async_background_response/{task_id}/`
 
 ### 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.
+Add the middleware to the application (it is not added automatically):
+
+```python
+from bazis.contrib.async_request.middleware import AsyncRequestMiddleware
+from bazis.core.app import app
+
+app.add_middleware(AsyncRequestMiddleware)
+```
+
+Any request can be moved to background using the `X-Async-Background: 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`).
+unless the request is executed in the background (the client sends it with
+`X-Async-Background: true`, and the consumer executes it). The consumer marks its requests
+in the ASGI scope, which clients cannot forge; the former `X-Async-Background-Internal`
+header is ignored.
 
-**Location**: `bazis.contrib.async_request.dependencies.require_async`
+**Location**: `bazis.contrib.async_request.utils.require_async`
 
 #### Attach to a Single Route
 
 ```python
 from fastapi import Depends
-from bazis.contrib.async_request.dependencies import require_async
+from bazis.contrib.async_request.utils import require_async
 
 @router.post(
     "/reports/generate/",
@@ -262,12 +277,12 @@ async def generate_report(...):
 
 ```python
 from fastapi import Depends
-from bazis.contrib.async_request.dependencies import require_async
+from bazis.contrib.async_request.utils import require_async
 
 @router.post("/reports/generate/")
 async def generate_report(
     ...,
-    _async_request: None = Depends(require_async),
+    async_request: None = Depends(require_async),
 ):
     ...
 ```
@@ -291,20 +306,22 @@ Runs 5 consumers in separate processes. Suitable for local development or deploy
 
 **Parameters**:
 
-- `--consumers-count` — number of consumers to run (default: 1)
+- `--consumers-count` — number of consumers to run (default: 15)
+- `--restart-delay-sec` — delay before restarting a consumer that exited (default: 1.0)
+- `--max-restarts` — restarts of a failed consumer before it is given up (default: unlimited)
 
 ## Working with Frontend
 
 ### Sending a Request
 
-Add the `X-Async-Request: true` header to your request:
+Add the `X-Async-Background: 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" \
+  -H "X-Async-Background: true" \
   -d '{
     "data": {
       "type": "myapp.order",
@@ -327,11 +344,12 @@ curl -X POST \
 }
 ```
 
-If the request has no `Authorization` header, pass a channel name directly:
+A client without a user token sends an anonymous token it generated itself (16–128
+characters `A-Z a-z 0-9 _ -`, e.g. a random UUID) as `Authorization: Bearer <token>`; the same
+token subscribes to its WebSocket channel (bazis-ws) and reads the result.
 
-```bash
-X-Async-Request: <channel_name>
-```
+The request is stored in the Kafka topic with all its headers, `Authorization` included, and
+executed later with them: protect the topic accordingly.
 
 Save the `async_request_id` — this is the task identifier for retrieving the result.
 
@@ -503,7 +521,7 @@ class AsyncReportClient {
       headers: {
         'Authorization': `Bearer ${this.token}`,
         'Content-Type': 'application/vnd.api+json',
-        'X-Async-Request': 'true'
+        'X-Async-Background': 'true'
       },
       body: JSON.stringify({
         data: {
@@ -633,7 +651,7 @@ Content-Type: application/json
 # Asynchronous request (returns task_id immediately)
 POST /api/v1/generate-analytics/
 Content-Type: application/json
-X-Async-Request: true
+X-Async-Background: true
 
 {
   "report_type": "sales",

{bazis_async_request-2.2.3 → bazis_async_request-2.4.0}/README.md

@@ -58,7 +58,7 @@ python manage.py kafka_consumer_multiple --consumers-count=5
 - **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.
+**How it works**: When sending a request with the `X-Async-Background: 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.**
 
@@ -102,7 +102,7 @@ This waits for the pytest container to finish and streams logs only from the Pyt
 ┌─────────────┐
 │   Client    │
 └──────┬──────┘
-       │ POST + X-Async-Request: true
+       │ POST + X-Async-Background: true
        ▼
 ┌─────────────────────┐
 │   API Endpoint      │
@@ -206,24 +206,34 @@ This adds the endpoint: `GET /api/v1/async_background_response/{task_id}/`
 
 ### 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.
+Add the middleware to the application (it is not added automatically):
+
+```python
+from bazis.contrib.async_request.middleware import AsyncRequestMiddleware
+from bazis.core.app import app
+
+app.add_middleware(AsyncRequestMiddleware)
+```
+
+Any request can be moved to background using the `X-Async-Background: 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`).
+unless the request is executed in the background (the client sends it with
+`X-Async-Background: true`, and the consumer executes it). The consumer marks its requests
+in the ASGI scope, which clients cannot forge; the former `X-Async-Background-Internal`
+header is ignored.
 
-**Location**: `bazis.contrib.async_request.dependencies.require_async`
+**Location**: `bazis.contrib.async_request.utils.require_async`
 
 #### Attach to a Single Route
 
 ```python
 from fastapi import Depends
-from bazis.contrib.async_request.dependencies import require_async
+from bazis.contrib.async_request.utils import require_async
 
 @router.post(
     "/reports/generate/",
@@ -237,12 +247,12 @@ async def generate_report(...):
 
 ```python
 from fastapi import Depends
-from bazis.contrib.async_request.dependencies import require_async
+from bazis.contrib.async_request.utils import require_async
 
 @router.post("/reports/generate/")
 async def generate_report(
     ...,
-    _async_request: None = Depends(require_async),
+    async_request: None = Depends(require_async),
 ):
     ...
 ```
@@ -266,20 +276,22 @@ Runs 5 consumers in separate processes. Suitable for local development or deploy
 
 **Parameters**:
 
-- `--consumers-count` — number of consumers to run (default: 1)
+- `--consumers-count` — number of consumers to run (default: 15)
+- `--restart-delay-sec` — delay before restarting a consumer that exited (default: 1.0)
+- `--max-restarts` — restarts of a failed consumer before it is given up (default: unlimited)
 
 ## Working with Frontend
 
 ### Sending a Request
 
-Add the `X-Async-Request: true` header to your request:
+Add the `X-Async-Background: 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" \
+  -H "X-Async-Background: true" \
   -d '{
     "data": {
       "type": "myapp.order",
@@ -302,11 +314,12 @@ curl -X POST \
 }
 ```
 
-If the request has no `Authorization` header, pass a channel name directly:
+A client without a user token sends an anonymous token it generated itself (16–128
+characters `A-Z a-z 0-9 _ -`, e.g. a random UUID) as `Authorization: Bearer <token>`; the same
+token subscribes to its WebSocket channel (bazis-ws) and reads the result.
 
-```bash
-X-Async-Request: <channel_name>
-```
+The request is stored in the Kafka topic with all its headers, `Authorization` included, and
+executed later with them: protect the topic accordingly.
 
 Save the `async_request_id` — this is the task identifier for retrieving the result.
 
@@ -478,7 +491,7 @@ class AsyncReportClient {
       headers: {
         'Authorization': `Bearer ${this.token}`,
         'Content-Type': 'application/vnd.api+json',
-        'X-Async-Request': 'true'
+        'X-Async-Background': 'true'
       },
       body: JSON.stringify({
         data: {
@@ -608,7 +621,7 @@ Content-Type: application/json
 # Asynchronous request (returns task_id immediately)
 POST /api/v1/generate-analytics/
 Content-Type: application/json
-X-Async-Request: true
+X-Async-Background: true
 
 {
   "report_type": "sales",

bazis_async_request-2.4.0/bazis/contrib/async_request/AGENTS.md

@@ -0,0 +1,75 @@
+# bazis-async-request — guide for AI agents
+
+Runs any HTTP request of a Bazis API in the background: a request with the header
+`X-Async-Background` is queued in Kafka (bazis-async-background) and answered 202; a
+consumer replays it through the ASGI application and stores the response for
+`GET /async_background_response/{task_id}/`. Use it for slow endpoints and bulk changes.
+
+## Setup
+
+```bash
+BS_INSTALLED_APPS='[..., "bazis.contrib.async_request", "bazis.contrib.async_background"]'
+BS_KAFKA_TASKS='["bazis.contrib.async_request.tasks"]'   # the consumer of the requests
+BS_KAFKA_BOOTSTRAP_SERVERS=kafka:9092
+BS_KAFKA_TOPIC_ASYNC_BG=myproject_async_request
+BS_KAFKA_GROUP_ID=myproject
+```
+
+```python
+# the main module of the application (as sample/sample/main.py)
+from bazis.contrib.async_request.middleware import AsyncRequestMiddleware
+from bazis.core.app import app
+
+app.add_middleware(AsyncRequestMiddleware)      # not added automatically
+
+# the root router
+router.register('bazis.contrib.async_background.router')    # async_request.E001
+```
+
+- Services and consumers as in bazis-async-background: Kafka, Redis, and
+  `python manage.py kafka_consumer_single` (or `kafka_consumer_multiple`) with the same
+  settings and database as the API.
+- Without Kafka settings the middleware executes these requests synchronously and only
+  logs a warning (`async_request.W001`).
+
+## Client
+
+- Send the request as usual plus `X-Async-Background: true` (the header's presence is
+  enough) and `Authorization: Bearer <token>`: a session JWT, or an anonymous token of
+  bazis-ws (16–128 characters `A-Z a-z 0-9 _ -`). Without a valid token: 401. The request
+  is replayed with the same header: routes that read the user (bazis-users, permit, author)
+  answer 401 to an anonymous token, so use it only for routes that do not.
+- Answer: 202 `{"data": null, "meta": {"async_request_id": <id>, "async_background_id": <id>}}`
+  (the same task id). Status updates arrive on the WebSocket channel of the token.
+- Result: `GET .../async_background_response/{task_id}/` with the same token returns
+  `{"task_id", "endpoint", "status", "headers", "response"}` of the replayed request
+  (an HTTP error is a `completed` task with its status); `{"status": "not ready"}` before.
+
+## Endpoints only for background requests
+
+```python
+from fastapi import Depends
+from bazis.contrib.async_request.utils import require_async
+
+@router.post('/reports/generate/', dependencies=[Depends(require_async)])
+async def generate_report(...): ...
+
+class ShopRouteSet(JsonapiRouteBase):
+    @inject_make(CrudApiAction.UPDATE)          # bazis.core.routes_abstract.initial
+    class InjectRequireAsync:
+        async_request: None = Depends(require_async)   # the annotation is required
+```
+
+A direct request to such an endpoint is 409.
+
+## Rules
+
+- Recognize the requests of the consumer only with `is_internal_request(scope)`
+  (`SCOPE_INTERNAL_KEY` in the ASGI scope, which clients cannot set). Never trust a
+  header: `X-Async-Background-Internal` is ignored.
+- Only JSON bodies (an object or a list of objects) are queued: another body (multipart,
+  form, binary) is replayed as `{}`.
+- The queued request keeps all headers, `Authorization` included, in the Kafka topic; it
+  runs with the client's token, so the token must still be valid when the consumer runs it.
+- Requests with the same `data.id` in the body go to the same Kafka partition.
+- WebSocket requests and the results route are never queued.