Metadata-Version: 2.4
Name: onionoo-fastapi
Version: 1.2.0
Summary: FastAPI-based semantic/OpenAPI proxy for Tor Onionoo.
Project-URL: Repository, https://github.com/anoni-net/onionoo-fastapi
Project-URL: Issues, https://github.com/anoni-net/onionoo-fastapi/issues
License: MIT License
        
        Copyright (c) 2026 Toomore Chiang (anoni.net)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
License-File: LICENSE
Requires-Python: >=3.13
Requires-Dist: cachetools>=5.3
Requires-Dist: fastapi-mcp>=0.4
Requires-Dist: fastapi[standard]<0.137,>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: prometheus-fastapi-instrumentator>=7.0
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: slowapi>=0.1.9
Requires-Dist: structlog>=24.1
Requires-Dist: tenacity>=8.3
Requires-Dist: uvicorn[standard]>=0.27
Description-Content-Type: text/markdown

# onionoo-fastapi

FastAPI-based **semantic/OpenAPI proxy** for the Tor **Onionoo** API.

- GitHub: <https://github.com/anoni-net/onionoo-fastapi>
- Upstream data source: <https://onionoo.torproject.org>
- This service **does not store Onionoo data**, it only forwards requests and transforms responses.
- Primary motivation: Onionoo has a solid spec, but **no OpenAPI**; this service provides a friendly schema **for tooling/AI agents**.

Reference spec: [Tor Metrics – Onionoo](https://metrics.torproject.org/onionoo.html)

## Hosted instance

- Service: `https://onionoo.anoni.net`
- Swagger UI: `https://onionoo.anoni.net/docs`

## Releases

Tagged releases (`vX.Y.Z`) trigger two GitHub Actions workflows:

- `.github/workflows/release.yml` — builds the wheel/sdist and publishes to
  PyPI via Trusted Publishing. Register this workflow as a trusted publisher
  on the `onionoo-fastapi` PyPI project once before the first tag.
- `.github/workflows/docker.yml` — builds a multi-arch image and pushes to
  `ghcr.io/<owner>/onionoo-fastapi`. Uses the default `GITHUB_TOKEN`.

Cut a release with:

```bash
git tag -a v0.2.0 -m "Release 0.2.0"
git push origin v0.2.0
```

## License

MIT. See `LICENSE`.

## Requirements

- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/)

## Install

```bash
git clone https://github.com/anoni-net/onionoo-fastapi
cd onionoo-fastapi
uv sync
```

Or if you already have the source:

```bash
cd onionoo-fastapi
uv sync
```

## Run

```bash
fastapi run app.main:app --reload --host 0.0.0.0 --port 8000
```
**Note:** `fastapi run` requires FastAPI version 0.110.0 or newer.

OpenAPI docs:

- Swagger UI: `http://localhost:8000/docs`
- OpenAPI JSON: `http://localhost:8000/openapi.json`

## Test

```bash
uv sync --extra dev
uv run pytest
```

## Docker

Build and run with Docker Compose:

```bash
docker compose up -d --build
```

If port 8000 is already in use, override host port (example: 8001):

```bash
HOST_PORT=8001 docker compose up -d --build
```

Stop:

```bash
docker compose down
```

Configuration via environment variables (example):

```bash
ONIONOO_BASE_URL=https://onionoo.torproject.org HOST_PORT=8001 docker compose up -d --build
```

## API

This service exposes semantic endpoints under `/v1/*`:

- `GET /v1/summary`
- `GET /v1/details`
- `GET /v1/bandwidth`
- `GET /v1/weights`
- `GET /v1/clients`
- `GET /v1/uptime`

Aggregate (server-side group-by, sorted by relay count):

- `GET /v1/aggregate/countries` — buckets by two-letter country code
- `GET /v1/aggregate/as` — buckets by autonomous system number
- `GET /v1/aggregate/flags` — buckets by directory-authority flag (a relay can fall into multiple flag buckets)

Plus:

- `GET /healthz` — static liveness
- `GET /healthz/ready` — verifies upstream reachability (cached)
- `GET /metrics` — Prometheus format

