onionoo-fastapi 1.0.0__py3-none-any.whl

app/__init__.py

@@ -0,0 +1 @@
+"""onionoo-fastapi package."""

app/main.py

@@ -0,0 +1,151 @@
+from contextlib import asynccontextmanager
+from time import monotonic
+
+import httpx
+from fastapi import FastAPI, Request, Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.middleware.gzip import GZipMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.routing import APIRoute
+from fastapi_mcp import FastApiMCP
+from prometheus_fastapi_instrumentator import Instrumentator
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from app.observability import RequestIdMiddleware, configure_logging, logger
+from app.routers import aggregate, bandwidth, clients, details, summary, uptime, weights
+from app.services.onionoo_client import OnionooClient, UpstreamError
+from app.settings import settings
+
+
+def create_app() -> FastAPI:
+    configure_logging()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        app.state.onionoo = OnionooClient()
+        app.state.ready_cache = {"checked_at": 0.0, "ok": False, "detail": ""}
+        logger.info("app.startup", base_url=settings.onionoo_base_url)
+        try:
+            yield
+        finally:
+            await app.state.onionoo.aclose()
+            logger.info("app.shutdown")
+
+    app = FastAPI(
+        title="Onionoo FastAPI Proxy",
+        version="1.0.0",
+        description="Semantic/OpenAPI proxy for Tor Onionoo (data is fetched from Onionoo upstream).",
+        lifespan=lifespan,
+    )
+
+    # Order matters: request-id should wrap everything; CORS before GZip.
+    app.add_middleware(RequestIdMiddleware)
+    if settings.cors_allowed_origins:
+        app.add_middleware(
+            CORSMiddleware,
+            allow_origins=settings.cors_allowed_origins,
+            allow_methods=["GET", "OPTIONS"],
+            allow_headers=["*"],
+            expose_headers=["X-Request-ID", "Last-Modified"],
+            allow_credentials=False,
+        )
+    app.add_middleware(GZipMiddleware, minimum_size=1000)
+
+    # The limiter is always constructed so `@limiter.exempt` decorators on the
+    # health endpoints remain valid even when rate limiting is toggled off.
+    # SlowAPIMiddleware is what actually enforces `default_limits`; without it
+    # the limiter object is inert.
+    limiter = Limiter(
+        key_func=get_remote_address,
+        default_limits=[f"{settings.rate_limit_per_minute}/minute"],
+    )
+    app.state.limiter = limiter
+    if settings.rate_limit_enabled:
+        from slowapi.middleware import SlowAPIMiddleware
+
+        app.add_middleware(SlowAPIMiddleware)
+
+    if settings.metrics_enabled:
+        Instrumentator().instrument(app).expose(app, endpoint="/metrics", tags=["health"])
+        # Prometheus scrapes shouldn't compete with end-user traffic for the
+        # per-IP rate budget. Mark the route exempt regardless of toggle.
+        for route in app.routes:
+            if isinstance(route, APIRoute) and route.path == "/metrics":
+                limiter.exempt(route.endpoint)
+                break
+
+    @app.get("/healthz", tags=["health"], summary="Liveness probe (static)")
+    @limiter.exempt
+    async def healthz() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.get("/healthz/ready", tags=["health"], summary="Readiness probe (pings upstream)")
+    @limiter.exempt
+    async def healthz_ready(request: Request) -> Response:
+        cache = request.app.state.ready_cache
+        now = monotonic()
+        if now - cache["checked_at"] < settings.healthz_ready_cache_seconds and cache["checked_at"]:
+            payload = {"status": "ok" if cache["ok"] else "degraded", "detail": cache["detail"]}
+            status = 200 if cache["ok"] else 503
+            return JSONResponse(status_code=status, content=payload)
+
+        client: OnionooClient = request.app.state.onionoo
+        try:
+            # Bypass the response cache: a cached 200 can mask a live outage.
+            await client.ping()
+            cache["ok"] = True
+            cache["detail"] = "upstream reachable"
+        except (UpstreamError, httpx.RequestError) as exc:
+            cache["ok"] = False
+            cache["detail"] = f"upstream unreachable: {exc}"
+        cache["checked_at"] = now
+
+        payload = {"status": "ok" if cache["ok"] else "degraded", "detail": cache["detail"]}
+        return JSONResponse(status_code=200 if cache["ok"] else 503, content=payload)
+
+    @app.exception_handler(UpstreamError)
+    async def upstream_error_handler(_request: Request, exc: UpstreamError) -> Response:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "error": "upstream_error",
+                "upstream_status": exc.status_code,
+                "upstream_body": exc.body,
+            },
+        )
+
+    @app.exception_handler(httpx.RequestError)
+    async def httpx_error_handler(_request: Request, exc: httpx.RequestError) -> Response:
+        return JSONResponse(
+            status_code=502,
+            content={
+                "error": "bad_gateway",
+                "message": str(exc),
+            },
+        )
+
+    app.include_router(summary.router, prefix="/v1", tags=["onionoo"])
+    app.include_router(details.router, prefix="/v1", tags=["onionoo"])
+    app.include_router(bandwidth.router, prefix="/v1", tags=["onionoo"])
+    app.include_router(weights.router, prefix="/v1", tags=["onionoo"])
+    app.include_router(clients.router, prefix="/v1", tags=["onionoo"])
+    app.include_router(uptime.router, prefix="/v1", tags=["onionoo"])
+    app.include_router(aggregate.router, prefix="/v1", tags=["aggregate"])
+
+    mcp = FastApiMCP(
+        app,
+        name="Onionoo MCP",
+        description=(
+            "Tor Onionoo data exposed as MCP tools. Read-only proxy: each tool wraps an "
+            "Onionoo endpoint (summary, details, bandwidth, weights, clients, uptime) and "
+            "accepts the same query parameters as the Onionoo spec."
+        ),
+        include_tags=["onionoo", "aggregate"],
+    )
+    mcp.mount_http()
+
+    return app
+
+
+app = create_app()

