feat(app): FastAPI routes for Dispatcher + WireCodec (step 5)

Adds mobilityapi/app.py + two routers that expose the catalog-driven
Dispatcher (PR #6) and WireCodec (PR #7) as HTTP endpoints:

  - GET  /catalog          -> list dispatcher-exposable functions
  - GET  /catalog/{name}   -> full signature for one function
  - POST /functions/{name} -> invoke with JSON body, decode/encode
                              opaque MEOS types via the WireCodec

The app is built by create_app(dispatcher, codec) — both dependencies
are explicit; no global singletons. Production wires both to PyMEOS;
tests pass stubs.

The POST /functions/{name} flow:
  1. Decode opaque-type params via codec.decode(encoding, wire_value).
  2. Dispatch via Dispatcher.dispatch(name, params).
  3. Encode the result via codec.encode(encoding, value) if the catalog
     marks the return as serialised.

Error mapping:
  - Unknown function           -> 404
  - Missing / extra parameters -> 400
  - Param encoding has no codec decoder -> 400
  - Result encoding has no codec encoder -> 500

tests/test_app.py: 11 HTTP-level tests against a tiny in-test catalog
covering scalar, serialised-in / scalar-out, and serialised-in /
serialised-out shapes, plus the four error paths. All 38 framework
tests pass.

Author: estebanzimanyi

.github/workflows/python.yml

@@ -41,14 +41,17 @@ jobs:
           python -c "from resource.temporal_geom_query import distance, velocity, acceleration"
 
   pytest-dispatcher:
-    name: Dispatcher / resolvers / wire unit tests
+    name: Dispatcher / resolvers / wire / app unit tests
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
-      - name: Install pytest
-        run: pip install --upgrade pip pytest
-      - name: Run dispatcher tests
-        run: python -m pytest tests/test_dispatcher.py tests/test_resolvers.py tests/test_wire.py -v
+      - name: Install dependencies
+        # `fastapi` + `httpx` are required by test_app.py; the other test
+        # modules run with pytest alone since the package init lazy-loads
+        # FastAPI via PEP 562.
+        run: pip install --upgrade pip pytest fastapi 'httpx>=0.24'
+      - name: Run framework + app tests
+        run: python -m pytest tests/test_dispatcher.py tests/test_resolvers.py tests/test_wire.py tests/test_app.py -v

mobilityapi/__init__.py

@@ -23,8 +23,21 @@
 )
 
 __all__ = [
+    "create_app",
     "Dispatcher", "FunctionSignature",
     "stub_resolver", "pymeos_resolver", "default_resolver",
     "WireCodec", "stub_codec", "pymeos_codec",
     "ENCODING_MFJSON", "ENCODING_TEXT", "ENCODING_WKB", "ENCODING_HEXWKB",
 ]
+
+
+# Lazy-load `create_app` (PEP 562) so importing `mobilityapi` does NOT pull
+# in FastAPI/Starlette/Pydantic.  Callers that need the HTTP routes import
+# `from mobilityapi import create_app` and pay the FastAPI dep then; tests
+# that only exercise Dispatcher/Resolvers/WireCodec do not need it on the
+# import path.
+def __getattr__(name):  # noqa: D401 - module-level descriptor
+    if name == "create_app":
+        from .app import create_app as _create_app
+        return _create_app
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

mobilityapi/app.py

