Struct WebSocketClient 

pub struct WebSocketClient { /* private fields */ }

WebSocket client for real-time communication with persistent connection.

Uses a single dispatcher task that reads all incoming frames and routes them to the appropriate consumer (request-response, subscription, or chat stream). The writer is held in a separate mutex so sends never block on reads.

Implementations

impl WebSocketClient

pub fn new(ws_url: impl AsRef<str>, token: impl Into<String>) -> Result<Self>

Create a new WebSocket client

pub async fn find_all(&self, collection: &str) -> Result<Vec<Record>>

Find all records in a collection via WebSocket

pub async fn subscribe( &self, collection: &str, filter_field: Option<&str>, filter_value: Option<&str>, ) -> Result<Receiver<MutationNotificationPayload>>

Subscribe to collection changes with an optional field filter.

Returns a receiver that yields MutationNotificationPayload events.

pub async fn unsubscribe(&self, collection: &str) -> Result<()>

Stop receiving mutation notifications for a collection.

This is an intentional teardown: it drops the local subscription sender(s) for collection (so dropped receivers stop being fed) and sends a best-effort Unsubscribe frame to the server so it stops streaming this collection on this connection. If the socket is already gone the local teardown suffices, since the server drops all subscriptions when the connection closes. Safe to call for a collection that is not currently subscribed (no-op).

A unique messageId is attached to the frame purely so the server’s ack carries a correlation id: Unsubscribe registers no pending request, so the dispatcher finds no match and silently discards the ack. The id stops that unmatched ack from being misrouted to an unrelated in-flight request.

pub async fn chat_send( &self, chat_id: &str, message: &str, ) -> Result<Receiver<ChatStreamEvent>>

Send a chat message and receive streaming responses with client tool support.

Returns a receiver that yields ChatStreamEvent items:

• Chunk(text) for each token/chunk from the LLM
• ToolCall { call_id, tool_name, arguments } when ekoDB needs a client tool executed
• End { ... } when the stream completes
• Error(msg) if something goes wrong

When a ToolCall event is received, call send_tool_result() to return the result. ekoDB will feed the result back to the LLM and continue streaming.

pub async fn chat_send_with_tools( &self, chat_id: &str, message: &str, client_tools: Option<Vec<ClientToolDefinition>>, max_iterations: Option<u32>, confirm_tools: Option<Vec<String>>, exclude_tools: Option<Vec<String>>, ) -> Result<Receiver<ChatStreamEvent>>

Send a chat message with client tool definitions.

Same as chat_send but includes client-side tool definitions that ekoDB merges with its built-in tools when calling the LLM.

pub async fn register_client_tools( &self, chat_id: &str, tools: Vec<ClientToolDefinition>, ) -> Result<()>

Register client-side tools for a chat session.

These tools persist across messages within the session. When the LLM invokes one, ekoDB sends a ClientToolCall event back to the client.

Note: The WS protocol for RegisterClientTools does not include a messageId field, so we use a dedicated register_tools_ack slot in the dispatcher instead of pending_requests. This means only one registration can be in-flight at a time, which is fine since tool registration is typically done once before chat starts.

pub async fn cancel_chat(&self, chat_id: &str) -> Result<()>

Cancel an in-flight chat stream by chat_id. Fires the server-side cancellation token, which aborts the LLM HTTP call AND skips persisting the assistant message. Use this instead of just dropping the receiver — pre-fix, dropping only halted chunk delivery; the LLM kept generating server-side and the assistant turn still landed in storage.

Connection: requires an active WS. If the client isn’t connected, this auto-reconnects via ensure_connected() (matching every other WS-RPC method on this client). Once delivered to the server, the cancel itself is a no-op when no in-flight stream matches chat_id — callers can fire it speculatively without checking.

pub async fn send_tool_result( &self, chat_id: &str, call_id: &str, success: bool, result: Option<Value>, error: Option<String>, ) -> Result<()>

Send the result of a client-side tool execution back to ekoDB.

Call this after receiving a ChatStreamEvent::ToolCall event. ekoDB will feed the result back to the LLM and continue the conversation.

pub async fn raw_completion( &self, request: &RawCompletionRequest, ) -> Result<RawCompletionResponse>

Stateless raw LLM completion via WebSocket.

Sends a RawComplete message and waits for the Success response. Preferred over HTTP for deployed instances: the persistent WSS connection is already authenticated and won’t be killed by reverse proxy timeouts.

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

Close the WebSocket connection with a proper close frame.

pub async fn set_schema_cache(&self, cache: Arc<SchemaCache>)

Attach a schema cache for automatic invalidation on SchemaChanged events.

pub async fn send_crud(&self, msg_type: &str, payload: Value) -> Result<Value>

Helper: send a typed WS request as raw JSON and wait for response. Attaches messageId at the top level for concurrent correlation. Send a typed CRUD request as raw JSON and return the data from the response.

pub async fn insert( &self, collection: &str, record: Value, bypass_ripple: Option<bool>, ) -> Result<Value>

Insert a single record into a collection via WebSocket.

pub async fn query( &self, collection: &str, filter: Option<Value>, sort: Option<Value>, limit: Option<u64>, skip: Option<u64>, ) -> Result<Vec<Value>>

Query records from a collection via WebSocket.

pub async fn find_by_id(&self, collection: &str, id: &str) -> Result<Value>

Find a record by ID via WebSocket.

pub async fn update( &self, collection: &str, id: &str, record: Value, bypass_ripple: Option<bool>, ) -> Result<Value>

Update a record by ID via WebSocket.

pub async fn delete( &self, collection: &str, id: &str, bypass_ripple: Option<bool>, ) -> Result<()>

Delete a record by ID via WebSocket.

pub async fn batch_insert( &self, collection: &str, records: Vec<Value>, bypass_ripple: Option<bool>, ) -> Result<Value>

Batch insert multiple records via WebSocket.

pub async fn batch_update( &self, collection: &str, updates: Vec<(String, Value)>, bypass_ripple: Option<bool>, ) -> Result<Value>

Batch update multiple records via WebSocket. Each update is a tuple of (id, record_data).

pub async fn batch_delete( &self, collection: &str, ids: Vec<String>, bypass_ripple: Option<bool>, ) -> Result<()>

Batch delete multiple records by IDs via WebSocket.

pub async fn text_search( &self, collection: &str, query: &str, fields: Option<Vec<String>>, limit: Option<u64>, ) -> Result<Vec<Value>>

Full-text search via WebSocket.

pub async fn distinct_values( &self, collection: &str, field: &str, filter: Option<Value>, ) -> Result<Value>

Get distinct values for a field via WebSocket.

pub async fn update_with_action( &self, collection: &str, id: &str, action: &str, field: &str, value: Option<Value>, ) -> Result<Value>

Apply an atomic field action to a record via WebSocket.

pub async fn create_collection( &self, name: &str, schema: Option<Value>, ) -> Result<()>

Create a new collection with optional schema via WebSocket.

pub async fn list_collections(&self) -> Result<Vec<String>>

List all collections via WebSocket.

pub async fn delete_collection(&self, name: &str) -> Result<()>

Delete a collection via WebSocket.

Trait Implementations

impl Clone for WebSocketClient

fn clone(&self) -> WebSocketClient

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.