simple-module-background-tasks 0.0.34__tar.gz → 0.0.36__tar.gz

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_background_tasks
-Version: 0.0.34
+Version: 0.0.36
 Summary: Celery + Redis task queue with admin UI for monitoring and retrying failed/stuck tasks
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python
@@ -23,10 +23,10 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: celery[redis]>=5.4
 Requires-Dist: redis>=5
-Requires-Dist: simple-module-core==0.0.34
-Requires-Dist: simple-module-db==0.0.34
-Requires-Dist: simple-module-hosting==0.0.34
-Requires-Dist: simple-module-settings==0.0.34
+Requires-Dist: simple-module-core==0.0.36
+Requires-Dist: simple-module-db==0.0.36
+Requires-Dist: simple-module-hosting==0.0.36
+Requires-Dist: simple-module-settings==0.0.36
 Description-Content-Type: text/markdown
 
 # simple_module_background_tasks

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/__init__.py

@@ -5,9 +5,11 @@ from background_tasks.log_context import (
     get_log_context,
     install_log_filter,
 )
+from background_tasks.worker_settings import settings_for
 
 __all__ = [
     "bind_task_context",
     "get_log_context",
     "install_log_filter",
+    "settings_for",
 ]

simple_module_background_tasks-0.0.36/background_tasks/_signal_bus.py

@@ -0,0 +1,61 @@
+"""Bridge from Celery's sync signal thread to the app's async event bus.
+
+Split out of :mod:`.signals` to keep it under the 300-line cap; ``signals``
+re-exports :func:`bind_event_bus` / :func:`unbind_event_bus`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import Any
+
+from simple_module_core.events import EventBus
+
+logger = logging.getLogger("background_tasks.signals")
+
+
+_bus: EventBus | None = None
+_loop: asyncio.AbstractEventLoop | None = None
+
+
+def bind_event_bus(bus: EventBus, loop: asyncio.AbstractEventLoop) -> None:
+    """Bind an event bus + its running loop so signals can publish events.
+
+    Signals fire on the Celery sync thread; `run_coroutine_threadsafe`
+    bridges back to ``loop`` so handlers run on the API event loop
+    regardless of which thread triggered the signal.
+    """
+    global _bus, _loop
+    _bus = bus
+    _loop = loop
+
+
+def unbind_event_bus() -> None:
+    """Drop the bound bus — called from ``on_shutdown`` so tests stay isolated."""
+    global _bus, _loop
+    _bus = None
+    _loop = None
+
+
+def publish_from_signal(event: Any) -> None:
+    """Dispatch ``event`` onto the bound bus without blocking the signal thread."""
+    if _bus is None or _loop is None:
+        return
+    try:
+        future = asyncio.run_coroutine_threadsafe(_bus.publish(event), _loop)
+    except RuntimeError:
+        # Loop has stopped (shutdown race). The DB row is already written.
+        logger.debug("Event bus loop is not running; skipping %s", type(event).__name__)
+        return
+    # Surface subscriber exceptions — run_coroutine_threadsafe otherwise only
+    # logs them when the Future is GC'd, which happens far from the failure.
+    future.add_done_callback(_log_publish_failure)
+
+
+def _log_publish_failure(future: asyncio.Future[Any]) -> None:
+    if future.cancelled():
+        return
+    exc = future.exception()
+    if exc is not None:
+        logger.error("Event publish raised: %s", exc, exc_info=exc)

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/constants.py

@@ -87,6 +87,14 @@ DEFAULT_STUCK_SWEEP_INTERVAL_SECONDS = 60
 DEFAULT_PURGE_INTERVAL_SECONDS = 60 * 60 * 24
 DEFAULT_RETENTION_DAYS = 14
 DEFAULT_MAX_RETRIES = 3
+# Redis pub/sub channel carrying the framework's cache invalidations. Namespaced
+# so that two apps on one Redis *server* do not each act on the other's messages.
+# The server, not the database: pub/sub ignores the logical DB index, so DBs 4 and
+# 5 of one instance share this channel. Mostly that costs pointless reads, but it
+# is not unconditionally harmless — an emptied cache is also what exposes
+# ``UsersAuthProvider._version_still_current``'s fail-open branch, so rename it
+# per app rather than relying on the DB number.
+DEFAULT_INVALIDATION_CHANNEL = "simple_module.invalidation"
 
 # ── Internal task names ─────────────────────────────────────────
 INTERNAL_TASK_SWEEP_STUCK = "background_tasks.sweep_stuck_tasks"
@@ -94,3 +102,7 @@ INTERNAL_TASK_PURGE_OLD = "background_tasks.purge_old_executions"
 # Harmless round-trip task; only wired into CI smoke tests and local dev —
 # not scheduled, not invoked by other modules.
 DEMO_ECHO_TASK = "background_tasks.demo_echo"
+
+TENANT_ID_MAX_LENGTH = 50
+# Filter value meaning "executions with no tenant" (beat / platform publishes).
+PLATFORM_TENANT_FILTER = "__platform__"

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/contracts/schemas.py

@@ -28,6 +28,7 @@ class TaskExecutionListItem(SQLModel):
     task_name: str
     status: TaskStatus
     queue: str
+    tenant_id: str | None = None
     args: list[Any] = []
     kwargs: dict[str, Any] = {}
     retries: int
@@ -49,6 +50,7 @@ class TaskExecutionDetail(SQLModel):
     task_name: str
     status: TaskStatus
     queue: str
+    tenant_id: str | None = None
     args: list[Any] = []
     kwargs: dict[str, Any] = {}
     result: dict[str, Any] | None = None

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/endpoints/api_admin.py

@@ -37,6 +37,7 @@ async def list_executions(
     q: str | None = Query(default=None),
     task_name: str | None = Query(default=None, deprecated=True),
     queue: str | None = Query(default=None),
+    tenant_id: str | None = Query(default=None),
     page: int = Query(default=1, ge=1),
     per_page: int = Query(default=20, ge=1, le=200),
     service: BackgroundTaskService = Depends(get_background_task_service),
@@ -50,7 +51,12 @@ async def list_executions(
     existing API callers keep working, and ``q`` wins when both are given.
     """
     return await service.list(
-        status=status, task_name=q or task_name, queue=queue, page=page, per_page=per_page
+        status=status,
+        task_name=q or task_name,
+        queue=queue,
+        tenant_id=tenant_id,
+        page=page,
+        per_page=per_page,
     )
 
 
