Skip to main content

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}