oidcauthlib 3.0.18__tar.gz → 3.0.19__tar.gz

{oidcauthlib-3.0.18/oidcauthlib.egg-info → oidcauthlib-3.0.19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oidcauthlib
-Version: 3.0.18
+Version: 3.0.19
 Summary: oidcauthlib
 Author-email: Imran Qureshi <imran.qureshi@bwell.com>
 License: Apache-2.0

oidcauthlib-3.0.19/VERSION

@@ -0,0 +1 @@
+3.0.19

oidcauthlib-3.0.19/oidcauthlib/cache_gate/__init__.py

@@ -0,0 +1,4 @@
+from oidcauthlib.cache_gate.advisory_lock import AdvisoryLock
+from oidcauthlib.cache_gate.version_gate import VersionGate
+
+__all__ = ["AdvisoryLock", "VersionGate"]

oidcauthlib-3.0.19/oidcauthlib/cache_gate/advisory_lock.py

@@ -0,0 +1,168 @@
+"""Staged here pending extraction into a standalone shared-infra package —
+this module has no OIDC-specific logic and doesn't belong in oidc-auth-lib
+long-term; it's here because this is the one package every consumer of
+VersionGate already depends on.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import uuid
+from types import TracebackType
+
+from key_value.aio.protocols.key_value import AsyncKeyValueProtocol
+
+logger = logging.getLogger(__name__)
+
+LOCK_COLLECTION = "advisory_locks"
+
+
+class AdvisoryLock:
+    """Distributed advisory lock backed by any AsyncKeyValueProtocol store.
+
+    Uses put-with-TTL so that stale locks auto-expire if the holder crashes.
+    Acquire semantics rely on get-then-put — not atomic compare-and-swap —
+    so there is a small race window. For leader-election among cooperating
+    workers at startup this is acceptable; do not use for high-contention
+    critical sections.
+
+    While held, a background task refreshes the lock's TTL every
+    `heartbeat_interval_seconds` (default `ttl_seconds / 2`) — so `ttl_seconds`
+    only bounds how quickly a *crashed* holder's lock is reclaimed, not how
+    long the guarded critical section may run. Without this, a critical
+    section that legitimately outlives `ttl_seconds` would have its lock
+    entry expire while still running, letting a second holder acquire the
+    same lock and re-enter concurrently — exactly what the lock exists to
+    prevent. A single missed heartbeat is not fatal: it's logged and retried
+    on the next tick, with a full `heartbeat_interval_seconds` of margin
+    before the lock would actually expire.
+
+    Usage:
+        async with AdvisoryLock(store, "skill_sync", ttl_seconds=300) as acquired:
+            if acquired:
+                await do_sync()
+    """
+
+    def __init__(
+        self,
+        store: AsyncKeyValueProtocol,
+        lock_name: str,
+        *,
+        ttl_seconds: int = 300,
+        collection: str = LOCK_COLLECTION,
+        heartbeat_interval_seconds: float | None = None,
+    ) -> None:
+        self._store = store
+        self._lock_name = lock_name
+        self._ttl_seconds = ttl_seconds
+        self._collection = collection
+        self._heartbeat_interval_seconds = heartbeat_interval_seconds or (ttl_seconds / 2)
+        self._holder_id = f"{os.getpid()}-{uuid.uuid4().hex[:8]}"
+        self._acquired = False
+        self._heartbeat_task: asyncio.Task[None] | None = None
+
+    @property
+    def acquired(self) -> bool:
+        return self._acquired
+
+    async def __aenter__(self) -> bool:
+        existing = await self._store.get(self._lock_name, collection=self._collection)
+
+        if existing is not None:
+            logger.info(
+                "AdvisoryLock: lock '%s' held by '%s' — skipping.",
+                self._lock_name,
+                existing.get("holder", "unknown"),
+            )
+            self._acquired = False
+            return False
+
+        await self._store.put(
+            self._lock_name,
+            {"holder": self._holder_id},
+            collection=self._collection,
+            ttl=self._ttl_seconds,
+        )
+
+        # Verify we won the race (read-after-write check)
+        written = await self._store.get(self._lock_name, collection=self._collection)
+        if written is not None and written.get("holder") == self._holder_id:
+            self._acquired = True
+            logger.info(
+                "AdvisoryLock: acquired lock '%s' (holder=%s, ttl=%ds)",
+                self._lock_name,
+                self._holder_id,
+                self._ttl_seconds,
+            )
+            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+        else:
+            self._acquired = False
+            logger.info(
+                "AdvisoryLock: lost race for lock '%s' — another holder won.",
+                self._lock_name,
+            )
+
+        return self._acquired
+
+    async def _heartbeat_loop(self) -> None:
+        while True:
+            await asyncio.sleep(self._heartbeat_interval_seconds)
+            try:
+                await self._store.put(
+                    self._lock_name,
+                    {"holder": self._holder_id},
+                    collection=self._collection,
+                    ttl=self._ttl_seconds,
+                )
+                logger.debug(
+                    "AdvisoryLock: refreshed lock '%s' (holder=%s, ttl=%ds)",
+                    self._lock_name,
+                    self._holder_id,
+                    self._ttl_seconds,
+                )
+            except Exception:
+                logger.warning(
+                    "AdvisoryLock: failed to refresh lock '%s' (holder=%s) — will retry "
+                    "in %.1fs; lock still expires in up to %ds if refreshes keep failing.",
+                    self._lock_name,
+                    self._holder_id,
+                    self._heartbeat_interval_seconds,
+                    self._ttl_seconds,
+                    exc_info=True,
+                )
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        if self._heartbeat_task is not None:
+            self._heartbeat_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._heartbeat_task
+            self._heartbeat_task = None
+
+        if self._acquired:
+            try:
+                await self._store.delete(self._lock_name, collection=self._collection)
+                logger.info(
+                    "AdvisoryLock: released lock '%s' (holder=%s)",
+                    self._lock_name,
+                    self._holder_id,
+                )
+            except Exception:
+                # Don't let a failed release mask an exception already propagating
+                # from the caller's critical section. The heartbeat has stopped, so
+                # the lock still self-clears once its TTL elapses.
+                logger.warning(
+                    "AdvisoryLock: failed to release lock '%s' (holder=%s) — it will "
+                    "still expire via TTL in up to %ds.",
+                    self._lock_name,
+                    self._holder_id,
+                    self._ttl_seconds,
+                    exc_info=True,
+                )

oidcauthlib-3.0.19/oidcauthlib/cache_gate/version_gate.py

@@ -0,0 +1,103 @@
+"""Staged here pending extraction into a standalone shared-infra package —
+this module has no OIDC-specific logic and doesn't belong in oidc-auth-lib
+long-term; it's here because this is the one package both current consumers
+(baileyai, baileyai-skills-service) already depend on.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+
+from key_value.aio.protocols.key_value import AsyncKeyValueProtocol
+
+from oidcauthlib.cache_gate.advisory_lock import AdvisoryLock
+
+logger = logging.getLogger(__name__)
+
+VERSION_GATE_COLLECTION = "version_gate"
+
+
+class VersionGate:
+    """Runs an action at most once per distinct version, across a pod fleet.
+
+    Compares `current_version` against a marker persisted in `store`. If it
+    differs, runs `action` and — only once `action` completes without raising
+    — persists the new marker. The marker is written *after* the action
+    succeeds, never before: writing it first would let a crashed/incomplete
+    action look "done" to every other pod, forever, until the version next
+    changes.
+
+    Pass `lock_name` when `action` is not safe to run concurrently from
+    multiple pods (e.g. a multi-step load with partial-write visibility).
+    Omit it when `action` is idempotent under concurrent execution (e.g. a
+    pure cache clear followed by lazy repopulation) — redundant concurrent
+    runs are then harmless and a lock only adds latency/contention.
+    """
+
+    def __init__(
+        self,
+        *,
+        store: AsyncKeyValueProtocol,
+        key: str,
+        collection: str = VERSION_GATE_COLLECTION,
+        lock_name: str | None = None,
+        lock_ttl_seconds: int = 300,
+        lock_heartbeat_interval_seconds: float | None = None,
+    ) -> None:
+        self._store = store
+        self._key = key
+        self._collection = collection
+        self._lock_name = lock_name
+        self._lock_ttl_seconds = lock_ttl_seconds
+        self._lock_heartbeat_interval_seconds = lock_heartbeat_interval_seconds
+
+    async def run_if_changed_async(
+        self,
+        *,
+        current_version: str,
+        action: Callable[[], Awaitable[None]],
+    ) -> bool:
+        """Runs `action` and records `current_version` iff it differs from the
+        stored marker. Returns True iff `action` ran.
+        """
+        if await self._is_current(current_version):
+            return False
+
+        if self._lock_name is None:
+            await action()
+            await self._mark(current_version)
+            return True
+
+        async with AdvisoryLock(
+            self._store,
+            self._lock_name,
+            ttl_seconds=self._lock_ttl_seconds,
+            heartbeat_interval_seconds=self._lock_heartbeat_interval_seconds,
+        ) as acquired:
+            if not acquired:
+                logger.info(
+                    "VersionGate: lock '%s' held by another pod — skipping.",
+                    self._lock_name,
+                )
+                return False
+
+            # Re-check: whoever held the lock before us may have already
+            # handled this version change while we were waiting to acquire.
+            if await self._is_current(current_version):
+                return False
+
+            await action()
+            await self._mark(current_version)
+            return True
+
+    async def _is_current(self, current_version: str) -> bool:
+        stored = await self._store.get(self._key, collection=self._collection)
+        return stored is not None and stored.get("version") == current_version
+
+    async def _mark(self, current_version: str) -> None:
+        await self._store.put(
+            self._key,
+            {"version": current_version},
+            collection=self._collection,
+        )

{oidcauthlib-3.0.18 → oidcauthlib-3.0.19/oidcauthlib.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oidcauthlib
-Version: 3.0.18
+Version: 3.0.19
 Summary: oidcauthlib
 Author-email: Imran Qureshi <imran.qureshi@bwell.com>
 License: Apache-2.0

{oidcauthlib-3.0.18 → oidcauthlib-3.0.19}/oidcauthlib.egg-info/SOURCES.txt

@@ -55,6 +55,9 @@ oidcauthlib/auth/well_known_configuration/auth_server_metadata_discovery.py
 oidcauthlib/auth/well_known_configuration/well_known_configuration_cache.py
 oidcauthlib/auth/well_known_configuration/well_known_configuration_cache_result.py
 oidcauthlib/auth/well_known_configuration/well_known_configuration_manager.py
+oidcauthlib/cache_gate/__init__.py
+oidcauthlib/cache_gate/advisory_lock.py
+oidcauthlib/cache_gate/version_gate.py
 oidcauthlib/container/__init__.py
 oidcauthlib/container/oidc_authlib_container_factory.py
 oidcauthlib/open_telemetry/__init__.py

oidcauthlib-3.0.18/VERSION

@@ -1 +0,0 @@
-3.0.18