about summary refs log tree commit diff
path: root/test/python/test_envelope.py
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-10-08 11:24:58 +0000
committerPjotr <wrk@bosa.lan>2026-10-08 11:55:30 +0000
commit22540223c43342473d7d428dffeeab9d94afb55c (patch)
treef81c6af04ea9157054a58d3fc20e99f55973a0ae /test/python/test_envelope.py
parent5650076cdf45a26aed8c6166069d74281a7f4bd7 (diff)
downloadgenenetwork4-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.py135
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()