feat: v3.3.0 tire mount periods, tire analytics, and movement-based drive sessions

Dockerfile

@@ -95,6 +95,12 @@ COPY --from=backend-builder /usr/local/bin /usr/local/bin
 COPY --from=backend-builder /app/app ./app
 COPY --from=backend-builder /app/pyproject.toml ./pyproject.toml
 
+# Copy the maintenance tools. The upgrade notes in CHANGELOG.md tell operators
+# to run these against a live instance, and without this they are not in the
+# image at all: every documented command failed with "can't open file".
+# They import `app.*` and expect to run from this directory.
+COPY --from=backend-builder /app/tools ./tools
+
 # Copy frontend build
 COPY --from=frontend-builder /app/frontend/dist ./static
 

backend/app/config.py

@@ -95,6 +95,13 @@ def _normalize_root_path(cls, v: object) -> str:
     # Database
     database_url: str = "sqlite+aiosqlite:////data/mygarage.db"
 
+    # Maintenance mode. Starts the app far enough to apply migrations and no
+    # further: no scheduler, no MQTT subscriber, and telemetry ingest answers
+    # 503. It exists because the odometer repair tools must run before any new
+    # reading lands, and migrations run inside this app's own lifespan, so
+    # without it there is no window in which that instruction can be obeyed.
+    maintenance_mode: bool = False
+
     # File Storage
     data_dir: Path = Path("/data")
     attachments_dir: Path = Path("/data/attachments")

backend/app/database.py

@@ -139,13 +139,11 @@ async def init_db():
     # Run migrations using the migration runner
     logger.info("Running database migrations...")
     try:
-        # Convert async database URL to sync for migrations
-        # asyncpg -> psycopg2, aiosqlite -> sqlite
-        sync_url = settings.database_url
-        if "asyncpg" in sync_url:
-            sync_url = sync_url.replace("postgresql+asyncpg", "postgresql+psycopg2")
-        elif "aiosqlite" in sync_url:
-            sync_url = sync_url.replace("sqlite+aiosqlite", "sqlite")
+        # Convert async database URL to sync for migrations. Shared with the
+        # maintenance tools under backend/tools/, which need the same mapping.
+        from app.utils.db_url import to_sync_url
+
+        sync_url = to_sync_url(settings.database_url)
 
         # Import and run migration runner
         from app.migrations.runner import run_migrations

backend/app/main.py

@@ -163,12 +163,25 @@ async def lifespan(app: FastAPI):
             logger.warning("=" * 80)
 
     # Start scheduled background tasks (session timeouts, device offline detection, etc.)
+    from app.tasks.livelink_tasks import start_mqtt_subscriber, stop_mqtt_subscriber
     from app.tasks.scheduled import start_scheduler, stop_scheduler
 
-    start_scheduler()
+    if settings.maintenance_mode:
+        # Migrations have run; stop here. Neither the scheduler nor the MQTT
+        # subscriber may write, because the whole point of the window is that
+        # the repair tools see the data exactly as the migration left it. A
+        # buffered dongle replays its backlog within seconds of the broker
+        # connecting, which is precisely what this prevents.
+        logger.warning("=" * 80)
+        logger.warning("MAINTENANCE MODE: scheduler and MQTT subscriber not started")
+        logger.warning("MAINTENANCE MODE: telemetry ingest will answer 503")
+        logger.warning("MAINTENANCE MODE: unset MYGARAGE_MAINTENANCE_MODE and restart when done")
+        logger.warning("=" * 80)
+        yield
+        logger.info("Shutting down MyGarage application (maintenance mode)...")
+        return
 
-    # Start MQTT subscriber if enabled
-    from app.tasks.livelink_tasks import start_mqtt_subscriber, stop_mqtt_subscriber
+    start_scheduler()
 
     await start_mqtt_subscriber()
 
