Skip to content

feat: optional Plex activity (Tautulli) integration + latency-aware health chips#60

Open
ndandan wants to merge 1 commit into
Shoshuo:mainfrom
ndandan:pr/tautulli-activity
Open

feat: optional Plex activity (Tautulli) integration + latency-aware health chips#60
ndandan wants to merge 1 commit into
Shoshuo:mainfrom
ndandan:pr/tautulli-activity

Conversation

@ndandan

@ndandan ndandan commented Jun 19, 2026

Copy link
Copy Markdown

What

Adds an optional, read-only Plex activity integration via the Tautulli API, plus a latency-aware rework of the dashboard service-health chips (the two ship together because both pivot on HealthService).

Plex activity (Tautulli)

Configured like any other service in /admin/settings (URL + API key), gated by isConfigured(), and registered with the per-service health circuit breaker. Two surfaces:

  • Dashboard "Current Plex activity" widget — active stream count, Direct Play / Direct Stream / Transcode breakdown, total / LAN / WAN bandwidth, and a per-session card (quality, HDR/SDR badge, source→target codec when transcoding). Async fragment (/tableau-de-bord/widget/plex) that hydrates on its own and refreshes every 10 s. Returns an empty body (hidden client-side) when Tautulli isn't configured.
  • Dedicated Plex Activity page (own sidebar entry, route-guarded) — now-playing strip, watch statistics with a 7 / 30 / 90-day toggle (top movies / shows / users / platforms), plays-over-time graphs with a Media-type ⇄ Stream-type toggle plus by-hour and by-day-of-week breakdowns and a platform × stream-type "problem clients" chart, a dense watch-history grid, per-library counts, and an in-app info modal per title (synopsis, ratings, cast/crew).

Security/robustness: the API key never leaves the server, every Tautulli response is normalised/sanitised before it reaches the browser, and each section/widget fails open independently so a down or misconfigured Tautulli never breaks the dashboard or the page. Chart.js is self-hosted under public/static/chart/ for CSP compliance (no CDN), and the existing Radarr stats chart is repointed at the self-hosted copy.

Latency-aware health chips

HealthService::statusFor() returns ['status' => up|slow|very_slow|down|degraded|null, 'latencyMs' => ?int], cached 10 s exactly like the old bool path — which now delegates to it, so isHealthy() keeps its existing contract for every current caller. The dashboard chips render the five states with a coloured dot, so a reachable-but-slow service is visibly distinct from a healthy one.

Why

Plex/Tautulli is one of the most-requested homelab companions to the *arr stack, and the health chips going from "up/down" to "up/slow/degraded/down" makes a struggling-but-reachable service legible at a glance.

Definition of Done

  • Tests: TautulliClient (HTTP, normalizers, edge cases — nulls, empty, unicode, boundaries), TautulliController (endpoints + route guard), HealthService::statusFor() / classifyLatency() (incl. the 750/2000 ms boundaries and cache-hit), and the shared relative_date Twig filter. make check (lint + Twig + full PHPUnit) green.
  • Security: read-only integration; API key stays server-side and never appears in a response; user-supplied Tautulli URL goes through the same SSRF protocol guard + redirect limits as the other clients; healthInvalidate whitelists tautulli.
  • UI/UX: Turbo-safe inline JS (IIFE, var, .then(), declarative modal triggers, polling timers cleaned up on turbo:before-render); dynamic values escaped via escHtml; tested in dark + light + a mobile viewport.
  • Docs: README.md (Plex activity section + Tautulli prereq) and CHANGELOG.md [Unreleased] updated.

Scoped as part of a per-feature contribution series. The dashboard tiles in this PR do not yet carry the quick-look hooks — that ships as a separate follow-up PR stacked on top of this one.

…alth chips

Adds a read-only Tautulli integration (configured in /admin/settings, behind
the per-service health circuit breaker) that surfaces current Plex activity:

- Dashboard "Current Plex activity" widget — active streams, Direct Play /
  Direct Stream / Transcode counts, total/LAN/WAN bandwidth, per-session cards
  (quality, HDR/SDR badge, source->target codec on transcode). Hydrates async
  and refreshes every 10s; fails open so a down Tautulli never breaks the page.
- Dedicated Plex Activity page (own sidebar entry): now-playing strip, watch
  stats with a 7/30/90-day toggle, plays-over-time graphs (Media/Stream-type
  toggle, by-hour, by-day-of-week, platform x stream-type problem-clients),
  dense history grid, per-library counts, and an in-app info modal per title.
- API key stays server-side; every response is sanitised before the browser.
- Chart.js self-hosted for CSP compliance, reused by the Radarr stats chart.

Also reworks the dashboard service-health chips to show latency:
HealthService::statusFor() returns a status word + round-trip ms (cached 10s,
isHealthy() now delegates to it and keeps its old contract). Chips render five
states (up / slow / very_slow / down / degraded) with a coloured dot.

Tests: TautulliClient (HTTP + normalizers + edge cases), TautulliController
(endpoints + route guard), HealthService statusFor/classifyLatency, and the
relative_date Twig filter.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant