test_api.py
python
sha256:6492a128c2a7aa4605102b380091a2192022e47d2bd3b35aac7e7596423317aa
fix(repos): a transfer moves the owner slug and owner autho…
Opus 5.5
minor
⚠ breaking
1 day ago
| 1 | """DOC_API — /muse/api contract (musehub#255, QA contract v2). |
| 2 | |
| 3 | Every claim on the page was checked against the MuseHub server source (``dev`` 2978eb11) and Muse |
| 4 | 0.2.1rc20 on 2026-11-08, by executing it with real Ed25519-signed requests against a disposable |
| 5 | MuseHub (in-process, disposable PostgreSQL). These tests keep the corrected page honest in both |
| 6 | directions without a database: the endpoint tables are compared with the application's route table |
| 7 | (method, path, auth kind, scope), the example field names with the response and request schemas, the |
| 8 | MSign figure is rebuilt from ``muse.core.msign`` with a fixed test key, and the numbers the page quotes |
| 9 | are read back from the code that enforces them. Known product defects stay documented as contract plus |
| 10 | warning (#241 defect-preservation rule): each is pinned here as a strict xfail against its product ticket, |
| 11 | so fixing the product fails the test and forces the page and the marker to change together. |
| 12 | """ |
| 13 | |
| 14 | from __future__ import annotations |
| 15 | |
| 16 | import hashlib |
| 17 | import html as html_lib |
| 18 | import re |
| 19 | from unittest.mock import patch |
| 20 | |
| 21 | import pytest |
| 22 | from fastapi import FastAPI |
| 23 | from fastapi.routing import APIRoute, iter_route_contexts |
| 24 | from fastapi.testclient import TestClient |
| 25 | from starlette.requests import Request |
| 26 | |
| 27 | from musehub.main import app |
| 28 | from tests.docs_contract import registry_check as rc |
| 29 | |
| 30 | PAGE = rc.phase_path("api") |
| 31 | HUB_ISSUES = "https://staging.musehub.ai/gabriel/musehub/issues/" |
| 32 | |
| 33 | # Product tickets the page's known-issue warnings link to (filed under #255, assigned to gabriel). |
| 34 | _T_TRANSFER = "306" # fixed: transfer moves the slug and authority (tests/test_musehub_repos.py) |
| 35 | _T_CURSOR = "308" # fixed: a malformed cursor is a 400 (tests/test_rest_invalid_cursor_308.py) |
| 36 | _T_RATELIMIT = "309" # fixed: no phantom default, {"detail"} 429, real Retry-After |
| 37 | _T_CASING = "310" # fixed: label/topic responses are camelCase (tests/test_rest_casing_310.py) |
| 38 | _T_VALIDATION = "311" # fixed: strict request bodies and list queries, real filters (tests/test_rest_strict_inputs_311.py) |
| 39 | _T_GAPS = "312" # fixed: GET /api/user, release DELETE, repo topics GET/PUT (tests/test_rest_gaps_312.py) |
| 40 | _LINKED = {"306", "308", "309", "178", "295", "66"} |
| 41 | |
| 42 | |
| 43 | @pytest.fixture(scope="module") |
| 44 | def raw(rendered: dict[str, str]) -> str: |
| 45 | return rendered[PAGE] |
| 46 | |
| 47 | |
| 48 | @pytest.fixture(scope="module") |
| 49 | def html(raw: str) -> str: |
| 50 | return raw.replace("'", "'").replace(""", '"').replace(""", '"') |
| 51 | |
| 52 | |
| 53 | def _text(fragment: str) -> str: |
| 54 | return html_lib.unescape(re.sub(r"<[^>]+>", "", fragment)) |
| 55 | |
| 56 | |
| 57 | def _flat(fragment: str) -> str: |
| 58 | return " ".join(_text(fragment).split()) |
| 59 | |
| 60 | |
| 61 | def _section(html: str, anchor: str) -> str: |
| 62 | rest = html.split(f'id="{anchor}"', 1)[1] |
| 63 | return rest.split("</section>", 1)[0] |
| 64 | |
| 65 | |
| 66 | def _tables(fragment: str) -> list[tuple[list[str], list[list[str]]]]: |
| 67 | """(header texts, rows of raw cell html) for every devdocs table in ``fragment``.""" |
| 68 | out = [] |
| 69 | for table in re.findall(r'<table class="devdocs-table[^"]*">(.*?)</table>', fragment, flags=re.S): |
| 70 | head = [_text(h).strip() for h in re.findall(r"<th[^>]*>(.*?)</th>", table, flags=re.S)] |
| 71 | rows = [re.findall(r"<td[^>]*>(.*?)</td>", r, flags=re.S) for r in re.findall(r"<tr>(.*?)</tr>", table, flags=re.S)] |
| 72 | out.append((head, [r for r in rows if r])) |
| 73 | return out |
| 74 | |
| 75 | |
| 76 | # ── Route table, read from the application ────────────────────────────────── |
| 77 | |
| 78 | |
| 79 | def _auth_of(route: APIRoute) -> tuple[str, str | None]: |
| 80 | kinds: list[str] = [] |
| 81 | scope: str | None = None |
| 82 | |
| 83 | def walk(dep: object) -> None: |
| 84 | nonlocal scope |
| 85 | for sub in dep.dependencies: # type: ignore[attr-defined] |
| 86 | call = sub.call |
| 87 | q = getattr(call, "__qualname__", "") |
| 88 | if "require_scope" in q and getattr(call, "__closure__", None): |
| 89 | for cell in call.__closure__: |
| 90 | if isinstance(cell.cell_contents, str): |
| 91 | scope = cell.cell_contents |
| 92 | kinds.append(q) |
| 93 | walk(sub) |
| 94 | |
| 95 | walk(route.dependant) |
| 96 | if any("require_signed_request" in k for k in kinds): |
| 97 | return "signed", scope |
| 98 | if any("optional_signed_request" in k for k in kinds): |
| 99 | return "optional", scope |
| 100 | return "none", scope |
| 101 | |
| 102 | |
| 103 | @pytest.fixture(scope="module") |
| 104 | def routes() -> dict[tuple[str, str], tuple[str, str | None]]: |
| 105 | # FastAPI 0.162 (the release image) keeps included routers as wrappers in app.routes, so walk the effective |
| 106 | # route contexts: each carries the mounted path and methods, and the original APIRoute (its dependant) for auth. |
| 107 | table: dict[tuple[str, str], tuple[str, str | None]] = {} |
| 108 | for ctx in iter_route_contexts(app.routes): |
| 109 | r, path = ctx.original_route, ctx.path or "" |
| 110 | if isinstance(r, APIRoute) and path.startswith("/api"): |
| 111 | for m in (ctx.methods or set()) - {"HEAD", "OPTIONS"}: |
| 112 | table.setdefault((m, path), _auth_of(r)) |
| 113 | assert len(table) > 100, f"route discovery found only {len(table)} /api routes" |
| 114 | return table |
| 115 | |
| 116 | |
| 117 | _SCOPE_RE = re.compile(r"\b((?:repo|issue|label|proposal|release|mist):(?:read|write))\b") |
| 118 | |
| 119 | |
| 120 | def _expand(path: str) -> str: |
| 121 | path = _text(path).strip() |
| 122 | if path.startswith("…"): |
| 123 | path = "/api/repos/{repo_id}" + path[1:] |
| 124 | return path.split("?", 1)[0] |
| 125 | |
| 126 | |
| 127 | def _documented_endpoints(html: str) -> list[tuple[str, str, str | None, str | None]]: |
| 128 | """(METHOD, path, auth kind or None, scope or None) for every row of every endpoint table.""" |
| 129 | rows: list[tuple[str, str, str | None, str | None]] = [] |
| 130 | for head, body in _tables(html): |
| 131 | if head[:2] == ["Method", "Path"]: |
| 132 | for cells in body: |
| 133 | method, path = _text(cells[0]).strip(), _expand(cells[1]) |
| 134 | auth = scope = None |
| 135 | if "Auth" in head: |
| 136 | a = _text(cells[head.index("Auth")]) |
| 137 | auth = "signed" if a.startswith("signed") else a.split()[0] |
| 138 | m = _SCOPE_RE.search(a) |
| 139 | scope = m.group(1) if m else None |
| 140 | rows.append((method, path, auth, scope)) |
| 141 | elif head[:1] == ["Path"] and len(head) == 2 and body and "…/branches" in body[0][0]: |
| 142 | for cells in body: # the "More endpoints" table: every <code> in the first cell is a GET path |
| 143 | for token in re.findall(r"<code>(.*?)</code>", cells[0], flags=re.S): |
| 144 | rows.append(("GET", _expand(token), "any", None)) |
| 145 | return rows |
| 146 | |
| 147 | |
| 148 | class TestRouteInventory: |
| 149 | """DOC_API_04: every documented METHOD path is a real route with the documented auth and scope.""" |
| 150 | |
| 151 | def test_endpoint_tables_parse(self, html: str) -> None: |
| 152 | rows = _documented_endpoints(html) |
| 153 | assert len(rows) >= 85, f"only {len(rows)} documented endpoints parsed" |
| 154 | |
| 155 | def test_every_documented_endpoint_is_routed(self, html: str, routes: dict) -> None: |
| 156 | missing = [f"{m} {p}" for m, p, _a, _s in _documented_endpoints(html) if (m, p) not in routes] |
| 157 | assert missing == [] |
| 158 | |
| 159 | def test_documented_auth_and_scope_match_the_dependencies(self, html: str, routes: dict) -> None: |
| 160 | wrong = [] |
| 161 | for m, p, auth, scope in _documented_endpoints(html): |
| 162 | if auth in (None, "any") or (m, p) not in routes: |
| 163 | continue |
| 164 | real_auth, real_scope = routes[(m, p)] |
| 165 | if auth != real_auth: |
| 166 | wrong.append(f"{m} {p}: documented {auth!r}, route is {real_auth!r}") |
| 167 | if scope is not None and scope != real_scope: |
| 168 | wrong.append(f"{m} {p}: documented scope {scope!r}, route requires {real_scope!r}") |
| 169 | assert wrong == [] |
| 170 | |
| 171 | def test_no_documented_scope_is_missing_on_a_scoped_write_route(self, html: str, routes: dict) -> None: |
| 172 | """A documented write route that really needs a scope must say which.""" |
| 173 | unscoped = [f"{m} {p}" for m, p, a, s in _documented_endpoints(html) |
| 174 | if a == "signed" and s is None and routes.get((m, p), ("", None))[1] is not None] |
| 175 | assert unscoped == [] |
| 176 | |
| 177 | def test_page_uses_no_version_prefix_or_slug_addressed_paths(self, html: str) -> None: |
| 178 | assert "/api/v1/repos" not in html |
| 179 | assert 'href="/api/v1/openapi.json"' not in html |
| 180 | assert "/repos/{owner}/{repo}" not in html |
| 181 | assert not [p for _m, p, _a, _s in _documented_endpoints(html) if p.startswith("/repos")] |
| 182 | |
| 183 | def test_the_operations_added_for_312_are_routed_and_documented(self, html: str, routes: dict) -> None: |
| 184 | documented = {(m, p) for m, p, _a, _s in _documented_endpoints(html)} |
| 185 | for key in [("GET", "/api/user"), ("DELETE", "/api/repos/{repo_id}/releases/{tag}"), |
| 186 | ("GET", "/api/repos/{repo_id}/topics"), ("PUT", "/api/repos/{repo_id}/topics")]: |
| 187 | assert key in routes and key in documented, key |
| 188 | assert ("POST", "/api/repos/{repo_id}/topics") not in routes # replaced by PUT, no alias |
| 189 | |
| 190 | def test_one_way_to_do_each_and_the_rest_stay_unsupported(self, routes: dict) -> None: |
| 191 | """Repository metadata is updated only through PATCH …/settings; the others have a documented equivalent |
| 192 | (PUT /api/users/{username}, PUT …/collaborators/{handle}/permission, PATCH …/labels/{label_id}).""" |
| 193 | for key in [("PATCH", "/api/repos/{repo_id}"), ("PATCH", "/api/user"), ("POST", "/api/repos/{repo_id}/forks"), |
| 194 | ("PATCH", "/api/repos/{repo_id}/collaborators/{handle}"), |
| 195 | ("PATCH", "/api/repos/{repo_id}/labels/{name}")]: |
| 196 | assert key not in routes, f"{key} is routed: a second way to do one thing" |
| 197 | |
| 198 | |
| 199 | # ── MSign ─────────────────────────────────────────────────────────────────── |
| 200 | |
| 201 | _SEED = bytes([1]) * 32 # public test vector, never a real key |
| 202 | _TS = 1744000000 |
| 203 | _BODY = b'{"title":"First issue"}' |
| 204 | _REPO_ID = "sha256:" + hashlib.sha256(b"musehub-docs-api-fixture").hexdigest() |
| 205 | _PATH = f"/api/repos/{_REPO_ID}/issues" |
| 206 | |
| 207 | |
| 208 | class TestMSign: |
| 209 | def _built(self) -> dict[str, str]: |
| 210 | from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey |
| 211 | |
| 212 | from muse.core.msign import build_msign_header, canonical_message |
| 213 | from muse.core.transport import SigningIdentity |
| 214 | from muse.core.types import b64url_encode |
| 215 | |
| 216 | priv = Ed25519PrivateKey.from_private_bytes(_SEED) |
| 217 | msg = canonical_message("POST", _PATH, _TS, _BODY, host="musehub.ai") |
| 218 | sig = b64url_encode(priv.sign(msg)) |
| 219 | header = build_msign_header(SigningIdentity(handle="gabriel", private_key=priv), "POST", |
| 220 | f"https://MuseHub.ai:443{_PATH}", _BODY, ts=_TS) |
| 221 | return {"message": msg.decode(), "sig": sig, "header": header, "pub": b64url_encode(priv.public_key().public_bytes_raw())} |
| 222 | |
| 223 | def test_figure_lines_signature_and_header_are_rebuilt_from_the_client_library(self, html: str) -> None: |
| 224 | built = self._built() |
| 225 | fig = html.split('id="msign-anatomy"', 1)[1].split("</figure>", 1)[0] |
| 226 | lines = built["message"].split("\n") |
| 227 | assert len(lines) == 6 |
| 228 | text = _text(fig) |
| 229 | for line in lines: |
| 230 | assert line in text, f"figure is missing canonical line {line!r}" |
| 231 | assert built["sig"] in text |
| 232 | assert built["header"] in text |
| 233 | assert built["header"].endswith(f'sig="{built["sig"]}"') |
| 234 | assert lines[5] == "sha256:" + hashlib.sha256(_BODY).hexdigest() |
| 235 | |
| 236 | def test_figure_signature_verifies_against_the_fixed_public_key(self) -> None: |
| 237 | from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey |
| 238 | |
| 239 | from muse.core.types import b64url_decode |
| 240 | |
| 241 | built = self._built() |
| 242 | pub = Ed25519PublicKey.from_public_bytes(b64url_decode(built["pub"])) |
| 243 | pub.verify(b64url_decode(built["sig"]), built["message"].encode()) # raises InvalidSignature on drift |
| 244 | |
| 245 | def test_server_and_client_build_identical_canonical_bytes(self) -> None: |
| 246 | from muse.core.msign import canonical_message |
| 247 | from musehub.auth.request_signing import build_canonical_message |
| 248 | |
| 249 | for body in (b"", _BODY): |
| 250 | assert build_canonical_message("post", _PATH, _TS, body, host="musehub.ai") == \ |
| 251 | canonical_message("POST", _PATH, _TS, body, host="musehub.ai") |
| 252 | |
| 253 | def test_empty_body_signs_the_hash_of_empty_bytes_not_an_empty_line(self, html: str) -> None: |
| 254 | from musehub.auth.request_signing import build_canonical_message |
| 255 | |
| 256 | last = build_canonical_message("GET", "/api/repos", _TS, b"", host="musehub.ai").decode().split("\n")[-1] |
| 257 | assert last == "sha256:" + hashlib.sha256(b"").hexdigest() |
| 258 | assert last.startswith("sha256:e3b0c442") and last.endswith("7852b855") |
| 259 | assert "sha256:e3b0c442…b855" in _text(_section(html, "auth")) |
| 260 | |
| 261 | def test_header_regex_requires_alg(self) -> None: |
| 262 | from musehub.auth.request_signing import _parse_msign_header |
| 263 | |
| 264 | ok = 'MSign handle="gabriel" alg="ed25519" ts=1744000000 sig="abc"' |
| 265 | assert _parse_msign_header(ok) == ("gabriel", "ed25519", 1744000000, "abc") |
| 266 | assert _parse_msign_header('MSign handle="gabriel" ts=1744000000 sig="abc"') is None |
| 267 | |
| 268 | def test_freshness_window_is_thirty_seconds(self, html: str) -> None: |
| 269 | from musehub.auth.request_signing import REPLAY_WINDOW_SECONDS |
| 270 | |
| 271 | assert REPLAY_WINDOW_SECONDS == 30 |
| 272 | assert "|now − ts| > 30" in html or "|now − ts| > 30" in _text(html) |
| 273 | |
| 274 | def test_page_does_not_claim_single_use_replay_protection(self, html: str) -> None: |
| 275 | auth = _flat(_section(html, "auth")) |
| 276 | assert "freshness window, not single-use replay protection" in auth |
| 277 | assert "accepted both times" in auth |
| 278 | |
| 279 | def test_openapi_description_example_is_accepted_by_the_verifier(self) -> None: |
| 280 | from musehub.auth.request_signing import _parse_msign_header |
| 281 | |
| 282 | example = re.search(r'Authorization: (MSign handle="[^"]+"[^`\n]*)', app.description.replace('\\"', '"')) |
| 283 | assert example is not None |
| 284 | header = example.group(1).replace("<unix>", "1744000000").replace("<b64url>", "abc") |
| 285 | assert _parse_msign_header(header) is not None |
| 286 | |
| 287 | def test_openapi_description_states_the_private_repo_answers(self) -> None: |
| 288 | """musehub#314: the public-read sentence also says what an anonymous or unauthorised private read gets.""" |
| 289 | text = " ".join(app.description.split()) |
| 290 | assert "Public repo read endpoints accept unauthenticated requests" in text |
| 291 | assert "A private repo answers 401 to an anonymous request and 404 to a signed caller with no access." in text |
| 292 | |
| 293 | def test_scope_names_on_the_page_are_the_scopes_the_routes_use(self, html: str, routes: dict) -> None: |
| 294 | used = {s for _a, s in routes.values() if s} |
| 295 | listed = set(re.findall(r"<code>((?:repo|issue|label|proposal|release|mist):(?:read|write))</code>", _section(html, "auth"))) |
| 296 | assert listed == used |
| 297 | |
| 298 | |
| 299 | # ── Errors, pagination, rate limits ───────────────────────────────────────── |
| 300 | |
| 301 | |
| 302 | @pytest.fixture(scope="module") |
| 303 | def client(): # noqa: ANN201 |
| 304 | """The app with no lifespan and no database: ``get_db`` is replaced by a session that is never used, |
| 305 | because every request below is refused (401, 422) before a handler could query.""" |
| 306 | from musehub.db.database import get_db |
| 307 | |
| 308 | async def _no_db(): # noqa: ANN202 |
| 309 | yield None |
| 310 | |
| 311 | app.dependency_overrides[get_db] = _no_db |
| 312 | try: |
| 313 | yield TestClient(app) # no context manager → no lifespan |
| 314 | finally: |
| 315 | app.dependency_overrides.pop(get_db, None) |
| 316 | |
| 317 | |
| 318 | class TestErrorsAndPagination: |
| 319 | def test_401_body_and_challenge_header(self, client: TestClient, html: str) -> None: |
| 320 | r = client.get("/api/repos") |
| 321 | assert r.status_code == 401 |
| 322 | assert r.json() == {"detail": "MSign Authorization header required."} |
| 323 | assert r.headers["www-authenticate"] == 'MSign realm="musehub"' |
| 324 | assert "MSign Authorization header required." in _text(html) |
| 325 | |
| 326 | def test_malformed_and_wrong_scheme_headers(self, client: TestClient) -> None: |
| 327 | bad = client.get("/api/repos", headers={"Authorization": 'MSign handle="a"'}) |
| 328 | assert (bad.status_code, bad.json()["detail"]) == (401, "Malformed MSign header.") |
| 329 | bearer = client.get("/api/repos", headers={"Authorization": "Bearer abc"}) |
| 330 | assert (bearer.status_code, bearer.headers["www-authenticate"]) == (401, 'MSign realm="musehub"') |
| 331 | |
| 332 | def test_validation_errors_are_a_list_under_detail(self, client: TestClient) -> None: |
| 333 | r = client.get("/api/repos/sha256:x/issues?limit=0") |
| 334 | assert r.status_code == 422 |
| 335 | entry = r.json()["detail"][0] |
| 336 | assert {"type", "loc", "msg", "input", "ctx"} <= set(entry) and entry["loc"] == ["query", "limit"] |
| 337 | |
| 338 | def test_limit_bounds_are_the_ones_the_page_states(self, html: str) -> None: |
| 339 | spec = app.openapi() |
| 340 | for path in ("/api/repos/{repo_id}/issues", "/api/repos/{repo_id}/proposals", "/api/repos/{repo_id}/releases", |
| 341 | "/api/repos/{repo_id}/webhooks", "/api/repos/{repo_id}/issues/{issue_number}/comments"): |
| 342 | limit = next(p for p in spec["paths"][path]["get"]["parameters"] if p["name"] == "limit")["schema"] |
| 343 | assert (limit["minimum"], limit["maximum"], limit["default"]) == (1, 200, 20), path |
| 344 | mine = next(p for p in spec["paths"]["/api/repos"]["get"]["parameters"] if p["name"] == "limit")["schema"] |
| 345 | assert (mine["minimum"], mine["maximum"], mine["default"]) == (1, 100, 20) |
| 346 | assert "<code>1</code>–<code>200</code>" in html and "<code>1</code>–<code>100</code>" in html |
| 347 | |
| 348 | def test_pagination_envelope_and_link_header_builder(self) -> None: |
| 349 | from starlette.requests import Request |
| 350 | |
| 351 | from musehub.api.routes.musehub.pagination import build_cursor_link_header |
| 352 | from musehub.core.public_urls import public_base_url |
| 353 | |
| 354 | req = Request({"type": "http", "method": "GET", "scheme": "http", "path": "/api/repos/x/issues", "query_string": b"state=open&limit=5", |
| 355 | "headers": [(b"host", b"h")], "server": ("h", 80)}) |
| 356 | link = build_cursor_link_header(req, "4", 2) |
| 357 | # an unlisted Host is never echoed: the link is built on the public base (musehub#276), filters kept, limit/cursor replaced |
| 358 | assert link == f'<{public_base_url(None)}/api/repos/x/issues?state=open&limit=2&cursor=4>; rel="next"' |
| 359 | |
| 360 | def test_malformed_cursors_are_rejected_before_they_are_parsed(self) -> None: |
| 361 | import inspect |
| 362 | |
| 363 | from musehub.services import musehub_issues |
| 364 | |
| 365 | src = inspect.getsource(musehub_issues.list_issues) |
| 366 | assert not re.search(r"(?<![\w.])int\(cursor\)", src), "issues cursor is parsed with a bare int()" |
| 367 | assert "cursor_int(cursor)" in src |
| 368 | |
| 369 | def test_pagination_documents_the_invalid_cursor_400(self, html: str) -> None: |
| 370 | pagination = _flat(_section(html, "pagination")) |
| 371 | assert '400 and {"detail": "invalid cursor"}' in pagination |
| 372 | assert f"{HUB_ISSUES}{_T_CURSOR}" not in html and f"musehub#{_T_CURSOR}" not in _text(html) |
| 373 | |
| 374 | def test_documented_error_shapes_exist_in_the_page(self, html: str) -> None: |
| 375 | errors = _flat(_section(html, "errors")) |
| 376 | assert '{"detail": "rate limit exceeded: 20 per 1 minute"}' in errors |
| 377 | assert '{"detail": "Repo not found"}' in errors |
| 378 | assert '"error": {"code"' not in html # the invented {error: {code, message, docs}} envelope stays gone |
| 379 | |
| 380 | |
| 381 | class TestRateLimits: |
| 382 | @staticmethod |
| 383 | def _mini() -> TestClient: |
| 384 | """A route decorated exactly like the issue-create route, behind the app's own limiter and 429 handler.""" |
| 385 | from slowapi.errors import RateLimitExceeded |
| 386 | |
| 387 | from musehub.main import _handle_rate_limit |
| 388 | from musehub.rate_limits import ISSUE_CREATE_LIMIT, get_msign_handle, limiter |
| 389 | |
| 390 | mini = FastAPI() |
| 391 | mini.state.limiter = limiter |
| 392 | mini.add_exception_handler(RateLimitExceeded, _handle_rate_limit) |
| 393 | |
| 394 | @mini.post("/issues") |
| 395 | @limiter.limit(ISSUE_CREATE_LIMIT, key_func=get_msign_handle) |
| 396 | async def create(request: Request) -> dict[str, bool]: |
| 397 | return {"ok": True} |
| 398 | |
| 399 | limiter.reset() |
| 400 | return TestClient(mini) |
| 401 | |
| 402 | def test_issue_create_is_20_per_minute_per_handle_and_the_429_shape(self, html: str) -> None: |
| 403 | from musehub.rate_limits import ISSUE_COMMENT_LIMIT, ISSUE_CREATE_LIMIT, WIRE_FETCH_LIMIT, WIRE_PUSH_LIMIT, limiter |
| 404 | |
| 405 | assert (ISSUE_CREATE_LIMIT, ISSUE_COMMENT_LIMIT, WIRE_PUSH_LIMIT, WIRE_FETCH_LIMIT) == \ |
| 406 | ("20/minute", "60/minute", "30/minute", "120/minute") |
| 407 | client = self._mini() |
| 408 | alice = {"Authorization": 'MSign handle="alice" alg="ed25519" ts=1 sig="x"'} |
| 409 | bob = {"Authorization": 'MSign handle="bob" alg="ed25519" ts=1 sig="x"'} |
| 410 | try: |
| 411 | assert [client.post("/issues", headers=alice).status_code for _ in range(20)] == [200] * 20 |
| 412 | refused = client.post("/issues", headers=alice) |
| 413 | assert refused.status_code == 429 |
| 414 | assert refused.json() == {"detail": "rate limit exceeded: 20 per 1 minute"} |
| 415 | assert 1 <= int(refused.headers["retry-after"]) <= 60 # the time left in the bucket, not a constant |
| 416 | assert not [h for h in refused.headers if h.lower().startswith("x-ratelimit")] |
| 417 | assert client.post("/issues", headers=bob).status_code == 200 # another handle has its own bucket |
| 418 | finally: |
| 419 | limiter.reset() |
| 420 | text = _flat(_section(html, "rate-limits")) |
| 421 | assert "20 (the 21st is refused)" in text and "60 (the 61st is refused)" in text |
| 422 | |
| 423 | def test_buckets_are_fixed_windows(self) -> None: |
| 424 | from musehub.rate_limits import limiter |
| 425 | |
| 426 | assert type(limiter._limiter).__name__ == "FixedWindowRateLimiter" |
| 427 | |
| 428 | def test_no_default_limit_is_claimed_or_documented(self, html: str) -> None: |
| 429 | """musehub#309 resolved by removing the never-applied 300/min default (no SlowAPIMiddleware); the page says so.""" |
| 430 | from musehub.rate_limits import limiter |
| 431 | |
| 432 | assert not getattr(limiter, "_default_limits", []) |
| 433 | assert not any(getattr(m.cls, "__name__", "") == "SlowAPIMiddleware" for m in app.user_middleware) |
| 434 | text = _flat(_section(html, "rate-limits")) |
| 435 | assert "300" not in text and f"musehub#{_T_RATELIMIT}" not in _text(html) |
| 436 | |
| 437 | |
| 438 | # ── Example bodies against the schemas ────────────────────────────────────── |
| 439 | |
| 440 | _TOP_KEY = re.compile(r'^ "(\w+)":', re.M) |
| 441 | _RESPONSES = { |
| 442 | "Repo object": "RepoResponse", "Issue object": "IssueResponse", "Proposal object": "ProposalResponse", |
| 443 | "Release object": "ReleaseResponse", "Collaborator object": "CollaboratorResponse", |
| 444 | "Label object and list": "LabelResponse", "Fork response": "UserForkedRepoEntry", |
| 445 | "User object (public)": "ProfileResponse", "Replace topics": None, "Response": "RepoTopicsResponse", |
| 446 | "Current user": "CurrentUserResponse", |
| 447 | } |
| 448 | _REQUESTS = { |
| 449 | "Create repo — request body": "CreateRepoRequest", "Create issue — request body": "IssueCreate", |
| 450 | "Create proposal — request body": "ProposalCreate", "Create release — request body": "ReleaseCreate", |
| 451 | "Invite collaborator": "CollaboratorInviteRequest", "Create label": "LabelCreate", |
| 452 | "Register webhook": "WebhookCreate", "Replace topics": "SetTopicsRequest", "Update profile": "ProfileUpdateRequest", |
| 453 | } |
| 454 | |
| 455 | |
| 456 | def _example_after(html: str, heading: str) -> str: |
| 457 | part = html.split(f">{heading}</h3>", 1) |
| 458 | assert len(part) == 2, f"no heading {heading!r}" |
| 459 | return part[1].split("</pre>", 1)[0].split("<pre", 1)[1].split(">", 1)[1] |
| 460 | |
| 461 | |
| 462 | def _props(name: str) -> set[str]: |
| 463 | from musehub.models.base import to_camel |
| 464 | |
| 465 | spec = app.openapi()["components"]["schemas"][name] |
| 466 | props = set(spec["properties"]) |
| 467 | return props | {p for p in props} | {to_camel(p) for p in props} |
| 468 | |
| 469 | |
| 470 | class TestExamplesMatchSchemas: |
| 471 | @pytest.mark.parametrize("heading,schema", [(h, s) for h, s in _RESPONSES.items() if s]) |
| 472 | def test_response_example_keys_exist_on_the_response_model(self, html: str, heading: str, schema: str) -> None: |
| 473 | keys = set(_TOP_KEY.findall(_text(_example_after(html, heading)))) |
| 474 | assert keys, heading |
| 475 | unknown = keys - _props(schema) |
| 476 | assert unknown == set(), f"{heading}: not on {schema}: {sorted(unknown)}" |
| 477 | |
| 478 | @pytest.mark.parametrize("heading,schema", list(_REQUESTS.items())) |
| 479 | def test_request_example_keys_exist_on_the_request_model(self, html: str, heading: str, schema: str) -> None: |
| 480 | block = _text(_example_after(html, heading)) |
| 481 | keys = set(re.findall(r'^\s{0,2}"(\w+)":', block, re.M)) |
| 482 | assert keys, heading |
| 483 | unknown = keys - _props(schema) |
| 484 | assert unknown == set(), f"{heading}: not on {schema}: {sorted(unknown)}" |
| 485 | |
| 486 | def test_proposal_and_issue_bodies_use_the_real_field_names(self, html: str) -> None: |
| 487 | assert "into_branch" not in _text(html).replace("not <code>into_branch</code>", "").replace("not into_branch", "") |
| 488 | assert '"assignees"' not in _text(_example_after(html, "Create issue — request body")) |
| 489 | assert '"status"' not in _text(_example_after(html, "Create issue — request body")) |
| 490 | |
| 491 | def test_label_and_topic_responses_are_camel_case(self) -> None: |
| 492 | """musehub#310 fixed; the schema walk over every response model is tests/test_rest_casing_310.py.""" |
| 493 | schemas = app.openapi()["components"]["schemas"] |
| 494 | snake = {n: [p for p in schemas[n]["properties"] if "_" in p] for n in ("LabelResponse", "RepoTopicsResponse", "TopicItem")} |
| 495 | assert snake == {"LabelResponse": [], "RepoTopicsResponse": [], "TopicItem": []} |
| 496 | |
| 497 | def test_label_delete_removes_the_name_from_issues_and_the_page_says_so(self, html: str) -> None: |
| 498 | import inspect |
| 499 | |
| 500 | from musehub.api.routes.musehub import labels |
| 501 | |
| 502 | src = inspect.getsource(labels.delete_label) |
| 503 | assert "UPDATE musehub_issues SET labels = array_remove" in src # the name leaves every issue's label array |
| 504 | assert "its name is removed from every issue and proposal that carries it" in _flat(_section(html, "labels")) |
| 505 | |
| 506 | def test_request_id_header_is_set_on_every_response(self, html: str) -> None: |
| 507 | import inspect |
| 508 | |
| 509 | from musehub.middleware import access_log |
| 510 | |
| 511 | assert "X-Request-Id" in inspect.getsource(access_log) |
| 512 | assert "X-Request-Id" in _flat(_section(html, "errors")) |
| 513 | |
| 514 | def test_page_shows_label_and_topic_responses_in_camel_case(self, html: str) -> None: |
| 515 | text = _text(html) |
| 516 | for gone in ('"label_id"', '"repo_id"', '"repo_count"', '{"items"', "three exceptions"): |
| 517 | assert gone not in text, gone |
| 518 | assert '"labelId"' in _text(_example_after(html, "Label object and list")) |
| 519 | assert '{"labels": [' in _text(_example_after(html, "Label object and list")) |
| 520 | assert '"repoCount"' in _flat(_section(html, "topics")) |
| 521 | assert f"gabriel/musehub#{_T_CASING}" not in text |
| 522 | |
| 523 | def test_write_models_reject_unknown_fields(self, html: str) -> None: |
| 524 | from musehub.models.musehub import IssueUpdate, ProposalMergeRequest |
| 525 | |
| 526 | assert IssueUpdate.model_config.get("extra") == "forbid" |
| 527 | assert ProposalMergeRequest.model_config.get("extra") == "forbid" |
| 528 | assert "extra_forbidden" in _flat(_section(html, "errors")) |
| 529 | assert "such as strategy, is 422 naming it" in _flat(_section(html, "proposals")) |
| 530 | |
| 531 | def test_repo_create_visibility_is_an_enum(self) -> None: |
| 532 | spec = app.openapi()["components"]["schemas"]["CreateRepoRequest"]["properties"]["visibility"] |
| 533 | assert spec.get("enum") == ["public", "private"], spec |
| 534 | |
| 535 | def test_list_filters_on_the_page_are_the_route_parameters(self, html: str) -> None: |
| 536 | paths = app.openapi()["paths"] |
| 537 | for path, filters in (("/api/repos/{repo_id}/issues", {"state", "label", "assignee"}), |
| 538 | ("/api/repos/{repo_id}/releases", {"channel", "draft"})): |
| 539 | names = {p["name"] for p in paths[path]["get"]["parameters"] if p["in"] == "query"} |
| 540 | assert names == filters | {"cursor", "limit"}, (path, names) |
| 541 | assert "?assignee=handle" in _flat(_section(html, "issues")) |
| 542 | assert "?draft=true lists only drafts" in _flat(_section(html, "releases")) |
| 543 | assert "must be SemVer" in _flat(_section(html, "releases")) |
| 544 | assert "ignoring case" in _flat(_section(html, "labels")) |
| 545 | assert f"musehub#{_T_VALIDATION}" not in _text(html) |
| 546 | |
| 547 | |
| 548 | # ── Proposal diff dimensions (musehub#313) ────────────────────────────────── |
| 549 | |
| 550 | |
| 551 | class TestDiffDimensions: |
| 552 | def test_the_dimension_table_is_the_engines(self, html: str) -> None: |
| 553 | from musehub.services.musehub_divergence import dimensions_for_domain |
| 554 | |
| 555 | rows = {_flat(r[0]): [_flat(c) for c in re.findall(r"<code>(.*?)</code>", r[1])] |
| 556 | for head, body in _tables(_section(html, "proposals")) if head[:2] == ["Domain", "Dimensions"] for r in body} |
| 557 | code_row = next(v for k, v in rows.items() if k.startswith("code")) |
| 558 | assert tuple(code_row) == dimensions_for_domain("code") == dimensions_for_domain(None) == dimensions_for_domain("mist") |
| 559 | assert tuple(rows["midi"]) == dimensions_for_domain("midi") |
| 560 | |
| 561 | def test_the_diff_summary_figures_are_the_engines(self, html: str) -> None: |
| 562 | from musehub.services.musehub_divergence import change_count_score |
| 563 | |
| 564 | assert (change_count_score(0), change_count_score(1), change_count_score(2), change_count_score(99)) == (0.0, 0.35, 0.5, 0.95) |
| 565 | assert "0.35 for one change and 0.15 more per further change, up to 0.95" in _flat(_section(html, "proposals")) |
| 566 | |
| 567 | def test_no_page_text_says_every_domain_gets_music_dimensions(self, html: str) -> None: |
| 568 | text = _flat(html) |
| 569 | assert "Proposals warning" not in text and "Known defect in rc20 (gabriel/musehub#313)" not in text |
| 570 | assert "musehub#313" not in text |
| 571 | |
| 572 | |
| 573 | # ── Webhooks ──────────────────────────────────────────────────────────────── |
| 574 | |
| 575 | |
| 576 | def _dispatched_events() -> set[str]: |
| 577 | import pathlib |
| 578 | |
| 579 | root = pathlib.Path(__file__).resolve().parents[2] / "musehub" |
| 580 | found: set[str] = set() |
| 581 | for f in root.rglob("*.py"): |
| 582 | text = f.read_text() |
| 583 | found |= set(re.findall(r"dispatch_event_background,\s*repo_id,\s*\"(\w+)\"", text)) |
| 584 | found |= set(re.findall(r"emit_event\([^,]+,\s*\"(\w+)\"", text)) |
| 585 | return found |
| 586 | |
| 587 | |
| 588 | class TestWebhooks: |
| 589 | def test_registrable_events_are_the_eight_on_the_page(self, html: str) -> None: |
| 590 | from musehub.models.musehub import WEBHOOK_EVENT_TYPES |
| 591 | |
| 592 | rows = {_text(c[0]).strip(): _text(c[2]).strip() for head, body in _tables(_section(html, "webhooks")) |
| 593 | if head == ["Event", "Can be registered", "Delivered today"] for c in body} |
| 594 | assert set(rows) == set(WEBHOOK_EVENT_TYPES) |
| 595 | |
| 596 | def test_the_events_marked_not_delivered_are_exactly_the_ones_no_route_dispatches(self, html: str) -> None: |
| 597 | from musehub.models.musehub import WEBHOOK_EVENT_TYPES |
| 598 | |
| 599 | rows = {_text(c[0]).strip(): _text(c[2]).strip() for head, body in _tables(_section(html, "webhooks")) |
| 600 | if head == ["Event", "Can be registered", "Delivered today"] for c in body} |
| 601 | not_delivered = {e for e, v in rows.items() if v.startswith("not delivered")} |
| 602 | assert not_delivered == set(WEBHOOK_EVENT_TYPES) - _dispatched_events() |
| 603 | |
| 604 | def test_every_registrable_event_is_dispatched_by_some_route(self) -> None: |
| 605 | from musehub.models.musehub import WEBHOOK_EVENT_TYPES |
| 606 | |
| 607 | assert _dispatched_events() == set(WEBHOOK_EVENT_TYPES) |
| 608 | |
| 609 | def test_issue_actions_are_the_ones_the_routes_send(self, html: str) -> None: |
| 610 | import inspect |
| 611 | |
| 612 | from musehub.api.routes.musehub import issues |
| 613 | |
| 614 | actions = set(re.findall(r'"action": "(\w+)"', inspect.getsource(issues))) |
| 615 | assert actions == {"opened", "closed", "reopened"} # musehub#304: reopen is no longer sent as "opened" |
| 616 | row = _flat(_section(html, "webhooks")) |
| 617 | assert 'Issue opened, closed and reopened (action "opened", "closed", "reopened")' in row |
| 618 | |
| 619 | def test_retry_policy_numbers(self, html: str) -> None: |
| 620 | from musehub.services import musehub_webhook_dispatcher as d |
| 621 | |
| 622 | assert (d._MAX_ATTEMPTS, d._BACKOFF_BASE, d._REQUEST_TIMEOUT) == (3, 1.0, 10.0) |
| 623 | text = _flat(_section(html, "webhooks")) |
| 624 | assert "up to three attempts, waiting 1 s and then 2 s" in text and "10-second timeout" in text |
| 625 | |
| 626 | def test_the_pages_verify_snippet_accepts_what_the_dispatcher_signs(self, html: str) -> None: |
| 627 | from musehub.services import musehub_webhook_dispatcher as d |
| 628 | |
| 629 | block = _text(_example_after(html, "Signature verification")) |
| 630 | ns: dict[str, object] = {} |
| 631 | exec(block.split("# In your handler:")[0], ns) # noqa: S102 — the page's own snippet, defining verify() |
| 632 | body = b'{"action":"opened"}' |
| 633 | signed = d._sign_payload("s3cr3t", body) |
| 634 | assert signed.startswith("sha256=") |
| 635 | assert ns["verify"]("s3cr3t", body, signed) is True # type: ignore[operator] |
| 636 | assert ns["verify"]("wrong", body, signed) is False # type: ignore[operator] |
| 637 | |
| 638 | def test_delivery_headers_and_ssrf_wording(self, html: str) -> None: |
| 639 | import inspect |
| 640 | |
| 641 | from musehub.services import musehub_webhook_dispatcher as d |
| 642 | |
| 643 | src = inspect.getsource(d._attempt_delivery) |
| 644 | for header in ("X-MuseHub-Event", "X-MuseHub-Delivery", "X-MuseHub-Signature", "MuseHub-Webhook/1.0"): |
| 645 | assert header in src and header in _flat(_section(html, "webhooks")) |
| 646 | assert "validate_outbound_url" in src |
| 647 | |
| 648 | def test_registration_rejects_http_and_private_targets(self) -> None: |
| 649 | from pydantic import ValidationError |
| 650 | |
| 651 | from musehub.models.musehub import WebhookCreate |
| 652 | |
| 653 | for url in ("http://ci.example.com/x", "https://127.0.0.1/x", "https://169.254.169.254/x"): |
| 654 | with pytest.raises(ValidationError): |
| 655 | WebhookCreate(url=url, events=["issue"]) |
| 656 | assert WebhookCreate(url="https://ci.example.com/x", events=["issue"]).secret == "" |
| 657 | |
| 658 | |
| 659 | # ── Page-level guards ─────────────────────────────────────────────────────── |
| 660 | |
| 661 | |
| 662 | class TestPageGuards: |
| 663 | def test_every_ticket_the_page_links_is_one_of_the_known_issues(self, html: str) -> None: |
| 664 | linked = set(re.findall(r"gabriel/musehub#(\d+)", _text(html))) | set(re.findall(rf"{re.escape(HUB_ISSUES)}(\d+)", html)) |
| 665 | assert linked <= _LINKED, f"unexpected ticket references: {sorted(linked - _LINKED)}" |
| 666 | assert not {_T_TRANSFER, _T_CASING, _T_VALIDATION, _T_GAPS} & linked |
| 667 | |
| 668 | def test_known_issues_table_lists_each_ticket_once(self, html: str) -> None: |
| 669 | table = _tables(_section(html, "known-issues"))[0][1] |
| 670 | ids = [re.search(r"musehub#(\d+)", _text(r[0])).group(1) for r in table] # type: ignore[union-attr] |
| 671 | assert len(ids) == len(set(ids)) |
| 672 | assert not {_T_TRANSFER, _T_CASING, _T_VALIDATION, _T_GAPS} & set(ids) |
| 673 | |
| 674 | def test_figure_has_caption_source_and_no_script(self, html: str) -> None: |
| 675 | fig = html.split('id="msign-anatomy"', 1)[1].split("</figure>", 1)[0] |
| 676 | assert 'aria-labelledby="msign-anatomy-title"' in html |
| 677 | assert "docfig__source" in fig and "<script" not in fig |
| 678 | assert fig.count("msgfig__line") >= 6 |
| 679 | |
| 680 | def test_sections_in_the_sidebar_exist(self, html: str) -> None: |
| 681 | for anchor in re.findall(r'href="#([\w-]+)"', html.split("</aside>", 1)[0]): |
| 682 | assert f'id="{anchor}"' in html, anchor |
| 683 | |
| 684 | def test_prose_never_documents_the_removed_envelope_or_fields(self, html: str) -> None: |
| 685 | text = _text(html) |
| 686 | for gone in ("invalid_semver", "timestamp_expired", "ref_conflict", "validation_error", "merge_conflict", |
| 687 | "X-RateLimit-Limit: 300", "Rate-limit state is returned on every response", "301 Moved Permanently", |
| 688 | "sliding 60-second", "60 (IP-keyed)"): |
| 689 | assert gone not in text, gone |
File History
20 commits
sha256:6492a128c2a7aa4605102b380091a2192022e47d2bd3b35aac7e7596423317aa
fix(repos): a transfer moves the owner slug and owner autho…
Opus 5.5
minor
⚠
1 day ago
sha256:9511d1c6e932d9f45df27b37c9d9d2efa4aedb53c0061b2e80de2f2574ce0636
docs(mists,api): Muse 0.2.2rc6 fixes muse#210/#211 — drop t…
Opus 5.5
patch
1 day ago
sha256:8142f1f2556a271f60c48e1e5c43f8d47fa28e6ac888651ce5cbc48211628ce8
fix(rest): strict REST inputs — unknown body fields and lis…
Opus 5.5
minor
⚠
1 day ago
sha256:8157b0df0e2312254edef68f882db2e510f21a94655f46def61a00abc850c106
Merge branch 'task/wave-hub-rest-310-312' into dev
Opus 5.5
minor
⚠
1 day ago
sha256:157f2b8f3de428f54183520d5e16e7b0627b03322fc6a68f44a4d40b58e887b1
feat(rest): current user, release delete, repo topics GET/P…
Opus 5.5
minor
⚠
1 day ago
sha256:adcba83c3f339337ce2a7d7233d02752c77a3eb236ab38affa548699dba957dd
fix(rest): label and topic responses are camelCase (#310)
Opus 5.5
minor
⚠
1 day ago
sha256:f01bf034eb409e79373775083966fb6d1ecaefb4ac3b2e7e6d8beaeb555259df
fix(rest): one honest rate-limit contract (#309); the pagin…
Opus 5.5
minor
⚠
1 day ago
sha256:299f7e61ed29513b71569e957cfd8ce55e2132041d220b1387ce0b43b12a3d92
Merge branch 'task/313-on-dev' into dev
Opus 5.5
minor
⚠
1 day ago
sha256:dc8a25669115527392507de6bb24bd7a06c109fdc1814cf7bed97ec10c835acb
fix(proposals): diff, compare, divergence and diff-summary …
Opus 5.5
minor
⚠
1 day ago
sha256:0ee8d0cfba18a9463727bbdc1dec6d33eeeae3d1c6fbbeb283b39db7bfe6657a
Merge branch 'task/rest-308-312' into dev
Opus 5.5
patch
1 day ago
sha256:762ad834cc326a18fd5ecb62f465e1ed59dac9cb7418674fd2c279dacc9febf4
fix(rest): a malformed pagination cursor is a 400 on every …
Opus 5.5
patch
1 day ago
sha256:b6c0bf4d4a047b432e15f1e74dd72a51b3a2b0c7bf11996680a5a91a0068ffe9
feat(webhooks): dispatch all eight events; deactivate a hoo…
Opus 5.5
patch
1 day ago
sha256:f19d5e4a89766fc91b926cdf801255e12dcd968041c0ece8adf6627760788d22
merge: next build — MCP (#291 #292 #295 #324), profiles/sit…
Opus 5.5
minor
⚠
1 day ago
sha256:7a1f4dfd571e937cb1032574d5c0965ba04ad520adcf523dec123d7a34746236
merge: rc26 — profiles/site wave (#119 #301 #303 #307 #314;…
Opus 5.5
minor
⚠
1 day ago
sha256:b68525cb97da48043fbcfe0a9b90bd8ec6ca6b34208110ce30110d4c4ced815c
fix(webhooks): reopening an issue sends action "reopened", …
Opus 5.5
minor
⚠
2 days ago
sha256:637e8821e77b2fef383d3020c15eafebaacd9d46ed7402e31aeba023b3a11ced
fix(export): GET /api/me/export no longer 500s for accounts…
Opus 5.5
patch
2 days ago
sha256:a4874ea21990b96dd0488fab5d5fe5a559838b9a8c8197da2e522dde57f15b43
docs(openapi): state the private-repo 401/404 next to the p…
Opus 5.5
patch
2 days ago
sha256:5534d428bcfa91a4702a48dc910275111fa389a6eba87d45ea026122b5ecb676
docs(api): drop the resolved musehub#314 known issue
Sonnet 5.5
patch
6 days ago
sha256:c3ad0d4c734b45818a7df5fb9a6b265d192a26e4d9173c902fbdfcbc3a8d06da
test(docs): drop the stale musehub#314 xfail on the OpenAPI…
Sonnet 5.5
6 days ago
sha256:640b1b697a985d9b4b34c55f41da13269f96a8829a57a9c7ff19245b1474de90
test(docs-api): build the #255 route table from FastAPI 0.1…
Opus 5.5
8 days ago