# Deployment Documentation

Tobuzz Extractor is engineered for zero-latency edge deployment on Cloudflare Workers with native `nodejs_compat` support and optional Cloudflare KV caching.

---

## Cloudflare Workers Deployment Setup

### 1. Configuration (`wrangler.toml`)
The repository includes `wrangler.toml` preconfigured for edge execution:

```toml
name = "tobuzz-extractor"
main = "src/worker.ts"
compatibility_date = "2024-09-23"
compatibility_flags = ["nodejs_compat"]

[assets]
directory = "."
binding = "ASSETS"

# Optional Cloudflare KV distributed cache
# [[kv_namespaces]]
# binding = "CACHE_KV"
# id = "<YOUR_KV_NAMESPACE_ID>"
```

### 2. Static Assets & Interactive UI
Static assets (`index.html`, documentation markdown files) are served seamlessly via Cloudflare Workers Static Assets (`[assets]` binding) or the built-in HTTP server during development.

### 3. Deploying via Wrangler CLI
```bash
# Install Wrangler CLI (if not already installed)
npm install -g wrangler

# Login to Cloudflare account
wrangler login

# Deploy directly to Cloudflare edge network
wrangler deploy
```

---

## Environment Variables & Bindings

| Variable / Binding | Type | Description |
| --- | --- | --- |
| `CACHE_KV` | KV Namespace Binding (Optional) | Cloudflare KV namespace for distributed edge caching across all global Points of Presence. |
| `ASSETS` | Assets Binding | Cloudflare Workers Assets binding to serve static files and documentation. |
| `RUN_LIVE_TESTS` | Environment Flag (`0`/`1`) | Set to `1` to run live network integration tests during test execution. |

---

## Edge Runtime Characteristics & Bounds

- **Ultra-Fast Cold Starts**: Running on the V8 isolate edge architecture provides sub-millisecond cold starts globally.
- **Resolver Budgeting**: The resolution loop enforces an overall timeout budget with individual provider caps (3.2s - 3.8s) and fast request parsing fallback, ensuring that responses return structured JSON before client or edge timeouts.
- **Media Proxy Streaming**: `/api/media-proxy` handles Range requests, HLS master/variant rewriting, and token negotiation directly on edge nodes with low latency and streaming chunk forwarding.