data-olympus 0.3.1__tar.gz → 0.3.3__tar.gz

{data_olympus-0.3.1 → data_olympus-0.3.3}/CHANGELOG.md

@@ -12,6 +12,43 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-07-05
+
+### Fixed
+
+- **MCP streamable-HTTP session churn under long-lived clients.** A persistent
+  client (notably `opencode serve`) that holds the `GET /mcp` SSE stream open was
+  being forced to reconnect on a cycle, piling up abandoned transports on the
+  server and leaking event listeners on the client until it degraded. Two causes
+  addressed:
+  - The activity middleware now keeps a session non-idle for as long as its SSE
+    stream is actually open (re-stamping every `KB_SESSION_TOUCH_INTERVAL_SEC`,
+    default 30s, clamped to a third of the idle window), so the reaper evicts a
+    session only after its stream has genuinely closed. With that safety in
+    place, the idle-reap default (`KB_SESSION_IDLE_TIMEOUT_SEC`) drops from 1800s
+    to 300s, so an abandoned handshake is cleared in minutes instead of half an
+    hour.
+  - The shipped ingress manifest (`deploy/k8s/ingress.yaml`) now sets a long
+    `proxy-read-timeout`/`proxy-send-timeout` and disables buffering, so a proxy
+    with a short default idle timeout (nginx: 60s) no longer closes the SSE
+    stream and triggers the reconnect loop. See `docs/serving.md`.
+
+## [0.3.2] - 2026-07-05
+
+### Fixed
+
+- **`gate/check` no longer self-DoSes multi-agent fleets with 429s.** The
+  enforcement hook calls `POST /api/v1/gate/check` (and `kb_gate_check`) once per
+  gated tool action for every agent, but it shared the write/consult quota
+  (`KB_RATE_LIMIT_PER_HOUR`, default 100). Behind an ingress with no auth, all
+  clients collapse to a single limiter bucket, so a few active agents exhausted
+  the hourly quota in minutes and everything after got `429 Too Many Requests`.
+  gate-check now has its own ceiling, `KB_GATE_CHECK_RATE_LIMIT_PER_HOUR`,
+  defaulting to `0` (unthrottled, consistent with the read routes) since it is a
+  mandatory per-action probe that does only cheap classification and no writes.
+  Set a positive value for an explicit backstop. `consult` and
+  `onboarding/cleanup-plan` stay throttled by `KB_RATE_LIMIT_PER_HOUR`.
+
 ## [0.3.1] - 2026-07-05
 
 ### Fixed
@@ -1013,7 +1050,9 @@ This project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `docs/adoption.md`: bring-your-own-KB guide (author, lint, index, serve, wire an agent).
 - `docs/comparison.md`: how data-olympus relates to OKF, enterprise catalogs, markdown KB tools, agent-context conventions, RAG, and ADR tooling.
 
-[Unreleased]: https://github.com/knaisoma/data-olympus/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/knaisoma/data-olympus/compare/v0.3.3...HEAD
+[0.3.3]: https://github.com/knaisoma/data-olympus/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/knaisoma/data-olympus/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/knaisoma/data-olympus/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/knaisoma/data-olympus/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/knaisoma/data-olympus/compare/v0.1.1...v0.2.0

