Module pubsub 

Pubsub watch — the receiver side of v1.3’s :gsoc-mine and :pss-target writer verbs. PSS topic subscriptions and GSOC (owner, identifier) subscriptions both connect to a Bee WebSocket and emit message frames whenever a publisher hits the corresponding /pss/send / SOC-upload endpoint.

The S15 Pubsub screen renders a merged timeline of all active subscriptions; this module owns the subscription metadata + the PubsubMessage shape that flows between the background watcher tasks and the screen via an mpsc channel in App.

Structs

HistoryFile

State backing the optional pubsub-history JSONL file. Tracks the current write offset so the writer can rotate at a configured size threshold without an extra metadata() syscall per append. Held inside an Arc<Mutex<_>> so every watcher task shares the same file handle + offset and serialises through the mutex.

PubsubMessage

One delivered message — what the screen renders as a row. Encodes both PSS (topic-keyed) and GSOC (address-keyed) variants in a single shape so the merged timeline can render them together, distinguished by PubsubKind in the row glyph.

Enums

PubsubKind

Constants

MAX_MESSAGES

Maximum number of messages the screen retains. Older messages are evicted from the front (VecDeque-style) so the cockpit’s memory stays bounded even on a noisy topic.

Functions

ascii_preview

Convert a small byte payload to a printable-ASCII preview. Replaces non-printable bytes with .. Caps at cap characters. Used by the screen renderer for the inline content peek.

gsoc_sub_id

hex_preview

Hex-prefix preview for binary payloads (when ASCII is mostly dots). Caps at cap characters of hex (so cap/2 bytes).

open_history_writer

Open path for append (O_CREATE | O_APPEND), creating it if it doesn’t exist. rotate_size_bytes and keep_files configure rotation: when a fresh append makes the file cross the size threshold, the active file is renamed to path.1 (older rotations shift to .2, .3, …, .keep_files; oldest is dropped) and a new empty file takes its place. Pass rotate_size_bytes = 0 to disable rotation. Errors are surfaced to the caller so cockpit startup can log a clear “history file disabled: ” message and keep the live tail going.

parse_history_line

Parse one JSONL history line into a PubsubMessage. Public only for tests; the writer’s format is the contract.

pss_sub_id

Identity for an active subscription. Used as the key in App’s pubsub_subs hashmap so re-issuing :pubsub-pss <topic> for an already-subscribed topic is detectable + cancellable.

replay_history_file

Read a previously-written pubsub history file back into a vector of PubsubMessages for replay onto the S15 timeline. Lines that fail to parse are logged + skipped so a single corrupt line doesn’t kill the whole replay. Caps the return at MAX_MESSAGES (the most recent N lines), since the screen can only render that many anyway. Returned in chronological order (oldest → newest).

smart_preview

Pick the smarter of ascii_preview / hex_preview for a payload — ASCII when ≥ 75% of the bytes are printable, hex otherwise. Pure for testability.

spawn_gsoc_watcher

Spawn a background task that drives a GSOC subscription’s recv() loop. Same shape as spawn_pss_watcher.

spawn_pss_watcher

Spawn a background task that drives a PSS subscription’s recv() loop and forwards every delivered message into tx as a PubsubMessage until cancel fires. Returns immediately after subscribe succeeds; the actual recv loop runs on tokio. history is the optional shared writer that appends every frame to a JSONL file on arrival.

Type Aliases

HistoryWriter

Optional history-file handle shared by every active subscription. None when [pubsub].history_file is unset; Some(handle) when the operator opted in. JSONL appends and rotation are serialised through the mutex so concurrent watchers don’t tear lines.