simple-module-background-tasks 0.0.33__tar.gz → 0.0.35__tar.gz

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simple_module_background_tasks
-Version: 0.0.33
+Version: 0.0.35
 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.33
-Requires-Dist: simple-module-db==0.0.33
-Requires-Dist: simple-module-hosting==0.0.33
-Requires-Dist: simple-module-settings==0.0.33
+Requires-Dist: simple-module-core==0.0.35
+Requires-Dist: simple-module-db==0.0.35
+Requires-Dist: simple-module-hosting==0.0.35
+Requires-Dist: simple-module-settings==0.0.35
 Description-Content-Type: text/markdown
 
 # simple_module_background_tasks

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/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"

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/background_tasks/deps.py

@@ -4,15 +4,15 @@ from __future__ import annotations
 
 from fastapi import Depends, Request
 from simple_module_core.events import EventBus
+from simple_module_db import RequestSession
 from simple_module_db.deps import get_db
-from sqlalchemy.ext.asyncio import AsyncSession
 
 from background_tasks.service import BackgroundTaskService
 
 
 async def get_background_task_service(
     request: Request,
-    db: AsyncSession = Depends(get_db),
+    db: RequestSession = Depends(get_db),
 ) -> BackgroundTaskService:
     services = request.app.state.background_tasks
     bus: EventBus = request.app.state.sm.event_bus

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/background_tasks/endpoints/api_admin.py

@@ -34,14 +34,23 @@ router = APIRouter(
 @router.get("/executions", response_model=TaskExecutionListResponse)
 async def list_executions(
     status: TaskStatus | None = Query(default=None),
-    task_name: str | None = Query(default=None),
+    q: str | None = Query(default=None),
+    task_name: str | None = Query(default=None, deprecated=True),
     queue: 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),
 ) -> TaskExecutionListResponse:
+    """List executions, filtered exactly as the page filters them.
+
+    The task-name search is ``q`` — the same name the page and the sweep use,
+    so an operator can move a URL between the three and keep their filter. This
+    endpoint originally spelled it ``task_name``, which meant a link copied off
+    the screen silently listed *everything*; that spelling is still accepted so
+    existing API callers keep working, and ``q`` wins when both are given.
+    """
     return await service.list(
-        status=status, task_name=task_name, queue=queue, page=page, per_page=per_page
+        status=status, task_name=q or task_name, queue=queue, page=page, per_page=per_page
     )
 
 

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/background_tasks/endpoints/views.py

@@ -6,9 +6,9 @@ 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,

simple_module_background_tasks-0.0.35/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.33 → simple_module_background_tasks-0.0.35}/background_tasks/locales/en.json

@@ -12,9 +12,11 @@
   "strip": {
     "queued": "Queued",
     "running": "Running",
-    "succeeded_24h": "Succeeded 24h",
+    "succeeded": "Succeeded",
     "failed": "Failed",
-    "stuck": "Stuck"
+    "stuck": "Stuck",
+    "window_all": "All time",
+    "window_24h": "Last 24h"
   },
   "filters": {
     "status_label": "Filter by status",

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/background_tasks/module.py

@@ -152,13 +152,17 @@ 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))
+        set_database_url(host.database_url, tenant_strict=multi)
+        set_default_tenant(None if multi else getattr(host, "default_tenant", "") or None)
         # build_celery imports `signals` for side effects and runs
         # `autodiscover_tasks` across every installed module.
         services.celery = build_celery(services.settings)
@@ -172,6 +176,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 +205,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()

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/background_tasks/pages/Detail.tsx

@@ -125,5 +125,5 @@ function Detail() {
   );
 }
 
-Detail.layout = (page: React.ReactNode) => <AdminLayout>{page}</AdminLayout>;
+Detail.layout = [AdminLayout];
 export default Detail;

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/background_tasks/pages/Index.tsx

@@ -228,5 +228,5 @@ function Index() {
   );
 }
 
-Index.layout = (page: React.ReactNode) => <AdminLayout>{page}</AdminLayout>;
+Index.layout = [AdminLayout];
 export default Index;

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/background_tasks/pages/Workers.tsx

@@ -111,5 +111,5 @@ function Workers() {
   );
 }
 
-Workers.layout = (page: React.ReactNode) => <AdminLayout>{page}</AdminLayout>;
+Workers.layout = [AdminLayout];
 export default Workers;

{simple_module_background_tasks-0.0.33 → simple_module_background_tasks-0.0.35}/background_tasks/pages/components/StatusStrip.tsx

@@ -21,6 +21,8 @@ interface Tile {
   /** Status this tile narrows the table to. */
   filter: TaskStatus;
   labelKey: StripLabelKey;
+  /** The period the figure covers, spelled out under it. */
+  windowKey: StripLabelKey;
   count: (counts: StatusCounts) => number;
   tone: Tone;
 }
@@ -29,21 +31,30 @@ interface Tile {
  * The five numbers that describe a queue, left to right in the order work
  * moves through it: waiting, running, done, broken, wedged.
  *
- * "Succeeded 24h" is the only windowed figure, and deliberately so — the other
- * four are states something is in *right now*, while success is only
- * interesting as a rate. An all-time success total is a number that never goes
- * down and therefore never says anything.
+ * Succeeded is the only windowed figure, and deliberately so — the other four
+ * are states something is in *right now*, while success is only interesting as
+ * a rate. An all-time success total is a number that never goes down and
+ * therefore never says anything.
+ *
+ * That makes the row mixed units, which is why every tile carries its period
+ * rather than only the odd one out: side by side and unlabelled, a 24-hour
+ * success count reading lower than the table's total for the same filter looks
+ * like a bug, and nothing on screen said otherwise.
  */
+const ALL_TIME = keys.background_tasks.strip.window_all;
+
 const TILES: Tile[] = [
   {
     filter: TASK_STATUS.PENDING,
     labelKey: keys.background_tasks.strip.queued,
+    windowKey: ALL_TIME,
     count: (c) => c[TASK_STATUS.PENDING] ?? 0,
     tone: 'default',
   },
   {
     filter: TASK_STATUS.RUNNING,
     labelKey: keys.background_tasks.strip.running,
+    windowKey: ALL_TIME,
     count: (c) => c[TASK_STATUS.RUNNING] ?? 0,
     tone: 'default',
   },
@@ -52,19 +63,22 @@ const TILES: Tile[] = [
     // windowed: the tile is how an operator reaches the successes at all, and
     // the segmented control below has no option for them.
     filter: TASK_STATUS.SUCCESS,
-    labelKey: keys.background_tasks.strip.succeeded_24h,
+    labelKey: keys.background_tasks.strip.succeeded,
+    windowKey: keys.background_tasks.strip.window_24h,
     count: (c) => c.success_24h ?? 0,
     tone: 'default',
   },
   {
     filter: TASK_STATUS.FAILED,
     labelKey: keys.background_tasks.strip.failed,
+    windowKey: ALL_TIME,
     count: (c) => c[TASK_STATUS.FAILED] ?? 0,
     tone: 'destructive',
   },
   {
     filter: TASK_STATUS.STUCK,
     labelKey: keys.background_tasks.strip.stuck,
+    windowKey: ALL_TIME,
     count: (c) => c[TASK_STATUS.STUCK] ?? 0,
     tone: 'warning',
   },
@@ -101,6 +115,8 @@ export function StatusStrip({ counts, active, onSelect }: Props) {
             <StatCard
               label={t(tile.labelKey)}
               value={count.toLocaleString()}
+              delta={t(tile.windowKey)}
+              deltaTone="secondary"
               tone={tone}
               className="h-full"
             />