Struct VCLConnection 

pub struct VCLConnection { /* private fields */ }

A secure VCL Protocol connection over UDP.

Each connection manages its own cryptographic state: independent send/receive hash chains, nonce tracking, shared secret, and Ed25519 key pair.

Example — Server

use vcl_protocol::connection::VCLConnection;

#[tokio::main]
async fn main() {
    let mut server = VCLConnection::bind("127.0.0.1:8080").await.unwrap();
    server.accept_handshake().await.unwrap();

    loop {
        match server.recv().await {
            Ok(packet) => println!("{}", String::from_utf8_lossy(&packet.payload)),
            Err(e)     => { eprintln!("{}", e); break; }
        }
    }
}

Example — Client

use vcl_protocol::connection::VCLConnection;

#[tokio::main]
async fn main() {
    let mut client = VCLConnection::bind("127.0.0.1:0").await.unwrap();
    client.connect("127.0.0.1:8080").await.unwrap();
    client.send(b"Hello!").await.unwrap();
    client.close().unwrap();
}

Implementations

impl VCLConnection

pub async fn bind(addr: &str) -> Result<Self, VCLError>

Bind a new VCL connection to a local UDP address.

Use "127.0.0.1:0" to let the OS assign a port (typical for clients).

Errors

Returns VCLError::IoError if the socket cannot be bound.

pub fn subscribe(&mut self) -> Receiver<VCLEvent>

Subscribe to connection events.

Returns an async mpsc::Receiver<VCLEvent> with a channel capacity of 64. Call this before connect() or accept_handshake() to receive the VCLEvent::Connected event.

Events are sent with try_send — if the channel is full, events are dropped silently.

pub fn set_timeout(&mut self, secs: u64)

Set the inactivity timeout in seconds (default: 60).

If no send() or recv() occurs within this duration, the next operation returns VCLError::Timeout. Set to 0 to disable the timeout.

pub fn get_timeout(&self) -> u64

Get the current inactivity timeout in seconds.

pub fn last_activity(&self) -> Instant

Get the Instant of the last send() or recv() activity.

pub fn set_shared_key(&mut self, private_key: &[u8])

Override the Ed25519 signing key with a pre-shared key.

⚠️ For testing only. Never use a pre-shared key in production.

pub async fn connect(&mut self, addr: &str) -> Result<(), VCLError>

Connect to a remote VCL server and perform the X25519 handshake.

After this returns Ok(()), the connection is ready to send() and recv(). Emits VCLEvent::Connected if subscribed.

Errors

• VCLError::IoError — socket or address error
• VCLError::HandshakeFailed — key exchange failed
• VCLError::ExpectedServerHello — unexpected handshake message

pub async fn accept_handshake(&mut self) -> Result<(), VCLError>

Accept an incoming X25519 handshake from a client (server side).

Blocks until a ClientHello is received. After this returns Ok(()), the connection is ready to send() and recv(). Emits VCLEvent::Connected if subscribed.

Errors

• VCLError::IoError — socket error
• VCLError::HandshakeFailed — key exchange failed
• VCLError::ExpectedClientHello — unexpected handshake message

pub async fn send(&mut self, data: &[u8]) -> Result<(), VCLError>

Encrypt, sign, and send a data packet to the peer.

Errors

• VCLError::ConnectionClosed — connection was closed
• VCLError::Timeout — inactivity timeout exceeded
• VCLError::NoSharedSecret — handshake not completed
• VCLError::NoPeerAddress — peer address unknown
• VCLError::IoError — socket error

pub async fn ping(&mut self) -> Result<(), VCLError>

Send a ping to the peer to check liveness and measure round-trip latency.

The pong reply is handled transparently inside recv() — you never see Pong packets directly. Subscribe to events to receive VCLEvent::PongReceived { latency }.

⚠️ You must keep calling recv() for the pong to be processed.

Errors

Same as send().

pub async fn rotate_keys(&mut self) -> Result<(), VCLError>

Initiate a mid-session key rotation using a fresh X25519 ephemeral exchange.

Sends our new public key to the peer (encrypted with the current key), waits for the peer’s new public key, and atomically switches to the new shared secret on both sides.

Emits VCLEvent::KeyRotated on success.

⚠️ The peer must be actively calling recv() during rotation. ⚠️ Do not call send() while rotate_keys() is awaiting a response.

Errors

• VCLError::ConnectionClosed / VCLError::Timeout
• VCLError::ChainValidationFailed / VCLError::SignatureInvalid
• VCLError::HandshakeFailed — unexpected packet type in response
• VCLError::InvalidPacket — malformed public key payload

pub async fn recv(&mut self) -> Result<VCLPacket, VCLError>

Receive the next data packet from the peer.

Control packets (Ping, Pong, KeyRotation) are handled transparently — this method loops internally until a Data packet arrives.

On success, packet.payload contains the decrypted data.

Errors

• VCLError::ConnectionClosed — connection was closed
• VCLError::Timeout — inactivity timeout exceeded
• VCLError::ReplayDetected — duplicate sequence or nonce
• VCLError::ChainValidationFailed — hash chain broken
• VCLError::SignatureInvalid — Ed25519 signature mismatch
• VCLError::CryptoError — decryption failed
• VCLError::IoError — socket error

pub fn close(&mut self) -> Result<(), VCLError>

Gracefully close the connection and clear all cryptographic state.

After calling close(), all further operations return VCLError::ConnectionClosed. Emits VCLEvent::Disconnected if subscribed.

Errors

Returns VCLError::ConnectionClosed if already closed.

pub fn is_closed(&self) -> bool

Returns true if the connection has been closed.

pub fn get_public_key(&self) -> Vec<u8>

Get the local Ed25519 public key (32 bytes).

pub fn get_shared_secret(&self) -> Option<[u8; 32]>

Get the current X25519 shared secret, or None if the handshake has not completed or the connection is closed.