@trillboards/edge-sdk 0.2.73 → 0.2.76

package/deploy/detector/tests/test_server.py

@@ -0,0 +1,577 @@
+"""The wire contract, against a REAL server on a real socket, with NO model.
+
+WHAT THIS SUITE IS FOR. `LocalDetectorClient.test.ts` enumerates fifteen
+payloads the client refuses. Every one of them, arriving from us, costs a whole
+frame — and worse, an emitted-but-refused payload is indistinguishable
+downstream from a service that is simply down. So the assertions here are mostly
+about what this service REFUSES TO EMIT and what status code it uses to say so,
+in the same spirit as the client's own suite.
+
+The detector is a stub. That is not a shortcut — it is the point. The 128 MiB
+artifact is OTA'd and will be absent on any machine that has not fetched it,
+including every CI runner, and a wire contract that can only be tested with a
+model present is a wire contract nothing tests.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import socket
+import unittest
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+from trillboards_detector.errors import DetectorNotReady
+from trillboards_detector.server import DetectorServer, MAX_BODY_BYTES
+
+JPEG = bytes([0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46])
+
+
+@dataclass
+class FakeDetection:
+    label: str
+    confidence: float
+    x: float
+    y: float
+    width: float
+    height: float
+
+
+class FakeBatch:
+    def __init__(self, detections, inference_ms=63.4):
+        self.detections = detections
+        self.inference_ms = inference_ms
+        self.degenerate_dropped = 0
+        self.unnamed_class_dropped = 0
+
+
+class FakeLoader:
+    """Everything `server.py` is allowed to know about the model."""
+
+    model_name = "rfdetr_medium"
+
+    def __init__(self, batch=None, state="ready", raises=None):
+        self._batch = batch if batch is not None else FakeBatch([])
+        self.state = state
+        self._raises = raises
+        self.calls: list[tuple] = []
+
+    def info(self):
+        return {"state": self.state, "model": self.model_name, "model_path": "/stub"}
+
+    def detect(self, jpeg, min_confidence, wanted):
+        self.calls.append((jpeg, min_confidence, wanted))
+        if self._raises is not None:
+            raise self._raises
+        return self._batch
+
+
+class ServerCase(unittest.TestCase):
+    def serve(self, loader) -> str:
+        import threading
+
+        server = DetectorServer(("127.0.0.1", 0), loader, log_line=lambda _m: None)
+        # 20 ms poll: `shutdown()` blocks until the loop notices, and the
+        # 500 ms default turns a 22-test suite into 11 s of pure waiting.
+        threading.Thread(target=lambda: server.serve_forever(poll_interval=0.02), daemon=True).start()
+        self.addCleanup(server.shutdown)
+        self.addCleanup(server.server_close)
+        host, port = server.server_address[:2]
+        return f"http://{host}:{port}"
+
+    def request(self, url, method="GET", body=None, raw_body=None):
+        data = raw_body if raw_body is not None else (json.dumps(body).encode() if body is not None else None)
+        req = urllib.request.Request(url, data=data, method=method)
+        if data is not None:
+            req.add_header("Content-Type", "application/json")
+        try:
+            with urllib.request.urlopen(req, timeout=10) as res:
+                return res.status, json.loads(res.read().decode())
+        except urllib.error.HTTPError as err:
+            with err:
+                payload = err.read().decode()
+            try:
+                return err.code, json.loads(payload)
+            except json.JSONDecodeError:
+                return err.code, {"raw": payload}
+
+    def detect(self, url, **payload):
+        body = {"image_b64": base64.b64encode(JPEG).decode(), "min_confidence": 0.25}
+        body.update(payload)
+        return self.request(f"{url}/detect", method="POST", body=body)
+
+    def chunked(self, url, payload, chunk_size=64, terminator=b"0\r\n\r\n", half_close=False):
+        """POST with Transfer-Encoding: chunked, on a raw socket.
+
+        urllib always sets Content-Length, so it cannot reach this path at all —
+        which is exactly how the defect below shipped and was only caught by
+        running the real Node client.
+        """
+        host = url.rsplit(":", 1)[0].replace("http://", "")
+        port = int(url.rsplit(":", 1)[1])
+        raw = json.dumps(payload).encode()
+        head = (
+            f"POST /detect HTTP/1.1\r\nHost: {host}:{port}\r\n"
+            "Content-Type: application/json\r\nTransfer-Encoding: chunked\r\n\r\n"
+        ).encode()
+        frames = [head]
+        for i in range(0, len(raw), chunk_size):
+            piece = raw[i:i + chunk_size]
+            frames.append(f"{len(piece):x}\r\n".encode() + piece + b"\r\n")
+        frames.append(terminator)
+        s = socket.create_connection((host, port), timeout=15)
+        try:
+            s.sendall(b"".join(frames))
+            if half_close:
+                s.shutdown(socket.SHUT_WR)
+            data = b""
+            s.settimeout(10)
+            while b"\r\n\r\n" not in data:
+                c = s.recv(65536)
+                if not c:
+                    break
+                data += c
+            head_bytes, _, rest = data.partition(b"\r\n\r\n")
+            status = int(head_bytes.split(b"\r\n")[0].split()[1])
+            length = 0
+            for line in head_bytes.split(b"\r\n")[1:]:
+                if line.lower().startswith(b"content-length:"):
+                    length = int(line.split(b":", 1)[1])
+            while len(rest) < length:
+                c = s.recv(65536)
+                if not c:
+                    break
+                rest += c
+            return status, json.loads(rest.decode()) if rest else {}
+        finally:
+            s.close()
+
+
+class TestHealth(ServerCase):
+    def test_ready_is_200_and_never_runs_inference(self):
+        loader = FakeLoader()
+        url = self.serve(loader)
+        status, body = self.request(f"{url}/health")
+        self.assertEqual(status, 200)
+        self.assertEqual(body["status"], "ok")
+        # THE ASSERTION THAT MATTERS. `GET /v1/models` answers 200 without ever
+        # building an engine, which is how a Windows fleet that could not
+        # analyze a single frame passed both its install health check and its
+        # CPU-fallback re-check. Health here must be cheap in the same way and
+        # honest in the way that one was not.
+        self.assertEqual(loader.calls, [])
+
+    def test_unavailable_is_503_so_the_client_reads_it_as_down(self):
+        url = self.serve(FakeLoader(state="unavailable"))
+        status, body = self.request(f"{url}/health")
+        self.assertEqual(status, 503)
+        self.assertEqual(body["status"], "unavailable")
+
+    def test_loading_is_also_not_healthy(self):
+        url = self.serve(FakeLoader(state="loading"))
+        status, _ = self.request(f"{url}/health")
+        self.assertEqual(status, 503)
+
+    def test_health_is_a_get(self):
+        url = self.serve(FakeLoader())
+        status, _ = self.request(f"{url}/health", method="POST", body={})
+        self.assertEqual(status, 405)
+
+
+class TestHealthCannotLoadTheModel(unittest.TestCase):
+    """The strongest form of "/health does not load the model": it CANNOT.
+
+    Asserting that a health probe did not happen to run inference tests one
+    code path. This tests the design that makes it impossible — `server.py`
+    reaches the model only through an injected object, so importing the whole
+    wire layer pulls in no ONNX runtime, no numpy and no Pillow, and therefore
+    has no way to build a session however it is called.
+
+    That is also what lets every case here except the numpy-dependent
+    post-processing ones (45 of 60 on 2026-08-24) run on a bare interpreter with
+    the artifact absent — which is every CI runner, since the
+    ~128 MiB ONNX is OTA'd and not committed. A wire contract that could only be
+    tested with the model present is a wire contract nothing tests.
+
+    IT CATCHES THE REGRESSION IN BOTH ENVIRONMENTS, BY DIFFERENT MECHANISMS, and
+    that is why the return-code assertion is not redundant with the leak
+    assertion:
+
+      bare interpreter (CI)   an added `import numpy` makes the subprocess exit
+                              non-zero — there is no numpy to import.
+      full venv (a dev box)   the import succeeds, and the leak list is what
+                              catches it.
+
+    Verified against a positive control on 2026-08-24: on an interpreter with
+    the runtime installed, this same probe against `trillboards_detector.loader`
+    reports `['onnxruntime', 'numpy', 'PIL', 'trillboards_detector.session']`.
+    A check that has never been shown to fail is not a check.
+    """
+
+    def test_importing_the_wire_layer_pulls_in_no_inference_runtime(self):
+        import subprocess
+        import sys
+
+        probe = (
+            "import sys; import trillboards_detector.server as s; "
+            "leaked = [m for m in ('onnxruntime','numpy','PIL','trillboards_detector.session',"
+            "'trillboards_detector.loader') if m in sys.modules]; "
+            "print(','.join(leaked))"
+        )
+        out = subprocess.run(
+            [sys.executable, "-c", probe], capture_output=True, text=True, timeout=60,
+        )
+        self.assertEqual(out.returncode, 0, out.stderr)
+        self.assertEqual(
+            out.stdout.strip(),
+            "",
+            "server.py imported an inference dependency — the wire layer must reach the "
+            "model only through the injected loader, or /health gains a way to load one "
+            "and the stdlib-only suite stops running on a bare interpreter",
+        )
+
+
+class TestDetectHappyPath(ServerCase):
+    def test_shape_is_exactly_what_the_client_parses(self):
+        batch = FakeBatch([FakeDetection("person", 0.91, 10.0, 20.0, 30.0, 40.0)])
+        url = self.serve(FakeLoader(batch))
+        status, body = self.detect(url)
+        self.assertEqual(status, 200)
+        self.assertEqual(
+            body,
+            {
+                "detections": [
+                    {
+                        "label": "person",
+                        "confidence": 0.91,
+                        "box": {"x": 10.0, "y": 20.0, "width": 30.0, "height": 40.0},
+                    }
+                ],
+                "inference_ms": 63.4,
+                "model": "rfdetr_medium",
+            },
+        )
+
+    def test_an_empty_frame_is_200_with_an_empty_array(self):
+        """An empty array is a RESULT. It must never become a 503, and a 503
+        must never become an empty array — the two directions of the same
+        collapse the client exists to prevent."""
+        url = self.serve(FakeLoader(FakeBatch([])))
+        status, body = self.detect(url)
+        self.assertEqual(status, 200)
+        self.assertEqual(body["detections"], [])
+        self.assertEqual(body["model"], "rfdetr_medium")
+
+    def test_boundary_confidences_0_and_1_survive(self):
+        batch = FakeBatch(
+            [FakeDetection("person", 0.0, 1, 2, 3, 4), FakeDetection("person", 1.0, 1, 2, 3, 4)]
+        )
+        url = self.serve(FakeLoader(batch))
+        _, body = self.detect(url)
+        self.assertEqual([d["confidence"] for d in body["detections"]], [0.0, 1.0])
+
+
+class TestClassFilter(ServerCase):
+    def test_classes_reach_the_detector_canonicalised(self):
+        loader = FakeLoader()
+        url = self.serve(loader)
+        self.detect(url, classes=["Person", "cell_phone", "dining-table"])
+        _, _, wanted = loader.calls[0]
+        self.assertEqual(wanted, {"person", "cell phone", "dining table"})
+
+    def test_absent_classes_means_every_class(self):
+        loader = FakeLoader()
+        url = self.serve(loader)
+        body = {"image_b64": base64.b64encode(JPEG).decode(), "min_confidence": 0.25}
+        self.request(f"{url}/detect", method="POST", body=body)
+        self.assertIsNone(loader.calls[0][2])
+
+    def test_an_empty_classes_array_is_a_400_not_a_synonym_for_all(self):
+        url = self.serve(FakeLoader())
+        status, _ = self.detect(url, classes=[])
+        self.assertEqual(status, 400)
+
+    def test_all_unknown_classes_is_a_loud_400(self):
+        """A profile naming classes the model cannot emit must not return an
+        empty frame forever while every surface looks healthy. That is
+        `yolov8_nano`: offered to ~97 of 114 profiles, loadable nowhere,
+        `vehicle_count` at ~0% fleet-wide for six months."""
+        url = self.serve(FakeLoader())
+        status, body = self.detect(url, classes=["shoplifter", "queue"])
+        self.assertEqual(status, 400)
+        self.assertIn("shoplifter", body["error"])
+
+    def test_a_partly_unknown_list_proceeds_on_the_known_half(self):
+        loader = FakeLoader()
+        url = self.serve(loader)
+        status, _ = self.detect(url, classes=["person", "shoplifter"])
+        self.assertEqual(status, 200)
+        self.assertEqual(loader.calls[0][2], {"person"})
+
+
+class TestRequestRefusals(ServerCase):
+    def test_min_confidence_bounds(self):
+        url = self.serve(FakeLoader())
+        for bad in (-0.1, 1.4, "0.9", None, True):
+            with self.subTest(bad=bad):
+                status, _ = self.detect(url, min_confidence=bad)
+                self.assertEqual(status, 400)
+
+    def test_min_confidence_is_optional_and_defaults(self):
+        loader = FakeLoader()
+        url = self.serve(loader)
+        body = {"image_b64": base64.b64encode(JPEG).decode()}
+        status, _ = self.request(f"{url}/detect", method="POST", body=body)
+        self.assertEqual(status, 200)
+        self.assertEqual(loader.calls[0][1], 0.25)
+
+    def test_image_refusals(self):
+        url = self.serve(FakeLoader())
+        for name, payload in [
+            ("missing", {}),
+            ("empty string", {"image_b64": ""}),
+            ("not base64", {"image_b64": "!!!not base64!!!"}),
+            ("not a string", {"image_b64": 42}),
+            ("decodes to nothing", {"image_b64": ""}),
+        ]:
+            with self.subTest(name=name):
+                body = {"min_confidence": 0.25}
+                body.update(payload)
+                status, _ = self.request(f"{url}/detect", method="POST", body=body)
+                self.assertEqual(status, 400)
+
+    def test_a_body_that_is_not_json(self):
+        url = self.serve(FakeLoader())
+        status, _ = self.request(f"{url}/detect", method="POST", raw_body=b"<html>Sign in to WiFi</html>")
+        self.assertEqual(status, 400)
+
+    def test_a_json_array_at_the_top_level(self):
+        url = self.serve(FakeLoader())
+        status, _ = self.request(f"{url}/detect", method="POST", body=[])
+        self.assertEqual(status, 400)
+
+    def test_an_oversized_body_is_413_not_an_allocation(self):
+        url = self.serve(FakeLoader())
+        req = urllib.request.Request(f"{url}/detect", data=b"{}", method="POST")
+        req.add_header("Content-Type", "application/json")
+        req.add_header("Content-Length", str(MAX_BODY_BYTES + 1))
+        try:
+            with urllib.request.urlopen(req, timeout=10) as res:
+                self.fail(f"expected 413, got {res.status}")
+        except urllib.error.HTTPError as err:
+            self.assertEqual(err.code, 413)
+
+    def test_unknown_routes_404(self):
+        url = self.serve(FakeLoader())
+        self.assertEqual(self.request(f"{url}/v1/models")[0], 404)
+        self.assertEqual(self.request(f"{url}/detect")[0], 404)  # GET on the POST route
+
+
+class TestChunkedRequests(ServerCase):
+    """`LocalDetectorClient` sends EVERY request chunked, and this is why.
+
+    `defaultDetectorPoster` sets exactly two headers — Content-Type and Accept —
+    then calls `req.write(body); req.end()`. With no declared length Node frames
+    the request with `Transfer-Encoding: chunked`, so chunked is the ONLY shape
+    production traffic arrives in. `http.server` does not decode it: it reports
+    Content-Length 0 and leaves the bytes on the socket.
+
+    Before this suite existed the service answered 400 "empty request body" to
+    every real call, and the undrained chunk bytes were then parsed as the next
+    request line, so Node reported `Parse Error: Expected HTTP/`. urllib always
+    sets Content-Length, so no test written with it could reach the defect —
+    only the real client could, which is what the integration test is for and
+    what these raw-socket cases keep from regressing.
+    """
+
+    def test_a_chunked_body_is_decoded_like_any_other(self):
+        batch = FakeBatch([FakeDetection("person", 0.91, 10.0, 20.0, 30.0, 40.0)])
+        loader = FakeLoader(batch)
+        url = self.serve(loader)
+        status, body = self.chunked(
+            url, {"image_b64": base64.b64encode(JPEG).decode(), "min_confidence": 0.25}
+        )
+        self.assertEqual(status, 200)
+        self.assertEqual(body["detections"][0]["label"], "person")
+        self.assertEqual(loader.calls[0][0], JPEG)
+
+    def test_many_small_chunks_reassemble_exactly(self):
+        loader = FakeLoader()
+        url = self.serve(loader)
+        big = bytes(range(256)) * 40  # 10 KiB, split across ~640 chunks
+        status, _ = self.chunked(
+            url, {"image_b64": base64.b64encode(big).decode(), "min_confidence": 0.25}, chunk_size=16
+        )
+        self.assertEqual(status, 200)
+        self.assertEqual(loader.calls[0][0], big)
+
+    def test_a_chunked_body_that_decodes_to_nothing_is_a_400(self):
+        url = self.serve(FakeLoader())
+        status, _ = self.chunked(url, {"image_b64": "", "min_confidence": 0.25})
+        self.assertEqual(status, 400)
+
+    def test_a_client_that_dies_mid_body_gets_a_400_not_an_empty_frame(self):
+        """No terminating zero-chunk, and the caller half-closes.
+
+        The read returns b"" and the service refuses. What it must NOT do is
+        treat a truncated body as an empty one and answer 200 with `[]` — the
+        collapse the whole contract exists to prevent.
+        """
+        url = self.serve(FakeLoader())
+        status, _ = self.chunked(
+            url,
+            {"image_b64": base64.b64encode(JPEG).decode(), "min_confidence": 0.25},
+            terminator=b"",
+            half_close=True,
+        )
+        self.assertEqual(status, 400)
+
+    def test_a_caller_that_stalls_mid_body_does_not_pin_a_worker_forever(self):
+        """Half a chunked body, socket left OPEN, caller says nothing more.
+
+        With no read timeout the handler blocks in `readline` for the life of
+        the process. `handle_one_request` catches TimeoutError and closes, so
+        the assertion is that the connection ENDS — the same unbounded-read leak
+        the runtime-edge-cases runbook records on the response side.
+        """
+        from unittest.mock import patch
+
+        from trillboards_detector.server import DetectorHandler
+
+        url = self.serve(FakeLoader())
+        host, port = url.replace("http://", "").rsplit(":", 1)
+        with patch.object(DetectorHandler, "timeout", 1):
+            s = socket.create_connection((host, int(port)), timeout=15)
+            try:
+                s.sendall(
+                    f"POST /detect HTTP/1.1\r\nHost: {host}\r\n"
+                    "Content-Type: application/json\r\nTransfer-Encoding: chunked\r\n\r\n"
+                    "10\r\n".encode()
+                )  # promises 16 bytes, sends none
+                s.settimeout(10)
+                self.assertEqual(s.recv(65536), b"", "the server kept the stalled connection open")
+            finally:
+                s.close()
+
+
+class TestDownIsNotEmpty(ServerCase):
+    def test_not_ready_is_503_never_an_empty_result(self):
+        url = self.serve(FakeLoader(state="unavailable", raises=DetectorNotReady("no artifact")))
+        status, body = self.detect(url)
+        self.assertEqual(status, 503)
+        self.assertNotIn("detections", body)
+
+    def test_a_failed_inference_is_500_never_an_empty_result(self):
+        url = self.serve(FakeLoader(raises=RuntimeError("ORT exploded")))
+        status, body = self.detect(url)
+        self.assertEqual(status, 500)
+        self.assertNotIn("detections", body)
+
+
+class TestNeverEmitWhatTheClientRefuses(ServerCase):
+    """If a detection cannot go on the wire, answer 500 — not a plausible 200.
+
+    Each row below is a payload `LocalDetectorClient` rejects outright. Reaching
+    the client at all would cost the whole frame AND look, from the client's
+    side, exactly like the service being down. So the service refuses first, in
+    a status code that cannot be read as a quiet venue.
+    """
+
+    def test_refuses_rather_than_emitting(self):
+        cases = {
+            "empty label": FakeDetection("", 0.9, 1, 1, 5, 5),
+            "zero width": FakeDetection("person", 0.9, 1, 1, 0, 5),
+            "zero height": FakeDetection("person", 0.9, 1, 1, 5, 0),
+            "negative extent": FakeDetection("person", 0.9, 1, 1, -3, 5),
+            "confidence above 1": FakeDetection("person", 1.4, 1, 1, 5, 5),
+            "confidence below 0": FakeDetection("person", -0.1, 1, 1, 5, 5),
+            "NaN confidence": FakeDetection("person", float("nan"), 1, 1, 5, 5),
+            "inf confidence": FakeDetection("person", float("inf"), 1, 1, 5, 5),
+            "NaN box side": FakeDetection("person", 0.9, float("nan"), 1, 5, 5),
+            "inf box side": FakeDetection("person", 0.9, 1, 1, float("inf"), 5),
+        }
+        for name, bad in cases.items():
+            with self.subTest(name=name):
+                # A good detection sits alongside the bad one, exactly as in the
+                # client's own suite: the whole payload goes, not just the row.
+                batch = FakeBatch([FakeDetection("person", 0.7, 1, 1, 2, 2), bad])
+                url = self.serve(FakeLoader(batch))
+                status, body = self.detect(url)
+                self.assertEqual(status, 500, f"{name} was emitted instead of refused")
+                self.assertNotIn("detections", body)
+
+
+class TestNeverEmitInvalidJson(ServerCase):
+    """`json.dumps` emits a bare `NaN` by default and no JSON parser accepts it.
+
+    The client would report "detector returned a body that is not JSON" — a
+    TRANSPORT-shaped message for an arithmetic fault on the producer side, which
+    sends the next reader to the wrong half of the wire. Detections are already
+    covered by `_assert_wire_safe`; these two rows cover the rest of the
+    envelope, which nothing else checks.
+    """
+
+    def test_a_non_finite_inference_ms_is_refused_not_serialised(self):
+        for bad in (float("nan"), float("inf"), float("-inf")):
+            with self.subTest(bad=bad):
+                batch = FakeBatch([FakeDetection("person", 0.9, 1, 1, 5, 5)], inference_ms=bad)
+                url = self.serve(FakeLoader(batch))
+                status, body = self.detect(url)
+                self.assertEqual(status, 500)
+                self.assertNotIn("detections", body)
+
+    def test_every_response_body_actually_parses_as_json(self):
+        """The assertion is `json.loads`, which — unlike Python's dumps — refuses
+        NaN, so it stands in for the client's own `JSON.parse`."""
+        batch = FakeBatch([FakeDetection("person", 0.91, 10.0, 20.0, 30.0, 40.0)])
+        url = self.serve(FakeLoader(batch))
+        for status, body in (
+            self.detect(url),
+            self.detect(url, min_confidence=2),      # 400
+            self.request(f"{url}/health"),           # 200
+            self.request(f"{url}/nope"),             # 404
+        ):
+            json.loads(json.dumps(body), parse_constant=_refuse_constant)
+
+
+def _refuse_constant(token):
+    raise AssertionError(f"response carried the non-JSON constant {token!r}")
+
+
+class TestChunkedTrailerBound(ServerCase):
+    def test_a_flood_of_trailer_lines_is_refused(self):
+        """Trailer lines are not body bytes, so MAX_BODY_BYTES does not bound
+        them. Without its own cap this is the one place a caller could keep a
+        worker busy indefinitely."""
+        url = self.serve(FakeLoader())
+        host, port = url.replace("http://", "").rsplit(":", 1)
+        payload = json.dumps(
+            {"image_b64": base64.b64encode(JPEG).decode(), "min_confidence": 0.25}
+        ).encode()
+        frames = (
+            f"POST /detect HTTP/1.1\r\nHost: {host}\r\nContent-Type: application/json\r\n"
+            "Transfer-Encoding: chunked\r\n\r\n"
+        ).encode()
+        frames += f"{len(payload):x}\r\n".encode() + payload + b"\r\n0\r\n"
+        frames += b"X-Pad: 1\r\n" * 200          # far past the cap, never a blank line
+        s = socket.create_connection((host, int(port)), timeout=15)
+        try:
+            s.sendall(frames)
+            s.shutdown(socket.SHUT_WR)
+            data = b""
+            s.settimeout(10)
+            while b"\r\n\r\n" not in data:
+                c = s.recv(65536)
+                if not c:
+                    break
+                data += c
+            self.assertTrue(data, "the server never answered the trailer flood")
+            self.assertEqual(int(data.split(b"\r\n")[0].split()[1]), 400)
+        finally:
+            s.close()
+
+
+if __name__ == "__main__":
+    unittest.main()