@@ -74,15 +80,18 @@ async def retry_failed_executions(
     status: TaskStatus | None = Query(default=None),
     task_name: str | None = Query(default=None, alias="q"),
     queue: str | None = Query(default=None),
+    tenant_id: str | None = Query(default=None),
     service: BackgroundTaskService = Depends(get_background_task_service),
 ) -> RetryFailedResult:
     """Re-enqueue every failed or stuck execution the current filter can see.
 
-    Takes the same three filters as the listing — status, search, queue — so
+    Takes the same filters as the listing — status, search, queue, tenant — so
     the sweep covers exactly the rows the operator is looking at and nothing
     else. Capped per call; the response says how many eligible rows are left.
     """
-    return await service.retry_failed(status=status, task_name=task_name, queue=queue)
+    return await service.retry_failed(
+        status=status, task_name=task_name, queue=queue, tenant_id=tenant_id
+    )
 
 
 @router.post(

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/endpoints/views.py

@@ -6,12 +6,13 @@ import asyncio
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
-from inertia import InertiaResponse
 from simple_module_hosting.inertia_deps import InertiaDep
 from simple_module_hosting.permissions import RequiresPermission
+from simple_module_inertia import InertiaResponse
 
 from background_tasks.constants import (
     PERM_VIEW,
+    PLATFORM_TENANT_FILTER,
     TaskStatus,
 )
 from background_tasks.deps import get_background_task_service
@@ -53,6 +54,7 @@ async def index(
     status: TaskStatus | None = Query(default=None),
     task_name: str = Query(default="", alias="q"),
     queue: str = Query(default=""),
+    tenant_id: str = Query(default="", alias="tenant"),
     page: int = Query(default=1),
     service: BackgroundTaskService = Depends(get_background_task_service),
 ) -> InertiaResponse:
@@ -60,22 +62,28 @@ async def index(
         status=status,
         task_name=task_name or None,
         queue=queue or None,
+        tenant_id=tenant_id or None,
         page=page,
         per_page=PER_PAGE,
     )
     # A filtered-empty list says nothing about the fleet, so don't pay to poll
     # it: the screen already knows to blame the filter.
-    unfiltered_and_empty = response.total == 0 and not task_name and not queue and status is None
+    unfiltered_and_empty = (
+        response.total == 0 and not task_name and not queue and not tenant_id and status is None
+    )
 
     async def strip_data() -> tuple[dict[str, int], list[str]]:
         """Everything above the table. Serial: one session, one connection."""
-        counts = await service.status_counts(task_name=task_name or None, queue=queue or None)
+        counts = await service.status_counts(
+            task_name=task_name or None, queue=queue or None, tenant_id=tenant_id or None
+        )
         # The strip's third tile is a windowed throughput reading rather than a
         # status total, so it needs its own count — see `success_count_since`.
         counts["success_24h"] = await service.success_count_since(
             hours=SUCCESS_WINDOW_HOURS,
             task_name=task_name or None,
             queue=queue or None,
+            tenant_id=tenant_id or None,
         )
         # Deliberately unfiltered: the dropdown is how an operator leaves the
         # queue they are in, so it keeps offering the ones they are not in.
@@ -97,6 +105,8 @@ async def index(
                 "success_24h": counts["success_24h"],
             },
             "queues": queues,
+            "tenant_ids": await service.tenant_ids(),
+            "platform_tenant_value": PLATFORM_TENANT_FILTER,
             "worker_presence": presence,
             "pagination": {
                 "page": response.page,
@@ -107,6 +117,7 @@ async def index(
                 "status": status.value if status else "",
                 "task_name": task_name,
                 "queue": queue,
+                "tenant": tenant_id,
             },
         },
     )

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/filters.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 from simple_module_db import LIKE_ESCAPE_CHAR, like_contains_pattern
 from sqlalchemy import ColumnElement, select
 
