asyncgh 0.1.0__tar.gz

asyncgh-0.1.0/.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+dist/
+public/

asyncgh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugo Haas
+
+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.

asyncgh-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: asyncgh
+Version: 0.1.0
+Summary: Minimal async GitHub REST + GraphQL transport: auth, retry, pagination -- no generated models
+Project-URL: Homepage, https://github.com/hugoh/gh-workflows/tree/main/asyncgh
+Project-URL: Issues, https://github.com/hugoh/gh-workflows/issues
+Project-URL: Repository, https://github.com/hugoh/gh-workflows
+Author: Hugo Haas
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.10
+Requires-Dist: pynacl>=1.5
+Requires-Dist: stamina>=25.2
+Description-Content-Type: text/markdown
+
+# asyncgh
+
+A minimal async GitHub API transport — the plumbing an account-wide config
+tool needs before any of its domain logic: authentication, a shared
+connection, retrying error handling, REST pagination, and GraphQL.
+
+There is no client object to construct and no config. It reads the token
+`gh auth login` already stored, keeps one process-wide `httpx2.AsyncClient`,
+and exposes plain functions.
+
+## Why not PyGithub / githubkit / gidgethub / fast.ai's `ghapi`?
+
+| Library | Async | Shape | Trade-off vs `asyncgh` |
+|---|---|---|---|
+| [PyGithub](https://github.com/PyGithub/PyGithub) | no | typed objects | sync-only — a poor fit for anything doing concurrent, fan-out API calls |
+| [githubkit](https://github.com/yanyongyu/githubkit) | yes | Pydantic models, generated from GitHub's OpenAPI spec | full, typed surface, but pulls in codegen'd models and `pydantic`; heavier than most scripts need |
+| [gidgethub](https://github.com/gidgethub/gidgethub) | yes | sans-I/O, bring-your-own HTTP client | closest in spirit, but leaves auth, retry, and the client itself to the caller |
+| [ghapi](https://ghapi.fast.ai) (fast.ai) | no | OpenAPI-generated, dynamic attribute access | lightweight like this package, but sync-only |
+| **asyncgh** | yes | plain `dict`s, ~200 lines | no generated models, no schema — you read GitHub's own docs and index the JSON; retry and GraphQL are built in, not bolted on |
+
+If you want typed responses and full API coverage, use `githubkit`. If you
+want an async client with almost no code between you and the wire — a script
+firing dozens of concurrent calls that reads a handful of fields per
+response — that's what this is for.
+
+## API
+
+Full API reference, generated from the docstrings:
+[hugoh.github.io/gh-workflows/asyncgh](https://hugoh.github.io/gh-workflows/asyncgh/)
+(rebuilt on every push that touches this package -- see
+`.github/workflows/docs.yml`).
+
+## Auth
+
+`Authorization: Bearer $(gh auth token)`, resolved lazily on the first
+request and cached for the process. `gh` must be installed and logged in.
+
+## Retries
+
+`api_request` retries transport errors (DNS, timeout, reset) and transient
+statuses — 429, 500, 502, 503, 504 — via [`stamina`](https://stamina.hynek.me).
+A `Retry-After` header sets the exact wait; otherwise exponential backoff with
+jitter. `GH_MAX_RETRIES` (default 3) caps the retries; there is no wall-clock
+timeout, so a minute-long `Retry-After` is honoured in full. When the retries
+are spent the last response is returned unchanged for the caller to judge.
+
+`graphql()` reuses that same retry for transport errors and 429/5xx, plus one
+addition: GitHub answers GraphQL rate limiting with HTTP 200 and an
+`errors[].type == "RATE_LIMITED"` body, which `api_request`'s status-based
+retry never sees -- `graphql()` retries that case itself, on the same
+backoff. Any other GraphQL error (bad query, not found) is not transient and
+raises immediately.
+
+## Consumers
+
+`repo-admin/` (in this repo) uses it for every account-wide GitHub command --
+`repo_admin.py`'s `sync` subcommands and `activity.py` via `api_request`/
+`api_json`/pagination; `digest.py` (wrapped by `../digest-action/`) is the
+one driving `graphql()`.

asyncgh-0.1.0/README.md

@@ -0,0 +1,59 @@
+# asyncgh
+
+A minimal async GitHub API transport — the plumbing an account-wide config
+tool needs before any of its domain logic: authentication, a shared
+connection, retrying error handling, REST pagination, and GraphQL.
+
+There is no client object to construct and no config. It reads the token
+`gh auth login` already stored, keeps one process-wide `httpx2.AsyncClient`,
+and exposes plain functions.
+
+## Why not PyGithub / githubkit / gidgethub / fast.ai's `ghapi`?
+
+| Library | Async | Shape | Trade-off vs `asyncgh` |
+|---|---|---|---|
+| [PyGithub](https://github.com/PyGithub/PyGithub) | no | typed objects | sync-only — a poor fit for anything doing concurrent, fan-out API calls |
+| [githubkit](https://github.com/yanyongyu/githubkit) | yes | Pydantic models, generated from GitHub's OpenAPI spec | full, typed surface, but pulls in codegen'd models and `pydantic`; heavier than most scripts need |
+| [gidgethub](https://github.com/gidgethub/gidgethub) | yes | sans-I/O, bring-your-own HTTP client | closest in spirit, but leaves auth, retry, and the client itself to the caller |
+| [ghapi](https://ghapi.fast.ai) (fast.ai) | no | OpenAPI-generated, dynamic attribute access | lightweight like this package, but sync-only |
+| **asyncgh** | yes | plain `dict`s, ~200 lines | no generated models, no schema — you read GitHub's own docs and index the JSON; retry and GraphQL are built in, not bolted on |
+
+If you want typed responses and full API coverage, use `githubkit`. If you
+want an async client with almost no code between you and the wire — a script
+firing dozens of concurrent calls that reads a handful of fields per
+response — that's what this is for.
+
+## API
+
+Full API reference, generated from the docstrings:
+[hugoh.github.io/gh-workflows/asyncgh](https://hugoh.github.io/gh-workflows/asyncgh/)
+(rebuilt on every push that touches this package -- see
+`.github/workflows/docs.yml`).
+
+## Auth
+
+`Authorization: Bearer $(gh auth token)`, resolved lazily on the first
+request and cached for the process. `gh` must be installed and logged in.
+
+## Retries
+
+`api_request` retries transport errors (DNS, timeout, reset) and transient
+statuses — 429, 500, 502, 503, 504 — via [`stamina`](https://stamina.hynek.me).
+A `Retry-After` header sets the exact wait; otherwise exponential backoff with
+jitter. `GH_MAX_RETRIES` (default 3) caps the retries; there is no wall-clock
+timeout, so a minute-long `Retry-After` is honoured in full. When the retries
+are spent the last response is returned unchanged for the caller to judge.
+
+`graphql()` reuses that same retry for transport errors and 429/5xx, plus one
+addition: GitHub answers GraphQL rate limiting with HTTP 200 and an
+`errors[].type == "RATE_LIMITED"` body, which `api_request`'s status-based
+retry never sees -- `graphql()` retries that case itself, on the same
+backoff. Any other GraphQL error (bad query, not found) is not transient and
+raises immediately.
+
+## Consumers
+
+`repo-admin/` (in this repo) uses it for every account-wide GitHub command --
+`repo_admin.py`'s `sync` subcommands and `activity.py` via `api_request`/
+`api_json`/pagination; `digest.py` (wrapped by `../digest-action/`) is the
+one driving `graphql()`.

asyncgh-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "asyncgh"
+version = "0.1.0"
+description = "Minimal async GitHub REST + GraphQL transport: auth, retry, pagination -- no generated models"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "Hugo Haas" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Internet :: WWW/HTTP",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+dependencies = ["httpx2>=2.10", "pynacl>=1.5", "stamina>=25.2"]
+
+[project.urls]
+Homepage = "https://github.com/hugoh/gh-workflows/tree/main/asyncgh"
+Issues = "https://github.com/hugoh/gh-workflows/issues"
+Repository = "https://github.com/hugoh/gh-workflows"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "pytest-httpx2>=0.1", "respx>=0.21"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/asyncgh"]
+
+[tool.pytest.ini_options]
+addopts = ["-p", "pytest_httpx2"]
+testpaths = ["tests"]
+asyncio_mode = "auto"

asyncgh-0.1.0/src/asyncgh/__init__.py

@@ -0,0 +1,42 @@
+"""asyncgh -- the GitHub REST API transport shared by repo-admin's scripts.
+
+Auth via the token `gh` already holds, one shared async client, raw and
+raise-on-error request helpers, `Link`-header pagination, and thin wrappers
+over the few endpoints more than one script needs (account-wide repo
+listing, Actions secrets). No config-file loading, no repo filtering -- those
+stay with the caller.
+"""
+
+from __future__ import annotations
+
+from .client import (
+    API_BASE,
+    GhError,
+    aclose_client,
+    api_json,
+    api_request,
+    error_message,
+    graphql,
+    paginated,
+)
+from .endpoints import (
+    encrypt_secret_value,
+    fetch_repos_json,
+    public_repos_json,
+    set_repo_secret,
+)
+
+__all__ = [
+    "API_BASE",
+    "GhError",
+    "aclose_client",
+    "api_json",
+    "api_request",
+    "encrypt_secret_value",
+    "error_message",
+    "fetch_repos_json",
+    "graphql",
+    "paginated",
+    "public_repos_json",
+    "set_repo_secret",
+]

asyncgh-0.1.0/src/asyncgh/client.py

@@ -0,0 +1,242 @@
+"""GitHub REST API transport: auth, the shared async client, and the
+request / pagination helpers every endpoint wrapper is built on.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+from typing import Any
+
+import httpx2
+import stamina
+
+API_BASE = "https://api.github.com"
+
+# Retry transport failures and transient statuses (429 + 5xx). `attempts` is
+# total tries, so MAX_RETRIES=3 means one call plus three retries. There is no
+# wall-clock timeout: GitHub's Retry-After on a secondary rate limit is often
+# a minute or more, and honouring it is the whole point.
+MAX_RETRIES = int(os.environ.get("GH_MAX_RETRIES", "3"))
+RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+RETRY_WAIT_INITIAL = 1.0
+RETRY_WAIT_MAX = 60.0
+RETRY_WAIT_JITTER = 1.0
+
+
+class GhError(RuntimeError):
+    """A GitHub API call -- or a caller's worker function -- failed
+    unexpectedly.
+
+    status_code is set for HTTP errors raised by api_json(), so callers can
+    branch on the real status code (e.g. 403 vs 404) instead of
+    string-matching an error message. Plain RuntimeError rather than a
+    reconcilekit.ReconcileError subclass -- asyncgh has no dependency on
+    reconcilekit, so it stays installable standalone; reconcilekit's own
+    run_parallel(..., error_cls=) only requires type[Exception], so GhError
+    still works there unchanged.
+    """
+
+    def __init__(self, message: str, *, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+def _auth_token() -> str:
+    """Reads the token `gh` already has -- keychain storage, SSO, and 2FA are
+    already solved by `gh auth login`, so this reuses that instead of
+    managing a separate credential.
+    """
+    result = subprocess.run(
+        ["gh", "auth", "token"], capture_output=True, text=True, check=False
+    )
+    if result.returncode != 0:
+        raise GhError(f"gh auth token failed: {result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+_client: httpx2.AsyncClient | None = None
+_client_lock = asyncio.Lock()
+
+
+async def _get_client() -> httpx2.AsyncClient:
+    # One shared AsyncClient rather than one per thread: there's no thread
+    # pool, and gh auth token only needs to be paid once per process.
+    global _client
+    if _client is None:
+        async with _client_lock:
+            if _client is None:
+                _client = httpx2.AsyncClient(
+                    headers={
+                        "Authorization": f"Bearer {_auth_token()}",
+                        "Accept": "application/vnd.github+json",
+                        "X-GitHub-Api-Version": "2022-11-28",
+                    },
+                    timeout=30,
+                )
+    return _client
+
+
+async def aclose_client() -> None:
+    global _client
+    if _client is not None:
+        await _client.aclose()
+        _client = None
+
+
+def _should_retry(exc: Exception) -> bool | float:
+    """stamina backoff hook. A `Retry-After` header (GitHub sends one on
+    secondary rate limits) sets the exact wait; otherwise transport errors
+    and RETRY_STATUSES responses retry on stamina's default backoff, and
+    everything else propagates.
+    """
+    response = getattr(exc, "response", None)
+    if response is not None:
+        header = response.headers.get("retry-after")
+        if header:
+            try:
+                return float(header)
+            except ValueError:
+                pass
+        return response.status_code in RETRY_STATUSES
+    return isinstance(exc, httpx2.TransportError)
+
+
+async def api_request(
+    method: str, path: str, *, json: Any = None, params: dict | None = None
+) -> httpx2.Response:
+    """Makes one GitHub REST API call and returns the raw Response --
+    callers decide what a given status means for their endpoint (e.g. a 404
+    means "feature disabled" for vulnerability-alerts but "not found"
+    everywhere else). Raises GhError only for genuine transport failures
+    (DNS, timeout, connection reset); HTTP error statuses are returned, not
+    raised.
+
+    Transport errors and transient statuses (429, 5xx) are retried up to
+    MAX_RETRIES times, honouring `Retry-After`. GitHub's writes here are
+    idempotent (secret PUTs replace), so retrying any method is safe.
+    """
+    url = path if path.startswith("http") else f"{API_BASE}{path}"
+    http = await _get_client()
+    try:
+        async for attempt in stamina.retry_context(
+            on=_should_retry,
+            attempts=MAX_RETRIES + 1,
+            timeout=None,
+            wait_initial=RETRY_WAIT_INITIAL,
+            wait_max=RETRY_WAIT_MAX,
+            wait_jitter=RETRY_WAIT_JITTER,
+        ):
+            with attempt:
+                try:
+                    response = await http.request(method, url, json=json, params=params)
+                except httpx2.TransportError:
+                    raise
+                except httpx2.HTTPError as exc:
+                    raise GhError(str(exc)) from exc
+                if response.status_code in RETRY_STATUSES:
+                    response.raise_for_status()
+                return response
+    except httpx2.HTTPStatusError as exc:
+        return exc.response  # retryable status, retries spent -- let the caller judge
+    except httpx2.TransportError as exc:
+        raise GhError(str(exc)) from exc
+    raise GhError("api_request retry loop exited without a response")  # unreachable
+
+
+def error_message(response: httpx2.Response) -> str:
+    """Extracts GitHub's own `message` field from an error response body,
+    falling back to the raw response text if the body isn't JSON.
+    """
+    try:
+        return response.json().get("message", response.text)
+    except ValueError:
+        return response.text
+
+
+async def api_json(
+    method: str, path: str, *, json: Any = None, params: dict | None = None
+) -> dict:
+    """Like api_request, but raises GhError (with status_code and GitHub's
+    own error message) on any non-2xx response, and returns the parsed JSON
+    body -- or {} for a body-less response like 204 No Content -- on success.
+    """
+    response = await api_request(method, path, json=json, params=params)
+    if not response.is_success:
+        raise GhError(error_message(response), status_code=response.status_code)
+    return response.json() if response.content else {}
+
+
+class _GraphQLRateLimited(Exception):
+    """Internal marker: GraphQL answered 200 with errors[].type ==
+    RATE_LIMITED, which api_request's transport/5xx retry never sees since
+    it only looks at the HTTP status. Retried at this layer instead.
+    """
+
+
+async def graphql(query: str, variables: dict | None = None) -> dict:
+    """Runs one GraphQL query and returns its `data` object.
+
+    GraphQL always answers HTTP 200, even for query errors, so success lives
+    in the body: `errors` present (with `data` null or partial) raises
+    GhError with the joined messages -- callers have no partial-data story,
+    so partial loss is worse than a loud failure. RATE_LIMITED errors retry
+    (stamina, same backoff as api_request) since they're the one transient
+    GraphQL failure mode; other GraphQL errors (bad query, not found) are
+    not transient and raise immediately.
+    """
+    try:
+        async for attempt in stamina.retry_context(
+            on=lambda exc: isinstance(exc, _GraphQLRateLimited),
+            attempts=MAX_RETRIES + 1,
+            timeout=None,
+            wait_initial=RETRY_WAIT_INITIAL,
+            wait_max=RETRY_WAIT_MAX,
+            wait_jitter=RETRY_WAIT_JITTER,
+        ):
+            with attempt:
+                response = await api_request(
+                    "POST",
+                    "/graphql",
+                    json={"query": query, "variables": variables or {}},
+                )
+                if not response.is_success:
+                    raise GhError(
+                        error_message(response), status_code=response.status_code
+                    )
+                body = response.json()
+                errors = body.get("errors")
+                if errors:
+                    if any(error.get("type") == "RATE_LIMITED" for error in errors):
+                        raise _GraphQLRateLimited(
+                            "; ".join(
+                                error.get("message", str(error)) for error in errors
+                            )
+                        )
+                    raise GhError(
+                        "; ".join(error.get("message", str(error)) for error in errors)
+                    )
+                return body["data"]
+    except _GraphQLRateLimited as exc:
+        raise GhError(str(exc)) from exc
+    raise GhError("graphql retry loop exited without a response")  # unreachable
+
+
+async def paginated(
+    method: str, path: str, *, params: dict | None = None
+) -> list[dict]:
+    """Follows GitHub's `Link: rel="next"` header, concatenating every page's
+    JSON array into one list.
+    """
+    items = []
+    url = path
+    query = params
+    while url:
+        response = await api_request(method, url, params=query)
+        if not response.is_success:
+            raise GhError(error_message(response), status_code=response.status_code)
+        items.extend(response.json())
+        url = response.links.get("next", {}).get("url")
+        query = None  # the "next" link already carries the full query string
+    return items

asyncgh-0.1.0/src/asyncgh/endpoints.py

@@ -0,0 +1,62 @@
+"""Thin wrappers over the handful of GitHub REST endpoints shared across
+repo-admin's scripts: account-wide repo listing and Actions secrets.
+"""
+
+from __future__ import annotations
+
+import base64
+
+from nacl import encoding, public
+
+from .client import api_json, paginated
+
+
+async def fetch_repos_json(owner: str) -> list[dict]:
+    """Lists every repo for `owner`. When `owner` is the authenticated `gh`
+    user, uses /user/repos so private repos are included; otherwise falls
+    back to /users/{owner}/repos, which only ever returns public repos.
+    """
+    viewer = (await api_json("GET", "/user")).get("login")
+    if owner == viewer:
+        return await paginated(
+            "GET", "/user/repos", params={"affiliation": "owner", "per_page": "100"}
+        )
+    return await paginated("GET", f"/users/{owner}/repos", params={"per_page": "100"})
+
+
+async def public_repos_json(owner: str) -> list[dict]:
+    """Lists `owner`'s public repos only, via /users/{owner}/repos -- unlike
+    fetch_repos_json, this always excludes private repos even when `owner`
+    is the authenticated user, so no /user call is needed to branch on it.
+    """
+    return await paginated("GET", f"/users/{owner}/repos", params={"per_page": "100"})
+
+
+def encrypt_secret_value(public_key_b64: str, value: str) -> str:
+    """Encrypts `value` for GitHub's Actions secrets API using a repo's
+    public key, per GitHub's documented libsodium sealed-box scheme.
+    """
+    public_key = public.PublicKey(
+        public_key_b64.encode("utf-8"), encoding.Base64Encoder
+    )
+    encrypted = public.SealedBox(public_key).encrypt(value.encode("utf-8"))
+    return base64.b64encode(encrypted).decode("utf-8")
+
+
+async def set_repo_secret(
+    owner: str, repo_name: str, secret_name: str, value: str
+) -> None:
+    """Sets one repo's Actions secret via GitHub's REST API: fetches the
+    repo's current public key, encrypts `value` for it, and PUTs the
+    result. The plaintext value never leaves this process -- it's encrypted
+    in memory before the request body is built.
+    """
+    key_data = await api_json(
+        "GET", f"/repos/{owner}/{repo_name}/actions/secrets/public-key"
+    )
+    encrypted_value = encrypt_secret_value(key_data["key"], value)
+    await api_json(
+        "PUT",
+        f"/repos/{owner}/{repo_name}/actions/secrets/{secret_name}",
+        json={"encrypted_value": encrypted_value, "key_id": key_data["key_id"]},
+    )

asyncgh-0.1.0/tests/conftest.py

@@ -0,0 +1,21 @@
+import pytest
+
+from asyncgh import client
+
+
+@pytest.fixture(autouse=True)
+def _reset_http_client():
+    # httpx2.AsyncClient is bound to the event loop it was created under, and
+    # pytest-asyncio's default function-scoped loop means a client surviving
+    # across tests would raise "attached to a different loop" errors.
+    client._client = None
+    yield
+    client._client = None
+
+
+@pytest.fixture(autouse=True)
+def fake_auth_token(monkeypatch):
+    # Avoids every test shelling out to the real `gh auth token` -- client
+    # creation is lazy, so this just needs to be in place before the first
+    # api_request/api_json call.
+    monkeypatch.setattr(client, "_auth_token", lambda: "fake-token")

asyncgh-0.1.0/tests/test_client.py

@@ -0,0 +1,271 @@
+import json
+
+import httpx
+import httpx2
+import pytest
+import respx
+from asyncgh.client import _should_retry
+
+from asyncgh import (
+    API_BASE,
+    GhError,
+    api_json,
+    api_request,
+    client,
+    error_message,
+    graphql,
+)
+
+
+@pytest.fixture(autouse=True)
+def _instant_backoff(monkeypatch):
+    monkeypatch.setattr(client, "RETRY_WAIT_INITIAL", 0.0)
+    monkeypatch.setattr(client, "RETRY_WAIT_MAX", 0.0)
+    monkeypatch.setattr(client, "RETRY_WAIT_JITTER", 0.0)
+
+
+async def test_error_message_prefers_json_message_field(httpx2_mock: respx.Router):
+    httpx2_mock.get(f"{API_BASE}/x").mock(
+        return_value=httpx.Response(404, json={"message": "not found"})
+    )
+    response = await api_request("GET", "/x")
+    assert error_message(response) == "not found"
+
+
+async def test_error_message_falls_back_to_raw_text_for_non_json_body(
+    httpx2_mock: respx.Router,
+):
+    httpx2_mock.get(f"{API_BASE}/x").mock(
+        return_value=httpx.Response(
+            500, text="plain text error", headers={"Content-Type": "text/plain"}
+        )
+    )
+    response = await api_request("GET", "/x")
+    assert error_message(response) == "plain text error"
+
+
+async def test_api_json_returns_parsed_body_on_success(httpx2_mock: respx.Router):
+    httpx2_mock.get(f"{API_BASE}/repos/hugoh/gh-workflows").mock(
+        return_value=httpx.Response(200, json={"name": "gh-workflows"})
+    )
+    assert await api_json("GET", "/repos/hugoh/gh-workflows") == {
+        "name": "gh-workflows"
+    }
+
+
+async def test_api_json_raises_gh_error_with_status_code_on_failure(
+    httpx2_mock: respx.Router,
+):
+    httpx2_mock.get(f"{API_BASE}/repos/hugoh/nope").mock(
+        return_value=httpx.Response(404, json={"message": "Not Found"})
+    )
+    with pytest.raises(GhError) as exc_info:
+        await api_json("GET", "/repos/hugoh/nope")
+    assert exc_info.value.status_code == 404
+    assert "Not Found" in str(exc_info.value)
+
+
+async def test_api_json_handles_empty_204_response(httpx2_mock: respx.Router):
+    httpx2_mock.put(f"{API_BASE}/repos/hugoh/gh-workflows/vulnerability-alerts").mock(
+        return_value=httpx.Response(204)
+    )
+    assert await api_json("PUT", "/repos/hugoh/gh-workflows/vulnerability-alerts") == {}
+
+
+async def test_api_request_does_not_raise_on_http_error_status(
+    httpx2_mock: respx.Router,
+):
+    httpx2_mock.get(
+        f"{API_BASE}/repos/hugoh/private-repo/private-vulnerability-reporting"
+    ).mock(return_value=httpx.Response(404))
+    response = await api_request(
+        "GET", "/repos/hugoh/private-repo/private-vulnerability-reporting"
+    )
+    assert response.status_code == 404
+
+
+async def test_api_request_retries_transport_error_then_succeeds(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.get(f"{API_BASE}/x").mock(
+        side_effect=[httpx2.ConnectError("boom"), httpx.Response(200, json={})]
+    )
+    response = await api_request("GET", "/x")
+    assert response.status_code == 200
+    assert route.call_count == 2
+
+
+async def test_api_request_raises_gh_error_after_exhausting_transport_retries(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.get(f"{API_BASE}/x").mock(
+        side_effect=httpx2.ConnectError("boom")
+    )
+    with pytest.raises(GhError, match="boom"):
+        await api_request("GET", "/x")
+    assert route.call_count == client.MAX_RETRIES + 1
+
+
+async def test_api_request_retries_retryable_status_then_returns_success(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.get(f"{API_BASE}/x").mock(
+        side_effect=[httpx.Response(503), httpx.Response(200, json={})]
+    )
+    response = await api_request("GET", "/x")
+    assert response.status_code == 200
+    assert route.call_count == 2
+
+
+async def test_api_request_returns_last_response_when_retries_exhausted(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.get(f"{API_BASE}/x").mock(return_value=httpx.Response(503))
+    response = await api_request("GET", "/x")
+    assert response.status_code == 503
+    assert route.call_count == client.MAX_RETRIES + 1
+
+
+async def test_api_request_does_not_retry_non_retryable_status(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.get(f"{API_BASE}/x").mock(return_value=httpx.Response(404))
+    await api_request("GET", "/x")
+    assert route.call_count == 1
+
+
+async def test_api_request_does_not_retry_non_transport_request_error(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.get(f"{API_BASE}/x").mock(
+        side_effect=httpx2.DecodingError("bad body")
+    )
+    with pytest.raises(GhError, match="bad body"):
+        await api_request("GET", "/x")
+    assert route.call_count == 1
+
+
+async def test_max_retries_zero_disables_retrying(
+    httpx2_mock: respx.Router, monkeypatch
+):
+    monkeypatch.setattr(client, "MAX_RETRIES", 0)
+    route = httpx2_mock.get(f"{API_BASE}/x").mock(return_value=httpx.Response(503))
+    await api_request("GET", "/x")
+    assert route.call_count == 1
+
+
+def _status_error(status: int, **headers: str) -> httpx2.HTTPStatusError:
+    request = httpx2.Request("GET", f"{API_BASE}/x")
+    response = httpx2.Response(status, headers=headers, request=request)
+    return httpx2.HTTPStatusError(str(status), request=request, response=response)
+
+
+def test_should_retry_reads_retry_after_header_as_exact_wait():
+    assert _should_retry(_status_error(429, **{"Retry-After": "42"})) == 42.0
+
+
+def test_should_retry_true_for_5xx_without_retry_after():
+    assert _should_retry(_status_error(503)) is True
+
+
+def test_should_retry_false_for_4xx():
+    assert _should_retry(_status_error(404)) is False
+
+
+def test_should_retry_true_for_transport_error():
+    assert _should_retry(httpx2.ConnectError("boom")) is True
+
+
+def test_should_retry_false_for_other_exception():
+    assert _should_retry(ValueError("nope")) is False
+
+
+async def test_graphql_posts_query_and_variables_and_returns_data(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.post(f"{API_BASE}/graphql").mock(
+        return_value=httpx.Response(200, json={"data": {"viewer": {"login": "hugoh"}}})
+    )
+    data = await graphql("query { viewer { login } }", {"x": 1})
+    assert data == {"viewer": {"login": "hugoh"}}
+    body = json.loads(route.calls[0].request.content)
+    assert body == {"query": "query { viewer { login } }", "variables": {"x": 1}}
+
+
+async def test_graphql_raises_gh_error_when_errors_present_and_data_null(
+    httpx2_mock: respx.Router,
+):
+    httpx2_mock.post(f"{API_BASE}/graphql").mock(
+        return_value=httpx.Response(
+            200, json={"data": None, "errors": [{"message": "Could not resolve"}]}
+        )
+    )
+    with pytest.raises(GhError, match="Could not resolve"):
+        await graphql("query { nope }")
+
+
+async def test_graphql_raises_gh_error_when_errors_present_alongside_partial_data(
+    httpx2_mock: respx.Router,
+):
+    httpx2_mock.post(f"{API_BASE}/graphql").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "data": {"r0": {"name": "a"}, "r1": None},
+                "errors": [{"message": "r1 not found"}],
+            },
+        )
+    )
+    with pytest.raises(GhError, match="r1 not found"):
+        await graphql("query { r0 r1 }")
+
+
+async def test_graphql_retries_on_transport_error_via_api_request(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.post(f"{API_BASE}/graphql").mock(
+        side_effect=[
+            httpx2.ConnectError("boom"),
+            httpx.Response(200, json={"data": {"ok": True}}),
+        ]
+    )
+    data = await graphql("query { ok }")
+    assert data == {"ok": True}
+    assert route.call_count == 2
+
+
+async def test_graphql_retries_rate_limited_error_then_succeeds(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.post(f"{API_BASE}/graphql").mock(
+        side_effect=[
+            httpx.Response(
+                200,
+                json={
+                    "data": None,
+                    "errors": [{"type": "RATE_LIMITED", "message": "rate limited"}],
+                },
+            ),
+            httpx.Response(200, json={"data": {"ok": True}}),
+        ]
+    )
+    data = await graphql("query { ok }")
+    assert data == {"ok": True}
+    assert route.call_count == 2
+
+
+async def test_graphql_raises_gh_error_after_exhausting_rate_limited_retries(
+    httpx2_mock: respx.Router,
+):
+    route = httpx2_mock.post(f"{API_BASE}/graphql").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "data": None,
+                "errors": [{"type": "RATE_LIMITED", "message": "rate limited"}],
+            },
+        )
+    )
+    with pytest.raises(GhError, match="rate limited"):
+        await graphql("query { ok }")
+    assert route.call_count == client.MAX_RETRIES + 1

asyncgh-0.1.0/tests/test_endpoints.py

@@ -0,0 +1,130 @@
+import base64
+
+import httpx
+import respx
+from nacl import encoding, public
+
+from asyncgh import (
+    API_BASE,
+    encrypt_secret_value,
+    endpoints,
+    fetch_repos_json,
+    public_repos_json,
+    set_repo_secret,
+)
+
+
+async def test_fetch_repos_json_uses_authenticated_user_repos_when_owner_matches(
+    httpx2_mock: respx.Router,
+):
+    httpx2_mock.get(f"{API_BASE}/user").mock(
+        return_value=httpx.Response(200, json={"login": "hugoh"})
+    )
+    httpx2_mock.get(f"{API_BASE}/user/repos").mock(
+        return_value=httpx.Response(200, json=[{"name": "a"}])
+    )
+    assert await fetch_repos_json("hugoh") == [{"name": "a"}]
+
+
+async def test_fetch_repos_json_falls_back_to_public_repos_for_other_owners(
+    httpx2_mock: respx.Router,
+):
+    httpx2_mock.get(f"{API_BASE}/user").mock(
+        return_value=httpx.Response(200, json={"login": "hugoh"})
+    )
+    httpx2_mock.get(f"{API_BASE}/users/someorg/repos").mock(
+        return_value=httpx.Response(200, json=[{"name": "b"}])
+    )
+    assert await fetch_repos_json("someorg") == [{"name": "b"}]
+
+
+async def test_fetch_repos_json_follows_pagination_link_header(
+    httpx2_mock: respx.Router,
+):
+    httpx2_mock.get(f"{API_BASE}/user").mock(
+        return_value=httpx.Response(200, json={"login": "hugoh"})
+    )
+    # respx routes are tried in registration order and a route with no
+    # `params` constraint matches any query string -- the page=2 route must
+    # be registered first, or the unconstrained page-1 route below would
+    # swallow it too and paginated would loop on page1 forever.
+    httpx2_mock.get(f"{API_BASE}/user/repos", params={"page": "2"}).mock(
+        return_value=httpx.Response(200, json=[{"name": "page2"}])
+    )
+    httpx2_mock.get(f"{API_BASE}/user/repos").mock(
+        return_value=httpx.Response(
+            200,
+            json=[{"name": "page1"}],
+            headers={"Link": f'<{API_BASE}/user/repos?page=2>; rel="next"'},
+        )
+    )
+    assert await fetch_repos_json("hugoh") == [{"name": "page1"}, {"name": "page2"}]
+
+
+async def test_public_repos_json_uses_public_users_endpoint_even_for_self(
+    httpx2_mock: respx.Router,
+):
+    # /users/{owner}/repos only ever returns public repos, even when owner is
+    # the authenticated user -- unlike fetch_repos_json, no /user call is
+    # needed to check whether owner is the viewer.
+    httpx2_mock.get(f"{API_BASE}/users/hugoh/repos").mock(
+        return_value=httpx.Response(200, json=[{"name": "public-repo"}])
+    )
+    assert await public_repos_json("hugoh") == [{"name": "public-repo"}]
+    assert not any(call.request.url.path == "/user" for call in httpx2_mock.calls)
+
+
+async def test_public_repos_json_follows_pagination_link_header(
+    httpx2_mock: respx.Router,
+):
+    httpx2_mock.get(f"{API_BASE}/users/hugoh/repos", params={"page": "2"}).mock(
+        return_value=httpx.Response(200, json=[{"name": "page2"}])
+    )
+    httpx2_mock.get(f"{API_BASE}/users/hugoh/repos").mock(
+        return_value=httpx.Response(
+            200,
+            json=[{"name": "page1"}],
+            headers={"Link": f'<{API_BASE}/users/hugoh/repos?page=2>; rel="next"'},
+        )
+    )
+    assert await public_repos_json("hugoh") == [{"name": "page1"}, {"name": "page2"}]
+
+
+def test_encrypt_secret_value_round_trips_through_sealed_box():
+    private_key = public.PrivateKey.generate()
+    public_key_b64 = private_key.public_key.encode(encoding.Base64Encoder).decode(
+        "utf-8"
+    )
+
+    ciphertext_b64 = encrypt_secret_value(public_key_b64, "super-secret-value")
+
+    decrypted = public.SealedBox(private_key).decrypt(base64.b64decode(ciphertext_b64))
+    assert decrypted == b"super-secret-value"
+
+
+async def test_set_repo_secret_encrypts_and_puts_with_key_id(monkeypatch):
+    private_key = public.PrivateKey.generate()
+    public_key_b64 = private_key.public_key.encode(encoding.Base64Encoder).decode(
+        "utf-8"
+    )
+    calls = []
+
+    async def fake_api_json(method, path, **kwargs):
+        if method == "GET":
+            return {"key": public_key_b64, "key_id": "key-id-123"}
+        calls.append((method, path, kwargs.get("json")))
+        return {}
+
+    monkeypatch.setattr(endpoints, "api_json", fake_api_json)
+    await set_repo_secret("hugoh", "repo", "NAME", "the-value")
+
+    assert len(calls) == 1
+    method, path, body = calls[0]
+    assert method == "PUT"
+    assert path == "/repos/hugoh/repo/actions/secrets/NAME"
+    assert body["key_id"] == "key-id-123"
+
+    decrypted = public.SealedBox(private_key).decrypt(
+        base64.b64decode(body["encrypted_value"])
+    )
+    assert decrypted == b"the-value"