Module pool 

BrainPool — a bounded, per-credential connection-pool cache to Brain.

Brain binds a connection’s identity at handshake from the credential it presents, so one shared pool cannot serve many credentials without crossing isolation. BrainPool therefore keeps a bounded per-credential pool cache: the first call for a credential opens a pool_size-wide brain_db_sdk::Pool authenticated as that credential and reuses it for every later call (pooled, never connect-per-request).

The cache is held in an ArcSwap so the hot path (pool already built) is a lock-free load + map lookup with a relaxed-atomic recency bump — no mutex, no .await under a lock. The cold path builds the pool OUTSIDE any critical section and publishes it via copy-on-write ArcSwap::rcu.

It is bounded two ways so a long-lived process serving many credentials doesn’t accumulate one Arc<Pool> (and pool_size live TCP connections) per credential forever: a periodic idle sweep (BrainPool::sweep_idle) drops pools unused past idle_ttl, and a hard cap (max_credentials) evicts the least-recently-used entry opportunistically on insert as a burst-protection backstop between sweeps.

This is the shared wire-engine both brain-edge (self-host) and the Arc cloud gateway use. Budgets and timeouts are deliberately not here — they are the caller’s concern.

Two modes

• Per-credential (BrainPool::new) — the self-host bearer-passthrough default described above. Each distinct wire credential gets its own pool, so Brain binds each to its own key-bound identity at handshake.
• Shared / act_as (BrainPool::shared) — one pool authenticated once as a trusted service principal (a can_act_as key). Every BrainPool::client_for hands back a client from that single pool regardless of the credential argument; the gateway then resolves each API key to a (namespace, space_id) and sets act_as per request so one connection pool serves every tenant. This mode is for the gateway only — the self-host edge doesn’t resolve keys to identities, so it stays per-credential.

Structs

BrainPool

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

BrainPoolConfig

Configuration for a BrainPool.