Struct BrainPool 

pub struct BrainPool { /* private fields */ }

A bounded connection-pool cache to Brain — per-credential (self-host) or a single shared service-principal pool with per-request act_as (gateway).

In per-credential mode the cache is keyed by the wire credential string and held in an ArcSwap so the hot path (pool already built) is a lock-free load + map lookup with no per-request hashing beyond the lookup itself. In shared mode there is one pool for every caller. Pools are created lazily, on first use.

Implementations

impl BrainPool

pub fn new(config: BrainPoolConfig) -> Self

Build an empty per-credential pool cache (the self-host bearer default). Pools are created lazily, on first use per credential. max_credentials is floored at 1 so the cache can always hold at least one entry.

pub fn shared(config: BrainPoolConfig, service_credential: String) -> Self

Build a shared / act_as pool authenticated as service_credential — a trusted service principal holding the can_act_as grant. Every BrainPool::client_for call returns a client from this ONE pool regardless of the credential argument, so a single connection pool can serve every tenant when the gateway sets act_as per request.

The pool is opened lazily on first use, so this constructor is synchronous and infallible just like BrainPool::new; a bad service credential or an unreachable Brain surfaces from the first client_for.

pub async fn client_for( &self, credential: &str, ) -> Result<Arc<BrainClient>, BrainError>

Get (or lazily build) a pooled client.

In per-credential mode the client is authenticated as credential: hot path is a lock-free load + lookup, bumping recency in place with a relaxed atomic; cold path builds the brain_db_sdk::Pool OUTSIDE any lock, publishes it via ArcSwap::rcu, and LRU-evicts the least-recently-used entry first if the cache is at max_credentials.

In shared mode credential is ignored: the returned client always comes from the single service-principal pool. The gateway then sets act_as per request to select the effective tenant identity.

Errors

Returns the underlying BrainError if a fresh pool fails to connect or handshake.

pub fn sweep_idle(&self)

Drop credentials idle beyond config.idle_ttl. Called by a background sweeper, never from the request path. One RCU pass; a no-op if nothing has gone idle. In shared mode there is a single long-lived pool with no per-credential entries to sweep, so this is a no-op.

pub async fn probe(&self, timeout: Duration) -> bool

Cheap reachability probe used by readiness: can we open a TCP socket to the Brain listener within timeout? Avoids a full handshake or a credential.

Trait Implementations

impl Debug for BrainPool

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

Reports the mode and the cache ceiling — never a credential, and never the pooled connections themselves.