pub struct SessionInitClient { /* private fields */ }Expand description
The communication client’s half of session initiation.
use s2_kit::connect::proto::{AccessToken, NodeId, SessionInitClient, TokenStore};
let store = TokenStore::new(AccessToken::from_entropy(&[1u8; 32])?);
let mut client = SessionInitClient::new(NodeId::parse("rm-1")?, NodeId::parse("cem-1")?, store);
let (bearer, body) = client.initiate()?;
assert_eq!(body.client_node_id.to_string(), "rm-1");Implementations§
Source§impl SessionInitClient
impl SessionInitClient
Sourcepub fn new(
client_node_id: NodeId,
server_node_id: NodeId,
tokens: TokenStore,
) -> Self
pub fn new( client_node_id: NodeId, server_node_id: NodeId, tokens: TokenStore, ) -> Self
A client for one pairing.
Sourcepub fn allowing_insecure_websocket(self) -> Self
pub fn allowing_insecure_websocket(self) -> Self
Accept a plaintext ws:// websocketUrl — for a loopback test and nothing else.
S2C §Encrypted connection: “S2 MUST NOT be sent over unencrypted channels.
Therefore a wss connection … must be used.” The communication token is a bearer;
over ws:// anyone on the path can read it and the session it opens.
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 initiate(
&mut self,
) -> Result<(AccessToken, SessionRequest), ConnectError>
pub fn initiate( &mut self, ) -> Result<(AccessToken, SessionRequest), ConnectError>
Build initiateSession, with the bearer to send it under.
A completed initiation is a legitimate place to start another: every reconnection
needs fresh credentials, because a communication token authorises exactly one
connection and lives thirty seconds. Requiring Self::restart in between would
make the common path the one a caller forgets.
Handle a 401 on initiateSession by moving to the next stored token.
S2C §Recovery: “It should try all the accessTokens sequentially.” When they are
exhausted the pairing really is gone, and this returns ConnectError::NotPaired
— which is a call to a human, not a retry.
Sourcepub fn accept(
&mut self,
grant: SessionGrant,
now: Timestamp,
) -> Result<(), ConnectError>
pub fn accept( &mut self, grant: SessionGrant, now: Timestamp, ) -> Result<(), ConnectError>
Take the grant and store the replacement token.
Storing before confirming is the order the specification requires, and the reason the two requests exist at all: a client that confirmed first and stored afterwards has a window in which a crash loses the replacement for good.
now starts the PENDING_TOKEN_LIFETIME clock on this side too, so a client
that was suspended between the two requests declines to retire the token it
already had rather than retiring it against a server that never activated the
replacement.
Sourcepub fn confirm(&mut self) -> Result<AccessToken, ConnectError>
pub fn confirm(&mut self) -> Result<AccessToken, ConnectError>
The bearer for confirmAccessToken: the new token.
Presenting it is the confirmation, which is why there is no body.
Sourcepub fn connected(
&mut self,
details: CommunicationDetails,
now: Timestamp,
) -> Result<SessionCredentials, ConnectError>
pub fn connected( &mut self, details: CommunicationDetails, now: Timestamp, ) -> Result<SessionCredentials, ConnectError>
Take the communication details the confirmation returned.
The old tokens are retired here and not before: the server has just proved it accepted the new one.
Sourcepub fn restart(&mut self)
pub fn restart(&mut self)
Start again after a failure, keeping whatever tokens survived.
This is what makes the two-phase commit worth having: after any failure at all, the store still holds a token the server will accept.
Sourcepub fn unpaired(&mut self) -> UnpairRequest
pub fn unpaired(&mut self) -> UnpairRequest
Forget the pairing. What a NoLongerPaired means.
Sourcepub fn tokens(&self) -> &TokenStore
pub fn tokens(&self) -> &TokenStore
The tokens, to persist.