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

bazis/contrib/async_background/__init__.py

@@ -0,0 +1,21 @@
+# 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 importlib.metadata import version
+
+
+try:
+    __version__ = version('bazis-async-background')
+except Exception:
+    __version__ = 'dev'

bazis/contrib/async_background/_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_background/apps.py

@@ -0,0 +1,23 @@
+# 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 AsyncBackgroundConfig(BaseConfig):
+    name = "bazis.contrib.async_background"
+    verbose_name = _("AsyncBackground")
+    default = True

bazis/contrib/async_background/broker.py

@@ -0,0 +1,62 @@
+# 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 random
+from contextlib import asynccontextmanager
+
+from django.conf import settings
+
+from faststream import FastStream
+from faststream.kafka import KafkaBroker
+
+
+_brokers_by_loop_id: dict[int, KafkaBroker] = {}
+_consumer_broker: KafkaBroker | None = None
+
+
+def _new_broker() -> KafkaBroker:
+    return KafkaBroker(settings.KAFKA_BOOTSTRAP_SERVERS)
+
+
+def get_broker_for_async() -> KafkaBroker:
+    loop_id = id(asyncio.get_running_loop())
+    broker = _brokers_by_loop_id.get(loop_id)
+    if broker is None:
+        broker = _new_broker()
+        _brokers_by_loop_id[loop_id] = broker
+    return broker
+
+
+def get_broker_for_consumer() -> KafkaBroker:
+    global _consumer_broker
+    if _consumer_broker is None:
+        _consumer_broker = _new_broker()
+    return _consumer_broker
+
+
+@asynccontextmanager
+async def lifespan_handler(app: FastStream | None = None):
+    stop_task = asyncio.create_task(
+        asyncio.sleep(
+            settings.KAFKA_CONSUMER_LIFETIME_SEC +
+            random.randint(0, settings.KAFKA_CONSUMER_LIFETIME_JITTER_SEC)
+        )
+    )
+    yield
+    stop_task.cancel()
+
+
+def build_app() -> FastStream:
+    return FastStream(get_broker_for_consumer(), lifespan=lifespan_handler)

bazis/contrib/async_background/conf.py

@@ -0,0 +1,88 @@
+# 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 Field, computed_field
+
+from bazis.core.utils.schemas import BazisSettings
+
+
+class Settings(BazisSettings):
+    """Kafka configuration."""
+
+    KAFKA_TASKS: list[str] = Field([], description="List of Kafka tasks to run.")
+
+    KAFKA_LOG_LEVEL: str = Field(
+        default="INFO", description="Logging level for Kafka (DEBUG, INFO, WARNING...)."
+    )
+
+    KAFKA_CONSUMER_LIFETIME_SEC: int | None = Field(
+        default=None, description="Lifetime of the Kafka consumer (in seconds). For example, 7200."
+    )  # TD: Try with rolling-update.
+
+    KAFKA_CONSUMER_LIFETIME_JITTER_SEC: int | None = Field(
+        default=None,
+        description="Maximum random lifetime shift (jitter) in seconds. For example, 300.",
+    )
+
+    KAFKA_RESPONSE_HOLD_SEC: int = Field(
+        default=86400, description="Time to hold the response for async requests (in seconds)."
+    )
+
+    KAFKA_BOOTSTRAP_SERVERS: str | None = Field(
+        default=None, description="List of Kafka brokers separated by commas (for example, 'kafka1:9092,kafka2:9092')."
+    )  # List of brokers polled to obtain the topic owner
+
+    KAFKA_TOPIC_ASYNC_REQUEST: str | None = Field(default=None, description="Kafka topic for async requests.")
+
+    KAFKA_GROUP_ID: str | None = Field(default=None, description="Kafka consumer group for this service.")
+
+    KAFKA_AUTO_OFFSET_RESET: str = Field(
+        default="earliest",
+        description="Behavior when there is no offset: earliest - from the beginning, latest - from the end.",
+    )
+
+    KAFKA_ENABLE_AUTO_COMMIT: bool = Field(
+        default=False, description="Enable automatic committing of offsets (not recommended)."
+    )
+    # If you enable automatic commits, information about messages read via poll() will be automatically
+    # committed to Kafka (moving the offset) at the interval auto.commit.interval.ms
+    # This approach helps avoid frequent commits and reduce the load on Kafka, but it is not suitable for most of our
+    # cases because:
+    # 1) When the consumer crashes, information about the fact of processing messages since the last auto.commit.interval.ms
+    # is lost, the offset for them does not have time to be moved by a commit, and after the consumer is restarted these messages will
+    # be processed again.
+    # 2) The commit that moves the offset for a message read via poll() may be sent to Kafka before the consumer
+    # actually processes this message. This creates a risk that the consumer will not be able to process the message successfully,
+    # and Kafka will have already advanced the offset for this message.
+
+    KAFKA_AUTO_COMMIT_INTERVAL_MS: int = Field(
+        default=10000, description="Interval for auto-committing the offset if enable.auto.commit is enabled."
+    )  # If KAFKA_ENABLE_AUTO_COMMIT is enabled
+
+    KAFKA_PUBLISH_TIMEOUT_SEC: int = Field(
+        default=10, description="Timeout in seconds for producing a message to Kafka."
+    )
+
+    @computed_field
+    @property
+    def KAFKA_ENABLED(self) -> bool: # noqa: N802
+        return all(
+            [
+                self.KAFKA_BOOTSTRAP_SERVERS,
+                self.KAFKA_TOPIC_ASYNC_REQUEST,
+            ]
+        )
+
+
+settings = Settings()

