refactor(node/api): restructure the HTTP API around typed DI and response models

packages/testing/src/consensus_testing/cli/apitest.py

@@ -40,7 +40,7 @@ def apitest(
     SERVER_URL is the base URL of the API server (e.g., http://localhost:5052).
 
     For testing the local leanSpec implementation, use the local pytest suite under
-    tests/api, which automatically starts a local server.
+    tests/node/api/endpoints, which automatically starts a local server.
     """
     config_path = Path(__file__).parent / "pytest_ini_files" / "pytest-apitest.ini"
 
@@ -59,7 +59,7 @@ def apitest(
         str(config_path),
         f"--rootdir={project_root}",
         f"--server-url={server_url}",
-        "tests/api",
+        "tests/node/api/endpoints",
     ]
 
     args.extend(pytest_args)

src/lean_spec/node/api/__init__.py

@@ -1,10 +1,8 @@
 """API server module for various API endpoints."""
 
-from lean_spec.node.api.aggregator_controller import AggregatorController
 from lean_spec.node.api.server import ApiServer, ApiServerConfig
 
 __all__ = [
-    "AggregatorController",
     "ApiServer",
     "ApiServerConfig",
 ]

src/lean_spec/node/api/context.py

@@ -0,0 +1,48 @@
+"""Typed dependencies the HTTP API handlers receive."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol
+
+from aiohttp import web
+
+from lean_spec.spec.forks import LstarSpec, Store
+
+
+class AggregatorRoleControl(Protocol):
+    """The slice of the sync service the admin endpoints read and write."""
+
+    is_aggregator: bool
+
+
+@dataclass(frozen=True, slots=True)
+class ApiContext:
+    """Dependencies shared across handlers, resolved once at startup."""
+
+    spec: LstarSpec
+    """Fork spec driving consensus computations such as fork-choice weights."""
+
+    store_getter: Callable[[], Store | None] | None
+    """Callable returning the live store, or None before the store exists."""
+
+    aggregator_role_control: AggregatorRoleControl | None
+    """Holder of the aggregator flag, or None when aggregator control is unwired."""
+
+    def require_store(self) -> Store:
+        """
+        Return the live store, or raise 503 when the node has no store yet.
+
+        The store is a frozen snapshot, so all reads in one handler stay consistent.
+        """
+        store = self.store_getter() if self.store_getter else None
+        if store is None:
+            raise web.HTTPServiceUnavailable(reason="Store not initialized")
+        return store
+
+    def require_aggregator_role_control(self) -> AggregatorRoleControl:
+        """Return the aggregator role control, or raise 503 when it is unwired."""
+        if self.aggregator_role_control is None:
+            raise web.HTTPServiceUnavailable(reason="Aggregator role control not available")
+        return self.aggregator_role_control