Module session 

Holding a session valid: refresh-on-read, rotation, and what a failure means.

Three things here are easy to get wrong and all three present as random logouts rather than as a bug:

• Refresh tokens rotate and are single-use. The new one must be stored atomically with the new access token, and a response that omits it means keep the old one — not store an empty string.
• Concurrent refreshes must be serialized. Two readers of the same session both presenting the same single-use token means the second gets invalid_grant, and most authorization servers revoke the first one’s freshly issued tokens along with it. The scheduler plus one user request is already enough concurrency.
• Only invalid_grant invalidates. Deleting on a network blip or a 5xx logs people out for a server hiccup; treating a dead grant as transient retries forever and never prompts a re-login.

Structs

RefreshContext

What a refresh needs beyond the session itself.

RefreshLocks

Per-subject refresh locks.

Functions

apply_refresh

Fold a refresh response into the stored session.

same_issuer

Refuse a re-discovered issuer that is not the one the grant belongs to.

valid_session

Read a session, refreshing it first if it is close to expiry.