bazis/contrib/async_background/management/__init__.py

@@ -0,0 +1,14 @@
+# 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.
+

bazis/contrib/async_background/management/commands/__init__.py

@@ -0,0 +1,14 @@
+# 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.
+

bazis/contrib/async_background/management/commands/kafka_consumer_multiple.py

@@ -0,0 +1,113 @@
+# 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 logging
+import os
+import sys
+import time
+
+from django.core.management.base import BaseCommand, CommandParser
+
+import psutil
+
+
+logger = logging.getLogger(__name__)
+
+POLL_INTERVAL_SEC = 1
+SHUTDOWN_POLL_INTERVAL_SEC = 0.1
+SHUTDOWN_TIMEOUT_SEC = 5
+
+
+class Command(BaseCommand):
+    help = "Starts Kafka consumers in separate processes."
+
+    def add_arguments(self, parser: CommandParser) -> None:
+        parser.add_argument(
+            "--consumers-count",
+            type=int,
+            default=15,
+            help="Number of processes to start (default: 15).",
+        )
+        parser.add_argument(
+            "--restart-delay-sec",
+            type=float,
+            default=1.0,
+            help="Delay before restarting a consumer process (default: 1.0).",
+        )
+        parser.add_argument(
+            "--max-restarts",
+            type=int,
+            default=None,
+            help="Maximum restarts per consumer. Omit for unlimited.",
+        )
+
+    def handle(self, *args, **options) -> None:
+        """Starts Kafka consumers and monitors their completion."""
+        logger.info("Starting Kafka consumers...")
+        consumers_count = options["consumers_count"]
+        restart_delay_sec = options["restart_delay_sec"]
+        max_restarts = options["max_restarts"]
+        processes: dict[int, psutil.Popen] = {}
+
+        def start_consumer_process(index: int) -> psutil.Popen:
+            env = os.environ.copy()
+            process = psutil.Popen(
+                [str(sys.executable), "manage.py", "kafka_consumer_single"],
+                env=env,
+            )
+            logger.info("Started consumer process %s with index %s", process.pid, index)
+            return process
+
+        try:
+            for i in range(1, consumers_count + 1):
+                processes[i] = start_consumer_process(i)
+
+            restart_counts: dict[int, int] = {i: 0 for i in processes}
+
+            while True:
+                time.sleep(POLL_INTERVAL_SEC)
+
+                for index, process in list(processes.items()):
+                    if process.poll() is not None:
+                        exit_code = process.returncode
+                        logger.warning(
+                            "Consumer process %s (index=%s) exited with code %s",
+                            process.pid,
+                            index,
+                            exit_code,
+                        )
+                        restart_counts[index] += 1
+                        if max_restarts is not None and restart_counts[index] > max_restarts:
+                            logger.error(
+                                "Consumer %s exceeded max restarts (%s).",
+                                index,
+                                max_restarts,
+                            )
+                            continue
+                        time.sleep(restart_delay_sec)
+                        logger.info("Restarting consumer process with index %s", index)
+                        processes[index] = start_consumer_process(index)
+
+        except KeyboardInterrupt:
+            logger.warning("Received KeyboardInterrupt. Shutting down...")
+            start_time = time.time()
+            while (time.time() - start_time) < SHUTDOWN_TIMEOUT_SEC:
+                for process in processes.values():
+                    process.poll()
+                time.sleep(SHUTDOWN_POLL_INTERVAL_SEC)
+
+            for process in processes.values():
+                if process.poll() is None:
+                    process.terminate()
+            logger.info("All consumer processes terminated.")

