zubbl-runtime 0.1.0__tar.gz

zubbl_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: zubbl-runtime
+Version: 0.1.0
+Summary: Core runtime client for Zubbl Runtime Guard
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+
+# Zubbl Runtime
+
+Core Python runtime client for Zubbl Runtime Guard.
+
+`zubbl-runtime` provides the shared runtime, bootstrap, signing, policy enforcement, resilience and transport components used by the Zubbl framework adapters.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install zubbl-runtime
+```
+
+Most developers should install a framework adapter such as `zubbl-fastapi`, which installs this package automatically.

zubbl_runtime-0.1.0/README.md

@@ -0,0 +1,17 @@
+# Zubbl Runtime
+
+Core Python runtime client for Zubbl Runtime Guard.
+
+`zubbl-runtime` provides the shared runtime, bootstrap, signing, policy enforcement, resilience and transport components used by the Zubbl framework adapters.
+
+## Requirements
+
+- Python 3.10+
+
+## Installation
+
+```bash
+pip install zubbl-runtime
+```
+
+Most developers should install a framework adapter such as `zubbl-fastapi`, which installs this package automatically.

zubbl_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "zubbl-runtime"
+version = "0.1.0"
+description = "Core runtime client for Zubbl Runtime Guard"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "httpx>=0.27.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.optional-dependencies]
+test = [
+  "pytest>=8.0",
+  "pytest-asyncio>=0.23",
+]

zubbl_runtime-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

zubbl_runtime-0.1.0/src/zubbl_runtime/__init__.py

@@ -0,0 +1,138 @@
+from .bootstrap import BootstrapClient, BootstrapError
+from .client import RuntimeClient, RuntimeClientError
+from .diagnostics import RuntimeDiagnostics
+from .endpoint_catalogue import (
+    EndpointCatalogueClient,
+    EndpointCatalogueError,
+    EndpointCatalogueSyncResult,
+)
+from .enforcement_result import (
+    EnforcementResult,
+    EnforcementResultBuilder,
+)
+from .models import BootstrapConfig
+from .transport import SignedTransport, TransportError
+from .runtime_context import RuntimeRequestContext
+from .runtime_enforcer import (
+    RuntimeAction,
+    RuntimeDecision,
+    RuntimeEnforcer,
+)
+from .rate_limit_store import (
+    InMemoryRateLimitStore,
+    RateLimitKey,
+    RateLimitResult,
+)
+from .route_matching import (
+    compile_route_pattern,
+    normalise_route_path,
+    route_matches,
+)
+from .policy_manager import PolicyManager
+from .policy_evaluator import (
+    EvaluationAction,
+    GeoEvaluationHandler,
+    PolicyEvaluation,
+    PolicyEvaluationHandler,
+    PolicyEvaluator,
+    PolicyEvaluatorRegistry,
+    RateLimitEvaluationHandler,
+    VpnEvaluationHandler,
+    default_policy_evaluator_registry,
+)
+from .policy_normalizer import (
+    AdaptiveInstruction,
+    CanonicalPolicyInstruction,
+    EnforcementMode,
+    GeoInstruction,
+    PolicyInstruction,
+    PolicyKind,
+    RateLimitInstruction,
+    UnknownPolicyInstruction,
+    VpnInstruction,
+    normalise_policy_tile,
+    normalise_policy_tiles,
+)
+from .policy_cache import PolicyCache
+from .policy_models import (
+    DecisionSource,
+    EffectivePolicy,
+    PolicyCacheKey,
+    PolicyDecision,
+    PolicyResolution,
+    PolicyScope,
+    PolicySnapshot,
+    PolicyTile,
+    PolicyValidationError,
+)
+from .signing import (
+    build_canonical_request,
+    generate_nonce,
+    sha256_hex,
+    sign_request,
+    verify_signature,
+)
+
+__all__ = [
+    "BootstrapClient",
+    "BootstrapConfig",
+    "BootstrapError",
+    "PolicyValidationError",
+    "PolicyTile",
+    "PolicySnapshot",
+    "PolicyScope",
+    "PolicyResolution",
+    "normalise_policy_tiles",
+    "normalise_policy_tile",
+    "VpnInstruction",
+    "UnknownPolicyInstruction",
+    "RateLimitInstruction",
+    "PolicyKind",
+    "PolicyInstruction",
+    "GeoInstruction",
+    "EnforcementMode",
+    "CanonicalPolicyInstruction",
+    "AdaptiveInstruction",
+    "default_policy_evaluator_registry",
+    "VpnEvaluationHandler",
+    "RateLimitEvaluationHandler",
+    "PolicyEvaluatorRegistry",
+    "PolicyEvaluationHandler",
+    "GeoEvaluationHandler",
+    "EnforcementResultBuilder",
+    "EndpointCatalogueSyncResult",
+    "EndpointCatalogueError",
+    "EndpointCatalogueClient",
+    "EnforcementResult",
+    "PolicyEvaluator",
+    "PolicyEvaluation",
+    "EvaluationAction",
+    "PolicyManager",
+    "PolicyDecision",
+    "PolicyCacheKey",
+    "PolicyCache",
+    "EffectivePolicy",
+    "DecisionSource",
+    "route_matches",
+    "normalise_route_path",
+    "compile_route_pattern",
+    "RateLimitResult",
+    "RateLimitKey",
+    "InMemoryRateLimitStore",
+    "RuntimeEnforcer",
+    "RuntimeDecision",
+    "RuntimeAction",
+    "RuntimeRequestContext",
+    "RuntimeDiagnostics",
+    "RuntimeClient",
+    "RuntimeClientError",
+    "SignedTransport",
+    "TransportError",
+    "build_canonical_request",
+    "generate_nonce",
+    "sha256_hex",
+    "sign_request",
+    "verify_signature",
+]
+
+__version__ = "0.1.0"

zubbl_runtime-0.1.0/src/zubbl_runtime/bootstrap.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+import httpx
+
+from .models import BootstrapConfig
+
+
+class BootstrapError(RuntimeError):
+    """Raised when Runtime Guard bootstrap cannot be completed."""
+
+
+@dataclass(slots=True)
+class _CachedBootstrap:
+    config: BootstrapConfig
+    expires_at: float
+
+
+class BootstrapClient:
+    """
+    Resolves Runtime Guard configuration from a Zubbl API key.
+
+    Bootstrap results are cached in memory only. The signing secret is never
+    persisted to disk by this client.
+
+    A shared HTTP client may be supplied by RuntimeClient. When no client is
+    supplied, standalone use retains the original per-request client lifecycle.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = "https://api.zubbl.com",
+        timeout_seconds: float = 8.0,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        cleaned_api_key = api_key.strip()
+
+        if not cleaned_api_key:
+            raise ValueError("api_key must not be empty")
+
+        self._api_key = cleaned_api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout_seconds = timeout_seconds
+        self._http_client = http_client
+        self._cache: _CachedBootstrap | None = None
+
+    async def _post_bootstrap(
+        self,
+        url: str,
+        *,
+        headers: dict[str, str],
+    ) -> httpx.Response:
+        if self._http_client is not None:
+            return await self._http_client.post(
+                url,
+                headers=headers,
+            )
+
+        # Backwards-compatible standalone behaviour.
+        async with httpx.AsyncClient(
+            timeout=self._timeout_seconds,
+        ) as client:
+            return await client.post(
+                url,
+                headers=headers,
+            )
+
+    async def bootstrap(
+        self,
+        *,
+        force_refresh: bool = False,
+    ) -> BootstrapConfig:
+        now = time.monotonic()
+
+        if (
+            not force_refresh
+            and self._cache is not None
+            and self._cache.expires_at > now
+        ):
+            return self._cache.config
+
+        url = f"{self._base_url}/api/sdk/bootstrap"
+
+        try:
+            response = await self._post_bootstrap(
+                url,
+                headers={
+                    "Authorization": f"Bearer {self._api_key}",
+                    "User-Agent": "zubbl-runtime/0.1.0",
+                },
+            )
+        except httpx.TimeoutException as exc:
+            raise BootstrapError(
+                "Zubbl bootstrap request timed out"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise BootstrapError(
+                "Could not connect to Zubbl bootstrap endpoint"
+            ) from exc
+
+        if response.status_code in {401, 403}:
+            raise BootstrapError(
+                "Zubbl API key is invalid, revoked or unavailable"
+            )
+
+        if response.status_code != 200:
+            raise BootstrapError(
+                f"Zubbl bootstrap failed with HTTP "
+                f"{response.status_code}"
+            )
+
+        try:
+            payload = response.json()
+
+            config = BootstrapConfig(
+                tenant_id=str(payload["tenant_id"]),
+                app_id=str(payload["app_id"]),
+                signing_secret=str(payload["signing_secret"]),
+                runtime_version=str(payload["runtime_version"]),
+                telemetry_enabled=bool(payload["telemetry_enabled"]),
+                endpoint_discovery=bool(payload["endpoint_discovery"]),
+                cache_ttl_seconds=int(
+                    payload["cache_ttl_seconds"]
+                ),
+                polling_interval_seconds=int(
+                    payload["polling_interval_seconds"]
+                ),
+                protocol_version=int(payload["protocol_version"]),
+                runtime_fail_mode=str(
+                    payload["runtime_fail_mode"]
+                ),
+            )
+        except (KeyError, TypeError, ValueError) as exc:
+            raise BootstrapError(
+                "Zubbl bootstrap returned an invalid configuration"
+            ) from exc
+
+        if (
+            not config.tenant_id
+            or not config.app_id
+            or not config.signing_secret
+        ):
+            raise BootstrapError(
+                "Zubbl bootstrap configuration is incomplete"
+            )
+
+        if config.runtime_fail_mode not in {"open", "closed"}:
+            raise BootstrapError(
+                "Zubbl bootstrap returned an invalid runtime_fail_mode"
+            )
+
+        self._cache = _CachedBootstrap(
+            config=config,
+            expires_at=(
+                now + max(1, config.cache_ttl_seconds)
+            ),
+        )
+
+        return config
+
+    def clear_cache(self) -> None:
+        self._cache = None