### Example requests

```bash
# Summary (semantic keys; upstream short keys are transformed)
curl -s 'http://localhost:8000/v1/summary?limit=1' | jq .

# Details (supports Onionoo query parameters + details-only `fields`)
curl -s 'http://localhost:8000/v1/details?limit=1&search=moria&fields=nickname,fingerprint' | jq .

# Bandwidth
curl -s 'http://localhost:8000/v1/bandwidth?limit=1&search=moria' | jq .

# Weights (relays only)
curl -s 'http://localhost:8000/v1/weights?limit=1&search=moria' | jq .

# Clients (bridges only)
curl -s 'http://localhost:8000/v1/clients?limit=1' | jq .

# Uptime
curl -s 'http://localhost:8000/v1/uptime?limit=1&search=moria' | jq .
```

### Semantic field mapping notes

- `/v1/summary` transforms Onionoo short keys:
  - relay: `n,f,a,r` → `nickname,fingerprint,addresses,running`
  - bridge: `n,h,r` → `nickname,hashed_fingerprint,running`
- For some bridge documents (`/bandwidth`, `/clients`, `/uptime`), Onionoo uses the key name `fingerprint` even though the value is a **hashed fingerprint**; this API exposes that as `hashed_fingerprint`.

### Caching / 304 behavior

If the client includes `If-Modified-Since`, it will be forwarded upstream. If Onionoo replies with `304`, this service will reply `304` too.

### Configuration

Upstream / cache:

- `ONIONOO_BASE_URL` (default: `https://onionoo.torproject.org`)
- `ONIONOO_TIMEOUT_SECONDS` (default: `30`)
- `DEFAULT_LIMIT` (default: `100`)
- `MAX_LIMIT` (default: `20000`) — high enough to pull the whole corpus in one call
- `MAX_LIMIT_UNTRIMMED` (default: `200`) — above this, `/v1/details` requires a `fields=` projection and returns 422 without one. An untrimmed full-corpus details document is ~90 MB.
- `USER_AGENT`
- `CACHE_MAXSIZE` (default: `128`)
- `CACHE_DEFAULT_TTL_SECONDS` (default: `300`)
- `UPSTREAM_RETRY_ATTEMPTS` (default: `2`)

Observability / production hardening:

- `LOG_LEVEL` (default: `INFO`)
- `LOG_FORMAT` (`json` or `console`, default `json`)
- `METRICS_ENABLED` (default: `true`) — exposes `/metrics` in Prometheus format
- `CORS_ALLOW_ORIGINS` — comma-separated allowlist of browser origins. Set it to an empty string to disable CORS. Defaults and behavior below. (Renamed in 1.2.0; the old `CORS_ALLOWED_ORIGINS` still works and logs a deprecation warning.)
- `RATE_LIMIT_ENABLED` (default: `false`)
- `RATE_LIMIT_PER_MINUTE` (default: `120`)
- `HEALTHZ_READY_CACHE_SECONDS` (default: `30`)

### CORS

Browser front ends can call this service directly, which is what the relay globe on the docs site does when a reader asks it for fresh data. `CORS_ALLOW_ORIGINS` is a comma-separated allowlist:

```bash
CORS_ALLOW_ORIGINS="https://anoni.net,https://staging.example.com"
CORS_ALLOW_ORIGINS=""   # no CORS headers at all
```

The allowlist is enumerated rather than set to `*` because widening it later is easier than narrowing it. Everything served here is public read-only Onionoo data, so the list is about who gets to spend this instance's upstream request budget.

The default covers where the docs site is served from, plus the two addresses `mkdocs serve` binds to:

| Origin | What it is |
|---|---|
| `https://anoni.net` | docs site on clearnet. The docs live under a path (`/docs/`), so the origin is the bare apex. |
| `http://docs.anoninetru5tflukgfaehun7q6khowgmymcff3gtk5oyesqazhmfxtyd.onion` | docs site on the onion mirror. Plain `http` is normal for an onion service. |
| `http://127.0.0.1:8000`, `http://localhost:8000` | local `mkdocs serve`. Browsers treat the two spellings as different origins, so both are listed. |