app/mcp_stdio.py

@@ -0,0 +1,189 @@
+"""Stdio MCP server entry point — `onionoo-mcp` console script.
+
+Exposes both the six low-level Onionoo endpoints (`onionoo_summary`, ...,
+`onionoo_uptime`) AND the high-level task-oriented tools defined in
+`app.mcp_tools` (find_relay, get_relay_health, top_relays_by_bandwidth,
+compare_relays, country_summary).
+
+Use this when you want an MCP-native client like Claude Desktop or Cursor to
+spawn a local subprocess and talk to it over stdio. For Streamable HTTP, run
+the FastAPI app instead and connect to `/mcp`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+
+from app.mcp_tools import (
+    aggregate_relays,
+    compare_relays,
+    country_summary,
+    find_relay,
+    get_relay_health,
+    top_relays_by_bandwidth,
+)
+from app.services.onionoo_client import OnionooClient
+
+_INSTRUCTIONS = """\
+This server wraps the Tor Onionoo API. Use the high-level tools first:
+- `find_relay` for free-form discovery
+- `get_relay_health` for a single relay's status snapshot
+- `top_relays_by_bandwidth` for ranking
+- `compare_relays` for side-by-side
+- `country_summary` for aggregates
+
+Drop down to the low-level tools (onionoo_summary, onionoo_details, ...) when
+you need raw Onionoo response shapes or filters that aren't covered above.
+"""
+
+
+def build_server() -> tuple[FastMCP, OnionooClient]:
+    """Build (but do not run) the stdio MCP server, wired to a fresh OnionooClient.
+
+    Returns the server alongside its client so the entry point can call
+    `client.aclose()` on shutdown without poking at private FastMCP state.
+    """
+    server = FastMCP("onionoo-mcp", instructions=_INSTRUCTIONS)
+    client = OnionooClient()
+
+    # --- High-level tools ----------------------------------------------------
+
+    @server.tool(
+        name="find_relay",
+        description=(
+            "Find Tor relays or bridges by free-form query. Auto-detects whether the "
+            "query is a 40-hex fingerprint (uses lookup), an AS number like 'AS3' "
+            "(uses as filter), an IP address (uses search), or otherwise a "
+            "nickname/substring (uses search). Returns a compact list with nickname, "
+            "fingerprint, country, AS, flags, and addresses."
+        ),
+    )
+    async def _find_relay(query: str, limit: int = 10) -> dict[str, Any]:
+        return await find_relay(client, query, limit=limit)
+
+    @server.tool(
+        name="get_relay_health",
+        description=(
+            "Snapshot the health of one relay: details (flags, country, AS, version, "
+            "advertised bandwidth) plus the available uptime and bandwidth history "
+            "periods. Requires a 40-hex relay fingerprint."
+        ),
+    )
+    async def _get_relay_health(fingerprint: str) -> dict[str, Any]:
+        return await get_relay_health(client, fingerprint)
+
+    @server.tool(
+        name="top_relays_by_bandwidth",
+        description=(
+            "List the top N running relays sorted by consensus weight. Optional "
+            "filters: country (two-letter code), flag (e.g. Exit, Guard, Fast). "
+            "Returns minimal fields suitable for ranking."
+        ),
+    )
+    async def _top_relays_by_bandwidth(
+        country: str | None = None,
+        flag: str | None = None,
+        limit: int = 10,
+    ) -> dict[str, Any]:
+        return await top_relays_by_bandwidth(client, country=country, flag=flag, limit=limit)
+
+    @server.tool(
+        name="compare_relays",
+        description=(
+            "Compare several relays side-by-side by fetching their details in parallel. "
+            "Pass a list of 40-hex fingerprints. Missing relays are reported with "
+            "found=False rather than silently dropped."
+        ),
+    )
+    async def _compare_relays(fingerprints: list[str]) -> dict[str, Any]:
+        return await compare_relays(client, fingerprints)
+
+    @server.tool(
+        name="country_summary",
+        description=(
+            "Aggregate stats for running relays in one country: total count, "
+            "total advertised bandwidth, total consensus weight, and a flag "
+            "distribution histogram. Country is a two-letter ISO code."
+        ),
+    )
+    async def _country_summary(country: str) -> dict[str, Any]:
+        return await country_summary(client, country)
+
+    @server.tool(
+        name="aggregate_relays",
+        description=(
+            "Group all running Tor relays by country, AS, or flag. Returns "
+            "buckets sorted by relay count (desc) with totals for advertised "
+            "bandwidth and consensus weight. Use group_by='flags' to discover "
+            "which roles dominate (Guard/Exit/Fast) — note a relay can belong "
+            "to multiple flag buckets. Set top=N to keep only the largest N. "
+            "The label set matches the REST endpoints /v1/aggregate/{countries,as,flags}."
+        ),
+    )
+    async def _aggregate_relays(
+        group_by: Literal["countries", "as", "flags"],
+        running: bool = True,
+        top: int | None = None,
+    ) -> dict[str, Any]:
+        return await aggregate_relays(client, group_by=group_by, running=running, top=top)
+
+    # --- Low-level Onionoo passthrough --------------------------------------
+
+    def _make_passthrough(method: str, description: str):
+        @server.tool(name=f"onionoo_{method}", description=description)
+        async def _passthrough(params: dict[str, Any] | None = None) -> dict[str, Any]:
+            resp = await client.get(method=method, params=params or {}, if_modified_since=None)
+            return {"status_code": resp.status_code, "body": resp.json_body}
+
+        return _passthrough
+
+    _make_passthrough(
+        "summary",
+        "Raw Onionoo /summary: lightweight relay/bridge list. Pass Onionoo query "
+        "parameters as a dict (e.g. {'search': 'moria', 'limit': '1'}). See "
+        "https://metrics.torproject.org/onionoo.html",
+    )
+    _make_passthrough(
+        "details",
+        "Raw Onionoo /details: full attributes (flags, AS, country, contact, …). "
+        "Pass a params dict (e.g. {'lookup': '<40-hex fp>'}). Supports `fields=` "
+        "to trim response. See https://metrics.torproject.org/onionoo.html",
+    )
+    _make_passthrough(
+        "bandwidth",
+        "Raw Onionoo /bandwidth: bandwidth time series for relays and bridges.",
+    )
+    _make_passthrough(
+        "weights",
+        "Raw Onionoo /weights: consensus weight / path-selection probability "
+        "time series (relays only).",
+    )
+    _make_passthrough(
+        "clients",
+        "Raw Onionoo /clients: estimated daily client counts (bridges only).",
+    )
+    _make_passthrough(
+        "uptime",
+        "Raw Onionoo /uptime: fractional uptime time series.",
+    )
+
+    return server, client
+
+
+async def _run_async() -> None:
+    server, client = build_server()
+    try:
+        await server.run_stdio_async()
+    finally:
+        await client.aclose()
+
+
+def main() -> None:
+    asyncio.run(_run_async())
+
+
+if __name__ == "__main__":
+    main()

app/mcp_tools.py

@@ -0,0 +1,273 @@
+"""High-level, task-oriented MCP tools.
+
+Each function composes one or more Onionoo endpoints into an LLM-friendly result.
+These are *not* thin REST wrappers — they pick the right endpoint, fan out
+requests in parallel, and aggregate. Use them when an agent should accomplish
+a goal ("how healthy is this relay?") in a single tool call.
+
+All tools operate against an injected `OnionooClient` so they can be tested
+without network access via respx.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import re
+from typing import Any, Literal
+
+from app.services.aggregate import aggregate_details
+from app.services.onionoo_client import OnionooClient, UpstreamError
+
+FINGERPRINT_RE = re.compile(r"^[0-9a-fA-F]{40}$")
+AS_RE = re.compile(r"^AS\d+$", re.IGNORECASE)
+
+
+def _looks_like_fingerprint(query: str) -> bool:
+    return bool(FINGERPRINT_RE.match(query.strip()))
+
+
+def _looks_like_as(query: str) -> bool:
+    return bool(AS_RE.match(query.strip()))
+
+
+async def find_relay(client: OnionooClient, query: str, *, limit: int = 10) -> dict[str, Any]:
+    """Find relays/bridges by free-form query.
+
+    Auto-detects whether `query` is a 40-hex fingerprint (uses lookup), an IPv4/IPv6
+    address (uses search), an AS number (uses as filter), or otherwise a nickname/
+    substring (uses search). Returns a compact list of matches.
+    """
+    q = query.strip()
+    params: dict[str, Any] = {"limit": str(limit)}
+
+    if _looks_like_fingerprint(q):
+        params["lookup"] = q.upper()
+    elif _looks_like_as(q):
+        params["as"] = q.upper()
+    else:
+        params["search"] = q
+
+    resp = await client.get(method="details", params=params, if_modified_since=None)
+    body = resp.json_body or {}
+
+    def _shape(item: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "nickname": item.get("nickname"),
+            "fingerprint": item.get("fingerprint") or item.get("hashed_fingerprint"),
+            "running": item.get("running"),
+            "country": item.get("country"),
+            "as": item.get("as"),
+            "flags": item.get("flags"),
+            "or_addresses": item.get("or_addresses"),
+        }
+
+    return {
+        "query": q,
+        "matched_via": "lookup" if "lookup" in params else "as" if "as" in params else "search",
+        "relays": [_shape(r) for r in body.get("relays", [])],
+        "bridges": [_shape(b) for b in body.get("bridges", [])],
+    }
+
+
+async def get_relay_health(client: OnionooClient, fingerprint: str) -> dict[str, Any]:
+    """Composite health snapshot for a single relay: details + uptime + bandwidth.
+
+    Fires three Onionoo queries in parallel and condenses the response into a
+    short, LLM-readable dict. Raises UpstreamError if any sub-fetch fails.
+    """
+    fp = fingerprint.strip().upper()
+    if not _looks_like_fingerprint(fp):
+        raise ValueError(f"fingerprint must be 40 hex chars, got {fingerprint!r}")
+
+    params = {"lookup": fp, "limit": "1"}
+
+    details_resp, uptime_resp, bandwidth_resp = await asyncio.gather(
+        client.get(method="details", params=params, if_modified_since=None),
+        client.get(method="uptime", params=params, if_modified_since=None),
+        client.get(method="bandwidth", params=params, if_modified_since=None),
+    )
+
+    relays = (details_resp.json_body or {}).get("relays", [])
+    if not relays:
+        return {"fingerprint": fp, "found": False}
+
+    relay = relays[0]
+    uptime = ((uptime_resp.json_body or {}).get("relays") or [{}])[0]
+    bw = ((bandwidth_resp.json_body or {}).get("relays") or [{}])[0]
+
+    return {
+        "fingerprint": fp,
+        "found": True,
+        "nickname": relay.get("nickname"),
+        "running": relay.get("running"),
+        "country": relay.get("country"),
+        "as": relay.get("as"),
+        "as_name": relay.get("as_name"),
+        "flags": relay.get("flags"),
+        "first_seen": relay.get("first_seen"),
+        "last_seen": relay.get("last_seen"),
+        "advertised_bandwidth": relay.get("advertised_bandwidth"),
+        "consensus_weight": relay.get("consensus_weight"),
+        "version": relay.get("version"),
+        "recommended_version": relay.get("recommended_version"),
+        "uptime_periods": sorted((uptime.get("uptime") or {}).keys()),
+        "bandwidth_periods": {
+            "read": sorted((bw.get("read_history") or {}).keys()),
+            "write": sorted((bw.get("write_history") or {}).keys()),
+        },
+    }
+
+
+async def top_relays_by_bandwidth(
+    client: OnionooClient,
+    *,
+    country: str | None = None,
+    flag: str | None = None,
+    limit: int = 10,
+) -> dict[str, Any]:
+    """Return the top N running relays by consensus weight, optionally filtered.
+
+    Onionoo's `order=-consensus_weight` puts the highest-weight relays first.
+    """
+    params: dict[str, Any] = {
+        "running": "true",
+        "order": "-consensus_weight",
+        "limit": str(limit),
+        "fields": ",".join(
+            [
+                "nickname",
+                "fingerprint",
+                "country",
+                "as",
+                "as_name",
+                "flags",
+                "advertised_bandwidth",
+                "consensus_weight",
+                "consensus_weight_fraction",
+            ]
+        ),
+    }
+    if country:
+        params["country"] = country
+    if flag:
+        params["flag"] = flag
+
+    resp = await client.get(method="details", params=params, if_modified_since=None)
+    relays = (resp.json_body or {}).get("relays", [])
+    return {
+        "country": country,
+        "flag": flag,
+        "count": len(relays),
+        "relays": relays,
+    }
+
+
+async def compare_relays(client: OnionooClient, fingerprints: list[str]) -> dict[str, Any]:
+    """Fetch details for several fingerprints in parallel and return a comparison.
+
+    Each fingerprint becomes one Onionoo lookup; missing relays are reported
+    rather than dropped.
+    """
+    if not fingerprints:
+        return {"relays": []}
+
+    normalized = [fp.strip().upper() for fp in fingerprints]
+    for fp in normalized:
+        if not _looks_like_fingerprint(fp):
+            raise ValueError(f"invalid fingerprint: {fp!r}")
+
+    async def _one(fp: str) -> dict[str, Any]:
+        try:
+            r = await client.get(
+                method="details",
+                params={"lookup": fp, "limit": "1"},
+                if_modified_since=None,
+            )
+        except UpstreamError as exc:
+            return {"fingerprint": fp, "found": False, "error": str(exc)}
+        relays = (r.json_body or {}).get("relays", [])
+        if not relays:
+            return {"fingerprint": fp, "found": False}
+        relay = relays[0]
+        return {
+            "fingerprint": fp,
+            "found": True,
+            "nickname": relay.get("nickname"),
+            "running": relay.get("running"),
+            "country": relay.get("country"),
+            "as": relay.get("as"),
+            "flags": relay.get("flags"),
+            "advertised_bandwidth": relay.get("advertised_bandwidth"),
+            "consensus_weight": relay.get("consensus_weight"),
+            "version": relay.get("version"),
+        }
+
+    rows = await asyncio.gather(*[_one(fp) for fp in normalized])
+    return {"relays": rows}
+
+
+async def country_summary(client: OnionooClient, country: str) -> dict[str, Any]:
+    """Aggregate Tor relays for one country: total count, flag distribution, weight.
+
+    Pulls a single Onionoo /details query with country filter (up to MAX_LIMIT
+    relays) and computes counts client-side.
+    """
+    country_code = country.strip().lower()
+    params = {
+        "country": country_code,
+        "running": "true",
+        "limit": "200",
+        "fields": "fingerprint,nickname,flags,advertised_bandwidth,consensus_weight",
+    }
+    resp = await client.get(method="details", params=params, if_modified_since=None)
+    body = resp.json_body or {}
+    relays = body.get("relays", [])
+
+    total_advertised_bw = 0
+    total_weight = 0
+    flag_counts: dict[str, int] = {}
+    for relay in relays:
+        total_advertised_bw += int(relay.get("advertised_bandwidth") or 0)
+        total_weight += int(relay.get("consensus_weight") or 0)
+        for f in relay.get("flags") or []:
+            flag_counts[f] = flag_counts.get(f, 0) + 1
+
+    return {
+        "country": country_code,
+        "running_relay_count": len(relays),
+        "truncated": body.get("relays_truncated"),
+        "total_advertised_bandwidth_bps": total_advertised_bw,
+        "total_consensus_weight": total_weight,
+        "flag_counts": dict(sorted(flag_counts.items(), key=lambda kv: kv[1], reverse=True)),
+    }
+
+
+_AGGREGATE_GROUP_BY_ALIASES = {
+    "countries": "country",
+    "country": "country",
+    "as": "as",
+    "flags": "flag",
+    "flag": "flag",
+}
+
+
+async def aggregate_relays(
+    client: OnionooClient,
+    *,
+    group_by: Literal["countries", "as", "flags"],
+    running: bool = True,
+    top: int | None = None,
+) -> dict[str, Any]:
+    """Group all running Tor relays by country / AS / flag.
+
+    Thin wrapper over `app.services.aggregate.aggregate_details`. The public
+    label set (`countries`/`as`/`flags`) matches the REST endpoint paths
+    (`/v1/aggregate/{countries,as,flags}`); singular forms remain accepted for
+    backwards compatibility with the original tool signature.
+    """
+    internal = _AGGREGATE_GROUP_BY_ALIASES.get(group_by)
+    if internal is None:
+        raise ValueError(
+            f"group_by must be one of {sorted(_AGGREGATE_GROUP_BY_ALIASES)}, got {group_by!r}"
+        )
+    return await aggregate_details(client, group_by=internal, running=running, limit=top)

app/models/__init__.py

@@ -0,0 +1 @@
+"""Pydantic models for API responses."""