Struct Federation 

pub struct Federation {
    pub connectors: Vec<Arc<Connector>>,
}

Manages multiple remote connectors for federated queries.

Fields

connectors: Vec<Arc<Connector>>

Implementations

impl Federation

pub fn new() -> Self

Create a new federation with no connectors.

pub fn add(&mut self, config: ConnectorConfig)

Add a connector for a remote Haystack server.

pub async fn sync_one(&self, name: &str) -> Result<usize, String>

Sync a single connector by name, returning the entity count on success.

pub async fn sync_all(&self) -> Vec<(String, Result<usize, String>)>

Sync all connectors, returning a vec of (name, result) pairs.

Each result is either Ok(count) with the number of entities synced, or Err(message) with the error description.

pub fn all_cached_entities(&self) -> Vec<HDict>

Returns all cached entities from all connectors, merged into a single vec.

pub fn filter_cached_entities( &self, filter_expr: &str, limit: usize, ) -> Result<Vec<HDict>, String>

Filter cached entities across all connectors using bitmap-accelerated queries.

Each connector uses its own bitmap tag index for fast filtering, then results are merged up to the given limit. Much faster than linear scan for tag-based queries over large federated entity sets.

pub fn connector_count(&self) -> usize

Returns the number of connectors.

pub fn owner_of(&self, id: &str) -> Option<&Arc<Connector>>

Returns the connector that owns the entity with the given ID, if any.

pub fn batch_read_by_id<'a>( &self, ids: impl IntoIterator<Item = &'a str>, ) -> (Vec<HDict>, Vec<String>)

Batch read entities by ID across federated connectors.

Groups IDs by owning connector and fetches each group in a single indexed lookup (O(1) per ID via cache_id_map), avoiding repeated linear scans. Returns (found_entities, missing_ids).

pub fn status(&self) -> Vec<(String, usize)>

Returns (name, entity_count) for each connector.

pub fn from_toml_str(toml_str: &str) -> Result<Self, String>

Parse a TOML string into a Federation, adding each connector defined under [connectors.<key>].

pub fn from_toml_file(path: &str) -> Result<Self, String>

Read a TOML file from disk and parse it into a Federation.

pub fn start_background_sync(&self) -> Vec<JoinHandle<()>>

Start background sync tasks for all connectors.

Each connector gets its own tokio task that loops at its configured sync interval, reconnecting automatically on failure. Returns the join handles (they run until the server shuts down).

Trait Implementations

impl Default for Federation

fn default() -> Self

Returns the “default value” for a type.