Components¶
Angelia is one binary with several roles. A homelab runs all of them in one process; a larger install runs more replicas of the busy ones against Postgres. The internal boundaries are Go packages, not network hops, so there is no broker to run.
angelia serve --roles=all # the default
angelia serve --roles=api # one process per role, on Postgres
angelia serve --roles=scheduler,dispatcher
The roles¶
- API
- The REST API (
/v1/), the SSE event stream and the MCP endpoint, all behind bearer tokens. It also applies the watch file at startup. Contract-first: the OpenAPI document is the source of truth, and the CLI is a client of it. - Scheduler
- Every target has a
next_check_at. The scheduler leases due targets from the database and asks the source for its versions, with per-host rate limits, jitter, backoff and conditional requests (anETaganswered304costs almost nothing). Fifty watches onpypi:requestsmean one fetch: watches share a target. - Diff and policy engine
- Compares the fetched versions with the known set, so it catches every new version, including a backport
such as
1.9.4released after2.0.0. Parses each version with its scheme (SemVer, PEP 440, calver, lexical), computes the bump, applies the policy, and writes the event and one delivery per matching subscription in the same transaction. - Dispatcher
- Leases due deliveries and hands them to sinks. At-least-once, exponential backoff with jitter (eight
attempts over about a day), then a dead letter you can inspect and replay.
Each delivery carries the idempotency key
<event id>:<subscription id>.
Sources and sinks¶
Sources are deliberately dumb: they list raw upstream versions and an opaque fetch state. Everything clever (diffing, parsing, filtering, cooldown) happens once, in the core, the same way for every ecosystem.
| Built in today | |
|---|---|
| Sources | pypi, npm, crates, github-release, github-tag, gitlab-release, and any of them pointed at a private registry |
| Sinks | webhook, github-dispatch, shoutrrr (Slack, Discord, Telegram, ntfy, Gotify, Matrix) |
| Pull | GET /v1/events with consumer cursors, GET /v1/events/stream (SSE), MCP |
Planned, not shipped
OCI images, Maven, the Go module proxy, generic HTTP JSON and regex sources, NATS and MQTT sinks, and third-party plugins (WASM) are on the roadmap in the architecture document. They do not exist in v0.2.0.
Storage¶
| Store | When |
|---|---|
| SQLite | the default: one process, one file, nothing to run |
| Postgres | several replicas: scheduler and dispatcher lease with FOR UPDATE SKIP LOCKED |
The event log is append-only. Events and deliveries are separate rows: one event, many deliveries, each with its own retry state, so a slow chat service never delays your CI.
Observability¶
/healthz and /readyz for probes, Prometheus metrics at /metrics on the same port, JSON logs by default,
and OpenTelemetry tracing. A Grafana dashboard ships in
deploy/grafana.