Skip to main content

Session

Struct Session 

Source
pub struct Session { /* private fields */ }
Available on crate feature 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

Source

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.

Source

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.

Source

pub fn with_s2_message_versions(self, versions: Vec<ProtocolVersion>) -> Self

Offer a different set of S2 JSON message versions, newest first.

Source

pub fn tokens(&self) -> &TokenStore

The tokens, to persist. Read this after every Self::initiate.

Source

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.

Every other failure leaves this session ready for the next attempt — after backoff — with whatever tokens survived, because S2C §Reconnection strategy says the client “must try to reconnect”. A NoLongerPaired is the exception: the pairing is gone, the tokens are cleared, and only a new pairing helps.

Source

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.

Source

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.

Source

pub fn reset_backoff(&mut self)

Give up on the current run of failures, so the next one starts from two seconds again.

Source

pub fn access_token(&self) -> Option<&AccessToken>

A token that has been refused, so the next attempt does not start from the top.

Trait Implementations§

Source§

impl Debug for Session

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
where ST: ?Sized, DT: ?Sized,

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Read<Exclusive, BecauseExclusive> for T
where T: ?Sized,

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more