arbora 0.1.8.dev10__tar.gz → 0.1.8.dev11__tar.gz

{arbora-0.1.8.dev10 → arbora-0.1.8.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arbora
-Version: 0.1.8.dev10
+Version: 0.1.8.dev11
 Summary: The deployable MCP, REST, control-plane, fleet, WebUI, and operations composition for the Knuckles agent platform.
 Author-email: Repository Maintainers <maintainers@knuckles.team>
 License-Expression: MIT

{arbora-0.1.8.dev10 → arbora-0.1.8.dev11}/arbora/_version.py

@@ -3,4 +3,4 @@
 Updated only by `bump-my-version` (see `.bumpversion.toml`) — never hand-edited.
 """
 
-__version__ = "0.1.8.dev10"
+__version__ = "0.1.8.dev11"

{arbora-0.1.8.dev10 → arbora-0.1.8.dev11}/arbora/fleet/catalog_reader.py

@@ -13,6 +13,7 @@ composition-root adapter.
 
 from __future__ import annotations
 
+import asyncio
 import logging
 import threading
 import time
@@ -222,6 +223,19 @@ _MAX_CACHED_SNAPSHOTS: Final = 64
 _MAX_CACHED_CONTENTS: Final = 50_000
 
 
+#: A snapshot older than its TTL is still served, while one refresh runs, up
+#: to this many TTLs old; past that a caller waits for the fresh read.
+_STALE_SERVE_FACTOR: Final = 3.0
+
+
+def _log_refresh_failure(task: asyncio.Task[Any]) -> None:
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is not None:
+        logger.warning("fleet catalog refresh failed: %s", type(exc).__name__)
+
+
 class FleetCatalogReader:
     """Read and verify one complete Medulla-native fleet catalog snapshot."""
 
@@ -254,6 +268,10 @@ class FleetCatalogReader:
         self._cache_lock = threading.Lock()
         self._snapshots: dict[tuple[Any, ...], tuple[float, FleetCatalog]] = {}
         self._contents: dict[tuple[Any, ...], ComponentContent] = {}
+        # One full read per key at a time, owned by the reader and shielded
+        # from its callers (ARBORA-FLEET-R067): a caller whose own deadline
+        # passes never cancels the read, so the snapshot always lands.
+        self._inflight: dict[tuple[Any, ...], asyncio.Task[FleetCatalog]] = {}
 
     async def read(
         self,
@@ -265,23 +283,65 @@ class FleetCatalogReader:
         context = await self._port.read_context()
         self._validate_context(context)
         key = (context, selected_kinds)
-        if self._snapshot_ttl_s > 0:
-            with self._cache_lock:
-                cached = self._snapshots.get(key)
-            if (
-                cached is not None
-                and time.monotonic() - cached[0] < self._snapshot_ttl_s
-            ):
-                return cached[1]
+        if self._snapshot_ttl_s <= 0:
+            return await self._read_full(context, selected_kinds)
+        with self._cache_lock:
+            cached = self._snapshots.get(key)
+        age = None if cached is None else time.monotonic() - cached[0]
+        if cached is not None and age is not None and age < self._snapshot_ttl_s:
+            return cached[1]
+        refresh = self._refresh(key, context, selected_kinds)
+        if (
+            cached is not None
+            and age is not None
+            and age < self._snapshot_ttl_s * _STALE_SERVE_FACTOR
+        ):
+            # Serve the last verified snapshot while one refresh runs: a full
+            # read outlasts every interactive deadline on a real fleet.
+            return cached[1]
+        return await asyncio.shield(refresh)
+
+    def _refresh(
+        self,
+        key: tuple[Any, ...],
+        context: ReadContext,
+        kinds: tuple[ComponentKind, ...],
+    ) -> asyncio.Task[FleetCatalog]:
+        """Start (or join) the one full read for ``key``; it caches on success."""
+
+        task = self._inflight.get(key)
+        if (
+            task is not None
+            and not task.done()
+            and task.get_loop() is asyncio.get_running_loop()
+        ):
+            return task
+
+        async def run() -> FleetCatalog:
+            try:
+                catalog = await self._read_full(context, kinds)
+                with self._cache_lock:
+                    if len(self._snapshots) >= _MAX_CACHED_SNAPSHOTS:
+                        self._snapshots.clear()
+                    self._snapshots[key] = (time.monotonic(), catalog)
+                return catalog
+            finally:
+                if self._inflight.get(key) is task_ref[0]:
+                    self._inflight.pop(key, None)
+
+        task_ref: list[asyncio.Task[FleetCatalog]] = []
+        task = asyncio.get_running_loop().create_task(run())
+        task_ref.append(task)
+        task.add_done_callback(_log_refresh_failure)
+        self._inflight[key] = task
+        return task
+
+    async def _read_full(
+        self, context: ReadContext, kinds: tuple[ComponentKind, ...]
+    ) -> FleetCatalog:
         registrations = await self._read_servers(context)
-        components = await self._read_components(context, selected_kinds)
-        catalog = await self._join(context, registrations, components)
-        if self._snapshot_ttl_s > 0:
-            with self._cache_lock:
-                if len(self._snapshots) >= _MAX_CACHED_SNAPSHOTS:
-                    self._snapshots.clear()
-                self._snapshots[key] = (time.monotonic(), catalog)
-        return catalog
+        components = await self._read_components(context, kinds)
+        return await self._join(context, registrations, components)
 
     @staticmethod
     def _validated_kinds(kinds: Sequence[ComponentKind]) -> tuple[ComponentKind, ...]:

{arbora-0.1.8.dev10 → arbora-0.1.8.dev11}/arbora.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arbora
-Version: 0.1.8.dev10
+Version: 0.1.8.dev11
 Summary: The deployable MCP, REST, control-plane, fleet, WebUI, and operations composition for the Knuckles agent platform.
 Author-email: Repository Maintainers <maintainers@knuckles.team>
 License-Expression: MIT

{arbora-0.1.8.dev10 → arbora-0.1.8.dev11}/tests/test_fleet_catalog_reader.py

@@ -342,6 +342,70 @@ def test_reader_reuses_a_verified_snapshot_within_its_ttl() -> None:
     assert len(port.search_calls) == 1
 
 
+class GatedPort(FakeFleetCatalogPort):
+    """A port whose server read waits on a gate: a slow full fleet read."""
+
+    def __init__(self, **kwargs: object) -> None:
+        super().__init__(**kwargs)  # type: ignore[arg-type]
+        self.gate = asyncio.Event()
+
+    async def query_registered_servers(
+        self, graph: str, limit: int, cursor: str | None, /
+    ) -> ServerPage:
+        await self.gate.wait()
+        return await super().query_registered_servers(graph, limit, cursor)
+
+
+@pytest.mark.spec("ARBORA-FLEET-R067")
+def test_a_caller_deadline_never_cancels_the_shared_snapshot_read() -> None:
+    """A read longer than the caller's budget still lands in the cache."""
+    port = GatedPort()
+    reader = FleetCatalogReader(port, snapshot_ttl_s=60.0)
+
+    async def scenario() -> tuple[object, object]:
+        with pytest.raises(TimeoutError):
+            await asyncio.wait_for(reader.read(), timeout=0.01)
+        joined = asyncio.create_task(reader.read())
+        await asyncio.sleep(0)
+        port.gate.set()
+        first = await joined
+        return first, await reader.read()
+
+    first, second = asyncio.run(scenario())
+    assert second is first
+    assert len(port.server_calls) == 1
+
+
+@pytest.mark.spec("ARBORA-FLEET-R067")
+def test_a_stale_snapshot_is_served_while_one_refresh_runs() -> None:
+    port = GatedPort(
+        server_pages=[server_page(SERVER), server_page(SERVER)],
+        component_pages=[
+            component_page(SERVER_COMPONENT, TOOL_COMPONENT),
+            component_page(SERVER_COMPONENT, TOOL_COMPONENT),
+        ],
+    )
+    reader = FleetCatalogReader(port, snapshot_ttl_s=60.0)
+
+    async def scenario() -> None:
+        port.gate.set()
+        first = await reader.read()
+        key = next(iter(reader._snapshots))
+        stamp, snap = reader._snapshots[key]
+        reader._snapshots[key] = (stamp - 61.0, snap)
+        port.gate.clear()
+        stale = await asyncio.wait_for(reader.read(), timeout=1.0)
+        assert stale is first
+        assert await asyncio.wait_for(reader.read(), timeout=1.0) is first
+        port.gate.set()
+        await reader._inflight[key]
+        fresh = await reader.read()
+        assert fresh is not first
+
+    asyncio.run(scenario())
+    assert len(port.server_calls) == 2
+
+
 def test_reader_without_a_ttl_reads_eg_every_time() -> None:
     port = FakeFleetCatalogPort(
         server_pages=[server_page(SERVER), server_page(SERVER)],