maprt-emulator 0.1.0__py3-none-any.whl

maprt_emulator/__init__.py

@@ -0,0 +1,11 @@
+"""maprt_emulator — the MapRT Emulator, a local emulator of the Vision RT MapRT API 2.0.
+
+Serves the seven documented REST endpoints over FastAPI, with the same Bearer-token auth, the
+same JSON envelope, the same two-ways-to-fail error model and the same streaming collision-map
+wire format as a real appliance — reading surfaces and recorded clearance maps out of a folder,
+and synthesizing plausible maps when no recording matches.
+
+**Not a medical device. Teaching use only. Not affiliated with or endorsed by Vision RT.**
+"""
+
+__version__ = "0.1.0"

maprt_emulator/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m maprt_emulator`` — the same entry point as the ``maprt-emulator`` console script."""
+
+from maprt_emulator.cli import main
+
+if __name__ == "__main__":
+    main()

maprt_emulator/app.py

@@ -0,0 +1,182 @@
+"""The FastAPI application: wiring, the ``Server`` header, and envelope error rendering.
+
+It serves the seven MapRT REST routes, plus FastAPI's own pages (``/docs``, ``/redoc``,
+``/openapi.json``), which every FastAPI application has, and the inventory page (``/inventory``,
+``/inventory.md``: what is served and what a call can reach; not in the schema). The pages describe only what an
+appliance takes and sends (:mod:`maprt_emulator.replies`), so a call tried there is a real one. There are no emulator control routes: a
+real appliance has none, and a client tested here must not come to rely on one. A real appliance
+publishes no API pages either, so a client must not depend on those. Faults are chosen when the
+emulator starts (``--scenario``), not over HTTP.
+
+Two things to remember when reading responses:
+
+* Every endpoint but ``GetMap`` answers with the envelope: ``{"data", "errorData", "success",
+  "errorCode", "errorCodeType"}`` on success, and the same without ``data`` on a negative result.
+* **A ``200`` status does not mean the call succeeded.** A negative result — bad token, unlicensed
+  feature, ambiguous room name — comes back at ``200`` with ``success: false``.
+"""
+
+import asyncio
+import logging
+
+from fastapi import FastAPI, Security
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+
+from maprt_emulator import envelope
+from maprt_emulator.auth import bearer_scheme
+from maprt_emulator.library import load_library, serves_packs
+from maprt_emulator.maps import MapLibrary
+from maprt_emulator.routes import beams, getmap, inventory, ping, rooms, surfaces
+from maprt_emulator.routes.getmap import MapCache
+from maprt_emulator.scenarios import ScenarioState
+from maprt_emulator.settings import API_VERSION, SERVER_VERSION, EmulatorSettings
+from maprt_emulator.store import Catalog
+
+logger = logging.getLogger("maprt_emulator")
+
+#: ``create_app``'s default for ``library``: load the packs the settings ask for.
+_FROM_SETTINGS = object()
+
+
+def create_app(settings=None, library=_FROM_SETTINGS):
+    """Build the application. ``settings`` defaults to one resolved from the environment.
+
+    ``library`` is the :class:`maprt_emulator.library.PackLibrary` to serve (or ``None`` for none),
+    when the caller has already loaded it, as the command line does to report it in the banner;
+    by default the packs the settings ask for are loaded here.
+    """
+    settings = settings or EmulatorSettings()
+
+    # FastAPI's default /docs, /redoc and /openapi.json stay: they come with any FastAPI app.
+    app = FastAPI(title="MapRT Emulator", version="2.0.0", description=DOCS_DESCRIPTION)
+    _describe_only_the_api(app)
+
+    app.state.settings = settings
+    app.state.token = settings.resolve_token()
+    app.state.catalog = Catalog.load(settings.data_dir)
+    app.state.library = load_library(settings) if library is _FROM_SETTINGS else library
+    # Decision 3: with packs loaded, the emulator presents the newest appliance they were recorded
+    # on, in the Server header and the ping reply. Nothing else changes with it.
+    appliance = app.state.library.appliance if serves_packs(app) else None
+    app.state.server_version = appliance["server"] if appliance else SERVER_VERSION
+    app.state.api_version = appliance["apiVersion"] if appliance else API_VERSION
+    app.state.maps = MapLibrary.load(settings.data_dir)
+    app.state.map_cache = MapCache(app.state.catalog, library=app.state.library)
+    app.state.scenarios = ScenarioState(settings)
+
+    @app.exception_handler(envelope.MapRTFailure)
+    async def _render_failure(_request, exc: envelope.MapRTFailure):
+        """Render a reported failure as the MapRT envelope at the status the raiser chose.
+
+        Note the status is usually **200**: that is the API's own convention for a negative
+        result, not an oversight here.
+        """
+        if exc.detail:
+            logger.warning("%s: %s", exc.error_code, exc.detail)
+        return JSONResponse(exc.envelope(), status_code=exc.status_code)
+
+    @app.exception_handler(RequestValidationError)
+    async def _render_validation_error(_request, exc: RequestValidationError):
+        """Render a malformed request body as the MapRT envelope at HTTP 400.
+
+        FastAPI's own answer would be ``422`` with ``{"detail": [...]}``, which is a perfectly
+        good REST convention and the wrong one here twice over: the spec (§5.3) puts a rejected
+        request at a 4xx such as 400, not 422, and the body is not the
+        envelope, so a MapRT client that has one parser for every response cannot read it.
+
+        The validation detail goes to the server log, not ``errorData``: no recorded error
+        carries anything there, so a client must not learn to read it.
+        """
+        logger.warning("InvalidArgument: %s", "; ".join(_readable(error) for error in exc.errors()))
+        return JSONResponse(envelope.fail(*envelope.INVALID_ARGUMENT), status_code=400)
+
+    @app.middleware("http")
+    async def _appliance_behaviour(request, call_next):
+        """Latency, the armed scenario's transport-level faults, and the ``Server`` header.
+
+        The faults are applied only to ``/integration`` paths, which is every route there is; an
+        unknown path still gets a plain 404.
+        """
+        scenarios_state = app.state.scenarios
+        is_api = request.url.path.startswith("/integration")
+
+        if settings.latency_ms:
+            await asyncio.sleep(settings.latency_ms / 1000)
+
+        if is_api and scenarios_state.extra_delay:
+            await asyncio.sleep(scenarios_state.extra_delay)
+
+        if is_api and scenarios_state.take_throttle_slot():
+            # The spec (§2.2.1.3) allows a server to throttle: to tell a client it can't take the
+            # request now and that it should try again. Retry-After tells a client how long to
+            # wait instead of hammering.
+            logger.warning("ServerBusy: the 'throttle' scenario refused %s", request.url.path)
+            response = JSONResponse(envelope.fail(*envelope.SERVER_BUSY), status_code=503)
+            response.headers["Retry-After"] = "1"
+            response.headers["server"] = app.state.server_version
+            return response
+
+        if is_api and scenarios_state.forced_status:
+            # A 5xx has no envelope to read on a real appliance, and a client that assumes it can
+            # always parse JSON fails inside its own error handler. One is sent anyway here, so
+            # the status is the thing being exercised rather than the body.
+            logger.warning("InternalError: the 'server-error' scenario answered %s", request.url.path)
+            response = JSONResponse(envelope.fail(*envelope.INTERNAL_ERROR),
+                                    status_code=scenarios_state.forced_status)
+            response.headers["server"] = app.state.server_version
+            return response
+
+        response = await call_next(request)
+        # Every appliance response carries a Server header, Saturn/<version> (spec §5.1). Worth
+        # reproducing — it is how a client can tell what it is talking to,
+        # and a notebook reads it to confirm the connection landed where it thinks.
+        response.headers["server"] = app.state.server_version
+        return response
+
+    # Security() here only documents the Bearer token for /docs; require_token does the checking.
+    for router in (ping.router, rooms.router, surfaces.router, getmap.router, beams.router):
+        app.include_router(router, dependencies=[Security(bearer_scheme)])
+    # A page for people, like /docs: no token, and not part of the API (left out of the schema).
+    app.include_router(inventory.router)
+
+    return app
+
+
+DOCS_DESCRIPTION = """\
+A local emulator of the MapRT API 2.0 REST routes. Teaching and testing use only. A real
+appliance publishes no page like this one.
+
+To try a call: **Authorize** with the token the emulator printed at start. A browser can't send
+the `VisionRT.Integration.Saturn/<version>` User-Agent an appliance requires, so start the
+emulator with `--lenient-user-agent`, or every call here answers `VersionMismatch`.
+
+[The inventory](/inventory) ([Markdown](/inventory.md)) lists what this emulator serves: with
+packs loaded, every recorded request, with a body to copy that gets the recorded reply.
+"""
+
+
+def _describe_only_the_api(app):
+    """Leave FastAPI's 422 validation reply out of the schema: the emulator never sends one.
+
+    A malformed body gets the MapRT error envelope at 400 (``_render_validation_error``), and
+    each POST route documents that 400 itself.
+    """
+    generate = app.openapi
+
+    def openapi():
+        schema = generate()
+        for operations in schema.get("paths", {}).values():
+            for operation in operations.values():
+                operation.get("responses", {}).pop("422", None)
+        for name in ("HTTPValidationError", "ValidationError"):
+            schema.get("components", {}).get("schemas", {}).pop(name, None)
+        return schema
+
+    app.openapi = openapi
+
+
+def _readable(error):
+    """One pydantic validation error as a short string, without its internal bookkeeping."""
+    location = ".".join(str(part) for part in error.get("loc", ()) if part != "body")
+    return f"{location or 'body'}: {error.get('msg', 'invalid')}"

maprt_emulator/auth.py

@@ -0,0 +1,105 @@
+"""Bearer-token auth and the User-Agent check, as a real appliance applies them.
+
+Three headers go on every MapRT API call::
+
+    Content-Type:  application/json
+    Authorization: Bearer <API_access_token>
+    User-Agent:    VisionRT.Integration.Saturn/<major>.<minor>.<patch>
+
+The token is a **shared secret** issued per appliance — not a login, not a session, nothing to
+refresh. It is the whole of the authentication story, which is why a real deployment puts the
+appliance behind TLS on a controlled network and treats the token like a password.
+
+What a real appliance does, read from recordings of one (Saturn/1.3.217.2, API 2.0.0,
+2026-10-23), and what the emulator therefore does:
+
+* **Any token problem** — no ``Authorization`` header, ``Bearer`` with nothing after it, the token
+  without the ``Bearer`` prefix, or a wrong token — gets HTTP **200** with ``success: false`` and
+  ``InvalidClientToken``. Never a 401. (``--auth-401`` returns 401 instead, for exercising a
+  client's other branch.)
+* **The token is checked first.** A wrong token with a bad User-Agent is ``InvalidClientToken``.
+* **The User-Agent** must be ``VisionRT.Integration.Saturn/`` followed by a version whose
+  *major.minor* is not newer than the API's (2.0): ``…/2.0.0``, ``…/2.0.1`` and ``…/1.2.8``
+  pass; ``…/2.1.0``, ``…/3.0.0``, ``…/`` with no version, no header at all, or ``curl/8.7.1``
+  all get HTTP 200, ``success: false``, ``VersionMismatch``. The patch number is ignored.
+
+The status code is the trap: a client that trusts it reads every one of these as a success.
+"""
+
+import logging
+
+from fastapi import Request
+from fastapi.security import HTTPBearer
+
+from maprt_emulator import envelope
+from maprt_emulator.settings import API_VERSION, USER_AGENT_PREFIX
+
+logger = logging.getLogger("maprt_emulator.auth")
+
+
+#: For ``/docs`` only: it gives the page an Authorize button that sends ``Bearer <token>``.
+#: ``auto_error=False`` means it never answers a request itself; :func:`require_token` does,
+#: with the envelope an appliance sends.
+bearer_scheme = HTTPBearer(auto_error=False, description="The token the emulator printed at start.")
+
+
+def bearer_token(request):
+    """The token from the ``Authorization`` header, or ``None`` if none was presented."""
+    header = request.headers.get("authorization")
+    if not header:
+        return None
+    scheme, _, value = header.partition(" ")
+    if scheme.lower() != "bearer" or not value.strip():
+        return None
+    return value.strip()
+
+
+def _major_minor(version):
+    """``(major, minor)`` from a ``a.b[.c…]`` version string, or ``None`` if it isn't one."""
+    parts = version.split(".")
+    if len(parts) < 2 or not parts[0].isdigit() or not parts[1].isdigit():
+        return None
+    return int(parts[0]), int(parts[1])
+
+
+def user_agent_accepted(agent, api_version=API_VERSION):
+    """Whether an appliance serving ``api_version`` accepts this User-Agent (see the module notes)."""
+    if not agent or not agent.startswith(USER_AGENT_PREFIX):
+        return False
+    client = _major_minor(agent[len(USER_AGENT_PREFIX):])
+    return client is not None and client <= _major_minor(api_version)
+
+
+def check_user_agent(request, settings):
+    """Refuse a User-Agent the appliance would refuse, unless ``--lenient-user-agent`` is set.
+
+    Strict by default, because the appliance is. Lenient only logs, so a beginner's first bare
+    ``GET`` can work before the header has been explained.
+    """
+    agent = request.headers.get("user-agent", "")
+    if user_agent_accepted(agent):
+        return
+    if settings.strict_user_agent:
+        raise envelope.MapRTFailure(envelope.VERSION_MISMATCH)
+    logger.warning("User-Agent %r would get VersionMismatch from an appliance", agent or "(none)")
+
+
+async def require_token(request: Request):
+    """FastAPI dependency: authenticate the request, or raise :class:`envelope.MapRTFailure`.
+
+    The token first, then the User-Agent — the appliance's order. Also the one place both are
+    applied, so every authenticated endpoint gets them without each route remembering to ask.
+    """
+    settings = request.app.state.settings
+    presented = bearer_token(request)
+
+    # The `bad-token` scenario refuses a correct token too — what an expired or rotated secret
+    # looks like from the client side, which is otherwise impossible to arrange on demand.
+    rejected = (presented is None or presented != request.app.state.token
+                or request.app.state.scenarios.rejects_token)
+    if rejected:
+        raise envelope.MapRTFailure(envelope.INVALID_CLIENT_TOKEN,
+                                    status_code=401 if settings.auth_401 else 200)
+
+    check_user_agent(request, settings)
+    return presented

maprt_emulator/check.py

@@ -0,0 +1,262 @@
+"""Validate a data directory without starting a server — ``maprt-emulator --check-data``.
+
+The loaders refuse to start on anything they cannot read, which is the right behaviour for a
+server but a slow way to iterate when you are adding data: edit, start, read a traceback, stop,
+repeat. This does the same loading, then goes further and reports the problems that are *not*
+fatal but are almost always mistakes — a map recorded against a surface id that no longer exists,
+an ``.obj`` nobody references, a plan naming a patient the appliance has never heard of.
+
+Nothing here changes what the server will do. It tells you what it is about to do.
+"""
+
+from pathlib import Path
+
+from maprt_emulator.library import load_library
+from maprt_emulator.maps import MapLibrary, MapLibraryError
+from maprt_emulator.store import Catalog, CatalogError
+
+
+class Report:
+    """Findings, split by consequence.
+
+    Note what the split is *not*: whether the loader raises. A duplicate room GUID and a
+    truncated recorded map both load perfectly happily and then serve wrong answers, which is
+    worse than refusing to start — so they are errors here even though the server would come up.
+    """
+
+    def __init__(self):
+        self.errors = []      # the server will refuse to start
+        self.warnings = []    # it will start, but this is probably not what you meant
+        self.notes = []       # worth seeing, not a problem
+
+    def error(self, message):
+        """Something that will produce wrong behaviour. Not necessarily a startup failure."""
+        self.errors.append(message)
+
+    def warn(self, message):
+        self.warnings.append(message)
+
+    def note(self, message):
+        self.notes.append(message)
+
+    @property
+    def ok(self):
+        return not self.errors
+
+    def render(self, data_dir):
+        lines = [f"Checking {data_dir}", ""]
+        for label, items, marker in (("ERROR", self.errors, "✗"),
+                                     ("WARNING", self.warnings, "!"),
+                                     ("", self.notes, "·")):
+            for item in items:
+                prefix = f"{marker} {label}: " if label else f"  {marker} "
+                lines.append(f"{prefix}{item}")
+        if self.errors:
+            lines += ["", (f"{_count(len(self.errors), 'error')} — fix these before serving this "
+                           f"data. Some of them will not stop the emulator starting; it will "
+                           f"start and give wrong answers, which is worse.")]
+        elif self.warnings:
+            lines += ["", (f"No errors, {_count(len(self.warnings), 'warning')}. "
+                           f"The emulator will run.")]
+        else:
+            lines += ["", "No problems found."]
+        return "\n".join(lines)
+
+
+def _count(number, noun):
+    return f"{number} {noun}{'' if number == 1 else 's'}"
+
+
+def check(data_dir):
+    """Validate ``data_dir`` and return a :class:`Report`."""
+    data_dir = Path(data_dir)
+    report = Report()
+
+    try:
+        catalog = Catalog.load(data_dir)
+    except CatalogError as exc:
+        report.error(str(exc))
+        return report      # nothing else can be checked without a catalog
+
+    try:
+        maps = MapLibrary.load(data_dir)
+    except MapLibraryError as exc:
+        report.error(str(exc))
+        maps = None
+
+    report.note(", ".join([
+        _count(len(catalog.known_patients), "patient"),
+        _count(len(catalog.surfaces), "surface"),
+        _count(len(catalog.rooms), "room"),
+        _count(len(maps) if maps else 0, "recorded map"),
+    ]))
+
+    _check_rooms(catalog, report)
+    _check_surfaces(catalog, data_dir, report)
+    _check_patients(catalog, report)
+    if maps is not None:
+        _check_maps(maps, catalog, report)
+    _check_plans(catalog, data_dir, report)
+
+    return report
+
+
+def _check_rooms(catalog, report):
+    ids = [room.id for room in catalog.rooms]
+    duplicates = {i for i in ids if ids.count(i) > 1}
+    for room_id in sorted(duplicates):
+        # GetMap keys on the GUID, so two rooms sharing one makes the choice between them
+        # arbitrary — and silently so.
+        report.error(f"two or more rooms share the id {room_id}; room ids must be unique")
+
+    names = [room.machine_name for room in catalog.rooms]
+    shared = sorted({n for n in names if names.count(n) > 1})
+    if shared:
+        # Not a problem — the shipped data does this on purpose, and so do real sites.
+        report.note(f"machine name(s) shared by several rooms: {', '.join(shared)} "
+                    f"(GET /integration/rooms/{{machineName}} will return DuplicateKey for these)")
+
+    for room in catalog.rooms:
+        if len(room.machine_name) > 16:
+            report.warn(f"room {room.name!r} has a machineName of {len(room.machine_name)} "
+                        f"characters; the spec caps it at 16")
+
+
+def _check_surfaces(catalog, data_dir, report):
+    from maprt_emulator.obj import ObjParseError, parse_obj
+
+    referenced = {surface.path.resolve() for surface in catalog.surfaces}
+    for directory in (data_dir / "surfaces", data_dir / "local" / "surfaces"):
+        if not directory.is_dir():
+            continue
+        for path in sorted(directory.glob("*.obj")):
+            if path.resolve() not in referenced:
+                report.warn(f"{path.relative_to(data_dir)} is not listed for any patient in "
+                            f"patients.json, so it will never be served")
+
+    for surface in catalog.surfaces:
+        try:
+            vertices, faces, _normals = parse_obj(surface.path.read_bytes())
+        except ObjParseError as exc:
+            report.error(f"{surface.path.name} does not parse as an OBJ mesh: {exc}")
+            continue
+        if len(vertices) < 100 or len(faces) < 100:
+            report.warn(f"{surface.path.name} has only {len(vertices)} vertices and "
+                        f"{len(faces)} faces — is it the mesh you meant?")
+
+
+def _check_patients(catalog, report):
+    for patient_id in sorted(catalog.known_patients):
+        if len(patient_id) > 64:
+            report.warn(f"patient id {patient_id!r} is {len(patient_id)} characters; "
+                        f"DICOM caps it at 64")
+        if not catalog.surfaces_for(patient_id):
+            # Legitimate and deliberately represented in the shipped data, but say so in case it
+            # is a typo in a surface id rather than an intentionally empty patient.
+            report.note(f"patient {patient_id} has no surfaces (a valid case: the API returns "
+                        f"an empty list at success:true)")
+
+    timestamps = [(p, [s.timestamp for s in catalog.surfaces_for(p)])
+                  for p in catalog.known_patients]
+    for patient_id, stamps in timestamps:
+        if len(stamps) != len(set(stamps)):
+            report.warn(f"patient {patient_id} has two surfaces with the same timeStamp; "
+                        f"'use the most recent' becomes arbitrary")
+
+
+def _check_maps(maps, catalog, report):
+    known_surfaces = {surface.id for surface in catalog.surfaces}
+    known_rooms = {room.id for room in catalog.rooms}
+
+    for recording in maps.recordings:
+        name = recording.path.name
+        # Not fatal — the library simply never matches it — but it means a recording you went to
+        # the trouble of capturing will silently never be served.
+        if recording.surface_id not in known_surfaces:
+            report.warn(f"{name} is recorded against surface {recording.surface_id}, which is "
+                        f"not in patients.json — it will never be served")
+        if recording.room_id not in known_rooms:
+            report.warn(f"{name} is recorded against room {recording.room_id}, which is not in "
+                        f"rooms.json — it will never be served")
+
+        text = recording.text()
+        if not text.strip().endswith("DONE"):
+            report.error(f"{name} has no DONE terminator; it was captured from a truncated "
+                         f"response and will parse into a wrong-shaped array")
+        try:
+            header = text.split("\n", 1)[0]
+            couch_samples, gantry_samples = (int(v) for v in header.split(","))
+        except ValueError:
+            report.error(f"{name} does not start with a 'couch,gantry' header line")
+            continue
+        triples = len(text.split()) - 2
+        if triples != couch_samples * gantry_samples:
+            report.error(f"{name} promises {couch_samples * gantry_samples:,} triples but "
+                         f"carries {triples:,}")
+
+
+def _check_plans(catalog, data_dir, report):
+    plans_dir = data_dir / "plans"
+    if not plans_dir.is_dir():
+        return
+    try:
+        import pydicom
+    except ImportError:
+        report.note("pydicom is not installed, so RT Plans were not checked")
+        return
+
+    for path in sorted(plans_dir.glob("*.dcm")):
+        try:
+            plan = pydicom.dcmread(path, stop_before_pixels=True)
+        except Exception as exc:  # noqa: BLE001 — any unreadable file is worth reporting
+            report.error(f"{path.name} does not read as DICOM: {type(exc).__name__}: {exc}")
+            continue
+
+        if getattr(plan, "Modality", None) != "RTPLAN":
+            report.warn(f"{path.name} is {getattr(plan, 'Modality', 'unknown')}, not RTPLAN")
+            continue
+
+        patient_id = str(getattr(plan, "PatientID", ""))
+        if patient_id not in catalog.known_patients:
+            # The capstone notebook looks this patient up; a mismatch fails its second cell.
+            report.warn(f"{path.name} is for patient {patient_id!r}, who is not in "
+                        f"patients.json — a notebook using this plan will fail")
+
+        machines = {str(b.TreatmentMachineName) for b in getattr(plan, "BeamSequence", [])
+                    if hasattr(b, "TreatmentMachineName")}
+        configured = {room.machine_name for room in catalog.rooms}
+        for machine in sorted(machines - configured):
+            report.warn(f"{path.name} names machine {machine!r}, which is not in rooms.json")
+
+
+def check_packs(settings, report):
+    """Add the packs the settings select to ``report``: a refusal, or a skipped pack, is an error
+    (a packs folder can be checked before a workshop); a mixed-version warning is a warning; the rest
+    are notes."""
+    try:
+        library = load_library(settings)
+    except CatalogError as exc:
+        report.error(f"packs: {exc}")
+        return
+    if library is None:
+        report.note("packs: off (--no-packs)" if settings.no_packs else "packs: none (no --packs-dir)")
+        return
+    report.note(f"packs: {library.summary()}")
+    for entry in library.skipped:
+        report.error(f"packs: {entry.name or entry.path} ({entry.path}) failed its checks and would be skipped: "
+                     + "; ".join(map(str, entry.findings)))
+    for warning in library.warnings:
+        report.warn(f"packs: {warning}")
+    for notice in library.notices:
+        report.note(f"packs: {notice}")
+
+
+def main(data_dir, settings=None):
+    """Print the report; return a process exit code. With ``settings``, the packs they select are
+    checked too."""
+    report = check(data_dir)
+    if settings is not None:
+        check_packs(settings, report)
+    print(report.render(data_dir))
+    return 0 if report.ok else 1
+