Struct Broker 

pub struct Broker<C, M>
where
    C: ?Sized + TokenHttpClient,
    M: ?Sized + TransportErrorMapper<C::TransportError>,
{
    pub http_client: Arc<C>,
    pub transport_mapper: Arc<M>,
    pub store: Arc<dyn BrokerStore>,
    pub descriptor: ProviderDescriptor,
    pub strategy: Arc<dyn ProviderStrategy>,
    pub client_id: String,
    pub client_secret: Option<String>,
    pub refresh_metrics: Arc<RefreshMetrics>,
    /* private fields */
}

Coordinates OAuth 2.0 flows against a single provider descriptor.

The broker owns the HTTP client, token store, provider descriptor, and strategy references so individual flow implementations can focus on grant-specific logic (state + PKCE generation, code exchanges, refresh rotations, etc.). Client credentials are stored alongside the descriptor so client-auth methods can be applied consistently across token endpoints.

Fields

http_client: Arc<C>

HTTP client wrapper used for every outbound provider request.

transport_mapper: Arc<M>

Mapper applied to transport-layer errors before surfacing them to callers.

store: Arc<dyn BrokerStore>

Token store implementation that persists issued secrets.

descriptor: ProviderDescriptor

Provider descriptor that defines OAuth endpoints and quirks.

strategy: Arc<dyn ProviderStrategy>

Strategy responsible for provider-specific token request adjustments.

client_id: String

OAuth 2.0 client identifier used in every grant.

client_secret: Option<String>

Optional client secret for confidential authentication methods.

refresh_metrics: Arc<RefreshMetrics>

Shared metrics recorder for refresh flow outcomes.

Implementations

impl<C, M> Broker<C, M>

where C: ?Sized + TokenHttpClient, M: ?Sized + TransportErrorMapper<C::TransportError>,

pub fn start_authorization( &self, tenant: TenantId, principal: PrincipalId, scope: ScopeSet, redirect_uri: Url, ) -> Result<AuthorizationSession>

Generates an Authorization Code + PKCE session for the provided tenant context.

Calling this method verifies that the backing descriptor advertises authorization_code support, builds a cryptographically strong state, and attaches a PKCE verifier/challenge pair. The resulting AuthorizationSession exposes accessor methods that UI layers can use to embed the authorize URL in a link or form, while backend handlers can persist the tenant/principal/scope context alongside the opaque state for later validation.

The broker does not automatically persist the session — it is the caller’s responsibility to stash it (or the relevant fields) until the redirect round-trip completes so AuthorizationSession::validate_state can run before an exchange.

pub async fn exchange_code( &self, session: AuthorizationSession, authorization_code: impl AsRef<str>, ) -> Result<TokenRecord>

Exchanges an authorization code + PKCE verifier for broker-managed tokens.

The AuthorizationSession generated by Broker::start_authorization carries the tenant/principal/scope context, redirect URI, and PKCE verifier needed to process the callback. Once the provider redirects back with a code, call this method with the original session and the returned code. Successful exchanges emit a TokenRecord that has already been written to the configured BrokerStore so subsequent fetches observe the latest secrets.

impl<C, M> Broker<C, M>

where C: ?Sized + TokenHttpClient, M: ?Sized + TransportErrorMapper<C::TransportError>,

pub async fn refresh_access_token( &self, request: CachedTokenRequest, ) -> Result<TokenRecord>

Refreshes the cached token family, performing CAS rotation + singleflight guards.

impl<C, M> Broker<C, M>

where C: TokenHttpClient + ?Sized, M: TransportErrorMapper<C::TransportError> + ?Sized,

pub async fn client_credentials( &self, request: CachedTokenRequest, ) -> Result<TokenRecord>

Performs the client_credentials grant with caching + singleflight guards.

impl<C, M> Broker<C, M>

where C: ?Sized + TokenHttpClient, M: ?Sized + TransportErrorMapper<C::TransportError>,

pub fn with_http_client( store: Arc<dyn BrokerStore>, descriptor: ProviderDescriptor, strategy: Arc<dyn ProviderStrategy>, client_id: impl Into<String>, http_client: impl Into<Arc<C>>, mapper: impl Into<Arc<M>>, ) -> Self

Creates a broker that reuses the caller-provided transport + mapper pair.

pub fn with_client_secret(self, secret: impl Into<String>) -> Self

Sets or replaces the client secret used for confidential client auth modes.

impl Broker<ReqwestHttpClient, ReqwestTransportErrorMapper>

pub fn new( store: Arc<dyn BrokerStore>, descriptor: ProviderDescriptor, strategy: Arc<dyn ProviderStrategy>, client_id: impl Into<String>, ) -> Self

Creates a new broker for the provided descriptor and client identifier.

The broker provisions its own reqwest-backed transport so callers do not need to pass HTTP handles explicitly. Use Broker::with_client_secret to attach a confidential client secret when the descriptor prefers client_secret_basic or client_secret_post.

Trait Implementations

impl<C, M> Clone for Broker<C, M>

where C: ?Sized + TokenHttpClient + Clone, M: ?Sized + TransportErrorMapper<C::TransportError> + Clone,

fn clone(&self) -> Broker<C, M>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<C, M> Debug for Broker<C, M>

where C: ?Sized + TokenHttpClient, M: ?Sized + TransportErrorMapper<C::TransportError>,

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

Formats the value using the given formatter.