content-gateway-client 0.1.0__tar.gz

content_gateway_client-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Rust
+/target
+/build
+
+# Node
+node_modules
+.pnpm-store
+*.log
+dist
+*.tsbuildinfo
+
+# Python
+.venv
+__pycache__
+*.egg-info
+.pytest_cache
+.mypy_cache
+.ruff_cache
+
+# Env
+.env
+.env.*
+!.env.example
+
+# Editors and tools
+.vscode/*
+!.vscode/extensions.json
+.idea
+.claude
+.cursor
+.DS_Store

content_gateway_client-0.1.0/CHANGELOG.md

@@ -0,0 +1,5 @@
+# content-gateway-client
+
+## 0.1.0
+
+First release: the gateway's routes typed from its OpenAPI document, a sync and an async client for the CurseForge and Modrinth passthroughs with the gateway's refusals handled, `resolve`, the Minecraft and loader version lists, and `modrinth_file_url`.

content_gateway_client-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: content-gateway-client
+Version: 0.1.0
+Summary: Typed client for content-gateway: the gateway's own routes from its OpenAPI document and the CurseForge and Modrinth passthroughs with the budget's refusals handled.
+Project-URL: Repository, https://github.com/matejhozlar/createrington-content-gateway
+Project-URL: Changelog, https://github.com/matejhozlar/createrington-content-gateway/blob/main/packages/python-client/CHANGELOG.md
+License-Expression: MIT
+Keywords: api-client,curseforge,minecraft,modrinth
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.28
+Description-Content-Type: text/markdown
+
+# content-gateway-client
+
+The Python client of [content-gateway](../../README.md): the gateway's own routes typed from its OpenAPI document, and the CurseForge and Modrinth passthroughs with the gateway's refusals handled. Sync and async, on [httpx](https://www.python-httpx.org/).
+
+```bash
+pip install content-gateway-client
+```
+
+Python 3.11 or newer.
+
+## Usage
+
+```python
+from content_gateway import ContentGateway, ContentGatewayError
+
+with ContentGateway("http://127.0.0.1:5005", token=TOKEN, pool="app") as gateway:
+    answer = gateway.curseforge(
+        "mods/search", query={"gameId": 432, "searchFilter": "jei", "classId": 6}
+    )
+    if not answer.ok:
+        raise RuntimeError(f"CurseForge answered {answer.status}")
+    for mod in answer.body["data"]:
+        print(mod["id"], mod["name"])
+```
+
+`curseforge(path, ...)` sends `api.curseforge.com/v1/<path>` through the gateway and answers whatever CurseForge answered as a `PassthroughAnswer`: `status`, `ok`, `body` (parsed JSON, the text when it is not JSON, `None` when empty), `headers`, and `cache`, which is `hit`, `miss` or `stale` from the gateway's `X-Cache`. A `body` makes the request a `POST`; `fresh=True` asks CurseForge again instead of the cache; `pool` draws from another of the token's pools. `query` values of `None` are left out.
+
+Only the gateway's own answers raise, as `ContentGatewayError` with the gateway's `code` (`BUDGET_SPENT`, `UPSTREAM_HOLD`, `UNAUTHORIZED`, ...), `status`, `pool` and `retry_after_ms`. `code` is `None` when the answer was not the gateway's JSON error at all, such as a proxy's HTML page.
+
+`modrinth(path, ...)` sends `api.modrinth.com/v2/<path>` through the gateway the same way; the calls draw from the pool's Modrinth budget. `modrinth_version_file(sha1)` and `modrinth_version_files(hashes)` are the two SHA-1 lookups, and `modrinth_file_url(version, sha1)` picks the address of the file itself on Modrinth's CDN out of a version.
+
+`resolve(file_ids, cdn=True, pool=None, fresh=False, wait_up_to=None, timeout=60)` reads `/v1/resolve`: a download address per CurseForge file, from CurseForge's own link, else Modrinth's copy of the file found by SHA-1, else the file's built address on CurseForge's CDN when it answers a HEAD with the file's size (`cdn=False` skips that step). A file with a `source` of `None` and `retry` true could not be fully checked this time. The consumer downloads from the address itself; no bytes pass through the gateway. The gateway tries the three sources in a row, so a call can take 40 s at worst; `resolve()` therefore waits 60 s rather than the client's timeout.
+
+`minecraft_versions(type=None, loader=None)`, `minecraft_version(id)` and `loader_versions(loader, minecraft=None)` read `/v1/minecraft/*`: Mojang's version list (releases by default, narrowed to what a loader builds for), one version with the Java major it needs, and a loader's builds (NeoForge, Forge, Fabric) with `stable` and `recommended` flags.
+
+`health()` reads `/v1/healthz` and `budget(days=None)` reads `/v1/budget`, one `UpstreamBudget` for CurseForge and one for Modrinth with the last `days` UTC days of counts (14 when left out, more than the gateway's `historyDays` answers the days kept).
+
+The gateway's own answers are plain dicts typed as `TypedDict`s generated from `openapi.json` (`Health`, `BudgetSnapshot`, `Resolved`, `MinecraftVersions`, ...), so a type checker knows their keys. The passthrough bodies are CurseForge's and Modrinth's JSON as it came, typed `Any`.
+
+### Async
+
+`AsyncContentGateway` has the same methods as coroutines, on `httpx.AsyncClient`:
+
+```python
+from content_gateway import AsyncContentGateway
+
+async with AsyncContentGateway("http://127.0.0.1:5005", token=TOKEN) as gateway:
+    health = await gateway.health()
+```
+
+### Waiting out a refusal
+
+A refused call answers `503` with `Retry-After`. A background job can sleep it out:
+
+```python
+answer = gateway.curseforge("mods", body={"modIds": mod_ids}, wait_up_to=300)
+```
+
+The call is sent again after each refusal that fits in what is left of `wait_up_to` seconds; one that does not fit raises at once. A request answering a user should leave it unset and pass the `retry_after_ms` on.
+
+### Timeouts and connections
+
+`timeout`, 15 s by default, is httpx's limit on each phase of a request (connecting, waiting for a read, a write), not on the whole call; the gateway answers in one body, so a call ends within it in practice. The gateway gives CurseForge 10 s before it answers `504` or a stale answer, so keep the client's timeout above that: a stalled call then comes back as the gateway's answer instead of an `httpx.TimeoutException` here. The client keeps connections to the gateway open between calls; pass your own `httpx.Client` or `httpx.AsyncClient` as `client` to change that or to test (an `httpx.MockTransport` makes a fake gateway).
+
+## Development
+
+```bash
+uv sync                     # the virtual environment with the dev tools
+uv run pytest
+uv run mypy
+uv run ruff check . && uv run ruff format --check .
+uv run python scripts/generate.py          # rewrite src/content_gateway/generated.py from openapi.json
+uv run python scripts/generate.py --check  # fail when it is stale
+```
+
+`src/content_gateway/generated.py` is generated from the gateway's `openapi.json` with [datamodel-code-generator](https://koxudaxi.github.io/datamodel-code-generator/) and checked in; `pnpm openapi` at the repository root regenerates it with the TypeScript types, and CI fails when it is stale. Never edit it by hand.
+
+The version lives in `pyproject.toml` and `CHANGELOG.md` holds its entries. A release tag of the gateway publishes the package to PyPI when that version is not there yet, through PyPI's trusted publishing from the release workflow, so the PyPI project trusts `release.yml` of the GitHub repository and no token is stored anywhere.

content_gateway_client-0.1.0/README.md

@@ -0,0 +1,78 @@
+# content-gateway-client
+
+The Python client of [content-gateway](../../README.md): the gateway's own routes typed from its OpenAPI document, and the CurseForge and Modrinth passthroughs with the gateway's refusals handled. Sync and async, on [httpx](https://www.python-httpx.org/).
+
+```bash
+pip install content-gateway-client
+```
+
+Python 3.11 or newer.
+
+## Usage
+
+```python
+from content_gateway import ContentGateway, ContentGatewayError
+
+with ContentGateway("http://127.0.0.1:5005", token=TOKEN, pool="app") as gateway:
+    answer = gateway.curseforge(
+        "mods/search", query={"gameId": 432, "searchFilter": "jei", "classId": 6}
+    )
+    if not answer.ok:
+        raise RuntimeError(f"CurseForge answered {answer.status}")
+    for mod in answer.body["data"]:
+        print(mod["id"], mod["name"])
+```
+
+`curseforge(path, ...)` sends `api.curseforge.com/v1/<path>` through the gateway and answers whatever CurseForge answered as a `PassthroughAnswer`: `status`, `ok`, `body` (parsed JSON, the text when it is not JSON, `None` when empty), `headers`, and `cache`, which is `hit`, `miss` or `stale` from the gateway's `X-Cache`. A `body` makes the request a `POST`; `fresh=True` asks CurseForge again instead of the cache; `pool` draws from another of the token's pools. `query` values of `None` are left out.
+
+Only the gateway's own answers raise, as `ContentGatewayError` with the gateway's `code` (`BUDGET_SPENT`, `UPSTREAM_HOLD`, `UNAUTHORIZED`, ...), `status`, `pool` and `retry_after_ms`. `code` is `None` when the answer was not the gateway's JSON error at all, such as a proxy's HTML page.
+
+`modrinth(path, ...)` sends `api.modrinth.com/v2/<path>` through the gateway the same way; the calls draw from the pool's Modrinth budget. `modrinth_version_file(sha1)` and `modrinth_version_files(hashes)` are the two SHA-1 lookups, and `modrinth_file_url(version, sha1)` picks the address of the file itself on Modrinth's CDN out of a version.
+
+`resolve(file_ids, cdn=True, pool=None, fresh=False, wait_up_to=None, timeout=60)` reads `/v1/resolve`: a download address per CurseForge file, from CurseForge's own link, else Modrinth's copy of the file found by SHA-1, else the file's built address on CurseForge's CDN when it answers a HEAD with the file's size (`cdn=False` skips that step). A file with a `source` of `None` and `retry` true could not be fully checked this time. The consumer downloads from the address itself; no bytes pass through the gateway. The gateway tries the three sources in a row, so a call can take 40 s at worst; `resolve()` therefore waits 60 s rather than the client's timeout.
+
+`minecraft_versions(type=None, loader=None)`, `minecraft_version(id)` and `loader_versions(loader, minecraft=None)` read `/v1/minecraft/*`: Mojang's version list (releases by default, narrowed to what a loader builds for), one version with the Java major it needs, and a loader's builds (NeoForge, Forge, Fabric) with `stable` and `recommended` flags.
+
+`health()` reads `/v1/healthz` and `budget(days=None)` reads `/v1/budget`, one `UpstreamBudget` for CurseForge and one for Modrinth with the last `days` UTC days of counts (14 when left out, more than the gateway's `historyDays` answers the days kept).
+
+The gateway's own answers are plain dicts typed as `TypedDict`s generated from `openapi.json` (`Health`, `BudgetSnapshot`, `Resolved`, `MinecraftVersions`, ...), so a type checker knows their keys. The passthrough bodies are CurseForge's and Modrinth's JSON as it came, typed `Any`.
+
+### Async
+
+`AsyncContentGateway` has the same methods as coroutines, on `httpx.AsyncClient`:
+
+```python
+from content_gateway import AsyncContentGateway
+
+async with AsyncContentGateway("http://127.0.0.1:5005", token=TOKEN) as gateway:
+    health = await gateway.health()
+```
+
+### Waiting out a refusal
+
+A refused call answers `503` with `Retry-After`. A background job can sleep it out:
+
+```python
+answer = gateway.curseforge("mods", body={"modIds": mod_ids}, wait_up_to=300)
+```
+
+The call is sent again after each refusal that fits in what is left of `wait_up_to` seconds; one that does not fit raises at once. A request answering a user should leave it unset and pass the `retry_after_ms` on.
+
+### Timeouts and connections
+
+`timeout`, 15 s by default, is httpx's limit on each phase of a request (connecting, waiting for a read, a write), not on the whole call; the gateway answers in one body, so a call ends within it in practice. The gateway gives CurseForge 10 s before it answers `504` or a stale answer, so keep the client's timeout above that: a stalled call then comes back as the gateway's answer instead of an `httpx.TimeoutException` here. The client keeps connections to the gateway open between calls; pass your own `httpx.Client` or `httpx.AsyncClient` as `client` to change that or to test (an `httpx.MockTransport` makes a fake gateway).
+
+## Development
+
+```bash
+uv sync                     # the virtual environment with the dev tools
+uv run pytest
+uv run mypy
+uv run ruff check . && uv run ruff format --check .
+uv run python scripts/generate.py          # rewrite src/content_gateway/generated.py from openapi.json
+uv run python scripts/generate.py --check  # fail when it is stale
+```
+
+`src/content_gateway/generated.py` is generated from the gateway's `openapi.json` with [datamodel-code-generator](https://koxudaxi.github.io/datamodel-code-generator/) and checked in; `pnpm openapi` at the repository root regenerates it with the TypeScript types, and CI fails when it is stale. Never edit it by hand.
+
+The version lives in `pyproject.toml` and `CHANGELOG.md` holds its entries. A release tag of the gateway publishes the package to PyPI when that version is not there yet, through PyPI's trusted publishing from the release workflow, so the PyPI project trusts `release.yml` of the GitHub repository and no token is stored anywhere.

content_gateway_client-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "content-gateway-client"
+version = "0.1.0"
+description = "Typed client for content-gateway: the gateway's own routes from its OpenAPI document and the CurseForge and Modrinth passthroughs with the budget's refusals handled."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.28,<1"]
+keywords = ["curseforge", "modrinth", "minecraft", "api-client"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Games/Entertainment",
+  "Topic :: Software Development :: Libraries",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/matejhozlar/createrington-content-gateway"
+Changelog = "https://github.com/matejhozlar/createrington-content-gateway/blob/main/packages/python-client/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling>=1.33"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/content_gateway"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/content_gateway", "README.md", "CHANGELOG.md"]
+
+[dependency-groups]
+dev = [
+  "anyio>=4.12",
+  "datamodel-code-generator>=0.89",
+  "mypy>=2.4",
+  "pytest>=9.2",
+  "ruff>=0.17",
+]
+
+[tool.uv]
+required-version = ">=0.13.7"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "RUF", "ANN", "PT"]
+ignore = ["ANN401", "E501"]
+
+[tool.ruff.lint.per-file-ignores]
+"src/content_gateway/generated.py" = ["I001"]
+
+[tool.mypy]
+strict = true
+files = ["src", "tests", "scripts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

content_gateway_client-0.1.0/src/content_gateway/__init__.py

@@ -0,0 +1,73 @@
+from .client import (
+    DEFAULT_TIMEOUT,
+    MODRINTH_CDN_HOST,
+    RESOLVE_TIMEOUT,
+    AsyncContentGateway,
+    CacheStatus,
+    ContentGateway,
+    ContentGatewayError,
+    Method,
+    PassthroughAnswer,
+    Query,
+    modrinth_file_url,
+)
+from .generated import (
+    ApiError,
+    BudgetSnapshot,
+    DayCounts,
+    DayPoolSnapshot,
+    DaySnapshot,
+    ErrorCode,
+    FileSource,
+    Health,
+    Latest,
+    Loader,
+    LoaderVersion,
+    LoaderVersions,
+    MinecraftVersion,
+    MinecraftVersionDetails,
+    MinecraftVersions,
+    PoolSnapshot,
+    Resolved,
+    ResolvedFile,
+    Source,
+    UpstreamBudget,
+    VersionFilter,
+    VersionType,
+)
+
+__all__ = [
+    "DEFAULT_TIMEOUT",
+    "MODRINTH_CDN_HOST",
+    "RESOLVE_TIMEOUT",
+    "ApiError",
+    "AsyncContentGateway",
+    "BudgetSnapshot",
+    "CacheStatus",
+    "ContentGateway",
+    "ContentGatewayError",
+    "DayCounts",
+    "DayPoolSnapshot",
+    "DaySnapshot",
+    "ErrorCode",
+    "FileSource",
+    "Health",
+    "Latest",
+    "Loader",
+    "LoaderVersion",
+    "LoaderVersions",
+    "Method",
+    "MinecraftVersion",
+    "MinecraftVersionDetails",
+    "MinecraftVersions",
+    "PassthroughAnswer",
+    "PoolSnapshot",
+    "Query",
+    "Resolved",
+    "ResolvedFile",
+    "Source",
+    "UpstreamBudget",
+    "VersionFilter",
+    "VersionType",
+    "modrinth_file_url",
+]

content_gateway_client-0.1.0/src/content_gateway/client.py

@@ -0,0 +1,623 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import time
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+from urllib.parse import quote, urlencode, urlsplit
+
+import httpx
+
+from .generated import (
+    ApiError,
+    BudgetSnapshot,
+    ErrorCode,
+    Health,
+    Loader,
+    LoaderVersions,
+    MinecraftVersionDetails,
+    MinecraftVersions,
+    Resolved,
+    VersionFilter,
+)
+
+DEFAULT_TIMEOUT = 15.0
+"""How long each phase of a request to the gateway may take (connecting, a read, a write), in seconds, above the 10 s it gives an upstream."""
+
+RESOLVE_TIMEOUT = 60.0
+"""The same for `resolve()` unless told otherwise, above the gateway's 40 s worst case."""
+
+MODRINTH_CDN_HOST = "cdn.modrinth.com"
+"""The host every Modrinth download address is on."""
+
+CacheStatus = Literal["hit", "miss", "stale"]
+"""How the gateway answered a passthrough call, from `X-Cache`."""
+
+Query = Mapping[str, str | int | float | bool | None]
+"""Query parameters; `None` values are left out and booleans become `true` or `false`."""
+
+Method = Literal["GET", "POST"]
+
+_CACHE_HEADER = "x-cache"
+_POOL_HEADER = "x-budget-pool"
+_CACHE_STATUSES: tuple[CacheStatus, ...] = ("hit", "miss", "stale")
+_JSON_TYPE = re.compile(r"\bjson\b", re.IGNORECASE)
+_SECONDS = re.compile(r"^\d+$")
+
+
+@dataclass(frozen=True, slots=True)
+class PassthroughAnswer:
+    """What an upstream (CurseForge or Modrinth) answered through the gateway."""
+
+    status: int
+    ok: bool
+    cache: CacheStatus
+    body: Any
+    headers: httpx.Headers
+
+
+class ContentGatewayError(Exception):
+    """An answer the gateway gave itself instead of passing one on; `code` is `None` when it was not the gateway's JSON error."""
+
+    status: int
+    code: ErrorCode | None
+    pool: str | None
+    retry_after_ms: int | None
+    message: str
+
+    def __init__(self, status: int, error: ApiError | None, fallback: str) -> None:
+        super().__init__(status, error, fallback)
+        self.message = error["message"] if error is not None else fallback
+        self.status = status
+        self.code = error["code"] if error is not None else None
+        self.pool = error.get("pool") if error is not None else None
+        self.retry_after_ms = error.get("retryAfterMs") if error is not None else None
+
+    def __str__(self) -> str:
+        return self.message
+
+
+@dataclass(frozen=True, slots=True)
+class _Request:
+    method: Method
+    path: str
+    query: Query | None = None
+    body: Any = None
+    authenticated: bool = True
+    pool: str | None = None
+    fresh: bool = False
+    wait_up_to: float | None = None
+    timeout: float | None = None
+
+
+_Outcome = tuple[Literal["done"], Any] | tuple[Literal["wait"], float]
+
+
+class _Gateway:
+    def __init__(self, base_url: str, token: str, pool: str | None, timeout: float) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._pool = pool
+        self._timeout = timeout
+
+    def _build(self, request: _Request) -> tuple[str, dict[str, str], bytes | None]:
+        url = self._base_url + request.path + _query_string(request.query)
+        headers = {"accept": "application/json"}
+        if request.authenticated:
+            headers["authorization"] = f"Bearer {self._token}"
+            pool = request.pool if request.pool is not None else self._pool
+            if pool is not None:
+                headers[_POOL_HEADER] = pool
+        if request.fresh:
+            headers["cache-control"] = "no-cache"
+        content: bytes | None = None
+        if request.body is not None:
+            headers["content-type"] = "application/json"
+            content = json.dumps(request.body).encode()
+        return url, headers, content
+
+    def _settle(self, request: _Request, response: httpx.Response, deadline: float) -> _Outcome:
+        body = _read_body(response)
+        if _CACHE_HEADER in response.headers or response.is_success:
+            return ("done", body)
+        error = _as_api_error(body)
+        wait = _retry_after(response, error)
+        if response.status_code == 503 and wait is not None and time.monotonic() + wait <= deadline:
+            return ("wait", wait)
+        fallback = f"the gateway answered {response.status_code} to {request.method} {request.path}"
+        if isinstance(body, str) and body != "":
+            fallback += f": {body}"
+        raise ContentGatewayError(response.status_code, error, fallback)
+
+    @staticmethod
+    def _passthrough_answer(
+        request: _Request, response: httpx.Response, body: Any
+    ) -> PassthroughAnswer:
+        cache = response.headers.get(_CACHE_HEADER)
+        if cache not in _CACHE_STATUSES:
+            raise ContentGatewayError(
+                response.status_code,
+                None,
+                f"the answer to {request.method} {request.path} did not come through the gateway: "
+                "no X-Cache header",
+            )
+        return PassthroughAnswer(
+            status=response.status_code,
+            ok=response.is_success,
+            cache=cast(CacheStatus, cache),
+            body=body,
+            headers=response.headers,
+        )
+
+    @staticmethod
+    def _passthrough_request(
+        upstream: str,
+        path: str,
+        *,
+        query: Query | None,
+        body: Any,
+        method: Method | None,
+        pool: str | None,
+        fresh: bool,
+        wait_up_to: float | None,
+    ) -> _Request:
+        chosen: Method = method if method is not None else ("GET" if body is None else "POST")
+        if chosen == "GET" and body is not None:
+            raise TypeError(
+                f"a GET to {path} cannot carry a body; leave method unset or make it POST"
+            )
+        return _Request(
+            method=chosen,
+            path=f"/v1/{upstream}/{path.lstrip('/')}",
+            query=query,
+            body=body,
+            pool=pool,
+            fresh=fresh,
+            wait_up_to=wait_up_to,
+        )
+
+    @staticmethod
+    def _budget_request(days: int | None) -> _Request:
+        return _Request("GET", "/v1/budget", query=None if days is None else {"days": days})
+
+    @staticmethod
+    def _resolve_request(
+        file_ids: Sequence[int],
+        *,
+        cdn: bool | None,
+        pool: str | None,
+        fresh: bool,
+        wait_up_to: float | None,
+        timeout: float,
+    ) -> _Request:
+        body: dict[str, Any] = {"fileIds": list(file_ids)}
+        if cdn is not None:
+            body["cdn"] = cdn
+        return _Request(
+            "POST",
+            "/v1/resolve",
+            body=body,
+            pool=pool,
+            fresh=fresh,
+            wait_up_to=wait_up_to,
+            timeout=timeout,
+        )
+
+    @staticmethod
+    def _minecraft_versions_request(type: VersionFilter | None, loader: Loader | None) -> _Request:
+        return _Request("GET", "/v1/minecraft/versions", query={"type": type, "loader": loader})
+
+    @staticmethod
+    def _minecraft_version_request(id: str) -> _Request:
+        return _Request("GET", f"/v1/minecraft/versions/{quote(id, safe='')}")
+
+    @staticmethod
+    def _loader_versions_request(loader: Loader, minecraft: str | None) -> _Request:
+        return _Request(
+            "GET", f"/v1/minecraft/loaders/{loader}/versions", query={"minecraft": minecraft}
+        )
+
+
+class ContentGateway(_Gateway):
+    """A consumer's connection to one gateway."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token: str,
+        pool: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.Client | None = None,
+    ) -> None:
+        super().__init__(base_url, token, pool, timeout)
+        self._client = client if client is not None else httpx.Client()
+        self._owns_client = client is None
+
+    def close(self) -> None:
+        """Closes the connections, unless the `httpx.Client` was passed in."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> ContentGateway:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def health(self) -> Health:
+        """`GET /v1/healthz`, which needs no token."""
+        return cast(Health, self._send(_Request("GET", "/v1/healthz", authenticated=False))[1])
+
+    def budget(self, *, days: int | None = None) -> BudgetSnapshot:
+        """`GET /v1/budget`: this minute's calls, the 429 hold and the daily counts of the last `days` UTC days."""
+        return cast(BudgetSnapshot, self._send(self._budget_request(days))[1])
+
+    def curseforge(
+        self,
+        path: str,
+        *,
+        query: Query | None = None,
+        body: Any = None,
+        method: Method | None = None,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+    ) -> PassthroughAnswer:
+        """Sends `api.curseforge.com/v1/<path>` (such as `mods/search`) through the gateway; CurseForge's answer comes back whatever its status, and only the gateway's own answers raise `ContentGatewayError`."""
+        return self._passthrough(
+            self._passthrough_request(
+                "curseforge",
+                path,
+                query=query,
+                body=body,
+                method=method,
+                pool=pool,
+                fresh=fresh,
+                wait_up_to=wait_up_to,
+            )
+        )
+
+    def modrinth(
+        self,
+        path: str,
+        *,
+        query: Query | None = None,
+        body: Any = None,
+        method: Method | None = None,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+    ) -> PassthroughAnswer:
+        """Sends `api.modrinth.com/v2/<path>` (such as `project/sodium`) through the gateway; Modrinth's answer comes back whatever its status, and only the gateway's own answers raise `ContentGatewayError`."""
+        return self._passthrough(
+            self._passthrough_request(
+                "modrinth",
+                path,
+                query=query,
+                body=body,
+                method=method,
+                pool=pool,
+                fresh=fresh,
+                wait_up_to=wait_up_to,
+            )
+        )
+
+    def modrinth_version_file(
+        self,
+        sha1: str,
+        *,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+    ) -> PassthroughAnswer:
+        """`GET /v1/modrinth/version_file/<sha1>`: the version Modrinth lists the file under, or a 404."""
+        return self.modrinth(
+            f"version_file/{quote(sha1, safe='')}", pool=pool, fresh=fresh, wait_up_to=wait_up_to
+        )
+
+    def modrinth_version_files(
+        self,
+        hashes: Sequence[str],
+        *,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+    ) -> PassthroughAnswer:
+        """`POST /v1/modrinth/version_files`: the versions Modrinth lists these SHA-1s under, keyed by lowercase hash."""
+        return self.modrinth(
+            "version_files",
+            body={"hashes": list(hashes), "algorithm": "sha1"},
+            pool=pool,
+            fresh=fresh,
+            wait_up_to=wait_up_to,
+        )
+
+    def resolve(
+        self,
+        file_ids: Sequence[int],
+        *,
+        cdn: bool | None = None,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+        timeout: float = RESOLVE_TIMEOUT,
+    ) -> Resolved:
+        """`POST /v1/resolve`: a download address per CurseForge file id."""
+        request = self._resolve_request(
+            file_ids, cdn=cdn, pool=pool, fresh=fresh, wait_up_to=wait_up_to, timeout=timeout
+        )
+        return cast(Resolved, self._send(request)[1])
+
+    def minecraft_versions(
+        self, *, type: VersionFilter | None = None, loader: Loader | None = None
+    ) -> MinecraftVersions:
+        """`GET /v1/minecraft/versions`: the Minecraft versions Mojang lists, newest first."""
+        return cast(
+            MinecraftVersions, self._send(self._minecraft_versions_request(type, loader))[1]
+        )
+
+    def minecraft_version(self, id: str) -> MinecraftVersionDetails:
+        """`GET /v1/minecraft/versions/<id>`: one version with the Java major it needs; `UNKNOWN_VERSION` raises."""
+        return cast(MinecraftVersionDetails, self._send(self._minecraft_version_request(id))[1])
+
+    def loader_versions(self, loader: Loader, *, minecraft: str | None = None) -> LoaderVersions:
+        """`GET /v1/minecraft/loaders/<loader>/versions`: a loader's builds, newest first."""
+        return cast(LoaderVersions, self._send(self._loader_versions_request(loader, minecraft))[1])
+
+    def _passthrough(self, request: _Request) -> PassthroughAnswer:
+        response, body = self._send(request)
+        return self._passthrough_answer(request, response, body)
+
+    def _send(self, request: _Request) -> tuple[httpx.Response, Any]:
+        url, headers, content = self._build(request)
+        deadline = time.monotonic() + (request.wait_up_to or 0)
+        timeout = request.timeout if request.timeout is not None else self._timeout
+        while True:
+            response = self._client.request(
+                request.method, url, headers=headers, content=content, timeout=timeout
+            )
+            outcome = self._settle(request, response, deadline)
+            if outcome[0] == "done":
+                return response, outcome[1]
+            time.sleep(outcome[1])
+
+
+class AsyncContentGateway(_Gateway):
+    """A consumer's connection to one gateway, for asyncio."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token: str,
+        pool: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(base_url, token, pool, timeout)
+        self._client = client if client is not None else httpx.AsyncClient()
+        self._owns_client = client is None
+
+    async def aclose(self) -> None:
+        """Closes the connections, unless the `httpx.AsyncClient` was passed in."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncContentGateway:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def health(self) -> Health:
+        """`GET /v1/healthz`, which needs no token."""
+        sent = await self._send(_Request("GET", "/v1/healthz", authenticated=False))
+        return cast(Health, sent[1])
+
+    async def budget(self, *, days: int | None = None) -> BudgetSnapshot:
+        """`GET /v1/budget`: this minute's calls, the 429 hold and the daily counts of the last `days` UTC days."""
+        sent = await self._send(self._budget_request(days))
+        return cast(BudgetSnapshot, sent[1])
+
+    async def curseforge(
+        self,
+        path: str,
+        *,
+        query: Query | None = None,
+        body: Any = None,
+        method: Method | None = None,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+    ) -> PassthroughAnswer:
+        """Sends `api.curseforge.com/v1/<path>` (such as `mods/search`) through the gateway; CurseForge's answer comes back whatever its status, and only the gateway's own answers raise `ContentGatewayError`."""
+        return await self._passthrough(
+            self._passthrough_request(
+                "curseforge",
+                path,
+                query=query,
+                body=body,
+                method=method,
+                pool=pool,
+                fresh=fresh,
+                wait_up_to=wait_up_to,
+            )
+        )
+
+    async def modrinth(
+        self,
+        path: str,
+        *,
+        query: Query | None = None,
+        body: Any = None,
+        method: Method | None = None,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+    ) -> PassthroughAnswer:
+        """Sends `api.modrinth.com/v2/<path>` (such as `project/sodium`) through the gateway; Modrinth's answer comes back whatever its status, and only the gateway's own answers raise `ContentGatewayError`."""
+        return await self._passthrough(
+            self._passthrough_request(
+                "modrinth",
+                path,
+                query=query,
+                body=body,
+                method=method,
+                pool=pool,
+                fresh=fresh,
+                wait_up_to=wait_up_to,
+            )
+        )
+
+    async def modrinth_version_file(
+        self,
+        sha1: str,
+        *,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+    ) -> PassthroughAnswer:
+        """`GET /v1/modrinth/version_file/<sha1>`: the version Modrinth lists the file under, or a 404."""
+        return await self.modrinth(
+            f"version_file/{quote(sha1, safe='')}", pool=pool, fresh=fresh, wait_up_to=wait_up_to
+        )
+
+    async def modrinth_version_files(
+        self,
+        hashes: Sequence[str],
+        *,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+    ) -> PassthroughAnswer:
+        """`POST /v1/modrinth/version_files`: the versions Modrinth lists these SHA-1s under, keyed by lowercase hash."""
+        return await self.modrinth(
+            "version_files",
+            body={"hashes": list(hashes), "algorithm": "sha1"},
+            pool=pool,
+            fresh=fresh,
+            wait_up_to=wait_up_to,
+        )
+
+    async def resolve(
+        self,
+        file_ids: Sequence[int],
+        *,
+        cdn: bool | None = None,
+        pool: str | None = None,
+        fresh: bool = False,
+        wait_up_to: float | None = None,
+        timeout: float = RESOLVE_TIMEOUT,
+    ) -> Resolved:
+        """`POST /v1/resolve`: a download address per CurseForge file id."""
+        request = self._resolve_request(
+            file_ids, cdn=cdn, pool=pool, fresh=fresh, wait_up_to=wait_up_to, timeout=timeout
+        )
+        sent = await self._send(request)
+        return cast(Resolved, sent[1])
+
+    async def minecraft_versions(
+        self, *, type: VersionFilter | None = None, loader: Loader | None = None
+    ) -> MinecraftVersions:
+        """`GET /v1/minecraft/versions`: the Minecraft versions Mojang lists, newest first."""
+        sent = await self._send(self._minecraft_versions_request(type, loader))
+        return cast(MinecraftVersions, sent[1])
+
+    async def minecraft_version(self, id: str) -> MinecraftVersionDetails:
+        """`GET /v1/minecraft/versions/<id>`: one version with the Java major it needs; `UNKNOWN_VERSION` raises."""
+        sent = await self._send(self._minecraft_version_request(id))
+        return cast(MinecraftVersionDetails, sent[1])
+
+    async def loader_versions(
+        self, loader: Loader, *, minecraft: str | None = None
+    ) -> LoaderVersions:
+        """`GET /v1/minecraft/loaders/<loader>/versions`: a loader's builds, newest first."""
+        sent = await self._send(self._loader_versions_request(loader, minecraft))
+        return cast(LoaderVersions, sent[1])
+
+    async def _passthrough(self, request: _Request) -> PassthroughAnswer:
+        response, body = await self._send(request)
+        return self._passthrough_answer(request, response, body)
+
+    async def _send(self, request: _Request) -> tuple[httpx.Response, Any]:
+        url, headers, content = self._build(request)
+        deadline = time.monotonic() + (request.wait_up_to or 0)
+        timeout = request.timeout if request.timeout is not None else self._timeout
+        while True:
+            response = await self._client.request(
+                request.method, url, headers=headers, content=content, timeout=timeout
+            )
+            outcome = self._settle(request, response, deadline)
+            if outcome[0] == "done":
+                return response, outcome[1]
+            await asyncio.sleep(outcome[1])
+
+
+def modrinth_file_url(version: Mapping[str, Any], sha1: str) -> str | None:
+    """The `https://cdn.modrinth.com` address of the file with this SHA-1 in a Modrinth version, or `None`; other files of the version and other hosts never count."""
+    wanted = sha1.lower()
+    for file in version.get("files") or ():
+        if not isinstance(file, Mapping):
+            continue
+        hashes = file.get("hashes")
+        found = hashes.get("sha1") if isinstance(hashes, Mapping) else None
+        if not isinstance(found, str) or found.lower() != wanted:
+            continue
+        url = file.get("url")
+        if not isinstance(url, str):
+            continue
+        try:
+            parts = urlsplit(url)
+        except ValueError:
+            continue
+        if parts.scheme == "https" and parts.hostname == MODRINTH_CDN_HOST:
+            return url
+    return None
+
+
+def _query_string(query: Query | None) -> str:
+    if query is None:
+        return ""
+    pairs = [(name, _query_value(value)) for name, value in query.items() if value is not None]
+    return f"?{urlencode(pairs)}" if pairs else ""
+
+
+def _query_value(value: str | int | float | bool) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _read_body(response: httpx.Response) -> Any:
+    text = response.text
+    if text == "":
+        return None
+    if not _JSON_TYPE.search(response.headers.get("content-type", "")):
+        return text
+    try:
+        return json.loads(text)
+    except ValueError:
+        return text
+
+
+def _as_api_error(body: Any) -> ApiError | None:
+    if not isinstance(body, dict):
+        return None
+    if not isinstance(body.get("code"), str) or not isinstance(body.get("message"), str):
+        return None
+    return cast(ApiError, body)
+
+
+def _retry_after(response: httpx.Response, error: ApiError | None) -> float | None:
+    if error is not None:
+        ms = error.get("retryAfterMs")
+        if isinstance(ms, int):
+            return ms / 1000
+    header = response.headers.get("retry-after", "").strip()
+    if _SECONDS.match(header):
+        return float(header)
+    return None

content_gateway_client-0.1.0/src/content_gateway/generated.py

@@ -0,0 +1,157 @@
+# generated by datamodel-codegen:
+#   filename:  openapi.json
+
+from __future__ import annotations
+from typing import Literal, NotRequired, TypeAlias, TypedDict
+
+
+class DayCounts(TypedDict):
+    calls: int
+    forbidden: int
+    hits: int
+    throttled: int
+    withheld: int
+
+
+class DayPoolSnapshot(DayCounts):
+    consumer: str
+    pool: str
+
+
+class DaySnapshot(TypedDict):
+    date: str
+    pools: list[DayPoolSnapshot]
+
+
+ErrorCode: TypeAlias = Literal[
+    "UNAUTHORIZED",
+    "POOL_REQUIRED",
+    "UNKNOWN_POOL",
+    "INVALID_PATH",
+    "INVALID_DAYS",
+    "INVALID_HASH",
+    "INVALID_BODY",
+    "INVALID_QUERY",
+    "UNKNOWN_VERSION",
+    "UNKNOWN_LOADER",
+    "UPSTREAM_TIMEOUT",
+    "UPSTREAM_UNREACHABLE",
+    "UPSTREAM_TOO_LARGE",
+    "UPSTREAM_UNREADABLE",
+    "BUDGET_SPENT",
+    "UPSTREAM_HOLD",
+    "REQUEST_TOO_LARGE",
+]
+
+
+FileSource: TypeAlias = Literal["curseforge", "modrinth", "curseforge-cdn"]
+
+
+class Health(TypedDict):
+    builtAt: NotRequired[str | None]
+    commit: NotRequired[str | None]
+    status: str
+    version: str
+
+
+class Latest(TypedDict):
+    release: str
+    snapshot: str
+
+
+Loader: TypeAlias = Literal["neoforge", "forge", "fabric"]
+
+
+class LoaderVersion(TypedDict):
+    minecraft: NotRequired[str | None]
+    recommended: bool
+    stable: bool
+    version: str
+
+
+class LoaderVersions(TypedDict):
+    loader: Loader
+    minecraft: NotRequired[str | None]
+    versions: list[LoaderVersion]
+
+
+class PoolSnapshot(TypedDict):
+    consumer: str
+    pool: str
+    used: int
+    withheld: int
+
+
+class ResolveRequest(TypedDict):
+    cdn: NotRequired[bool]
+    fileIds: list[int]
+
+
+class ResolvedFile(TypedDict):
+    fileId: int
+    fileName: NotRequired[str | None]
+    retry: bool
+    sha1: NotRequired[str | None]
+    size: NotRequired[int | None]
+    source: NotRequired[FileSource | None]
+    url: NotRequired[str | None]
+
+
+Source: TypeAlias = Literal["redis", "memory", "unavailable"]
+
+
+class UpstreamBudget(TypedDict):
+    days: list[DaySnapshot]
+    heldUntil: NotRequired[str | None]
+    limitPerMinute: int
+    pools: list[PoolSnapshot]
+    resetsAt: str
+    used: int
+    withheld: int
+
+
+class VersionFilesRequest(TypedDict):
+    algorithm: NotRequired[str]
+    hashes: list[str]
+
+
+VersionFilter: TypeAlias = Literal["release", "snapshot", "all"]
+
+
+VersionType: TypeAlias = Literal["release", "snapshot", "old_beta", "old_alpha"]
+
+
+class ApiError(TypedDict):
+    code: ErrorCode
+    message: str
+    pool: NotRequired[str | None]
+    retryAfterMs: NotRequired[int | None]
+
+
+class BudgetSnapshot(TypedDict):
+    curseforge: UpstreamBudget
+    historyDays: int
+    modrinth: UpstreamBudget
+    source: Source
+
+
+class MinecraftVersion(TypedDict):
+    id: str
+    releaseTime: str
+    type: VersionType
+
+
+class MinecraftVersionDetails(TypedDict):
+    id: str
+    javaMajor: NotRequired[int | None]
+    releaseTime: str
+    type: VersionType
+
+
+class MinecraftVersions(TypedDict):
+    latest: Latest
+    versions: list[MinecraftVersion]
+
+
+class Resolved(TypedDict):
+    files: list[ResolvedFile]