diff options
| author | Pjotr <wrk@bosa.lan> | 2026-10-08 11:24:58 +0000 |
|---|---|---|
| committer | Pjotr <wrk@bosa.lan> | 2026-10-08 11:55:30 +0000 |
| commit | 22540223c43342473d7d428dffeeab9d94afb55c (patch) | |
| tree | f81c6af04ea9157054a58d3fc20e99f55973a0ae /test/python/test_envelope.py | |
| parent | 5650076cdf45a26aed8c6166069d74281a7f4bd7 (diff) | |
| download | genenetwork4-22540223c43342473d7d428dffeeab9d94afb55c.tar.gz | |
* src/response.rs: wrap every success response in one envelope.
Breaking: every success body is now {"data", "meta": {"state",
"took_ms", "request_id"}, "notes", "next"}; clients read `data`. Only
`/` (plain text) and `/openapi.json` are unwrapped.
* src/response.rs (Envelope, Meta, State, Ctx, RequestInfo): handlers
take Ctx first and build the response with ctx.envelope(data), so
timing and the request id are never filled in by hand. `state` is
`complete` or `partial`; notes are server-authored only; `next` are
concrete relative hrefs (path_segment percent-encodes names).
* src/routes/*.rs, src/lib.rs (version): every handler returns
Envelope<..> with next links; /search is `partial` when the locus
lookup fails or a sorted 1000-hit window may be truncated, and
/publications/{pubmed_id}/traits when datasets were left out for
authorization.
* src/error.rs (ApiError): add `took_ms`, an RFC 7807 extension member.
* src/auth.rs (AuthToken): the 401 now carries request_id and took_ms
(it never had a request_id); Ctx stores RequestInfo in the request
extensions for it.
* tests: common::data / envelope_data parse every success body through
the envelope; tests/envelope.rs and test/python/test_envelope.py check
the shape, errors, and that every `next` link resolves;
tests/envelope_partial.rs checks the `partial` search without a
database; tests/openapi.rs fails if a JSON success response is not an
Envelope_* schema.
* README.md, docs/SKILL.md, docs/gn-auth.md, RELEASE_NOTES.md: document
the envelope and took_ms on errors.
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Diffstat (limited to 'test/python/test_envelope.py')
| -rw-r--r-- | test/python/test_envelope.py | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/test/python/test_envelope.py b/test/python/test_envelope.py new file mode 100644 index 0000000..160a50c --- /dev/null +++ b/test/python/test_envelope.py @@ -0,0 +1,135 @@ +"""Mirrors tests/envelope.rs and the envelope check of tests/openapi.rs: +the success envelope (`data` next to `meta`, `notes` and `next`) on +every endpoint except `/` and `/openapi.json`, and that every `next` +href resolves. The `/version` and OpenAPI checks need nothing else; the +`next` crawl needs a live MariaDB and a token (see docs/gn-auth.md) and +skips with a message when either is missing. +""" + +import http.client +import json +import unittest + +from auth_helpers import TOKEN_ENV, auth_token +from server_test_case import HOST, PORT, ServerTestCase, database_reachable + +# Hrefs not followed: lists of thousands of rows (every trait of a +# group, every probeset of a dataset). +TOO_LARGE_SUFFIXES = ("/traits", "/probesets") + +SEEDS = [ + "/species", + "/species/mouse", + "/species/mouse/datasets", + "/groups", + "/groups/BXD", + "/groups/BXD/strains", + "/groups/BXD/case-attributes", + "/groups/BXD/datasets", + "/groups/BXD/traits?abbreviation=5HT_MB_M", + "/groups/BXD/traits/17985", + "/groups/BXD/traits/17985/values", + "/datasets/Br_U_0803_M", + "/datasets/Br_U_0803_M/probesets/100001_at", + "/datasets/Br_U_0803_M/probesets/100001_at/values", + "/traits/BXDPublish/17985", + "/traits/BXDPublish/17985/values", + "/publications/24102824/traits", +] + + +class EnvelopeTest(ServerTestCase): + EXTRA_ENV = TOKEN_ENV + + def get(self, path, token=None, timeout=60): + conn = http.client.HTTPConnection(HOST, int(PORT), timeout=timeout) + try: + headers = {"Authorization": f"Bearer {token}"} if token else {} + conn.request("GET", path, headers=headers) + response = conn.getresponse() + return response, response.read() + finally: + conn.close() + + def test_version_is_wrapped_in_the_envelope(self): + response, body = self.get("/version") + self.assertEqual(response.status, 200) + envelope = json.loads(body) + self.assertEqual(envelope["data"]["name"], "GeneNetwork4") + self.assertEqual(envelope["meta"]["state"], "complete") + self.assertIsInstance(envelope["meta"]["took_ms"], int) + self.assertEqual( + envelope["meta"]["request_id"], response.getheader("x-request-id") + ) + self.assertEqual(envelope["notes"], []) + self.assertEqual(envelope["next"], []) + + def test_errors_carry_the_request_id_and_took_ms(self): + # The token extractor's 401: needs no database or gn-auth. + response, body = self.get("/species") + self.assertEqual(response.status, 401) + error = json.loads(body) + self.assertEqual(error["code"], "invalid_token") + self.assertEqual(error["request_id"], response.getheader("x-request-id")) + self.assertIsInstance(error["took_ms"], int) + + def test_the_greeting_and_the_openapi_document_are_not_wrapped(self): + response, body = self.get("/") + self.assertEqual(response.status, 200) + self.assertEqual(body, b"Hello, world!") + + response, body = self.get("/openapi.json") + doc = json.loads(body) + self.assertIn("openapi", doc) + self.assertNotIn("meta", doc) + + def test_every_json_success_response_is_an_envelope(self): + _, body = self.get("/openapi.json") + checked = 0 + for path, item in json.loads(body)["paths"].items(): + for method, operation in item.items(): + content = operation["responses"].get("200", {}).get("content", {}) + body_schema = content.get("application/json") + if body_schema is None: + continue + schema = body_schema["schema"].get("$ref", "") + self.assertTrue( + schema.startswith("#/components/schemas/Envelope_"), + f"{method} {path}: 200 response is {schema!r}, not an envelope", + ) + checked += 1 + self.assertGreaterEqual(checked, 20) + + def test_next_links_resolve(self): + if not database_reachable(): + self.skipTest("no database on 127.0.0.1:3306") + token = auth_token() + if not token: + self.skipTest("no token (see docs/gn-auth.md)") + + followed = 0 + for seed in SEEDS: + response, body = self.get(seed, token) + self.assertEqual(response.status, 200, f"GET {seed}: {body[:200]}") + envelope = json.loads(body) + self.assertEqual( + envelope["meta"]["request_id"], response.getheader("x-request-id"), seed + ) + self.assertIsInstance(envelope["meta"]["took_ms"], int, seed) + for nxt in envelope["next"]: + href = nxt["href"] + self.assertTrue(href.startswith("/"), f"{seed}: relative href {href}") + self.assertIsInstance(nxt["description"], str) + if href.endswith(TOO_LARGE_SUFFIXES): + continue + response, linked = self.get(href, token) + self.assertEqual( + response.status, 200, f"{seed} suggests {href}: {linked[:200]}" + ) + self.assertIn("state", json.loads(linked)["meta"]) + followed += 1 + self.assertGreaterEqual(followed, 20) + + +if __name__ == "__main__": + unittest.main() |
