Struct HaystackClient 

pub struct HaystackClient<T: Transport> { /* private fields */ }

A client for communicating with a Haystack HTTP API server.

Provides typed methods for all standard Haystack ops (about, read, hisRead, etc.) as well as a generic call method for custom ops.

Supports both HTTP and WebSocket transports.

Implementations

impl HaystackClient<HttpTransport>

pub async fn connect( url: &str, username: &str, password: &str, ) -> Result<Self, ClientError>

Connect to a Haystack server via HTTP, performing SCRAM authentication.

Arguments

• url - The server API root (e.g. http://localhost:8080/api)
• username - The username to authenticate as
• password - The user’s plaintext password

pub async fn connect_with_tls( url: &str, username: &str, password: &str, tls: &TlsConfig, ) -> Result<Self, ClientError>

Connect to a Haystack server via HTTP with mutual TLS (mTLS) client certificate authentication, then perform SCRAM authentication.

Builds a custom reqwest::Client configured with the provided TLS identity (client certificate + key) and optional CA certificate, then runs the standard SCRAM handshake over that client.

Arguments

• url - The server API root (e.g. https://localhost:8443/api)
• username - The username to authenticate as
• password - The user’s plaintext password
• tls - The mTLS configuration (cert, key, optional CA)

impl HaystackClient<WsTransport>

pub async fn connect_ws( url: &str, ws_url: &str, username: &str, password: &str, ) -> Result<Self, ClientError>

Connect to a Haystack server via WebSocket.

Performs SCRAM authentication over HTTP first to obtain an auth token, then establishes a WebSocket connection using that token.

Arguments

• url - The server API root for HTTP auth (e.g. http://localhost:8080/api)
• ws_url - The WebSocket URL (e.g. ws://localhost:8080/api/ws)
• username - The username to authenticate as
• password - The user’s plaintext password

impl<T: Transport> HaystackClient<T>

pub fn from_transport(transport: T) -> Self

Create a client with an already-configured transport.

Useful for testing or when you have a custom Transport implementation.

pub async fn call(&self, op: &str, req: &HGrid) -> Result<HGrid, ClientError>

Call a raw Haystack op with a request grid.

op is the operation name (e.g. "read", "hisRead"). The server returns an error grid (as [ClientError::Grid]) if the op fails.

pub async fn about(&self) -> Result<HGrid, ClientError>

Call the about op. Returns a single-row grid with server metadata including vendorName, productName, productVersion, and tz.

pub async fn ops(&self) -> Result<HGrid, ClientError>

Call the ops op. Returns a grid listing every operation the server supports, with name, summary, and doc columns.

pub async fn formats(&self) -> Result<HGrid, ClientError>

Call the formats op. Returns a grid of MIME types the server can read/write, with mime, receive, and send columns.

pub async fn libs(&self) -> Result<HGrid, ClientError>

Call the libs op. Returns a grid of Xeto library modules installed on the server, including name and version for each library.

pub async fn read( &self, filter: &str, limit: Option<usize>, ) -> Result<HGrid, ClientError>

Call the read op with a Haystack filter expression and optional limit.

filter is a Haystack filter string (e.g. "site", "equip and siteRef==@s", "temp > 72"). Returns a grid of matching entity dicts. Pass limit to cap the number of results. Returns an empty grid if nothing matches.

pub async fn read_by_ids(&self, ids: &[&str]) -> Result<HGrid, ClientError>

Call the read op with a list of entity ref ids.

Each entry in ids is a ref value string (e.g. "@site-1", "@equip-2"). Returns one row per id. Rows for unknown ids contain only a Null marker.

pub async fn nav(&self, nav_id: Option<&str>) -> Result<HGrid, ClientError>

Call the nav op to walk the site/equip/point navigation tree.

Pass None to get root-level nodes, or Some(nav_id) to expand a specific node. Returns a grid of child navigation entries.

pub async fn defs(&self, filter: Option<&str>) -> Result<HGrid, ClientError>

Call the defs op to query the server’s tag/def ontology.

filter is an optional Haystack filter (e.g. "point", "equip") to narrow results. Returns a grid of matching def dicts.

pub async fn watch_sub( &self, ids: &[&str], lease: Option<&str>, ) -> Result<HGrid, ClientError>

Call the watchSub op to subscribe to real-time changes for a set of entities.

ids are ref value strings (e.g. ["@point-1", "@point-2"]). lease is an optional duration string (e.g. "1min", "30sec", "1hr") controlling how long the server keeps the watch alive without polls. Returns a grid whose meta contains the assigned watchId.

pub async fn watch_poll(&self, watch_id: &str) -> Result<HGrid, ClientError>

Call the watchPoll op to poll a watch for changed entity values.

watch_id is the identifier returned by watch_sub. Returns a grid of entities whose curVal has changed since the last poll.

pub async fn watch_unsub( &self, watch_id: &str, ids: &[&str], ) -> Result<HGrid, ClientError>

Call the watchUnsub op to remove entities from an active watch.

watch_id identifies the watch. ids are the ref value strings to unsubscribe (e.g. ["@point-1"]). The watch is closed automatically when all entities have been removed.

pub async fn point_write( &self, id: &str, level: u8, val: Kind, ) -> Result<HGrid, ClientError>

Call the pointWrite op to write a value to a writable point.

id is the point ref (e.g. "@point-1"). level is the priority array level 1–17 per the Haystack spec (1=emergency, 8=manual, 16=default, 17=fallback). val is the value to write at that level.

pub async fn his_read( &self, id: &str, range: &str, ) -> Result<HGrid, ClientError>

Call the hisRead op to read time-series history for a point.

id is the point ref (e.g. "@sensor-1"). range is a Haystack range string: "today", "yesterday", a single date like "2024-01-01", a date span "2024-01-01,2024-01-31", or a datetime with timezone like "2024-01-01T00:00:00-05:00 New_York". Returns a grid of ts/val rows.

pub async fn his_write( &self, id: &str, items: Vec<HDict>, ) -> Result<HGrid, ClientError>

Call the hisWrite op to write time-series samples for a point.

id is the point ref. items must be dicts each containing a ts (DateTime) and val tag. Returns an empty grid on success or an error grid if the write is rejected.

pub async fn invoke_action( &self, id: &str, action: &str, args: HDict, ) -> Result<HGrid, ClientError>

Call the invokeAction op to invoke a named action on an entity.

id is the target entity ref. action is the action name. args is an HDict of additional parameters for the action. Returns the action’s result grid.

pub async fn close_session(&self) -> Result<HGrid, ClientError>

Call the close op to close the current server session.

This is distinct from close which shuts down the underlying transport connection.

pub async fn specs(&self, lib: Option<&str>) -> Result<HGrid, ClientError>

List all Xeto specs on the server, optionally filtered by library name.

Pass None to list specs across all libraries, or Some("lib_name") to restrict to a single library. Returns a grid of spec dicts.

pub async fn spec(&self, qname: &str) -> Result<HGrid, ClientError>

Get a single Xeto spec by its fully-qualified name.

qname is the qualified spec name (e.g. "ph::Site"). Returns a single-row grid with the spec definition.

pub async fn load_lib( &self, name: &str, source: &str, ) -> Result<HGrid, ClientError>

Load a Xeto library from source text into the server’s ontology.

name is the library name and source is the raw Xeto source code. Returns an error grid if the source fails to parse or validate.

pub async fn unload_lib(&self, name: &str) -> Result<HGrid, ClientError>

Unload a previously loaded Xeto library by name.

Removes the library and its specs from the server’s active ontology.

pub async fn export_lib(&self, name: &str) -> Result<HGrid, ClientError>

Export a library as Xeto source text.

Returns a grid whose first row contains the serialized Xeto source for the named library.

pub async fn validate(&self, entities: Vec<HDict>) -> Result<HGrid, ClientError>

Validate entity dicts against the server’s Xeto ontology.

entities is a list of HDict records to check. Returns a grid with validation results — each row reports errors for the corresponding input entity. An empty result grid means all entities are valid.

pub async fn close(&self) -> Result<(), ClientError>

Close the underlying transport connection (HTTP or WebSocket).

Call close_session first if you want to explicitly end the server-side session before disconnecting.