@@ -0,0 +1,59 @@
+"""FastAPI application factory for the MobilityAPI Dispatcher framework.
+
+Exposes the catalog-driven Dispatcher + WireCodec foundation (steps 3 / 4
+of the ingestion plan) as HTTP routes. Two router groups:
+
+- ``/catalog/*``    — read-only introspection (list functions, fetch one).
+- ``/functions/*``  — invoke a MEOS function from a JSON request body.
+
+The app is built by :func:`create_app`, which takes injected
+``Dispatcher`` and ``WireCodec`` instances. Production wires both to
+PyMEOS; tests pass stubs.  No global singletons; every dependency is
+explicit, which keeps the request-time hot path resolver-agnostic and
+the test surface fast.
+"""
+
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from .dispatcher import Dispatcher
+from .routers import catalog, functions
+from .wire import WireCodec
+
+
+def create_app(
+    dispatcher: Dispatcher,
+    codec: WireCodec,
+    *,
+    title: str = "MobilityAPI",
+    version: str = "0.1.0",
+) -> FastAPI:
+    """Build the FastAPI app from the injected dispatcher + codec.
+
+    :param dispatcher: ``Dispatcher`` instance bound to a resolver
+        (``stub_resolver`` for tests, ``pymeos_resolver`` for prod).
+    :param codec: ``WireCodec`` mapping the catalog's per-parameter
+        encoding labels (``mfjson`` / ``text`` / ``wkb`` / ``hexwkb``)
+        to Python factory + serialiser callables.
+
+    The dispatcher and codec are exposed to routers via
+    ``app.state.dispatcher`` and ``app.state.codec`` so router
+    dependencies can read them without a global.
+    """
+    app = FastAPI(
+        title=title,
+        version=version,
+        description=(
+            "Catalog-driven dispatcher for MEOS functions, exposed over "
+            "HTTP. Every route delegates to the MobilityAPI Dispatcher; "
+            "no MEOS C code is invoked outside the dispatcher resolver."
+        ),
+    )
+    app.state.dispatcher = dispatcher
+    app.state.codec = codec
+
+    app.include_router(catalog.router, prefix="/catalog", tags=["catalog"])
+    app.include_router(functions.router, prefix="/functions", tags=["functions"])
+
+    return app

mobilityapi/routers/__init__.py

@@ -0,0 +1,5 @@
+"""FastAPI routers for the MobilityAPI Dispatcher framework.
+
+Each router is a thin shell over the Dispatcher + WireCodec; the heavy
+lifting lives in :mod:`mobilityapi.dispatcher` and :mod:`mobilityapi.wire`.
+"""

mobilityapi/routers/catalog.py

@@ -0,0 +1,59 @@
+"""Catalog introspection endpoints.
+
+The MobilityAPI ingestion pipeline (steps 1–3) lands the MEOS catalog as
+``vendor/meos-api/meos-idl.json``. Step 4's :class:`Dispatcher` loads
+that catalog and filters it to the *exposable* subset (functions whose
+catalog entry has ``network.exposable=true`` or is missing).
+
+This router exposes that subset over HTTP so callers can discover what
+the deployed instance can dispatch. Two routes:
+
+- ``GET /catalog``         — list function names + categories.
+- ``GET /catalog/{name}``  — full signature for one function.
+
+Both routes are read-only and never call into MEOS.
+"""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, Request
+
+router = APIRouter()
+
+
+@router.get("", summary="List dispatcher-exposable MEOS function names")
+def list_functions(request: Request) -> dict:
+    dispatcher = request.app.state.dispatcher
+    items = [
+        {
+            "name": sig.name,
+            "category": sig.category,
+            "return_type": sig.return_type,
+        }
+        for sig in dispatcher.signatures()
+    ]
+    items.sort(key=lambda x: x["name"])
+    return {"count": len(items), "functions": items}
+
+
+@router.get("/{name}", summary="Full signature for one MEOS function")
+def get_function(name: str, request: Request) -> dict:
+    dispatcher = request.app.state.dispatcher
+    if not dispatcher.has(name):
+        raise HTTPException(
+            status_code=404,
+            detail=(
+                f"Function `{name}` is not in the dispatcher catalog. "
+                f"GET /catalog lists available functions."
+            ),
+        )
+    sig = dispatcher.signature(name)
+    return {
+        "name": sig.name,
+        "category": sig.category,
+        "params": sig.params,
+        "return_type": sig.return_type,
+        "decode_per_param": sig.decode_per_param,
+        "encode_return": sig.encode_return,
+        "description": sig.description,
+    }

mobilityapi/routers/functions.py

