pub enum HarnessOperatorEventV1 {
SnapshotBaseline {
sequence: u64,
tasks: Vec<RedactedTaskV1>,
runs: Vec<RedactedRunV1>,
nodes: Vec<HarnessRuntimeNodeInventoryV1>,
},
TaskChanged {
sequence: u64,
task: RedactedTaskV1,
},
RunChanged {
sequence: u64,
run: RedactedRunV1,
},
RuntimeInventoryChanged {
sequence: u64,
node: HarnessRuntimeNodeInventoryV1,
},
RuntimeInventoryRemoved {
sequence: u64,
node_id: String,
},
Lagged {
sequence: u64,
},
Ping {
sequence: u64,
},
}Expand description
Long-lived, server-push counterpart to HarnessOperatorReplyV1. A
SubscribeEvents connection stops replying with a single frame and
instead writes one of these, newline-terminated, per change – see the
module doc for the framing this switches the connection into.
sequence is a per-subscription monotonic counter the host mints for
that one connection alone; it never resets, including across a
Lagged/SnapshotBaseline pair, so a client can detect a gap without
cross-referencing wall time. An auth failure or an over-limit subscribe
never reaches this type at all – both still use the ordinary
single-frame HarnessOperatorReplyV1::Error before the connection
closes, since neither one ever admits a subscription in the first place.
Variants§
SnapshotBaseline
Always the first frame after a successful subscribe, and re-sent as
the recovery frame immediately after a Lagged – the client must
treat this as a full replacement of its task/run/node state, never a
delta against whatever it held before.
Fields
tasks: Vec<RedactedTaskV1>runs: Vec<RedactedRunV1>nodes: Vec<HarnessRuntimeNodeInventoryV1>TaskChanged
RunChanged
RuntimeInventoryChanged
RuntimeInventoryRemoved
Lagged
This subscriber’s outbound queue overflowed and one or more events
were dropped for it specifically – other subscribers are unaffected.
The host always follows this with a fresh SnapshotBaseline once it
can build one; until that frame arrives the client must treat every
task/run/node it is holding as stale rather than trying to patch
around the gap.
Ping
Server-side keep-alive, unconditional and periodic (see
hatchery-harness-service::runtime’s own
HOST_SUBSCRIBER_KEEPALIVE_INTERVAL): the registry’s only way to
discover a dead subscriber is a write to it actually failing, so
without something to push on an otherwise-idle connection an
abandoned subscriber can sit occupying its slot indefinitely (see
SubscriberRegistry’s own doc comment). Deliberately its own
variant rather than reusing an existing one: Lagged carries a
promise (a SnapshotBaseline follows) that a bare keep-alive would
break, and every other variant carries real task/run/node state a
client applies – faking either risks a client acting on a change
that never happened. Ping carries nothing to act on, so it cannot
be mistaken for either; every current reader
(hatchery-harness-client’s generic next_event decode,
hatchery-tui’s project_harness_operator_event) drops it on the
floor by construction. sequence is kept only for schema symmetry
with every other variant – there is no gap to detect against a
keep-alive that carries no state of its own.