3.2 KiB
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. Usesources.journal_namespaceif 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
≤ Nby adding onePRIORITY=kmatch for each k in 0..=N. Matches on the same field are OR'ed by sd-journal. seek_tail, then step backwardlinesentries.linesis clamped tolimits.max_lines.- Reverse the result so it returns oldest-first.
- Unit filter via
- B3
follow(JournalQuery, CancellationToken) -> mpsc::Receiver<JournalEntry>:- Seek to tail and run a blocking loop of
wait(Some(500ms)), then drain new entries withnext. - Each iteration checks
tx.is_closed()andtoken.is_cancelled()and exits if either is true (review G2). - Use
blocking_sendwith a bounded channel, around 1024 entries. Decide on drop-or-block for slow consumers and document it.
- Seek to tail and run a blocking loop of
- B4 Map
__REALTIME_TIMESTAMP,PRIORITY,_SYSTEMD_UNIT,SYSLOG_IDENTIFIER,_PID,_HOSTNAMEandMESSAGEtoJournalEntry.MESSAGEmay 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
JoinHandleto prove it.
Done when
- The example snapshot output matches
journalctl -u X -p err -n N -o jsonfor the same filters. - Follow prints new entries live.
logger -t test helloshows up in under a second. - B6 passes.
Notes
- Reading the full system journal needs the
systemd-journalgroup (or root). Without it you only see your own user's entries. Say so in the example's error output. - If the
systemdcrate 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_UNITonly;UNITis used only as a fallback when mapping entries. Follow applies backpressure (no drops).sinceis 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.servicestyle 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_.