bazis-async-background 2.2.2__tar.gz → 2.3.0__tar.gz

bazis_async_background-2.3.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_background-2.3.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+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
+          LAST_TAG=$(git tag --list 'v*' --sort=-v:refname | head -n 1)
+          echo "Last release: ${LAST_TAG:-none}, new release: v$VERSION"
+          if [ -n "$LAST_TAG" ] && [ "$(printf '%s\n%s\n' "${LAST_TAG#v}" "$VERSION" | sort -V | tail -n 1)" != "$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_background-2.3.0/.github/workflows/tests.yml

@@ -0,0 +1,123 @@
+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
+
+  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_background
+      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: 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="" -p no:cacheprovider
+
+      - name: Consumer log
+        if: failure()
+        run: cat "$RUNNER_TEMP/consumer.log"

bazis_async_background-2.3.0/CLAUDE.md

@@ -0,0 +1,64 @@
+# bazis-async-background
+
+Background tasks over Kafka for Bazis (FastStream): `enqueue_task_async` stores the status of a task in
+Redis and publishes it to a Kafka topic; consumer processes (`kafka_consumer_single` /
+`kafka_consumer_multiple`) run the subscribers registered in the `KAFKA_TASKS` modules
+(`subscriber_kwargs()` builds their arguments from the settings) and publish the statuses to
+the WebSocket channel of the client (bazis-ws). `GET /async_background_response/{task_id}/`
+returns the result to the owner of the channel.
+
+The channel of a request is resolved by `resolve_channel_name_async` with the functions of
+bazis-ws: an anonymous token must never address a user channel.
+
+The package code is in `bazis/contrib/async_background`, 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_background \
+BS_KAFKA_GROUP_ID=sample_local \
+python -m pytest ../tests -o addopts="" -p no:cacheprovider
+```
+
+The tests marked `kafka` also need a running consumer (start it first, from `sample`, with
+the same variables): `python manage.py kafka_consumer_single &`. Without Kafka settings they
+are skipped. A local Kafka without Docker: download the Kafka binaries and start a single
+KRaft node (`bin/kafka-storage.sh format ...`, `bin/kafka-server-start.sh
+config/kraft/server.properties`).
+
+Lint: `ruff check bazis tests`. 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-background/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-background/.
+
+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_background-2.2.2 → bazis_async_background-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bazis-async-background
-Version: 2.2.2
+Version: 2.3.0
 Summary: Async Background core framework for Bazis.
 Author-email: Ilya Kharyn <ilya.tt07@gmail.com>
 Maintainer-email: Ilya Kharyn <ilya.tt07@gmail.com>
@@ -17,11 +17,12 @@ Classifier: Framework :: Django
 Classifier: Framework :: FastAPI
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
-Requires-Dist: bazis
-Requires-Dist: bazis-ws
-Requires-Dist: faststream[kafka]
+Requires-Dist: bazis>=2.3.1
+Requires-Dist: bazis-ws>=2.3.0
+Requires-Dist: faststream[kafka]>=0.6
+Requires-Dist: redis>=5.0
 Provides-Extra: test
-Requires-Dist: bazis-test-utils; extra == "test"
+Requires-Dist: bazis-test-utils>=2.3.0; extra == "test"
 Provides-Extra: dev
 Requires-Dist: ruff; extra == "dev"
 
@@ -197,8 +198,10 @@ BS_KAFKA_TASKS='["my_app.background.tasks"]'
 - `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_ENABLE_AUTO_COMMIT` — commit a message before processing it (FastStream `AckPolicy.ACK_FIRST`; not recommended: a crash loses the message)
+- `KAFKA_ACK_POLICY` — without auto commit, when a message is committed: `reject_on_error` (default: after processing, also when it failed, so a failing message is not redelivered forever), `nack_on_error` (only after a successful processing) or `ack`
 - `KAFKA_AUTO_COMMIT_INTERVAL_MS` — auto-commit interval in ms
+- `KAFKA_PUBLISH_TIMEOUT_SEC` — timeout of publishing a task
 - `KAFKA_LOG_LEVEL` — log level for consumers
 
 ### Route Registration
@@ -214,7 +217,14 @@ router = BazisRouter(prefix='/api/v1')
 router.register('bazis.contrib.async_background.router')
 ```
 
-This adds the endpoint: `GET /api/v1/async_background_response/{task_id}/`
+This adds the endpoint: `GET /api/v1/async_background_response/{task_id}/`.
+
+The request must carry the same `Authorization: Bearer <token>` as the request that created
+the task: a user session JWT (bazis-users) or an anonymous token generated by the client
+(16–128 characters `A-Z a-z 0-9 _ -`). The token determines the WebSocket channel of the
+client (bazis-ws), which receives the status updates and owns the results; the results of
+other channels are refused with 403. The statuses are stored in the cache database under
+`async_bg:task:<task_id>` for `KAFKA_RESPONSE_HOLD_SEC`.
 
 ## Usage
 
@@ -245,7 +255,7 @@ Runs 5 consumers in separate processes. Suitable for local development or deploy
 ### Minimal Task Registration
 
 ```python
-from bazis.contrib.async_background.broker import get_broker_for_consumer
+from bazis.contrib.async_background.broker import get_broker_for_consumer, subscriber_kwargs
 from bazis.contrib.async_background.schemas import KafkaTask, TaskStatus
 from bazis.contrib.async_background.utils import set_and_publish_status_async
 from pydantic import BaseModel
@@ -255,7 +265,7 @@ class DemoPayload(BaseModel):
     message: str
 
 
-@get_broker_for_consumer().subscriber("my_app_background_tasks")
+@get_broker_for_consumer().subscriber("my_app_background_tasks", **subscriber_kwargs())
 async def consumer_demo(task: KafkaTask[DemoPayload]):
     await set_and_publish_status_async(
         task_id=task.task_id,

{bazis_async_background-2.2.2 → bazis_async_background-2.3.0}/README.md

@@ -170,8 +170,10 @@ BS_KAFKA_TASKS='["my_app.background.tasks"]'
 - `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_ENABLE_AUTO_COMMIT` — commit a message before processing it (FastStream `AckPolicy.ACK_FIRST`; not recommended: a crash loses the message)
+- `KAFKA_ACK_POLICY` — without auto commit, when a message is committed: `reject_on_error` (default: after processing, also when it failed, so a failing message is not redelivered forever), `nack_on_error` (only after a successful processing) or `ack`
 - `KAFKA_AUTO_COMMIT_INTERVAL_MS` — auto-commit interval in ms
+- `KAFKA_PUBLISH_TIMEOUT_SEC` — timeout of publishing a task
 - `KAFKA_LOG_LEVEL` — log level for consumers
 
 ### Route Registration
@@ -187,7 +189,14 @@ router = BazisRouter(prefix='/api/v1')
 router.register('bazis.contrib.async_background.router')
 ```
 
-This adds the endpoint: `GET /api/v1/async_background_response/{task_id}/`
+This adds the endpoint: `GET /api/v1/async_background_response/{task_id}/`.
+
+The request must carry the same `Authorization: Bearer <token>` as the request that created
+the task: a user session JWT (bazis-users) or an anonymous token generated by the client
+(16–128 characters `A-Z a-z 0-9 _ -`). The token determines the WebSocket channel of the
+client (bazis-ws), which receives the status updates and owns the results; the results of
+other channels are refused with 403. The statuses are stored in the cache database under
+`async_bg:task:<task_id>` for `KAFKA_RESPONSE_HOLD_SEC`.
 
 ## Usage
 
@@ -218,7 +227,7 @@ Runs 5 consumers in separate processes. Suitable for local development or deploy
 ### Minimal Task Registration
 
 ```python
-from bazis.contrib.async_background.broker import get_broker_for_consumer
+from bazis.contrib.async_background.broker import get_broker_for_consumer, subscriber_kwargs
 from bazis.contrib.async_background.schemas import KafkaTask, TaskStatus
 from bazis.contrib.async_background.utils import set_and_publish_status_async
 from pydantic import BaseModel
@@ -228,7 +237,7 @@ class DemoPayload(BaseModel):
     message: str
 
 
-@get_broker_for_consumer().subscriber("my_app_background_tasks")
+@get_broker_for_consumer().subscriber("my_app_background_tasks", **subscriber_kwargs())
 async def consumer_demo(task: KafkaTask[DemoPayload]):
     await set_and_publish_status_async(
         task_id=task.task_id,

bazis_async_background-2.3.0/bazis/contrib/async_background/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '2.3.0'
+__version_tuple__ = version_tuple = (2, 3, 0)
+
+__commit_id__ = commit_id = 'gf5747b6d2'

bazis_async_background-2.3.0/bazis/contrib/async_background/broker.py

@@ -0,0 +1,241 @@
+# 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 asyncio
+import logging
+import random
+from contextlib import asynccontextmanager
+
+from django.conf import settings
+
+from aiokafka.admin import AIOKafkaAdminClient, NewTopic
+from aiokafka.errors import NoError, TopicAlreadyExistsError
+from faststream import AckPolicy, FastStream
+from faststream.kafka import KafkaBroker
+
+
+logger = logging.getLogger(__name__)
+
+
+_brokers_by_loop: dict[asyncio.AbstractEventLoop, KafkaBroker] = {}
+
+
+def drop_closed_loops(registry: dict):
+    """
+    Removes the objects of closed event loops from a per-loop registry: the objects refer to
+    their loop, so a weak registry would never release them.
+    """
+    for loop in [loop for loop in registry if loop.is_closed()]:
+        del registry[loop]
+_consumer_broker: KafkaBroker | None = None
+
+
+def _new_broker() -> KafkaBroker:
+    # the broker connects when it starts: the task modules can be imported without Kafka.
+    # The publication is bounded by the request timeout of the producer: cancelling it from
+    # outside would leave the message queued in the producer and delivered later
+    return KafkaBroker(
+        settings.KAFKA_BOOTSTRAP_SERVERS or 'localhost',
+        request_timeout_ms=settings.KAFKA_PUBLISH_TIMEOUT_SEC * 1000,
+    )
+
+
+def get_broker_for_async() -> KafkaBroker:
+    """
+    Returns the (not started) publishing broker of the running event loop: a broker and
+    its connections cannot be shared between event loops.
+    """
+    loop = asyncio.get_running_loop()
+    broker = _brokers_by_loop.get(loop)
+    if broker is None:
+        drop_closed_loops(_brokers_by_loop)
+        broker = _new_broker()
+        _brokers_by_loop[loop] = broker
+    return broker
+
+
+def get_broker_for_consumer() -> KafkaBroker:
+    """
+    Returns the broker that the subscribers of the consumer process register on.
+    """
+    global _consumer_broker
+    if _consumer_broker is None:
+        _consumer_broker = _new_broker()
+    return _consumer_broker
+
+
+def subscriber_kwargs(**overrides) -> dict:
+    """
+    The arguments of `broker.subscriber(...)` from the KAFKA_* settings, for the installed
+    FastStream (`auto_commit` was replaced by `ack_policy` in FastStream 0.6)::
+
+        @get_broker_for_consumer().subscriber(settings.KAFKA_TOPIC_ASYNC_BG, **subscriber_kwargs())
+        async def consumer(task: KafkaTask[MyPayload]): ...
+    """
+    kwargs: dict[str, object] = {
+        'auto_offset_reset': settings.KAFKA_AUTO_OFFSET_RESET,
+        'auto_commit_interval_ms': settings.KAFKA_AUTO_COMMIT_INTERVAL_MS,
+        'consumer_timeout_ms': settings.KAFKA_CONSUMER_TIMEOUT_MS,
+        'ack_policy': (
+            AckPolicy.ACK_FIRST
+            if settings.KAFKA_ENABLE_AUTO_COMMIT
+            else AckPolicy(settings.KAFKA_ACK_POLICY)
+        ),
+    }
+    if settings.KAFKA_GROUP_ID:
+        kwargs['group_id'] = settings.KAFKA_GROUP_ID
+    if settings.KAFKA_FETCH_MIN_BYTES is not None:
+        kwargs['fetch_min_bytes'] = settings.KAFKA_FETCH_MIN_BYTES
+    if settings.KAFKA_FETCH_MAX_WAIT_MS is not None:
+        kwargs['fetch_max_wait_ms'] = settings.KAFKA_FETCH_MAX_WAIT_MS
+    kwargs.update(overrides)
+    return kwargs
+
+
+def consumer_lifetime() -> float | None:
+    """
+    The lifetime of a consumer process in seconds (with a random jitter), or None.
+    """
+    if not settings.KAFKA_CONSUMER_LIFETIME_SEC:
+        return None
+    jitter = settings.KAFKA_CONSUMER_LIFETIME_JITTER_SEC or 0
+    return settings.KAFKA_CONSUMER_LIFETIME_SEC + random.randint(0, jitter)
+
+
+def lifetime_hooks(app: FastStream, lifetime: float):
+    """
+    Returns the hooks that start and cancel the timer which stops the application after
+    its lifetime.
+    """
+    timer: dict[str, asyncio.Task] = {}
+
+    async def stop_after_lifetime():
+        await asyncio.sleep(lifetime)
+        logger.info('Kafka consumer lifetime of %s s is over, stopping.', round(lifetime))
+        app.exit()
+
+    async def start_lifetime_timer():
+        timer['task'] = asyncio.create_task(stop_after_lifetime())
+
+    async def stop_lifetime_timer():
+        if task := timer.get('task'):
+            task.cancel()
+
+    return start_lifetime_timer, stop_lifetime_timer
+
+
+def build_app() -> FastStream:
+    """
+    The FastStream application of a consumer process. With KAFKA_CONSUMER_LIFETIME_SEC the
+    application stops after its lifetime, and kafka_consumer_multiple starts a new process.
+    """
+    app = FastStream(get_broker_for_consumer())
+    if lifetime := consumer_lifetime():
+        start_timer, stop_timer = lifetime_hooks(app, lifetime)
+        app.after_startup(start_timer)
+        app.on_shutdown(stop_timer)
+    return app
+
+
+@asynccontextmanager
+async def _get_admin_client():
+    admin_client = AIOKafkaAdminClient(
+        bootstrap_servers=settings.KAFKA_BOOTSTRAP_SERVERS,
+        request_timeout_ms=settings.KAFKA_ADMIN_TIMEOUT_MS,
+    )
+    started = False
+    try:
+        await admin_client.start()
+        started = True
+        yield admin_client
+    finally:
+        if started:
+            await admin_client.close()
+        else:
+            try:
+                await admin_client.close()
+            except Exception:
+                logger.debug(
+                    "Kafka admin client close failed after failed start.",
+                    exc_info=True,
+                )
+
+
+async def ensure_topic_exists(
+    topic_name: str,
+    num_partitions: int | None = None,
+    replication_factor: int | None = None,
+) -> None:
+    logger.info("Ensuring Kafka topic '%s' exists...", topic_name)
+
+    resolved_num_partitions = num_partitions or settings.KAFKA_AUTO_TOPIC_NUM_PARTITIONS
+    resolved_replication_factor = replication_factor or settings.KAFKA_AUTO_TOPIC_REPLICATION_FACTOR
+
+    try:
+        async with _get_admin_client() as admin_client:
+            topics = await admin_client.list_topics()
+            if topic_name in topics:
+                logger.info("Kafka topic '%s' already exists.", topic_name)
+                return
+
+            new_topic = NewTopic(
+                name=topic_name,
+                num_partitions=resolved_num_partitions,
+                replication_factor=resolved_replication_factor,
+            )
+
+            resp = await admin_client.create_topics([new_topic])
+
+            for err in getattr(resp, "topic_errors", []):
+                # err[0]/err[1]/err[2] topic/error_code/message
+                error_code = err[1]
+                if error_code == NoError.errno:
+                    continue
+
+                if error_code == TopicAlreadyExistsError.errno:
+                    logger.info("Kafka topic '%s' already exists.", topic_name)
+                    return
+
+                error_message = err[2] if len(err) > 2 else None
+                raise RuntimeError(
+                    f"Error creating Kafka topic '{topic_name}': "
+                    f"code={error_code} message={error_message}"
+                )
+
+        logger.info("Kafka topic '%s' created successfully.", topic_name)
+    except TopicAlreadyExistsError:
+        logger.info("Kafka topic '%s' already exists.", topic_name)
+    except Exception:
+        logger.exception("Error creating Kafka topic '%s'.", topic_name)
+        raise
+
+
+async def get_topics_by_prefix(
+    prefix: str,
+) -> list[str]:
+    try:
+        async with _get_admin_client() as admin_client:
+            topics = await admin_client.list_topics()
+
+        topics = [t for t in topics if t.startswith(prefix)]
+        logger.info(
+            "Found %d topics with prefix '%s': %s",
+            len(topics),
+            prefix,
+            topics if topics else "none",
+        )
+        return topics
+    except Exception:
+        logger.exception("Kafka error while listing topics with prefix '%s'.", prefix)
+        raise