Files
2026-10-19 14:14:29 -04:00

3.2 KiB

WS-B — journal source

Field Value
Status Done
Owner —
Phase 1 (parallel)
Depends on P0 (incl. spike findings on the systemd crate)
Blocks WS-E, WS-F, WS-G (to finish)
Owned files src/sources/journal.rs, examples/journal_tail.rs

Goal

Implement JournalSource over sd-journal via the systemd crate. It provides a bounded snapshot query and a cancellable live follow.

Tasks

Tick these in TODO.md.

  • B1 Run every sd-journal call inside tokio::task::spawn_blocking (review G1). Open the journal inside the blocking closure and never hold it across .await. Use sources.journal_namespace if the spike found namespace support. Otherwise log a warning when it is set and use the default journal.
  • B2 query(JournalQuery):
    • Unit filter via match_add("_SYSTEMD_UNIT", unit).
    • Priority filter ≤ N by adding one PRIORITY=k match for each k in 0..=N. Matches on the same field are OR'ed by sd-journal.
    • seek_tail, then step backward lines entries. lines is clamped to limits.max_lines.
    • Reverse the result so it returns oldest-first.
  • B3 follow(JournalQuery, CancellationToken) -> mpsc::Receiver<JournalEntry>:
    • Seek to tail and run a blocking loop of wait(Some(500ms)), then drain new entries with next.
    • Each iteration checks tx.is_closed() and token.is_cancelled() and exits if either is true (review G2).
    • Use blocking_send with a bounded channel, around 1024 entries. Decide on drop-or-block for slow consumers and document it.
  • B4 Map __REALTIME_TIMESTAMP, PRIORITY, _SYSTEMD_UNIT, SYSLOG_IDENTIFIER, _PID, _HOSTNAME and MESSAGE to JournalEntry. MESSAGE may be binary, so convert it with lossy UTF-8.
  • B5 examples/journal_tail.rs --unit X [--priority err] [--lines N] [--follow].
  • B6 Test that dropping the receiver makes the blocking thread exit within about one second. Use a counter or JoinHandle to prove it.

Done when

  • The example snapshot output matches journalctl -u X -p err -n N -o json for the same filters.
  • Follow prints new entries live. logger -t test hello shows up in under a second.
  • B6 passes.

Notes

  • Reading the full system journal needs the systemd-journal group (or root). Without it you only see your own user's entries. Say so in the example's error output.
  • If the systemd crate turns out unmaintained or broken during the spike, record the alternative in the P0 log before starting.

Log

  • 2026-10-15: Card created.
  • 2026-10-15: Implemented B1-B6 on branch ws-b/journal-source. Query and follow verified on the live host. Unit filter matches _SYSTEMD_UNIT only; UNIT is used only as a fallback when mapping entries. Follow applies backpressure (no drops). since is applied during the backward backlog scan.
  • 2026-10-15: Review fixes: unit filter is now (_SYSTEMD_UNIT=u OR UNIT=u), with PRIORITY matches repeated per disjunct. Verified against journalctl -u hyprland-headless.service style PID1 lines (same 5 entries, same timestamps). Offline unit tests cover match plan, ordering, since, and send exit on drop/cancel. Live follow tests are #[ignore]: cargo test -- --ignored live_.