The clearnet and onion entries are not symmetric on purpose: clearnet is path-based under the apex, while the onion mirror is a subdomain of the onion key and therefore a separate origin. **If you self-host, replace this list with your own origins.** The default names our sites because that is what the hosted instance serves.

A reader on the onion mirror who triggers a live refresh makes a **clearnet** request to `onionoo.anoni.net`, which leaves the Tor network through an exit node. Tor still hides their address from us, but the request is not onion-to-onion.

What the middleware sends:

- `Access-Control-Allow-Origin` mirrors the request origin when it is on the list, and is absent otherwise.
- `Access-Control-Allow-Methods: GET, OPTIONS`. Every route is read-only.
- `Access-Control-Allow-Credentials` is never sent. No route reads cookies or `Authorization`, so browsers should not attach ambient credentials to these calls.
- `Access-Control-Expose-Headers: X-Request-ID, Last-Modified`, so JavaScript can read the correlation id and the upstream publish time.
- `Vary: Origin` on **every** response. Starlette's CORSMiddleware only adds it on the branch where an allowed origin was present, which means a response fetched without an `Origin` header (a crawler, an uptime check, a curl) is cacheable under the same key as a browser fetch. Behind a shared cache such as Cloudflare that lets a stored copy with no `Access-Control-Allow-Origin` be replayed to a browser, where it fails. `VaryOriginMiddleware` fills the header in whenever CORS leaves it out.

The `CORS_ALLOWED_ORIGINS` name from 1.0.0 is still accepted so upgrading does not silently drop a self-hosted allowlist. `Settings` ignores unknown environment variables, so without the alias the old name would be swallowed without a word and the only symptom would be a browser-side CORS failure with nothing in the service log. Startup logs a deprecation warning when the old name is what supplied the value.

### Resource sizing

A single-worker container (the default `uvicorn` CMD in the Dockerfile) measured on Alpine 3.23 / Python 3.14 / aarch64 against the real Onionoo upstream:

| Phase | RSS | Notes |
|---|---:|---|
| **Idle** (just after start) | ~75 MiB | Python + FastAPI + Pydantic + httpx + fastapi-mcp + structlog + Prometheus instrumentator loaded; cache empty. |
| **Typical agent traffic** | ~90 MiB | After ~15 mixed `/v1/*` calls (details + aggregates), only a handful of distinct upstream payloads cached. |
| **Cache near saturation** | ~180 MiB | After 200 distinct `/v1/details` queries with `fields=` projection; cache holds ~200 entries. |

From these measurements, each cached entry costs **~0.5 MiB on average** when callers use the `fields=` projection. With the default `CACHE_MAXSIZE=128` that yields a **~64 MiB upper bound** under realistic agent traffic.

Entries hold the parsed upstream body, so a few large documents dominate the resident set. `MAX_LIMIT_UNTRIMMED` is what keeps any single entry small: it forces high-limit `/v1/details` callers into a `fields=` projection, so the multi-hundred-MiB caches that unfiltered full-corpus responses would produce stay out of reach. Raise `CACHE_MAXSIZE` only after checking the payload sizes your deployment actually sees.

Suggested memory limits for `docker run --memory` / Kubernetes requests:

| Deployment shape | Memory request | Memory limit |
|---|---:|---:|
| Personal / single-agent test | 128 MiB | 256 MiB |
| Hosted instance, mostly cached requests | 256 MiB | 512 MiB |
| Public instance, agents may issue unfiltered `/details` | 512 MiB | 1–2 GiB |

CPU is light — a single worker handles 10s of QPS comfortably; scale with replicas if you need more throughput. (`uvicorn ... --workers N` is also an option, but each worker keeps its own in-memory cache; horizontal scaling via separate containers is usually a better fit.)

### Health checks

- `GET /healthz` — static liveness probe, never hits upstream.
- `GET /healthz/ready` — pings Onionoo (`summary?limit=1`); 200 when reachable, 503 otherwise. Result is cached for `HEALTHZ_READY_CACHE_SECONDS`.

### Request tracing