@@ -0,0 +1,121 @@
+"""Function invocation endpoint.
+
+``POST /functions/{name}`` is the single entry point that converts an
+HTTP request body into a Dispatcher call. The body is a JSON object whose
+keys match the catalog's parameter names; opaque MEOS types (any
+parameter the catalog labels with ``decode_per_param``) are decoded by
+the :class:`WireCodec` before the dispatcher invokes the MEOS function,
+and the return value is encoded back to a wire-friendly representation
+on the way out.
+
+The contract:
+
+- Request body: ``{ "params": { "<arg>": <wire_value>, ... } }``
+- Response body for serialised returns:
+  ``{ "result": <wire_value>, "encoding": "mfjson"|"wkb"|... }``
+- Response body for scalar returns:
+  ``{ "result": <value>, "encoding": null }``
+
+This is the minimal vocabulary that lets a thin HTTP client (Polars
+notebook, Spark UDF, JavaScript map UI) treat every MEOS function the
+same way — call by name with a JSON body, read a typed result.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from pydantic import BaseModel, Field
+
+router = APIRouter()
+
+
+class InvokeRequest(BaseModel):
+    """Body of a POST /functions/{name} request."""
+
+    params: dict[str, Any] = Field(
+        default_factory=dict,
+        description=(
+            "Map of parameter name to wire value. Opaque MEOS types "
+            "(Temporal*, STBox, Set, …) MUST be supplied as the encoded "
+            "wire form named in the catalog's `decode_per_param`."
+        ),
+    )
+
+
+class InvokeResponse(BaseModel):
+    """Body of a POST /functions/{name} response."""
+
+    result: Any = Field(..., description="The function return value.")
+    encoding: str | None = Field(
+        None,
+        description=(
+            "Encoding the result is delivered in. `null` for scalar "
+            "(int / float / str / bool) returns; one of `mfjson` / "
+            "`text` / `wkb` / `hexwkb` for serialised MEOS objects."
+        ),
+    )
+
+
+@router.post(
+    "/{name}",
+    response_model=InvokeResponse,
+    summary="Invoke a dispatcher-exposable MEOS function",
+)
+def invoke(name: str, body: InvokeRequest, request: Request) -> InvokeResponse:
+    dispatcher = request.app.state.dispatcher
+    codec = request.app.state.codec
+
+    if not dispatcher.has(name):
+        raise HTTPException(
+            status_code=404,
+            detail=(
+                f"Function `{name}` is not in the dispatcher catalog. "
+                f"GET /catalog lists available functions."
+            ),
+        )
+
+    sig = dispatcher.signature(name)
+
+    # 1. Decode opaque MEOS-type parameters via the codec, leaving
+    #    scalar parameters untouched.
+    decoded: dict[str, Any] = {}
+    for key, value in body.params.items():
+        encoding = sig.decode_per_param.get(key)
+        if encoding:
+            try:
+                decoded[key] = codec.decode(encoding, value)
+            except KeyError as e:
+                raise HTTPException(
+                    status_code=400,
+                    detail=(
+                        f"Parameter `{key}` claims encoding `{encoding}` "
+                        f"but the WireCodec has no decoder for it."
+                    ),
+                ) from e
+        else:
+            decoded[key] = value
+
+    # 2. Dispatch — surfaces KeyError (unknown name, caught above) and
+    #    TypeError (missing / extra params) as 400 errors.
+    try:
+        result = dispatcher.dispatch(name, decoded)
+    except TypeError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    # 3. Encode the result if the catalog labels it with an encoding.
+    if sig.encode_return:
+        try:
+            wire_result = codec.encode(sig.encode_return, result)
+        except KeyError as e:
+            raise HTTPException(
+                status_code=500,
+                detail=(
+                    f"Result claims encoding `{sig.encode_return}` "
+                    f"but the WireCodec has no encoder for it."
+                ),
+            ) from e
+        return InvokeResponse(result=wire_result, encoding=sig.encode_return)
+
+    return InvokeResponse(result=result, encoding=None)