sie-config 0.8.0__py3-none-any.whl

sie_config/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

sie_config/app_factory.py

@@ -0,0 +1,249 @@
+import logging
+import os
+import time
+from collections.abc import AsyncGenerator, Callable
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Request
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.responses import Response
+
+from sie_config import metrics as sie_metrics
+from sie_config.config_api import router as config_router
+from sie_config.config_store import ConfigStore
+from sie_config.health import router as health_router
+from sie_config.managed_metrics import setup_managed_metrics
+from sie_config.model_registry import ModelRegistry
+from sie_config.nats_publisher import NatsPublisher
+
+logger = logging.getLogger(__name__)
+
+# Default paths for bundle and model configs.
+# In Docker, SIE_BUNDLES_DIR and SIE_MODELS_DIR are always set (see Dockerfile).
+# In development, fall back to the sibling sie_server package in the source tree.
+_DEFAULT_BUNDLES_DIR = Path(__file__).parent.parent.parent.parent / "sie_server" / "bundles"
+_DEFAULT_MODELS_DIR = Path(__file__).parent.parent.parent.parent / "sie_server" / "models"
+_BOUNDED_HTTP_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"})
+
+
+class _TelemetryHTTPMiddleware(BaseHTTPMiddleware):
+    # Record one backend-neutral config HTTP observation for every request.
+    #
+    # The `path` label is the FastAPI route template (e.g.
+    # `/v1/configs/models/{model_id}`) rather than the raw URL so
+    # per-model reads do not explode the label cardinality. We resolve
+    # the route after the downstream handler runs -- Starlette only
+    # populates `request.scope["route"]` once routing has matched. Unknown
+    # URLs collapse to the contract's bounded `other` label; the Modal URL is
+    # externally reachable, so retaining arbitrary request paths would let a
+    # caller create unbounded time series.
+    #
+    # The exception path matters as much as the success one. If
+    # `call_next(...)` raises, Starlette converts the exception into a
+    # 500 *outside* this middleware, so a naive `response = await
+    # call_next(request)` followed by `.labels(...)` would miss exactly
+    # the failures operators care about most. We wrap the entire
+    # critical section in `try / except / finally` so that:
+    #   - a raised exception still bumps `status="500"` in the counter
+    #     and observes latency (the timing is meaningful -- a 50 ms
+    #     crash is very different from a 30 s one),
+    #   - the original exception is re-raised so Starlette's default
+    #     500 handler runs and the client sees the same response it
+    #     would without this middleware.
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: RequestResponseEndpoint,
+    ) -> Response:
+        # `status_code` is seeded at 500 so an exception raised
+        # inside `call_next` (before we can read `response.status_code`)
+        # still attributes the failure correctly in the `finally` block.
+        # FastAPI/Starlette's outer exception handler turns the raised
+        # exception into a 500 for the client, so counting it as a 500
+        # matches what the caller actually sees.
+        start = time.monotonic()
+        status_code = 500
+        try:
+            response = await call_next(request)
+            status_code = response.status_code
+            return response
+        finally:
+            elapsed = time.monotonic() - start
+            route = request.scope.get("route")
+            path_label = getattr(route, "path", None) or "other"
+            method_label = request.method if request.method in _BOUNDED_HTTP_METHODS else "other"
+
+            sie_metrics.record_http_request(
+                method=method_label,
+                path=path_label,
+                status=status_code,
+                duration_s=elapsed,
+            )
+            if path_label == "/v1/configs/export":
+                sie_metrics.record_snapshot_publish(success=200 <= status_code < 300)
+
+
+class AppFactory:
+    """Factory for creating the SIE Config Service FastAPI application."""
+
+    @classmethod
+    def create_app(cls) -> FastAPI:
+        """Create and configure the FastAPI application.
+
+        Returns:
+            Configured FastAPI application instance.
+        """
+        setup_managed_metrics()
+        app = FastAPI(
+            title="SIE Config Service",
+            description="Config control plane for SIE clusters",
+            version="0.1.0",
+            lifespan=cls._create_lifespan(),
+        )
+
+        # Do not install request instrumentation at all when telemetry is
+        # disabled. A no-op OTel meter still leaves clock reads, route
+        # resolution and attribute preparation on every request; omitting the
+        # middleware makes the public disabled path a true pass-through.
+        #
+        # When enabled, telemetry must wrap the app BEFORE the routers mount
+        # so it observes every request (including errors raised before a route
+        # matches, e.g. body-size rejections). Starlette applies middleware in
+        # outer-to-inner order, so adding it first makes it the outermost layer.
+        if sie_metrics.telemetry_enabled():
+            app.add_middleware(_TelemetryHTTPMiddleware)
+
+        app.include_router(health_router)
+        app.include_router(config_router)
+
+        return app
+
+    @classmethod
+    def _create_lifespan(cls) -> Callable[[FastAPI], Any]:
+        """Create the lifespan context manager for the application."""
+
+        @asynccontextmanager
+        async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+            """Application lifespan manager."""
+            logger.info("Starting SIE Config Service")
+
+            async with (
+                cls._model_registry(app),
+                cls._config_store(app),
+                cls._nats_publisher(app),
+            ):
+                yield
+
+            logger.info("Stopped SIE Config Service")
+
+        return lifespan
+
+    @classmethod
+    @asynccontextmanager
+    async def _model_registry(cls, app: FastAPI) -> AsyncGenerator[None, None]:
+        """Initialize ModelRegistry for model->bundle mapping."""
+        bundles_dir = Path(os.environ.get("SIE_BUNDLES_DIR", str(_DEFAULT_BUNDLES_DIR)))
+        models_dir = Path(os.environ.get("SIE_MODELS_DIR", str(_DEFAULT_MODELS_DIR)))
+
+        try:
+            model_registry = ModelRegistry(bundles_dir, models_dir)
+            app.state.model_registry = model_registry
+            unrouteable = model_registry.unrouteable_models
+            logger.info(
+                "ModelRegistry initialized: %d bundles, %d models (%d unrouteable)",
+                len(model_registry.list_bundles()),
+                len(model_registry.list_models()),
+                len(unrouteable),
+            )
+            # Seed the models gauge. At this point every model came
+            # from disk; the `api`-sourced tally catches up once
+            # ConfigStore restore runs in `_config_store`.
+            sie_metrics.update_models_gauge(
+                api_count=0,
+                filesystem_count=len(model_registry.list_models()),
+            )
+        except Exception:
+            logger.exception("Failed to initialize ModelRegistry, continuing without it")
+            app.state.model_registry = None
+
+        yield
+
+    @classmethod
+    @asynccontextmanager
+    async def _config_store(cls, app: FastAPI) -> AsyncGenerator[None, None]:
+        """Initialize config store for persisting API-added model configs."""
+        config_dir = os.environ.get("SIE_CONFIG_STORE_DIR")
+        if config_dir:
+            store = ConfigStore(config_dir)
+            app.state.config_store = store
+            initial_epoch = store.read_epoch()
+            logger.info("Config store initialized at %s (epoch=%d)", config_dir, initial_epoch)
+            # Mirror the persisted epoch into telemetry so the
+            # `sie.config.epoch` gauge reflects reality immediately on
+            # startup. Without this, dashboards would read 0 until the
+            # first successful `POST /v1/configs/models` call bumped
+            # the counter — which, crucially, never happens in a
+            # read-only control plane.
+            sie_metrics.set_epoch(initial_epoch)
+
+            if os.environ.get("SIE_CONFIG_RESTORE", "").lower() == "true":
+                model_registry: ModelRegistry | None = app.state.model_registry
+                if model_registry is None:
+                    logger.warning("Cannot restore configs -- ModelRegistry not initialized")
+                else:
+                    stored_models = store.load_all_models()
+                    for model_id, model_config in stored_models.items():
+                        try:
+                            model_registry.add_model_config(model_config)
+                            logger.info("Restored model from config store: %s", model_id)
+                        except Exception:
+                            logger.exception("Failed to restore model: %s", model_id)
+                    if stored_models:
+                        logger.info("Restored %d models from config store", len(stored_models))
+                    # Recompute the split now that API-added models
+                    # have been folded back into the registry.
+                    api_count = len(store.list_models())
+                    total = len(model_registry.list_models())
+                    sie_metrics.update_models_gauge(
+                        api_count=api_count,
+                        filesystem_count=max(total - api_count, 0),
+                    )
+        else:
+            app.state.config_store = None
+            # Epoch zero is authoritative in no-store deployments. Seed the
+            # synchronous gauge explicitly so dashboards distinguish that
+            # state from a producer that never emitted telemetry.
+            sie_metrics.set_epoch(0)
+
+        yield
+
+    @classmethod
+    @asynccontextmanager
+    async def _nats_publisher(cls, app: FastAPI) -> AsyncGenerator[None, None]:
+        """Initialize NATS publisher for config distribution."""
+        nats_url = os.environ.get("SIE_NATS_URL")
+        nats_publisher: NatsPublisher | None = None
+
+        # The asynchronous dial may take the full startup retry budget, and a
+        # deployment without NATS never dials at all. In both cases false is an
+        # authoritative current value rather than an absent series.
+        sie_metrics.set_nats_connected(False)
+
+        if nats_url:
+            nats_publisher = NatsPublisher(nats_url=nats_url)
+            app.state.nats_publisher = nats_publisher
+            # Do not await NATS here: it can outlast startup probe budgets while the
+            # NATS pod schedules; /healthz must bind as soon as model registry + store init finish.
+            nats_publisher.kickoff_connect()
+        else:
+            app.state.nats_publisher = None
+            logger.info("NATS not configured (SIE_NATS_URL not set) -- config distribution disabled")
+
+        try:
+            yield
+        finally:
+            if nats_publisher:
+                await nats_publisher.disconnect()

