How ototot/notifier works
1. Overall shape
- This is a Rust workspace with a single executable, a shared runtime crate, and four plugin crates grouped into sources and destinations.
- The architecture is compile-time plugin-based, not dynamically loaded: the server is built with whichever source/destination crates are included in the workspace.
2. Top-level runtime vs. plugins
- apps/notifier-server is the application entrypoint and HTTP service.
- crates/notifier-runtime holds shared infrastructure: configuration loading/validation, SQLite-backed storage, and template rendering.
- plugins/sources/* and plugins/destinations/* encapsulate provider-specific routing/policy logic.
3. Primary data flow
- Startup loads a single config file, validates it, reconciles configured sources, and only then marks the service ready.
- Incoming events are accepted from provider webhooks or source polling, transformed into a rendered message, persisted to SQLite, and then delivered asynchronously to a destination.
- The service returns webhook success only after the event has been stored, so delivery is decoupled from ingestion.
4. Ingress side: sources
- Supported sources are Twitch, TwitCasting, and Nitter.
- Twitch and TwitCasting are webhook-driven sources that expose one configured POST callback path each.
- Nitter is pull-based: it polls RSS feeds in the background and does not gate readiness on feed availability.
5. Egress side: destinations
- Supported destinations are Discord and Telegram.
- The destination plugins are thin bindings around provider SDKs (serenity for Discord, teloxide for Telegram) with routing and policy logic in the plugin crates.
- Messages are sent as plain text in v1, with provider-specific length limits treated as permanent failures rather than being truncated.
6. Configuration model
- Configuration is loaded once at startup and requires restart to change.
- Sources and destinations are keyed reusable instances; routes reference those IDs and add route-local inputs such as broadcaster lists, channel IDs, and message templates.
- Route IDs must remain stable across restarts because they are part of the durable routing model.
7. Template and event shaping
- Route message fields use MiniJinja templates.
- Rendering happens at webhook ingestion time, and the rendered text is what gets stored, which makes retries deterministic.
- The runtime also exposes schema and template-variable documentation through the schema command.
8. Persistence and delivery
- SQLite is the durable queue and state store.
- Accepted events are persisted before success is returned; workers later consume queued rows and deliver them to destinations.
- Rows survive restarts, so in-flight work is recovered after process failure.
9. Retry and failure semantics
- Network failures, HTTP 429, and HTTP 5xx are retried with exponential backoff and jitter up to one hour.
- Other 4xx responses and exhausted retries are moved to dead-letter state.
- If a route is removed while rows are queued, those rows are also moved to dead-letter.
10. Readiness and reconciliation
- GET /health and GET /ready are exposed by the server.
- Readiness depends on successful source reconciliation: missing provider subscriptions are created, but absent config entries are not deleted from providers.
- Twitch callback URLs are derived from public_base_url plus a source path; TwitCasting requires the full callback URL to be configured separately.
11. Deduplication and at-least-once delivery
- Delivery is explicitly at least once; duplicate sends can occur if a destination accepts a request but the response is lost.
- Deduplication keys differ by source: Twitch message IDs, TwitCasting broadcaster/movie-derived keys, and Nitter RSS item GUIDs or links.
- This keeps source identity handling in the plugin layer while the runtime handles durable queuing.
12. Operational boundaries
- The service does not log specs or credentials; source and destination credentials are stored literally in config.
- config.example.json and the check-config, schema, and serve commands form the main operator workflow.
- The CI workflow under .github/workflows/build.yml supports standard Rust validation (fmt, clippy, tests) around this plugin-oriented architecture.
Main entry points: main.rs Notifier server · config.rs Config model · src/lib.rs Twitch source · src/lib.rs TwitCasting source
Components 17
App
Executable entrypoint and HTTP service
- Notifier server · Main executable that boots the service, exposes health/readiness, and runs workers
apps/notifier-server/src/main.rs - Health API · GET /health and GET /ready surface service liveness and reconciliation state
apps/notifier-server/src/main.rs - Reconciler · Ensures required source subscriptions exist before readiness is reported
apps/notifier-server/src/main.rs - Ingestion · Accepts webhook or polled events, renders messages, and persists accepted rows
apps/notifier-server/src/main.rs - Delivery workers · Consumes queued rows and delivers them to destinations with retries and backoff
apps/notifier-server/src/main.rs
Runtime
Shared config, storage, and templating
- Runtime core · Shared runtime crate used by the server and plugins
crates/notifier-runtime/src/lib.rs - Config model · Loads, validates, and reconciles configuration and route definitions
crates/notifier-runtime/src/config.rs - SQLite store · Persistent event queue and state store for accepted notifications
crates/notifier-runtime/src/storage.rs - Template engine · MiniJinja-based rendering for route messages and schema docs
crates/notifier-runtime/src/template.rs
Sources
Ingress plugins for provider events
- Twitch source · Webhook-driven source plugin with source-specific deduplication and callback handling
plugins/sources/twitch/src/lib.rs - TwitCasting source · Webhook-driven source plugin with provider-specific callback and deduplication logic
plugins/sources/twitcasting/src/lib.rs - Nitter source · RSS polling source plugin that discovers events in the background
plugins/sources/nitter/src/lib.rs
Destinations
Egress plugins for provider delivery
- Discord destination · Thin binding around the Discord SDK with routing and policy logic
plugins/destinations/discord/src/lib.rs - Telegram destination · Thin binding around the Telegram SDK with routing and policy logic
plugins/destinations/telegram/src/lib.rs
Ops
Operator docs, example config, and CI
- Schema command · Operator command for schema and template-variable documentation
apps/notifier-server/src/main.rs - Example config · Reference configuration for operators
config.example.json - Build CI · Rust formatting, linting, and test validation in GitHub Actions
.github/workflows/build.yml
Connections 23
- Notifier server → Runtime core: uses · Server depends on shared runtime services
- Notifier server → Config model: loads · Startup loads and validates config once
- Notifier server → SQLite store: persists · Accepted events are written to SQLite before success
- Notifier server → Template engine: renders · Route messages are rendered at ingestion time
- Notifier server → Health API: exposes · HTTP service exposes health and readiness endpoints
- Notifier server → Reconciler: reconciles · Startup reconciles configured sources before ready
- Notifier server → Ingestion: accepts · Ingress path accepts provider events
- Notifier server → Delivery workers: dispatches · Background workers deliver queued rows asynchronously
- Notifier server → Schema command: provides · CLI surface includes schema documentation command
- Config model → Twitch source: binds · Config maps routes to Twitch source instances
- Config model → TwitCasting source: binds · Config maps routes to TwitCasting source instances
- Config model → Nitter source: binds · Config maps routes to Nitter source instances
- Config model → Discord destination: binds · Config maps routes to Discord destination instances
- Config model → Telegram destination: binds · Config maps routes to Telegram destination instances
- Ingestion → Template engine: renders · Messages are shaped through MiniJinja templates
- Ingestion → SQLite store: stores · Rendered events are queued durably in SQLite
- Delivery workers → Discord destination: sends · Workers deliver queued messages to Discord
- Delivery workers → Telegram destination: sends · Workers deliver queued messages to Telegram
- Reconciler → Twitch source: subscribes · Ensures Twitch webhook subscriptions exist
- Reconciler → TwitCasting source: configures · Validates and preserves TwitCasting callback setup
- Nitter source → Ingestion: polls into · Background polling feeds events into ingestion
- Twitch source → Ingestion: emits · Webhook events enter the shared ingestion pipeline
- TwitCasting source → Ingestion: emits · Webhook events enter the shared ingestion pipeline