Refactored stream observations and config refresh handling.

- Replaced legacy typing (Optional, List, Type, Union, Tuple) with PEP 604/585 equivalents.
- Added pyproject.toml with configurations for hatch-vcs, mypy, ruff, and codespell.
- Added CI workflows for formatting, linting, type checking, and spelling.
- Added CD workflow for building and uploading plugin artifacts on push to master and version tags.
- Added dependency auditing workflow with pip-audit.
- Added comprehensive docstrings and inline comments across all modules.
- Fixed User-Agent header using hardcoded version instead of actual plugin version.
- Fixed grammar and terminology in log messages and comments.
- Removed unreachable error handling branch in unsubscribe command.

.gitea/workflows/audit.yml

@@ -0,0 +1,35 @@
+name: Audit
+
+on:
+  schedule:
+    - cron: "0 0 * * 1"
+  push:
+    paths: [uv.lock]
+  pull_request:
+    paths: [uv.lock]
+
+permissions:
+  contents: read
+
+env:
+  UV_PYTHON_DOWNLOADS: never
+
+jobs:
+  audit:
+    name: Dependencies
+    runs-on: logaldeveloper-archlinux-ci
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Cache uv packages
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ hashFiles('uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Audit dependencies with pip-audit
+        run: uv run pip-audit --skip-editable

.gitea/workflows/cd.yml

@@ -0,0 +1,75 @@
+name: CD
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+  # packages: write  # not yet supported by Gitea
+
+env:
+  UV_PYTHON_DOWNLOADS: never
+
+jobs:
+  publish:
+    name: Publish
+    runs-on: logaldeveloper-archlinux-ci
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Install dependencies
+        run: uv sync --locked --no-dev
+
+      - name: Generate package metadata
+        id: metadata
+        run: |
+          version="${{ gitea.ref_name }}"
+          version="${version#v}"
+          printf 'version=%s\n' "$version" | tee -a "$GITEA_OUTPUT"
+
+      - name: Write version into maubot.yaml
+        run: |
+          sed -i "s/^version: .*/version: ${{ steps.metadata.outputs.version }}/" maubot.yaml
+          grep "^version:" maubot.yaml
+
+      - name: Build plugin
+        run: 7z a -tzip -mx=9 -xr!__pycache__ owncastsentry-v${{ steps.metadata.outputs.version }}.mbp owncastsentry/ maubot.yaml base-config.yaml LICENSE.txt
+
+      - name: Print artifact checksums
+        run: |
+          echo "MD5: $(md5sum owncastsentry-v${{ steps.metadata.outputs.version }}.mbp)"
+          echo "SHA1: $(sha1sum owncastsentry-v${{ steps.metadata.outputs.version }}.mbp)"
+          echo "SHA256: $(sha256sum owncastsentry-v${{ steps.metadata.outputs.version }}.mbp)"
+
+      - name: Generate SBOM
+        env:
+          SYFT_CHECK_FOR_APP_UPDATE: "false"
+        run: |
+          syft scan dir:.venv \
+            --override-default-catalogers python-installed-package-cataloger \
+            --select-catalogers=-file \
+            --source-name git.logal.dev/LogalDeveloper/OwncastSentry \
+            --source-version "${{ steps.metadata.outputs.version }}" \
+            --output syft-table \
+            --output cyclonedx-json=owncastsentry-${{ steps.metadata.outputs.version }}.cyclonedx.json
+          sha256sum owncastsentry-${{ steps.metadata.outputs.version }}.cyclonedx.json
+          zstd -T0 --ultra -22 \
+            owncastsentry-${{ steps.metadata.outputs.version }}.cyclonedx.json
+
+      - name: Upload plugin artifact
+        uses: https://github.com/christopherhx/gitea-upload-artifact@8818363695ca2d5782c64f6453273341374767b7 # v7
+        with:
+          path: owncastsentry-v${{ steps.metadata.outputs.version }}.mbp
+          archive: "false"
+
+      - name: Upload SBOM artifact
+        uses: https://github.com/christopherhx/gitea-upload-artifact@8818363695ca2d5782c64f6453273341374767b7 # v7
+        with:
+          name: owncastsentry-cyclonedx-${{ steps.metadata.outputs.version }}
+          path: owncastsentry-${{ steps.metadata.outputs.version }}.cyclonedx.json.zst
+          if-no-files-found: error
+          archive: "false"

.gitea/workflows/ci.yml

@@ -0,0 +1,110 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  UV_PYTHON_DOWNLOADS: never
+
+jobs:
+  formatting:
+    name: Formatting
+    runs-on: logaldeveloper-archlinux-ci
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Cache uv packages
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ hashFiles('uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Check formatting with Ruff
+        run: uv run ruff format --check --diff .
+
+  linting:
+    name: Linting
+    runs-on: logaldeveloper-archlinux-ci
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Cache uv packages
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ hashFiles('uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Check linting with Ruff
+        run: uv run ruff check .
+
+  tests:
+    name: Tests
+    runs-on: logaldeveloper-archlinux-ci
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Cache uv packages
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ hashFiles('uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Run unit tests with Pytest
+        run: uv run pytest -v --cov --cov-report=
+
+      - name: Report code coverage
+        run: uv run coverage report
+
+  type-checking:
+    name: Type Checking
+    runs-on: logaldeveloper-archlinux-ci
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Cache uv packages
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ hashFiles('uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Check types with Mypy
+        run: uv run mypy .
+
+  spelling:
+    name: Spelling
+    runs-on: logaldeveloper-archlinux-ci
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Cache uv packages
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ hashFiles('uv.lock') }}
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Check spelling with codespell
+        run: uv run codespell

.gitignore

@@ -1,3 +1,6 @@
 __pycache__/
 *.py[cod]
 *$py.class
+.venv/
+owncastsentry/_version.py
+.coverage

LICENSE.txt

@@ -1,6 +1,7 @@
+
                                  Apache License
                            Version 2.0, January 2004
-                        https://www.apache.org/licenses/
+                        http://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -174,3 +175,28 @@
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

base-config.yaml

@@ -0,0 +1,4 @@
+# Prometheus metrics endpoint.
+# When enabled, a /metrics endpoint is exposed via the maubot webapp.
+# Disabled by default.
+metrics_enabled: false

maubot.yaml

@@ -7,3 +7,9 @@ modules:
 main_class: OwncastSentry
 database: true
 database_type: asyncpg
+config: true
+webapp: true
+dependencies:
+  - prometheus_client>=0.24.1
+extra_files:
+  - base-config.yaml

owncastsentry/README.md

@@ -0,0 +1,390 @@
+# OwncastSentry Package
+
+This package contains the Maubot plugin runtime code for OwncastSentry. It
+tracks room subscriptions to Owncast instances, polls subscribed streams,
+detects stream state changes, and sends Matrix notifications.
+
+This README gives maintainers a high-level map of how the package fits
+together and where the important behavior lives. User-facing setup and command
+usage belong outside this package. Function-level details belong in docstrings
+or tests.
+
+## Files
+
+- `__init__.py`: Maubot plugin entry point, service wiring, command
+  decorators, scheduler loop, shutdown, and metrics endpoint.
+- `config.py`: Maubot configuration proxy for the Prometheus metrics endpoint
+  setting.
+- `types.py`: immutable value objects, Owncast API response validation, derived
+  stream status, update results, and subscription domain errors.
+- `repository.py`: database schema migrations plus stream and subscription
+  repositories.
+- `owncast_client.py`: bounded aiohttp client for Owncast `/api/status` and
+  `/api/config` requests.
+- `subscription_manager.py`: subscription use cases, domain normalization, and
+  first-subscription Owncast validation.
+- `stream_monitor.py`: stream update orchestration, state transition detection,
+  progressive failure backoff, cleanup thresholds, notification decisions, and
+  stream metrics.
+- `notification_service.py`: Matrix notification formatting, broadcast,
+  per-domain notification cooldowns, cleanup notices, and delivery metrics.
+- `commands.py`: Maubot command handlers for subscribe, unsubscribe,
+  subscriptions, and live listings.
+- `metrics.py`: isolated Prometheus registry, counters, gauges, and response
+  timing helpers.
+
+The package has a service-layer shape: `OwncastSentry.start()` builds the
+services, commands call `CommandHandler`, command handlers call
+`SubscriptionManager`, scheduled updates call `StreamMonitor`, and
+`StreamMonitor` coordinates repositories, the Owncast client, notifications,
+and metrics.
+
+```mermaid
+flowchart LR
+    Maubot["Maubot loads OwncastSentry"] --> Start["OwncastSentry.start()"]
+    Start --> Repos["StreamRepository and SubscriptionRepository"]
+    Start --> Owncast["OwncastClient"]
+    Start --> Metrics["MetricsService"]
+    Start --> Notify["NotificationService"]
+    Start --> Monitor["StreamMonitor"]
+    Start --> Manager["SubscriptionManager"]
+    Start --> Commands["CommandHandler"]
+    Commands --> Manager
+    Manager --> Repos
+    Manager --> Owncast
+    Monitor --> Repos
+    Monitor --> Owncast
+    Monitor --> Notify
+    Monitor --> Metrics
+    Notify --> Repos
+    Notify --> Matrix["Matrix client"]
+```
+
+## Core Concepts
+
+A few terms are used throughout the package:
+
+- A stream is a normalized Owncast domain tracked by the plugin. The database
+  stores one stream row per domain, even if multiple Matrix rooms subscribe to
+  it.
+- A subscription is a Matrix room's request to receive notifications for one
+  stream domain.
+- `StreamStateObservation` is one successful Owncast status API sample. The
+  monitor decides whether the observation starts a new persisted status period.
+- `StreamConfigObservation` is metadata fetched from Owncast's config API,
+  currently the instance name and tags used in notifications and periodic
+  display-name refreshes.
+- `StreamState` is an immutable snapshot of the latest persisted state for a
+  stream: display metadata, the latest Owncast online flag, when that status was
+  first observed by the bot, failure count, and the derived online, offline, or
+  unknown status.
+
+Durable state lives in the database. The `streams` table stores the latest
+known display and state fields for each Owncast domain, and the `subscriptions`
+table stores which Matrix rooms follow each domain.
+
+Subscriptions are room-scoped, while stream state is shared per domain.
+Notification delivery fans out from one stored stream state to the rooms
+currently subscribed to that domain.
+
+Stream identity is the normalized bare domain. Repositories, metrics,
+notification state, and Owncast API calls all use that domain rather than the
+original user-supplied URL.
+
+Failures stay isolated at plugin boundaries. A bad command, failed stream
+check, or room delivery is logged and counted without stopping unrelated
+commands, stream updates, or notifications.
+
+`StreamStateObservation`, `StreamConfigObservation`, `StreamState`,
+`UpdateResult`, and `RoomSubscription` are immutable snapshots. State changes
+are represented by new values that are persisted through repositories instead of
+mutating existing objects.
+
+## Service Wiring
+
+`OwncastSentry.start()` is the composition root for one plugin instance. It
+loads config, creates the metrics service, Owncast API client, repositories,
+notification service, stream monitor, subscription manager, and command handler,
+then passes dependencies into each service explicitly.
+
+This keeps lower-level modules independent of Maubot globals. Commands do not
+construct repositories, `StreamMonitor` does not know about the Maubot
+scheduler, and notification delivery does not fetch its own subscription state
+from the plugin instance.
+
+The plugin boundary owns scheduling. The minute loop loads subscribed domains
+from `SubscriptionRepository` and calls `StreamMonitor.update_all_streams()`.
+The same pattern applies to new background work: schedule it from the plugin
+boundary, keep the worker service callable directly, and close owned external
+resources from `OwncastSentry.stop()`.
+
+## Subscription Management
+
+`SubscriptionManager` coordinates the room-to-domain relationship. Command
+handlers pass it user-supplied stream targets, and it turns those targets into
+normalized domains before touching repository state.
+
+Subscribing a room creates a subscription for the normalized domain and creates
+the shared stream row when the domain is first seen. First-time domains are
+validated through `OwncastClient`; domains that already have subscribers reuse
+the existing stream record instead of revalidating.
+
+Unsubscribing removes one room's subscription to a domain. It does not delete
+the shared stream row or make remote Owncast requests. Long-term dead stream
+cleanup is owned by `StreamMonitor`.
+
+Listing methods stay room-scoped. They return the subscriptions relevant to one
+Matrix room, with the shared stream state attached for display.
+
+## Owncast API Client
+
+`OwncastClient` owns the aiohttp session used for Owncast API requests. It
+fetches stream status and instance config, validates response shape, and turns
+accepted responses into the value objects used by the rest of the package.
+
+The session uses a plugin-specific User-Agent, a dummy cookie jar, no DNS cache,
+a global connection limit, a per-host connection limit of one, and connect/read
+socket timeouts. aiohttp's own DNS cache is disabled so DNS caching and policy
+stay with the resolver configured for the deployment.
+
+The per-host connection limit and keepalive settings are intentional. Each
+Owncast instance gets at most one reusable connection, so minute-by-minute
+status checks can reuse the existing TLS session instead of opening a fresh
+connection for every poll.
+
+Responses are accepted only when they are HTTP 200 JSON objects under the
+configured size limit. Invalid JSON, non-object JSON, oversized bodies,
+unexpected status codes, malformed API fields, connection errors, and timeouts
+are logged and ignored.
+
+The response-time metric is recorded only when a request completes and the
+parsed response shape is valid. Failed requests remove any stale timing label
+for that domain.
+
+## Stream Monitoring
+
+`StreamMonitor` owns the core per-domain state machine. `update_stream()`
+compares the stored stream state with the latest Owncast status response,
+decides whether to send a notification, updates persistent state when needed,
+and records stream metrics. Each poll first handles missing rows, polling
+backoff, and failed Owncast requests. Only a valid status response enters the
+stream transition policy. `update_all_streams()` wraps this flow for many
+domains, isolates per-domain exceptions, and records subscription-count metrics.
+
+```mermaid
+flowchart TD
+    Start["update_stream(domain)"] --> Old["load stored StreamState"]
+    Old --> Missing{"row exists?"}
+    Missing -->|no| Noop["return success"]
+    Missing -->|yes| Backoff{"backoff allows poll?"}
+    Backoff -->|no| Skip["skip HTTP call<br/>increment failure counter"]
+    Skip --> CleanupSkip["run warning/deletion cleanup checks"]
+    CleanupSkip --> MetricsSkip["if row remains, update<br/>status and failure metrics"]
+    MetricsSkip --> SuccessSkip["return success"]
+    Backoff -->|yes| Fetch["fetch and validate /api/status"]
+    Fetch --> Fetched{"got valid state?"}
+    Fetched -->|no| Failure["increment failure counter"]
+    Failure --> CleanupFail["run warning/deletion cleanup checks"]
+    CleanupFail --> MetricsFail["if row remains, update<br/>status and failure metrics"]
+    MetricsFail --> Failed["return failure"]
+    Fetched -->|yes| Reset["reset failure counter and metric"]
+    Reset --> Timer["ensure offline timer<br/>cache entry exists"]
+    Timer --> Transition["classify stream transition"]
+    Transition --> First{"first observation?"}
+    First -->|yes| FirstLog["log suppressed notification"]
+    First -->|no| LiveCheck{"went live?"}
+    FirstLog --> ConfigDecision
+    LiveCheck -->|yes| Brief{"observed offline less than<br/>temporary cooldown?"}
+    LiveCheck -->|no| TitleChanged{"title changed<br/>while online?"}
+    Brief -->|no| LiveNotify["go-live notification needed"]
+    Brief -->|yes| BriefTitle{"title changed?"}
+    BriefTitle -->|yes| BriefNotify["title-change notification needed"]
+    BriefTitle -->|no| NoNotify["no notification"]
+    TitleChanged -->|yes| OfflineMarker{"offline marker newer than<br/>last notification?"}
+    TitleChanged -->|no| WentOffline{"went offline?"}
+    WentOffline -->|yes| Offline["record offline timer"]
+    WentOffline -->|no| NoNotify
+    OfflineMarker -->|yes| ResumeNotify["go-live notification needed"]
+    OfflineMarker -->|no| TitleNotify["title-change notification needed"]
+    NoNotify --> ConfigDecision
+    Offline --> ConfigDecision
+    LiveNotify --> ConfigDecision
+    BriefNotify --> ConfigDecision
+    ResumeNotify --> ConfigDecision
+    TitleNotify --> ConfigDecision
+    ConfigDecision{"notification, first observation,<br/>or hourly refresh?"}
+    ConfigDecision -->|yes| Config["fetch /api/config"]
+    ConfigDecision -->|no| NotifyGate{"notification needed?"}
+    Config --> NotifyGate
+    NotifyGate -->|yes| Send["attempt live/title notification"]
+    NotifyGate -->|no| Save["save stream row<br/>repository ignores unchanged values"]
+    Send --> Save
+    Save --> FinalMetrics["set current status metric"]
+    FinalMetrics --> Done["return success"]
+```
+
+Failure counters drive both status and polling behavior. A stream is displayed
+as unknown when its failure counter is above `UNKNOWN_STATUS_THRESHOLD`.
+Counters 0 through 4 poll every minute; later tiers poll only on selected
+counter values and eventually only every fifteenth minute. Skipped cycles still
+increment the counter so cleanup can progress.
+
+Transition decisions use Owncast's `online` field. The stream status timestamp is
+the bot's local UTC observation time for the first successful poll, a missing
+timestamp repair, or an online/offline transition. Owncast's remote connect,
+disconnect, and server timestamps are not required for status parsing.
+
+First observation is special. If a new stream row has no status timestamp, the
+first successful update fetches config and stores state but suppresses
+notification attempts, even if the stream is already live.
+
+Go-live notification attempts happen when a stream moves from offline to online
+and the monitor's in-memory offline timer shows it was not merely a brief
+outage. A stream that returns within the temporary offline cooldown only attempts
+a notification when the title changed, and then it uses a title change
+notification.
+
+Mid-session title changes attempt title change notifications. If the monitor has
+an offline marker that is newer than the last notification, it attempts a normal
+live notification instead so rooms do not see a title change for what is
+effectively a new session.
+
+Offline transitions do not notify rooms. They update the database and record a
+monotonic offline timestamp used by later live/title notification policy.
+
+The live/title notification send step is an attempt, not a guaranteed Matrix message.
+`NotificationService` still applies the shared live/title cooldown and records
+the cooldown only when at least one room receives the message.
+
+`/api/config` is fetched when the monitor is about to attempt a live or
+title-change notification, on a stream's first successful observation, and
+during the hourly refresh window for successfully polled streams. The config
+response supplies the display name and tags for notifications. If config is
+fetched successfully during an update, the persisted stream name is refreshed
+from it; otherwise the stored name is left unchanged.
+
+## Cleanup Policy
+
+A domain that remains unreachable is eventually cleaned up. The failure counter
+represents minute ticks, including skipped backoff ticks.
+
+At the 83-day threshold, `StreamMonitor` sends a cleanup warning to all rooms
+subscribed to the domain. At the 90-day threshold or beyond, it sends a deletion
+notice, deletes all subscriptions for the domain, deletes the stream row, clears
+the monitor and notification caches for that domain, and removes per-domain
+metrics.
+
+```mermaid
+flowchart TD
+    Counter["failure counter after failed or skipped check"] --> Warn{"counter == 83 days?"}
+    Warn -->|yes| Warning["send cleanup warning"]
+    Warn -->|no| Delete
+    Warning --> Delete{"counter >= 90 days?"}
+    Delete -->|no| Done["done"]
+    Delete -->|yes| Notice["send cleanup deletion notice"]
+    Notice --> Subs["delete subscriptions"]
+    Subs --> Stream["delete stream row"]
+    Stream --> Caches["clear local caches"]
+    Caches --> Metrics["remove per-domain metrics"]
+    Metrics --> DoneCleanup["done"]
+```
+
+## Notification Delivery
+
+`NotificationService` sends plain text Matrix messages to every room subscribed
+to a domain. Broadcasts run concurrently and use `asyncio.gather(...,
+return_exceptions=True)` so one failed room does not block delivery to other
+rooms.
+
+Live and title-change notifications share a per-domain cooldown. The cooldown
+is recorded only when at least one room receives the message. If there are no
+subscribed rooms, or every delivery fails, no cooldown is recorded.
+
+Notification text is whitespace-normalized before sending. Stream names fall
+back to the domain when config lookup fails or the instance name is empty. Tags
+are appended as hash tags after filtering out empty tags and tags that start
+with a dot.
+
+Cleanup warning and deletion notices bypass the live/title cooldown, but still
+record delivery metrics.
+
+## Command Handling
+
+`OwncastSentry` exposes Maubot command decorators in `__init__.py`, but command
+behavior lives in `CommandHandler`. The plugin entry points are thin wrappers
+that catch unexpected exceptions and record command error metrics.
+
+`CommandHandler.subscribe()` and `CommandHandler.unsubscribe()` translate
+domain errors into user-facing Matrix replies. `subscriptions()` and `live()`
+read resolved room subscriptions and render Markdown output with escaped
+untrusted text.
+
+Command listings are room-scoped and ordered by domain through repository
+queries. `subscriptions()` includes online, offline, and unknown streams.
+`live()` includes only rows marked online with a failure count at or below the
+unknown threshold.
+
+## Persistence
+
+The database schema is managed by `repository.py` through Maubot's upgrade
+table.
+
+- Revision 1 creates `streams` and `subscriptions`.
+- Revision 2 fixes `subscriptions.stream_domain` from `INTEGER` to `TEXT`.
+- Revision 3 adds `streams.failure_counter`.
+- Revision 4 replaces separate connect/disconnect timestamps with
+  `streams.online` and `streams.status_since`.
+
+Repositories own SQL access. `StreamRepository.update()` writes display
+and state fields; failure counters use dedicated methods.
+`SubscriptionRepository` raises domain-specific errors for duplicate adds and
+missing removes.
+
+Resolved subscription listings join `subscriptions` to `streams`, which means
+orphaned subscription rows without a stream row are skipped in room display
+queries.
+
+## Metrics
+
+`MetricsService` uses a private `CollectorRegistry` so plugin metrics do not mix
+with process-global Prometheus collectors.
+
+The registered metrics cover:
+
+- notification delivery attempts by type and result;
+- current stream status per domain (`1` online, `0` offline, `-1` unknown);
+- subscription count per domain;
+- consecutive check failures per domain;
+- last successful Owncast API response duration per domain;
+- build/version information;
+- open aiohttp connection count;
+- internal scheduler and command errors.
+
+Known counter label combinations are initialized to zero. This keeps the
+Prometheus output stable before any events have occurred.
+
+## Test Map
+
+Start with these tests when changing package behavior:
+
+- `tests/test_types.py`: immutable value objects, API response shape checks,
+  truncation, stream status derivation, and subscription errors.
+- `tests/test_repository.py`: schema-backed stream and subscription repository
+  behavior.
+- `tests/test_subscription_manager.py`: domain normalization, subscribe and
+  unsubscribe workflows, validation skipping, and room listing delegation.
+- `tests/test_owncast_client.py`: Owncast API request handling, response body
+  limits, validation failures, User-Agent, response timing, and connection
+  counts.
+- `tests/test_stream_monitor.py`: polling backoff, first-update suppression,
+  live/offline/title transitions, cleanup thresholds, exception isolation, and
+  monitor metrics.
+- `tests/test_notification_service.py`: message formatting, sanitization,
+  cooldown behavior, broadcast failure accounting, cleanup notices, and
+  notification metrics.
+- `tests/test_commands.py`: end-to-end Maubot command behavior, Markdown
+  escaping, duration formatting, room-scoped subscription listings, and live
+  listings.
+- `tests/test_metrics.py`: Prometheus counters, gauges, response timer,
+  per-domain label removal, build info, open connections, and isolated registry
+  output.

owncastsentry/__init__.py

@@ -1,19 +1,40 @@
 # Copyright 2026 Logan Fick
 #
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
-from maubot import Plugin, MessageEvent
+"""OwncastSentry maubot plugin."""
+
+import asyncio
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from aiohttp import web
+from maubot import MessageEvent, Plugin  # type: ignore[attr-defined]
 from maubot.handlers import command
-from mautrix.util.async_db import UpgradeTable
+from prometheus_client.exposition import choose_encoder
 
-from .migrations import get_upgrade_table
-from .owncast_client import OwncastClient
-from .database import StreamRepository, SubscriptionRepository
-from .notification_service import NotificationService
-from .stream_monitor import StreamMonitor
 from .commands import CommandHandler
+from .config import Config
+from .metrics import ErrorSource, MetricsService
+from .notification_service import NotificationService
+from .owncast_client import OwncastClient
+from .repository import StreamRepository, SubscriptionRepository, get_upgrade_table
+from .stream_monitor import StreamMonitor
+from .subscription_manager import SubscriptionManager
+
+if TYPE_CHECKING:
+    from mautrix.util.async_db import Database, UpgradeTable
+    from mautrix.util.config import BaseProxyConfig
 
 
 class OwncastSentry(Plugin):
@@ -21,113 +42,152 @@ class OwncastSentry(Plugin):
 
     @classmethod
     def get_db_upgrade_table(cls) -> UpgradeTable | None:
-        """
-        Helper method for telling Maubot about our database migrations.
-
-        :return: An UpgradeTable with our registered migrations.
-        """
+        """Return the database upgrade table for Maubot."""
         return get_upgrade_table()
 
-    async def start(self) -> None:
-        """
-        Method called by Maubot upon startup of the instance.
-        Initializes all services and registers a recurring task every minute to update the state of all subscribed streams.
+    @classmethod
+    def get_config_class(cls) -> type[BaseProxyConfig]:
+        """Return the configuration class for Maubot."""
+        return Config
 
-        :return: Nothing.
+    async def start(self) -> None:
+        """Initialize services and schedule stream state updates.
+
+        Starts a scheduler coroutine that updates subscribed streams at the top
+        of each wall-clock minute.
         """
+        # Load configuration
+        config: Config = self.config  # type: ignore[assignment]
+        config.load_and_update()
+        db: Database = self.database  # type: ignore[assignment]
+
+        # Initialize metrics service and register web endpoint (if enabled)
+        self.metrics_service = MetricsService()
+        self.metrics_service.set_build_info(str(self.loader.meta.version))
+        if config.metrics_enabled and self.webapp is not None:
+            self.webapp.add_route(
+                method="GET", path="/metrics", handler=self._metrics_endpoint
+            )
+
         # Initialize the Owncast API client
-        self.owncast_client = OwncastClient(self.log)
+        self.owncast_client = OwncastClient(
+            self.log, str(self.loader.meta.version), metrics=self.metrics_service
+        )
+        self.metrics_service.register_open_connections_gauge(
+            lambda: self.owncast_client.open_connection_count
+        )
 
         # Initialize repositories
-        self.stream_repo = StreamRepository(self.database)
-        self.subscription_repo = SubscriptionRepository(self.database)
+        self.stream_repo = StreamRepository(db)
+        self.subscription_repo = SubscriptionRepository(db)
 
         # Initialize notification service
         self.notification_service = NotificationService(
-            self.client, self.subscription_repo, self.log
+            self.client,
+            self.subscription_repo,
+            self.log,
+            metrics=self.metrics_service,
         )
 
         # Initialize stream monitor
         self.stream_monitor = StreamMonitor(
             self.owncast_client,
             self.stream_repo,
+            self.subscription_repo,
             self.notification_service,
             self.log,
+            metrics=self.metrics_service,
         )
 
-        # Initialize command handler
-        self.command_handler = CommandHandler(
+        # Initialize subscription manager
+        self.subscription_manager = SubscriptionManager(
             self.owncast_client,
             self.stream_repo,
             self.subscription_repo,
             self.log,
         )
 
-        # Schedule periodic stream state updates every 60 seconds
-        self.sched.run_periodically(60, self._update_all_stream_states)
+        # Initialize command handler
+        self.command_handler = CommandHandler(
+            self.subscription_manager,
+        )
 
-    async def _update_all_stream_states(self) -> None:
-        """
-        Wrapper method for updating all stream states.
-        Fetches list of subscribed domains and delegates to StreamMonitor.
+        # Schedule stream state updates at the top of each wall-clock minute.
+        self.sched.run_later(0, self._run_stream_updates_every_minute())
 
-        :return: Nothing.
-        """
-        # Get list of all stream domains with active subscriptions
-        subscribed_domains = await self.subscription_repo.get_all_subscribed_domains()
-
-        # Delegate to stream monitor
-        await self.stream_monitor.update_all_streams(subscribed_domains)
+    async def stop(self) -> None:
+        """Clean up resources by closing the HTTP session."""
+        await self.owncast_client.close()
 
     @command.new(help="Subscribes to a new Owncast stream.")
     @command.argument("url")
     async def subscribe(self, evt: MessageEvent, url: str) -> None:
-        """
-        Command handler that delegates to CommandHandler.
-
-        :param evt: MessageEvent of the message calling the command.
-        :param url: A string containing the user supplied URL to a stream to try and subscribe to.
-        :return: Nothing.
-        """
+        """Delegate subscribe command to CommandHandler."""
+        try:
             await self.command_handler.subscribe(evt, url)
+        except Exception:
+            self.metrics_service.record_error(ErrorSource.COMMAND)
+            self.log.exception("Unhandled exception in subscribe command.")
+            await evt.reply("An unexpected error occurred. Please try again later.")
 
     @command.new(help="Unsubscribes from an Owncast stream.")
     @command.argument("url")
     async def unsubscribe(self, evt: MessageEvent, url: str) -> None:
-        """
-        Command handler that delegates to CommandHandler.
-
-        :param evt: MessageEvent of the message calling the command.
-        :param url: A string containing the user supplied URL to a stream to try and unsubscribe from.
-        :return: Nothing.
-        """
+        """Delegate unsubscribe command to CommandHandler."""
+        try:
             await self.command_handler.unsubscribe(evt, url)
+        except Exception:
+            self.metrics_service.record_error(ErrorSource.COMMAND)
+            self.log.exception("Unhandled exception in unsubscribe command.")
+            await evt.reply("An unexpected error occurred. Please try again later.")
 
     @command.new(help="Lists all stream subscriptions in this room.")
     async def subscriptions(self, evt: MessageEvent) -> None:
-        """
-        Command handler that delegates to CommandHandler.
-
-        :param evt: MessageEvent of the message calling the command.
-        :return: Nothing.
-        """
+        """Delegate subscriptions command to CommandHandler."""
+        try:
             await self.command_handler.subscriptions(evt)
+        except Exception:
+            self.metrics_service.record_error(ErrorSource.COMMAND)
+            self.log.exception("Unhandled exception in subscriptions command.")
+            await evt.reply("An unexpected error occurred. Please try again later.")
 
     @command.new(help="Lists currently live streams in this room.")
     async def live(self, evt: MessageEvent) -> None:
-        """
-        Command handler that delegates to CommandHandler.
-
-        :param evt: MessageEvent of the message calling the command.
-        :return: Nothing.
-        """
+        """Delegate live command to CommandHandler."""
+        try:
             await self.command_handler.live(evt)
+        except Exception:
+            self.metrics_service.record_error(ErrorSource.COMMAND)
+            self.log.exception("Unhandled exception in live command.")
+            await evt.reply("An unexpected error occurred. Please try again later.")
 
-    async def stop(self) -> None:
-        """
-        Method called by Maubot upon shutdown of the instance.
-        Closes the HTTP session.
+    async def _run_stream_updates_every_minute(self) -> None:
+        """Run stream state updates at the top of each wall-clock minute."""
+        while True:
+            current_time = datetime.now(UTC)
+            delay = 60 - current_time.second - (current_time.microsecond / 1_000_000)
+            await asyncio.sleep(delay)
+            await self._update_all_stream_states()
 
-        :return: Nothing.
-        """
-        await self.owncast_client.close()
+    async def _update_all_stream_states(self) -> None:
+        """Update stream states for domains with active subscriptions."""
+        try:
+            # Get list of all stream domains with active subscriptions
+            subscribed_domains = (
+                await self.subscription_repo.get_all_subscribed_domains()
+            )
+
+            # Delegate to stream monitor
+            await self.stream_monitor.update_all_streams(subscribed_domains)
+        except Exception:
+            self.metrics_service.record_error(ErrorSource.SCHEDULER_LOOP)
+            self.log.exception("Unhandled exception in scheduler loop.")
+
+    async def _metrics_endpoint(self, request: web.Request) -> web.Response:
+        """Serve Prometheus metrics."""
+        accept = request.headers.get("Accept", "")
+        encoder, content_type = choose_encoder(accept)
+        output = encoder(self.metrics_service.registry)
+        response = web.Response(body=output)
+        response.headers["Content-Type"] = content_type
+        return response

owncastsentry/commands.py

@@ -1,299 +1,270 @@
 # Copyright 2026 Logan Fick
 #
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
 
-import sqlite3
-from datetime import datetime, timezone
-from maubot import MessageEvent
-from mautrix.types import TextMessageEventContent, MessageType
+"""Command handlers for OwncastSentry bot commands."""
 
-from .owncast_client import OwncastClient
-from .database import StreamRepository, SubscriptionRepository
-from .models import StreamStatus
-from .utils import domainify, sanitize_for_markdown
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
 
-
-class CommandHandler:
-    """Handles bot commands for subscribing to streams."""
-
-    def __init__(
-        self,
-        owncast_client: OwncastClient,
-        stream_repo: StreamRepository,
-        subscription_repo: SubscriptionRepository,
-        logger,
-    ):
-        """
-        Initialize the command handler.
-
-        :param owncast_client: Client for making API calls to Owncast instances
-        :param stream_repo: Repository for stream data
-        :param subscription_repo: Repository for subscription data
-        :param logger: Logger instance
-        """
-        self.owncast_client = owncast_client
-        self.stream_repo = stream_repo
-        self.subscription_repo = subscription_repo
-        self.log = logger
-
-    async def subscribe(self, evt: MessageEvent, url: str) -> None:
-        """
-        "!subscribe" command handler for users to subscribe a room to a given stream's notifications.
-
-        :param evt: MessageEvent of the message calling the command.
-        :param url: A string containing the user supplied URL to a stream to try and subscribe to.
-        :return: Nothing.
-        """
-        # Convert the user input to only a domain
-        stream_domain = domainify(url)
-
-        # How many subscriptions already exist for this domain?
-        subscription_count = await self.subscription_repo.count_by_domain(stream_domain)
-
-        if subscription_count == 0:
-            # There are 0 subscriptions, we need to validate this domain is an Owncast stream.
-            is_valid = await self.owncast_client.validate_instance(stream_domain)
-            if not is_valid:
-                # The stream state fetch returned nothing. Probably not an Owncast stream.
-                await evt.reply(
-                    "The URL you supplied does not appear to be a valid Owncast instance. You may have specified an invalid domain, or the instance is offline."
+from .types import (
+    AlreadySubscribedError,
+    InvalidOwncastInstanceError,
+    NotSubscribedError,
+    StreamStatus,
 )
-                return
 
-        # Try to add a new subscription for the requested stream domain in the room the command was executed in
+if TYPE_CHECKING:
+    from maubot import MessageEvent  # type: ignore[attr-defined]
+
+    from .subscription_manager import SubscriptionManager
+
+
+_MARKDOWN_ESCAPE_TABLE = str.maketrans({c: f"\\{c}" for c in r"\*_[]()~`#+-=|{}.!<>&"})
+_SECONDS_PER_MINUTE = 60
+_SECONDS_PER_HOUR = 60 * _SECONDS_PER_MINUTE
+_SECONDS_PER_DAY = 24 * _SECONDS_PER_HOUR
+
+
+def _sanitize_for_plain_text(text: str) -> str:
+    """Sanitize text before Markdown escaping."""
+    if not text:
+        return text
+
+    sanitized = text.replace("\n", " ").replace("\r", " ")
+    return " ".join(sanitized.split())
+
+
+def _escape_markdown(text: str) -> str:
+    """Escape Markdown special characters in untrusted text."""
+    if not text:
+        return text
+
+    return text.translate(_MARKDOWN_ESCAPE_TABLE)
+
+
+def _sanitize_for_markdown(text: str) -> str:
+    """Sanitize text for safe Markdown rendering."""
+    if not text:
+        return text
+
+    return _escape_markdown(_sanitize_for_plain_text(text))
+
+
+def _format_duration(timestamp_str: str, now: datetime) -> str:
+    """Calculate and format the duration from a timestamp to now."""
     try:
-            await self.subscription_repo.add(stream_domain, evt.room_id)
-        except sqlite3.IntegrityError as exception:
-            # Something weird happened... Was it due to attempting to insert a duplicate row?
-            if "UNIQUE constraint failed" in exception.args[0]:
-                # Yes, this is an expected condition. Tell the user the room is already subscribed and give up.
-                await evt.reply(
-                    "This room is already subscribed to notifications for "
-                    + stream_domain
-                    + "."
-                )
-                return
-            else:
-                # Nope... Something unexpected happened. Give up.
-                self.log.error(
-                    f"[{stream_domain}] An error occurred while attempting to add subscription in room {evt.room_id}: {exception}"
-                )
-                raise exception
-
-        # The subscription was successfully added! Try to add a placeholder row for the stream's state in the streams table.
-        try:
-            await self.stream_repo.create(stream_domain)
-            # The insert was successful, so this is the first time we're seeing this stream. Log it.
-            self.log.info(f"[{stream_domain}] Discovered new stream!")
-        except sqlite3.IntegrityError as exception:
-            # Attempts to add rows for streams already known is an expected condition. What is anything except that?
-            if "UNIQUE constraint failed" not in exception.args[0]:
-                # Something unexpected happened. Give up.
-                self.log.error(
-                    f"[{stream_domain}] An error occurred while attempting to add stream information after adding subscription: {exception}"
-                )
-                raise exception
-
-        # All went well! We added a new subscription and (at least tried) to add a row for the stream state. Tell the user.
-        self.log.info(f"[{stream_domain}] Subscription added for room {evt.room_id}.")
-        await evt.reply(
-            "Subscription added! This room will receive notifications when "
-            + stream_domain
-            + " goes live."
-        )
-
-    async def unsubscribe(self, evt: MessageEvent, url: str) -> None:
-        """
-        "!unsubscribe" command handler for users to unsubscribe a room from a given stream's notifications.
-
-        :param evt: MessageEvent of the message calling the command.
-        :param url: A string containing the user supplied URL to a stream to try and unsubscribe from.
-        :return: Nothing.
-        """
-        # Convert the user input to only a domain
-        stream_domain = domainify(url)
-
-        # Attempt to delete the requested subscription from the database
-        result = await self.subscription_repo.remove(stream_domain, evt.room_id)
-
-        # Did it work?
-        if result == 1:
-            # Yes, one row was deleted. Tell the user.
-            self.log.info(
-                f"[{stream_domain}] Subscription removed for room {evt.room_id}."
-            )
-            await evt.reply(
-                "Subscription removed! This room will no longer receive notifications for "
-                + stream_domain
-                + "."
-            )
-        elif result == 0:
-            # No, nothing changed. Tell the user.
-            await evt.reply(
-                "This room is already not subscribed to notifications for "
-                + stream_domain
-                + "."
-            )
-        else:
-            # Somehow more than 1 (or even less than 0 ???) rows were changed... Log it!
-            self.log.error(
-                "Encountered strange situation! Expected 0 or 1 rows on DELETE query for removing subscription; got "
-                + str(result)
-                + " instead. Something very bad may have happened!!!!"
-            )
-
-    def _format_duration(self, timestamp_str: str) -> str:
-        """
-        Calculate and format the duration from a timestamp to now.
-
-        :param timestamp_str: ISO 8601 timestamp string
-        :return: Formatted duration string (e.g., "1 hour", "2 days")
-        """
-        try:
-            timestamp = datetime.fromisoformat(timestamp_str.replace("Z", "+00:00"))
-            now = datetime.now(timezone.utc)
+        timestamp = datetime.fromisoformat(timestamp_str)
         delta = now - timestamp
 
         seconds = int(delta.total_seconds())
-            if seconds < 60:
-                return f"{seconds} second{'s' if seconds != 1 else ''}"
-            elif seconds < 3600:
-                minutes = seconds // 60
-                return f"{minutes} minute{'s' if minutes != 1 else ''}"
-            elif seconds < 86400:
-                hours = seconds // 3600
-                return f"{hours} hour{'s' if hours != 1 else ''}"
-            else:
-                days = seconds // 86400
-                return f"{days} day{'s' if days != 1 else ''}"
-        except Exception:
+        if seconds < 0:
             return "unknown duration"
+        if seconds < _SECONDS_PER_MINUTE:
+            return f"{seconds} second{'s' if seconds != 1 else ''}"
+        if seconds < _SECONDS_PER_HOUR:
+            minutes = seconds // _SECONDS_PER_MINUTE
+            return f"{minutes} minute{'s' if minutes != 1 else ''}"
+        if seconds < _SECONDS_PER_DAY:
+            hours = seconds // _SECONDS_PER_HOUR
+            return f"{hours} hour{'s' if hours != 1 else ''}"
+    except TypeError, ValueError:
+        return "unknown duration"
+    else:
+        days = seconds // _SECONDS_PER_DAY
+        return f"{days} day{'s' if days != 1 else ''}"
 
-    async def subscriptions(self, evt: MessageEvent) -> None:
+
+class CommandHandler:
+    """Handles bot commands for managing stream subscriptions."""
+
+    def __init__(
+        self,
+        subscription_manager: SubscriptionManager,
+    ) -> None:
+        """Initialize the command handler.
+
+        :param subscription_manager: Subscription domain workflow coordinator.
         """
-        "!subscriptions" command handler for listing all stream subscriptions in the current room.
+        self.subscription_manager = subscription_manager
+
+    async def subscribe(self, evt: MessageEvent, url: str) -> None:
+        """Subscribe a room to a stream's notifications.
 
         :param evt: MessageEvent of the message calling the command.
-        :return: Nothing.
+        :param url: User-supplied Owncast URL, domain, or Fediverse-style address.
         """
-        # Get all stream domains this room is subscribed to
-        subscribed_domains = await self.subscription_repo.get_subscribed_streams_for_room(
+        try:
+            stream_domain = await self.subscription_manager.subscribe(evt.room_id, url)
+        except InvalidOwncastInstanceError:
+            await evt.reply(
+                "The URL you supplied does not appear to "
+                "be a valid Owncast instance. You may have "
+                "specified an invalid domain, or the "
+                "instance is offline."
+            )
+            return
+        except AlreadySubscribedError as e:
+            await evt.reply(
+                f"This room is already subscribed to notifications for {e.domain}."
+            )
+            return
+
+        await evt.reply(
+            f"Subscription added! This room will receive "
+            f"notifications when {stream_domain} goes live."
+        )
+
+    async def unsubscribe(self, evt: MessageEvent, url: str) -> None:
+        """Unsubscribe a room from a stream's notifications.
+
+        :param evt: MessageEvent of the message calling the command.
+        :param url: User-supplied Owncast URL, domain, or Fediverse-style address.
+        """
+        try:
+            stream_domain = await self.subscription_manager.unsubscribe(
+                evt.room_id, url
+            )
+        except NotSubscribedError as e:
+            await evt.reply(
+                f"This room is already not subscribed to notifications for {e.domain}."
+            )
+            return
+
+        await evt.reply(
+            f"Subscription removed! This room will no "
+            f"longer receive notifications for {stream_domain}."
+        )
+
+    async def subscriptions(self, evt: MessageEvent) -> None:
+        """List all stream subscriptions in the current room.
+
+        :param evt: MessageEvent of the message calling the command.
+        """
+        subscriptions = await self.subscription_manager.list_room_subscriptions(
             evt.room_id
         )
 
-        # Check if there are no subscriptions
-        if not subscribed_domains:
-            await evt.reply("This room is not subscribed to any Owncast instances.\n\nTo subscribe to an Owncast instance, use `!subscribe <domain>`", markdown=True)
+        if not subscriptions:
+            await evt.reply(
+                "This room is not subscribed to any Owncast "
+                "instances.\n\nTo subscribe to an Owncast "
+                "instance, use `!subscribe <domain>`",
+                markdown=True,
+            )
             return
 
         # Build the response message body as Markdown
-        body_text = f"**Subscriptions for this room ({len(subscribed_domains)}):**\n\n"
+        count = len(subscriptions)
+        parts = [f"**Subscriptions for this room ({count}):**\n\n"]
+        now = datetime.now(UTC)
 
-        for domain in subscribed_domains:
-            # Get the stream state from the database
-            stream_state = await self.stream_repo.get_by_domain(domain)
-
-            if stream_state is None:
-                # Stream exists in subscriptions but not in streams table (shouldn't happen)
-                body_text += f"- **{domain}**  \n"
-                body_text += f"  - Status: Unknown  \n"
-                body_text += f"  - Link: https://{domain}\n\n"
-                continue
-
-            # Determine stream name (use domain as fallback)
-            stream_name = stream_state.name if stream_state.name else domain
-            safe_stream_name = sanitize_for_markdown(stream_name)
+        for subscription in subscriptions:
+            domain = subscription.domain
+            stream_state = subscription.stream_state
+            stream_name = stream_state.name or domain
+            safe_stream_name = _sanitize_for_markdown(stream_name)
 
             # Start building this stream's entry with stream name as main bullet
-            body_text += f"- **{safe_stream_name}**  \n"
+            parts.append(f"- **{safe_stream_name}**  \n")
 
             # Add title if stream is online (as a sub-bullet)
             if stream_state.status == StreamStatus.ONLINE and stream_state.title:
-                safe_title = sanitize_for_markdown(stream_state.title)
-                body_text += f"  - Title: {safe_title}  \n"
+                safe_title = _sanitize_for_markdown(stream_state.title)
+                parts.append(f"  - Title: {safe_title}  \n")
 
             # Determine status and duration (as a sub-bullet)
-            if stream_state.status == StreamStatus.ONLINE:
-                # Stream is online - use last_connect_time
-                if stream_state.last_connect_time:
-                    duration = self._format_duration(stream_state.last_connect_time)
-                    body_text += f"  - Status: Online for {duration}  \n"
-                else:
-                    body_text += f"  - Status: Online  \n"
-            elif stream_state.status == StreamStatus.UNKNOWN:
-                # Stream status is unknown - instance unreachable
-                body_text += f"  - Status: Unknown (instance unreachable)  \n"
-            else:
-                # Stream is offline - use last_disconnect_time
-                if stream_state.last_disconnect_time:
-                    duration = self._format_duration(stream_state.last_disconnect_time)
-                    body_text += f"  - Status: Offline for {duration}  \n"
-                else:
-                    body_text += f"  - Status: Offline  \n"
+            match stream_state.status:
+                case StreamStatus.ONLINE if stream_state.status_since:
+                    duration = _format_duration(stream_state.status_since, now)
+                    parts.append(f"  - Status: Online for {duration}  \n")
+                case StreamStatus.ONLINE:
+                    parts.append("  - Status: Online  \n")
+                case StreamStatus.UNKNOWN:
+                    parts.append("  - Status: Unknown (instance unreachable)  \n")
+                case StreamStatus.OFFLINE if stream_state.status_since:
+                    duration = _format_duration(stream_state.status_since, now)
+                    parts.append(f"  - Status: Offline for {duration}  \n")
+                case StreamStatus.OFFLINE:
+                    parts.append("  - Status: Offline  \n")
 
             # Add stream link (as a sub-bullet)
-            body_text += f"  - Link: https://{domain}\n\n"
+            parts.append(f"  - Link: https://{domain}\n\n")
 
         # Add help text for unsubscribing
-        body_text += "\nTo unsubscribe from any of these Owncast instances, use `!unsubscribe <domain>`"
+        parts.append(
+            "\nTo unsubscribe from any of these Owncast "
+            "instances, use `!unsubscribe <domain>`"
+        )
 
         # Send the response as Markdown
-        await evt.reply(body_text, markdown=True)
+        await evt.reply("".join(parts), markdown=True)
 
     async def live(self, evt: MessageEvent) -> None:
-        """
-        "!live" command handler for listing only currently live streams in the current room.
+        """List currently live streams in the current room.
 
         :param evt: MessageEvent of the message calling the command.
-        :return: Nothing.
         """
-        # Get all stream domains this room is subscribed to
-        subscribed_domains = await self.subscription_repo.get_subscribed_streams_for_room(
+        live_streams = await self.subscription_manager.list_live_room_subscriptions(
             evt.room_id
         )
 
-        # Check if there are no subscriptions
-        if not subscribed_domains:
-            await evt.reply("This room is not subscribed to any Owncast instances.\n\nTo subscribe to an Owncast instance, use `!subscribe <domain>`", markdown=True)
+        if not live_streams:
+            if not await self.subscription_manager.has_room_subscriptions(evt.room_id):
+                await evt.reply(
+                    "This room is not subscribed to any Owncast "
+                    "instances.\n\nTo subscribe to an Owncast "
+                    "instance, use `!subscribe <domain>`",
+                    markdown=True,
+                )
                 return
 
-        # Filter for only live streams (exclude unknown status)
-        live_streams = []
-        for domain in subscribed_domains:
-            stream_state = await self.stream_repo.get_by_domain(domain)
-            if stream_state and stream_state.status == StreamStatus.ONLINE:
-                live_streams.append((domain, stream_state))
-
-        # Check if there are no live streams
-        if not live_streams:
-            await evt.reply("No subscribed Owncast instances are currently live.\n\nUse `!subscriptions` to list all subscriptions.", markdown=True)
+            await evt.reply(
+                "No subscribed Owncast instances are currently "
+                "live.\n\nUse `!subscriptions` to list all "
+                "subscriptions.",
+                markdown=True,
+            )
             return
 
         # Build the response message body as Markdown
-        body_text = f"**Live Owncast instances ({len(live_streams)}):**\n\n"
+        count = len(live_streams)
+        parts = [f"**Live Owncast instances ({count}):**\n\n"]
+        now = datetime.now(UTC)
 
-        for domain, stream_state in live_streams:
-            # Determine stream name (use domain as fallback)
-            stream_name = stream_state.name if stream_state.name else domain
-            safe_stream_name = sanitize_for_markdown(stream_name)
+        for subscription in live_streams:
+            domain = subscription.domain
+            stream_state = subscription.stream_state
+            stream_name = stream_state.name or domain
+            safe_stream_name = _sanitize_for_markdown(stream_name)
 
             # Start building this stream's entry with stream name as main bullet
-            body_text += f"- **{safe_stream_name}**  \n"
+            parts.append(f"- **{safe_stream_name}**  \n")
 
-            # Add title (should be present for live streams)
+            # Add title when available
             if stream_state.title:
-                safe_title = sanitize_for_markdown(stream_state.title)
-                body_text += f"  - Title: {safe_title}  \n"
+                safe_title = _sanitize_for_markdown(stream_state.title)
+                parts.append(f"  - Title: {safe_title}  \n")
 
             # Add status with duration
-            if stream_state.last_connect_time:
-                duration = self._format_duration(stream_state.last_connect_time)
-                body_text += f"  - Online for {duration}  \n"
+            if stream_state.status_since:
+                duration = _format_duration(stream_state.status_since, now)
+                parts.append(f"  - Online for {duration}  \n")
+            else:
+                parts.append("  - Online  \n")
 
             # Add stream link
-            body_text += f"  - Link: https://{domain}\n\n"
+            parts.append(f"  - Link: https://{domain}\n\n")
 
         # Send the response as Markdown
-        await evt.reply(body_text.rstrip(), markdown=True)
+        await evt.reply("".join(parts).rstrip(), markdown=True)

owncastsentry/config.py

@@ -0,0 +1,33 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Configuration module for the OwncastSentry plugin."""
+
+from mautrix.util.config import BaseProxyConfig, ConfigUpdateHelper
+
+
+class Config(BaseProxyConfig):
+    """Configuration class for OwncastSentry plugin."""
+
+    def do_update(self, helper: ConfigUpdateHelper) -> None:
+        """Update configuration with user-provided values.
+
+        :param helper: ConfigUpdateHelper for copying values.
+        """
+        helper.copy("metrics_enabled")
+
+    @property
+    def metrics_enabled(self) -> bool:
+        """Return whether the Prometheus metrics endpoint is enabled."""
+        return self["metrics_enabled"]  # type: ignore[no-any-return]

owncastsentry/database.py

@@ -1,209 +0,0 @@
-# Copyright 2026 Logan Fick
-#
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-
-from typing import Optional, List
-from mautrix.util.async_db import Database
-
-from .models import StreamState
-
-
-class StreamRepository:
-    """Repository for managing stream data in the database."""
-
-    def __init__(self, database: Database):
-        """
-        Initialize the stream repository.
-
-        :param database: The maubot database instance
-        """
-        self.db = database
-
-    async def get_by_domain(self, domain: str) -> Optional[StreamState]:
-        """
-        Get a stream's state by domain.
-
-        :param domain: The stream domain
-        :return: StreamState if found, None otherwise
-        """
-        query = "SELECT * FROM streams WHERE domain=$1"
-        async with self.db.acquire() as conn:
-            row = await conn.fetchrow(query, domain)
-            return StreamState.from_db_row(row) if row else None
-
-    async def create(self, domain: str) -> None:
-        """
-        Create a new stream entry in the database.
-
-        :param domain: The stream domain
-        :return: Nothing
-        """
-        query = "INSERT INTO streams (domain) VALUES ($1)"
-        async with self.db.acquire() as conn:
-            await conn.execute(query, domain)
-
-    async def update(self, state: StreamState) -> None:
-        """
-        Update a stream's state in the database.
-
-        :param state: The StreamState to save
-        :return: Nothing
-        """
-        query = """UPDATE streams
-                   SET name=$1, title=$2, last_connect_time=$3, last_disconnect_time=$4
-                   WHERE domain=$5"""
-        async with self.db.acquire() as conn:
-            await conn.execute(
-                query,
-                state.name,
-                state.title,
-                state.last_connect_time,
-                state.last_disconnect_time,
-                state.domain,
-            )
-
-    async def exists(self, domain: str) -> bool:
-        """
-        Check if a stream exists in the database.
-
-        :param domain: The stream domain
-        :return: True if exists, False otherwise
-        """
-        result = await self.get_by_domain(domain)
-        return result is not None
-
-    async def increment_failure_counter(self, domain: str) -> None:
-        """
-        Increment the failure counter for a stream by 1.
-
-        :param domain: The stream domain
-        :return: Nothing
-        """
-        query = """UPDATE streams
-                   SET failure_counter = failure_counter + 1
-                   WHERE domain=$1"""
-        async with self.db.acquire() as conn:
-            await conn.execute(query, domain)
-
-    async def reset_failure_counter(self, domain: str) -> None:
-        """
-        Reset the failure counter for a stream to 0.
-
-        :param domain: The stream domain
-        :return: Nothing
-        """
-        query = """UPDATE streams
-                   SET failure_counter = 0
-                   WHERE domain=$1"""
-        async with self.db.acquire() as conn:
-            await conn.execute(query, domain)
-
-    async def delete(self, domain: str) -> None:
-        """
-        Delete a stream record from the database.
-
-        :param domain: The stream domain
-        :return: Nothing
-        """
-        query = "DELETE FROM streams WHERE domain=$1"
-        async with self.db.acquire() as conn:
-            await conn.execute(query, domain)
-
-
-class SubscriptionRepository:
-    """Repository for managing stream subscriptions in the database."""
-
-    def __init__(self, database: Database):
-        """
-        Initialize the subscription repository.
-
-        :param database: The maubot database instance
-        """
-        self.db = database
-
-    async def add(self, domain: str, room_id: str) -> None:
-        """
-        Add a subscription for a room to a stream.
-
-        :param domain: The stream domain
-        :param room_id: The Matrix room ID
-        :return: Nothing
-        :raises: sqlite3.IntegrityError if subscription already exists
-        """
-        query = "INSERT INTO subscriptions (stream_domain, room_id) VALUES ($1, $2)"
-        async with self.db.acquire() as conn:
-            await conn.execute(query, domain, room_id)
-
-    async def remove(self, domain: str, room_id: str) -> int:
-        """
-        Remove a subscription for a room from a stream.
-
-        :param domain: The stream domain
-        :param room_id: The Matrix room ID
-        :return: Number of rows deleted (0 or 1)
-        """
-        query = "DELETE FROM subscriptions WHERE stream_domain=$1 AND room_id=$2"
-        async with self.db.acquire() as conn:
-            result = await conn.execute(query, domain, room_id)
-            return result.rowcount
-
-    async def get_subscribed_rooms(self, domain: str) -> List[str]:
-        """
-        Get all room IDs subscribed to a stream.
-
-        :param domain: The stream domain
-        :return: List of room IDs
-        """
-        query = "SELECT room_id FROM subscriptions WHERE stream_domain=$1"
-        async with self.db.acquire() as conn:
-            results = await conn.fetch(query, domain)
-            return [row["room_id"] for row in results]
-
-    async def get_subscribed_streams_for_room(self, room_id: str) -> List[str]:
-        """
-        Get all stream domains that a room is subscribed to.
-
-        :param room_id: The Matrix room ID
-        :return: List of stream domains
-        """
-        query = "SELECT stream_domain FROM subscriptions WHERE room_id=$1"
-        async with self.db.acquire() as conn:
-            results = await conn.fetch(query, room_id)
-            return [row["stream_domain"] for row in results]
-
-    async def get_all_subscribed_domains(self) -> List[str]:
-        """
-        Get all unique stream domains that have at least one subscription.
-
-        :return: List of stream domains
-        """
-        query = "SELECT DISTINCT stream_domain FROM subscriptions"
-        async with self.db.acquire() as conn:
-            results = await conn.fetch(query)
-            return [row["stream_domain"] for row in results]
-
-    async def count_by_domain(self, domain: str) -> int:
-        """
-        Count the number of subscriptions for a given stream domain.
-
-        :param domain: The stream domain
-        :return: Number of subscriptions
-        """
-        query = "SELECT COUNT(*) FROM subscriptions WHERE stream_domain=$1"
-        async with self.db.acquire() as conn:
-            result = await conn.fetchrow(query, domain)
-            return result[0]
-
-    async def delete_all_for_domain(self, domain: str) -> int:
-        """
-        Delete all subscriptions for a given stream domain.
-
-        :param domain: The stream domain
-        :return: Number of subscriptions deleted
-        """
-        query = "DELETE FROM subscriptions WHERE stream_domain=$1"
-        async with self.db.acquire() as conn:
-            result = await conn.execute(query, domain)
-            return result.rowcount

owncastsentry/metrics.py

@@ -0,0 +1,236 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Prometheus metrics service for OwncastSentry."""
+
+import time
+from contextlib import contextmanager, suppress
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from prometheus_client import CollectorRegistry, Counter, Gauge, Info
+
+from .types import StreamStatus
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Generator
+
+
+class NotificationType(StrEnum):
+    """Notification type labels for the delivery counter."""
+
+    LIVE = "live"
+    TITLE_CHANGE = "title_change"
+    CLEANUP_WARNING = "cleanup_warning"
+    CLEANUP_DELETION = "cleanup_deletion"
+
+
+class ErrorSource(StrEnum):
+    """Error source labels for the error counter."""
+
+    SCHEDULER_LOOP = "scheduler_loop"
+    COMMAND = "command"
+
+
+# Mapping from StreamStatus enum to numeric gauge values
+_STATUS_VALUES: dict[StreamStatus, float] = {
+    StreamStatus.ONLINE: 1.0,
+    StreamStatus.OFFLINE: 0.0,
+    StreamStatus.UNKNOWN: -1.0,
+}
+
+
+class _ResponseTimer:
+    """Timer that only records an observation when explicitly marked successful."""
+
+    __slots__ = ("_domain", "_gauge", "_should_observe", "_start")
+
+    def __init__(self, gauge: Gauge, domain: str) -> None:
+        self._gauge = gauge
+        self._domain = domain
+        self._start = time.monotonic()
+        self._should_observe = False
+
+    def success(self) -> None:
+        """Mark the request as successful so the duration is recorded."""
+        self._should_observe = True
+
+    def finalize(self) -> None:
+        """Record or discard the timing observation when the block exits."""
+        if self._should_observe:
+            self._gauge.labels(domain=self._domain).set(
+                max(time.monotonic() - self._start, 0)
+            )
+        else:
+            with suppress(KeyError):
+                self._gauge.remove(self._domain)
+
+
+class MetricsService:
+    """Manages Prometheus metrics with an isolated registry."""
+
+    def __init__(self) -> None:
+        """Initialize metrics with a custom collector registry."""
+        self.registry = CollectorRegistry()
+
+        self.notification_delivery_total = Counter(
+            "owncastsentry_notification_delivery_total",
+            "Total notification delivery attempts to individual rooms",
+            ["type", "result"],
+            registry=self.registry,
+        )
+        self.stream_status = Gauge(
+            "owncastsentry_stream_status",
+            "Current stream status (1=online, 0=offline, -1=unknown)",
+            ["domain"],
+            registry=self.registry,
+        )
+        self.stream_subscriptions = Gauge(
+            "owncastsentry_stream_subscriptions",
+            "Number of room subscriptions per stream domain",
+            ["domain"],
+            registry=self.registry,
+        )
+        self.check_failures = Gauge(
+            "owncastsentry_check_failures",
+            "Consecutive check failure count per stream domain",
+            ["domain"],
+            registry=self.registry,
+        )
+        self.api_response_seconds = Gauge(
+            "owncastsentry_api_response_seconds",
+            "Last successful Owncast API query duration in seconds per stream domain",
+            ["domain"],
+            registry=self.registry,
+        )
+        self.build_info = Info(
+            "owncastsentry",
+            "OwncastSentry build information",
+            registry=self.registry,
+        )
+        self.open_connections = Gauge(
+            "owncastsentry_http_connections_open",
+            "Current number of open HTTP connections (idle and active)",
+            registry=self.registry,
+        )
+        self.errors_total = Counter(
+            "owncastsentry_errors_total",
+            "Internal errors by source",
+            ["source"],
+            registry=self.registry,
+        )
+
+        # Initialize known counter label combinations so they start at 0
+        for notification_type in NotificationType:
+            for result in ("success", "failure"):
+                self.notification_delivery_total.labels(
+                    type=notification_type, result=result
+                )
+        for source in ErrorSource:
+            self.errors_total.labels(source=source)
+
+    def record_delivery(
+        self,
+        notification_type: NotificationType,
+        *,
+        successful: int = 0,
+        failed: int = 0,
+    ) -> None:
+        """Record notification delivery results.
+
+        :param notification_type: The type of notification delivered.
+        :param successful: Number of successful room deliveries.
+        :param failed: Number of failed room deliveries.
+        """
+        self.notification_delivery_total.labels(
+            type=notification_type, result="success"
+        ).inc(successful)
+        self.notification_delivery_total.labels(
+            type=notification_type, result="failure"
+        ).inc(failed)
+
+    def set_stream_status(self, domain: str, status: StreamStatus) -> None:
+        """Set the status gauge for a stream domain.
+
+        :param domain: The stream domain.
+        :param status: The current stream status.
+        """
+        self.stream_status.labels(domain=domain).set(_STATUS_VALUES[status])
+
+    def set_check_failures(self, domain: str, count: int) -> None:
+        """Set the consecutive failure count for a stream domain.
+
+        :param domain: The stream domain.
+        :param count: The current failure counter value.
+        """
+        self.check_failures.labels(domain=domain).set(count)
+
+    def set_subscription_count(self, domain: str, count: int) -> None:
+        """Set the subscription count for a stream domain.
+
+        :param domain: The stream domain.
+        :param count: The number of room subscriptions.
+        """
+        self.stream_subscriptions.labels(domain=domain).set(count)
+
+    @contextmanager
+    def response_timer(self, domain: str) -> Generator[_ResponseTimer]:
+        """Return a context manager that times an Owncast API query.
+
+        Call ``timer.success()`` inside the block to record the duration.
+        If ``success()`` is never called, any existing timing label for the
+        domain is removed.
+
+        :param domain: The stream domain being queried.
+        """
+        timer = _ResponseTimer(self.api_response_seconds, domain)
+        try:
+            yield timer
+        finally:
+            timer.finalize()
+
+    def set_build_info(self, version: str) -> None:
+        """Set the build version info metric.
+
+        :param version: The plugin version string.
+        """
+        self.build_info.info({"version": version})
+
+    def register_open_connections_gauge(self, callback: Callable[[], float]) -> None:
+        """Register a gauge that reads open connection count on scrape.
+
+        :param callback: Function returning the current open count.
+        """
+        self.open_connections.set_function(callback)
+
+    def record_error(self, source: ErrorSource) -> None:
+        """Increment the internal error counter.
+
+        :param source: The source of the error.
+        """
+        self.errors_total.labels(source=source).inc()
+
+    def remove_stream(self, domain: str) -> None:
+        """Remove a stream's gauge labels after cleanup deletion.
+
+        :param domain: The stream domain to remove.
+        """
+        with suppress(KeyError):
+            self.stream_status.remove(domain)
+        with suppress(KeyError):
+            self.check_failures.remove(domain)
+        with suppress(KeyError):
+            self.stream_subscriptions.remove(domain)
+        with suppress(KeyError):
+            self.api_response_seconds.remove(domain)

owncastsentry/migrations.py

@@ -1,93 +0,0 @@
-# Copyright 2026 Logan Fick
-#
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-
-from mautrix.util.async_db import UpgradeTable, Connection
-
-upgrade_table = UpgradeTable()
-
-
-@upgrade_table.register(description="Initial revision")
-async def upgrade_v1(conn: Connection) -> None:
-    """
-    Runs migrations to upgrade database schema to verison 1 format.
-    Version 1 is the initial format of the database.
-
-    :param conn: A connection to run the v1 database migration on.
-    :return: Nothing.
-    """
-    await conn.execute(
-        """CREATE TABLE "streams" (
-	        "domain"	TEXT NOT NULL UNIQUE,
-	        "name"	TEXT,
-	        "title"	TEXT,
-	        "last_connect_time"	TEXT,
-	        "last_disconnect_time"	TEXT,
-	        PRIMARY KEY("domain")
-        )"""
-    )
-
-    await conn.execute(
-        """CREATE TABLE "subscriptions" (
-	        "stream_domain"	INTEGER NOT NULL,
-	        "room_id"	TEXT NOT NULL,
-	        UNIQUE("room_id","stream_domain")
-        )"""
-    )
-
-
-@upgrade_table.register(description="Fix stream_domain column type from INTEGER to TEXT")
-async def upgrade_v2(conn: Connection) -> None:
-    """
-    Runs migrations to upgrade database schema to version 2 format.
-    Version 2 fixes the stream_domain column type in subscriptions table from INTEGER to TEXT.
-
-    :param conn: A connection to run the v2 database migration on.
-    :return: Nothing.
-    """
-    # Create new subscriptions table with correct schema
-    await conn.execute(
-        """CREATE TABLE "subscriptions_new" (
-	        "stream_domain"	TEXT NOT NULL,
-	        "room_id"	TEXT NOT NULL,
-	        UNIQUE("room_id","stream_domain")
-        )"""
-    )
-
-    # Copy all existing data from old table to new table
-    await conn.execute(
-        """INSERT INTO subscriptions_new (stream_domain, room_id)
-           SELECT stream_domain, room_id FROM subscriptions"""
-    )
-
-    # Drop the old table
-    await conn.execute("DROP TABLE subscriptions")
-
-    # Rename new table to original name
-    await conn.execute("ALTER TABLE subscriptions_new RENAME TO subscriptions")
-
-
-@upgrade_table.register(description="Add failure_counter column for backoff and auto-cleanup")
-async def upgrade_v3(conn: Connection) -> None:
-    """
-    Runs migrations to upgrade database schema to version 3 format.
-    Version 3 adds the failure_counter column to track connection failures for backoff and auto-cleanup.
-
-    :param conn: A connection to run the v3 database migration on.
-    :return: Nothing.
-    """
-    # Add failure_counter column with default value of 0
-    await conn.execute(
-        """ALTER TABLE streams ADD COLUMN failure_counter INTEGER DEFAULT 0"""
-    )
-
-
-def get_upgrade_table() -> UpgradeTable:
-    """
-    Helper function for retrieving the upgrade table.
-
-    :return: The upgrade table with registered migrations.
-    """
-    return upgrade_table

owncastsentry/models.py

@@ -1,110 +0,0 @@
-# Copyright 2026 Logan Fick
-#
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-
-from dataclasses import dataclass
-from enum import Enum
-from typing import Optional, List
-
-from .utils import (
-    MAX_INSTANCE_TITLE_LENGTH,
-    MAX_STREAM_TITLE_LENGTH,
-    MAX_TAG_LENGTH,
-    UNKNOWN_STATUS_THRESHOLD,
-    truncate,
-)
-
-
-class StreamStatus(Enum):
-    """Represents the status of a stream."""
-
-    ONLINE = "online"
-    OFFLINE = "offline"
-    UNKNOWN = "unknown"
-
-
-@dataclass
-class StreamState:
-    """Represents the state of an Owncast stream."""
-
-    domain: str
-    name: Optional[str] = None
-    title: Optional[str] = None
-    last_connect_time: Optional[str] = None
-    last_disconnect_time: Optional[str] = None
-    failure_counter: int = 0
-
-    @property
-    def status(self) -> StreamStatus:
-        """Returns the stream status considering failure_counter."""
-        if self.failure_counter > UNKNOWN_STATUS_THRESHOLD:
-            return StreamStatus.UNKNOWN
-        elif self.last_connect_time is not None:
-            return StreamStatus.ONLINE
-        else:
-            return StreamStatus.OFFLINE
-
-    @classmethod
-    def from_api_response(cls, response: dict, domain: str) -> "StreamState":
-        """
-        Creates a StreamState from an API response.
-
-        :param response: API response as a dictionary (camelCase keys)
-        :param domain: The stream domain
-        :return: StreamState instance
-        """
-        return cls(
-            domain=domain,
-            title=truncate(response.get("streamTitle", ""), MAX_STREAM_TITLE_LENGTH),
-            last_connect_time=response.get("lastConnectTime"),
-            last_disconnect_time=response.get("lastDisconnectTime"),
-        )
-
-    @classmethod
-    def from_db_row(cls, row: dict) -> "StreamState":
-        """
-        Creates a StreamState from a database row.
-
-        :param row: Database row as a dictionary
-        :return: StreamState instance
-        """
-        return cls(
-            domain=row["domain"],
-            name=row["name"],
-            title=row["title"],
-            last_connect_time=row["last_connect_time"],
-            last_disconnect_time=row["last_disconnect_time"],
-            failure_counter=row["failure_counter"],
-        )
-
-
-@dataclass
-class StreamConfig:
-    """Represents the configuration of an Owncast stream."""
-
-    name: str = ""
-    tags: List[str] = None
-
-    def __post_init__(self):
-        """Initialize default values after dataclass initialization."""
-        if self.tags is None:
-            self.tags = []
-
-    @classmethod
-    def from_api_response(cls, response: dict) -> "StreamConfig":
-        """
-        Creates a StreamConfig from an API response.
-
-        :param response: API response as a dictionary
-        :return: StreamConfig instance
-        """
-        # Truncate instance name to max length
-        name = truncate(response.get("name", ""), MAX_INSTANCE_TITLE_LENGTH)
-
-        # Truncate each tag to max length
-        raw_tags = response.get("tags", [])
-        tags = [truncate(tag, MAX_TAG_LENGTH) for tag in raw_tags]
-
-        return cls(name=name, tags=tags)

owncastsentry/notification_service.py

@@ -1,250 +1,307 @@
 # Copyright 2026 Logan Fick
 #
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Notification service for sending Matrix messages."""
 
-import time
 import asyncio
-from typing import List
+import time
+from typing import TYPE_CHECKING, Any
 
-from mautrix.types import TextMessageEventContent, MessageType
+from mautrix.types import MessageType, TextMessageEventContent
 
-from .database import SubscriptionRepository
-from .utils import SECONDS_BETWEEN_NOTIFICATIONS, sanitize_for_markdown
+from .metrics import NotificationType
+
+if TYPE_CHECKING:
+    import logging
+    from collections.abc import Sequence
+
+    from .metrics import MetricsService
+    from .repository import SubscriptionRepository
+
+
+_SECONDS_BETWEEN_NOTIFICATIONS = 20 * 60
+
+_CLEANUP_WARNING_DAYS = 83
+_CLEANUP_DELETE_DAYS = 90
+
+
+def _sanitize_for_plain_text(text: str) -> str:
+    """Sanitize text for plain text rendering."""
+    if not text:
+        return text
+
+    return " ".join(text.split())
 
 
 class NotificationService:
     """Service for sending Matrix notifications about stream events."""
 
-    def __init__(self, client, subscription_repo: SubscriptionRepository, logger):
-        """
-        Initialize the notification service.
+    def __init__(
+        self,
+        client: Any,
+        subscription_repo: SubscriptionRepository,
+        logger: logging.Logger,
+        metrics: MetricsService,
+    ) -> None:
+        """Initialize the notification service.
 
-        :param client: The Matrix client for sending messages
-        :param subscription_repo: Repository for managing subscriptions
-        :param logger: Logger instance
+        :param client: The Matrix client for sending messages.
+        :param subscription_repo: Repository for managing subscriptions.
+        :param logger: Logger instance for debugging.
+        :param metrics: Metrics service for recording counters.
         """
         self.client = client
         self.subscription_repo = subscription_repo
         self.log = logger
+        self.metrics = metrics
 
         # Cache for tracking when notifications were last sent
-        self.notification_timers_cache = {}
+        self.notification_timers_cache: dict[str, float] = {}
 
     async def notify_stream_live(
         self,
         domain: str,
         name: str,
         title: str,
-        tags: List[str],
+        tags: Sequence[str],
+        *,
         title_change: bool = False,
     ) -> None:
-        """
-        Sends notifications to rooms with subscriptions to the provided stream domain.
+        """Send notifications to rooms subscribed to a stream.
 
-        :param domain: The domain of the stream to send notifications for.
-        :param name: The name of the stream to include in the message.
-        :param title: The title of the stream to include in the message.
+        :param domain: The stream domain to send notifications for.
+        :param name: The stream name to include in the message.
+        :param title: The stream title to include in the message.
         :param tags: List of stream tags to include in the message.
-        :param title_change: Whether or not this is for a stream changing its title rather than going live.
-        :return: Nothing.
+        :param title_change: Whether this is a title change notification.
         """
         # Has enough time passed since the last notification was sent?
         if not self._can_notify(domain):
             seconds_since_last = round(
-                time.time() - self.notification_timers_cache[domain]
+                time.monotonic() - self.notification_timers_cache[domain]
             )
             self.log.info(
-                f"[{domain}] Not sending notifications. Only {seconds_since_last} of required {SECONDS_BETWEEN_NOTIFICATIONS} seconds has passed since last notification."
+                "[%s] Not sending notifications. Only %s of required "
+                "%s seconds have passed since last notification.",
+                domain,
+                seconds_since_last,
+                _SECONDS_BETWEEN_NOTIFICATIONS,
             )
             return
 
-        # Record that we're sending a notification now
-        self._record_notification(domain)
-
-        # Get a list of room IDs with active subscriptions to the stream domain
-        room_ids = await self.subscription_repo.get_subscribed_rooms(domain)
-
         # Build the notification message
-        body_text = self._format_message(name, title, domain, tags, title_change)
-
-        # Set up counters for statistics
-        successful_notifications = 0
-        failed_notifications = 0
+        body_text = self._format_message(
+            name, title, domain, tags, title_change=title_change
+        )
 
         # Send notifications to all subscribed rooms in parallel
-        # IMPROVEMENT: Parallel notification delivery with asyncio.gather (was a TODO in original code)
-        tasks = []
-        for room_id in room_ids:
-            tasks.append(self._send_notification(room_id, body_text, domain))
+        successful, failed = await self._broadcast_to_rooms(domain, body_text)
 
-        results = await asyncio.gather(*tasks, return_exceptions=True)
-
-        # Count successes and failures
-        for result in results:
-            if isinstance(result, Exception):
-                failed_notifications += 1
-            else:
-                successful_notifications += 1
+        # Record that a notification was sent if at least one room received it.
+        if successful > 0:
+            self._record_notification(domain)
 
         # Log completion
         notification_type = "title change" if title_change else "going live"
         self.log.info(
-            f"[{domain}] Completed sending {notification_type} notifications! {successful_notifications} succeeded, {failed_notifications} failed."
+            "[%s] Completed sending %s notifications! %s succeeded, %s failed.",
+            domain,
+            notification_type,
+            successful,
+            failed,
         )
 
+        self.metrics.record_delivery(
+            NotificationType.TITLE_CHANGE if title_change else NotificationType.LIVE,
+            successful=successful,
+            failed=failed,
+        )
+
+    async def send_cleanup_warning(self, domain: str) -> None:
+        """Send cleanup warning notification to all subscribed rooms.
+
+        :param domain: The stream domain.
+        """
+        remaining_days = _CLEANUP_DELETE_DAYS - _CLEANUP_WARNING_DAYS
+        body_text = (
+            "⚠️  Warning: Subscription Cleanup Scheduled\n\n"
+            f"The Owncast instance at {domain} has been "
+            f"unreachable for {_CLEANUP_WARNING_DAYS} days. If it remains "
+            f"unreachable for {remaining_days} more days "
+            f"({_CLEANUP_DELETE_DAYS} days total), this subscription "
+            f"will be automatically removed."
+        )
+
+        successful, failed = await self._broadcast_to_rooms(domain, body_text)
+        self.log.info(
+            "[%s] Sent cleanup warning to %s rooms (%s failed).",
+            domain,
+            successful,
+            failed,
+        )
+
+        self.metrics.record_delivery(
+            NotificationType.CLEANUP_WARNING, successful=successful, failed=failed
+        )
+
+    async def send_cleanup_deletion(self, domain: str) -> None:
+        """Send cleanup deletion notification to all subscribed rooms.
+
+        :param domain: The stream domain.
+        """
+        body_text = (
+            "🗑️  Subscription Automatically Removed\n\n"
+            f"The Owncast instance at {domain} has been "
+            f"unreachable for {_CLEANUP_DELETE_DAYS} days and has been "
+            f"automatically removed from subscriptions in this "
+            f"room.\n\n"
+            f"If the instance comes online again and you want to "
+            f"resubscribe, run `!subscribe {domain}`."
+        )
+
+        successful, failed = await self._broadcast_to_rooms(domain, body_text)
+        self.log.info(
+            "[%s] Sent cleanup deletion notice to %s rooms (%s failed).",
+            domain,
+            successful,
+            failed,
+        )
+
+        self.metrics.record_delivery(
+            NotificationType.CLEANUP_DELETION, successful=successful, failed=failed
+        )
+
+    def get_last_notification_time(self, domain: str) -> float:
+        """Get the cached live/title-change notification timestamp for a domain.
+
+        :param domain: The stream domain.
+        :return: Monotonic timestamp of the last successful live/title-change
+            notification, or 0 if none has been recorded.
+        """
+        return self.notification_timers_cache.get(domain, 0)
+
+    def clear_notification_state(self, domain: str) -> None:
+        """Clear cached notification state for a deleted domain.
+
+        :param domain: The stream domain to remove from local caches.
+        """
+        self.notification_timers_cache.pop(domain, None)
+
     async def _send_notification(
         self, room_id: str, body_text: str, domain: str
     ) -> None:
-        """
-        Send a notification to a single room.
+        """Send a notification to a single room.
 
-        :param room_id: The Matrix room ID to send to
-        :param body_text: The message body text
-        :param domain: The stream domain (for logging)
-        :return: Nothing
-        :raises: Exception if sending fails
+        :param room_id: The Matrix room ID to send to.
+        :param body_text: The message body text.
+        :param domain: The stream domain (for logging).
+        Propagates send errors so broadcast delivery accounting can count failures.
         """
         try:
             content = TextMessageEventContent(msgtype=MessageType.TEXT, body=body_text)
             await self.client.send_message(room_id, content)
         except Exception as exception:
             self.log.warning(
-                f"[{domain}] Failed to send notification message to room [{room_id}]: {exception}"
+                "[%s] Failed to send notification message to room [%s]: %s",
+                domain,
+                room_id,
+                exception,
             )
             raise
 
     def _format_message(
-        self, name: str, title: str, domain: str, tags: List[str], title_change: bool
+        self,
+        name: str,
+        title: str,
+        domain: str,
+        tags: Sequence[str],
+        *,
+        title_change: bool,
     ) -> str:
-        """
-        Format the notification message body.
+        """Format the notification message body.
 
-        :param name: The stream name
-        :param title: The stream title
-        :param domain: The stream domain
-        :param tags: List of stream tags
-        :param title_change: Whether this is a title change notification
-        :return: Formatted message body
+        :param name: The stream name.
+        :param title: The stream title.
+        :param domain: The stream domain.
+        :param tags: List of stream tags.
+        :param title_change: Whether this is a title change notification.
+        :return: Formatted message body.
         """
         # Use name if available, fallback to domain
-        stream_name = name if name else domain
-        safe_stream_name = sanitize_for_markdown(stream_name)
+        stream_name = name or domain
+        safe_stream_name = _sanitize_for_plain_text(stream_name)
 
         # Choose message based on notification type
         if title_change:
-            body_text = "📝 " + safe_stream_name + " has changed its stream title!"
+            parts = [f"📝 {safe_stream_name} has changed its stream title!"]
         else:
-            body_text = "🎥 " + safe_stream_name + " is now live!"
+            parts = [f"🎥 {safe_stream_name} is now live!"]
 
         # Add title if present
-        if title != "":
-            safe_title = sanitize_for_markdown(title)
-            body_text += "\nStream Title: " + safe_title
+        if title:
+            safe_title = _sanitize_for_plain_text(title)
+            parts.append(f"\nStream Title: {safe_title}")
 
         # Add stream URL
-        body_text += "\n\nTo tune in, visit: https://" + domain + "/"
+        parts.append(f"\n\nTo tune in, visit: https://{domain}/")
 
         # Add tags if present
-        if tags and len(tags) > 0:
-            safe_tags = []
-            for tag in tags:
-                safe_tag = sanitize_for_markdown(tag)
-                if safe_tag and not safe_tag.startswith('.'):
-                    safe_tags.append(safe_tag)
+        if tags:
+            tag_text = " ".join(
+                f"#{safe_tag}"
+                for tag in tags
+                if (safe_tag := _sanitize_for_plain_text(tag))
+                and not safe_tag.startswith(".")
+            )
 
-            if safe_tags:
-                body_text += "\n\n"
-                body_text += " ".join("#" + tag for tag in safe_tags)
+            if tag_text:
+                parts.append(f"\n\n{tag_text}")
 
-        return body_text
+        return "".join(parts)
 
     def _can_notify(self, domain: str) -> bool:
-        """
-        Check if enough time has passed to send another notification.
+        """Check if enough time has passed to send another notification.
 
-        :param domain: The stream domain
-        :return: True if notification can be sent, False otherwise
+        :param domain: The stream domain.
+        :return: True if notification can be sent, False otherwise.
         """
-        if domain not in self.notification_timers_cache:
-            return True
-
-        seconds_since_last = round(time.time() - self.notification_timers_cache[domain])
-        return seconds_since_last >= SECONDS_BETWEEN_NOTIFICATIONS
+        last_notification_time = self.notification_timers_cache.get(domain)
+        return (
+            last_notification_time is None
+            or time.monotonic() - last_notification_time
+            >= _SECONDS_BETWEEN_NOTIFICATIONS
+        )
 
     def _record_notification(self, domain: str) -> None:
-        """
-        Record that a notification was sent at the current time.
+        """Record that a notification was sent at the current time.
 
-        :param domain: The stream domain
-        :return: Nothing
+        :param domain: The stream domain.
         """
-        self.notification_timers_cache[domain] = time.time()
+        self.notification_timers_cache[domain] = time.monotonic()
 
-    async def send_cleanup_warning(self, domain: str) -> None:
-        """
-        Send 83-day warning notification to all subscribed rooms.
+    async def _broadcast_to_rooms(self, domain: str, body_text: str) -> tuple[int, int]:
+        """Send a message to all rooms subscribed to a domain.
 
-        :param domain: The stream domain
-        :return: Nothing
+        :param domain: The stream domain.
+        :param body_text: The message body text.
+        :return: Tuple of (successful, failed) counts.
         """
-        # Get all subscribed rooms
         room_ids = await self.subscription_repo.get_subscribed_rooms(domain)
-
-        # Build the warning message
-        body_text = (
-            f"⚠️  Warning: Subscription Cleanup Scheduled\n\n"
-            f"The Owncast instance at {domain} has been unreachable for 83 days. "
-            f"If it remains unreachable for 7 more days (90 days total), this "
-            f"subscription will be automatically removed."
-        )
-
-        # Send to all rooms in parallel
-        tasks = []
-        for room_id in room_ids:
-            tasks.append(self._send_notification(room_id, body_text, domain))
-
+        tasks = [
+            self._send_notification(room_id, body_text, domain) for room_id in room_ids
+        ]
         results = await asyncio.gather(*tasks, return_exceptions=True)
-
-        # Count successes and failures
-        successful = sum(1 for r in results if not isinstance(r, Exception))
-        failed = sum(1 for r in results if isinstance(r, Exception))
-
-        self.log.info(
-            f"[{domain}] Sent cleanup warning to {successful} rooms ({failed} failed)."
-        )
-
-    async def send_cleanup_deletion(self, domain: str) -> None:
-        """
-        Send 90-day deletion notification to all subscribed rooms.
-
-        :param domain: The stream domain
-        :return: Nothing
-        """
-        # Get all subscribed rooms
-        room_ids = await self.subscription_repo.get_subscribed_rooms(domain)
-
-        # Build the deletion message
-        body_text = (
-            f"🗑️  Subscription Automatically Removed\n\n"
-            f"The Owncast instance at {domain} has been unreachable for 90 days "
-            f"and has been automatically removed from subscriptions in this room.\n\n"
-            f"If the instance comes online again and you want to resubscribe, "
-            f"run `!subscribe {domain}`."
-        )
-
-        # Send to all rooms in parallel
-        tasks = []
-        for room_id in room_ids:
-            tasks.append(self._send_notification(room_id, body_text, domain))
-
-        results = await asyncio.gather(*tasks, return_exceptions=True)
-
-        # Count successes and failures
-        successful = sum(1 for r in results if not isinstance(r, Exception))
-        failed = sum(1 for r in results if isinstance(r, Exception))
-
-        self.log.info(
-            f"[{domain}] Sent cleanup deletion notice to {successful} rooms ({failed} failed)."
-        )
+        failed = sum(1 for r in results if isinstance(r, BaseException))
+        successful = len(results) - failed
+        return successful, failed

owncastsentry/owncast_client.py

@@ -1,138 +1,183 @@
 # Copyright 2026 Logan Fick
 #
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""HTTP client for querying Owncast instance APIs."""
+
+import json
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Any
 
 import aiohttp
-import json
-from typing import Optional
 
-from .models import StreamConfig, StreamState
-from .utils import OWNCAST_STATUS_PATH, OWNCAST_CONFIG_PATH, USER_AGENT
+from .types import (
+    InvalidApiResponseError,
+    StreamConfigObservation,
+    StreamStateObservation,
+)
+
+if TYPE_CHECKING:
+    import logging
+
+    from .metrics import MetricsService
+
+
+_OWNCAST_STATUS_PATH = "/api/status"
+_OWNCAST_CONFIG_PATH = "/api/config"
+_MAX_JSON_RESPONSE_BYTES = 1024 * 1024
+_JSON_READ_CHUNK_BYTES = 64 * 1024
+_HTTP_CONNECTION_LIMIT = 1000
+_HTTP_CONNECTION_LIMIT_PER_HOST = 1
+_HTTP_KEEPALIVE_TIMEOUT_SECONDS = 120
+_HTTP_CONNECT_TIMEOUT_SECONDS = 5
+_HTTP_READ_TIMEOUT_SECONDS = 5
+
+
+def _user_agent(version: str) -> str:
+    """Build the User-Agent header string for HTTP requests."""
+    return (
+        f"OwncastSentry/{version}"
+        " (bot; +https://git.logal.dev/LogalDeveloper/OwncastSentry)"
+    )
+
+
+async def _read_limited_response_body(
+    response: aiohttp.ClientResponse,
+) -> bytearray | None:
+    """Read a response body while enforcing the maximum JSON response size."""
+    # Check Content-Length first when the server provides it so clearly
+    # oversized responses can be rejected before buffering any body bytes.
+    if (
+        response.content_length is not None
+        and response.content_length > _MAX_JSON_RESPONSE_BYTES
+    ):
+        return None
+
+    body = bytearray()
+    # Read until EOF instead of using one read(n) call. aiohttp's read(n)
+    # may return a partial body as soon as data is available.
+    async for chunk in response.content.iter_chunked(_JSON_READ_CHUNK_BYTES):
+        body.extend(chunk)
+        if len(body) > _MAX_JSON_RESPONSE_BYTES:
+            return None
+
+    return body
 
 
 class OwncastClient:
     """HTTP client for communicating with Owncast instances."""
 
-    def __init__(self, logger):
-        """
-        Initialize the Owncast client with an HTTP session.
+    def __init__(
+        self,
+        logger: logging.Logger,
+        version: str,
+        metrics: MetricsService,
+    ) -> None:
+        """Initialize the Owncast client with an HTTP session.
 
         :param logger: Logger instance for debugging
+        :param version: Plugin version string for the User-Agent header
+        :param metrics: Metrics service for recording response times.
         """
         self.log = logger
+        self.metrics = metrics
 
         # Set up HTTP session configuration
-        headers = {"User-Agent": USER_AGENT}
+        headers = {"User-Agent": _user_agent(version)}
         cookie_jar = aiohttp.DummyCookieJar()
         connector = aiohttp.TCPConnector(
-            use_dns_cache=False, limit=1000, limit_per_host=1, keepalive_timeout=120
+            use_dns_cache=False,
+            limit=_HTTP_CONNECTION_LIMIT,
+            limit_per_host=_HTTP_CONNECTION_LIMIT_PER_HOST,
+            keepalive_timeout=_HTTP_KEEPALIVE_TIMEOUT_SECONDS,
+        )
+        timeout = aiohttp.ClientTimeout(
+            sock_connect=_HTTP_CONNECT_TIMEOUT_SECONDS,
+            sock_read=_HTTP_READ_TIMEOUT_SECONDS,
         )
-        timeout = aiohttp.ClientTimeout(sock_connect=5, sock_read=5)
 
         self.session = aiohttp.ClientSession(
-            headers=headers, cookie_jar=cookie_jar, timeout=timeout, connector=connector
+            headers=headers,
+            cookie_jar=cookie_jar,
+            timeout=timeout,
+            connector=connector,
         )
 
-    async def get_stream_state(self, domain: str) -> Optional[StreamState]:
-        """
-        Get the current stream state for a given domain.
-        HTTPS on port 443 is assumed, no other protocols or ports are supported.
+    async def get_stream_state(self, domain: str) -> StreamStateObservation | None:
+        """Get the current stream state for a given domain.
+
+        HTTPS on port 443 is assumed, no other protocols or ports
+        are supported.
 
         :param domain: The domain (not URL) where the stream is hosted.
-        :return: A StreamState with stream state if available, None if an error occurred.
+        :return: A StreamStateObservation if available, None on error.
         """
-        self.log.debug(f"[{domain}] Fetching current stream state...")
-        status_url = "https://" + domain + OWNCAST_STATUS_PATH
+        self.log.debug("[%s] Fetching current stream state...", domain)
+        with self.metrics.response_timer(domain) as timer:
+            new_state = await self._fetch_json(domain, _OWNCAST_STATUS_PATH)
+
+            if new_state is None:
+                return None
 
-        # Make a request to the endpoint
             try:
-            response = await self.session.request(
-                "GET", status_url, allow_redirects=False
+                stream_observation = StreamStateObservation.from_api_response(
+                    new_state, domain
                 )
-        except Exception as e:
+            except InvalidApiResponseError as e:
                 self.log.warning(
-                f"[{domain}] Error making GET request to {OWNCAST_STATUS_PATH}: {e}"
+                    "[%s] Rejecting response to request on %s as response "
+                    "shape is invalid: %s",
+                    domain,
+                    _OWNCAST_STATUS_PATH,
+                    e,
                 )
                 return None
 
-        # Check the response code is success
-        if response.status != 200:
-            self.log.warning(
-                f"[{domain}] Response to request on {OWNCAST_STATUS_PATH} was not 200, got {response.status} instead."
-            )
-            return None
+            timer.success()
+            return stream_observation
 
-        # Try and interpret the response as JSON
-        try:
-            new_state = json.loads(await response.read())
-        except Exception as e:
-            self.log.warning(
-                f"[{domain}] Rejecting response to request on {OWNCAST_STATUS_PATH} as could not be interpreted as JSON: {e}"
-            )
-            return None
+    async def get_stream_config(self, domain: str) -> StreamConfigObservation | None:
+        """Get the current stream config for a given domain.
 
-        # Validate the response to ensure it contains all the basic info needed to function
-        required_fields = [
-            "lastConnectTime",
-            "lastDisconnectTime",
-            "streamTitle",
-            "online",
-        ]
-        for field in required_fields:
-            if field not in new_state:
-                self.log.warning(
-                    f"[{domain}] Rejecting response to request on {OWNCAST_STATUS_PATH} as it does not have {field} parameter."
-                )
-                return None
-
-        return StreamState.from_api_response(new_state, domain)
-
-    async def get_stream_config(self, domain: str) -> Optional[StreamConfig]:
-        """
-        Get the current stream config for a given domain.
-        HTTPS on port 443 is assumed, no other protocols or ports are supported.
+        HTTPS on port 443 is assumed, no other protocols or ports
+        are supported.
 
         :param domain: The domain (not URL) where the stream is hosted.
-        :return: A StreamConfig with the stream's configuration, or None if fetch failed.
+        :return: A StreamConfigObservation, or None if fetch failed.
         """
-        self.log.debug(f"[{domain}] Fetching current stream config...")
-        config_url = "https://" + domain + OWNCAST_CONFIG_PATH
+        self.log.debug("[%s] Fetching current stream config...", domain)
+        with self.metrics.response_timer(domain) as timer:
+            config = await self._fetch_json(domain, _OWNCAST_CONFIG_PATH)
+            if config is None:
+                return None
 
-        # Make a request to the endpoint
             try:
-            response = await self.session.request(
-                "GET", config_url, allow_redirects=False
-            )
-        except Exception as e:
+                stream_config = StreamConfigObservation.from_api_response(config)
+            except InvalidApiResponseError as e:
                 self.log.warning(
-                f"[{domain}] Error making GET request to {OWNCAST_CONFIG_PATH}: {e}"
+                    "[%s] Rejecting response to request on %s as response "
+                    "shape is invalid: %s",
+                    domain,
+                    _OWNCAST_CONFIG_PATH,
+                    e,
                 )
                 return None
 
-        # Check the response code is success
-        if response.status != 200:
-            self.log.warning(
-                f"[{domain}] Response to request on {OWNCAST_CONFIG_PATH} was not 200, got {response.status} instead."
-            )
-            return None
-
-        # Try and interpret the response as JSON
-        try:
-            config = json.loads(await response.read())
-        except Exception as e:
-            self.log.warning(
-                f"[{domain}] Rejecting response to request on {OWNCAST_CONFIG_PATH} as could not be interpreted as JSON: {e}"
-            )
-            return None
-
-        # Create StreamConfig with validated fields
-        return StreamConfig.from_api_response(config)
+            timer.success()
+            return stream_config
 
     async def validate_instance(self, domain: str) -> bool:
-        """
-        Validate that a domain is a valid Owncast instance.
+        """Validate that a domain is a valid Owncast instance.
 
         :param domain: The domain to validate
         :return: True if valid Owncast instance, False otherwise
@@ -140,6 +185,73 @@ class OwncastClient:
         state = await self.get_stream_state(domain)
         return state is not None
 
+    @property
+    def open_connection_count(self) -> int:
+        """Return the total number of open HTTP connections."""
+        connector = self.session.connector
+        if connector is None:
+            return 0
+
+        # aiohttp does not expose public live pool counts; this metric intentionally
+        # mirrors its internal idle and active connection pools.
+        idle = sum(len(conns) for conns in connector._conns.values())  # noqa: SLF001
+        active = len(connector._acquired)  # noqa: SLF001
+        return idle + active
+
     async def close(self) -> None:
         """Close the HTTP session."""
         await self.session.close()
+
+    async def _fetch_json(self, domain: str, path: str) -> dict[str, Any] | None:
+        """Fetch and parse JSON from an Owncast API endpoint.
+
+        :param domain: The domain to query.
+        :param path: The API path to request.
+        :return: Parsed JSON response, or None on error.
+        """
+        url = f"https://{domain}{path}"
+        try:
+            async with self.session.get(url, allow_redirects=False) as response:
+                if response.status != HTTPStatus.OK:
+                    self.log.warning(
+                        "[%s] Response to request on %s was not 200, got %s instead.",
+                        domain,
+                        path,
+                        response.status,
+                    )
+                    return None
+                try:
+                    body = await _read_limited_response_body(response)
+                    if body is None:
+                        self.log.warning(
+                            "[%s] Rejecting response to request on %s as it "
+                            "was larger than %s bytes.",
+                            domain,
+                            path,
+                            _MAX_JSON_RESPONSE_BYTES,
+                        )
+                        return None
+
+                    result = json.loads(body)
+                    if not isinstance(result, dict):
+                        self.log.warning(
+                            "[%s] Rejecting response to request on %s as JSON "
+                            "was not an object.",
+                            domain,
+                            path,
+                        )
+                        return None
+                except ValueError as e:
+                    self.log.warning(
+                        "[%s] Rejecting response to request on %s as could not "
+                        "be interpreted as JSON: %s",
+                        domain,
+                        path,
+                        e,
+                    )
+                    return None
+                else:
+                    return result
+        except (aiohttp.ClientError, TimeoutError, OSError) as e:
+            self.log.warning("[%s] Error making GET request to %s: %s", domain, path, e)
+            return None

owncastsentry/repository.py

@@ -0,0 +1,493 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Repository and schema upgrade definitions for OwncastSentry.
+
+Only SQLite is supported as a database backend for now.
+"""
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from mautrix.util.async_db import Connection, UpgradeTable
+
+from .types import (
+    UNKNOWN_STATUS_THRESHOLD,
+    AlreadySubscribedError,
+    NotSubscribedError,
+    RoomSubscription,
+    StreamState,
+    format_status_since,
+)
+
+if TYPE_CHECKING:
+    from mautrix.util.async_db import Database
+
+
+upgrade_table = UpgradeTable()
+
+
+class _Unset:
+    """Sentinel type for omitted partial stream update fields."""
+
+    __slots__ = ()
+
+
+_UNSET = _Unset()
+
+
+def _normalize_legacy_status_since(value: Any) -> str | None:
+    """Normalize a legacy timestamp value to the canonical UTC format."""
+    if value is None:
+        return None
+    if isinstance(value, datetime):
+        parsed = value
+    elif isinstance(value, str):
+        value = value.strip()
+        if not value:
+            return None
+        try:
+            parsed = datetime.fromisoformat(value)
+        except ValueError:
+            return None
+    else:
+        return None
+
+    if parsed.tzinfo is None:
+        return None
+    return format_status_since(parsed.astimezone(UTC))
+
+
+@upgrade_table.register(  # type: ignore[arg-type, call-arg, untyped-decorator]
+    description="Initial revision"
+)
+async def upgrade_v1(conn: Connection) -> None:
+    """Create the initial database schema.
+
+    Creates the streams and subscriptions tables.
+
+    :param conn: A connection to run the v1 database migration on.
+    """
+    await conn.execute(
+        """CREATE TABLE "streams" (
+            "domain"    TEXT NOT NULL UNIQUE,
+            "name"  TEXT,
+            "title" TEXT,
+            "last_connect_time" TEXT,
+            "last_disconnect_time"  TEXT,
+            PRIMARY KEY("domain")
+        )"""
+    )
+
+    await conn.execute(
+        """CREATE TABLE "subscriptions" (
+            "stream_domain" INTEGER NOT NULL,
+            "room_id"   TEXT NOT NULL,
+            UNIQUE("room_id","stream_domain")
+        )"""
+    )
+
+
+@upgrade_table.register(  # type: ignore[arg-type, call-arg, untyped-decorator]
+    description="Fix stream_domain column type from INTEGER to TEXT"
+)
+async def upgrade_v2(conn: Connection) -> None:
+    """Upgrade database schema to version 2 format.
+
+    Fixes the stream_domain column type in the subscriptions table
+    from INTEGER to TEXT.
+
+    :param conn: A connection to run the v2 database migration on.
+    """
+    await conn.execute(
+        """CREATE TABLE "subscriptions_new" (
+            "stream_domain" TEXT NOT NULL,
+            "room_id"   TEXT NOT NULL,
+            UNIQUE("room_id","stream_domain")
+        )"""
+    )
+
+    await conn.execute(
+        """INSERT INTO subscriptions_new (stream_domain, room_id)
+           SELECT stream_domain, room_id FROM subscriptions"""
+    )
+
+    await conn.execute("DROP TABLE subscriptions")
+    await conn.execute("ALTER TABLE subscriptions_new RENAME TO subscriptions")
+
+
+@upgrade_table.register(  # type: ignore[arg-type, call-arg, untyped-decorator]
+    description="Add failure_counter column for backoff and auto-cleanup"
+)
+async def upgrade_v3(conn: Connection) -> None:
+    """Upgrade database schema to version 3 format.
+
+    Adds the failure_counter column to track connection failures
+    for backoff and auto-cleanup.
+
+    :param conn: A connection to run the v3 database migration on.
+    """
+    await conn.execute(
+        """ALTER TABLE streams ADD COLUMN failure_counter INTEGER DEFAULT 0"""
+    )
+
+
+@upgrade_table.register(  # type: ignore[arg-type, call-arg, untyped-decorator]
+    description="Store online status and current status timestamp"
+)
+async def upgrade_v4(conn: Connection) -> None:
+    """Upgrade database schema to version 4 format.
+
+    Replaces separate connect and disconnect timestamp columns with an
+    authoritative online flag and a timestamp for the current status.
+
+    :param conn: A connection to run the v4 database migration on.
+    """
+    await conn.execute(
+        """CREATE TABLE "streams_new" (
+            "domain"    TEXT NOT NULL UNIQUE,
+            "name"  TEXT,
+            "title" TEXT,
+            "online" BOOLEAN NOT NULL DEFAULT false,
+            "status_since" TEXT,
+            "failure_counter" INTEGER DEFAULT 0,
+            PRIMARY KEY("domain")
+        )"""
+    )
+
+    rows = await conn.fetch(
+        """SELECT domain, name, title, last_connect_time, last_disconnect_time,
+                  failure_counter
+           FROM streams"""
+    )
+    for row in rows:
+        last_connect_time = row["last_connect_time"]
+        online = last_connect_time is not None and str(last_connect_time).strip() != ""
+        legacy_timestamp = last_connect_time if online else row["last_disconnect_time"]
+        await conn.execute(
+            """INSERT INTO streams_new (
+                   domain, name, title, online, status_since, failure_counter
+               )
+               VALUES ($1, $2, $3, $4, $5, $6)""",
+            row["domain"],
+            row["name"],
+            row["title"],
+            online,
+            _normalize_legacy_status_since(legacy_timestamp),
+            row["failure_counter"],
+        )
+
+    await conn.execute("DROP TABLE streams")
+    await conn.execute("ALTER TABLE streams_new RENAME TO streams")
+
+
+def get_upgrade_table() -> UpgradeTable:
+    """Return the repository upgrade table with registered migrations."""
+    return upgrade_table
+
+
+class StreamRepository:
+    """Repository for managing stream data in the database."""
+
+    def __init__(self, database: Database) -> None:
+        """Initialize the stream repository.
+
+        :param database: The maubot database instance.
+        """
+        self.db: Any = database
+
+    async def create(self, domain: str) -> bool:
+        """Create a new stream entry in the database.
+
+        :param domain: The stream domain.
+        :return: True if created, False if the stream already existed.
+        """
+        query = """INSERT INTO streams (domain)
+                   VALUES ($1)
+                   ON CONFLICT (domain) DO NOTHING"""
+        async with self.db.acquire() as conn:
+            result = await conn.execute(query, domain)
+            return int(result.rowcount) > 0
+
+    async def get_by_domain(self, domain: str) -> StreamState | None:
+        """Get a stream's state by domain.
+
+        :param domain: The stream domain.
+        :return: StreamState if found, None otherwise.
+        """
+        query = "SELECT * FROM streams WHERE domain=$1"
+        async with self.db.acquire() as conn:
+            row = await conn.fetchrow(query, domain)
+            return StreamState.from_db_row(row) if row else None
+
+    async def exists(self, domain: str) -> bool:
+        """Check if a stream exists in the database.
+
+        :param domain: The stream domain.
+        :return: True if exists, False otherwise.
+        """
+        result = await self.get_by_domain(domain)
+        return result is not None
+
+    async def update(
+        self,
+        domain: str,
+        *,
+        name: str | None | _Unset = _UNSET,
+        title: str | None | _Unset = _UNSET,
+        online: bool | _Unset = _UNSET,
+        status_since: str | None | _Unset = _UNSET,
+    ) -> None:
+        """Update only the supplied stream fields in the database.
+
+        Passing None writes NULL for nullable fields. Omitting a field leaves
+        that column unchanged.
+
+        :param domain: The stream domain.
+        :param name: Optional stream display name update.
+        :param title: Optional stream title update.
+        :param online: Optional stream online state update.
+        :param status_since: Optional current status timestamp update.
+        """
+        # _UNSET marks omitted fields so None can still be written as SQL NULL.
+        update_name = not isinstance(name, _Unset)
+        update_title = not isinstance(title, _Unset)
+        update_online = not isinstance(online, _Unset)
+        update_status_since = not isinstance(status_since, _Unset)
+
+        if not (update_name or update_title or update_online or update_status_since):
+            return
+
+        name_value = None if isinstance(name, _Unset) else name
+        title_value = None if isinstance(title, _Unset) else title
+        online_value = None if isinstance(online, _Unset) else online
+        status_since_value = None if isinstance(status_since, _Unset) else status_since
+
+        # SQLite's IS NOT gives null-safe comparisons for the supported backend.
+        query = """UPDATE streams
+                   SET name = CASE WHEN $1 THEN $2 ELSE name END,
+                       title = CASE WHEN $3 THEN $4 ELSE title END,
+                       online = CASE WHEN $5 THEN $6 ELSE online END,
+                       status_since = CASE WHEN $7 THEN $8 ELSE status_since END
+                   WHERE domain=$9
+                     AND (($1 AND name IS NOT $2)
+                          OR ($3 AND title IS NOT $4)
+                          OR ($5 AND online IS NOT $6)
+                          OR ($7 AND status_since IS NOT $8))"""
+        async with self.db.acquire() as conn:
+            await conn.execute(
+                query,
+                update_name,
+                name_value,
+                update_title,
+                title_value,
+                update_online,
+                online_value,
+                update_status_since,
+                status_since_value,
+                domain,
+            )
+
+    async def delete(self, domain: str) -> None:
+        """Delete a stream record from the database.
+
+        :param domain: The stream domain.
+        """
+        query = "DELETE FROM streams WHERE domain=$1"
+        async with self.db.acquire() as conn:
+            await conn.execute(query, domain)
+
+    async def increment_failure_counter(self, domain: str) -> None:
+        """Increment the failure counter for a stream by 1.
+
+        :param domain: The stream domain.
+        """
+        query = """UPDATE streams
+                   SET failure_counter = failure_counter + 1
+                   WHERE domain=$1"""
+        async with self.db.acquire() as conn:
+            await conn.execute(query, domain)
+
+    async def reset_failure_counter(self, domain: str) -> None:
+        """Reset the failure counter for a stream to 0.
+
+        :param domain: The stream domain.
+        """
+        query = """UPDATE streams
+                   SET failure_counter = 0
+                   WHERE domain=$1 AND failure_counter != 0"""
+        async with self.db.acquire() as conn:
+            await conn.execute(query, domain)
+
+
+class SubscriptionRepository:
+    """Repository for managing stream subscriptions in the database."""
+
+    def __init__(self, database: Database) -> None:
+        """Initialize the subscription repository.
+
+        :param database: The maubot database instance.
+        """
+        self.db: Any = database
+
+    async def add(self, domain: str, room_id: str) -> None:
+        """Add a subscription for a room to a stream.
+
+        :param domain: The stream domain.
+        :param room_id: The Matrix room ID.
+        :raises AlreadySubscribedError: If subscription already exists.
+        """
+        query = """INSERT INTO subscriptions (stream_domain, room_id)
+                   VALUES ($1, $2)
+                   ON CONFLICT (room_id, stream_domain) DO NOTHING"""
+        async with self.db.acquire() as conn:
+            result = await conn.execute(query, domain, room_id)
+            if int(result.rowcount) == 0:
+                raise AlreadySubscribedError(domain)
+
+    async def remove(self, domain: str, room_id: str) -> None:
+        """Remove a subscription for a room from a stream.
+
+        :param domain: The stream domain.
+        :param room_id: The Matrix room ID.
+        :raises NotSubscribedError: If no subscription exists.
+        """
+        query = "DELETE FROM subscriptions WHERE stream_domain=$1 AND room_id=$2"
+        async with self.db.acquire() as conn:
+            result = await conn.execute(query, domain, room_id)
+            if int(result.rowcount) == 0:
+                raise NotSubscribedError(domain)
+
+    async def delete_all_for_domain(self, domain: str) -> int:
+        """Delete all subscriptions for a given stream domain.
+
+        :param domain: The stream domain.
+        :return: Number of subscriptions deleted.
+        """
+        query = "DELETE FROM subscriptions WHERE stream_domain=$1"
+        async with self.db.acquire() as conn:
+            result = await conn.execute(query, domain)
+            return int(result.rowcount)
+
+    async def get_subscribed_rooms(self, domain: str) -> list[str]:
+        """Get all room IDs subscribed to a stream.
+
+        :param domain: The stream domain.
+        :return: List of room IDs.
+        """
+        query = "SELECT room_id FROM subscriptions WHERE stream_domain=$1"
+        async with self.db.acquire() as conn:
+            results = await conn.fetch(query, domain)
+            return [row["room_id"] for row in results]
+
+    async def get_subscribed_streams_for_room(self, room_id: str) -> list[str]:
+        """Get all stream domains that a room is subscribed to.
+
+        :param room_id: The Matrix room ID.
+        :return: List of stream domains.
+        """
+        query = "SELECT stream_domain FROM subscriptions WHERE room_id=$1"
+        async with self.db.acquire() as conn:
+            results = await conn.fetch(query, room_id)
+            return [row["stream_domain"] for row in results]
+
+    async def has_room_subscriptions(self, room_id: str) -> bool:
+        """Check whether a room has any subscriptions."""
+        query = "SELECT 1 FROM subscriptions WHERE room_id=$1 LIMIT 1"
+        async with self.db.acquire() as conn:
+            result = await conn.fetchrow(query, room_id)
+            return result is not None
+
+    async def get_room_subscriptions(self, room_id: str) -> list[RoomSubscription]:
+        """Get resolved stream subscriptions for a room ordered by domain.
+
+        :param room_id: The Matrix room ID.
+        :return: Subscriptions with stream state attached.
+        """
+        query = """SELECT streams.*
+                   FROM subscriptions
+                   JOIN streams ON streams.domain = subscriptions.stream_domain
+                   WHERE subscriptions.room_id=$1
+                   ORDER BY streams.domain"""
+        async with self.db.acquire() as conn:
+            results = await conn.fetch(query, room_id)
+            return [
+                RoomSubscription(
+                    domain=row["domain"],
+                    stream_state=StreamState.from_db_row(row),
+                )
+                for row in results
+            ]
+
+    async def get_live_room_subscriptions(self, room_id: str) -> list[RoomSubscription]:
+        """Get resolved live stream subscriptions for a room ordered by domain."""
+        query = """SELECT streams.*
+                   FROM subscriptions
+                   JOIN streams ON streams.domain = subscriptions.stream_domain
+                   WHERE subscriptions.room_id=$1
+                     AND streams.online=true
+                     AND streams.failure_counter <= $2
+                   ORDER BY streams.domain"""
+        async with self.db.acquire() as conn:
+            results = await conn.fetch(query, room_id, UNKNOWN_STATUS_THRESHOLD)
+            return [
+                RoomSubscription(
+                    domain=row["domain"],
+                    stream_state=StreamState.from_db_row(row),
+                )
+                for row in results
+            ]
+
+    async def get_all_subscribed_domains(self) -> list[str]:
+        """Get all unique stream domains that have at least one subscription.
+
+        :return: List of stream domains.
+        """
+        query = "SELECT DISTINCT stream_domain FROM subscriptions"
+        async with self.db.acquire() as conn:
+            results = await conn.fetch(query)
+            return [row["stream_domain"] for row in results]
+
+    async def count_by_domain(self, domain: str) -> int:
+        """Count the number of subscriptions for a given stream domain.
+
+        :param domain: The stream domain.
+        :return: Number of subscriptions.
+        """
+        query = "SELECT COUNT(*) FROM subscriptions WHERE stream_domain=$1"
+        async with self.db.acquire() as conn:
+            result = await conn.fetchrow(query, domain)
+            return int(result[0])
+
+    async def count_by_domains(self, domains: list[str]) -> dict[str, int]:
+        """Count subscriptions for each requested stream domain.
+
+        :param domains: The stream domains to count subscriptions for.
+        :return: Mapping from each requested domain to its subscription count.
+        """
+        if not domains:
+            return {}
+
+        counts = dict.fromkeys(domains, 0)
+        query = """SELECT stream_domain, COUNT(*) AS subscription_count
+                   FROM subscriptions
+                   GROUP BY stream_domain"""
+        async with self.db.acquire() as conn:
+            results = await conn.fetch(query)
+
+        for row in results:
+            domain = row["stream_domain"]
+            if domain in counts:
+                counts[domain] = int(row["subscription_count"])
+        return counts

owncastsentry/stream_monitor.py

@@ -1,23 +1,165 @@
 # Copyright 2026 Logan Fick
 #
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
 #
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Stream monitoring service for OwncastSentry."""
 
 import asyncio
 import time
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import Enum, auto
+from typing import TYPE_CHECKING
 
-from .owncast_client import OwncastClient
-from .database import StreamRepository, SubscriptionRepository
-from .notification_service import NotificationService
-from .models import StreamState
-from .utils import (
-    TEMPORARY_OFFLINE_NOTIFICATION_COOLDOWN,
-    CLEANUP_WARNING_THRESHOLD,
-    CLEANUP_DELETE_THRESHOLD,
-    should_query_stream,
+from .types import (
+    StreamConfigObservation,
+    StreamState,
+    StreamStateObservation,
+    StreamStatus,
+    UpdateResult,
 )
 
+if TYPE_CHECKING:
+    import logging
+
+    from .metrics import MetricsService
+    from .notification_service import NotificationService
+    from .owncast_client import OwncastClient
+    from .repository import StreamRepository, SubscriptionRepository
+
+
+_TEMPORARY_OFFLINE_NOTIFICATION_COOLDOWN = 7 * 60
+
+_CLEANUP_WARNING_THRESHOLD = 83 * 24 * 60
+_CLEANUP_DELETE_THRESHOLD = 90 * 24 * 60
+_QUERY_EVERY_MINUTE_FAILURE_LIMIT = 4
+_QUERY_EVERY_2_MINUTES_FAILURE_LIMIT = 9
+_QUERY_EVERY_3_MINUTES_FAILURE_LIMIT = 14
+_QUERY_EVERY_5_MINUTES_FAILURE_LIMIT = 29
+_QUERY_EVERY_2_MINUTES_INTERVAL = 2
+_QUERY_EVERY_3_MINUTES_INTERVAL = 3
+_QUERY_EVERY_5_MINUTES_INTERVAL = 5
+_QUERY_EVERY_15_MINUTES_INTERVAL = 15
+
+
+def _should_query_stream(failure_counter: int) -> bool:
+    """Determine if a stream should be queried based on failure count."""
+    if failure_counter <= _QUERY_EVERY_MINUTE_FAILURE_LIMIT:
+        return True
+    if failure_counter <= _QUERY_EVERY_2_MINUTES_FAILURE_LIMIT:
+        return failure_counter % _QUERY_EVERY_2_MINUTES_INTERVAL == 0
+    if failure_counter <= _QUERY_EVERY_3_MINUTES_FAILURE_LIMIT:
+        return failure_counter % _QUERY_EVERY_3_MINUTES_INTERVAL == 0
+    if failure_counter <= _QUERY_EVERY_5_MINUTES_FAILURE_LIMIT:
+        return failure_counter % _QUERY_EVERY_5_MINUTES_INTERVAL == 0
+    return failure_counter % _QUERY_EVERY_15_MINUTES_INTERVAL == 0
+
+
+class _StreamTransitionKind(Enum):
+    """High-level status transition from stored state to fresh observation."""
+
+    FIRST_OBSERVATION = auto()
+    WENT_LIVE = auto()
+    WENT_OFFLINE = auto()
+    TITLE_CHANGED = auto()
+    STATUS_UNCHANGED = auto()
+
+
+@dataclass(frozen=True, slots=True)
+class _StreamTransition:
+    """Classified stream transition and timestamp metadata."""
+
+    kind: _StreamTransitionKind
+    status_since: str | None
+
+
+class _NotificationKind(Enum):
+    """Live/title notification action for a transition."""
+
+    NONE = auto()
+    LIVE = auto()
+    TITLE_CHANGE = auto()
+
+    @property
+    def should_notify(self) -> bool:
+        """Return whether a live/title-change notification should be attempted."""
+        return self is not _NotificationKind.NONE
+
+
+def _classify_transition(
+    old_state: StreamState, observation: StreamStateObservation
+) -> _StreamTransition:
+    """Classify the transition from the stored state to the latest observation."""
+    if old_state.status_since is None:
+        return _StreamTransition(
+            kind=_StreamTransitionKind.FIRST_OBSERVATION,
+            status_since=observation.observed_at,
+        )
+
+    if old_state.online != observation.online:
+        return _StreamTransition(
+            kind=(
+                _StreamTransitionKind.WENT_LIVE
+                if observation.online
+                else _StreamTransitionKind.WENT_OFFLINE
+            ),
+            status_since=observation.observed_at,
+        )
+
+    if old_state.online and old_state.title != observation.title:
+        return _StreamTransition(
+            kind=_StreamTransitionKind.TITLE_CHANGED,
+            status_since=old_state.status_since,
+        )
+
+    return _StreamTransition(
+        kind=_StreamTransitionKind.STATUS_UNCHANGED,
+        status_since=old_state.status_since,
+    )
+
+
+def _classify_notification(
+    transition: _StreamTransition,
+    old_state: StreamState,
+    observation: StreamStateObservation,
+    *,
+    offline_duration_seconds: int | None = None,
+    went_offline_after_last_notification: bool = False,
+) -> _NotificationKind:
+    """Classify the live/title notification policy for a transition.
+
+    The caller supplies timing context because it comes from the monitor's
+    monotonic offline cache and notification-service cache, not the transition.
+    """
+    match transition.kind:
+        case _StreamTransitionKind.WENT_LIVE:
+            if offline_duration_seconds is not None and (
+                offline_duration_seconds < _TEMPORARY_OFFLINE_NOTIFICATION_COOLDOWN
+            ):
+                if old_state.title != observation.title:
+                    return _NotificationKind.TITLE_CHANGE
+                return _NotificationKind.NONE
+
+            return _NotificationKind.LIVE
+
+        case _StreamTransitionKind.TITLE_CHANGED:
+            if went_offline_after_last_notification:
+                return _NotificationKind.LIVE
+            return _NotificationKind.TITLE_CHANGE
+
+        case _:
+            return _NotificationKind.NONE
+
 
 class StreamMonitor:
     """Monitors Owncast streams and detects state changes."""
@@ -26,270 +168,286 @@ class StreamMonitor:
         self,
         owncast_client: OwncastClient,
         stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
         notification_service: NotificationService,
-        logger,
-    ):
-        """
-        Initialize the stream monitor.
+        logger: logging.Logger,
+        metrics: MetricsService,
+    ) -> None:
+        """Initialize the stream monitor.
 
-        :param owncast_client: Client for making API calls to Owncast instances
-        :param stream_repo: Repository for stream data
-        :param notification_service: Service for sending notifications
-        :param logger: Logger instance
+        :param owncast_client: Client for making API calls to Owncast instances.
+        :param stream_repo: Repository for stream data.
+        :param subscription_repo: Repository for subscription data.
+        :param notification_service: Service for sending notifications.
+        :param logger: Logger instance for debugging.
+        :param metrics: Metrics service for recording Prometheus metrics.
         """
         self.owncast_client = owncast_client
         self.stream_repo = stream_repo
+        self.subscription_repo = subscription_repo
         self.notification_service = notification_service
         self.log = logger
+        self.metrics = metrics
 
         # Cache for tracking when streams last went offline
-        self.offline_timer_cache = {}
+        self.offline_timer_cache: dict[str, float] = {}
 
-    async def update_all_streams(self, subscribed_domains: list[str]) -> None:
-        """
-        Checks the status of all streams with active subscriptions.
-        Updates for all streams are performed asynchronously, with the method returning when the slowest update completes.
+    async def update_all_streams(self, subscribed_domains: list[str]) -> UpdateResult:
+        """Check the status of all streams with active subscriptions.
 
-        :param subscribed_domains: List of stream domains to update
-        :return: Nothing.
+        Updates for all streams are performed asynchronously, with the
+        method returning when the slowest update completes.
+
+        :param subscribed_domains: List of stream domains to update.
+        :return: UpdateResult with success/failure counts.
         """
         self.log.debug("Updating all stream states...")
 
-        # Build a list of async tasks which update the state for each stream domain
-        tasks = []
+        total_streams = len(subscribed_domains)
+
+        # Run all stream updates concurrently and collect results.
+        results = await asyncio.gather(
+            *(self.update_stream(domain) for domain in subscribed_domains),
+            return_exceptions=True,
+        )
+
+        # Count successes and failures
+        successful_checks = 0
+        failed_checks = 0
+        for domain, result in zip(subscribed_domains, results, strict=True):
+            if isinstance(result, BaseException):
+                self.log.exception(
+                    "[%s] Unhandled exception during stream update.",
+                    domain,
+                    exc_info=result,
+                )
+                failed_checks += 1
+            elif result:
+                successful_checks += 1
+            else:
+                failed_checks += 1
+
+        self.log.debug(
+            "Update complete. %s/%s succeeded, %s failed.",
+            successful_checks,
+            total_streams,
+            failed_checks,
+        )
+
+        subscription_counts = await self.subscription_repo.count_by_domains(
+            subscribed_domains
+        )
         for domain in subscribed_domains:
-            tasks.append(asyncio.create_task(self.update_stream(domain)))
+            self.metrics.set_subscription_count(
+                domain, subscription_counts.get(domain, 0)
+            )
 
-        # Run the tasks in parallel
-        await asyncio.gather(*tasks)
-        self.log.debug("Update complete.")
+        return UpdateResult(
+            total_streams=total_streams,
+            successful_checks=successful_checks,
+            failed_checks=failed_checks,
+        )
 
-    async def update_stream(self, domain: str) -> None:
-        """
-        Updates the state of a given stream domain and sends notifications to subscribed Matrix rooms if it goes live.
-        Implements progressive backoff for connection failures and auto-cleanup for dead instances.
+    async def update_stream(self, domain: str) -> bool:
+        """Update the state of a stream and send notifications as needed.
+
+        Sends notifications to subscribed Matrix rooms when a stream goes
+        live or changes title. Implements progressive backoff for connection
+        failures and auto-cleanup for dead instances.
 
         :param domain: The domain of the stream to update.
-        :return: Nothing.
+        :return: True if check succeeded or was skipped, False on failure.
         """
         # Fetch the current stream state from database to check failure_counter
         old_state = await self.stream_repo.get_by_domain(domain)
         failure_counter = old_state.failure_counter if old_state else 0
 
+        if old_state is None:
+            return True
+
         # Check if we should query this stream based on backoff schedule
-        if not should_query_stream(failure_counter):
+        if not _should_query_stream(failure_counter):
             # Skip this cycle, increment counter to track time passage
             await self.stream_repo.increment_failure_counter(domain)
             self.log.debug(
-                f"[{domain}] Skipping query due to backoff (counter={failure_counter + 1})"
+                "[%s] Skipping query due to backoff (counter=%s)",
+                domain,
+                failure_counter + 1,
             )
             # Check cleanup thresholds even when skipping query
             await self._check_cleanup_thresholds(domain, failure_counter + 1)
-            return
-
-        # A flag indicating whether this is the first state update of a brand-new stream to avoid sending notifications if its already live.
-        first_update = False
-
-        # A flag indicating whether to update the stream's state in the database.
-        # Used to avoid writing to the database when a stream's state hasn't changed at all.
-        update_database = False
-
-        # Holds the stream's latest configuration, if fetched and deemed necessary during the update process.
-        stream_config = None
+            updated_state = await self.stream_repo.get_by_domain(domain)
+            if updated_state is not None:
+                self.metrics.set_stream_status(domain, updated_state.status)
+                self.metrics.set_check_failures(domain, failure_counter + 1)
+            # Backoff is expected behavior, not a failure
+            return True
 
         # Fetch the latest stream state from the server
-        new_state = await self.owncast_client.get_stream_state(domain)
+        observation = await self.owncast_client.get_stream_state(domain)
 
         # If the fetch failed, increment failure counter and skip the update
-        if new_state is None:
+        if observation is None:
             await self.stream_repo.increment_failure_counter(domain)
             self.log.warning(
-                f"[{domain}] Connection failure (counter={failure_counter + 1})"
+                "[%s] Connection failure (counter=%s)",
+                domain,
+                failure_counter + 1,
             )
             # Check cleanup thresholds after connection failure
             await self._check_cleanup_thresholds(domain, failure_counter + 1)
-            return
+            updated_state = await self.stream_repo.get_by_domain(domain)
+            if updated_state is not None:
+                self.metrics.set_stream_status(domain, updated_state.status)
+                self.metrics.set_check_failures(domain, failure_counter + 1)
+            # Actual connection failure
+            return False
 
         # Fetch succeeded! Reset failure counter
         await self.stream_repo.reset_failure_counter(domain)
+        self.metrics.set_check_failures(domain, 0)
 
-        # Fix possible race conditions with timers
-        if domain not in self.offline_timer_cache:
-            self.offline_timer_cache[domain] = 0
-        if domain not in self.notification_service.notification_timers_cache:
-            self.notification_service.notification_timers_cache[domain] = 0
+        # Initialize timer cache entries to prevent KeyError on first access
+        self.offline_timer_cache.setdefault(domain, 0)
 
-        # Does the last known stream state not have a value for the last connect and disconnect time?
-        if (
-            old_state.last_connect_time is None
-            and old_state.last_disconnect_time is None
-        ):
-            # Yes, this is the first update. Don't send any notifications.
-            update_database = True
-            first_update = True
+        transition = _classify_transition(old_state, observation)
+        # Notification policy may need runtime timing context in addition to
+        # the stored state and latest observation.
+        offline_duration_seconds: int | None = None
+        went_offline_after_last_notification = False
 
-        # Does the latest stream state have a last connect time and the old state not have one?
-        if (
-            new_state.last_connect_time is not None
-            and old_state.last_connect_time is None
-        ):
-            # Yes! This stream is now live.
-            update_database = True
-            stream_config = await self.owncast_client.get_stream_config(domain)
-
-            self.log.info(f"[{domain}] Stream is now live!")
-
-            # Calculate how many seconds since the stream last went offline
-            seconds_since_last_offline = round(
-                time.time() - self.offline_timer_cache[domain]
-            )
-
-            # Have we queried this stream before? (In other words, is this not the first state update ever?)
-            if not first_update:
-                # Use fallback values if config fetch failed
-                stream_name = stream_config.name if stream_config else domain
-                stream_tags = stream_config.tags if stream_config else []
-
-                # Yes. Has this stream been offline for a short amount of time?
-                if seconds_since_last_offline < TEMPORARY_OFFLINE_NOTIFICATION_COOLDOWN:
-                    # Yes. Did the stream title change?
-                    if old_state.title != new_state.title:
-                        # Yes. The stream was only down for a short time, send a special notification indicating the stream changed its name.
-                        await self.notification_service.notify_stream_live(
-                            domain,
-                            stream_name,
-                            new_state.title,
-                            stream_tags,
-                            title_change=True,
-                        )
-                    else:
-                        # No. The stream was only down for a short time and didn't change its title. Don't send a notification.
+        match transition.kind:
+            case _StreamTransitionKind.FIRST_OBSERVATION:
                 self.log.info(
-                            f"[{domain}] Not sending notifications. Stream was only offline for {seconds_since_last_offline} of {TEMPORARY_OFFLINE_NOTIFICATION_COOLDOWN} seconds and did not change its title."
-                        )
-                else:
-                    # This stream has been offline for a while. Send a normal notification.
-                    await self.notification_service.notify_stream_live(
+                    "[%s] Not sending notifications. This is the first state "
+                    "update for this stream.",
                     domain,
-                        stream_name,
-                        new_state.title,
-                        stream_tags,
-                        title_change=False,
                 )
-            else:
-                # No, this is the first time we're querying
+            case _StreamTransitionKind.WENT_LIVE:
+                self.log.info("[%s] Stream is now live!", domain)
+                offline_duration_seconds = round(
+                    time.monotonic() - self.offline_timer_cache[domain]
+                )
+                # Brief reconnects with the same title are treated as transient
+                # outages, not new live events.
+                if (
+                    offline_duration_seconds < _TEMPORARY_OFFLINE_NOTIFICATION_COOLDOWN
+                    and old_state.title == observation.title
+                ):
                     self.log.info(
-                    f"[{domain}] Not sending notifications. This is the first state update for this stream."
+                        "[%s] Not sending notifications. Stream was only offline for "
+                        "%s of %s seconds and did not change its title.",
+                        domain,
+                        offline_duration_seconds,
+                        _TEMPORARY_OFFLINE_NOTIFICATION_COOLDOWN,
+                    )
+            case _StreamTransitionKind.TITLE_CHANGED:
+                self.log.info("[%s] Stream title was changed!", domain)
+                # If we saw an offline event after the last notification, send
+                # a go-live notice instead of only a title-change notice.
+                went_offline_after_last_notification = self.offline_timer_cache[
+                    domain
+                ] > self.notification_service.get_last_notification_time(domain)
+            case _StreamTransitionKind.WENT_OFFLINE:
+                self.offline_timer_cache[domain] = time.monotonic()
+                self.log.info("[%s] Stream is now offline.", domain)
+            case _StreamTransitionKind.STATUS_UNCHANGED:
+                pass
+
+        notification_kind = _classify_notification(
+            transition,
+            old_state,
+            observation,
+            offline_duration_seconds=offline_duration_seconds,
+            went_offline_after_last_notification=went_offline_after_last_notification,
         )
 
-        if (
-            new_state.last_connect_time is not None
-            and old_state.last_connect_time is not None
-        ):
-            # Did the stream title change mid-session?
-            if old_state.title != new_state.title:
-                self.log.info(f"[{domain}] Stream title was changed!")
-                update_database = True
+        stream_config: StreamConfigObservation | None = None
+        observed_at = datetime.fromisoformat(observation.observed_at)
+        hourly_config_refresh_due = (
+            observed_at.tzinfo is not None and observed_at.astimezone(UTC).minute == 0
+        )
+        should_fetch_config = (
+            notification_kind.should_notify
+            or transition.kind is _StreamTransitionKind.FIRST_OBSERVATION
+            or hourly_config_refresh_due
+        )
+        if should_fetch_config:
             stream_config = await self.owncast_client.get_stream_config(domain)
 
-                # Use fallback values if config fetch failed
+        if notification_kind.should_notify:
             stream_name = stream_config.name if stream_config else domain
-                stream_tags = stream_config.tags if stream_config else []
+            stream_tags = stream_config.tags if stream_config else ()
+            is_title_change = notification_kind is _NotificationKind.TITLE_CHANGE
 
-                # This is a fun case to account for... Let's try and explain this.
-                # Was the last time this stream sent a notification before it last went offline?
-                if (
-                    self.offline_timer_cache[domain]
-                    > self.notification_service.notification_timers_cache[domain]
-                ):
-                    # Yes. Send a regular go live notification.
-                    # Why? A title change notification could be confusing to users in this case.
-                    # How? If a stream goes offline before its next allowed notification, it'll get rate limited. If it then changes its title, this part of the code will send a title change notification. This can be a little confusing, so override to a normal go live notification in this case.
             await self.notification_service.notify_stream_live(
                 domain,
                 stream_name,
-                        new_state.title,
+                observation.title or "",
                 stream_tags,
-                        title_change=False,
+                title_change=is_title_change,
             )
-                else:
-                    # No. Send a normal title change notification.
-                    await self.notification_service.notify_stream_live(
+
+        self.log.debug("[%s] Saving stream state if changed...", domain)
+
+        if stream_config is not None:
+            await self.stream_repo.update(
                 domain,
-                        stream_name,
-                        new_state.title,
-                        stream_tags,
-                        title_change=True,
+                name=stream_config.name,
+                title=observation.title,
+                online=observation.online,
+                status_since=transition.status_since,
             )
-
-        # Does the latest stream state no longer have a last connect time but the old state does?
-        elif (
-            new_state.last_connect_time is None
-            and old_state.last_connect_time is not None
-        ):
-            # Yep. This stream is now offline. Log it.
-            update_database = True
-            self.offline_timer_cache[domain] = time.time()
-            if first_update:
-                self.log.info(f"[{domain}] Stream is offline.")
         else:
-                self.log.info(f"[{domain}] Stream is now offline.")
-
-        # Update the database with the current stream state, if needed.
-        if update_database:
-            # Ensure we have the stream config before updating the database
-            if stream_config is None:
-                stream_config = await self.owncast_client.get_stream_config(domain)
-
-            # Use fallback value if config fetch failed
-            stream_name = stream_config.name if stream_config else ""
-
-            self.log.debug(f"[{domain}] Updating stream state in database...")
-
-            # Create updated state object (title already truncated in new_state)
-            updated_state = StreamState(
-                domain=domain,
-                name=stream_name,
-                title=new_state.title,
-                last_connect_time=new_state.last_connect_time,
-                last_disconnect_time=new_state.last_disconnect_time,
+            await self.stream_repo.update(
+                domain,
+                title=observation.title,
+                online=observation.online,
+                status_since=transition.status_since,
             )
 
-            await self.stream_repo.update(updated_state)
-
         # All done.
-        self.log.debug(f"[{domain}] State update completed.")
+        self.log.debug("[%s] State update completed.", domain)
+        stream_status = (
+            StreamStatus.ONLINE if observation.online else StreamStatus.OFFLINE
+        )
+        self.metrics.set_stream_status(domain, stream_status)
+        return True
 
     async def _check_cleanup_thresholds(self, domain: str, counter: int) -> None:
-        """
-        Check if a domain has hit cleanup warning or deletion thresholds.
+        """Check if a domain hit cleanup warning or deletion thresholds.
 
-        :param domain: The domain to check
-        :param counter: The current failure counter value
-        :return: Nothing
+        :param domain: The domain to check.
+        :param counter: The current failure counter value.
         """
         # Check for 83-day warning threshold
-        if counter == CLEANUP_WARNING_THRESHOLD:
+        if counter == _CLEANUP_WARNING_THRESHOLD:
             self.log.warning(
-                f"[{domain}] Reached 83-day warning threshold. Sending cleanup warning."
+                "[%s] Reached 83-day warning threshold. Sending cleanup warning.",
+                domain,
             )
             await self.notification_service.send_cleanup_warning(domain)
 
         # Check for 90-day deletion threshold
-        if counter >= CLEANUP_DELETE_THRESHOLD:
+        if counter >= _CLEANUP_DELETE_THRESHOLD:
             self.log.warning(
-                f"[{domain}] Reached 90-day deletion threshold. Removing all subscriptions."
+                "[%s] Reached 90-day deletion threshold. Removing all subscriptions.",
+                domain,
             )
             # Send deletion notification
             await self.notification_service.send_cleanup_deletion(domain)
 
             # Delete all subscriptions for this domain
-            subscription_repo = SubscriptionRepository(self.stream_repo.db)
-            deleted_count = await subscription_repo.delete_all_for_domain(domain)
+            deleted_count = await self.subscription_repo.delete_all_for_domain(domain)
 
             # Delete the stream record
             await self.stream_repo.delete(domain)
+            self.offline_timer_cache.pop(domain, None)
+            self.notification_service.clear_notification_state(domain)
 
             self.log.info(
-                f"[{domain}] Cleanup complete. Deleted {deleted_count} subscriptions and stream record."
+                "[%s] Cleanup complete. Deleted %s subscriptions and stream record.",
+                domain,
+                deleted_count,
             )
+            self.metrics.remove_stream(domain)

owncastsentry/subscription_manager.py

@@ -0,0 +1,119 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Business logic for managing room stream subscriptions."""
+
+import re
+from typing import TYPE_CHECKING
+from urllib.parse import urlparse
+
+from .types import (
+    InvalidOwncastInstanceError,
+    RoomSubscription,
+)
+
+if TYPE_CHECKING:
+    import logging
+
+    from .owncast_client import OwncastClient
+    from .repository import StreamRepository, SubscriptionRepository
+
+
+_DOMAIN_CLEANUP_RE = re.compile(r"[^a-z0-9.-]")
+
+
+def _domainify(url: str) -> str:
+    """Extract and sanitize a domain from user input."""
+    url = url.strip()
+
+    if "@" in url:
+        url = url.rsplit("@", 1)[1]
+
+    if not url.startswith(("http://", "https://", "//")):
+        url = f"//{url}"
+
+    parsed = urlparse(url)
+    domain = (parsed.netloc or parsed.path).lower()
+    domain = domain.partition(":")[0].partition("/")[0]
+    return _DOMAIN_CLEANUP_RE.sub("", domain).strip(".-")
+
+
+class SubscriptionManager:
+    """Coordinates subscription use cases between handlers and repositories."""
+
+    def __init__(
+        self,
+        owncast_client: OwncastClient,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+        logger: logging.Logger,
+    ) -> None:
+        """Initialize the subscription manager."""
+        self.owncast_client = owncast_client
+        self.stream_repo = stream_repo
+        self.subscription_repo = subscription_repo
+        self.log = logger
+
+    async def subscribe(self, room_id: str, url: str) -> str:
+        """Subscribe a room to stream notifications and return the stream domain.
+
+        :param room_id: Matrix room ID to subscribe.
+        :param url: User-supplied Owncast URL, domain, or Fediverse-style address.
+        :return: Normalized stream domain.
+        :raises InvalidOwncastInstanceError: If first-time validation fails.
+        :raises AlreadySubscribedError: If the room is already subscribed.
+        """
+        stream_domain = _domainify(url)
+
+        subscription_count = await self.subscription_repo.count_by_domain(stream_domain)
+        if subscription_count == 0:
+            is_valid = await self.owncast_client.validate_instance(stream_domain)
+            if not is_valid:
+                raise InvalidOwncastInstanceError(stream_domain)
+
+        await self.subscription_repo.add(stream_domain, room_id)
+
+        if await self.stream_repo.create(stream_domain):
+            self.log.info("[%s] Discovered new stream!", stream_domain)
+
+        self.log.info("[%s] Subscription added for room %s.", stream_domain, room_id)
+        return stream_domain
+
+    async def unsubscribe(self, room_id: str, url: str) -> str:
+        """Remove a room subscription and return the stream domain.
+
+        :param room_id: Matrix room ID to unsubscribe.
+        :param url: User-supplied Owncast URL, domain, or Fediverse-style address.
+        :return: Normalized stream domain.
+        :raises NotSubscribedError: If no subscription was removed.
+        """
+        stream_domain = _domainify(url)
+        await self.subscription_repo.remove(stream_domain, room_id)
+
+        self.log.info("[%s] Subscription removed for room %s.", stream_domain, room_id)
+        return stream_domain
+
+    async def list_room_subscriptions(self, room_id: str) -> list[RoomSubscription]:
+        """Return stream subscriptions for a room with display state attached."""
+        return await self.subscription_repo.get_room_subscriptions(room_id)
+
+    async def has_room_subscriptions(self, room_id: str) -> bool:
+        """Return whether the room has any stream subscriptions."""
+        return await self.subscription_repo.has_room_subscriptions(room_id)
+
+    async def list_live_room_subscriptions(
+        self, room_id: str
+    ) -> list[RoomSubscription]:
+        """Return only currently online stream subscriptions for a room."""
+        return await self.subscription_repo.get_live_room_subscriptions(room_id)

owncastsentry/types.py

@@ -0,0 +1,257 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Data containers and domain errors for OwncastSentry."""
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+UNKNOWN_STATUS_THRESHOLD = 15
+
+# Maximum field lengths based on Owncast's admin config constants.
+# Source: https://github.com/owncast/owncast/blob/master/web/utils/config-constants.tsx
+_MAX_INSTANCE_TITLE_LENGTH = 255  # TEXTFIELD_PROPS_SERVER_NAME maxLength
+_MAX_STREAM_TITLE_LENGTH = 100  # TEXTFIELD_PROPS_STREAM_TITLE maxLength
+_MAX_TAG_LENGTH = 24  # tag maxLength
+
+
+class InvalidApiResponseError(ValueError):
+    """The Owncast API response did not match the expected shape."""
+
+
+def _require_field(response: dict[str, Any], field: str) -> Any:
+    """Return a required API response field or raise if missing."""
+    try:
+        return response[field]
+    except KeyError as e:
+        raise InvalidApiResponseError(f"missing field: {field}") from e
+
+
+def _require_str(response: dict[str, Any], field: str) -> str:
+    """Return a required string API response field."""
+    value = _require_field(response, field)
+    if not isinstance(value, str):
+        raise InvalidApiResponseError(f"{field} must be a string")
+    return value
+
+
+def _optional_config_str(response: dict[str, Any], field: str) -> str:
+    """Return an optional config string, defaulting to empty when absent."""
+    value = response.get(field, "")
+    if not isinstance(value, str):
+        raise InvalidApiResponseError(f"{field} must be a string")
+    return value
+
+
+def _optional_tag_list(response: dict[str, Any]) -> list[str]:
+    """Return optional config tags, defaulting to an empty list when absent."""
+    value = response.get("tags", [])
+    if not isinstance(value, list):
+        raise InvalidApiResponseError("tags must be a list")
+    if not all(isinstance(tag, str) for tag in value):
+        raise InvalidApiResponseError("tags must contain only strings")
+    return value
+
+
+def _truncate(text: str, max_length: int) -> str:
+    """Truncate text to a maximum length."""
+    if len(text) <= max_length:
+        return text
+    return text[:max_length]
+
+
+def format_status_since(timestamp: datetime) -> str:
+    """Format a status timestamp using the package's canonical UTC format."""
+    if timestamp.tzinfo is None:
+        timestamp = timestamp.replace(tzinfo=UTC)
+    return timestamp.astimezone(UTC).isoformat(timespec="seconds")
+
+
+def _current_observed_at() -> str:
+    """Return the current UTC time in the package's timestamp format."""
+    return format_status_since(datetime.now(UTC))
+
+
+class StreamStatus(Enum):
+    """Represents the status of a stream."""
+
+    ONLINE = "online"
+    OFFLINE = "offline"
+    UNKNOWN = "unknown"
+
+
+@dataclass(frozen=True, slots=True)
+class StreamStateObservation:
+    """Status API sample fetched from an Owncast instance.
+
+    This records what `/api/status` reported during one request. `observed_at`
+    belongs to that fetch; the monitor decides whether that time starts a new
+    persisted online/offline period in `StreamState`.
+    """
+
+    domain: str
+    title: str | None = None
+    online: bool = False
+    observed_at: str = field(default_factory=_current_observed_at)
+
+    @classmethod
+    def from_api_response(
+        cls, response: dict[str, Any], domain: str
+    ) -> StreamStateObservation:
+        """Create a StreamStateObservation from a status API response.
+
+        :param response: API response as a dictionary (camelCase keys).
+        :param domain: The stream domain.
+        :return: StreamStateObservation instance.
+        :raises InvalidApiResponseError: If the response shape is invalid.
+        """
+        stream_title = _require_str(response, "streamTitle")
+        online = _require_field(response, "online")
+        if not isinstance(online, bool):
+            raise InvalidApiResponseError("online must be a boolean")
+
+        return cls(
+            domain=domain,
+            title=_truncate(stream_title, _MAX_STREAM_TITLE_LENGTH),
+            online=online,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class StreamState:
+    """Stream record remembered by the repository.
+
+    States include persisted display data, the current online/offline period,
+    and failure counters used to derive user-facing status. `status_since`
+    records when the persisted online/offline period began.
+    """
+
+    domain: str
+    name: str | None = None
+    title: str | None = None
+    online: bool = False
+    status_since: str | None = None
+    failure_counter: int = 0
+
+    @property
+    def status(self) -> StreamStatus:
+        """Derive stream status from failure count and online state.
+
+        Returns UNKNOWN if failures exceed the threshold, ONLINE if the
+        stream is online, or OFFLINE otherwise.
+        """
+        if self.failure_counter > UNKNOWN_STATUS_THRESHOLD:
+            return StreamStatus.UNKNOWN
+        if self.online:
+            return StreamStatus.ONLINE
+        return StreamStatus.OFFLINE
+
+    @classmethod
+    def from_db_row(cls, row: dict[str, Any]) -> StreamState:
+        """Create a StreamState from a database row.
+
+        :param row: Database row as a dictionary.
+        :return: StreamState instance.
+        """
+        return cls(
+            domain=row["domain"],
+            name=row["name"],
+            title=row["title"],
+            online=bool(row["online"]),
+            status_since=row["status_since"],
+            failure_counter=row["failure_counter"],
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class StreamConfigObservation:
+    """Config API sample fetched from an Owncast instance.
+
+    This records display metadata from one `/api/config` request. It is used for
+    notification text and may refresh persisted display fields independently of
+    the stream's online/offline state.
+    """
+
+    name: str = ""
+    tags: tuple[str, ...] = ()
+    observed_at: str = field(default_factory=_current_observed_at)
+
+    @classmethod
+    def from_api_response(cls, response: dict[str, Any]) -> StreamConfigObservation:
+        """Create a StreamConfigObservation from an API response.
+
+        :param response: API response as a dictionary.
+        :return: StreamConfigObservation instance.
+        :raises InvalidApiResponseError: If the response shape is invalid.
+        """
+        # Apply Owncast's instance name limit.
+        name = _truncate(
+            _optional_config_str(response, "name"), _MAX_INSTANCE_TITLE_LENGTH
+        )
+
+        # Apply Owncast's per-tag limit.
+        raw_tags = _optional_tag_list(response)
+        tags = tuple([_truncate(tag, _MAX_TAG_LENGTH) for tag in raw_tags])
+
+        return cls(name=name, tags=tags)
+
+
+@dataclass(frozen=True, slots=True)
+class UpdateResult:
+    """Result of a stream update cycle."""
+
+    total_streams: int
+    successful_checks: int
+    failed_checks: int
+
+
+class SubscriptionError(Exception):
+    """Base class for subscription domain errors."""
+
+
+class InvalidOwncastInstanceError(SubscriptionError):
+    """The requested domain is not a reachable Owncast instance."""
+
+    def __init__(self, domain: str) -> None:
+        """Initialize with the rejected stream domain."""
+        self.domain = domain
+        super().__init__(f"invalid Owncast instance: {domain}")
+
+
+class AlreadySubscribedError(SubscriptionError):
+    """The room is already subscribed to the stream."""
+
+    def __init__(self, domain: str) -> None:
+        """Initialize with the duplicate stream domain."""
+        self.domain = domain
+        super().__init__(f"already subscribed: {domain}")
+
+
+class NotSubscribedError(SubscriptionError):
+    """The room is not subscribed to the stream."""
+
+    def __init__(self, domain: str) -> None:
+        """Initialize with the missing stream domain."""
+        self.domain = domain
+        super().__init__(f"not subscribed: {domain}")
+
+
+@dataclass(frozen=True, slots=True)
+class RoomSubscription:
+    """A stream subscription resolved with the stream state used for display."""
+
+    domain: str
+    stream_state: StreamState

owncastsentry/utils.py

@@ -1,185 +0,0 @@
-# Copyright 2026 Logan Fick
-#
-# Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: https://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
-
-import re
-from urllib.parse import urlparse
-
-# Path to the GetStatus API call on Owncast instances
-OWNCAST_STATUS_PATH = "/api/status"
-
-# Path to GetWebConfig API call on Owncast instances
-OWNCAST_CONFIG_PATH = "/api/config"
-
-# User agent to send with all HTTP requests.
-USER_AGENT = (
-    "OwncastSentry/1.1.0 (bot; +https://git.logal.dev/LogalDeveloper/OwncastSentry)"
-)
-
-# Hard minimum amount of time between when notifications can be sent for a stream. Prevents spamming notifications for glitchy or malicious streams.
-SECONDS_BETWEEN_NOTIFICATIONS = 20 * 60  # 20 minutes in seconds
-
-# I'm not sure the best way to name or explain this variable, so let's just say what uses it:
-#
-# After a stream goes offline, a timer is started. Then, ...
-# - If a stream comes back online with the same title within this time, no notification is sent.
-# - If a stream comes back online with a different title, a rename notification is sent.
-# - If this time period passes entirely and a stream comes back online after, it's treated as regular going live.
-TEMPORARY_OFFLINE_NOTIFICATION_COOLDOWN = 7 * 60  # 7 minutes in seconds
-
-# Counter thresholds for auto-cleanup (based on 60-second polling intervals)
-CLEANUP_WARNING_THRESHOLD = 83 * 24 * 60  # 119,520 cycles = 83 days
-CLEANUP_DELETE_THRESHOLD = 90 * 24 * 60  # 129,600 cycles = 90 days
-
-# Failure counter threshold for treating stream status as "unknown"
-UNKNOWN_STATUS_THRESHOLD = 15
-
-# Maximum field lengths based on Owncast's configuration
-# Source: https://github.com/owncast/owncast/blob/master/web/utils/config-constants.tsx
-MAX_INSTANCE_TITLE_LENGTH = 255  # Server Name (line 81)
-MAX_STREAM_TITLE_LENGTH = 100  # Stream Title (line 91)
-MAX_TAG_LENGTH = 24  # Per tag (line 208)
-
-
-def should_query_stream(failure_counter: int) -> bool:
-    """
-    Determine if a stream should be queried based on its failure counter.
-    Implements progressive backoff: 60s (5min) -> 2min (5min) -> 3min (5min) -> 5min (15min) -> 15min.
-
-    :param failure_counter: The current failure counter value
-    :return: True if the stream should be queried this cycle, False otherwise
-    """
-    if failure_counter <= 4:
-        # Query every 60s for first 5 minutes (counters 0-4)
-        return True
-    elif failure_counter <= 9:
-        # Query every 2 minutes for next 5 minutes (counters 5-9)
-        return (failure_counter * 60) % 120 == 0
-    elif failure_counter <= 14:
-        # Query every 3 minutes for next 5 minutes (counters 10-14)
-        return (failure_counter * 60) % 180 == 0
-    elif failure_counter <= 29:
-        # Query every 5 minutes for next 15 minutes (counters 15-29)
-        return (failure_counter * 60) % 300 == 0
-    else:
-        # Query every 15 minutes after 30 minutes (counter 30+)
-        return (failure_counter * 60) % 900 == 0
-
-
-def domainify(url: str) -> str:
-    """
-    Extract and sanitize a domain from user input.
-
-    Handles URLs, bare domains, and email-style input (user@domain).
-    Only allows valid domain characters (alphanumeric, hyphens, periods).
-
-    :param url: URL, domain, or email-style string
-    :return: Sanitized domain
-    """
-    # Handle email-style format first (e.g., "notify@stream.logal.dev")
-    if "@" in url:
-        url = url.split("@")[-1]
-
-    # Prepend // if no scheme so urlparse treats input as netloc
-    if not url.startswith(('http://', 'https://', '//')):
-        url = '//' + url
-
-    parsed = urlparse(url)
-    domain = (parsed.netloc or parsed.path).lower()
-
-    # Strip port and path
-    domain = domain.split(':')[0].split('/')[0]
-
-    # Allow only valid domain characters
-    return re.sub(r'[^a-z0-9.-]', '', domain).strip('.-')
-
-
-def truncate(text: str, max_length: int) -> str:
-    """
-    Truncate text to a maximum length.
-
-    :param text: The text to truncate
-    :param max_length: Maximum allowed length
-    :return: Truncated text, or original if within limit
-    """
-    if not text or len(text) <= max_length:
-        return text
-    return text[:max_length]
-
-
-def escape_markdown(text: str) -> str:
-    """
-    Escape Markdown special characters to prevent injection attacks.
-
-    This function sanitizes untrusted external input (like stream names and titles)
-    before embedding them in Markdown-formatted messages. It prevents malicious
-    actors from injecting arbitrary Markdown/HTML content.
-
-    :param text: The text to escape
-    :return: The escaped text safe for Markdown rendering
-    """
-    if not text:
-        return text
-
-    # Escape Markdown special characters by prefixing with backslash
-    # Covers: formatting (*_~`), links ([]()), headings (#), lists (-+),
-    # blockquotes (>), code blocks (```), and other special characters
-    special_chars = {
-        '\\': '\\\\',  # Backslash must be first to avoid double-escaping
-        '*': '\\*',
-        '_': '\\_',
-        '[': '\\[',
-        ']': '\\]',
-        '(': '\\(',
-        ')': '\\)',
-        '~': '\\~',
-        '`': '\\`',
-        '#': '\\#',
-        '+': '\\+',
-        '-': '\\-',
-        '=': '\\=',
-        '|': '\\|',
-        '{': '\\{',
-        '}': '\\}',
-        '.': '\\.',
-        '!': '\\!',
-        '<': '\\<',
-        '>': '\\>',
-        '&': '\\&',
-    }
-
-    escaped_text = text
-    for char, replacement in special_chars.items():
-        escaped_text = escaped_text.replace(char, replacement)
-
-    return escaped_text
-
-
-def sanitize_for_markdown(text: str) -> str:
-    """
-    Sanitize text for safe Markdown rendering.
-
-    Removes newlines, normalizes whitespace, and escapes Markdown special characters.
-    Use this for any untrusted external content before embedding in Markdown messages.
-
-    Note: This function does not truncate. Size limits should be enforced at the
-    model layer (e.g., in from_api_response methods).
-
-    :param text: The text to sanitize
-    :return: Sanitized and escaped text safe for Markdown rendering
-    """
-    if not text:
-        return text
-
-    # Remove newlines and carriage returns to prevent multi-line injection
-    sanitized = text.replace('\n', ' ').replace('\r', ' ')
-
-    # Collapse multiple spaces into single space
-    sanitized = ' '.join(sanitized.split())
-
-    # Escape Markdown special characters
-    sanitized = escape_markdown(sanitized)
-
-    return sanitized

pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "owncastsentry"
+dynamic = ["version"]
+description = "A maubot plugin that monitors Owncast streams and sends Matrix notifications"
+authors = [
+    { name = "Logan Fick" },
+]
+license = "Apache-2.0"
+requires-python = ">=3.14"
+dependencies = ["prometheus_client>=0.25.0"]
+
+[project.urls]
+Repository = "https://git.logal.dev/LogalDeveloper/OwncastSentry"
+
+[build-system]
+requires = ["hatchling>=1.29.0", "hatch-vcs>=0.5.0"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "maubot[encryption]>=0.6.0",
+    "aioresponses>=0.7.8",
+    "codespell>=2.4.2",
+    "hatch>=1.16.5",
+    "mypy>=2.1.0",
+    "pip-audit>=2.10.0",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.13",
+    "time-machine>=3.2.0",
+]
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "owncastsentry/_version.py"
+
+[tool.mypy]
+python_version = "3.14"
+strict = true
+warn_unreachable = true
+explicit_package_bases = true
+# Maubot's pytest helpers are not fully typed, so strict mypy checks on
+# integration tests produce noise around fixture-provided bot/plugin objects.
+exclude = ["tests/"]
+
+[tool.ruff]
+target-version = "py314"
+extend-exclude = ["owncastsentry/_version.py"]  # auto-generated by hatch-vcs
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "ANN401",  # Any is valid at system boundaries; mypy strict handles real issues
+    "C901",    # McCabe complexity: noisy and not actionable
+    "COM812",  # handled by the formatter
+    "D203",    # incompatible with D211 (no blank line before class docstring)
+    "D213",    # incompatible with D212 (summary on first line)
+    "EM",      # exception message style: inline literals are fine
+    "PLR0911", # too many return statements: flat early-returns are clear
+    "PLR0912", # too many branches: inherent in parsers, validators, CLI
+    "PLR0913", # too many arguments: API surfaces and constructors need them
+    "PLR0915", # too many statements: inherent in parsers, validators, CLI
+    "TRY003",  # inline exception messages are fine (complements EM ignore)
+    "TRY301",  # raise inside try: guard clauses don't need helper functions
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "S101",     # assert is standard for pytest
+    "S311",     # pseudo-random generators are fine in tests
+    "SLF001",   # tests legitimately access private members for verification
+    "ARG001",   # unused args are normal for fixtures and handler stubs
+    "PLR2004",  # magic values are clear in test assertions
+]
+
+[tool.coverage.run]
+source = ["owncastsentry"]
+omit = ["owncastsentry/_version.py"]
+
+[tool.coverage.report]
+show_missing = true
+skip_empty = true
+
+[tool.codespell]
+skip = "owncastsentry/_version.py,uv.lock"

tests/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""OwncastSentry test suite."""

tests/conftest.py

@@ -0,0 +1,230 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared test fixtures and stubs for OwncastSentry tests."""
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+import pytest
+from mautrix.util.async_db import Database
+from prometheus_client import generate_latest
+
+from owncastsentry import OwncastSentry
+from owncastsentry.config import Config
+from owncastsentry.repository import (
+    StreamRepository,
+    SubscriptionRepository,
+    get_upgrade_table,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+    from pathlib import Path
+
+    from maubot import Plugin
+    from mautrix.util.async_db import UpgradeTable
+    from mautrix.util.config import BaseProxyConfig
+
+    from owncastsentry.metrics import MetricsService
+    from owncastsentry.types import StreamConfigObservation, StreamStateObservation
+
+
+def generate_metrics_output(metrics: MetricsService) -> str:
+    """Generate Prometheus text format output from a MetricsService registry."""
+    return generate_latest(metrics.registry).decode("utf-8")
+
+
+@pytest.fixture
+async def database(tmp_path: Path) -> AsyncIterator[Database]:
+    """Yield a real SQLite-backed mautrix Database with migrations applied."""
+    db_path = tmp_path / "test.db"
+    db = Database.create(
+        f"sqlite:///{db_path}",
+        upgrade_table=get_upgrade_table(),
+    )
+    await db.start()
+    yield db
+    await db.stop()
+
+
+@pytest.fixture
+def stream_repo(database: Database) -> StreamRepository:
+    """Return a StreamRepository backed by the test database."""
+    return StreamRepository(database)
+
+
+@pytest.fixture
+def subscription_repo(database: Database) -> SubscriptionRepository:
+    """Return a SubscriptionRepository backed by the test database."""
+    return SubscriptionRepository(database)
+
+
+# These fixtures use names expected by the maubot.testing framework.
+# They look unused but are discovered automatically by maubot's pytest plugin.
+
+
+@pytest.fixture
+def maubot_plugin_class() -> type[Plugin]:
+    """Use OwncastSentry as the plugin class for maubot integration tests."""
+    return OwncastSentry
+
+
+@pytest.fixture
+def maubot_plugin_config_class() -> type[BaseProxyConfig]:
+    """Use our Config class for maubot integration tests."""
+    return Config
+
+
+@pytest.fixture
+def maubot_upgrade_table() -> UpgradeTable:
+    """Provide the database upgrade table for maubot integration tests."""
+    return get_upgrade_table()
+
+
+VALID_CONFIG_RESPONSE: dict[str, object] = {
+    "appearanceVariables": {},
+    "name": "LogalDeveloper's Live Stream",
+    "customStyles": "",
+    "streamTitle": "I think I can do this... Let's start a nuclear reaction - Playing Nucleares!",  # noqa: E501
+    "offlineMessage": "<p>HTTP/1.1 204 No Content</p>\n<p>You've reached the right place, but I'm not live right now.</p>",  # noqa: E501
+    "logo": "/logo",
+    "version": "Owncast v0.2.4-linux-64bit (8e89391309dd3aa4d0db4361a2ba1e144f42f8c8)",
+    "extraPageContent": (
+        "<h1>About</h1>\n<p>Hi there! I'm Logan, a cybersecurity professional "
+        "with a background in Linux systems and network administration. This is my "
+        "little corner of the internet where I exclusively run my live streams. While "
+        "gaming is my most common stream topic, I occasionally stream other things "
+        "which interest me, such as cybersecurity challenges. If you are looking for "
+        "my main website, where my blog and project directory is hosted, please visit: "
+        '<a href="https://logal.dev/">https://logal.dev/</a></p>\n<p>Any views and '
+        "opinions expressed in my live streams and videos are my own and do not "
+        "necessarily reflect those of my employer or any affiliated organizations."
+        "</p>\n<h1>Following</h1>\n<p>I don\u2019t stick to a strict streaming "
+        "schedule, but there are a few ways to stay updated so you know when I go "
+        "live:</p>\n<ul>\n<li>\u2b50 <strong>Matrix</strong>: Send the message "
+        "<code>!subscribe stream.logal.dev</code> to "
+        '<a href="https://matrix.to/#/@owncastsentry:logal.dev">'
+        "@owncastsentry:logal.dev</a>.</li>\n<li><strong>Fediverse</strong>: Follow "
+        "<code>@notify@stream.logal.dev</code>.</li>\n</ul>\n<h1>Chat Commands</h1>"
+        "\n<p>To make things more interactive, there are several commands you can "
+        "send in chat to play sound effects live on stream:</p>\n<ul>\n"
+        "<li>!boom</li>\n<li>!bluetooth</li>\n<li>!bruh</li>\n<li>!creeper</li>\n"
+        "<li>!directed</li>\n<li>!fart</li>\n<li>!icetea</li>\n<li>!oof</li>\n"
+        "<li>!perfect</li>\n<li>!spare</li>\n<li>!thatsit</li>\n<li>!usb</li>\n"
+        "<li>!whocares</li>\n<li>!yoda</li>\n</ul>"
+    ),
+    "summary": "Video games, cybersecurity, and more!",
+    "tags": [
+        "video games",
+        "chatting",
+        "casual",
+        "english",
+        "streaming",
+        "owncast",
+        "variety",
+    ],
+    "socialHandles": None,
+    "externalActions": [
+        {
+            "url": "https://ko-fi.com/logaldeveloper",
+            "html": "",
+            "title": "Tip",
+            "description": "",
+            "icon": "https://stream.logal.dev/img/platformlogos/ko-fi.svg",
+            "color": "",
+            "openExternally": True,
+        },
+        {
+            "url": "https://tubefree.org/c/logaldeveloper_stream_archive",
+            "html": "",
+            "title": "Previous Live Stream Recordings",
+            "description": "",
+            "icon": "https://stream.logal.dev/img/platformlogos/fediverse.svg",
+            "color": "",
+            "openExternally": True,
+        },
+    ],
+    "notifications": {
+        "browser": {
+            "publicKey": "BI9BhIY6c7nfP6ZSIu7T53Lta5sGYqDqwSpiCabZ0XQxPQOmnUHRSjInaa3HX9XmYE-bV8SFmbFk4stZy2jnJ3M",  # noqa: E501
+            "enabled": True,
+        },
+    },
+    "federation": {
+        "account": "notify@stream.logal.dev",
+        "followerCount": 74,
+        "enabled": True,
+    },
+    "maxSocketPayloadSize": 2048,
+    "hideViewerCount": False,
+    "chatDisabled": False,
+    "chatSpamProtectionDisabled": False,
+    "nsfw": False,
+    "authentication": {"indieAuthEnabled": True},
+}
+
+VALID_STATUS_RESPONSE: dict[str, object] = {
+    "serverTime": "2026-03-13T15:16:14.354962696-04:00",
+    "lastConnectTime": None,
+    "lastDisconnectTime": "2026-03-04T21:05:32-05:00",
+    "versionNumber": "0.2.4",
+    "streamTitle": "I think I can do this... Let's start a nuclear reaction - Playing Nucleares!",  # noqa: E501
+    "online": False,
+}
+
+
+@dataclass
+class _SentMessage:
+    """A message recorded by _StubMatrixClient."""
+
+    room_id: str
+    content: Any
+
+
+class _StubMatrixClient:
+    """Recording stub for the Matrix client used in notification tests."""
+
+    def __init__(self) -> None:
+        self.sent_messages: list[_SentMessage] = []
+        self.should_fail_for_rooms: set[str] = set()
+
+    async def send_message(self, room_id: str, content: Any) -> None:
+        """Record a sent message, or raise if room is in the fail set."""
+        if room_id in self.should_fail_for_rooms:
+            msg = f"Stubbed failure for room {room_id}"
+            raise RuntimeError(msg)
+        self.sent_messages.append(_SentMessage(room_id=room_id, content=content))
+
+
+@dataclass
+class _StubOwncastClient:
+    """Configurable stub for the Owncast HTTP client."""
+
+    stream_state: StreamStateObservation | None = None
+    stream_config: StreamConfigObservation | None = None
+    state_call_count: int = field(default=0, init=False)
+    config_call_count: int = field(default=0, init=False)
+    queried_domains: list[str] = field(default_factory=list, init=False)
+
+    async def get_stream_state(self, domain: str) -> StreamStateObservation | None:
+        """Return the configured stream observation."""
+        self.state_call_count += 1
+        self.queried_domains.append(domain)
+        return self.stream_state
+
+    async def get_stream_config(self, _domain: str) -> StreamConfigObservation | None:
+        """Return the configured stream config."""
+        self.config_call_count += 1
+        return self.stream_config

tests/test_commands.py

@@ -0,0 +1,581 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for bot command handlers."""
+
+import json
+from datetime import UTC, datetime, timedelta
+from typing import TYPE_CHECKING
+
+import pytest
+import time_machine
+from aioresponses import aioresponses
+
+from owncastsentry.commands import (
+    _SECONDS_PER_DAY,
+    _SECONDS_PER_HOUR,
+    _SECONDS_PER_MINUTE,
+    _escape_markdown,
+    _format_duration,
+    _sanitize_for_markdown,
+)
+from owncastsentry.owncast_client import _OWNCAST_STATUS_PATH
+from owncastsentry.types import UNKNOWN_STATUS_THRESHOLD
+from tests.conftest import VALID_STATUS_RESPONSE
+
+if TYPE_CHECKING:
+    from maubot.testing.bot import TestBot
+
+    from owncastsentry import OwncastSentry
+
+
+class TestEscapeMarkdown:
+    """Markdown special character escaping."""
+
+    @pytest.mark.parametrize(
+        ("input_text", "expected"),
+        [
+            pytest.param("hello", "hello", id="plain-text-unchanged"),
+            pytest.param("*bold*", "\\*bold\\*", id="asterisks"),
+            pytest.param("_italic_", "\\_italic\\_", id="underscores"),
+            pytest.param("[link](url)", "\\[link\\]\\(url\\)", id="link-syntax"),
+            pytest.param("`code`", "\\`code\\`", id="backticks"),
+            pytest.param("# heading", "\\# heading", id="heading"),
+            pytest.param("> quote", "\\> quote", id="blockquote"),
+            pytest.param("<html>", "\\<html\\>", id="angle-brackets"),
+            pytest.param("a & b", "a \\& b", id="ampersand"),
+            pytest.param("a\\b", "a\\\\b", id="backslash"),
+            pytest.param("", "", id="empty-string"),
+        ],
+    )
+    def test_escapes_special_chars(self, input_text: str, expected: str) -> None:
+        """Escape Markdown special characters in input text."""
+        assert _escape_markdown(input_text) == expected
+
+
+class TestSanitizeForMarkdown:
+    """Markdown sanitization combining whitespace normalization and escaping."""
+
+    def test_removes_newlines_and_escapes(self) -> None:
+        """Normalize newlines and escape Markdown special characters."""
+        result = _sanitize_for_markdown("*bold*\nnew line")
+        assert result == "\\*bold\\* new line"
+
+    def test_empty_string(self) -> None:
+        """Return empty string unchanged."""
+        assert _sanitize_for_markdown("") == ""
+
+
+class TestFormatDuration:
+    """Elapsed time calculation from ISO timestamps."""
+
+    _NOW = datetime(2026, 3, 13, 12, 0, 0, tzinfo=UTC)
+
+    @pytest.mark.parametrize(
+        ("seconds_ago", "expected"),
+        [
+            pytest.param(1, "1 second", id="singular-second"),
+            pytest.param(30, "30 seconds", id="plural-seconds"),
+            pytest.param(_SECONDS_PER_MINUTE, "1 minute", id="singular-minute"),
+            pytest.param(2 * _SECONDS_PER_MINUTE, "2 minutes", id="plural-minutes"),
+            pytest.param(_SECONDS_PER_HOUR, "1 hour", id="singular-hour"),
+            pytest.param(2 * _SECONDS_PER_HOUR, "2 hours", id="plural-hours"),
+            pytest.param(_SECONDS_PER_DAY, "1 day", id="singular-day"),
+            pytest.param(2 * _SECONDS_PER_DAY, "2 days", id="plural-days"),
+        ],
+    )
+    def test_formats_duration(self, seconds_ago: int, expected: str) -> None:
+        """Format a timestamp into a human-readable duration."""
+        timestamp = (self._NOW - timedelta(seconds=seconds_ago)).isoformat()
+        result = _format_duration(timestamp, self._NOW)
+        assert result == expected
+
+    def test_invalid_timestamp(self) -> None:
+        """Return 'unknown duration' for unparsable timestamps."""
+        assert _format_duration("not-a-timestamp", self._NOW) == "unknown duration"
+
+    def test_naive_timestamp(self) -> None:
+        """Return 'unknown duration' for timestamps without timezone information."""
+        assert _format_duration("2026-03-13T11:59:00", self._NOW) == "unknown duration"
+
+    def test_future_timestamp(self) -> None:
+        """Return 'unknown duration' for timestamps in the future."""
+        timestamp = (self._NOW + timedelta(seconds=1)).isoformat()
+        assert _format_duration(timestamp, self._NOW) == "unknown duration"
+
+
+@pytest.mark.usefixtures("maubot_plugin")
+class TestSubscribeCommand:
+    """Subscribe command end-to-end via maubot."""
+
+    async def test_subscribe_valid_stream(self, maubot_test_bot: TestBot) -> None:
+        """Subscribe to a valid Owncast stream."""
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        assert len(maubot_test_bot.responded) == 1
+        assert maubot_test_bot.responded[0].content.body == (
+            "Subscription added! This room will receive notifications when "
+            "stream.logal.dev goes live."
+        )
+
+    async def test_subscribe_invalid_stream(self, maubot_test_bot: TestBot) -> None:
+        """Reject subscription to an invalid Owncast instance."""
+        status_url = f"https://invalid.com{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(status_url, status=404)
+            await maubot_test_bot.send("!subscribe invalid.com")
+
+        assert len(maubot_test_bot.responded) == 1
+        assert maubot_test_bot.responded[0].content.body == (
+            "The URL you supplied does not appear to "
+            "be a valid Owncast instance. You may have "
+            "specified an invalid domain, or the "
+            "instance is offline."
+        )
+
+    async def test_subscribe_already_subscribed(self, maubot_test_bot: TestBot) -> None:
+        """Reject duplicate subscription in the same room."""
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        # Second subscribe; stream already exists so validation is skipped
+        await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        assert len(maubot_test_bot.responded) == 2
+        assert maubot_test_bot.responded[1].content.body == (
+            "This room is already subscribed to notifications for stream.logal.dev."
+        )
+
+    async def test_subscribe_existing_stream_new_room(
+        self, maubot_test_bot: TestBot
+    ) -> None:
+        """Skip validation when the domain already has subscriptions."""
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        # Subscribe from a different room. The existing subscribed domain skips
+        # validation, so an empty aioresponses context will raise ConnectionError
+        # if any HTTP request is attempted.
+        with aioresponses():
+            await maubot_test_bot.send(
+                "!subscribe stream.logal.dev", room_id="!otherroom:example.com"
+            )
+
+        assert len(maubot_test_bot.responded) == 2
+        assert maubot_test_bot.responded[1].content.body == (
+            "Subscription added! This room will receive notifications when "
+            "stream.logal.dev goes live."
+        )
+
+
+@pytest.mark.usefixtures("maubot_plugin")
+class TestUnsubscribeCommand:
+    """Unsubscribe command end-to-end via maubot."""
+
+    async def test_unsubscribe_existing(self, maubot_test_bot: TestBot) -> None:
+        """Unsubscribe from a subscribed stream."""
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        await maubot_test_bot.send("!unsubscribe stream.logal.dev")
+
+        assert len(maubot_test_bot.responded) == 2
+        assert maubot_test_bot.responded[1].content.body == (
+            "Subscription removed! This room will no "
+            "longer receive notifications for stream.logal.dev."
+        )
+
+    async def test_unsubscribe_not_subscribed(self, maubot_test_bot: TestBot) -> None:
+        """Reject unsubscribe from a non-subscribed stream."""
+        await maubot_test_bot.send("!unsubscribe unknown.com")
+
+        assert len(maubot_test_bot.responded) == 1
+        assert maubot_test_bot.responded[0].content.body == (
+            "This room is already not subscribed to notifications for unknown.com."
+        )
+
+
+@pytest.mark.usefixtures("maubot_plugin")
+class TestSubscriptionsCommand:
+    """Subscriptions listing command end-to-end via maubot."""
+
+    async def test_no_subscriptions(self, maubot_test_bot: TestBot) -> None:
+        """Show help text when no subscriptions exist."""
+        await maubot_test_bot.send("!subscriptions")
+
+        assert len(maubot_test_bot.responded) == 1
+        assert maubot_test_bot.responded[0].content.body == (
+            "This room is not subscribed to any Owncast "
+            "instances.\n\nTo subscribe to an Owncast "
+            "instance, use `!subscribe <domain>`"
+        )
+
+    @time_machine.travel(datetime(2026, 3, 13, 12, 0, 0, tzinfo=UTC))
+    async def test_shows_online_stream(
+        self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
+    ) -> None:
+        """Show stream details including title and duration."""
+        # Subscribe first
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        # Update stream state to be online with a name
+        await maubot_plugin.stream_repo.update(
+            "stream.logal.dev",
+            name="Test Stream",
+            title="Playing Games",
+            online=True,
+            status_since="2026-01-01T12:00:00+00:00",
+        )
+
+        await maubot_test_bot.send("!subscriptions")
+
+        assert len(maubot_test_bot.responded) == 2
+        assert maubot_test_bot.responded[1].content.body == (
+            "**Subscriptions for this room (1):**\n\n"
+            "● **Test Stream** \n"
+            "  ○ Title: Playing Games\n"
+            "  ○ Status: Online for 71 days\n"
+            "  ○ Link: https://stream.logal.dev\n"
+            "To unsubscribe from any of these Owncast "
+            "instances, use `!unsubscribe <domain>`"
+        )
+
+    @time_machine.travel(datetime(2026, 3, 13, 12, 0, 0, tzinfo=UTC))
+    async def test_escapes_markdown_in_stream_name_and_title(
+        self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
+    ) -> None:
+        """Render stream name and title as literal text in command output."""
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        await maubot_plugin.stream_repo.update(
+            "stream.logal.dev",
+            name="*Bold* [link](https://evil.example)\nName",
+            title="`code` > quote #tag",
+            online=True,
+            status_since="2026-01-01T12:00:00+00:00",
+        )
+
+        await maubot_test_bot.send("!subscriptions")
+
+        content = maubot_test_bot.responded[1].content
+        assert "● ***Bold* [link](https://evil.example) Name**" in content.body
+        assert "  ○ Title: `code` > quote #tag" in content.body
+        assert content.formatted_body is not None
+        assert '<a href="https://evil.example">' not in content.formatted_body
+        assert (
+            "<strong>*Bold* [link](https://evil.example) Name</strong>"
+            in content.formatted_body
+        )
+        assert "Title: `code` &gt; quote #tag" in content.formatted_body
+
+    @time_machine.travel(datetime(2026, 3, 13, 12, 0, 0, tzinfo=UTC))
+    async def test_shows_offline_stream(
+        self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
+    ) -> None:
+        """Show offline status for non-live streams."""
+        # Subscribe first
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        # Update stream state to be offline
+        await maubot_plugin.stream_repo.update(
+            "stream.logal.dev",
+            name="Test Stream",
+            status_since="2026-01-01T10:00:00+00:00",
+        )
+
+        await maubot_test_bot.send("!subscriptions")
+
+        assert len(maubot_test_bot.responded) == 2
+        assert maubot_test_bot.responded[1].content.body == (
+            "**Subscriptions for this room (1):**\n\n"
+            "● **Test Stream** \n"
+            "  ○ Status: Offline for 71 days\n"
+            "  ○ Link: https://stream.logal.dev\n"
+            "To unsubscribe from any of these Owncast "
+            "instances, use `!unsubscribe <domain>`"
+        )
+
+    async def test_shows_offline_stream_without_disconnect_time(
+        self, maubot_test_bot: TestBot
+    ) -> None:
+        """Show offline status without duration before first poll completes."""
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        # Stream row exists with no state yet - query subscriptions immediately
+        await maubot_test_bot.send("!subscriptions")
+
+        assert len(maubot_test_bot.responded) == 2
+        assert maubot_test_bot.responded[1].content.body == (
+            "**Subscriptions for this room (1):**\n\n"
+            "● **stream.logal.dev** \n"
+            "  ○ Status: Offline\n"
+            "  ○ Link: https://stream.logal.dev\n"
+            "To unsubscribe from any of these Owncast "
+            "instances, use `!unsubscribe <domain>`"
+        )
+
+    async def test_shows_unknown_stream(
+        self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
+    ) -> None:
+        """Show unknown status when instance has been unreachable."""
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        # Increment failure counter past the unknown threshold
+        for _ in range(UNKNOWN_STATUS_THRESHOLD + 1):
+            await maubot_plugin.stream_repo.increment_failure_counter(
+                "stream.logal.dev"
+            )
+
+        await maubot_test_bot.send("!subscriptions")
+
+        assert len(maubot_test_bot.responded) == 2
+        assert maubot_test_bot.responded[1].content.body == (
+            "**Subscriptions for this room (1):**\n\n"
+            "● **stream.logal.dev** \n"
+            "  ○ Status: Unknown (instance unreachable)\n"
+            "  ○ Link: https://stream.logal.dev\n"
+            "To unsubscribe from any of these Owncast "
+            "instances, use `!unsubscribe <domain>`"
+        )
+
+    @time_machine.travel(datetime(2026, 3, 13, 12, 0, 0, tzinfo=UTC))
+    async def test_shows_multiple_subscriptions(
+        self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
+    ) -> None:
+        """List subscriptions ordered by domain with mixed statuses."""
+        # Subscribe in reverse domain order to verify domain-sorted output
+        with aioresponses() as mocked:
+            mocked.get(
+                f"https://beta.com{_OWNCAST_STATUS_PATH}",
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            mocked.get(
+                f"https://alpha.com{_OWNCAST_STATUS_PATH}",
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe beta.com")
+            await maubot_test_bot.send("!subscribe alpha.com")
+
+        # Set alpha online, beta offline
+        await maubot_plugin.stream_repo.update(
+            "alpha.com",
+            name="Alpha Stream",
+            title="Streaming Live",
+            online=True,
+            status_since="2026-03-13T10:00:00+00:00",
+        )
+        await maubot_plugin.stream_repo.update(
+            "beta.com",
+            name="Beta Stream",
+            status_since="2026-03-12T18:00:00+00:00",
+        )
+
+        await maubot_test_bot.send("!subscriptions")
+
+        assert len(maubot_test_bot.responded) == 3
+        assert maubot_test_bot.responded[2].content.body == (
+            "**Subscriptions for this room (2):**\n\n"
+            "● **Alpha Stream**\n"
+            "  \n"
+            "  ○ Title: Streaming Live\n"
+            "  ○ Status: Online for 2 hours\n"
+            "  ○ Link: https://alpha.com\n"
+            "● **Beta Stream**\n"
+            "  \n"
+            "  ○ Status: Offline for 18 hours\n"
+            "  ○ Link: https://beta.com\n"
+            "To unsubscribe from any of these Owncast "
+            "instances, use `!unsubscribe <domain>`"
+        )
+
+
+@pytest.mark.usefixtures("maubot_plugin")
+class TestLiveCommand:
+    """Live streams listing command end-to-end via maubot."""
+
+    async def test_no_subscriptions(self, maubot_test_bot: TestBot) -> None:
+        """Show help text when no subscriptions exist."""
+        await maubot_test_bot.send("!live")
+
+        assert len(maubot_test_bot.responded) == 1
+        assert maubot_test_bot.responded[0].content.body == (
+            "This room is not subscribed to any Owncast "
+            "instances.\n\nTo subscribe to an Owncast "
+            "instance, use `!subscribe <domain>`"
+        )
+
+    async def test_no_live_streams(
+        self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
+    ) -> None:
+        """Show 'no live' message when all streams are offline."""
+        # Subscribe first
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        # Update stream state to offline
+        await maubot_plugin.stream_repo.update(
+            "stream.logal.dev",
+            name="Test Stream",
+            status_since="2026-01-01T10:00:00+00:00",
+        )
+
+        await maubot_test_bot.send("!live")
+
+        assert len(maubot_test_bot.responded) == 2
+        assert maubot_test_bot.responded[1].content.body == (
+            "No subscribed Owncast instances are currently "
+            "live.\n\nUse `!subscriptions` to list all "
+            "subscriptions."
+        )
+
+    @time_machine.travel(datetime(2026, 3, 13, 12, 0, 0, tzinfo=UTC))
+    async def test_shows_live_stream(
+        self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
+    ) -> None:
+        """Show live stream with title and duration."""
+        # Subscribe first
+        status_url = f"https://stream.logal.dev{_OWNCAST_STATUS_PATH}"
+        with aioresponses() as mocked:
+            mocked.get(
+                status_url,
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe stream.logal.dev")
+
+        # Update stream state to online
+        await maubot_plugin.stream_repo.update(
+            "stream.logal.dev",
+            name="Test Stream",
+            title="Playing Games",
+            online=True,
+            status_since="2026-01-01T12:00:00+00:00",
+        )
+
+        await maubot_test_bot.send("!live")
+
+        assert len(maubot_test_bot.responded) == 2
+        assert maubot_test_bot.responded[1].content.body == (
+            "**Live Owncast instances (1):**\n\n"
+            "● **Test Stream** \n"
+            "  ○ Title: Playing Games\n"
+            "  ○ Online for 71 days\n"
+            "  ○ Link: https://stream.logal.dev"
+        )
+
+    @time_machine.travel(datetime(2026, 3, 13, 12, 0, 0, tzinfo=UTC))
+    async def test_shows_multiple_live_streams(
+        self, maubot_test_bot: TestBot, maubot_plugin: OwncastSentry
+    ) -> None:
+        """List live streams ordered by domain with different durations."""
+        # Subscribe in reverse domain order to verify domain-sorted output
+        with aioresponses() as mocked:
+            mocked.get(
+                f"https://beta.com{_OWNCAST_STATUS_PATH}",
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            mocked.get(
+                f"https://alpha.com{_OWNCAST_STATUS_PATH}",
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            await maubot_test_bot.send("!subscribe beta.com")
+            await maubot_test_bot.send("!subscribe alpha.com")
+
+        # Set both streams online with different status timestamps
+        await maubot_plugin.stream_repo.update(
+            "alpha.com",
+            name="Alpha Stream",
+            title="Morning Show",
+            online=True,
+            status_since="2026-03-13T10:00:00+00:00",
+        )
+        await maubot_plugin.stream_repo.update(
+            "beta.com",
+            name="Beta Stream",
+            title="Evening Vibes",
+            online=True,
+            status_since="2026-03-13T06:00:00+00:00",
+        )
+
+        await maubot_test_bot.send("!live")
+
+        assert len(maubot_test_bot.responded) == 3
+        assert maubot_test_bot.responded[2].content.body == (
+            "**Live Owncast instances (2):**\n\n"
+            "● **Alpha Stream**\n"
+            "  \n"
+            "  ○ Title: Morning Show\n"
+            "  ○ Online for 2 hours\n"
+            "  ○ Link: https://alpha.com\n"
+            "● **Beta Stream**\n"
+            "  \n"
+            "  ○ Title: Evening Vibes\n"
+            "  ○ Online for 6 hours\n"
+            "  ○ Link: https://beta.com"
+        )

tests/test_metrics.py

@@ -0,0 +1,314 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for the Prometheus metrics service."""
+
+import pytest
+
+from owncastsentry.metrics import ErrorSource, MetricsService, NotificationType
+from owncastsentry.types import StreamStatus
+from tests.conftest import generate_metrics_output
+
+
+class TestRecordDelivery:
+    """Notification delivery counter with type and result labels."""
+
+    @pytest.mark.parametrize(
+        ("notification_type", "successful", "failed", "expected_fragments"),
+        [
+            pytest.param(
+                NotificationType.LIVE,
+                3,
+                0,
+                ['result="success",type="live"} 3.0'],
+                id="live-success",
+            ),
+            pytest.param(
+                NotificationType.LIVE,
+                0,
+                2,
+                ['result="failure",type="live"} 2.0'],
+                id="live-failure",
+            ),
+            pytest.param(
+                NotificationType.TITLE_CHANGE,
+                1,
+                0,
+                ['result="success",type="title_change"} 1.0'],
+                id="title-change-success",
+            ),
+            pytest.param(
+                NotificationType.CLEANUP_WARNING,
+                2,
+                0,
+                ['result="success",type="cleanup_warning"} 2.0'],
+                id="cleanup-warning-success",
+            ),
+            pytest.param(
+                NotificationType.CLEANUP_DELETION,
+                1,
+                1,
+                [
+                    'result="success",type="cleanup_deletion"} 1.0',
+                    'result="failure",type="cleanup_deletion"} 1.0',
+                ],
+                id="cleanup-deletion-mixed",
+            ),
+        ],
+    )
+    def test_records_delivery(
+        self,
+        notification_type: NotificationType,
+        successful: int,
+        failed: int,
+        expected_fragments: list[str],
+    ) -> None:
+        """Record delivery results with correct type and result labels."""
+        service = MetricsService()
+        service.record_delivery(notification_type, successful=successful, failed=failed)
+        output = generate_metrics_output(service)
+        for fragment in expected_fragments:
+            assert fragment in output
+
+    @pytest.mark.parametrize(
+        ("notification_type", "result"),
+        [
+            pytest.param(t, r, id=f"{t}-{r}")
+            for t in NotificationType
+            for r in ("success", "failure")
+        ],
+    )
+    def test_all_combinations_initialized(
+        self, notification_type: NotificationType, result: str
+    ) -> None:
+        """All type/result label combinations exist at zero on init."""
+        service = MetricsService()
+        output = generate_metrics_output(service)
+        expected = (
+            f"owncastsentry_notification_delivery_total"
+            f'{{result="{result}",type="{notification_type}"}} 0.0'
+        )
+        assert expected in output
+
+
+class TestSetStreamStatus:
+    """Per-stream status gauge."""
+
+    @pytest.mark.parametrize(
+        ("status", "expected_value"),
+        [
+            pytest.param(StreamStatus.ONLINE, 1.0, id="online"),
+            pytest.param(StreamStatus.OFFLINE, 0.0, id="offline"),
+            pytest.param(StreamStatus.UNKNOWN, -1.0, id="unknown"),
+        ],
+    )
+    def test_sets_status(self, status: StreamStatus, expected_value: float) -> None:
+        """Set gauge to the correct value for each stream status."""
+        service = MetricsService()
+        service.set_stream_status("test.com", status)
+        output = generate_metrics_output(service)
+        expected = f'owncastsentry_stream_status{{domain="test.com"}} {expected_value}'
+        assert expected in output
+
+
+class TestSetSubscriptionCount:
+    """Per-stream subscription count gauge."""
+
+    def test_sets_count(self) -> None:
+        """Set the subscription count for a domain."""
+        service = MetricsService()
+        service.set_subscription_count("test.com", 5)
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_stream_subscriptions{domain="test.com"} 5.0' in output
+
+    def test_updates_count(self) -> None:
+        """Update the subscription count for a domain."""
+        service = MetricsService()
+        service.set_subscription_count("test.com", 5)
+        service.set_subscription_count("test.com", 3)
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_stream_subscriptions{domain="test.com"} 3.0' in output
+
+
+class TestSetCheckFailures:
+    """Consecutive check failure gauge per domain."""
+
+    def test_sets_count(self) -> None:
+        """Set the failure count for a domain."""
+        service = MetricsService()
+        service.set_check_failures("fail.com", 3)
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_check_failures{domain="fail.com"} 3.0' in output
+
+    def test_resets_to_zero(self) -> None:
+        """Reset the failure count to zero."""
+        service = MetricsService()
+        service.set_check_failures("fail.com", 5)
+        service.set_check_failures("fail.com", 0)
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_check_failures{domain="fail.com"} 0.0' in output
+
+
+class TestResponseTimer:
+    """Response time gauge via context manager."""
+
+    def test_records_on_success(self) -> None:
+        """Record a response time when success() is called."""
+        service = MetricsService()
+        with service.response_timer("example.com") as timer:
+            timer.success()
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_api_response_seconds{domain="example.com"}' in output
+
+    def test_does_not_record_without_success(self) -> None:
+        """Do not record when success() is never called."""
+        service = MetricsService()
+        with service.response_timer("example.com"):
+            pass
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_api_response_seconds{domain="example.com"}' not in output
+
+    def test_overwrites_previous_value(self) -> None:
+        """Overwrite previous value with the latest response time."""
+        service = MetricsService()
+        with service.response_timer("example.com") as timer:
+            timer.success()
+        with service.response_timer("example.com") as timer:
+            timer.success()
+        output = generate_metrics_output(service)
+        # Gauge should have exactly one line for this domain, not accumulated
+        matches = [
+            line
+            for line in output.splitlines()
+            if line.startswith("owncastsentry_api_response_seconds{")
+        ]
+        assert len(matches) == 1
+
+    def test_does_not_record_on_exception(self) -> None:
+        """Do not record when the block raises before success() is called."""
+        service = MetricsService()
+        with (
+            pytest.raises(ValueError, match="boom"),
+            service.response_timer("example.com"),
+        ):
+            raise ValueError("boom")
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_api_response_seconds{domain="example.com"}' not in output
+
+
+class TestRemoveStream:
+    """Stale stream label cleanup."""
+
+    def test_removes_stream_label(self) -> None:
+        """Remove a stream's gauge labels after cleanup deletion."""
+        service = MetricsService()
+        service.set_stream_status("gone.com", StreamStatus.OFFLINE)
+        service.set_subscription_count("gone.com", 2)
+        assert 'domain="gone.com"' in generate_metrics_output(service)
+        service.remove_stream("gone.com")
+        assert 'domain="gone.com"' not in generate_metrics_output(service)
+
+    def test_remove_nonexistent_is_noop(self) -> None:
+        """Removing a nonexistent stream does not raise."""
+        service = MetricsService()
+        service.remove_stream("never.com")
+
+
+class TestRegisterOpenConnectionsGauge:
+    """Callback-based open connection gauge."""
+
+    def test_reads_value_from_callback(self) -> None:
+        """Read the open connection count from the callback at scrape time."""
+        service = MetricsService()
+        counter = [3]
+        service.register_open_connections_gauge(lambda: counter[0])
+        output = generate_metrics_output(service)
+        assert "owncastsentry_http_connections_open 3.0" in output
+
+    def test_reflects_updated_value(self) -> None:
+        """Reflect changes in the callback value on subsequent scrapes."""
+        service = MetricsService()
+        counter = [1]
+        service.register_open_connections_gauge(lambda: counter[0])
+        counter[0] = 5
+        output = generate_metrics_output(service)
+        assert "owncastsentry_http_connections_open 5.0" in output
+
+
+class TestSetBuildInfo:
+    """Build version info metric."""
+
+    def test_sets_version(self) -> None:
+        """Set the build version info."""
+        service = MetricsService()
+        service.set_build_info("1.2.3")
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_info{version="1.2.3"} 1.0' in output
+
+
+class TestRecordError:
+    """Internal error counter."""
+
+    def test_increments_counter(self) -> None:
+        """Increment the error counter for a source."""
+        service = MetricsService()
+        service.record_error(ErrorSource.SCHEDULER_LOOP)
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_errors_total{source="scheduler_loop"} 1.0' in output
+
+    def test_increments_multiple_sources(self) -> None:
+        """Increment error counters for different sources independently."""
+        service = MetricsService()
+        service.record_error(ErrorSource.SCHEDULER_LOOP)
+        service.record_error(ErrorSource.COMMAND)
+        service.record_error(ErrorSource.COMMAND)
+        output = generate_metrics_output(service)
+        assert 'owncastsentry_errors_total{source="scheduler_loop"} 1.0' in output
+        assert 'owncastsentry_errors_total{source="command"} 2.0' in output
+
+    @pytest.mark.parametrize(
+        "source",
+        [pytest.param(s, id=s) for s in ErrorSource],
+    )
+    def test_all_sources_initialized(self, source: ErrorSource) -> None:
+        """All known source labels exist at zero on init."""
+        service = MetricsService()
+        output = generate_metrics_output(service)
+        expected = f'owncastsentry_errors_total{{source="{source}"}} 0.0'
+        assert expected in output
+
+
+class TestRegistryOutput:
+    """Prometheus registry output."""
+
+    def test_returns_string(self) -> None:
+        """Return a string (not bytes)."""
+        service = MetricsService()
+        output = generate_metrics_output(service)
+        assert isinstance(output, str)
+
+    def test_contains_help_lines(self) -> None:
+        """Include HELP lines for registered metrics."""
+        service = MetricsService()
+        output = generate_metrics_output(service)
+        assert "# HELP owncastsentry_notification_delivery_total" in output
+        assert "# HELP owncastsentry_errors_total" in output
+        assert "# HELP owncastsentry_info" in output
+
+    def test_uses_isolated_registry(self) -> None:
+        """Use a custom registry, not the global default."""
+        service = MetricsService()
+        output = generate_metrics_output(service)
+        assert "python_gc" not in output
+        assert "process_" not in output

tests/test_notification_service.py

@@ -0,0 +1,582 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for the notification service."""
+
+import asyncio
+import logging
+import time
+from typing import TYPE_CHECKING
+
+import pytest
+
+from owncastsentry.metrics import MetricsService
+from owncastsentry.notification_service import (
+    _SECONDS_BETWEEN_NOTIFICATIONS,
+    NotificationService,
+    _sanitize_for_plain_text,
+)
+from tests.conftest import _StubMatrixClient, generate_metrics_output
+
+if TYPE_CHECKING:
+    from owncastsentry.repository import StreamRepository, SubscriptionRepository
+
+
+def _make_service(
+    *,
+    client: _StubMatrixClient,
+    subscription_repo: SubscriptionRepository,
+    metrics: MetricsService | None = None,
+) -> NotificationService:
+    """Build a NotificationService with a stub client and real repo."""
+    return NotificationService(
+        client=client,
+        subscription_repo=subscription_repo,
+        logger=logging.getLogger("test"),
+        metrics=metrics or MetricsService(),
+    )
+
+
+class TestSanitizeForPlainText:
+    """Plain text sanitization for notifications."""
+
+    @pytest.mark.parametrize(
+        ("input_text", "expected"),
+        [
+            pytest.param("hello world", "hello world", id="plain-text"),
+            pytest.param("line1\nline2", "line1 line2", id="newline-removed"),
+            pytest.param("line1\rline2", "line1 line2", id="carriage-return"),
+            pytest.param("line1\r\nline2", "line1 line2", id="crlf-removed"),
+            pytest.param(
+                "too   many   spaces", "too many spaces", id="spaces-collapsed"
+            ),
+            pytest.param("", "", id="empty-string"),
+        ],
+    )
+    def test_sanitizes(self, input_text: str, expected: str) -> None:
+        """Sanitize the text for safe plain-text rendering."""
+        assert _sanitize_for_plain_text(input_text) == expected
+
+
+class TestCanNotify:
+    """Rate-limiting logic for notification cooldowns."""
+
+    def test_first_notification_allowed(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Allow the first notification for an unseen domain."""
+        service = _make_service(
+            client=_StubMatrixClient(), subscription_repo=subscription_repo
+        )
+        assert service._can_notify("example.com") is True
+
+    def test_within_cooldown_blocked(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Block notifications within the cooldown window."""
+        service = _make_service(
+            client=_StubMatrixClient(), subscription_repo=subscription_repo
+        )
+        service.notification_timers_cache["example.com"] = time.monotonic()
+        assert service._can_notify("example.com") is False
+
+    def test_after_cooldown_allowed(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Allow notifications after the cooldown window expires."""
+        service = _make_service(
+            client=_StubMatrixClient(), subscription_repo=subscription_repo
+        )
+        # Subtract an extra second to ensure the cooldown has fully elapsed
+        service.notification_timers_cache["example.com"] = (
+            time.monotonic() - _SECONDS_BETWEEN_NOTIFICATIONS - 1
+        )
+        assert service._can_notify("example.com") is True
+
+
+class TestGetLastNotificationTime:
+    """Last notification timestamp retrieval."""
+
+    def test_returns_cached_value(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return the cached timestamp for a known domain."""
+        service = _make_service(
+            client=_StubMatrixClient(), subscription_repo=subscription_repo
+        )
+        service.notification_timers_cache["example.com"] = 12345.0
+        assert service.get_last_notification_time("example.com") == 12345.0
+
+    def test_returns_zero_for_unknown(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return 0 for a domain that has never been notified."""
+        service = _make_service(
+            client=_StubMatrixClient(), subscription_repo=subscription_repo
+        )
+        assert service.get_last_notification_time("unknown.com") == 0
+
+
+class TestClearNotificationState:
+    """Notification cache cleanup for deleted domains."""
+
+    def test_clears_cached_notification_time(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Remove cached notification state for a domain."""
+        service = _make_service(
+            client=_StubMatrixClient(), subscription_repo=subscription_repo
+        )
+        service.notification_timers_cache["example.com"] = 12345.0
+
+        service.clear_notification_state("example.com")
+
+        assert service.get_last_notification_time("example.com") == 0
+
+    def test_missing_domain_is_ignored(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Ignore cleanup for a domain with no cached state."""
+        service = _make_service(
+            client=_StubMatrixClient(), subscription_repo=subscription_repo
+        )
+
+        service.clear_notification_state("unknown.com")
+
+        assert service.get_last_notification_time("unknown.com") == 0
+
+
+class TestFormatMessage:
+    """Notification message formatting."""
+
+    @pytest.mark.parametrize(
+        ("name", "title", "domain", "tags", "title_change", "expected"),
+        [
+            pytest.param(
+                "My Stream",
+                "Playing Games",
+                "example.com",
+                [],
+                False,
+                "🎥 My Stream is now live!\n"
+                "Stream Title: Playing Games\n"
+                "\n"
+                "To tune in, visit: https://example.com/",
+                id="go-live-with-title",
+            ),
+            pytest.param(
+                "My Stream",
+                "New Title",
+                "example.com",
+                [],
+                True,
+                "📝 My Stream has changed its stream title!\n"
+                "Stream Title: New Title\n"
+                "\n"
+                "To tune in, visit: https://example.com/",
+                id="title-change",
+            ),
+            pytest.param(
+                "My Stream",
+                "",
+                "example.com",
+                [],
+                False,
+                "🎥 My Stream is now live!\n\nTo tune in, visit: https://example.com/",
+                id="go-live-no-title",
+            ),
+            pytest.param(
+                "",
+                "Title",
+                "example.com",
+                [],
+                False,
+                "🎥 example.com is now live!\n"
+                "Stream Title: Title\n"
+                "\n"
+                "To tune in, visit: https://example.com/",
+                id="name-fallback-to-domain",
+            ),
+            pytest.param(
+                "Stream",
+                "Title",
+                "example.com",
+                ["gaming", "fun"],
+                False,
+                "🎥 Stream is now live!\n"
+                "Stream Title: Title\n"
+                "\n"
+                "To tune in, visit: https://example.com/\n"
+                "\n"
+                "#gaming #fun",
+                id="with-tags",
+            ),
+            pytest.param(
+                "Stream",
+                "Title",
+                "example.com",
+                [".hidden", "visible"],
+                False,
+                "🎥 Stream is now live!\n"
+                "Stream Title: Title\n"
+                "\n"
+                "To tune in, visit: https://example.com/\n"
+                "\n"
+                "#visible",
+                id="dot-prefix-tag-filtered",
+            ),
+            pytest.param(
+                "Stream",
+                "Title",
+                "example.com",
+                [".secret"],
+                False,
+                "🎥 Stream is now live!\n"
+                "Stream Title: Title\n"
+                "\n"
+                "To tune in, visit: https://example.com/",
+                id="all-tags-dot-prefixed",
+            ),
+        ],
+    )
+    def test_format_message(
+        self,
+        name: str,
+        title: str,
+        domain: str,
+        tags: list[str],
+        *,
+        title_change: bool,
+        expected: str,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Format the notification message with expected content."""
+        service = _make_service(
+            client=_StubMatrixClient(), subscription_repo=subscription_repo
+        )
+        result = service._format_message(
+            name, title, domain, tags, title_change=title_change
+        )
+        assert result == expected
+
+
+class TestNotifyStreamLive:
+    """Live notification sending behavior."""
+
+    async def test_sends_to_all_subscribed_rooms(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Send notifications to every room subscribed to the domain."""
+        client = _StubMatrixClient()
+        service = _make_service(client=client, subscription_repo=subscription_repo)
+
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room1:matrix.org")
+        await subscription_repo.add("example.com", "!room2:matrix.org")
+
+        await service.notify_stream_live("example.com", "Stream", "Title", ["tag"])
+
+        assert len(client.sent_messages) == 2
+        room_ids = {msg.room_id for msg in client.sent_messages}
+        assert room_ids == {"!room1:matrix.org", "!room2:matrix.org"}
+        expected_body = (
+            "🎥 Stream is now live!\n"
+            "Stream Title: Title\n"
+            "\n"
+            "To tune in, visit: https://example.com/\n"
+            "\n"
+            "#tag"
+        )
+        for msg in client.sent_messages:
+            assert msg.content.body == expected_body
+
+    async def test_records_cooldown_after_success(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Record a cooldown after at least one room receives a notification."""
+        client = _StubMatrixClient()
+        service = _make_service(client=client, subscription_repo=subscription_repo)
+
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room:matrix.org")
+
+        before_send = time.monotonic()
+        await service.notify_stream_live("example.com", "Stream", "Title", [])
+
+        assert service.get_last_notification_time("example.com") >= before_send
+
+    async def test_no_cooldown_when_no_subscribed_rooms(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Do not record a cooldown if no room receives the notification."""
+        client = _StubMatrixClient()
+        service = _make_service(client=client, subscription_repo=subscription_repo)
+
+        await service.notify_stream_live("example.com", "Stream", "Title", [])
+
+        assert len(client.sent_messages) == 0
+        assert service.get_last_notification_time("example.com") == 0
+
+    async def test_no_cooldown_when_all_deliveries_fail(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Do not record a cooldown if every room delivery fails."""
+        client = _StubMatrixClient()
+        client.should_fail_for_rooms.add("!bad:matrix.org")
+        service = _make_service(client=client, subscription_repo=subscription_repo)
+
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!bad:matrix.org")
+
+        await service.notify_stream_live("example.com", "Stream", "Title", [])
+
+        assert len(client.sent_messages) == 0
+        assert service.get_last_notification_time("example.com") == 0
+
+    async def test_counts_cancelled_delivery_as_failure(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Count a cancelled delivery result as a failure."""
+        client = _StubMatrixClient()
+
+        async def send_message(_room_id: str, _content: object) -> None:
+            raise asyncio.CancelledError
+
+        client.send_message = send_message
+        service = _make_service(client=client, subscription_repo=subscription_repo)
+
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room:matrix.org")
+
+        await service.notify_stream_live("example.com", "Stream", "Title", [])
+
+        assert service.get_last_notification_time("example.com") == 0
+
+    async def test_skips_when_rate_limited(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Skip sending when the domain is within the rate-limit cooldown."""
+        client = _StubMatrixClient()
+        service = _make_service(client=client, subscription_repo=subscription_repo)
+        service.notification_timers_cache["example.com"] = time.monotonic()
+
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room1:matrix.org")
+
+        await service.notify_stream_live("example.com", "Stream", "Title", [])
+
+        assert len(client.sent_messages) == 0
+
+    async def test_counts_failures(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Deliver to other subscribed rooms when one room delivery fails."""
+        client = _StubMatrixClient()
+        client.should_fail_for_rooms.add("!bad:matrix.org")
+        service = _make_service(client=client, subscription_repo=subscription_repo)
+
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!bad:matrix.org")
+        await subscription_repo.add("example.com", "!good:matrix.org")
+
+        await service.notify_stream_live("example.com", "Stream", "Title", [])
+
+        assert len(client.sent_messages) == 1
+        assert client.sent_messages[0].room_id == "!good:matrix.org"
+        assert client.sent_messages[0].content.body == (
+            "🎥 Stream is now live!\n"
+            "Stream Title: Title\n"
+            "\n"
+            "To tune in, visit: https://example.com/"
+        )
+
+
+class TestSendCleanupWarning:
+    """Cleanup warning notification sending."""
+
+    async def test_sends_warning_to_all_rooms(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Send cleanup warning to all subscribed rooms."""
+        client = _StubMatrixClient()
+        service = _make_service(client=client, subscription_repo=subscription_repo)
+
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room1:matrix.org")
+
+        await service.send_cleanup_warning("example.com")
+
+        assert len(client.sent_messages) == 1
+        assert client.sent_messages[0].content.body == (
+            "⚠️  Warning: Subscription Cleanup Scheduled\n"
+            "\n"
+            "The Owncast instance at example.com has been "
+            "unreachable for 83 days. If it remains "
+            "unreachable for 7 more days "
+            "(90 days total), this subscription "
+            "will be automatically removed."
+        )
+
+
+class TestSendCleanupDeletion:
+    """Cleanup deletion notification sending."""
+
+    async def test_sends_deletion_to_all_rooms(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Send cleanup deletion notice to all subscribed rooms."""
+        client = _StubMatrixClient()
+        service = _make_service(client=client, subscription_repo=subscription_repo)
+
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room1:matrix.org")
+
+        await service.send_cleanup_deletion("example.com")
+
+        assert len(client.sent_messages) == 1
+        assert client.sent_messages[0].content.body == (
+            "🗑️  Subscription Automatically Removed\n"
+            "\n"
+            "The Owncast instance at example.com has been "
+            "unreachable for 90 days and has been "
+            "automatically removed from subscriptions in this "
+            "room.\n"
+            "\n"
+            "If the instance comes online again and you want to "
+            "resubscribe, run `!subscribe example.com`."
+        )
+
+
+class TestNotificationMetrics:
+    """Notification metrics recording."""
+
+    async def test_records_live_notification(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Record a live notification metric."""
+        client = _StubMatrixClient()
+        metrics = MetricsService()
+        service = _make_service(
+            client=client, subscription_repo=subscription_repo, metrics=metrics
+        )
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room:matrix.org")
+        await service.notify_stream_live("example.com", "Stream", "Title", [])
+        output = generate_metrics_output(metrics)
+        expected = (
+            "owncastsentry_notification_delivery_total"
+            '{result="success",type="live"} 1.0'
+        )
+        assert expected in output
+
+    async def test_records_title_change_notification(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Record a title_change notification metric."""
+        client = _StubMatrixClient()
+        metrics = MetricsService()
+        service = _make_service(
+            client=client, subscription_repo=subscription_repo, metrics=metrics
+        )
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room:matrix.org")
+        await service.notify_stream_live(
+            "example.com", "Stream", "Title", [], title_change=True
+        )
+        output = generate_metrics_output(metrics)
+        expected = (
+            "owncastsentry_notification_delivery_total"
+            '{result="success",type="title_change"} 1.0'
+        )
+        assert expected in output
+
+    async def test_records_cleanup_warning_notification(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Record a cleanup_warning notification metric."""
+        client = _StubMatrixClient()
+        metrics = MetricsService()
+        service = _make_service(
+            client=client, subscription_repo=subscription_repo, metrics=metrics
+        )
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room:matrix.org")
+        await service.send_cleanup_warning("example.com")
+        output = generate_metrics_output(metrics)
+        expected = (
+            "owncastsentry_notification_delivery_total"
+            '{result="success",type="cleanup_warning"} 1.0'
+        )
+        assert expected in output
+
+    async def test_records_cleanup_deletion_notification(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Record a cleanup_deletion notification metric."""
+        client = _StubMatrixClient()
+        metrics = MetricsService()
+        service = _make_service(
+            client=client, subscription_repo=subscription_repo, metrics=metrics
+        )
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room:matrix.org")
+        await service.send_cleanup_deletion("example.com")
+        output = generate_metrics_output(metrics)
+        expected = (
+            "owncastsentry_notification_delivery_total"
+            '{result="success",type="cleanup_deletion"} 1.0'
+        )
+        assert expected in output
+
+    async def test_no_metric_when_rate_limited(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Do not record metric when notification is rate-limited."""
+        client = _StubMatrixClient()
+        metrics = MetricsService()
+        service = _make_service(
+            client=client, subscription_repo=subscription_repo, metrics=metrics
+        )
+        service.notification_timers_cache["example.com"] = time.monotonic()
+        await stream_repo.create("example.com")
+        await subscription_repo.add("example.com", "!room:matrix.org")
+        await service.notify_stream_live("example.com", "Stream", "Title", [])
+        output = generate_metrics_output(metrics)
+        assert 'result="success",type="live"} 0.0' in output

tests/test_owncast_client.py

@@ -0,0 +1,479 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for the Owncast HTTP client."""
+
+import json
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+import pytest
+import time_machine
+from aioresponses import aioresponses
+
+from owncastsentry.metrics import MetricsService
+from owncastsentry.owncast_client import (
+    _MAX_JSON_RESPONSE_BYTES,
+    OwncastClient,
+    _read_limited_response_body,
+    _user_agent,
+)
+from tests.conftest import (
+    VALID_CONFIG_RESPONSE,
+    VALID_STATUS_RESPONSE,
+    generate_metrics_output,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+
+class _ChunkedContent:
+    """Fake aiohttp response content that yields predefined chunks."""
+
+    def __init__(self, chunks: tuple[bytes, ...]) -> None:
+        """Store chunks to return from iter_chunked."""
+        self._chunks = chunks
+
+    async def iter_chunked(self, _size: int) -> AsyncIterator[bytes]:
+        """Yield chunks using the interface aiohttp exposes."""
+        for chunk in self._chunks:
+            yield chunk
+
+
+class _ChunkedResponse:
+    """Fake aiohttp response with chunked content."""
+
+    def __init__(
+        self,
+        chunks: tuple[bytes, ...],
+        content_length: int | None = None,
+    ) -> None:
+        """Store the content stream and optional Content-Length value."""
+        self.content = _ChunkedContent(chunks)
+        self.content_length = content_length
+
+
+@pytest.fixture
+async def owncast_client() -> AsyncIterator[OwncastClient]:
+    """Create an OwncastClient and close it after the test."""
+    client = OwncastClient(
+        logger=logging.getLogger("test"),
+        version="0.0.0",
+        metrics=MetricsService(),
+    )
+    yield client
+    await client.close()
+
+
+class TestUserAgent:
+    """User-Agent header construction."""
+
+    @pytest.mark.parametrize(
+        ("version", "expected"),
+        [
+            pytest.param(
+                "1.2.3",
+                "OwncastSentry/1.2.3 (bot; +https://git.logal.dev/LogalDeveloper/OwncastSentry)",
+                id="semver",
+            ),
+            pytest.param(
+                "0.0.0",
+                "OwncastSentry/0.0.0 (bot; +https://git.logal.dev/LogalDeveloper/OwncastSentry)",
+                id="zeroed",
+            ),
+            pytest.param(
+                "1.1.1.dev10+gf0146d061.d20260313",
+                "OwncastSentry/1.1.1.dev10+gf0146d061.d20260313 (bot; +https://git.logal.dev/LogalDeveloper/OwncastSentry)",
+                id="dev-version",
+            ),
+        ],
+    )
+    def test_user_agent(self, version: str, expected: str) -> None:
+        """Build a correctly formatted User-Agent header."""
+        assert _user_agent(version) == expected
+
+
+class TestReadLimitedResponseBody:
+    """Bounded response body reading."""
+
+    async def test_reads_all_chunks_before_returning(self) -> None:
+        """Return the full body when JSON arrives in multiple chunks."""
+        response = _ChunkedResponse(
+            (
+                b'{"streamTitle":',
+                b'"hello","online":true}',
+            )
+        )
+
+        result = await _read_limited_response_body(response)
+
+        assert result == bytearray(b'{"streamTitle":"hello","online":true}')
+
+    async def test_returns_none_when_content_length_is_too_large(self) -> None:
+        """Return None when Content-Length is already over the limit."""
+        response = _ChunkedResponse(
+            (),
+            content_length=_MAX_JSON_RESPONSE_BYTES + 1,
+        )
+
+        result = await _read_limited_response_body(response)
+
+        assert result is None
+
+    async def test_returns_none_when_streamed_body_is_too_large(self) -> None:
+        """Return None when chunked content grows past the limit."""
+        response = _ChunkedResponse(
+            (
+                b"x" * _MAX_JSON_RESPONSE_BYTES,
+                b"x",
+            )
+        )
+
+        result = await _read_limited_response_body(response)
+
+        assert result is None
+
+
+class TestGetStreamState:
+    """Stream observation retrieval from the status API."""
+
+    @time_machine.travel(datetime(2026, 3, 13, 12, 0, 0, tzinfo=UTC))
+    async def test_returns_state_on_success(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return a StreamStateObservation with correct fields on a valid response."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/status",
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            result = await owncast_client.get_stream_state("stream.logal.dev")
+
+        assert result is not None
+        assert result.domain == "stream.logal.dev"
+        assert (
+            result.title
+            == "I think I can do this... Let's start a nuclear reaction - Playing Nucleares!"  # noqa: E501
+        )
+        assert result.online is False
+        assert result.observed_at == "2026-03-13T12:00:00+00:00"
+
+    async def test_returns_none_on_missing_field(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when the response is missing required fields."""
+        incomplete = {"streamTitle": "Test Stream"}
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/status",
+                body=json.dumps(incomplete).encode(),
+            )
+            result = await owncast_client.get_stream_state("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_invalid_field_type(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when the response has malformed field types."""
+        malformed = {
+            **VALID_STATUS_RESPONSE,
+            "streamTitle": 123,
+        }
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/status",
+                body=json.dumps(malformed).encode(),
+            )
+            result = await owncast_client.get_stream_state("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_invalid_json(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when the response body is not valid JSON."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/status",
+                body=b"not json",
+            )
+            result = await owncast_client.get_stream_state("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_non_object_json(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when the response JSON is not an object."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/status",
+                body=json.dumps([]).encode(),
+            )
+            result = await owncast_client.get_stream_state("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_oversized_json(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when the response body is too large."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/status",
+                body=b" " * (_MAX_JSON_RESPONSE_BYTES + 1),
+            )
+            result = await owncast_client.get_stream_state("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_non_200(self, owncast_client: OwncastClient) -> None:
+        """Return None when the response status is not 200."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/status",
+                status=404,
+            )
+            result = await owncast_client.get_stream_state("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_connection_error(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when a connection error occurs."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/status",
+                exception=ConnectionError(),
+            )
+            result = await owncast_client.get_stream_state("stream.logal.dev")
+
+        assert result is None
+
+
+class TestGetStreamConfig:
+    """Stream configuration retrieval from the config API."""
+
+    async def test_returns_config_on_success(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return a StreamConfigObservation with fields from a valid response."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/config",
+                body=json.dumps(VALID_CONFIG_RESPONSE).encode(),
+            )
+            result = await owncast_client.get_stream_config("stream.logal.dev")
+
+        assert result is not None
+        assert result.name == "LogalDeveloper's Live Stream"
+        assert result.tags == (
+            "video games",
+            "chatting",
+            "casual",
+            "english",
+            "streaming",
+            "owncast",
+            "variety",
+        )
+
+    async def test_returns_none_on_invalid_json(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when the response body is not valid JSON."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/config",
+                body=b"not json",
+            )
+            result = await owncast_client.get_stream_config("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_non_object_json(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when the response JSON is not an object."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/config",
+                body=json.dumps([]).encode(),
+            )
+            result = await owncast_client.get_stream_config("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_invalid_field_type(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when the response has malformed field types."""
+        malformed = {
+            **VALID_CONFIG_RESPONSE,
+            "tags": "gaming",
+        }
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/config",
+                body=json.dumps(malformed).encode(),
+            )
+            result = await owncast_client.get_stream_config("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_oversized_json(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when the response body is too large."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/config",
+                body=b" " * (_MAX_JSON_RESPONSE_BYTES + 1),
+            )
+            result = await owncast_client.get_stream_config("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_non_200(self, owncast_client: OwncastClient) -> None:
+        """Return None when the response status is not 200."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/config",
+                status=500,
+            )
+            result = await owncast_client.get_stream_config("stream.logal.dev")
+
+        assert result is None
+
+    async def test_returns_none_on_connection_error(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return None when a connection error occurs."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://stream.logal.dev/api/config",
+                exception=ConnectionError(),
+            )
+            result = await owncast_client.get_stream_config("stream.logal.dev")
+
+        assert result is None
+
+
+class TestValidateInstance:
+    """Owncast instance validation via the status API."""
+
+    async def test_returns_true_for_valid_instance(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return True when the status endpoint returns a valid response."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://valid.com/api/status",
+                body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+            )
+            result = await owncast_client.validate_instance("valid.com")
+
+        assert result is True
+
+    async def test_returns_false_for_invalid_instance(
+        self, owncast_client: OwncastClient
+    ) -> None:
+        """Return False when the status endpoint returns a non-200 response."""
+        with aioresponses() as mocked:
+            mocked.get(
+                "https://invalid.com/api/status",
+                status=404,
+            )
+            result = await owncast_client.validate_instance("invalid.com")
+
+        assert result is False
+
+
+class TestResponseTimeMetrics:
+    """Response time gauge recording."""
+
+    async def test_records_on_success(self) -> None:
+        """Record response time on a successful request."""
+        metrics = MetricsService()
+        client = OwncastClient(
+            logger=logging.getLogger("test"),
+            version="0.0.0",
+            metrics=metrics,
+        )
+        try:
+            with aioresponses() as mocked:
+                mocked.get(
+                    "https://example.com/api/status",
+                    body=json.dumps(VALID_STATUS_RESPONSE).encode(),
+                )
+                await client.get_stream_state("example.com")
+            output = generate_metrics_output(metrics)
+            assert 'owncastsentry_api_response_seconds{domain="example.com"}' in output
+        finally:
+            await client.close()
+
+    async def test_no_observation_on_failure(self) -> None:
+        """Do not record response time when request fails."""
+        metrics = MetricsService()
+        client = OwncastClient(
+            logger=logging.getLogger("test"),
+            version="0.0.0",
+            metrics=metrics,
+        )
+        try:
+            with aioresponses() as mocked:
+                mocked.get(
+                    "https://example.com/api/status",
+                    status=500,
+                )
+                await client.get_stream_state("example.com")
+            output = generate_metrics_output(metrics)
+            assert (
+                'owncastsentry_api_response_seconds{domain="example.com"}' not in output
+            )
+        finally:
+            await client.close()
+
+    async def test_no_observation_on_connection_error(self) -> None:
+        """Do not record response time on connection error."""
+        metrics = MetricsService()
+        client = OwncastClient(
+            logger=logging.getLogger("test"),
+            version="0.0.0",
+            metrics=metrics,
+        )
+        try:
+            with aioresponses() as mocked:
+                mocked.get(
+                    "https://example.com/api/status",
+                    exception=ConnectionError(),
+                )
+                await client.get_stream_state("example.com")
+            output = generate_metrics_output(metrics)
+            assert (
+                'owncastsentry_api_response_seconds{domain="example.com"}' not in output
+            )
+        finally:
+            await client.close()
+
+
+class TestOpenConnectionCount:
+    """Open connection count."""
+
+    async def test_zero_with_no_requests(self, owncast_client: OwncastClient) -> None:
+        """Return zero when no requests have been made."""
+        assert owncast_client.open_connection_count == 0

tests/test_repository.py

@@ -0,0 +1,483 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for database repository classes."""
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+from owncastsentry.repository import _normalize_legacy_status_since
+from owncastsentry.types import (
+    UNKNOWN_STATUS_THRESHOLD,
+    AlreadySubscribedError,
+    NotSubscribedError,
+)
+
+if TYPE_CHECKING:
+    from mautrix.util.async_db import Database
+
+    from owncastsentry.repository import StreamRepository, SubscriptionRepository
+
+
+class TestStreamSchema:
+    """Streams table schema after migrations."""
+
+    async def test_uses_online_and_status_since_columns(
+        self, database: Database
+    ) -> None:
+        """Create the current schema without legacy connect/disconnect columns."""
+        async with database.acquire() as conn:
+            rows = await conn.fetch("PRAGMA table_info(streams)")
+
+        assert [row["name"] for row in rows] == [
+            "domain",
+            "name",
+            "title",
+            "online",
+            "status_since",
+            "failure_counter",
+        ]
+
+
+class TestNormalizeLegacyStatusSince:
+    """Legacy timestamp normalization used by the v4 migration."""
+
+    @pytest.mark.parametrize(
+        ("value", "expected"),
+        [
+            pytest.param(
+                "2026-05-21T19:06:24Z",
+                "2026-05-21T19:06:24+00:00",
+                id="utc-z",
+            ),
+            pytest.param(
+                "2026-05-21T19:38:40+02:00",
+                "2026-05-21T17:38:40+00:00",
+                id="positive-offset",
+            ),
+            pytest.param(
+                "2026-05-17T21:23:27-04:00",
+                "2026-05-18T01:23:27+00:00",
+                id="negative-offset",
+            ),
+            pytest.param("", None, id="blank"),
+            pytest.param(None, None, id="null"),
+            pytest.param("not a timestamp", None, id="malformed"),
+        ],
+    )
+    def test_normalizes_parseable_aware_timestamps(
+        self, value: str | None, expected: str | None
+    ) -> None:
+        """Normalize parseable legacy values and ignore unusable ones."""
+        assert _normalize_legacy_status_since(value) == expected
+
+
+class TestStreamExists:
+    """Stream existence checks."""
+
+    async def test_returns_true_for_existing_stream(
+        self, stream_repo: StreamRepository
+    ) -> None:
+        """Return True when the stream exists in the database."""
+        await stream_repo.create("example.com")
+        assert await stream_repo.exists("example.com") is True
+
+    async def test_returns_false_for_missing_stream(
+        self, stream_repo: StreamRepository
+    ) -> None:
+        """Return False when the stream does not exist in the database."""
+        assert await stream_repo.exists("missing.com") is False
+
+
+class TestStreamCreate:
+    """Stream creation behavior."""
+
+    async def test_returns_true_when_created(
+        self, stream_repo: StreamRepository
+    ) -> None:
+        """Return True when a stream row is inserted."""
+        assert await stream_repo.create("example.com") is True
+
+    async def test_returns_false_when_existing(
+        self, stream_repo: StreamRepository
+    ) -> None:
+        """Return False when a stream row already exists."""
+        await stream_repo.create("example.com")
+        assert await stream_repo.create("example.com") is False
+
+
+class TestStreamDelete:
+    """Stream record deletion."""
+
+    async def test_removes_stream_record(self, stream_repo: StreamRepository) -> None:
+        """Remove the stream record so get_by_domain returns None."""
+        await stream_repo.create("example.com")
+        await stream_repo.delete("example.com")
+        assert await stream_repo.get_by_domain("example.com") is None
+
+
+class TestStreamUpdate:
+    """Partial stream state updates."""
+
+    async def test_updates_only_supplied_fields(
+        self, stream_repo: StreamRepository
+    ) -> None:
+        """Update supplied fields while leaving omitted fields unchanged."""
+        await stream_repo.create("example.com")
+        await stream_repo.update(
+            "example.com",
+            name="Original Name",
+            title="Original Title",
+            online=True,
+            status_since="2026-01-01T12:00:00+00:00",
+        )
+
+        await stream_repo.update("example.com", title="Updated Title")
+
+        state = await stream_repo.get_by_domain("example.com")
+        assert state is not None
+        assert state.name == "Original Name"
+        assert state.title == "Updated Title"
+        assert state.online is True
+        assert state.status_since == "2026-01-01T12:00:00+00:00"
+
+    async def test_can_set_nullable_field_to_null(
+        self, stream_repo: StreamRepository
+    ) -> None:
+        """Treat None as a supplied NULL value, not an omitted field."""
+        await stream_repo.create("example.com")
+        await stream_repo.update(
+            "example.com",
+            name="Original Name",
+            title="Original Title",
+            status_since="2026-01-01T12:00:00+00:00",
+        )
+
+        await stream_repo.update("example.com", title=None)
+
+        state = await stream_repo.get_by_domain("example.com")
+        assert state is not None
+        assert state.name == "Original Name"
+        assert state.title is None
+        assert state.status_since == "2026-01-01T12:00:00+00:00"
+
+    async def test_accepts_no_supplied_fields(
+        self, stream_repo: StreamRepository
+    ) -> None:
+        """Leave the row unchanged when no partial fields are supplied."""
+        await stream_repo.create("example.com")
+        await stream_repo.update(
+            "example.com",
+            title="Original Title",
+            status_since="2026-01-01T12:00:00+00:00",
+        )
+
+        await stream_repo.update("example.com")
+
+        state = await stream_repo.get_by_domain("example.com")
+        assert state is not None
+        assert state.title == "Original Title"
+        assert state.status_since == "2026-01-01T12:00:00+00:00"
+
+
+class TestGetSubscribedStreamsForRoom:
+    """Subscribed stream lookup by room."""
+
+    async def test_returns_all_domains_for_room(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Return all domains a room is subscribed to."""
+        await stream_repo.create("alpha.com")
+        await stream_repo.create("beta.com")
+        await subscription_repo.add("alpha.com", "!room1:example.com")
+        await subscription_repo.add("beta.com", "!room1:example.com")
+
+        result = await subscription_repo.get_subscribed_streams_for_room(
+            "!room1:example.com"
+        )
+        assert sorted(result) == ["alpha.com", "beta.com"]
+
+    async def test_returns_empty_list_for_unsubscribed_room(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return an empty list when the room has no subscriptions."""
+        result = await subscription_repo.get_subscribed_streams_for_room(
+            "!nobody:example.com"
+        )
+        assert result == []
+
+
+class TestHasRoomSubscriptions:
+    """Room subscription existence checks."""
+
+    async def test_returns_true_for_subscribed_room(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return True when the room has at least one subscription."""
+        await subscription_repo.add("alpha.com", "!room1:example.com")
+
+        assert await subscription_repo.has_room_subscriptions("!room1:example.com")
+
+    async def test_returns_false_for_unsubscribed_room(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return False when the room has no subscriptions."""
+        assert not await subscription_repo.has_room_subscriptions("!nobody:example.com")
+
+
+class TestGetRoomSubscriptions:
+    """Resolved room subscription lookup."""
+
+    async def test_returns_sorted_stream_states_and_skips_missing_rows(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Return sorted resolved subscriptions and skip missing stream rows."""
+        await stream_repo.create("beta.example")
+        await stream_repo.update("beta.example", name="Beta")
+        await stream_repo.create("alpha.example")
+        await stream_repo.update("alpha.example", name="Alpha")
+        await subscription_repo.add("beta.example", "!room:example.com")
+        await subscription_repo.add("missing.example", "!room:example.com")
+        await subscription_repo.add("alpha.example", "!room:example.com")
+
+        subscriptions = await subscription_repo.get_room_subscriptions(
+            "!room:example.com"
+        )
+
+        assert [subscription.domain for subscription in subscriptions] == [
+            "alpha.example",
+            "beta.example",
+        ]
+        assert [subscription.stream_state.name for subscription in subscriptions] == [
+            "Alpha",
+            "Beta",
+        ]
+
+    async def test_returns_empty_list_for_unsubscribed_room(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return an empty list when the room has no resolved subscriptions."""
+        subscriptions = await subscription_repo.get_room_subscriptions(
+            "!nobody:example.com"
+        )
+        assert subscriptions == []
+
+
+class TestGetLiveRoomSubscriptions:
+    """Resolved live room subscription lookup."""
+
+    async def test_returns_online_streams_and_skips_inactive_states(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Return only streams whose derived status is ONLINE."""
+        await stream_repo.create("offline.example")
+        await stream_repo.update(
+            "offline.example",
+            name="Offline",
+            status_since="2026-01-01T00:00:00+00:00",
+        )
+        await stream_repo.create("online.example")
+        await stream_repo.update(
+            "online.example",
+            name="Online",
+            online=True,
+            status_since="2026-01-01T00:00:00+00:00",
+        )
+        await stream_repo.create("unknown.example")
+        await stream_repo.update(
+            "unknown.example",
+            name="Unknown",
+            online=True,
+            status_since="2026-01-01T00:00:00+00:00",
+        )
+        for _ in range(UNKNOWN_STATUS_THRESHOLD + 1):
+            await stream_repo.increment_failure_counter("unknown.example")
+
+        await subscription_repo.add("offline.example", "!room:example.com")
+        await subscription_repo.add("online.example", "!room:example.com")
+        await subscription_repo.add("unknown.example", "!room:example.com")
+
+        subscriptions = await subscription_repo.get_live_room_subscriptions(
+            "!room:example.com"
+        )
+
+        assert [subscription.domain for subscription in subscriptions] == [
+            "online.example"
+        ]
+
+    async def test_returns_empty_list_for_room_with_no_live_streams(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Return an empty list when no subscribed streams are live."""
+        await stream_repo.create("offline.example")
+        await subscription_repo.add("offline.example", "!room:example.com")
+
+        subscriptions = await subscription_repo.get_live_room_subscriptions(
+            "!room:example.com"
+        )
+
+        assert subscriptions == []
+
+
+class TestAddSubscription:
+    """Subscription creation behavior."""
+
+    async def test_adds_subscription(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Add a subscription row."""
+        await subscription_repo.add("alpha.com", "!room1:example.com")
+        assert await subscription_repo.get_subscribed_rooms("alpha.com") == [
+            "!room1:example.com"
+        ]
+
+    async def test_raises_when_existing(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Raise AlreadySubscribedError when a subscription already exists."""
+        await subscription_repo.add("alpha.com", "!room1:example.com")
+        with pytest.raises(AlreadySubscribedError):
+            await subscription_repo.add("alpha.com", "!room1:example.com")
+
+
+class TestRemoveSubscription:
+    """Subscription removal behavior."""
+
+    async def test_removes_subscription(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Remove an existing subscription row."""
+        await subscription_repo.add("alpha.com", "!room1:example.com")
+        await subscription_repo.remove("alpha.com", "!room1:example.com")
+        assert await subscription_repo.get_subscribed_rooms("alpha.com") == []
+
+    async def test_raises_when_missing(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Raise NotSubscribedError when no subscription exists."""
+        with pytest.raises(NotSubscribedError):
+            await subscription_repo.remove("alpha.com", "!room1:example.com")
+
+
+class TestGetAllSubscribedDomains:
+    """Unique subscribed domain retrieval."""
+
+    async def test_returns_each_domain_once(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Return each domain once even with multiple subscriptions."""
+        await stream_repo.create("alpha.com")
+        await subscription_repo.add("alpha.com", "!room1:example.com")
+        await subscription_repo.add("alpha.com", "!room2:example.com")
+
+        result = await subscription_repo.get_all_subscribed_domains()
+        assert result == ["alpha.com"]
+
+    async def test_returns_empty_list_with_no_subscriptions(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return an empty list when there are no subscriptions."""
+        result = await subscription_repo.get_all_subscribed_domains()
+        assert result == []
+
+
+class TestCountByDomain:
+    """Subscription count by domain."""
+
+    async def test_returns_correct_count(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Return the correct subscription count for a domain."""
+        await stream_repo.create("alpha.com")
+        await subscription_repo.add("alpha.com", "!room1:example.com")
+        await subscription_repo.add("alpha.com", "!room2:example.com")
+
+        assert await subscription_repo.count_by_domain("alpha.com") == 2
+
+    async def test_returns_zero_for_unknown_domain(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return 0 for a domain with no subscriptions."""
+        assert await subscription_repo.count_by_domain("unknown.com") == 0
+
+
+class TestCountByDomains:
+    """Bulk subscription counts by domain."""
+
+    async def test_returns_counts_for_requested_domains(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Return counts for requested domains and zero for missing domains."""
+        await stream_repo.create("alpha.com")
+        await stream_repo.create("beta.com")
+        await stream_repo.create("ignored.com")
+        await subscription_repo.add("alpha.com", "!room1:example.com")
+        await subscription_repo.add("alpha.com", "!room2:example.com")
+        await subscription_repo.add("beta.com", "!room3:example.com")
+        await subscription_repo.add("ignored.com", "!room4:example.com")
+
+        assert await subscription_repo.count_by_domains(
+            ["beta.com", "missing.com", "alpha.com"]
+        ) == {
+            "beta.com": 1,
+            "missing.com": 0,
+            "alpha.com": 2,
+        }
+
+    async def test_returns_empty_dict_for_empty_domain_list(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return an empty mapping when no domains are requested."""
+        assert await subscription_repo.count_by_domains([]) == {}
+
+
+class TestDeleteAllForDomain:
+    """Bulk subscription deletion by domain."""
+
+    async def test_deletes_all_subscriptions_and_returns_count(
+        self,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Delete all subscriptions for the domain and return the count."""
+        await stream_repo.create("alpha.com")
+        await subscription_repo.add("alpha.com", "!room1:example.com")
+        await subscription_repo.add("alpha.com", "!room2:example.com")
+
+        deleted = await subscription_repo.delete_all_for_domain("alpha.com")
+        assert deleted == 2
+
+        rooms = await subscription_repo.get_subscribed_rooms("alpha.com")
+        assert rooms == []
+
+    async def test_returns_zero_for_unknown_domain(
+        self, subscription_repo: SubscriptionRepository
+    ) -> None:
+        """Return 0 when deleting subscriptions for an unknown domain."""
+        assert await subscription_repo.delete_all_for_domain("unknown.com") == 0

tests/test_subscription_manager.py

@@ -0,0 +1,284 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for subscription manager business logic."""
+
+import logging
+from typing import TYPE_CHECKING
+
+import pytest
+
+from owncastsentry.subscription_manager import SubscriptionManager, _domainify
+from owncastsentry.types import (
+    UNKNOWN_STATUS_THRESHOLD,
+    AlreadySubscribedError,
+    InvalidOwncastInstanceError,
+    NotSubscribedError,
+)
+
+if TYPE_CHECKING:
+    from owncastsentry.repository import StreamRepository, SubscriptionRepository
+
+
+class _StubOwncastClient:
+    """Owncast client stub for validation-only manager tests."""
+
+    def __init__(self, *, valid: bool = True) -> None:
+        """Initialize the stub with a fixed validation result."""
+        self.valid = valid
+        self.validated_domains: list[str] = []
+
+    async def validate_instance(self, domain: str) -> bool:
+        """Record the domain and return the configured validation result."""
+        self.validated_domains.append(domain)
+        return self.valid
+
+
+@pytest.fixture
+def owncast_client() -> _StubOwncastClient:
+    """Return a validation-only Owncast client stub."""
+    return _StubOwncastClient()
+
+
+@pytest.fixture
+def manager(
+    owncast_client: _StubOwncastClient,
+    stream_repo: StreamRepository,
+    subscription_repo: SubscriptionRepository,
+) -> SubscriptionManager:
+    """SubscriptionManager built directly for unit tests."""
+    return SubscriptionManager(
+        owncast_client=owncast_client,  # type: ignore[arg-type]
+        stream_repo=stream_repo,
+        subscription_repo=subscription_repo,
+        logger=logging.getLogger("test"),
+    )
+
+
+class TestDomainify:
+    """Domain extraction and sanitization from user input."""
+
+    @pytest.mark.parametrize(
+        ("input_url", "expected"),
+        [
+            pytest.param("example.com", "example.com", id="bare-domain"),
+            pytest.param("  example.com  ", "example.com", id="surrounding-whitespace"),
+            pytest.param("https://example.com", "example.com", id="https-url"),
+            pytest.param("http://example.com", "example.com", id="http-url"),
+            pytest.param("https://example.com:8080", "example.com", id="url-with-port"),
+            pytest.param(
+                "https://example.com/path/to/page",
+                "example.com",
+                id="url-with-path",
+            ),
+            pytest.param(
+                "user@stream.logal.dev",
+                "stream.logal.dev",
+                id="email-style",
+            ),
+            pytest.param(
+                "matrix@notify@stream.logal.dev",
+                "stream.logal.dev",
+                id="last-at-sign-wins",
+            ),
+            pytest.param("EXAMPLE.COM", "example.com", id="uppercase"),
+            pytest.param("exam!ple.com", "example.com", id="special-chars-stripped"),
+            pytest.param(".example.com.", "example.com", id="leading-trailing-dots"),
+            pytest.param("-example.com-", "example.com", id="leading-trailing-hyphens"),
+            pytest.param(
+                "sub.domain.example.com",
+                "sub.domain.example.com",
+                id="subdomain",
+            ),
+        ],
+    )
+    def test_extracts_domain(self, input_url: str, expected: str) -> None:
+        """Extract and sanitize the domain from various input formats."""
+        assert _domainify(input_url) == expected
+
+
+class TestManagerSubscribe:
+    """SubscriptionManager subscribe workflow."""
+
+    async def test_first_subscription_validates_and_creates_stream(
+        self,
+        manager: SubscriptionManager,
+        owncast_client: _StubOwncastClient,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """First subscription validates the instance and creates stream state."""
+        domain = await manager.subscribe(
+            "!room:example.com", "https://Stream.Example/foo"
+        )
+
+        assert domain == "stream.example"
+        assert owncast_client.validated_domains == ["stream.example"]
+        assert await stream_repo.exists("stream.example") is True
+        assert await subscription_repo.get_subscribed_rooms("stream.example") == [
+            "!room:example.com"
+        ]
+
+    async def test_invalid_first_subscription_raises(
+        self,
+        manager: SubscriptionManager,
+        owncast_client: _StubOwncastClient,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Invalid first-time Owncast validation raises a domain error."""
+        owncast_client.valid = False
+
+        with pytest.raises(InvalidOwncastInstanceError) as exc_info:
+            await manager.subscribe("!room:example.com", "bad.example")
+
+        assert exc_info.value.domain == "bad.example"
+        assert owncast_client.validated_domains == ["bad.example"]
+        assert await stream_repo.exists("bad.example") is False
+        assert await subscription_repo.get_subscribed_rooms("bad.example") == []
+
+    async def test_duplicate_subscription_raises(
+        self,
+        manager: SubscriptionManager,
+        owncast_client: _StubOwncastClient,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Duplicate room subscription raises AlreadySubscribedError."""
+        await manager.subscribe("!room:example.com", "stream.example")
+
+        with pytest.raises(AlreadySubscribedError) as exc_info:
+            await manager.subscribe("!room:example.com", "stream.example")
+
+        assert exc_info.value.domain == "stream.example"
+        assert owncast_client.validated_domains == ["stream.example"]
+        assert await subscription_repo.get_subscribed_rooms("stream.example") == [
+            "!room:example.com"
+        ]
+
+    async def test_existing_stream_new_room_skips_validation(
+        self,
+        manager: SubscriptionManager,
+        owncast_client: _StubOwncastClient,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Domains with existing subscriptions skip remote validation."""
+        await manager.subscribe("!room1:example.com", "stream.example")
+        owncast_client.valid = False
+
+        domain = await manager.subscribe("!room2:example.com", "stream.example")
+
+        assert domain == "stream.example"
+        assert owncast_client.validated_domains == ["stream.example"]
+        rooms = await subscription_repo.get_subscribed_rooms("stream.example")
+        assert sorted(rooms) == [
+            "!room1:example.com",
+            "!room2:example.com",
+        ]
+
+
+class TestManagerUnsubscribe:
+    """SubscriptionManager unsubscribe workflow."""
+
+    async def test_removes_existing_subscription(
+        self,
+        manager: SubscriptionManager,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Existing room subscription is removed and its domain is returned."""
+        await manager.subscribe("!room:example.com", "stream.example")
+
+        domain = await manager.unsubscribe("!room:example.com", "stream.example")
+
+        assert domain == "stream.example"
+        assert await subscription_repo.get_subscribed_rooms("stream.example") == []
+
+    async def test_missing_subscription_raises(
+        self,
+        manager: SubscriptionManager,
+    ) -> None:
+        """Removing a non-existent subscription raises NotSubscribedError."""
+        with pytest.raises(NotSubscribedError) as exc_info:
+            await manager.unsubscribe("!room:example.com", "missing.example")
+
+        assert exc_info.value.domain == "missing.example"
+
+
+class TestManagerListings:
+    """SubscriptionManager room listing behavior."""
+
+    async def test_list_room_subscriptions_returns_sorted_stream_states(
+        self,
+        manager: SubscriptionManager,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Return sorted room subscriptions and skip missing stream rows."""
+        await stream_repo.create("beta.example")
+        await stream_repo.update("beta.example", name="Beta")
+        await stream_repo.create("alpha.example")
+        await stream_repo.update("alpha.example", name="Alpha")
+        await subscription_repo.add("beta.example", "!room:example.com")
+        await subscription_repo.add("missing.example", "!room:example.com")
+        await subscription_repo.add("alpha.example", "!room:example.com")
+
+        subscriptions = await manager.list_room_subscriptions("!room:example.com")
+
+        assert [subscription.domain for subscription in subscriptions] == [
+            "alpha.example",
+            "beta.example",
+        ]
+        assert [subscription.stream_state.name for subscription in subscriptions] == [
+            "Alpha",
+            "Beta",
+        ]
+
+    async def test_list_live_room_subscriptions_filters_online_streams(
+        self,
+        manager: SubscriptionManager,
+        stream_repo: StreamRepository,
+        subscription_repo: SubscriptionRepository,
+    ) -> None:
+        """Live listing includes only subscriptions with ONLINE stream status."""
+        await stream_repo.create("offline.example")
+        await stream_repo.update(
+            "offline.example",
+            name="Offline",
+            status_since="2026-01-01T00:00:00+00:00",
+        )
+        await stream_repo.create("online.example")
+        await stream_repo.update(
+            "online.example",
+            name="Online",
+            online=True,
+            status_since="2026-01-01T00:00:00+00:00",
+        )
+        await stream_repo.create("unknown.example")
+        await stream_repo.update(
+            "unknown.example",
+            name="Unknown",
+            online=True,
+            status_since="2026-01-01T00:00:00+00:00",
+        )
+        for _ in range(UNKNOWN_STATUS_THRESHOLD + 1):
+            await stream_repo.increment_failure_counter("unknown.example")
+
+        await subscription_repo.add("offline.example", "!room:example.com")
+        await subscription_repo.add("online.example", "!room:example.com")
+        await subscription_repo.add("unknown.example", "!room:example.com")
+
+        subscriptions = await manager.list_live_room_subscriptions("!room:example.com")
+
+        assert [subscription.domain for subscription in subscriptions] == [
+            "online.example"
+        ]

tests/test_types.py

@@ -0,0 +1,388 @@
+# Copyright 2026 Logan Fick
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Tests for data models."""
+
+from dataclasses import FrozenInstanceError
+from datetime import UTC, datetime, timedelta, timezone
+
+import pytest
+import time_machine
+
+from owncastsentry.types import (
+    _MAX_INSTANCE_TITLE_LENGTH,
+    _MAX_STREAM_TITLE_LENGTH,
+    _MAX_TAG_LENGTH,
+    UNKNOWN_STATUS_THRESHOLD,
+    AlreadySubscribedError,
+    InvalidApiResponseError,
+    InvalidOwncastInstanceError,
+    NotSubscribedError,
+    RoomSubscription,
+    StreamConfigObservation,
+    StreamState,
+    StreamStateObservation,
+    StreamStatus,
+    SubscriptionError,
+    UpdateResult,
+    _truncate,
+    format_status_since,
+)
+
+
+class TestTruncate:
+    """Text truncation to a maximum length."""
+
+    @pytest.mark.parametrize(
+        ("text", "max_length", "expected"),
+        [
+            pytest.param("hello", 10, "hello", id="under-limit"),
+            pytest.param("hello", 5, "hello", id="exact-limit"),
+            pytest.param("hello world", 5, "hello", id="over-limit"),
+            pytest.param("", 5, "", id="empty-string"),
+        ],
+    )
+    def test_truncates(self, text: str, max_length: int, expected: str) -> None:
+        """Return text unchanged within the limit and truncate over-limit text."""
+        assert _truncate(text, max_length) == expected
+
+
+class TestStreamStateStatus:
+    """Stream status derivation from state fields."""
+
+    @pytest.mark.parametrize(
+        ("failure_counter", "online", "expected"),
+        [
+            pytest.param(
+                UNKNOWN_STATUS_THRESHOLD + 1,
+                False,
+                StreamStatus.UNKNOWN,
+                id="above-threshold-offline-returns-unknown",
+            ),
+            pytest.param(
+                UNKNOWN_STATUS_THRESHOLD + 1,
+                True,
+                StreamStatus.UNKNOWN,
+                id="above-threshold-online-returns-unknown",
+            ),
+            pytest.param(
+                0,
+                True,
+                StreamStatus.ONLINE,
+                id="zero-failures-online-returns-online",
+            ),
+            pytest.param(
+                0,
+                False,
+                StreamStatus.OFFLINE,
+                id="zero-failures-offline-returns-offline",
+            ),
+            pytest.param(
+                UNKNOWN_STATUS_THRESHOLD,
+                True,
+                StreamStatus.ONLINE,
+                id="at-threshold-online-returns-online",
+            ),
+            pytest.param(
+                UNKNOWN_STATUS_THRESHOLD,
+                False,
+                StreamStatus.OFFLINE,
+                id="at-threshold-offline-returns-offline",
+            ),
+        ],
+    )
+    def test_status(
+        self,
+        failure_counter: int,
+        online: object,
+        expected: StreamStatus,
+    ) -> None:
+        """Return the correct status based on failure counter and online state."""
+        state = StreamState(
+            domain="example.com",
+            failure_counter=failure_counter,
+            online=online is True,
+        )
+        assert state.status is expected
+
+
+class TestFormatStatusSince:
+    """Status timestamp formatting."""
+
+    def test_formats_as_utc_iso_seconds(self) -> None:
+        """Normalize aware datetimes to UTC with second precision."""
+        timestamp = datetime(
+            2026,
+            1,
+            1,
+            12,
+            34,
+            56,
+            123456,
+            tzinfo=timezone(timedelta(hours=-5)),
+        )
+
+        assert format_status_since(timestamp) == "2026-01-01T17:34:56+00:00"
+
+    def test_treats_naive_as_utc(self) -> None:
+        """Format naive datetimes as UTC."""
+        timestamp = datetime.fromisoformat("2026-01-01T12:34:56.123456")
+
+        assert format_status_since(timestamp) == "2026-01-01T12:34:56+00:00"
+
+
+class TestStreamStateObservationFromApiResponse:
+    """StreamStateObservation construction from an API response dictionary."""
+
+    def test_typical_response(self) -> None:
+        """Populate API-derived fields from a complete status response."""
+        observed_at = datetime(2026, 1, 1, 0, 0, 1, tzinfo=UTC)
+        response = {
+            "streamTitle": "My Stream",
+            "online": True,
+        }
+        with time_machine.travel(observed_at, tick=False):
+            observation = StreamStateObservation.from_api_response(
+                response, "example.com"
+            )
+        assert observation.domain == "example.com"
+        assert observation.title == "My Stream"
+        assert observation.online is True
+        assert observation.observed_at == "2026-01-01T00:00:01+00:00"
+
+    def test_missing_required_field_raises(self) -> None:
+        """Reject API responses without required stream state fields."""
+        with pytest.raises(InvalidApiResponseError):
+            StreamStateObservation.from_api_response({}, "bare.example.com")
+
+    def test_offline_response(self) -> None:
+        """Populate offline state from a status response."""
+        observed_at = datetime(2026, 1, 1, 0, 0, 1, tzinfo=UTC)
+        response = {
+            "streamTitle": "Offline Stream",
+            "online": False,
+        }
+        with time_machine.travel(observed_at, tick=False):
+            observation = StreamStateObservation.from_api_response(
+                response, "example.com"
+            )
+        assert observation.online is False
+        assert observation.observed_at == "2026-01-01T00:00:01+00:00"
+
+    def test_title_truncation(self) -> None:
+        """Truncate the stream title to _MAX_STREAM_TITLE_LENGTH."""
+        observed_at = datetime(2026, 1, 1, 0, 0, 1, tzinfo=UTC)
+        long_title = "A" * (_MAX_STREAM_TITLE_LENGTH + 50)
+        response = {
+            "streamTitle": long_title,
+            "online": True,
+        }
+        with time_machine.travel(observed_at, tick=False):
+            observation = StreamStateObservation.from_api_response(
+                response, "example.com"
+            )
+        assert len(observation.title) == _MAX_STREAM_TITLE_LENGTH
+        assert observation.title == "A" * _MAX_STREAM_TITLE_LENGTH
+
+    @pytest.mark.parametrize(
+        ("field", "value"),
+        [
+            pytest.param("streamTitle", 123, id="title-not-string"),
+            pytest.param("online", "true", id="online-not-bool"),
+        ],
+    )
+    def test_invalid_field_type_raises(self, field: str, value: object) -> None:
+        """Reject stream state responses with malformed field types."""
+        response: dict[str, object] = {
+            "streamTitle": "My Stream",
+            "online": True,
+        }
+        response[field] = value
+
+        with pytest.raises(InvalidApiResponseError):
+            StreamStateObservation.from_api_response(response, "example.com")
+
+
+class TestStreamStateFromDbRow:
+    """StreamState construction from a database row dictionary."""
+
+    def test_typical_row(self) -> None:
+        """Populate all fields from a complete database row."""
+        row = {
+            "domain": "example.com",
+            "name": "Test Instance",
+            "title": "Live Now",
+            "online": True,
+            "status_since": "2026-01-01T00:00:00+00:00",
+            "failure_counter": 3,
+        }
+        state = StreamState.from_db_row(row)
+        assert state.domain == "example.com"
+        assert state.name == "Test Instance"
+        assert state.title == "Live Now"
+        assert state.online is True
+        assert state.status_since == "2026-01-01T00:00:00+00:00"
+        assert state.failure_counter == 3
+
+    def test_row_with_none_optional_fields(self) -> None:
+        """Accept None for optional fields in a database row."""
+        row = {
+            "domain": "example.com",
+            "name": None,
+            "title": None,
+            "online": False,
+            "status_since": None,
+            "failure_counter": 0,
+        }
+        state = StreamState.from_db_row(row)
+        assert state.domain == "example.com"
+        assert state.name is None
+        assert state.title is None
+        assert state.online is False
+        assert state.status_since is None
+        assert state.failure_counter == 0
+
+
+class TestStreamConfigObservationFromApiResponse:
+    """StreamConfigObservation construction from an API response dictionary."""
+
+    def test_typical_response(self) -> None:
+        """Populate name and tags from a complete API response."""
+        response = {"name": "My Instance", "tags": ["gaming", "music"]}
+        observed_at = datetime(2026, 1, 1, 0, 0, 1, tzinfo=UTC)
+        with time_machine.travel(observed_at, tick=False):
+            config = StreamConfigObservation.from_api_response(response)
+        assert config.name == "My Instance"
+        assert config.tags == ("gaming", "music")
+        assert config.observed_at == "2026-01-01T00:00:01+00:00"
+
+    def test_missing_keys_defaults(self) -> None:
+        """Use defaults when name and tags keys are missing."""
+        config = StreamConfigObservation.from_api_response({})
+        assert config.name == ""
+        assert config.tags == ()
+
+    def test_name_truncation(self) -> None:
+        """Truncate the instance name to _MAX_INSTANCE_TITLE_LENGTH."""
+        long_name = "B" * (_MAX_INSTANCE_TITLE_LENGTH + 50)
+        response = {"name": long_name, "tags": []}
+        config = StreamConfigObservation.from_api_response(response)
+        assert len(config.name) == _MAX_INSTANCE_TITLE_LENGTH
+        assert config.name == "B" * _MAX_INSTANCE_TITLE_LENGTH
+
+    def test_tag_truncation(self) -> None:
+        """Truncate each tag to _MAX_TAG_LENGTH."""
+        long_tag = "C" * (_MAX_TAG_LENGTH + 10)
+        response = {"name": "", "tags": [long_tag, "short"]}
+        config = StreamConfigObservation.from_api_response(response)
+        assert len(config.tags[0]) == _MAX_TAG_LENGTH
+        assert config.tags[0] == "C" * _MAX_TAG_LENGTH
+        assert config.tags[1] == "short"
+
+    @pytest.mark.parametrize(
+        ("field", "value"),
+        [
+            pytest.param("name", None, id="name-not-string"),
+            pytest.param("tags", "gaming", id="tags-not-list"),
+            pytest.param("tags", ["gaming", 123], id="tag-not-string"),
+        ],
+    )
+    def test_invalid_field_type_raises(self, field: str, value: object) -> None:
+        """Reject stream config responses with malformed field types."""
+        response: dict[str, object] = {"name": "My Instance", "tags": ["gaming"]}
+        response[field] = value
+
+        with pytest.raises(InvalidApiResponseError):
+            StreamConfigObservation.from_api_response(response)
+
+
+class TestValueTypeImmutability:
+    """Dataclass value containers are immutable snapshots."""
+
+    def test_stream_state_is_immutable(self) -> None:
+        """StreamState cannot be mutated in place."""
+        state = StreamState(domain="stream.example")
+        with pytest.raises(FrozenInstanceError):
+            state.title = "Changed"  # type: ignore[misc]
+
+    def test_stream_observation_is_immutable(self) -> None:
+        """StreamStateObservation cannot be mutated in place."""
+        observation = StreamStateObservation(
+            domain="stream.example",
+        )
+        with pytest.raises(FrozenInstanceError):
+            observation.title = "Changed"  # type: ignore[misc]
+
+    def test_stream_config_is_immutable(self) -> None:
+        """StreamConfigObservation cannot be mutated in place."""
+        config = StreamConfigObservation(name="Stream")
+        with pytest.raises(FrozenInstanceError):
+            config.name = "Changed"  # type: ignore[misc]
+
+    def test_stream_config_tags_are_immutable(self) -> None:
+        """StreamConfigObservation tags are stored in an immutable tuple."""
+        config = StreamConfigObservation(name="Stream", tags=("gaming",))
+        assert config.tags == ("gaming",)
+
+    def test_update_result_is_immutable(self) -> None:
+        """UpdateResult cannot be mutated in place."""
+        result = UpdateResult(total_streams=1, successful_checks=1, failed_checks=0)
+        with pytest.raises(FrozenInstanceError):
+            result.failed_checks = 1  # type: ignore[misc]
+
+
+class TestSubscriptionTypes:
+    """Subscription display containers and domain error hierarchy."""
+
+    @pytest.mark.parametrize(
+        "error_cls",
+        [
+            pytest.param(InvalidOwncastInstanceError, id="invalid-instance"),
+            pytest.param(AlreadySubscribedError, id="already-subscribed"),
+            pytest.param(NotSubscribedError, id="not-subscribed"),
+        ],
+    )
+    def test_errors_subclass_subscription_error(
+        self, error_cls: type[Exception]
+    ) -> None:
+        """Every subscription domain error subclasses SubscriptionError."""
+        assert issubclass(error_cls, SubscriptionError)
+
+    @pytest.mark.parametrize(
+        "error",
+        [
+            pytest.param(
+                InvalidOwncastInstanceError("bad.example"),
+                id="invalid-instance",
+            ),
+            pytest.param(
+                AlreadySubscribedError("dupe.example"),
+                id="already-subscribed",
+            ),
+            pytest.param(
+                NotSubscribedError("missing.example"),
+                id="not-subscribed",
+            ),
+        ],
+    )
+    def test_errors_store_domain(self, error: SubscriptionError) -> None:
+        """Subscription domain errors expose the stream domain that failed."""
+        assert error.domain in str(error)
+
+    def test_room_subscription_is_immutable(self) -> None:
+        """RoomSubscription is an immutable stream display snapshot."""
+        state = StreamState(domain="stream.example")
+        subscription = RoomSubscription(domain="stream.example", stream_state=state)
+        with pytest.raises(FrozenInstanceError):
+            subscription.domain = "other.example"  # type: ignore[misc]