bazis/contrib/async_background/management/commands/kafka_consumer_single.py

@@ -0,0 +1,91 @@
+# 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 inspect
+import logging
+import sys
+import time
+
+from django.conf import settings
+from django.core.management.base import BaseCommand
+
+from aiokafka.errors import KafkaConnectionError
+
+from bazis.contrib.async_background.broker import build_app
+
+
+logger = logging.getLogger(__name__)
+
+
+def _get_consumer_logger(consumer_id: int) -> logging.Logger:
+    consumer_logger = logging.getLogger(f"consumer_{consumer_id}")
+    if not consumer_logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            "%(asctime)s - %(levelname)s - %(name)s - [consumer_id=%(consumer_id)s] - %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+        handler.setFormatter(formatter)
+        consumer_logger.addHandler(handler)
+        consumer_logger.setLevel(settings.KAFKA_LOG_LEVEL)
+    return consumer_logger
+
+
+def run_consumer(consumer_id: int) -> None:
+    from bazis.core.app import app  # noqa: F401
+    from bazis.core.router import router  # noqa: F401
+
+    if not settings.KAFKA_TASKS:
+        logger.warning("No Kafka tasks configured in settings.KAFKA_TASKS.")
+        return
+
+    for task_path in settings.KAFKA_TASKS:
+        __import__(task_path)
+
+    consumer_logger = _get_consumer_logger(consumer_id)
+    consumer_logger.info("Starting consumer process", extra={"consumer_id": consumer_id})
+
+    while True:
+        try:
+            broker_app = build_app()
+            result = broker_app.run()
+            if inspect.iscoroutine(result):
+                asyncio.run(result)
+            break
+        except KafkaConnectionError as err:
+            consumer_logger.warning(
+                "Kafka not ready: %s. Retrying in 1s...",
+                err,
+                extra={"consumer_id": consumer_id},
+            )
+            time.sleep(1)
+        except Exception as err:
+            consumer_logger.exception(
+                "Error while processing: %s",
+                err,
+                extra={"consumer_id": consumer_id},
+            )
+            sys.exit(1)
+        finally:
+            consumer_logger.info("Consumer process stopped", extra={"consumer_id": consumer_id})
+
+
+class Command(BaseCommand):
+    help = "Starts a single Kafka consumer (one process)."
+
+    def handle(self, *args, **options) -> None:
+        """Entry point of the Django command."""
+        logger.info("Starting a single Kafka consumer...")
+        run_consumer(consumer_id=1)

bazis/contrib/async_background/producer.py

@@ -0,0 +1,132 @@
+# 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 threading
+from uuid import uuid4
+
+from pydantic import BaseModel
+
+from bazis.contrib.async_background.broker import get_broker_for_async
+from bazis.contrib.async_background.schemas import KafkaTask, TaskStatus
+from bazis.contrib.async_background.utils import set_and_publish_status_async
+
+
+logger = logging.getLogger(__name__)
+
+
+async def enqueue_task_async[Payload: BaseModel](
+    *,
+    topic_name: str,
+    channel_name: str,
+    payload: Payload,
+    partition_marker: str | None = None,
+) -> KafkaTask[Payload]:
+    task_id = str(uuid4())
+    message = KafkaTask[Payload](
+        task_id=task_id,
+        channel_name=channel_name,
+        payload=payload,
+    )
+
+    await set_and_publish_status_async(
+        task_id=task_id,
+        channel_name=channel_name,
+        status=TaskStatus.CREATED,
+    )
+
+    try:
+        producer = _get_kafka_producer(topic_name)
+        await producer.send_one_message(
+            message=message.model_dump(),
+            partition_marker=partition_marker,
+        )
+    except Exception as err:
+        await set_and_publish_status_async(
+            task_id=task_id,
+            channel_name=channel_name,
+            status=TaskStatus.FAILED,
+            response={"error": str(err)},
+        )
+        raise
+    else:
+        await set_and_publish_status_async(
+            task_id=task_id,
+            channel_name=channel_name,
+            status=TaskStatus.PENDING,
+        )
+    return message
+
+
+class _KafkaProducer:
+    """FastStream Kafka producer with reusable connection lifecycle."""
+
+    def __init__(self, topic_name: str) -> None:
+        self.topic_name = topic_name
+        self._start_lock = threading.Lock()
+        self._started = False
+        self._loop_id: int | None = None
+        self._broker = None
+
+    async def ensure_started(self) -> None:
+        current_loop_id = id(asyncio.get_running_loop())
+        if self._started and self._loop_id == current_loop_id:
+            return
+        with self._start_lock:
+            current_loop_id = id(asyncio.get_running_loop())
+            if self._started and self._loop_id == current_loop_id:
+                return
+            if self._started and self._loop_id != current_loop_id:
+                self._started = False
+                self._loop_id = None
+                self._broker = None
+            if self._broker is None:
+                self._broker = get_broker_for_async()
+            await self._broker.start()
+            self._started = True
+            self._loop_id = current_loop_id
+
+    async def send_one_message(
+        self,
+        message: dict,
+        partition_marker: str | None = None,
+    ) -> None:
+        """Sends a single message to Kafka."""
+        await self.ensure_started()
+        try:
+            await self._broker.publish(
+                message,
+                self.topic_name,
+                key=partition_marker.encode("utf-8") if partition_marker else None,
+            )
+        except Exception:
+            logger.exception("Kafka publish failed.")
+            raise
+
+
+_producer_cache: dict[tuple[str | None, int], _KafkaProducer] = {}
+
+
+def _get_kafka_producer(topic_name: str) -> _KafkaProducer:
+    try:
+        loop_id = id(asyncio.get_running_loop())
+    except RuntimeError:
+        loop_id = None
+    cache_key = (topic_name, loop_id if loop_id is not None else threading.get_ident())
+    producer = _producer_cache.get(cache_key)
+    if producer is None:
+        producer = _KafkaProducer(topic_name)
+        _producer_cache[cache_key] = producer
+    return producer

bazis/contrib/async_background/router.py

@@ -0,0 +1,15 @@
+# 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 .routes import router  # noqa: F401

bazis/contrib/async_background/routes.py

