Module connector 

Connector for fetching entities from a remote Haystack server.

Overview

A Connector maintains a persistent connection (HTTP or WebSocket) to a remote Haystack server, periodically syncs entities into a local cache, and proxies write operations (hisRead, hisWrite, pointWrite, invokeAction, import) to the remote when the target entity is owned by that connector.

Lifecycle

1. Construction — Connector::new creates a connector with an empty cache from a ConnectorConfig (parsed from the TOML federation config).
2. Connection — on first sync, Connector::sync calls connect_persistent() which tries WebSocket first, falling back to HTTP.
3. Sync loop — Connector::spawn_sync_task spawns a tokio task that calls Connector::sync at an adaptive interval. Sync tries incremental delta sync via the changes op first, falling back to full entity fetch.
4. Cache — Connector::update_cache replaces the cached entity list and rebuilds the bitmap tag index and owned-ID set for fast lookups.
5. Proxy — write ops check Connector::owns and forward to the remote server via proxy_* methods, stripping/re-adding the ID prefix as needed.

ID Prefixing

When id_prefix is configured, all Ref values (id, siteRef, etc.) are prefixed on sync and stripped before proxying. See prefix_refs and strip_prefix_refs.

Structs

Connector

ConnectorConfig

Configuration for a remote Haystack server connection.

ConnectorState

and state for adaptive sync and federation proxy operations. See the module-level documentation for the full lifecycle. Observable state of a federation connector.

Enums

TransportMode

Transport protocol used by a connector.

Functions

decode_sync_payload

Decode an entity grid from HBF binary received during federation sync.

encode_sync_payload

Encode an entity grid to HBF binary for efficient federation sync.

prefix_refs

Prefix all Ref values in an entity dict.

strip_prefix_refs

Strip a prefix from all Ref values in an entity dict.