cctv-stack 0.3.1__tar.gz → 0.5.0__tar.gz

{cctv_stack-0.3.1 → cctv_stack-0.5.0}/.gitignore

@@ -5,6 +5,9 @@ __pycache__/
 build/
 dist/
 
+# mkdocs output. Generated by `uv run mkdocs build`; the published copy is built by CI.
+site/
+
 # Environments
 .venv/
 venv/
@@ -39,6 +42,13 @@ data/
 # is the site's file, not the repository's. `cameras.example.yml` is committed; this is not.
 config/cameras.yml
 
+# The generated monitoring config. It carries the heartbeat token and is derived from
+# cameras.yml at start-up, so editing it by hand is wasted work as well.
+config/gatus/
+
+# Generated by install.sh from probes of this machine (lld/07 §5).
+config/host.yml
+
 # Generated Frigate config, plus Frigate's own runtime state, because the directory is
 # mounted as its /config.
 #

{cctv_stack-0.3.1 → cctv_stack-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cctv-stack
-Version: 0.3.1
+Version: 0.5.0
 Summary: A packaging-first self-hosted CCTV stack built on Frigate.
 Project-URL: Homepage, https://github.com/aravindmyd/cctv-stack
 Project-URL: Repository, https://github.com/aravindmyd/cctv-stack
@@ -252,9 +252,9 @@ adds the four pieces it leaves to the operator:
 
 It is not a replacement for Frigate. It is the missing layer around it.
 
-**Current release: `0.3.0`.** Clips, B2 upload, local retention and health are
-implemented. Cloud retention, an aggregate status page and the one-command installer are
-not — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the exact state and roadmap.
+**Current release: `0.5.0`.** Clips, B2 upload, local retention, the aggregate status page
+and alerting through Gatus/ntfy are implemented. Cloud retention and the one-command
+installer are not — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the exact state and roadmap.
 
 ---
 
@@ -281,10 +281,10 @@ pip install "cctv-stack[mqtt,storage]"
 ### Container image
 
 ```bash
-docker pull ghcr.io/aravindmyd/cctv-stack:0.3.0
+docker pull ghcr.io/aravindmyd/cctv-stack:0.5.0
 ```
 
-Tags published per release: `:0.3.0`, `:0.3`, and the commit tag `:sha-<short>`.
+Tags published per release: `:0.5.0`, `:0.5`, and the commit tag `:sha-<short>`.
 A moving `:edge` tag follows `master`. If the registry package is private, run
 `docker login ghcr.io` first. The image includes `ffmpeg`/`ffprobe`.
 
@@ -297,10 +297,16 @@ A moving `:edge` tag follows `master`. If the registry package is private, run
 | `cctv-clip-worker` | Turn completed Frigate reviews into canonical clips |
 | `cctv-uploader` | Upload clips to B2 through the persisted retry state machine |
 | `cctv-cleanup` | Enforce local retention after a successful upload |
+| `cctv-status` | Serve the aggregate status page (`:8084/status`), health and metrics |
+| `cctv-host` | Detect this machine's host profile and Frigate's `shm_size` |
 
-The three services are long-running and configuration-driven; they take no command-line
+The four services are long-running and configuration-driven; they take no command-line
 arguments. Run them under systemd, Docker, or Compose.
 
+With Compose, the answer to *is my CCTV working?* is at
+`http://<host>:8084/status`; the dashboard and history are at `http://<host>:3001` (Gatus),
+and alerts arrive through ntfy at `http://<host>:8085`.
+
 ## Quick start
 
 The only required input is a `cameras.yml`. This minimal file is valid; `${VAR}` values

{cctv_stack-0.3.1 → cctv_stack-0.5.0}/README.md

@@ -18,9 +18,9 @@ adds the four pieces it leaves to the operator:
 
 It is not a replacement for Frigate. It is the missing layer around it.
 
-**Current release: `0.3.0`.** Clips, B2 upload, local retention and health are
-implemented. Cloud retention, an aggregate status page and the one-command installer are
-not — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the exact state and roadmap.
+**Current release: `0.5.0`.** Clips, B2 upload, local retention, the aggregate status page
+and alerting through Gatus/ntfy are implemented. Cloud retention and the one-command
+installer are not — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the exact state and roadmap.
 
 ---
 
@@ -47,10 +47,10 @@ pip install "cctv-stack[mqtt,storage]"
 ### Container image
 
 ```bash
-docker pull ghcr.io/aravindmyd/cctv-stack:0.3.0
+docker pull ghcr.io/aravindmyd/cctv-stack:0.5.0
 ```
 
-Tags published per release: `:0.3.0`, `:0.3`, and the commit tag `:sha-<short>`.
+Tags published per release: `:0.5.0`, `:0.5`, and the commit tag `:sha-<short>`.
 A moving `:edge` tag follows `master`. If the registry package is private, run
 `docker login ghcr.io` first. The image includes `ffmpeg`/`ffprobe`.
 
@@ -63,10 +63,16 @@ A moving `:edge` tag follows `master`. If the registry package is private, run
 | `cctv-clip-worker` | Turn completed Frigate reviews into canonical clips |
 | `cctv-uploader` | Upload clips to B2 through the persisted retry state machine |
 | `cctv-cleanup` | Enforce local retention after a successful upload |
+| `cctv-status` | Serve the aggregate status page (`:8084/status`), health and metrics |
+| `cctv-host` | Detect this machine's host profile and Frigate's `shm_size` |
 
-The three services are long-running and configuration-driven; they take no command-line
+The four services are long-running and configuration-driven; they take no command-line
 arguments. Run them under systemd, Docker, or Compose.
 
+With Compose, the answer to *is my CCTV working?* is at
+`http://<host>:8084/status`; the dashboard and history are at `http://<host>:3001` (Gatus),
+and alerts arrive through ntfy at `http://<host>:8085`.
+
 ## Quick start
 
 The only required input is a `cameras.yml`. This minimal file is valid; `${VAR}` values

{cctv_stack-0.3.1 → cctv_stack-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cctv-stack"
-version = "0.3.1"
+version = "0.5.0"
 description = "A packaging-first self-hosted CCTV stack built on Frigate."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -74,6 +74,8 @@ cctv-clip-worker = "cctv.worker:main"
 cctv-config = "cctv.config_cli:main"
 cctv-uploader = "cctv.uploader:main"
 cctv-cleanup = "cctv.cleanup:main"
+cctv-status = "cctv.status_service:main"
+cctv-host = "cctv.host_cli:main"
 
 [project.urls]
 Homepage = "https://github.com/aravindmyd/cctv-stack"

{cctv_stack-0.3.1 → cctv_stack-0.5.0}/src/cctv/__init__.py

@@ -16,4 +16,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.3.1"
+__version__ = "0.5.0"

{cctv_stack-0.3.1 → cctv_stack-0.5.0}/src/cctv/db.py

@@ -1476,3 +1476,109 @@ def overdue_local(conn: sqlite3.Connection, *, camera: str, cutoff: Instant) ->
             None if row["oldest"] is None else max(0.0, cutoff - float(row["oldest"]))
         ),
     )
+
+
+# ---------------------------------------------------------------------------------------
+# Status-collector reads. All read-only, all bounded, none of them a table scan on every
+# scrape: the collector polls these on its own cadence, and a status page that is expensive
+# to render is a status page that hides problems behind its own latency.
+# ---------------------------------------------------------------------------------------
+
+
+def last_clip_per_camera(conn: sqlite3.Connection) -> dict[str, Instant]:
+    """The most recent clip start time for each camera that has ever produced one.
+
+    A camera absent from this mapping has never produced a clip. That is different from a
+    camera whose last clip is old, and the status page must not conflate them: a camera added
+    ten minutes ago is not "quiet since 1970".
+    """
+    return {
+        str(row["camera"]): float(row["last"])
+        for row in conn.execute("SELECT camera, MAX(start_time) AS last FROM clips GROUP BY camera")
+    }
+
+
+def clip_start_times_since(
+    conn: sqlite3.Connection, *, since: Instant, limit_per_camera: int = 500
+) -> dict[str, list[Instant]]:
+    """Clip start times per camera since `since`, newest first.
+
+    The silent-camera check (lld/06 §3.4) needs the *typical* gap between clips, which is a
+    median over history rather than a count. One clip per minute for a busy doorbell would
+    make an unbounded query grow with footage; `limit_per_camera` keeps the query's cost flat
+    while leaving far more samples than a median needs.
+    """
+    out: dict[str, list[Instant]] = {}
+    for row in conn.execute(
+        "SELECT camera, start_time FROM ("
+        "  SELECT camera, start_time,"
+        "         ROW_NUMBER() OVER (PARTITION BY camera ORDER BY start_time DESC) AS n"
+        "    FROM clips WHERE start_time >= ?"
+        ") WHERE n <= ? ORDER BY camera, start_time DESC",
+        (since, limit_per_camera),
+    ):
+        out.setdefault(str(row["camera"]), []).append(float(row["start_time"]))
+    return out
+
+
+@dataclass(frozen=True, slots=True)
+class DiskSample:
+    at: Instant
+    free_bytes: int
+    clips_bytes: int
+    media_bytes: int
+
+
+def record_disk_sample(
+    conn: sqlite3.Connection,
+    *,
+    at: Instant,
+    free_bytes: int,
+    clips_bytes: int,
+    media_bytes: int,
+) -> None:
+    """Upsert one sample. Keyed on `at`, so a retried collection cannot duplicate history."""
+    with write_txn(conn):
+        conn.execute(
+            "INSERT OR REPLACE INTO disk_samples (at, free_bytes, clips_bytes, media_bytes) "
+            "VALUES (?, ?, ?, ?)",
+            (at, free_bytes, clips_bytes, media_bytes),
+        )
+
+
+def disk_samples_since(conn: sqlite3.Connection, *, since: Instant) -> list[DiskSample]:
+    """Samples from `since` onwards, oldest first. The storage projection's only input."""
+    return [
+        DiskSample(
+            at=float(row["at"]),
+            free_bytes=int(row["free_bytes"]),
+            clips_bytes=int(row["clips_bytes"]),
+            media_bytes=int(row["media_bytes"]),
+        )
+        for row in conn.execute(
+            "SELECT at, free_bytes, clips_bytes, media_bytes FROM disk_samples "
+            "WHERE at >= ? ORDER BY at",
+            (since,),
+        )
+    ]
+
+
+def prune_disk_samples(conn: sqlite3.Connection, *, before: Instant) -> int:
+    """Delete samples older than `before`. Returns how many rows went."""
+    with write_txn(conn):
+        cur = conn.execute("DELETE FROM disk_samples WHERE at < ?", (before,))
+    return int(cur.rowcount or 0)
+
+
+def last_cleanup_run_at(conn: sqlite3.Connection) -> Instant | None:
+    """When retention last completed a pass, from the row `cctv-cleanup` writes.
+
+    Read here rather than derived from `clips`, because "retention is running" is a fact only
+    the cleanup service knows; a database with nothing to delete looks identical whether
+    cleanup is working or dead.
+    """
+    row = conn.execute(
+        "SELECT COALESCE(last_success_at, last_run_at) AS at FROM sweep_state "
+        "WHERE name = 'cleanup_local'"
+    ).fetchone()
+    return None if row is None or row["at"] is None else float(row["at"])

