Metadata-Version: 2.4
Name: zubbl-runtime
Version: 0.1.12
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.

## API keys

Supply the API key through the application environment. Never place a real Zubbl key in source code, Git, logs or screenshots.

```bash
export ZUBBL_API_KEY="zubbl_sk_..."
```

For local development, use an uncommitted environment file loaded by your application. Hosted applications should use their platform-managed environment variables or secrets.

## Bootstrap errors

`BootstrapError.retryable` distinguishes temporary network, timeout, HTTP 408, HTTP 429 and HTTP 5xx failures from non-retryable credential or configuration errors. This bootstrap policy is separate from the remotely supplied `runtime_fail_mode`.


## Trusted network context

When a framework adapter supplies a client IP, Runtime Guard uses a signed Zubbl Worker request to resolve trusted country, ASN, VPN and hosting information before local policy enforcement. Results are cached by IP to avoid a remote lookup for every request.

If trusted network information is temporarily unavailable, country remains `XX`. Geo policies allow unknown countries by default; applications can explicitly set `unknown_country_default` to `deny` when strict handling is required.

This normal path does not require trusting user-supplied proxy headers.

## Policy refresh

Runtime Guard periodically refreshes effective policies using the polling interval supplied during bootstrap. Policy changes therefore take effect without restarting the protected application. The longer cache lifetime remains available for last-known-good policy recovery when Zubbl is temporarily unavailable.