-from background_tasks.constants import RETRYABLE_STATUSES, TaskStatus
+from background_tasks.constants import PLATFORM_TENANT_FILTER, RETRYABLE_STATUSES, TaskStatus
 from background_tasks.models import TaskExecution
 
 Conditions = list[ColumnElement[bool]]
@@ -22,9 +22,19 @@ def execution_filters(
     status: TaskStatus | None = None,
     task_name: str | None = None,
     queue: str | None = None,
+    tenant_id: str | None = None,
 ) -> Conditions:
-    """The three axes the executions screen filters on."""
+    """The axes the executions screen filters on.
+
+    *tenant_id* is a tenant id, or :data:`PLATFORM_TENANT_FILTER` for
+    executions published with no tenant. The screen is platform-wide; tenant is
+    a filter, not a scope.
+    """
     conditions: Conditions = []
+    if tenant_id == PLATFORM_TENANT_FILTER:
+        conditions.append(TaskExecution.tenant_id.is_(None))
+    elif tenant_id:
+        conditions.append(TaskExecution.tenant_id == tenant_id)
     if status is not None:
         conditions.append(TaskExecution.status == status)
     if task_name:
@@ -41,6 +51,7 @@ def bulk_retry_conditions(
     status: TaskStatus | None = None,
     task_name: str | None = None,
     queue: str | None = None,
+    tenant_id: str | None = None,
 ) -> Conditions | None:
     """What the bulk sweep may touch, or ``None`` when it may touch nothing.
 
@@ -64,6 +75,6 @@ def bulk_retry_conditions(
     already_retried = select(child.c.id).where(child.c.retried_from_id == TaskExecution.id).exists()
     return [
         TaskExecution.status.in_(sorted(wanted)),
-        *execution_filters(task_name=task_name, queue=queue),
+        *execution_filters(task_name=task_name, queue=queue, tenant_id=tenant_id),
         ~already_retried,
     ]

simple_module_background_tasks-0.0.36/background_tasks/invalidation.py

@@ -0,0 +1,211 @@
+"""Redis pub/sub transport for the framework's :class:`InvalidationBus`.
+
+This module owns the app's Redis connection already — one URL, one set of
+settings, one health check. Cross-process cache invalidation needs exactly that
+connection and nothing else, so it is installed from here rather than opened a
+second time inside whichever module happens to keep a cache (GH #318). A module
+→ framework import is fine; the reverse is what ``SM009`` forbids, which is why
+the bus itself knows nothing about Redis.
+
+Every framework channel shares one Redis channel. The volume is a handful of
+messages per revocation — ``users`` is the only publisher today — and
+``Invalidation.channel`` routes
+inside the receiving process, so one subscription is less machinery for the same
+result — and it means a module that adds a channel after boot needs no
+resubscribe.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from simple_module_core.invalidation import InvalidationBus
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["RedisInvalidationTransport"]
+
+INITIAL_BACKOFF_SECONDS = 1.0
+MAX_BACKOFF_SECONDS = 30.0
+
+SUBSCRIBE_TIMEOUT_SECONDS = 5.0
+"""Ceiling on the one-shot SUBSCRIBE at the top of each listener attempt.
+
+A separate bound from :data:`PUBLISH_TIMEOUT_SECONDS` because it is not in a
+request's way — only a wedged listener's. Needed because ``socket_connect_timeout``
+bounds the *connect* and nothing else: against a broker that completes the TCP
+handshake and then never answers, ``subscribe`` waits on a read that has no
+deadline, so the listener hangs before it has ever raised, ``_log_failure`` never
+runs, and the reconnect loop below never gets a turn. Cross-process invalidation
+is then silently and permanently off on this worker, while the boot log says it is
+on — the exact "does nothing and nobody learns" failure this whole file is
+supposed to avoid. Found by QA, not by the original tests.
+"""
+
+READ_TIMEOUT_SECONDS = 10.0
+"""``socket_timeout`` for the client: a bound on any read that has started.
+
+Cannot simply be small: the same option applies to the subscription, and a quiet
+channel must not be torn down for being quiet. That is why the listener polls
+:meth:`redis.asyncio.client.PubSub.get_message` with its own short timeout instead
+of blocking in ``listen()`` — polling returns ``None`` on an idle channel without
+ever starting a read, so this deadline only bites when bytes stop arriving
+mid-message.
+"""
+
+HEALTH_CHECK_INTERVAL_SECONDS = 15.0
+"""How often redis-py PINGs an otherwise idle subscription.
+
+The half-open socket — ESTABLISHED at both ends, carrying nothing, as a NAT or
+load balancer idle-drop leaves it — is invisible to every timeout above, because
+no read is ever attempted. redis-py's health check is what turns it into an error:
+the PING's reply read is bounded by ``socket_timeout``, so a mute peer raises into
+the reconnect loop within roughly this interval.
+"""
+
+LISTEN_POLL_SECONDS = 1.0
+"""How long each ``get_message`` waits before returning ``None`` and looping.
+
+Also the granularity at which the health check and cancellation get a turn.
+"""
+
+PUBLISH_TIMEOUT_SECONDS = 1.0
+"""Ceiling on how long a publish may hold up the request that triggered it.
+
+``publish`` is awaited inside the response cycle — a password change's
+``db.on_commit`` callback runs before the response is sent — and redis-py
+defaults to *no* socket timeout, so a Redis that accepts connections but stops
+answering would hang that request indefinitely rather than degrade the fan-out.
+One second is far more than a local round trip needs and far less than a user
+waits. Exceeding it raises, which the bus logs and swallows: the local eviction
+has already happened, so the cost of the timeout is the same staleness window
+that existed before this transport.
+"""
+
+
+class RedisInvalidationTransport:
+    """Publishes to, and listens on, one Redis pub/sub channel.
+
+    Satisfies ``simple_module_core.invalidation.InvalidationTransport``
+    structurally — no import of the Protocol at runtime, so this file costs
+    nothing when the bus is unused.
+    """
+
+    def __init__(self, bus: InvalidationBus, url: str, channel: str) -> None:
+        self._bus = bus
+        self._url = url
+        self._channel = channel
+        self._client = None
+        self._listener: asyncio.Task | None = None
+        self._warned = False
+
+    async def start(self) -> None:
+        """Open the client and start the listener task.
+
+        Does **not** wait for a successful connection, and does not raise if
+        Redis is down. Invalidation is an accelerator over a TTL that already
+        bounds staleness, so an unreachable broker must degrade the app to
+        per-process caching — its behaviour before this existed — rather than
+        fail the boot of a web worker that can otherwise serve every request.
+        ``/health`` already reports Redis; this logs a warning naming the
+        consequence so the two agree.
+        """
+        import redis.asyncio as aioredis
+
+        # Four deadlines, each covering a failure the others do not. Connect
+        # covers a host that swallows SYN packets; socket_timeout covers a read
+        # that starts and stalls; keepalive and the health check cover a socket
+        # that is open at both ends and carrying nothing. Without the last two a
+        # half-open connection leaves this worker permanently and silently
+        # without cross-process invalidation.
+        self._client = aioredis.from_url(
+            self._url,
+            socket_connect_timeout=PUBLISH_TIMEOUT_SECONDS,
+            socket_timeout=READ_TIMEOUT_SECONDS,
+            socket_keepalive=True,
+            health_check_interval=HEALTH_CHECK_INTERVAL_SECONDS,
+        )
+        self._listener = asyncio.create_task(self._listen(), name="sm-invalidation-listener")
+
+    async def publish(self, message: str) -> None:
+        """Broadcast one encoded invalidation. Raises — the bus logs it.
+
+        Bounded by :data:`PUBLISH_TIMEOUT_SECONDS`, because this runs inside the
+        response cycle of the request that made the write.
+        """
+        if self._client is None:
+            raise RuntimeError("RedisInvalidationTransport.start() was not called")
+        async with asyncio.timeout(PUBLISH_TIMEOUT_SECONDS):
+            await self._client.publish(self._channel, message)
+
+    async def stop(self) -> None:
+        """Cancel the listener and close the client."""
+        if self._listener is not None:
+            self._listener.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._listener
+            self._listener = None
+        if self._client is not None:
+            with contextlib.suppress(Exception):
+                await self._client.aclose()
+            self._client = None
+
+    async def _listen(self) -> None:
+        """Subscribe and hand every message to the bus, reconnecting forever.
+
+        Reconnects rather than giving up after the first failure: a Redis that
+        is briefly unreachable during a deploy would otherwise leave this worker
+        with cross-process invalidation permanently off, which is the original
+        bug wearing a warning message. Backoff is capped so a long outage does
+        not turn into a reconnect storm when it ends.
+
+        Only the *first* failure of a run logs at warning. A worker that
+        outlives an hour of downtime should not have written an hour of
+        identical lines, but the state still has to be visible once.
+        """
+        backoff = INITIAL_BACKOFF_SECONDS
+        while True:
+            pubsub = None
+            try:
+                pubsub = self._client.pubsub()
+                async with asyncio.timeout(SUBSCRIBE_TIMEOUT_SECONDS):
+                    await pubsub.subscribe(self._channel)
+                if self._warned:
+                    logger.info("Invalidation listener reconnected to %r", self._channel)
+                self._warned = False
+                backoff = INITIAL_BACKOFF_SECONDS
+                while True:
+                    # Polling rather than ``listen()``: an idle channel returns
+                    # None instead of blocking in an unbounded read, which is what
+                    # lets redis-py run its health check and lets cancellation
+                    # land promptly at shutdown.
+                    raw = await pubsub.get_message(timeout=LISTEN_POLL_SECONDS)
+                    if raw is None or raw.get("type") != "message":
+                        continue
+                    await self._bus.deliver(raw["data"])
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                self._log_failure(exc)
+                await asyncio.sleep(backoff)
+                backoff = min(backoff * 2, MAX_BACKOFF_SECONDS)
+            finally:
+                if pubsub is not None:
+                    with contextlib.suppress(Exception):
+                        await pubsub.aclose()
+
+    def _log_failure(self, exc: Exception) -> None:
+        """Warn once per outage, then stay quiet about the same outage."""
+        if self._warned:
+            logger.debug("Invalidation listener still down: %s", exc)
+            return
+        self._warned = True
+        logger.warning(
+            "Invalidation listener lost Redis (%s); other workers keep cached "
+            "values until they expire. Retrying.",
+            exc,
+        )

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/locales/en.json

@@ -26,7 +26,11 @@
     "stuck": "Stuck",
     "queue_label": "Queue:",
     "queue_all": "all",
-    "queue_aria": "Filter by queue"
+    "queue_aria": "Filter by queue",
+    "tenant_label": "Tenant:",
+    "tenant_all": "all",
+    "tenant_platform": "Platform",
+    "tenant_aria": "Filter by tenant"
   },
   "status": {
     "queued": "queued",
@@ -44,7 +48,8 @@
     "queued_at": "Queued",
     "duration": "Duration",
     "actions": "Actions",
-    "retry": "Retry"
+    "retry": "Retry",
+    "tenant": "Tenant"
   },
   "detail": {
     "head_title": "Task detail",
@@ -69,7 +74,8 @@
     "traceback": "Traceback",
     "copy": "Copy",
     "copied": "Copied",
-    "no_traceback": "No traceback recorded."
+    "no_traceback": "No traceback recorded.",
+    "tenant": "Tenant"
   },
   "retry_dialog": {
     "title": "Retry {name}?",

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/log_context.py

@@ -10,7 +10,7 @@ Celery signals plus arbitrary domain identifiers via
 from __future__ import annotations
 
 import logging
-from collections.abc import Iterator, Mapping
+from collections.abc import Generator, Mapping
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from types import MappingProxyType
@@ -46,7 +46,7 @@ def get_log_context() -> dict[str, Any]:
 
 
 @contextmanager
-def bind_task_context(**identifiers: Any) -> Iterator[None]:
+def bind_task_context(**identifiers: Any) -> Generator[None]:
     """Layer ``identifiers`` onto the current task's log context.
 
     Nests cleanly. Raises ``ValueError`` if any key collides with a

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/models.py

@@ -15,6 +15,7 @@ from background_tasks.constants import (
     DEFAULT_QUEUE,
     MODULE_NAME,
     TABLE_TASK_EXECUTION,
+    TENANT_ID_MAX_LENGTH,
     TaskStatus,
 )
 
@@ -48,6 +49,12 @@ class TaskExecution(Base, AuditMixin, table=True):  # ty: ignore[unsupported-bas
     )
     queue: str = Field(default=DEFAULT_QUEUE, max_length=64)
 
+    # The tenant the task was published for; NULL for beat and other platform
+    # publishes. Deliberately not MultiTenantMixin: those rows have no tenant
+    # and strict mode would raise on their insert. The admin screens are
+    # platform-wide and filter on this column.
+    tenant_id: str | None = Field(default=None, index=True, max_length=TENANT_ID_MAX_LENGTH)
+
     args: list[Any] = Field(default_factory=list, sa_column=Column(JSON))
     kwargs: dict[str, Any] = Field(default_factory=dict, sa_column=Column(JSON))
     result: dict[str, Any] | None = Field(default=None, sa_column=Column(JSON))
@@ -79,4 +86,10 @@ class TaskExecution(Base, AuditMixin, table=True):  # ty: ignore[unsupported-bas
             "status",
             "queued_at",
         ),
+        Index(
+            "ix_background_tasks_task_execution_tenant_status_queued",
+            "tenant_id",
+            "status",
+            "queued_at",
+        ),
     )

{simple_module_background_tasks-0.0.34 → simple_module_background_tasks-0.0.36}/background_tasks/module.py

@@ -152,13 +152,18 @@ class BackgroundTasksModule(ModuleBase):
         from background_tasks.celery_app import build_celery
         from background_tasks.signals import bind_event_bus
         from background_tasks.sync_db import set_database_url
+        from background_tasks.tenant_context import set_default_tenant
 
         services = app.state.background_tasks
         # Pin the sync engine to the same URL the host's async settings
         # resolved — pydantic-settings reads ``.env`` but never propagates
         # to ``os.environ``, so signals would otherwise fall back to the
         # SQLite default and silently drop ``TaskExecution`` rows.
-        set_database_url(app.state.sm.settings.database_url)
+        host = app.state.sm.settings
+        multi = bool(getattr(host, "multi_tenant", False))
+        default_tenant = None if multi else getattr(host, "default_tenant", "") or None
+        set_database_url(host.database_url, tenant_strict=multi, default_tenant=default_tenant)
+        set_default_tenant(default_tenant)
         # build_celery imports `signals` for side effects and runs
         # `autodiscover_tasks` across every installed module.
         services.celery = build_celery(services.settings)
@@ -172,6 +177,8 @@ class BackgroundTasksModule(ModuleBase):
             services.settings.task_default_queue,
         )
 
+        await self._start_invalidation_transport(app)
+
         # Registered here, not in register_health_checks: the Celery app does
         # not exist until this hook builds it, and the check must follow later
         # settings changes rather than pinning the boot-time instance.
@@ -199,11 +206,52 @@ class BackgroundTasksModule(ModuleBase):
             )
         )
 
+    @staticmethod
+    async def _start_invalidation_transport(app: FastAPI) -> None:
+        """Hand the framework bus the Redis connection this module configures.
+
+        The transport is installed here rather than in a registration hook
+        because it needs a running event loop for its listener task, and it is
+        installed by *this* module because it owns the Redis URL — a cache-owning
+        module opening its own connection is the duplication GH #318 exists to
+        avoid.
+
+        A worker process that runs Celery without the FastAPI app never reaches
+        this, so it publishes nothing and hears nothing. That is the same
+        documented cross-process limit as ``bind_event_bus`` above: a task that
+        invalidates a cache should do it through an API call or accept the TTL.
+        """
+        from background_tasks.invalidation import RedisInvalidationTransport
+
+        services = app.state.background_tasks
+        s = services.settings
+        if not s.broadcast_invalidations:
+            logger.info(
+                "BackgroundTasks: cross-worker cache invalidation disabled "
+                "(broadcast_invalidations=false) — per-process caches expire on their own TTL"
+            )
+            return
+
+        bus = app.state.sm.invalidation
+        transport = RedisInvalidationTransport(bus, s.broker_url, s.invalidation_channel)
+        await transport.start()
+        bus.set_transport(transport)
+        services.invalidation_transport = transport
+        logger.info(
+            "BackgroundTasks: invalidation transport on %r for channel(s) %s",
+            s.invalidation_channel,
+            ", ".join(bus.channels) or "(none subscribed)",
+        )
+
     async def on_shutdown(self, app: FastAPI) -> None:
         from background_tasks.signals import unbind_event_bus
         from background_tasks.sync_db import dispose_sync_engine
 
         services = app.state.background_tasks
+        if services.invalidation_transport is not None:
+            app.state.sm.invalidation.clear_transport()
+            await services.invalidation_transport.stop()
+            services.invalidation_transport = None
         if services.celery is not None:
             services.celery.close()
         unbind_event_bus()