@@ -0,0 +1,57 @@
+# 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
+
+from django.utils.translation import gettext_lazy as _
+
+from fastapi import HTTPException, Request
+
+from bazis.contrib.async_background.utils import (
+    ChannelNameError,
+    get_redis_async,
+    resolve_channel_name_async,
+)
+from bazis.core.errors import JsonApi401Exception, JsonApi403Exception
+from bazis.core.routing import BazisRouter
+
+
+router = BazisRouter(tags=[_("Async requests")])
+
+
+@router.get("/async_background_response/{task_id}/", response_model=dict)
+async def get_async_background_response(request: Request, task_id: str, full_response: bool = False) -> dict:
+    """Returns the result of a background task by its identifier."""
+    try:
+        channel_name = await resolve_channel_name_async(request)
+    except ChannelNameError as err:
+        raise JsonApi401Exception from err
+
+    redis_data_raw = await get_redis_async().get(task_id)
+    if not redis_data_raw:
+        raise HTTPException(status_code=404, detail=_("Unknown task ID"))
+    try:
+        redis_data = json.loads(redis_data_raw.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as err:
+        raise HTTPException(status_code=500, detail=_("Invalid task data format in Redis")) from err
+
+    if channel_name != redis_data["channel_name"]:
+        raise JsonApi403Exception
+
+    if full_response:
+        return redis_data
+
+    response = redis_data.get("response")
+    return response if response is not None else {"status": "not ready"}
+

bazis/contrib/async_background/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 enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class TaskStatus(str, Enum):
+    """Background task statuses."""
+
+    CREATED = "created"  # The task is registered but has not yet been sent to Kafka
+    PENDING = "pending"  # The message has been delivered to Kafka and is awaiting processing
+    PROCESSING = "processing"  # The consumer has started processing
+    COMPLETED = "completed"  # The task has completed successfully
+    FAILED = "failed"  # An error occurred during execution
+
+
+class KafkaTask[Payload: BaseModel](BaseModel):
+    """Base schema for tasks processed by Kafka."""
+
+    task_id: str = Field(..., description="Background task identifier")
+    channel_name: str = Field(..., description="Channel name for status updates")
+    payload: Payload
+

bazis/contrib/async_background/utils.py

@@ -0,0 +1,137 @@
+# 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 json
+import logging
+
+from django.conf import settings
+
+from fastapi import Request
+
+from redis import Redis
+from redis.asyncio import Redis as AsyncRedis
+
+from bazis.contrib.ws.utils import UserError, get_user_from_token_async
+
+from .schemas import TaskStatus
+
+
+logger = logging.getLogger(__name__)
+
+redis = Redis.from_url(settings.CACHES['default']['LOCATION'])
+_redis_async_by_loop: dict[int, AsyncRedis] = {}
+
+
+def get_redis_async() -> AsyncRedis:
+    loop_id = id(asyncio.get_running_loop())
+    client = _redis_async_by_loop.get(loop_id)
+    if client is None:
+        client = AsyncRedis.from_url(settings.CACHES['default']['LOCATION'])
+        _redis_async_by_loop[loop_id] = client
+    return client
+
+
+class StatusStorageError(Exception):
+    """Error when setting or publishing status in Redis."""
+
+
+class ChannelNameError(Exception):
+    """Error when resolving channel name."""
+
+
+def set_and_publish_status(
+    task_id: str, channel_name: str, status: TaskStatus, response: dict | None = None
+) -> None:
+    """Saves the task status in Redis and publishes a minimal status to the WS channel."""
+    try:
+        # Save the full status in Redis (for subsequent retrieval of the result by task_id)
+        redis.set(
+            task_id,
+            json.dumps(
+                {
+                    "status": status.value,
+                    "channel_name": channel_name,
+                    "response": response,
+                },
+                ensure_ascii=False,
+            ),
+            ex=settings.KAFKA_RESPONSE_HOLD_SEC,
+        )
+    except Exception as err:
+        logger.exception("Failed to set task %s in Redis", task_id)
+        raise StatusStorageError(f"Redis set failed: {err}") from err
+
+    try:
+        # Prepare a lightweight payload for publication via WebSocket
+        redis.publish(
+            channel_name,
+            json.dumps(
+                {
+                    "status": status.value,
+                    "task_id": task_id,
+                    "action": "async_bg",
+                },
+                ensure_ascii=False,
+            ),
+        )
+
+        logger.info(
+            "Published WS message for task %s with status %s to channel %s",
+            task_id,
+            status.value,
+            channel_name,
+        )
+    except Exception as err:
+        logger.exception("Failed to publish to channel for task %s", task_id)
+        raise StatusStorageError(f"Redis publish failed: {err}") from err
+
+
+async def set_and_publish_status_async(
+    task_id: str, channel_name: str, status: TaskStatus, response: dict | None = None
+) -> None:
+    from asgiref.sync import sync_to_async
+
+    await sync_to_async(set_and_publish_status)(
+        task_id,
+        channel_name,
+        status,
+        response,
+    )
+
+
+def _get_token_from_request(request: Request) -> str | None:
+    authorization = request.headers.get("authorization")
+    if not authorization or not authorization.lower().startswith("bearer "):
+        return None
+    return authorization.split(" ")[1].strip()
+
+
+async def resolve_channel_name_async(request: Request) -> str:
+    token = _get_token_from_request(request)
+
+    if token and token.count('.') == 2:
+        try:
+            user = await get_user_from_token_async(token)
+        except UserError as exc:
+            raise ChannelNameError(
+                f"Failed to get user from token: {exc.message}"
+            ) from exc
+        return user.user_channel
+    elif token:
+        return token
+    else:
+        raise ChannelNameError(
+            "No valid token found in request for channel name resolution."
+        )

bazis_async_background-2.2.0.dist-info/METADATA

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: bazis-async-background
+Version: 2.2.0
+Summary: Async Background core framework for Bazis.
+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-background
+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
+Requires-Dist: bazis-ws
+Requires-Dist: faststream[kafka]
+Provides-Extra: test
+Requires-Dist: bazis-test-utils; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+
+# Bazis Async Background
+
+[![PyPI version](https://img.shields.io/pypi/v/bazis-async-background.svg)](https://pypi.org/project/bazis-async-background/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/bazis-async-background.svg)](https://pypi.org/project/bazis-async-background/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Core background task framework for Bazis. It provides Kafka broker helpers, task schemas, status storage in Redis, and a base API to retrieve task results.
+
+## Quick Start
+
+```bash
+# Install the package
+uv add bazis-async-background
+
+# Configure environment variables / settings
+INSTALLED_APPS='["bazis.contrib.async_background", ...]'
+BAZIS_CONFIG_APPS='["bazis.contrib.async_background", ...]'
+
+# Kafka settings
+KAFKA_BOOTSTRAP_SERVERS=localhost:9093
+KAFKA_TOPIC_ASYNC_REQUEST=my_app_background_tasks
+KAFKA_GROUP_ID=my_app_background
+KAFKA_TASKS='["my_app.background.tasks"]'
+
+# 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)
+  - [Running Consumers](#running-consumers)
+- [Examples](#examples)
+- [License](#license)
+- [Links](#links)
+
+## Description
+
+**Bazis Async Background** is a core package for running background tasks in the Bazis framework. It includes:
+
+- **Kafka Producer** — sending tasks to Kafka queue
+- **Kafka Consumer** — processing tasks from the queue
+- **Redis storage** — storing task execution results
+- **API endpoint** — retrieving results by task_id
+
+## Requirements
+
+- **Python**: 3.12+
+- **bazis**: latest version
+- **PostgreSQL**: 12+
+- **Redis**: For storing results and caching
+- **Kafka**: For task queue
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add bazis-async-background
+```
+
+### Using pip
+
+```bash
+pip install bazis-async-background
+```
+
+## Running Tests
+
+Run from the project root:
+
+```bash
+docker compose -f sample/docker-compose.test.yml up --build --exit-code-from bazis-async-background-pytest --attach bazis-async-background-pytest --attach bazis-async-background-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    │
+└──────┬──────┘
+       │ Background task request
+       ▼
+┌─────────────────────┐
+│   API Endpoint      │
+│ (Async Background)  │
+└──────┬──────────────┘
+       │ 1. Return task_id (202)
+       │ 2. Send to Kafka
+       ▼
+┌─────────────────────┐
+│   Kafka Topic       │
+│ (async_background)  │
+└──────┬──────────────┘
+       │
+       │ Consumer polls
+       ▼
+┌─────────────────────┐
+│  Kafka Consumer     │
+│  (Background Worker)│
+└──────┬──────────────┘
+       │ 3. Process task
+       │ 4. Save result to Redis
+       ▼
+┌─────────────────────┐
+│      Redis          │
+│   (Results Store)   │
+└──────┬──────────────┘
+       │
+       │ 5. GET /async_background_response/{task_id}/
+       ▼
+┌─────────────────────┐
+│   API Endpoint      │
+│   (Get Result)      │
+└─────────────────────┘
+```
+
+## Configuration
+
+### Environment Variables / Settings
+
+Add to your `.env` or `settings.py`:
+
+```bash
+# Required settings
+INSTALLED_APPS='["bazis.contrib.async_background", ...]'
+BAZIS_CONFIG_APPS='["bazis.contrib.async_background", ...]'
+KAFKA_TASKS='["my_app.background.tasks"]'
+
+# Kafka settings
+KAFKA_BOOTSTRAP_SERVERS=localhost:9093
+KAFKA_TOPIC_ASYNC_REQUEST=my_app_background_tasks
+KAFKA_GROUP_ID=my_app_background
+
+# 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
+```
+
+**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
+
+### 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)
+
+## Examples
+
+### Minimal Task Registration
+
+```python
+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 pydantic import BaseModel
+
+
+class DemoPayload(BaseModel):
+    message: str
+
+
+@get_broker_for_consumer().subscriber("my_app_background_tasks")
+async def consumer_demo(task: KafkaTask[DemoPayload]):
+    await set_and_publish_status_async(
+        task_id=task.task_id,
+        channel_name=task.channel_name,
+        status=TaskStatus.COMPLETED,
+        response={"echo": task.payload.model_dump()},
+    )
+```
+
+## License
+
+Apache License 2.0
+
+See [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [Bazis Documentation](https://github.com/ecofuture-tech/bazis) — main repository
+- [Bazis Async Background Repository](https://github.com/ecofuture-tech/bazis-async-background) — package repository
+- [Issue Tracker](https://github.com/ecofuture-tech/bazis-async-background/issues) — report bugs or request features
+- [Apache Kafka](https://kafka.apache.org/) — Kafka documentation

bazis_async_background-2.2.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+bazis/contrib/async_background/__init__.py,sha256=fQ4bunv4zeO5I0gmiNFAAiswPLm2uy5XDwaIz6M6OJM,755
+bazis/contrib/async_background/_version.py,sha256=6OGz4a0gjMGlckPyPCNiJDWyFDO-tWO8O_ZNx4ajT2Y,704
+bazis/contrib/async_background/apps.py,sha256=obdEeKVgMdqsmKAwHVPpDzonhp9qCNM-P6GqcwPWeUs,862
+bazis/contrib/async_background/broker.py,sha256=iHxW20sUIQJcMxLsikPwXZdvpqK-hQVJSMaPvQFtxFk,1843
+bazis/contrib/async_background/conf.py,sha256=0jv_EcjNU7LbP3k0WynnOlEGc6qXOExZ8gxFVpao68Q,3824
+bazis/contrib/async_background/producer.py,sha256=k7SO4KRmXVCvTluycnLUWPtUBelljnDRkZIUfTfHzik,4205
+bazis/contrib/async_background/router.py,sha256=aQRPo_2IaqXILLAI9tQuefPUhYuS2gTdVGTcbO_MK8k,656
+bazis/contrib/async_background/routes.py,sha256=K46h6x9SCtIuo1CTVsM0j2KIAWPP2PYajbT8zpOD4cU,2077
+bazis/contrib/async_background/schemas.py,sha256=DMporComNAJK1TWREmYayntVjeX3v06TGzp99TDzuE8,1398
+bazis/contrib/async_background/utils.py,sha256=1DlPfE9-odo5ssSTsc9g6E6zl3iDQMrQkfVQvDB8oWA,4249
+bazis/contrib/async_background/management/__init__.py,sha256=7MU6gF_TkvnR3NFi-Nfci4RIacoZ6bqMjwlR6ONK8Ms,615
+bazis/contrib/async_background/management/commands/__init__.py,sha256=7MU6gF_TkvnR3NFi-Nfci4RIacoZ6bqMjwlR6ONK8Ms,615
+bazis/contrib/async_background/management/commands/kafka_consumer_multiple.py,sha256=j4fKuKJAb0NoZUP17RjwktHpiLtwwrvqGSxPLTowINo,4208
+bazis/contrib/async_background/management/commands/kafka_consumer_single.py,sha256=Dupi8l7YwKRt8SvhWXCcQX8MKd0k4og_D9n59_sMvIw,3066
+bazis_async_background-2.2.0.dist-info/METADATA,sha256=7YOxquFpncjmWHRInvS2ZRaASAA3JpI-aAj0ffD4SrI,8557
+bazis_async_background-2.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+bazis_async_background-2.2.0.dist-info/top_level.txt,sha256=WgdrPZTZBMG8i_EqxA3vU5qI4ETQ_RsqKqSqsfIApHY,6
+bazis_async_background-2.2.0.dist-info/RECORD,,

bazis_async_background-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_background-2.2.0.dist-info/top_level.txt

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