Struct convex::base_client::BaseConvexClient

pub struct BaseConvexClient { /* private fields */ }

The synchronous state machine for the ConvexClient. It’s recommended to use the higher level ConvexClient unless you are building a framework.

This struct should be used instead of the ConvexClient when you want the ability to build consistent client views. For example, in order to use your own websocket manager or make a client compatible with another language (e.g. Swift or Python).

For the latter use case, we strongly recommend you to take a look at the implementation of the ConvexClient. The recommended pattern to use an BaseConvexClient is to create a background thread to manage actions on queries/mutations and incoming websocket connections, and use that to advance the BaseConvexClient’s state.

Managing Convex State

The main methods, subscribe, unsubscribe, and mutation directly correspond to its equivalent for the external ConvexClient.

The only different method is get_query, which returns the current value for a query given its query id. This method can be used to synchronously request the current value, as opposed to a stream of values in subscribe.

Note: these methods have the side effect of adding messages to be sent to the server, so you would need to flush all outgoing messages by looping on pop_next_message after each call of the above functions.

Watching for consistent updates to queries

To watch for consistent changes in query values, you can add the following code to the background thread:

use convex::base_client::BaseConvexClient;
use convex::Value;
use convex_sync_types::ServerMessage;

fn on_receive_server_message(mut base_client: BaseConvexClient, msg: ServerMessage<Value>) {
    let res = base_client.receive_message(msg).expect("Base client error");
    if let Some(latest_result_map) = res {
        for (subscriber_id, function_result) in latest_result_map.iter() {
            // Notify components of the updated_value
        }
    }
}

Managing Web Socket States

To manage websocket messages, use receive_message (for incoming messages from the server) and pop_next_message (for outgoing messages to send to the server). The BaseConvexClient does not send these messages, so you will have to regularly monitor if there are messages to be sent by calling pop_next_message.

Additionally, when the websocket reconnects, you should call resend_ongoing_queries_mutations and loop on pop_next_message to resend requests to the Server to resubscribe to queries and perform ongoing mutations.

pop_next_message should be called after the following methods:

• resend_ongoing_queries_mutations
• subscribe
• unsubscribe
• mutation

Implementations

impl BaseConvexClient

pub fn new() -> Self

Construct a new BaseConvexClient.

pub fn subscribe( &mut self, udf_path: UdfPath, args: BTreeMap<String, Value> ) -> SubscriberId

Update state to be subscribed to a query and add subscription request to the outgoing message queue.

After calling this, it is highly recommended to loop on pop_next_message to flush websocket messages to the server.

pub fn unsubscribe(&mut self, subscriber_id: SubscriberId)

Update state to be unsubscribed to a query and add unsubscription request to the outgoing message queue.

After calling this, it is highly recommended to loop on pop_next_message to flush websocket messages to the server.

pub fn get_query(&self, query_id: QueryId) -> Option<FunctionResult>

Return the local value of a query.

pub fn mutation( &mut self, udf_path: UdfPath, args: BTreeMap<String, Value> ) -> Receiver<FunctionResult>

Track mutation and add mutation request to the outgoing message queue.

After calling this, it is highly recommended to loop on pop_next_message to flush websocket messages to the server.

pub fn action( &mut self, udf_path: UdfPath, args: BTreeMap<String, Value> ) -> Receiver<FunctionResult>

Track action and add action request to the outgoing message queue.

After calling this, it is highly recommended to loop on pop_next_message to flush websocket messages to the server.

pub fn set_auth(&mut self, token: AuthenticationToken)

Set auth on the sync protocol.

pub fn pop_next_message(&mut self) -> Option<ClientMessage>

Pop the next message from the outgoing message queue.

Note that this does not send the message because the Internal client has no awareness of websockets. After popping the next message, it is the caller’s responsibility to actually send it.

pub fn max_observed_timestamp(&self) -> Option<Timestamp>

Returns the maximum timestamp observed by the client.

pub fn receive_message( &mut self, message: ServerMessage<Value> ) -> Result<Option<QueryResults>, String>

Given a message from a Server, update the base state accordingly.

pub fn latest_results(&self) -> &QueryResults

Grab a snapshot of the latest query results to all subscribed queries.

pub fn resend_ongoing_queries_mutations(&mut self)

Resend all subscribed queries and ongoing mutations. Should be used once the websocket closes and reconnects.