@@ -215,13 +228,17 @@ async def lifespan(app: FastAPI):
 from app.middleware import (
     CSRFProtectionMiddleware,
     IngestBodySizeLimitMiddleware,
+    MaintenanceModeMiddleware,
     RequestIDMiddleware,
     SecurityHeadersMiddleware,
 )
 
 # Innermost: the ingest body-size guard runs closest to the app, so its 413
 # still flows out through RequestID + SecurityHeaders and is fully decorated.
 app.add_middleware(IngestBodySizeLimitMiddleware)
+# Just outside it: in maintenance mode there is no point measuring a body we
+# are about to refuse.
+app.add_middleware(MaintenanceModeMiddleware)
 app.add_middleware(CSRFProtectionMiddleware)
 app.add_middleware(RequestIDMiddleware)
 app.add_middleware(SecurityHeadersMiddleware)

backend/app/middleware.py

@@ -13,6 +13,7 @@
 import json
 import logging
 import os
+import re
 import uuid
 from collections.abc import Awaitable, Callable, Mapping
 
@@ -238,6 +239,35 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
 #: the (linear-time) normalizer. An optional Traefik `maxRequestBodyBytes` cap is
 #: documented as deploy-side defense-in-depth but is not in this repo (R1-H3).
 INGEST_PATH = "/api/v1/livelink/ingest"
+
+#: Router prefixes whose handlers write telemetry. Maintenance mode closes these
+#: and nothing else: the rest of the API stays reachable so an operator can watch
+#: the upgrade, and /api/health keeps answering so the container healthcheck does
+#: not fail the maintenance window and trigger a restart.
+#: Ingest routers, closed wholesale: everything under them writes telemetry.
+MAINTENANCE_CLOSED_PREFIXES = ("/api/v1/livelink", "/api/v1/torque")
+
+#: Individual admin routes that write telemetry. The admin router as a whole
+#: must stay OPEN -- the operator uses it to watch the repair and to turn
+#: maintenance mode back off -- so these are matched exactly rather than by
+#: prefix. `POST /api/livelink/devices/{id}/backfill` reaches `bulk_backfill`.
+_MAINTENANCE_CLOSED_ADMIN_RE = re.compile(r"^/api/livelink/devices/[^/]+/backfill/?$")
+
+
+def is_maintenance_closed(path: str) -> bool:
+    """Whether maintenance mode should refuse a request to ``path``.
+
+    Args:
+        path: The request path, without query string.
+
+    Returns:
+        True if the path can write telemetry and must be refused with 503.
+    """
+    if path.startswith(MAINTENANCE_CLOSED_PREFIXES):
+        return True
+    return _MAINTENANCE_CLOSED_ADMIN_RE.match(path) is not None
+
+
 INGEST_MAX_BODY_BYTES = 256 * 1024
 
 
@@ -331,6 +361,48 @@ def _get_header(scope: Scope, name: bytes) -> str | None:
     return None
 
 
+class MaintenanceModeMiddleware:
+    """Refuse telemetry ingest with 503 while the instance is in maintenance mode.
+
+    The upgrade procedure for the odometer repair tools requires that no new
+    reading lands between the migration and the repair. Migrations run inside
+    this app's own lifespan and the MQTT toggle is a database row, so stopping
+    ingest from outside the process is not possible; this closes it from inside.
+
+    ``settings.maintenance_mode`` is read per request rather than captured at
+    construction, so the gate can be flipped in tests without rebuilding the app.
+    The cost is one attribute read per request on a boolean that is almost always
+    False.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        self.app = app
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        from app.config import settings
+
+        if scope["type"] != "http" or not settings.maintenance_mode:
+            await self.app(scope, receive, send)
+            return
+
+        path = scope.get("path", "")
+        if not is_maintenance_closed(path):
+            await self.app(scope, receive, send)
+            return
+
+        logger.info("Maintenance mode: refused ingest request to %s", path)
+        await _send_json(
+            send,
+            status=503,
+            payload={
+                "detail": (
+                    "MyGarage is in maintenance mode and is not accepting telemetry. "
+                    "Readings buffered on the device will be delivered once it exits."
+                )
+            },
+        )
+
+
 async def _send_json(send: Send, *, status: int, payload: Mapping[str, object]) -> None:
     """Emit a JSON response from inside ASGI middleware without recursing.