servicekit 2.0.2__tar.gz → 3.0.0__tar.gz

{servicekit-2.0.2 → servicekit-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: servicekit
-Version: 2.0.2
+Version: 3.0.0
 Summary: Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services
 Keywords: fastapi,sqlalchemy,async,database,rest-api,crud,framework
 Author: Morten Hansen
@@ -15,13 +15,12 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Database
 Requires-Dist: aiosqlite>=0.21.0
 Requires-Dist: alembic>=1.17.0
-Requires-Dist: fastapi[standard]>=0.136.3
+Requires-Dist: fastapi[standard]>=0.142.2
 Requires-Dist: gunicorn>=23.0.0
-Requires-Dist: opentelemetry-api>=1.37.0
+Requires-Dist: opentelemetry-api>=1.44.0
 Requires-Dist: opentelemetry-exporter-prometheus>=0.58b0
-Requires-Dist: opentelemetry-instrumentation-fastapi>=0.58b0
 Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.58b0
-Requires-Dist: opentelemetry-sdk>=1.37.0
+Requires-Dist: opentelemetry-sdk>=1.44.0
 Requires-Dist: pydantic>=2.12.0
 Requires-Dist: python-ulid>=3.1.0
 Requires-Dist: sqlalchemy[asyncio]>=2.0.43
@@ -115,7 +114,7 @@ app = (
     .with_database(url)               # Database configuration
     .with_jobs(max_concurrency=10)   # Job scheduler
     .with_auth()                      # API key authentication
-    .with_monitoring()                # Prometheus metrics
+    .with_monitoring()                # Prometheus metrics (on by default)
     .with_app("./webapp")             # Static web app
     .include_router(custom_router)   # Custom routes
     .build()

{servicekit-2.0.2 → servicekit-3.0.0}/README.md

@@ -79,7 +79,7 @@ app = (
     .with_database(url)               # Database configuration
     .with_jobs(max_concurrency=10)   # Job scheduler
     .with_auth()                      # API key authentication
-    .with_monitoring()                # Prometheus metrics
+    .with_monitoring()                # Prometheus metrics (on by default)
     .with_app("./webapp")             # Static web app
     .include_router(custom_router)   # Custom routes
     .build()

{servicekit-2.0.2 → servicekit-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "servicekit"
-version = "2.0.2"
+version = "3.0.0"
 description = "Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -25,13 +25,12 @@ classifiers = [
 dependencies = [
     "aiosqlite>=0.21.0",
     "alembic>=1.17.0",
-    "fastapi[standard]>=0.136.3",
+    "fastapi[standard]>=0.142.2",
     "gunicorn>=23.0.0",
-    "opentelemetry-api>=1.37.0",
+    "opentelemetry-api>=1.44.0",
     "opentelemetry-exporter-prometheus>=0.58b0",
-    "opentelemetry-instrumentation-fastapi>=0.58b0",
     "opentelemetry-instrumentation-sqlalchemy>=0.58b0",
-    "opentelemetry-sdk>=1.37.0",
+    "opentelemetry-sdk>=1.44.0",
     "pydantic>=2.12.0",
     "python-ulid>=3.1.0",
     "sqlalchemy[asyncio]>=2.0.43",

{servicekit-2.0.2 → servicekit-3.0.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "servicekit"
-version = "2.0.2"
+version = "3.0.0"
 description = "Async SQLAlchemy framework with FastAPI integration - reusable foundation for building data services"
 readme = "README.md"
 authors = [{ name = "Morten Hansen", email = "morten@dhis2.org" }]
@@ -27,13 +27,12 @@ classifiers = [
 dependencies = [
   "aiosqlite>=0.21.0",
   "alembic>=1.17.0",
-  "fastapi[standard]>=0.136.3",
+  "fastapi[standard]>=0.142.2",
   "gunicorn>=23.0.0",
-  "opentelemetry-api>=1.37.0",
+  "opentelemetry-api>=1.44.0",
   "opentelemetry-exporter-prometheus>=0.58b0",
-  "opentelemetry-instrumentation-fastapi>=0.58b0",
   "opentelemetry-instrumentation-sqlalchemy>=0.58b0",
-  "opentelemetry-sdk>=1.37.0",
+  "opentelemetry-sdk>=1.44.0",
   "pydantic>=2.12.0",
   "python-ulid>=3.1.0",
   "sqlalchemy[asyncio]>=2.0.43",

{servicekit-2.0.2 → servicekit-3.0.0}/src/servicekit/api/monitoring.py

@@ -1,9 +1,8 @@
-"""OpenTelemetry monitoring setup with auto-instrumentation."""
+"""OpenTelemetry monitoring setup: Prometheus metrics, SQLAlchemy instrumentation, FastAPI OpenTelemetry."""
 
 from fastapi import FastAPI
 from opentelemetry import metrics
 from opentelemetry.exporter.prometheus import PrometheusMetricReader
-from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
 from opentelemetry.instrumentation.sqlalchemy import SQLAlchemyInstrumentor
 from opentelemetry.sdk.metrics import MeterProvider
 from opentelemetry.sdk.resources import Resource
@@ -28,7 +27,7 @@ def setup_monitoring(
     service_name: str | None = None,
     enable_traces: bool = False,
 ) -> PrometheusMetricReader:
-    """Setup OpenTelemetry with FastAPI and SQLAlchemy auto-instrumentation."""
+    """Setup the global Prometheus meter provider and SQLAlchemy instrumentation; FastAPI OpenTelemetry records HTTP."""
     global _meter_provider_initialized, _sqlalchemy_instrumented, _process_collector_registered, _metric_reader
 
     # Use app title as service name if not provided
@@ -54,11 +53,6 @@ def setup_monitoring(
             # Already registered
             pass
 
-    # Auto-instrument FastAPI - check if already instrumented
-    instrumentor = FastAPIInstrumentor()
-    if not instrumentor.is_instrumented_by_opentelemetry:
-        instrumentor.instrument_app(app)
-
     # Auto-instrument SQLAlchemy - only once globally
     if not _sqlalchemy_instrumented:
         try:
@@ -86,19 +80,12 @@ def setup_monitoring(
 
 
 def teardown_monitoring() -> None:
-    """Teardown OpenTelemetry instrumentation and reset module state."""
-    global _meter_provider_initialized, _sqlalchemy_instrumented, _process_collector_registered, _metric_reader
+    """Teardown SQLAlchemy instrumentation; the global meter provider cannot be replaced, so its reader stays."""
+    global _sqlalchemy_instrumented
 
-    _meter_provider_initialized = False
     _sqlalchemy_instrumented = False
-    _process_collector_registered = False
-    _metric_reader = None
 
     try:
-        # Uninstrument FastAPI
-        FastAPIInstrumentor().uninstrument()
-
-        # Uninstrument SQLAlchemy
         SQLAlchemyInstrumentor().uninstrument()
 
         logger.info("monitoring.disabled")

{servicekit-2.0.2 → servicekit-3.0.0}/src/servicekit/api/service_builder.py

@@ -5,16 +5,20 @@ from __future__ import annotations
 import asyncio
 import os
 import re
+import secrets
 import signal
 import sys
+from collections.abc import MutableMapping, Sequence
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, AsyncContextManager, AsyncGenerator, Awaitable, Callable, Self
 
 from fastapi import APIRouter, FastAPI
+from fastapi.telemetry import TelemetryConfig
 from pydantic import BaseModel, ConfigDict, field_validator
 from sqlalchemy import text
+from starlette.types import ASGIApp, Message, Receive, Scope, Send
 
 from servicekit import Database, SqliteDatabase
 from servicekit.logging import configure_logging, get_logger
@@ -34,6 +38,10 @@ type LifecycleHook = Callable[[FastAPI], Awaitable[None]]
 type DependencyOverride = Callable[..., object]
 type LifespanFactory = Callable[[FastAPI], AsyncContextManager[None]]
 
+# Header the readiness probe sends and expects echoed back, so it only accepts its own app
+_READINESS_TOKEN_HEADER = "x-servicekit-readiness-token"
+_DEFAULT_LOCAL_PORT = 8000
+
 
 @dataclass(frozen=True)
 class _HealthOptions:
@@ -107,6 +115,8 @@ class _RegistrationOptions:
     service_key: str | None
     service_key_env: str
     re_register_grace_period: float
+    local_port: int | None = None
+    local_port_env: str = "PORT"
 
 
 class ServiceInfo(BaseModel):
@@ -159,7 +169,12 @@ class BaseServiceBuilder:
         self._system_options: _SystemOptions | None = None
         self._job_options: JobOptions | None = None
         self._auth_options: _AuthOptions | None = None
-        self._monitoring_options: _MonitoringOptions | None = None
+        self._monitoring_options: _MonitoringOptions | None = _MonitoringOptions(
+            prefix="/metrics",
+            tags=["Observability"],
+            service_name=None,
+            enable_traces=False,
+        )
         self._registration_options: _RegistrationOptions | None = None
         self._app_configs: list[App] = []
         self._custom_routers: list[APIRouter] = []
@@ -307,13 +322,17 @@ class BaseServiceBuilder:
 
     def with_monitoring(
         self,
+        enabled: bool = True,
         *,
         prefix: str = "/metrics",
         tags: list[str] | None = None,
         service_name: str | None = None,
         enable_traces: bool = False,
     ) -> Self:
-        """Enable OpenTelemetry monitoring with Prometheus endpoint and auto-instrumentation."""
+        """Configure OpenTelemetry monitoring (enabled by default); pass enabled=False to turn it off."""
+        if not enabled:
+            self._monitoring_options = None
+            return self
         self._monitoring_options = _MonitoringOptions(
             prefix=prefix,
             tags=list(tags) if tags is not None else ["Observability"],
@@ -341,8 +360,15 @@ class BaseServiceBuilder:
         service_key: str | None = None,
         service_key_env: str = "SERVICEKIT_REGISTRATION_KEY",
         re_register_grace_period: float = 30.0,
+        local_port: int | None = None,
+        local_port_env: str = "PORT",
     ) -> Self:
-        """Enable service registration with orchestrator for service discovery."""
+        """Enable service registration with orchestrator for service discovery.
+
+        ``host``/``port`` (or ``host_env``/``port_env``) form the address advertised to the orchestrator.
+        ``local_port`` (or ``local_port_env``) is the port the app binds locally, probed for readiness
+        before registering; set it when the advertised port differs from the bind port.
+        """
         self._registration_options = _RegistrationOptions(
             orchestrator_url=orchestrator_url,
             host=host,
@@ -360,6 +386,8 @@ class BaseServiceBuilder:
             service_key=service_key,
             service_key_env=service_key_env,
             re_register_grace_period=re_register_grace_period,
+            local_port=local_port,
+            local_port_env=local_port_env,
         )
         return self
 
@@ -408,6 +436,7 @@ class BaseServiceBuilder:
             description=self._app_description,
             version=self._version,
             lifespan=lifespan,
+            telemetry=self._build_telemetry_config(),
         )
         app.state.database_url = self._database_url
 
@@ -534,8 +563,26 @@ class BaseServiceBuilder:
         for dependency, override in self._dependency_overrides.items():
             app.dependency_overrides[dependency] = override
 
+        # Last, so it wraps any build_middleware_stack patch made above
+        if self._registration_options is not None:
+            app.state.readiness_token = secrets.token_hex(16)
+            app.build_middleware_stack = _wrap_with_readiness_token(app)  # type: ignore[method-assign]
+
         return app
 
+    def _build_telemetry_config(self) -> TelemetryConfig:
+        """Build FastAPI OpenTelemetry settings: skip metrics scrapes when enabled, turn everything off when not."""
+        if self._monitoring_options is None:
+            return {"tracing": False, "metrics": False, "logs": False, "auto_configure": False}
+        metrics_prefix = self._monitoring_options.prefix
+
+        def exclude_metrics_scrape(scope: MutableMapping[str, Any]) -> bool:
+            """Skip telemetry for requests to the metrics endpoint."""
+            path = str(scope.get("path", ""))
+            return path == metrics_prefix or path.startswith(f"{metrics_prefix}/")
+
+        return {"exclude": exclude_metrics_scrape}
+
     # --------------------------------------------------------------------- Extension points
 
     def _validate_module_configuration(self) -> None:
@@ -882,49 +929,99 @@ class BaseServiceBuilder:
         return cls(info=info, **kwargs).build()
 
 
-def _resolve_port(options: _RegistrationOptions) -> int:
-    """Resolve port from options or environment, matching register_service logic."""
-    if options.port is not None:
-        return options.port
-    port_str = os.getenv(options.port_env)
-    if port_str:
-        try:
-            return int(port_str)
-        except ValueError:
-            return 8000
-    return 8000
+class _ReadinessTokenMiddleware:
+    """Echo the readiness token header on responses to requests that present the matching token."""
+
+    def __init__(self, app: ASGIApp, *, token: str) -> None:
+        """Wrap the ASGI app with the per-instance readiness token."""
+        self.app = app
+        self.token = token
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        """Pass the request through, tagging the response when the probe token matches."""
+        if scope["type"] != "http" or not self._has_token(scope):
+            await self.app(scope, receive, send)
+            return
+
+        async def send_with_token(message: Message) -> None:
+            """Append the token header to the response start message."""
+            if message["type"] == "http.response.start":
+                headers = list(message.get("headers", []))
+                headers.append((_READINESS_TOKEN_HEADER.encode("latin-1"), self.token.encode("latin-1")))
+                message = {**message, "headers": headers}
+            await send(message)
+
+        await self.app(scope, receive, send_with_token)
+
+    def _has_token(self, scope: Scope) -> bool:
+        """Return whether the request carries this instance's readiness token."""
+        expected = (_READINESS_TOKEN_HEADER.encode("latin-1"), self.token.encode("latin-1"))
+        return any((name.lower(), value) == expected for name, value in scope.get("headers", []))
+
+
+def _wrap_with_readiness_token(app: FastAPI) -> Callable[[], ASGIApp]:
+    """Wrap the app's middleware stack builder so readiness token tagging is always the outermost layer."""
+    build_middleware_stack = app.build_middleware_stack
+
+    def build_with_readiness_token() -> ASGIApp:
+        """Build the regular stack, including middleware added after build(), inside the token middleware."""
+        return _ReadinessTokenMiddleware(build_middleware_stack(), token=app.state.readiness_token)
+
+    return build_with_readiness_token
+
+
+def _parse_port(value: str | None) -> int | None:
+    """Parse a port from an environment value, returning None when unset or invalid."""
+    if not value:
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _local_port_candidates(options: _RegistrationOptions) -> list[int]:
+    """Resolve the local ports to probe for readiness, most specific first."""
+    if options.local_port is not None:
+        return [options.local_port]
+    advertised_port = options.port if options.port is not None else _parse_port(os.getenv(options.port_env))
+    candidates = [_parse_port(os.getenv(options.local_port_env)), advertised_port, _DEFAULT_LOCAL_PORT]
+    return list(dict.fromkeys(port for port in candidates if port is not None))
 
 
 async def _wait_until_ready(
-    port: int, *, health_path: str | None = None, poll_interval: float = 0.5, timeout: float = 30.0
-) -> bool:
-    """Poll the local app until it is serving requests."""
+    ports: Sequence[int],
+    *,
+    token: str,
+    health_path: str | None = None,
+    poll_interval: float = 0.5,
+    timeout: float = 30.0,
+) -> int | None:
+    """Poll the candidate local ports until this app serves requests, returning the ready port or None."""
     import httpx
 
-    if health_path:
-        url = f"http://127.0.0.1:{port}{health_path}"
-        check_kind = "health"
-    else:
-        url = f"http://127.0.0.1:{port}/"
-        check_kind = "tcp"
+    path = health_path or "/"
+    check_kind = "health" if health_path else "tcp"
+    headers = {_READINESS_TOKEN_HEADER: token}
 
     deadline = asyncio.get_event_loop().time() + timeout
     while asyncio.get_event_loop().time() < deadline:
-        try:
-            async with httpx.AsyncClient() as client:
-                response = await client.get(url, timeout=2.0)
-                if health_path:
-                    if response.status_code == 200:
-                        return True
-                else:
-                    # Any response means the server is accepting connections
-                    return True
-        except Exception:
-            pass
+        for port in ports:
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(f"http://127.0.0.1:{port}{path}", headers=headers, timeout=2.0)
+            except Exception:
+                continue
+            # Something else listening on a candidate port (e.g. the orchestrator itself) is not us
+            if response.headers.get(_READINESS_TOKEN_HEADER) != token:
+                continue
+            # In tcp mode any response means the server is accepting connections
+            if not health_path or response.status_code == 200:
+                return port
         await asyncio.sleep(poll_interval)
 
-    logger.warning("registration.readiness_timeout", port=port, check=check_kind, timeout=timeout)
-    return False
+    logger.warning("registration.readiness_timeout", ports=list(ports), check=check_kind, timeout=timeout)
+    return None
 
 
 def _fail_registration(app: FastAPI, reason: str) -> None:
@@ -992,18 +1089,19 @@ async def _register_after_ready(
     options: _RegistrationOptions, info: BaseModel, app: FastAPI, health_path: str | None
 ) -> None:
     """Wait for the app to be ready, then register with the orchestrator."""
-    port = _resolve_port(options)
-    ready = await _wait_until_ready(port, health_path=health_path)
-    if not ready:
+    ports = _local_port_candidates(options)
+    ready_port = await _wait_until_ready(ports, token=app.state.readiness_token, health_path=health_path)
+    if ready_port is None:
         if options.fail_on_error:
-            _fail_registration(app, f"App on port {port} never became ready, cannot register")
+            _fail_registration(app, f"App never became ready on local ports {ports}, cannot register")
         else:
             logger.error(
                 "registration.aborted",
-                port=port,
+                ports=ports,
                 message="App never became ready, skipping registration",
             )
         return
+    logger.debug("registration.ready", port=ready_port)
 
     # Shield registration from cancellation so that if the POST succeeds,
     # app.state.registration_info is always written before the task exits.

{servicekit-2.0.2 → servicekit-3.0.0}/src/servicekit/api/utilities.py

@@ -41,9 +41,10 @@ def run_app(
     Args:
         app: FastAPI app instance OR string "module:app" path
         host: Server host (default: "127.0.0.1", env: HOST)
-        port: Server port (default: 8000, env: PORT). The resolved value is also
-            exported as SERVICEKIT_PORT (unless already set) so service
-            registration advertises and probes the same port uvicorn binds.
+        port: Server port (default: 8000, env: PORT). The resolved value is
+            exported as PORT so service registration probes the port uvicorn
+            binds, and as SERVICEKIT_PORT (unless already set) so it is also
+            the advertised port by default.
         workers: Number of worker processes (default: 1, env: WORKERS)
         reload: Enable auto-reload (default: True for string, False for instance)
         log_level: Logging level (default: from LOG_LEVEL env var or "info")
@@ -71,10 +72,11 @@ def run_app(
         reload = False
 
     # Make the bind port visible to service registration, which runs inside the
-    # app lifespan and otherwise resolves its own port (SERVICEKIT_PORT, else
-    # 8000) with no knowledge of where uvicorn actually bound. setdefault means an
-    # explicitly set SERVICEKIT_PORT (e.g. an externally advertised port behind a
-    # proxy) still wins.
+    # app lifespan with no knowledge of where uvicorn actually bound. PORT is the
+    # local port its readiness probe tries first. SERVICEKIT_PORT is the port
+    # advertised to the orchestrator; setdefault means an explicitly set value
+    # (e.g. a published host port or a port behind a proxy) still wins.
+    os.environ["PORT"] = str(resolved_port)
     os.environ.setdefault("SERVICEKIT_PORT", str(resolved_port))
 
     uvicorn.run(