rays
dd91602a49
Reviewing what production's traces and metrics leave out turned up twelve gaps; each is an issue. Metrics. A Prometheus histogram for ipx and the directory both (ipx_directory::metrics::Histograms), which ipx's request histogram (#364) now uses too. - ipx: each statement's time once it has a connection, by its first word, from SeaORM's metric callback; and the wait for one, for hand-written SQL in db.rs, measured as the call less the statement (the callback runs in the poll that returns the result, so the time read after the await is that statement's) (#367). SeaORM's own queries are timed but their wait is not seen: a shortcut, noted. - ipx: counters of what the events say, counted in emit, which every event passes once: feed failures by error.type, new items, downloads saved and failed, DeadAir's seconds found (#368). - ipx: the page's list_shown, play_start and stall timings (#369). - directory: requests by method, route (a route layer puts the matched route on the response, or each feed's page was a row) and status; feeds checked and failed; snapshots taken (#370). - ipx-web: Caddy's own metrics on METRICS_BIND (:9180), served apart from the port the tunnel reaches. `servers { metrics }`, which Caddy 2.11 calls deprecated, because the browser tests' Caddy is 2.6 (#371). Traces. - A list's sync is list_sync with steps, an OPML upload opml_import (#372). Doing so showed sync_group reading every account and its subscription to the list once per listed feed; read once now (#377). - Each command the worker runs, from the socket, the CLI or the page, is a command span with its job inside (#373). - The daemon's start is a trace, from opening the database through the catalogue's repairs to "daemon started" (#374). - The directory's lines carry trace_id and span_id: WithTrace moves to ipx_directory::otel and both use it (#375). - A tap or key is its trace's root span (#376). The page names a root span id in each request's traceparent, where the parent was random and pointed at nothing, and reports the tap (ids, start, its last answer) when the next begins or the page is hidden. opentelemetry 0.33 gives a span builder no way to take ids, so the shared tracer provider has an id generator that takes given ids inside with_ids, on one thread. Alerts. grafana/alerts.py, Grafana alerting provisioning beside the dashboard (#365): ipx, the directory or ipx-web down, scans stopped, a job over 30 minutes, the pool full, 5xx, 502s, Jev refused, Signals stopped, the directory's refresher stopped, Tower's load and memory, the monitoring down, Tempo not reading its blocks, iPX's lines not reaching Loki. No contact point yet: firing shows in Grafana. Prometheus now scrapes Tempo, Loki, Alloy and itself (#366), in the monitoring project's config, not this repository's. The dashboard has database and page-timing panels; the prod check knows the new metrics, spans and alerts. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ipx
A self-hosted podcatcher for a household. It checks your feeds, downloads the episodes, and serves
a web UI modelled on the 2004 Mac app iPodderX, for any number of people sharing one copy of
the files. One Rust binary, ipx, is both the daemon and the command line.
It is a rewrite of ipodderx-core, the Python engine behind iPodderX (2004-2008, Ray Slakinski & August Trometer).
What it does
- The web UI. It has a toolbar, and a feed list that opens with the Directory, Currently Listening and All Subscriptions. Items sit in a sortable table with a Files pane, and there is a player bar. It comes in Dark, Light and Classic themes, and works on a phone.
- Several people, one copy. Each person has their own subscriptions and their own read, pinned and playback state. There is one file on disk per episode, however many people want it. People sign in with a password or through a proxy (Cloudflare Zero Trust or Authentik), and admins manage accounts and settings.
- Scanning. Feeds are checked on a schedule, globally or per feed, and a feed's own TTL is honoured. Keyword, explicit-content and media-type filters decide what is downloaded, with a limit on how many of a feed's newest episodes are downloaded.
- Downloads. Files come over HTTP or BitTorrent and are filed into a folder per feed. Retention deletes the oldest files to stay under a disk quota or an age limit, and never touches an item someone has pinned.
- OPML. You can import and export your own subscriptions. You can also subscribe to an OPML URL, which keeps a whole list in step as a folder.
Run it
With Docker:
docker build -t ipx .
docker build -f Dockerfile.web -t ipx-web .
docker compose up -d
docker-compose.yml is a sample: ipx, with its database in SQLite and its three volumes
(/config, /data and /downloads) in folders beside the file, and ipx-web, the page, served by
Caddy in front of it. Change them to suit. The UI is on port 8099. BitTorrent uses 6881
over TCP and UDP. Files are written as PUID/PGID, 99:100 by default.
From source:
cargo build --release
./target/release/ipx daemon
The first start creates admin with a random password, written to admin-password beside
config.toml (readable by ipx's user alone; the log says where, never what it is). Set
IPX_ADMIN_PASSWORD to choose it instead. Sign in at /login, then change it:
echo -n 'a good password' | ipx user passwd admin
The UI is plain HTTP, so put TLS in front of it if it is reachable from outside your network.
Documentation
| docs/configuration.md | Every config key, path and environment variable |
| docs/cli.md | Every command, including ipx user |
| docs/users.md | Accounts, and what several people share |
| docs/sso.md | Signing in through Cloudflare Zero Trust or Authentik |
| docs/architecture.md | How it works: modules, schema, control socket, HTTP API |
| crates/ipx/CHANGELOG.md, web/CHANGELOG.md, crates/directory/CHANGELOG.md | What changed, by release, for ipx, the page and the directory |
| CLAUDE.md | Notes for working on the code, including how production is deployed |
Tests
cargo test # the engine: parsing, filters, retention, schedules, SQL, per-user state
node tests/page-smoke.js # the page script loads without throwing
node tests/native-bridge.js # the page hands playback to a native shell
npx playwright test # a real browser against a real daemon on fixture feeds
npm install gets the test runner, and npx playwright install --with-deps chromium gets the
browser.
License
MIT, see LICENSE. The icons are Font Awesome Free 7.3.1 by @fontawesome, under CC BY 4.0, embedded as SVG.