pub struct TokenStore { /* private fields */ }Expand description
The access tokens a paired node holds, newest first, and the rules that govern them.
This is the piece that makes the pairing survivable. Storing a list rather than one
token is why a dropped reply is a retry instead of a service call — and the list is
what S2C §Recovery asks for: “It now has (at least) two accessTokens in its list, and
does not know for certain which one is active at the communication server. It should
try all the accessTokens sequentially.”
Each entry remembers whether it is already in force or is a grant still waiting to be
confirmed, because only the second kind expires — after
PENDING_TOKEN_LIFETIME, which is what stops a confirmation that arrives an hour
late from retiring a token that still works.
Implementations§
Source§impl TokenStore
impl TokenStore
Sourcepub const MAX: usize = 4
pub const MAX: usize = 4
How many tokens are kept before the oldest is dropped.
Each failed round trip adds one. Four is well past the two the protocol produces in the worst ordinary case, and bounds what a peer can make us store.
Sourcepub fn new(current: AccessToken) -> Self
pub fn new(current: AccessToken) -> Self
A store holding the token pairing produced.
Sourcepub fn accepts(&self, presented: &AccessToken) -> bool
pub fn accepts(&self, presented: &AccessToken) -> bool
Whether a presented token opens the door.
Any token in the list is accepted, because the client may hold any of them and the alternative to accepting it is a dead pairing.
Sourcepub fn add(&mut self, token: AccessToken, now: Timestamp)
pub fn add(&mut self, token: AccessToken, now: Timestamp)
Record a replacement granted at now and not yet confirmed.
It joins the list rather than replacing it, because until the client proves it has
stored the new token both must open the door (S2C §Recovery). What now buys is
the other half of the rule: confirm will not activate a grant
the client sat on for more than PENDING_TOKEN_LIFETIME.
Sourcepub fn adopt(&mut self, token: AccessToken)
pub fn adopt(&mut self, token: AccessToken)
Record a token that is already in force, such as the one pairing produced.
Sourcepub fn confirm(
&mut self,
token: &AccessToken,
now: Timestamp,
) -> Result<(), ConnectError>
pub fn confirm( &mut self, token: &AccessToken, now: Timestamp, ) -> Result<(), ConnectError>
Activate a granted token and retire every other, as confirmAccessToken does.
Called when the client proves it holds one — by presenting it as the bearer of
confirmAccessToken — which is what makes retiring the others safe.
§Errors
ConnectError::NotPaired when the token is not one this store holds;
ConnectError::Expired when it was granted more than
PENDING_TOKEN_LIFETIME ago and so is no longer confirmable. An expired grant
leaves the store untouched, so whatever the client held before still works.
Sourcepub fn is_pending(&self, presented: &AccessToken) -> bool
pub fn is_pending(&self, presented: &AccessToken) -> bool
Whether a presented token is a grant this store issued and has not yet seen confirmed.
confirmAccessToken must be authenticated with the replacement, not with any
token the store happens to accept: presenting the replacement is the proof the
client stored it, and that proof is the only reason retiring the others is safe.
Sourcepub fn current(&self) -> Option<&AccessToken>
pub fn current(&self) -> Option<&AccessToken>
The token to present next: the newest.
Sourcepub fn candidates(&self) -> impl Iterator<Item = &AccessToken>
pub fn candidates(&self) -> impl Iterator<Item = &AccessToken>
Every token to try, newest first.
A client that got a 401 works down this list before concluding it is unpaired.