{data_olympus-0.3.1 → data_olympus-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-olympus
-Version: 0.3.1
+Version: 0.3.3
 Summary: Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server
 Project-URL: Homepage, https://github.com/knaisoma/data-olympus
 Project-URL: Repository, https://github.com/knaisoma/data-olympus

{data_olympus-0.3.1 → data_olympus-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "data-olympus"
-version = "0.3.1"
+version = "0.3.3"
 description = "Governance-grade knowledge-base format (OKF-compatible) plus CLI and single-writer MCP server"
 readme = "README.md"
 requires-python = ">=3.13"

{data_olympus-0.3.1 → data_olympus-0.3.3}/src/data_olympus/config.py

@@ -28,6 +28,14 @@ class Config:
     write_block_paths: list[str] = field(default_factory=list)
     rate_limit_per_hour: int = 100
     rate_limit_per_ip_per_hour: int = 0
+    # Separate ceiling for the high-frequency /api/v1/gate/check route (the
+    # enforcement hook's per-tool-action freshness probe). 0 (default) disables
+    # throttling for that route: it is a mandatory, once-per-tool-call, read-only
+    # probe, so any fixed hourly quota self-DoSes an active multi-agent fleet
+    # (behind ingress all clients collapse to one limiter bucket). Reads are
+    # already unthrottled; this keeps gate/check consistent with them. Set a
+    # positive value only if you want an explicit backstop.
+    gate_check_rate_limit_per_hour: int = 0
     max_text_bytes: int = 262144
     max_postimage_bytes: int = 1048576
     max_body_bytes: int = 2097152
@@ -57,8 +65,15 @@ class Config:
     # Streamable-http session reaping: terminate transports idle beyond this many
     # seconds to bound _server_instances (see session_metrics). 0 disables the
     # reaper (observability-only). The scan runs every session_reap_interval_sec.
-    session_idle_timeout_sec: int = 1800
+    # An in-flight GET SSE stream is kept non-idle by the activity middleware, so
+    # this window only clears sessions whose stream has actually closed (an
+    # abandoned handshake); 5 minutes keeps those from piling up.
+    session_idle_timeout_sec: int = 300
     session_reap_interval_sec: int = 60
+    # How often the activity middleware re-stamps a session while its GET SSE
+    # stream is open, so a quiet-but-connected client is never reaped. Clamped
+    # below session_idle_timeout_sec at wiring time.
+    session_touch_interval_sec: int = 30
     # Optional override for the status-aware reranker's status->weight map
     # (issue #37). None means "use the Index built-in default map". A negative
     # weight boosts an in-force status, a positive one penalizes a retired one.
@@ -155,6 +170,7 @@ def load_config() -> Config:
     write_block_paths = _split_csv(os.getenv("KB_WRITE_BLOCK_PATHS", ""))
     rate_limit_per_hour = int(os.getenv("KB_RATE_LIMIT_PER_HOUR", "100"))
     rate_limit_per_ip_per_hour = int(os.getenv("KB_RATE_LIMIT_PER_IP_PER_HOUR", "0"))
+    gate_check_rate_limit_per_hour = int(os.getenv("KB_GATE_CHECK_RATE_LIMIT_PER_HOUR", "0"))
     max_text_bytes = int(os.getenv("KB_MAX_TEXT_BYTES", "262144"))
     max_postimage_bytes = int(os.getenv("KB_MAX_POSTIMAGE_BYTES", "1048576"))
     max_body_bytes = int(os.getenv("KB_MAX_BODY_BYTES", "2097152"))
@@ -182,8 +198,9 @@ def load_config() -> Config:
     auth_principals = parse_principals_env(os.getenv("KB_AUTH_PRINCIPALS", ""))
     consult_ttl_sec = int(os.getenv("KB_CONSULT_TTL_SEC", "300"))
     ledger_path = os.getenv("KB_LEDGER_PATH", "/state/ledger.json")
-    session_idle_timeout_sec = int(os.getenv("KB_SESSION_IDLE_TIMEOUT_SEC", "1800"))
+    session_idle_timeout_sec = int(os.getenv("KB_SESSION_IDLE_TIMEOUT_SEC", "300"))
     session_reap_interval_sec = int(os.getenv("KB_SESSION_REAP_INTERVAL_SEC", "60"))
+    session_touch_interval_sec = int(os.getenv("KB_SESSION_TOUCH_INTERVAL_SEC", "30"))
     status_weights = _load_status_weights(os.getenv("KB_STATUS_WEIGHTS", ""))
     read_only = _env_bool(os.getenv("KB_READ_ONLY", ""))
     from data_olympus.cooccurrence import (
@@ -226,6 +243,7 @@ def load_config() -> Config:
         write_block_paths=write_block_paths,
         rate_limit_per_hour=rate_limit_per_hour,
         rate_limit_per_ip_per_hour=rate_limit_per_ip_per_hour,
+        gate_check_rate_limit_per_hour=gate_check_rate_limit_per_hour,
         max_text_bytes=max_text_bytes,
         max_postimage_bytes=max_postimage_bytes,
         max_body_bytes=max_body_bytes,
@@ -244,6 +262,7 @@ def load_config() -> Config:
         ledger_path=ledger_path,
         session_idle_timeout_sec=session_idle_timeout_sec,
         session_reap_interval_sec=session_reap_interval_sec,
+        session_touch_interval_sec=session_touch_interval_sec,
         status_weights=status_weights,
         read_only=read_only,
         cooccurrence_enabled=cooc_enabled,

{data_olympus-0.3.1 → data_olympus-0.3.3}/src/data_olympus/rest_api.py

@@ -32,6 +32,7 @@ if TYPE_CHECKING:
     from starlette.requests import Request
 
     from data_olympus.models import HealthResponse
+    from data_olympus.rate_limit import SlidingWindowLimiter
     from data_olympus.server import ServerState
 
 
@@ -285,22 +286,33 @@ async def _read_json_capped(
         )
 
 
+_USE_WRITE_LIMITER: Any = object()
+
+
 def _rate_limited(
     state: ServerState, request: Request, principal: Principal,
+    *, limiter: SlidingWindowLimiter | None = _USE_WRITE_LIMITER,
 ) -> JSONResponse | None:
-    """Apply the shared sliding-window limiter to an enforcement-plane route.
-
-    The consult / gate / cleanup-plan routes were previously unthrottled (item 6),
-    so an anonymous or authenticated caller could hammer the classifier and ledger
-    without bound. Reuse the same limiter the write routes use, keyed by
-    (remote_addr, principal name) so a per-principal quota applies. Returns a 429
-    JSONResponse when over quota, else None.
-
-    When the limiter is absent (a read-only deployment with no write pipeline
-    configured) throttling is skipped: there is no shared limiter object to
-    consult and these routes are read-mostly there.
+    """Apply a sliding-window limiter to an enforcement-plane route.
+
+    The consult / cleanup-plan routes were previously unthrottled (item 6), so an
+    anonymous or authenticated caller could hammer the classifier and ledger
+    without bound. They reuse the write limiter (``state.rate_limiter``), keyed by
+    (remote_addr, principal name). Returns a 429 JSONResponse when over quota, else
+    None.
+
+    ``limiter`` overrides which limiter to consult. The high-frequency
+    /api/v1/gate/check route passes ``state.gate_rate_limiter`` (None by default),
+    so it is unthrottled unless an operator sets an explicit ceiling: it is a
+    mandatory once-per-tool-action probe, and any fixed quota shared across a
+    fleet (all clients collapse to one bucket behind ingress) self-DoSes with 429s.
+
+    When the resolved limiter is absent (a read-only deployment, or gate/check with
+    no ceiling configured) throttling is skipped.
     """
-    limiter = state.rate_limiter
+    # Distinguish "no limiter arg" (use the write limiter) from an explicit None
+    # (the gate-check limiter with no ceiling: throttling is genuinely off).
+    limiter = state.rate_limiter if limiter is _USE_WRITE_LIMITER else limiter
     if limiter is None:
         return None
     remote_addr = request.client.host if request.client else "unknown"
@@ -662,7 +674,12 @@ def register_routes(
             principal, denied = _authorize(request, registry)
             if denied is not None:
                 return denied
-            if (throttled := _rate_limited(state, request, principal)) is not None:
+            # gate/check uses its own limiter (unthrottled by default): it is the
+            # hook's once-per-tool-action probe, so it must not share the write /
+            # consult quota (that self-DoSes a fleet, see _rate_limited).
+            if (throttled := _rate_limited(
+                state, request, principal, limiter=state.gate_rate_limiter
+            )) is not None:
                 return throttled
             import time as _time
 

{data_olympus-0.3.1 → data_olympus-0.3.3}/src/data_olympus/server.py

@@ -123,6 +123,7 @@ class ServerState:
         push_queue: PushQueue | None = None,
         pending: PendingQueue | None = None,
         rate_limiter: SlidingWindowLimiter | None = None,
+        gate_rate_limiter: SlidingWindowLimiter | None = None,
         blocklist: PathBlocklist | None = None,
         audit_log: AuditLog | None = None,
         classifier: IntentClassifier | None = None,
@@ -147,6 +148,10 @@ class ServerState:
         self.push_queue: PushQueue | None = push_queue
         self.pending: PendingQueue | None = pending
         self.rate_limiter: SlidingWindowLimiter | None = rate_limiter
+        # Separate limiter for /api/v1/gate/check (None = unthrottled, the default).
+        # Kept distinct from `rate_limiter` so gate-check traffic and the write /
+        # consult / cleanup-plan quota never share a bucket.
+        self.gate_rate_limiter: SlidingWindowLimiter | None = gate_rate_limiter
         self.blocklist: PathBlocklist | None = blocklist
         self.audit_log: AuditLog | None = audit_log
         # Process-wide write serializer (scope item 1): one instance shared by
@@ -232,6 +237,7 @@ def build_app(
     confidence_threshold: float = 0.85,
     rate_limit_per_hour: int = 100,
     rate_limit_per_ip_per_hour: int = 0,
+    gate_check_rate_limit_per_hour: int = 0,
     max_text_bytes: int = 262144,
     max_postimage_bytes: int = 1048576,
     max_body_bytes: int = 2097152,
@@ -245,8 +251,9 @@ def build_app(
     audit_hmac_key: str = "",
     audit_max_bytes: int = 0,
     ledger_path: str | None = None,
-    session_idle_timeout_sec: int = 1800,
+    session_idle_timeout_sec: int = 300,
     session_reap_interval_sec: int = 60,
+    session_touch_interval_sec: int = 30,
     status_weights: dict[str, float] | None = None,
     read_only: bool = False,
     embeddings_enabled: bool = False,
@@ -279,6 +286,7 @@ def build_app(
         write_block_paths=write_block_paths or [],
         rate_limit_per_hour=rate_limit_per_hour,
         rate_limit_per_ip_per_hour=rate_limit_per_ip_per_hour,
+        gate_check_rate_limit_per_hour=gate_check_rate_limit_per_hour,
         max_text_bytes=max_text_bytes,
         max_postimage_bytes=max_postimage_bytes,
         max_body_bytes=max_body_bytes,
@@ -293,6 +301,7 @@ def build_app(
         audit_max_bytes=audit_max_bytes,
         session_idle_timeout_sec=session_idle_timeout_sec,
         session_reap_interval_sec=session_reap_interval_sec,
+        session_touch_interval_sec=session_touch_interval_sec,
         status_weights=status_weights,
         read_only=read_only,
         embeddings_enabled=embeddings_enabled,
@@ -393,6 +402,13 @@ def build_app(
             max_per_hour=config.rate_limit_per_hour,
             max_per_ip_per_hour=config.rate_limit_per_ip_per_hour,
         )
+        # gate/check gets its own limiter only when a positive ceiling is set;
+        # 0 (default) leaves it unthrottled (see Config.gate_check_rate_limit_per_hour).
+        gate_rate_limiter = (
+            SlidingWindowLimiter(max_per_hour=config.gate_check_rate_limit_per_hour)
+            if config.gate_check_rate_limit_per_hour > 0
+            else None
+        )
         blocklist = PathBlocklist(
             tier_blocks=config.write_block_tiers,
             path_blocks=config.write_block_paths,
@@ -401,6 +417,7 @@ def build_app(
         state.push_queue = push_queue
         state.pending = pending
         state.rate_limiter = rate_limiter
+        state.gate_rate_limiter = gate_rate_limiter
         state.blocklist = blocklist
 
     if config.kb_remote_url and not config.read_only:
@@ -545,17 +562,22 @@ def build_app(
         )
         return resp.model_dump()
 
-    def _mcp_rate_limited() -> dict[str, object] | None:
-        """Apply the shared sliding-window limiter to an MCP enforcement-plane tool
+    def _mcp_rate_limited(*, gate: bool = False) -> dict[str, object] | None:
+        """Apply a sliding-window limiter to an MCP enforcement-plane tool
         (WP0b item (b)).
 
-        The REST consult / gate-check / cleanup-plan routes throttle via
-        ``_rate_limited``; the MCP tool paths did not, so an agent could hammer the
-        classifier/ledger unbounded. Key on the resolved principal (there is no
-        per-request remote addr on the MCP transport, so the limiter's per-agent
-        quota is the meaningful dimension). Returns a rejection dict when over
-        quota, else None. Skipped when no limiter is wired (read-only deploy)."""
-        limiter = state.rate_limiter
+        The REST consult / cleanup-plan routes throttle via ``_rate_limited``; the
+        MCP tool paths did not, so an agent could hammer the classifier/ledger
+        unbounded. Key on the resolved principal (there is no per-request remote
+        addr on the MCP transport, so the limiter's per-agent quota is the
+        meaningful dimension). Returns a rejection dict when over quota, else None.
+
+        ``gate=True`` (kb_gate_check) consults ``state.gate_rate_limiter`` instead
+        of the write limiter; that limiter is None by default, so the
+        high-frequency freshness probe is unthrottled unless explicitly capped,
+        matching the REST /api/v1/gate/check route. Skipped when the resolved
+        limiter is None (read-only deploy, or gate-check with no ceiling set)."""
+        limiter = state.gate_rate_limiter if gate else state.rate_limiter
         if limiter is None:
             return None
         principal_name = _current_principal.get().name
@@ -768,7 +790,7 @@ def build_app(
         ) -> dict[str, object]:
             """Return a verdict (allow | consult_required) for a pending code action.
             Governed actions require a fresh consultation on record."""
-            if (throttled := _mcp_rate_limited()) is not None:
+            if (throttled := _mcp_rate_limited(gate=True)) is not None:
                 return throttled
             import time as _time
 
@@ -852,6 +874,7 @@ def build_app_from_config(config: Config, *, bootstrap_now: bool = True) -> Fast
         confidence_threshold=config.confidence_threshold,
         rate_limit_per_hour=config.rate_limit_per_hour,
         rate_limit_per_ip_per_hour=config.rate_limit_per_ip_per_hour,
+        gate_check_rate_limit_per_hour=config.gate_check_rate_limit_per_hour,
         max_text_bytes=config.max_text_bytes,
         max_postimage_bytes=config.max_postimage_bytes,
         max_body_bytes=config.max_body_bytes,
@@ -867,6 +890,7 @@ def build_app_from_config(config: Config, *, bootstrap_now: bool = True) -> Fast
         ledger_path=config.ledger_path,
         session_idle_timeout_sec=config.session_idle_timeout_sec,
         session_reap_interval_sec=config.session_reap_interval_sec,
+        session_touch_interval_sec=config.session_touch_interval_sec,
         status_weights=config.status_weights,
         read_only=config.read_only,
         embeddings_enabled=config.embeddings_enabled,
@@ -962,9 +986,25 @@ def main() -> None:
     )
 
     tracker = SessionActivityTracker()
+    # Re-stamp an in-flight SSE session at least 3x per idle window, so a
+    # quiet-but-connected client is never reaped even if an operator sets a short
+    # idle timeout. Falls back to the configured interval when the idle window is
+    # generous.
+    _idle = config.session_idle_timeout_sec
+    _touch_interval = float(config.session_touch_interval_sec)
+    if _idle > 0:
+        # Always strictly below the idle window (>= 3 touches per window) even for
+        # a tiny idle value; a small positive floor avoids a zero/negative sleep.
+        _touch_interval = max(0.1, min(_touch_interval, _idle / 3))
     http_app = app.http_app(
         transport="streamable-http",
-        middleware=[StarletteMiddleware(SessionActivityMiddleware, tracker=tracker)],
+        middleware=[
+            StarletteMiddleware(
+                SessionActivityMiddleware,
+                tracker=tracker,
+                touch_interval_sec=_touch_interval,
+            )
+        ],
     )
     # Health surfaces the live session count; the manager is only reachable once
     # the lifespan has started, so this returns None before then (never raises).

{data_olympus-0.3.1 → data_olympus-0.3.3}/src/data_olympus/session_metrics.py

@@ -45,6 +45,7 @@ these internals, discovery returns ``None`` and the count is reported as
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import logging
 import time
 from typing import TYPE_CHECKING, Any, Protocol
@@ -195,20 +196,61 @@ class SessionActivityTracker:
 
 class SessionActivityMiddleware:
     """ASGI middleware that stamps :class:`SessionActivityTracker` on each request
-    carrying an ``mcp-session-id`` header. Pure pass-through otherwise; adds no
-    latency beyond a header scan."""
+    carrying an ``mcp-session-id`` header.
+
+    The ``GET /mcp`` Server-Sent-Events stream is a *single* long-lived request
+    that emits no further ASGI events while the session is quiet. Stamping only
+    at request start would let the idle reaper evict a still-connected client
+    after the idle window (forcing a reconnect, the exact churn that piles up
+    transports server-side and leaks listeners in a persistent client like
+    ``opencode serve``). So for an in-flight GET stream this middleware re-stamps
+    the session every ``touch_interval_sec`` for as long as the stream stays open;
+    when the client disconnects the request completes, re-stamping stops, and only
+    then does the session go idle and become reap-eligible. Short GET/POST
+    requests finish before the first tick, so they pay only the initial stamp.
+    """
 
-    def __init__(self, app: ASGIApp, tracker: SessionActivityTracker) -> None:
+    def __init__(
+        self,
+        app: ASGIApp,
+        tracker: SessionActivityTracker,
+        *,
+        touch_interval_sec: float = 30.0,
+    ) -> None:
         self.app = app
         self._tracker = tracker
+        self._touch_interval = touch_interval_sec
 
     async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
-        if scope.get("type") == "http":
-            for key, value in scope.get("headers", []):
-                if key.lower() == _MCP_SESSION_ID_HEADER and value:
-                    self._tracker.touch(value.decode("latin-1"))
-                    break
-        await self.app(scope, receive, send)
+        if scope.get("type") != "http":
+            await self.app(scope, receive, send)
+            return
+        session_id = ""
+        for key, value in scope.get("headers", []):
+            if key.lower() == _MCP_SESSION_ID_HEADER and value:
+                session_id = value.decode("latin-1")
+                break
+        if not session_id:
+            await self.app(scope, receive, send)
+            return
+        self._tracker.touch(session_id)
+        # Only the long-lived GET SSE stream needs keep-alive re-stamping.
+        if scope.get("method") != "GET":
+            await self.app(scope, receive, send)
+            return
+
+        async def _keep_active() -> None:
+            while True:
+                await asyncio.sleep(self._touch_interval)
+                self._tracker.touch(session_id)
+
+        task = asyncio.create_task(_keep_active())
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await task
 
 
 async def reap_idle_sessions(