Every request is assigned an `X-Request-ID`. Clients may supply one to correlate across systems; the same value is echoed back on the response and bound into every log record produced during the request.

### Metrics

`/metrics` exposes Prometheus-format counters / histograms, including:

- `onionoo_cache_hits_total`, `onionoo_cache_misses_total`
- `onionoo_upstream_seconds{method=...}` (histogram)
- `onionoo_upstream_errors_total{method=..., status=...}`
- Standard `http_request_duration_seconds` from the FastAPI instrumentator

### Raw passthrough

For large payloads (`/v1/details`), pass `?raw=true` to skip Pydantic re-validation and forward the upstream JSON verbatim. Trade-off: raw mode does **not** apply semantic key remapping (e.g. on `/v1/summary` you'll see `n,f,a,r` rather than `nickname,fingerprint,addresses,running`) and **no `_meta` block is injected**.

### Response metadata (`_meta`)

Non-raw responses on `/v1/*` include a proxy-injected `_meta` block at the top of the envelope:

```json
{
  "_meta": {
    "cache_age_seconds": 12.345,
    "upstream_last_modified": "Thu, 15 May 2026 12:00:00 GMT"
  },
  "version": "9.0",
  ...
}
```

`cache_age_seconds = 0.0` means the response was just fetched from Onionoo. A non-zero value means the proxy served it from its in-memory cache.

### Trimming payloads with `fields=`

All `/v1/*` endpoints accept `?fields=a,b,c`. On `/summary` and `/details` Onionoo applies the projection at the upstream level; on history endpoints (bandwidth, weights, clients, uptime) Onionoo applies it where supported. Using it on large queries can shrink LLM input by an order of magnitude.

## Use as an MCP server

This project ships an [MCP](https://modelcontextprotocol.io) server with two
transports — pick whichever fits your client.

### Tools

**Task-oriented (recommended for agents)**

- `find_relay(query)` — free-form lookup; auto-detects fingerprint, AS, IP, or nickname
- `get_relay_health(fingerprint)` — composite snapshot (details + uptime + bandwidth)
- `top_relays_by_bandwidth(country?, flag?, limit)` — top-N by consensus weight
- `compare_relays(fingerprints)` — parallel side-by-side details
- `country_summary(country)` — running relay count, total bandwidth, flag distribution

**Low-level pass-through (raw Onionoo endpoints)**

- `onionoo_summary`, `onionoo_details`, `onionoo_bandwidth`, `onionoo_weights`,
  `onionoo_clients`, `onionoo_uptime` — each takes a `params` dict matching the
  [Onionoo query spec](https://metrics.torproject.org/onionoo.html).

**Aggregates**

- `aggregate_relays(group_by="country"|"as"|"flag", running=True, top=N)` — server-side group-by, sorted by relay count.

> Streamable HTTP `/mcp` exposes the six low-level endpoints (`get_summary` …
> `get_uptime`) plus the three aggregate endpoints (`aggregate_countries`,
> `aggregate_as`, `aggregate_flags`). The task-oriented tools and the unified
> `aggregate_relays` live in the stdio server. Both transports can run side by side.

### Streamable HTTP transport (recommended for hosted use)

Run the FastAPI app — `/mcp` is mounted automatically.

Inspect with MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL: http://localhost:8000/mcp
```

Claude Desktop / Cursor:

```json
{
  "mcpServers": {
    "onionoo": {
      "type": "http",
      "url": "https://onionoo.anoni.net/mcp"
    }
  }
}
```

### stdio transport (recommended for local agents)

`uv sync` installs an `onionoo-mcp` console script:

```bash
onionoo-mcp
```

Claude Desktop / Cursor:

```json
{
  "mcpServers": {
    "onionoo": {
      "command": "uvx",
      "args": ["--from", "/path/to/onionoo-fastapi", "onionoo-mcp"]
    }
  }
}
```

Or, if the repo is checked out and you have `uv`:

```json
{
  "mcpServers": {
    "onionoo": {
      "command": "uv",
      "args": ["--directory", "/path/to/onionoo-fastapi", "run", "onionoo-mcp"]
    }
  }
}
```

