pub struct Session { /* private fields */ }connect-client only.Expand description
Turns a stored pairing into an authorised WebSocket, as often as needed.
One Session is one pairing. It owns the token store, so the rotation the protocol
requires happens whether or not the caller remembers it exists — but the caller must
persist Session::tokens after every Session::initiate, because a token that
only ever lived in memory is a pairing that does not survive a restart.
use s2_kit::connect::client::Session;
use s2_kit::connect::proto::*;
use s2_kit::connect::tls::TlsPolicy;
use s2_kit::types::Timestamp;
let mut session = Session::new(
&paired.pairing.details.initiate_session_url,
&paired.policy(),
paired.pairing.local,
paired.pairing.remote.id,
TokenStore::new(paired.pairing.details.access_token.clone()),
)?;
let credentials = session.initiate(Timestamp::now()).await?;
// Persist the rotated tokens *now*, before connecting.
let to_store = session.tokens();Implementations§
Source§impl Session
impl Session
Sourcepub const REQUEST_TIMEOUT: Duration
pub const REQUEST_TIMEOUT: Duration
How long any single session-initiation request may take.
Well inside the thirty seconds a communication token lives, so that a slow request cannot hand back credentials that have already expired.
Sourcepub fn new(
base_url: &str,
policy: &TlsPolicy,
client_node_id: NodeId,
server_node_id: NodeId,
tokens: TokenStore,
) -> Result<Self, Error>
pub fn new( base_url: &str, policy: &TlsPolicy, client_node_id: NodeId, server_node_id: NodeId, tokens: TokenStore, ) -> Result<Self, Error>
A session for one pairing.
policy should be Paired::policy — the pinned CA for a
LAN peer, the public PKI for a WAN one. Using TlsPolicy::LanPairingOnly here
would leave the channel unauthenticated, so it is refused.
Sourcepub fn with_s2_message_versions(self, versions: Vec<ProtocolVersion>) -> Self
pub fn with_s2_message_versions(self, versions: Vec<ProtocolVersion>) -> Self
Offer a different set of S2 JSON message versions, newest first.
Sourcepub fn tokens(&self) -> &TokenStore
pub fn tokens(&self) -> &TokenStore
The tokens, to persist. Read this after every Self::initiate.
Sourcepub async fn initiate(
&mut self,
now: Timestamp,
) -> Result<SessionCredentials, Error>
pub async fn initiate( &mut self, now: Timestamp, ) -> Result<SessionCredentials, Error>
Run both requests and come back with somewhere to connect.
A 401 on the first is not a failure: the store may hold a token the server has
already retired, so this works down the list the way S2C §Recovery prescribes,
and only gives up when every one has been refused.
Sourcepub async fn unpair(&mut self) -> Result<(), Error>
pub async fn unpair(&mut self) -> Result<(), Error>
Forget the pairing, telling the server so.
The local store is cleared whether or not the server answers: a client that keeps a token for a pairing it has renounced is a client that will keep trying to use it.
Sourcepub fn backoff(&mut self) -> Duration
pub fn backoff(&mut self) -> Duration
How long to wait before the next attempt, after one has failed.
S2C §Reconnection strategy: delay_n = random(0, min(600 s, 2 s × 2^n)). The
randomness is drawn here because a fleet of devices that all reconnect on the same
schedule is a thundering herd; Backoff::delay_with takes it as a parameter for a
test that wants it pinned.
Sourcepub fn reset_backoff(&mut self)
pub fn reset_backoff(&mut self)
Give up on the current run of failures, so the next one starts from two seconds again.
Sourcepub fn access_token(&self) -> Option<&AccessToken>
pub fn access_token(&self) -> Option<&AccessToken>
A token that has been refused, so the next attempt does not start from the top.