open_net/api/net_status/events.rs
1use super::{NetworkSnapshot, NetworkStatus};
2
3/// One committed event in a named monitor's ordered observation stream.
4#[derive(Clone, Debug)]
5pub struct NetworkEvent {
6 /// Monotonic event cursor for this named monitor. Initial carries its current cursor.
7 pub sequence: u64,
8 /// Local activation generation. Stop/restart never reuses an earlier generation.
9 pub generation: u64,
10 /// Revision of the engine's shared observation associated with this event.
11 pub source_revision: u64,
12 /// The same local snapshot exposed by `NetStatusClient::snapshot` at this commit.
13 pub snapshot: NetworkSnapshot,
14 /// Initial, observation, reachability transition, or lifecycle notification.
15 pub kind: NetworkEventKind,
16}
17
18/// An ordered event or a new atomic baseline after this observer overflowed.
19/// Reconciliation identifies a delivery gap; it does not replay missed events.
20#[non_exhaustive]
21#[derive(Clone, Debug)]
22pub enum NetworkObservation {
23 /// An original event, including the first atomic Initial baseline.
24 Event(NetworkEvent),
25 /// The last event delivered before a gap and the replacement's Initial.
26 /// Compare loss epochs only within one generation; a changed generation
27 /// requires a new application baseline. Delivery does not imply that work
28 /// dispatched by the previous callback has finished.
29 Reconciled {
30 previous: NetworkEvent,
31 current: NetworkEvent,
32 },
33}
34
35/// Lifecycle notifications never manufacture a network disconnection.
36#[non_exhaustive]
37#[derive(Clone, Copy, Debug, Eq, PartialEq)]
38pub enum NetworkEventKind {
39 /// Atomic subscription baseline; all later events follow this cursor.
40 Initial,
41 /// The first usable observation after activation or monitor initialization.
42 ObservationReady,
43 /// A committed transition between two known reachability values.
44 ReachabilityChanged {
45 previous: NetworkStatus,
46 current: NetworkStatus,
47 },
48 /// Starting, stopping, failure, or permanent shutdown.
49 LifecycleChanged,
50}
51
52/// Per-subscriber bounds. A full queue disconnects only that subscriber after
53/// its retained prefix, reporting `ReceiveError::Failed` with `CallbackOverflow`.
54/// An individual event larger than `max_bytes` ends it with `ItemTooLarge`.
55#[derive(Clone, Copy, Debug)]
56pub struct NetworkEventOptions {
57 /// Maximum queued events, including the initial baseline.
58 pub capacity: usize,
59 /// Maximum accounted event bytes, including owned network-name strings.
60 pub max_bytes: usize,
61}
62
63impl Default for NetworkEventOptions {
64 fn default() -> Self {
65 Self {
66 capacity: 256,
67 max_bytes: 256 * 1024,
68 }
69 }
70}