Struct Client 

pub struct Client {

    pub(crate) client_secret: Arc<ClientSecret>,
    pub(crate) fs: Arc<ZoeClientFileStorage>,
    pub(crate) storage: Arc<ZoeClientStorage>,
    pub(crate) message_manager: Arc<ZoeClientMessageManager>,
    pub(crate) blob_service: Arc<ZoeClientBlobService>,
    pub(crate) relay_connections: Arc<RwLock<BTreeMap<KeyId, RelayClient>>>,
    pub(crate) relay_info: Arc<RwLock<BTreeMap<KeyId, RelayConnectionInfo>>>,
    pub(crate) encryption_key: [u8; 32],
    pub(crate) client_secret_observable: SharedObservable<ClientSecret>,
    pub(crate) relay_status_sender: Arc<Sender<RelayStatusUpdate>>,
    _relay_status_keeper: Arc<InactiveReceiver<RelayStatusUpdate>>,
    pub(crate) connection_monitors: Arc<RwLock<BTreeMap<KeyId, JoinHandle<()>>>>,
    pub(crate) session_manager: Arc<ZoeClientSessionManager>,
}

Fields

client_secret: Arc<ClientSecret>

fs: Arc<ZoeClientFileStorage>

storage: Arc<ZoeClientStorage>

message_manager: Arc<ZoeClientMessageManager>

blob_service: Arc<ZoeClientBlobService>

relay_connections: Arc<RwLock<BTreeMap<KeyId, RelayClient>>>

relay_info: Arc<RwLock<BTreeMap<KeyId, RelayConnectionInfo>>>

encryption_key: [u8; 32]

client_secret_observable: SharedObservable<ClientSecret>

Observable state for client secret updates - third parties can subscribe to changes

relay_status_sender: Arc<Sender<RelayStatusUpdate>>

Broadcast channel for per-relay connection status updates

_relay_status_keeper: Arc<InactiveReceiver<RelayStatusUpdate>>

Keeper receiver to prevent relay status broadcast channel closure (not actively used) Arc-wrapped to ensure channel stays open even when Client instances are cloned and dropped

connection_monitors: Arc<RwLock<BTreeMap<KeyId, JoinHandle<()>>>>

Connection monitoring tasks for each relay

session_manager: Arc<ZoeClientSessionManager>

Session manager for the client

Implementations

impl Client

pub async fn store_file(&self, file_path: PathBuf) -> Result<FileRef>

Store a file by reading from disk, encrypting, and storing in blob storage

This method:

1. Reads the file from the provided path
2. Encrypts the content using convergent encryption
3. Stores the encrypted data in the blob store
4. Returns metadata needed to retrieve the file later

Arguments

• file_path - Path to the file to store

Returns

A FileRef containing the metadata needed to retrieve the file

Errors

Returns an error if:

• The file cannot be read
• Encryption fails
• Blob storage operation fails

pub async fn store_data( &self, data: &[u8], reference_name: &str, content_type: Option<String>, ) -> Result<FileRef>

Store raw data (not from a file) with encryption and blob storage

This method allows storing arbitrary data without reading from disk.

Arguments

• data - The raw data to store
• reference_name - A reference name for the data (used in metadata)
• content_type - Optional content type for metadata

Returns

FileRef containing the blob hash, encryption info, and metadata

pub async fn has_file(&self, stored_info: &FileRef) -> Result<bool>

Check if a file exists in storage

Arguments

• stored_info - Metadata from when the file was stored

Returns

true if the file exists in storage, false otherwise

pub async fn retrieve_file( &self, file_ref: &FileRef, output_path: PathBuf, ) -> Result<()>

Retrieve a file from storage and save it to disk

This method:

1. Retrieves the encrypted data from blob storage using the FileRef
2. Decrypts the content
3. Writes the decrypted content to the specified path

Arguments

• file_ref - Metadata for the file to retrieve
• output_path - Path where the decrypted file should be saved

Errors

Returns an error if:

• The file cannot be found in storage
• Decryption fails
• Writing to disk fails

pub async fn retrieve_file_bytes(&self, file_ref: &FileRef) -> Result<Vec<u8>>

Retrieve a file from storage as bytes

This method:

1. Retrieves the encrypted data from blob storage using the FileRef
2. Decrypts the content
3. Returns the decrypted content as bytes

Arguments

• file_ref - Metadata for the file to retrieve

Returns

The decrypted file content as Vec<u8>

Errors

Returns an error if:

• The file cannot be found in storage
• Decryption fails

impl Client

pub async fn add_relay(&self, address: RelayAddress) -> Result<()>

Add a relay server to the client

This will attempt to connect to all addresses in the RelayAddress in random order with a 10-second timeout per attempt. Only adds the relay to local state if a connection succeeds.

