gabriel / musehub public
test_api.py python
689 lines 35.7 KB Hotspot Blast
Raw
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| &gt; 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