{cctv_stack-0.3.1 → cctv_stack-0.5.0}/src/cctv/health.py

@@ -19,6 +19,7 @@ Endpoints, per
 ```text
 GET  /health          JSON report;  ?strict=1 makes DEGRADED/UNKNOWN return 503
 GET  /metrics         Prometheus text exposition
+GET  /status          aggregate status (status-collector only): JSON, or HTML to a browser
 GET  /admin/queue     backlog summary (requires INTERNAL_API_TOKEN)
 POST /admin/retry     requeue failed clips (requires INTERNAL_API_TOKEN and a reason)
 ```
@@ -76,11 +77,13 @@ CODES = frozenset(
     {
         "BACKLOG_AGING",
         "CAMERA_OFFLINE",
+        "CAMERA_QUIET",
         "CLEANUP_STALE",
         "CLIPS_OVERDUE_RETENTION",
         "CLIP_COVERAGE_LOW",
         "CLIP_FLUSH_PRESSURE",
         "CLIP_HAS_GAPS",
+        "COLLECTOR_STALE",
         "DB_INTEGRITY_FAILED",
         "DB_UNAVAILABLE",
         "DETECTION_FALLING_BEHIND",
@@ -304,6 +307,9 @@ class _Handler(BaseHTTPRequestHandler):
         if path.path == "/metrics":
             self._metrics()
             return
+        if path.path == "/status":
+            self._status()
+            return
         if path.path == "/admin/queue":
             self._admin_queue()
             return
@@ -326,6 +332,24 @@ class _Handler(BaseHTTPRequestHandler):
         gauges = self._config.gauges() if self._config.gauges else None
         self._write(200, render_metrics(report, gauges=gauges).encode("utf-8"), "text/plain")
 
+    def _status(self) -> None:
+        """Aggregate status: HTML for a browser, JSON for everything else.
+
+        Negotiated on `Accept` rather than a separate path, so a monitor and a human can be
+        given the same URL and neither has to know the other exists. A service that did not
+        mount the route (every service but `status-collector`) answers 404 rather than an
+        empty page, which is the honest thing to say.
+        """
+        if self._config.status is None:
+            self._json(HTTPStatus.NOT_FOUND, {"error": "no aggregate status on this service"})
+            return
+        wants_html = "text/html" in (self.headers.get("Accept") or "")
+        if wants_html and self._config.status_html is not None:
+            body = self._config.status_html().encode("utf-8")
+            self._write(200, body, "text/html; charset=utf-8")
+            return
+        self._json(200, dict(self._config.status()))
+
     def _admin_guard(self) -> bool:
         if self._config.admin is None or not self._config.token:
             self._json(
@@ -385,12 +409,16 @@ class HealthServer(ThreadingHTTPServer):
         admin: AdminRoutes | None = None,
         token: str | None = None,
         gauges: Callable[[], Mapping[str, float | int]] | None = None,
+        status: Callable[[], Mapping[str, Any]] | None = None,
+        status_html: Callable[[], str] | None = None,
     ) -> None:
         super().__init__(address, _Handler)
         self.snapshot = snapshot
         self.admin = admin
         self.token = token
         self.gauges = gauges
+        self.status = status
+        self.status_html = status_html
 
 
 def start_health_server(
@@ -401,13 +429,23 @@ def start_health_server(
     admin: AdminRoutes | None = None,
     token: str | None = None,
     gauges: Callable[[], Mapping[str, float | int]] | None = None,
+    status: Callable[[], Mapping[str, Any]] | None = None,
+    status_html: Callable[[], str] | None = None,
 ) -> tuple[HealthServer, threading.Thread]:
     """Start serving in a background thread. Returns the server and its thread.
 
     Port `0` means "disabled" — a deployment that does not want the surface pays nothing for
     it, and the caller logs that choice rather than leaving it implicit.
     """
-    server = HealthServer((host, port), snapshot=snapshot, admin=admin, token=token, gauges=gauges)
+    server = HealthServer(
+        (host, port),
+        snapshot=snapshot,
+        admin=admin,
+        token=token,
+        gauges=gauges,
+        status=status,
+        status_html=status_html,
+    )
     thread = threading.Thread(target=server.serve_forever, name="health", daemon=True)
     thread.start()
     return server, thread