pub fn add_relay_background( &self, address: RelayAddress, ) -> RelayConnectionHandle

Add a relay server to the client in the background

This returns immediately with a handle that you can optionally poll for the result. The connection attempt continues in the background regardless of whether you poll the handle. Relay status updates will be sent via the normal broadcast channels.

Usage Examples

// Fire and forget - just start the connection in background
let handle = client.add_relay_background(relay_address);
handle.detach(); // Connection continues in background

// Poll occasionally for result
let mut handle = client.add_relay_background(relay_address);
loop {
    match handle.try_result()? {
        Some(result) => {
            // Connection completed
            break result;
        }
        None => {
            // Still connecting, do other work
            tokio::time::sleep(Duration::from_millis(100)).await;
        }
    }
}

// Wait for completion
let result = client.add_relay_background(relay_address).await_result().await?;

async fn try_connect_to_relay_addresses( &self, address: &RelayAddress, ) -> Result<(SocketAddr, RelayClient), Vec<(String, ClientError)>>

Try to connect to a relay using all its addresses in random order

Returns the successful address and relay client, or all connection errors

pub async fn remove_relay( &self, server_public_key: VerifyingKey, ) -> Result<bool>

Remove a relay connection (offline mode only)

pub async fn get_relay_status(&self) -> Result<Vec<RelayConnectionInfo>>

Get list of all configured relays with their connection status

pub async fn has_connected_relays(&self) -> bool

Check if any relays are currently connected

pub async fn reconnect_failed_relays(&self) -> Result<usize>

Attempt to reconnect to all failed relays

async fn connect_to_relay( &self, server_public_key: VerifyingKey, server_addr: SocketAddr, ) -> Result<RelayClient>

Connect to a specific relay (internal method)

pub async fn close(&self)

pub fn overall_status_stream( &self, ) -> impl Stream<Item = OverallConnectionStatus>

Create a stream of overall connection status computed from relay status updates

This is a computed stream that automatically updates when any relay status changes. It maintains local state and only locks once for initial state, then updates based on incoming relay status changes without additional locking.

pub async fn overall_status(&self) -> OverallConnectionStatus

Calculate the current overall connection status

This is computed from the current relay states, ensuring it’s always accurate but makes it a bit more expensive to compute. For live updates it is recommended to use overall_status_stream instead.

fn start_connection_monitoring( &self, relay_id: KeyId, relay_client: RelayClient, )

Start monitoring a relay connection for disconnections

async fn stop_connection_monitoring(&self, relay_id: KeyId)

Stop monitoring a relay connection

async fn notify_relay_status_change( &self, relay_id: KeyId, relay_address: RelayAddress, status: RelayConnectionStatus, )

Notify about relay status change

impl Client

pub fn subscribe_to_relay_status(&self) -> Receiver<RelayStatusUpdate>

Subscribe to per-relay connection status updates

This provides real-time updates about individual relay connection status changes. Each relay reports its status independently via this broadcast channel.

impl Client

pub fn client_secret(&self) -> ClientSecret

Get the current client secret

impl Client

pub fn subscribe_to_client_secret(&self) -> Subscriber<ClientSecret>

Subscribe to client secret updates

Third parties can use this to be notified when the client secret changes, allowing them to store updated client secrets with the current server configuration.

pub(crate) async fn update_client_secret_state(&self)

Update the client secret observable state with current server configuration

impl Client

pub fn client_secret_hex(&self) -> Result<String>

pub fn id_hex(&self) -> String

pub fn session_manager(&self) -> Arc<ZoeClientSessionManager>

Close the client and clean up all resources Get access to the session manager for PQXDH operations

This provides access to the underlying session manager which handles PQXDH protocol handlers and state management.

Returns

A reference to the SessionManager

pub fn group_manager(&self) -> GroupManager

impl Client

pub fn message_manager(&self) -> &Arc<ZoeClientMessageManager>

Get access to the multi-relay message manager

pub fn blob_service(&self) -> &Arc<ZoeClientBlobService>

Get access to the multi-relay blob service

pub fn storage(&self) -> &Arc<ZoeClientStorage>

Get access to storage

pub fn public_key(&self) -> VerifyingKey

Get the client’s public key

pub fn keypair(&self) -> &Arc<KeyPair>

Get the client’s keypair

pub fn blob_client(&self) -> &BlobClient

Get a reference to the blob client for advanced operations

This provides direct access to the underlying blob storage client for operations not covered by the high-level file storage API.

Returns

A reference to the BlobClient

impl Client

pub fn builder() -> ClientBuilder

Create a new ClientBuilder for constructing a Client

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

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

Performs copy-assignment from source.