vcl_protocol/
event.rs

1//! # VCL Connection Events
2//!
3//! [`VCLEvent`] represents lifecycle and data events emitted by a [`VCLConnection`].
4//!
5//! Subscribe with [`VCLConnection::subscribe`] before calling `connect()` or
6//! `accept_handshake()` to ensure you receive all events including [`VCLEvent::Connected`].
7//!
8//! [`VCLConnection`]: crate::connection::VCLConnection
9//! [`VCLConnection::subscribe`]: crate::connection::VCLConnection::subscribe
10
11use std::time::Duration;
12
13/// Events emitted by a [`VCLConnection`](crate::connection::VCLConnection).
14///
15/// Received via the `mpsc::Receiver<VCLEvent>` returned by
16/// [`VCLConnection::subscribe()`](crate::connection::VCLConnection::subscribe).
17///
18/// # Example
19///
20/// ```no_run
21/// use vcl_protocol::{VCLEvent, connection::VCLConnection};
22///
23/// #[tokio::main]
24/// async fn main() {
25///     let mut conn = VCLConnection::bind("127.0.0.1:0").await.unwrap();
26///     let mut events = conn.subscribe();
27///
28///     tokio::spawn(async move {
29///         while let Some(event) = events.recv().await {
30///             match event {
31///                 VCLEvent::Connected => println!("Ready!"),
32///                 VCLEvent::PongReceived { latency } =>
33///                     println!("Latency: {:?}", latency),
34///                 VCLEvent::Disconnected => break,
35///                 _ => {}
36///             }
37///         }
38///     });
39/// }
40/// ```
41#[derive(Debug, Clone)]
42pub enum VCLEvent {
43    /// Handshake completed — the connection is ready to send and receive data.
44    Connected,
45
46    /// `close()` was called — connection is now shut down.
47    Disconnected,
48
49    /// A data packet was successfully received and decrypted.
50    PacketReceived {
51        /// Sequence number of the received packet.
52        sequence: u64,
53        /// Size of the decrypted payload in bytes.
54        size: usize,
55    },
56
57    /// The peer sent a Ping — a Pong was sent back automatically.
58    PingReceived,
59
60    /// A Pong was received in response to our `ping()` call.
61    PongReceived {
62        /// Measured round-trip time from `ping()` to pong receipt.
63        latency: Duration,
64    },
65
66    /// Mid-session key rotation completed — both sides now use the new shared secret.
67    KeyRotated,
68
69    /// A non-fatal internal error occurred.
70    Error(String),
71}
vcl_protocol/event.rs

vcl_protocol/
event.rs
