Struct Connector 

pub struct Connector {
    pub config: ConnectorConfig,
    /* private fields */
}

Fields

config: ConnectorConfig

Implementations

impl Connector

pub fn new(config: ConnectorConfig) -> Self

Create a new connector with an empty cache.

The connector starts disconnected; a persistent connection is established lazily on the first sync call.

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

Connect to the remote server, fetch entities, and update cache.

Tries incremental delta sync first (via the changes op) if we have a known remote version. Falls back to full sync on first connect, when the remote doesn’t support changes, or when the version gap is too large.

Returns the number of cached entities after sync, or an error string.

pub fn update_cache(&self, entities: Vec<HDict>)

Replace the cached entities and rebuild the owned-ID index and bitmap tag index.

Extracts all id Ref values from the given entities into a HashSet, builds a bitmap tag index for fast filtered reads, then atomically replaces the cache, ownership set, and index.

pub fn owns(&self, id: &str) -> bool

Returns true if this connector owns an entity with the given ID.

pub fn get_cached_entity(&self, id: &str) -> Option<Arc<HDict>>

Look up a single cached entity by ID using the O(1) id_map index.

pub fn batch_get_cached(&self, ids: &[&str]) -> (Vec<Arc<HDict>>, Vec<String>)

Look up multiple cached entities by ID in a single pass. Returns found entities and missing IDs.

pub fn cached_entities(&self) -> Vec<Arc<HDict>>

Returns Arc-wrapped references to all cached entities (cheap pointer copies).

pub fn entity_count(&self) -> usize

Returns the number of cached entities.

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

Filter cached entities using the bitmap tag index for acceleration.

Returns matching entities up to limit (0 = unlimited). Uses the same two-phase approach as EntityGraph: bitmap candidates → full filter eval.

pub fn filter_cached_with_ast( &self, ast: &FilterNode, limit: usize, ) -> Vec<Arc<HDict>>

Filter cached entities using a pre-parsed filter AST.

Avoids redundant parsing when the same filter is applied across multiple connectors (e.g. federated reads). Returns Arc-wrapped references for cheap cloning in federation pipelines.

pub fn add_remote_watch(&self, prefixed_id: &str)

Add a federated entity ID to the remote watch set.

pub fn remove_remote_watch(&self, prefixed_id: &str)

Remove a federated entity ID from the remote watch set.

pub fn remote_watch_count(&self) -> usize

Returns the number of entity IDs being watched remotely.

pub fn transport_mode(&self) -> TransportMode

Returns the current transport mode.

pub fn is_connected(&self) -> bool

Returns whether the connector is currently connected (last sync succeeded).

pub fn last_sync_time(&self) -> Option<DateTime<Utc>>

Returns the timestamp of the last successful sync, if any.

pub fn cache_version(&self) -> u64

Returns the current cache version counter.

pub fn state(&self) -> ConnectorState

Returns an observable snapshot of this connector’s state.

pub async fn proxy_his_read( &self, prefixed_id: &str, range: &str, ) -> Result<HGrid, String>

Proxy a hisRead request to the remote server.

Strips the ID prefix, calls hisRead on the remote, and returns the response grid. Clears the client on connection error.

pub async fn proxy_point_write( &self, prefixed_id: &str, level: u8, val: &Kind, ) -> Result<HGrid, String>

Proxy a pointWrite request to the remote server.

Strips the ID prefix, calls pointWrite on the remote with the given level and value. Clears the client on connection error.

pub async fn proxy_his_write( &self, prefixed_id: &str, items: Vec<HDict>, ) -> Result<HGrid, String>

Proxy a hisWrite request to the remote server.

Strips the ID prefix, calls hisWrite on the remote with the given time-series rows. Clears the client on connection error.

pub async fn proxy_import(&self, entity: &HDict) -> Result<HGrid, String>

Proxy an import request for a single entity to the remote server.

Strips the id prefix from the entity, wraps it in a single-row grid, and calls the remote import op.

pub async fn proxy_invoke_action( &self, prefixed_id: &str, action: &str, args: HDict, ) -> Result<HGrid, String>

Proxy an invokeAction request to the remote server.

Strips the ID prefix, calls invokeAction on the remote with the given action name and arguments dict. Clears the client on connection error.

pub fn spawn_sync_task(connector: Arc<Connector>) -> JoinHandle<()>

Spawn a background sync task for this connector.

The task loops forever, syncing entities at the configured interval. On error, the persistent client is cleared to force reconnection on the next iteration.