Session Lifecycle

A session is an encrypted channel between two paired peers. Sessions handle connection management, automatic reconnection, and forward-secret message delivery.

Connection States

Sessions move through a simple state machine:

connecting -> connected -> reconnecting -> connected
                                        \-> disconnected

State	Description
connecting	Noise XX handshake in progress
connected	Session active, messages can be sent and received
reconnecting	Transport dropped, attempting to re-establish
disconnected	Session ended or reconnection failed

Automatic Reconnection

When a transport drops (e.g., switching from WiFi to cellular), sessions automatically attempt to reconnect. Key properties:

• Double Ratchet state is preserved -- no re-pairing is needed. The ratchet picks up where it left off.
• Transport-agnostic -- sessions persist across transport changes. A connection that started over WebRTC can resume over a relay, or vice versa.
• Transparent to your app -- messages sent during reconnection are queued and delivered once the session is re-established.

Event Handling for State Changes

Listen for StateChanged events to update your UI or trigger application logic when a session's state changes.

Rust

let mut events = node.subscribe();
while let Some(event) = events.recv().await {
    match event {
        Event::StateChanged { peer_id, state } => {
            println!("Peer {} state: {:?}", peer_id, state);
        }
        _ => {}
    }
}

TypeScript

node.on('session_state', (peerId, state) => {
    console.log(`Peer ${peerId} state: ${state}`);
});

Go

for event := range node.Events() {
    if sc, ok := event.(cairn.StateChangedEvent); ok {
        fmt.Printf("Peer %s state: %s\n", sc.PeerID, sc.State)
    }
}

Python

async for event in node.events():
    if event.type == NodeEventType.STATE_CHANGED:
        print(f"Peer {event.peer_id} state: {event.state}")

PHP

$node->on('session_state', function (string $peerId, string $state) {
    echo "Peer $peerId state: $state\n";
});

The state value is one of: connecting, connected, reconnecting, disconnected.

Session Properties

You can inspect a session's current state and the peer it is connected to.

Rust

let session = node.connect(&peer_id).await?;
println!("Peer: {}", session.peer_id());
println!("State: {:?}", session.state());

TypeScript

const session = await node.connect(peerId);
console.log(`Peer: ${session.peerId}`);
console.log(`State: ${session.state}`);

Go

session, _ := node.Connect(peerId)
fmt.Println("Peer:", session.PeerID())
fmt.Println("State:", session.State())

Python

session = await node.connect(peer_id)
print(f"Peer: {session.peer_id}")
print(f"State: {session.state}")

PHP

$session = $node->connect($peerId);
echo "Peer: " . $session->peerId() . "\n";
echo "State: " . $session->state() . "\n";