sie_config/cli.py

@@ -0,0 +1,125 @@
+import dataclasses
+import logging
+import sys
+from datetime import UTC, datetime
+from typing import Annotated, Any
+
+import orjson
+import typer
+import uvicorn
+
+from sie_config.types import AuditEntry
+
+app = typer.Typer(
+    name="sie-config",
+    help="SIE Config Service - Config control plane for SIE clusters",
+    no_args_is_help=True,
+)
+
+
+# Derived from AuditEntry dataclass -- single source of truth for audit fields.
+OPTIONAL_FIELDS = tuple(f.name for f in dataclasses.fields(AuditEntry))
+
+
+class JSONFormatter(logging.Formatter):
+    """Formatter that outputs structured JSON logs for Loki compatibility."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Format log record as JSON."""
+        log_data: dict[str, Any] = {
+            "timestamp": datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z"),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+
+        # Add optional structured fields if present
+        log_data |= {field: value for field in OPTIONAL_FIELDS if (value := getattr(record, field, None)) is not None}
+
+        if record.exc_info:
+            log_data["exception"] = self.formatException(record.exc_info)
+        return orjson.dumps(log_data, default=str).decode()
+
+
+def setup_logging(level: str, *, json_format: bool = False) -> None:
+    """Configure logging.
+
+    Args:
+        level: Log level (DEBUG, INFO, WARNING, ERROR).
+        json_format: Use structured JSON format for Loki.
+    """
+    log_level = getattr(logging, level.upper())
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setLevel(log_level)
+
+    if json_format:
+        handler.setFormatter(JSONFormatter())
+    else:
+        handler.setFormatter(
+            logging.Formatter(
+                fmt="%(asctime)s | %(levelname)-8s | %(name)s - %(message)s",
+                datefmt="%Y-%m-%d %H:%M:%S",
+            )
+        )
+
+    root_logger = logging.getLogger()
+    root_logger.setLevel(log_level)
+    for existing_handler in root_logger.handlers[:]:
+        root_logger.removeHandler(existing_handler)
+    root_logger.addHandler(handler)
+
+
+@app.command()
+def serve(
+    port: Annotated[int, typer.Option("--port", "-p", help="Port to listen on")] = 8080,
+    host: Annotated[str, typer.Option("--host", "-h", help="Host to bind to")] = "0.0.0.0",  # noqa: S104 -- intentional bind to all interfaces
+    log_level: Annotated[
+        str,
+        typer.Option(
+            "--log-level",
+            "-l",
+            envvar="SIE_LOG_LEVEL",
+            help="Log level (DEBUG, INFO, WARNING, ERROR).",
+        ),
+    ] = "info",
+    json_logs: Annotated[
+        bool,
+        typer.Option(
+            "--json-logs",
+            envvar="SIE_LOG_JSON",
+            help="Enable structured JSON logging for Loki.",
+        ),
+    ] = False,
+    reload: Annotated[
+        bool,
+        typer.Option("--reload", "-r", help="Enable auto-reload for development"),
+    ] = False,
+) -> None:
+    """Start the SIE Config Service."""
+    setup_logging(log_level, json_format=json_logs)
+
+    uvicorn.run(
+        "sie_config.app_factory:AppFactory.create_app",
+        host=host,
+        port=port,
+        log_level=log_level.lower(),
+        reload=reload,
+        factory=True,
+    )
+
+
+@app.command()
+def version() -> None:
+    """Show version information."""
+    from sie_config import __version__
+
+    print(f"sie-config {__version__}")
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    app()
+
+
+if __name__ == "__main__":
+    main()