Struct bonsaidb::client::Client

pub struct Client<A = ()> where
    A: CustomApi,  { /* private fields */ }

Client for connecting to a BonsaiDb server.

Connecting via QUIC

The URL scheme to connect via QUIC is bonsaidb. If no port is specified, port 5645 is assumed.

With a valid TLS certificate

let client = Client::build(Url::parse("bonsaidb://my-server.com")?)
    .finish()
    .await?;

With a Self-Signed Pinned Certificate

When using install_self_signed_certificate(), clients will need the contents of the pinned-certificate.der file within the database. It can be specified when building the client:

let certificate =
    Certificate::from_der(std::fs::read("mydb.bonsaidb/pinned-certificate.der")?)?;
let client = Client::build(Url::parse("bonsaidb://localhost")?)
    .with_certificate(certificate)
    .finish()
    .await?;

Connecting via WebSockets

WebSockets are built atop the HTTP protocol. There are two URL schemes for WebSockets:

• ws: Insecure WebSockets. Port 80 is assumed if no port is specified.
• wss: Secure WebSockets. Port 443 is assumed if no port is specified.

Without TLS

let client = Client::build(Url::parse("ws://localhost")?)
    .finish()
    .await?;

With TLS

let client = Client::build(Url::parse("wss://my-server.com")?)
    .finish()
    .await?;

Using a CustomApi

Our user guide has a section on creating and using a CustomApi.

// `bonsaidb_core` is re-exported to `bonsaidb::core` or `bonsaidb_client::core`.
use bonsaidb_core::custom_api::{CustomApi, Infallible};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
pub enum Request {
    Ping,
}

#[derive(Serialize, Deserialize, Clone, Debug)]
pub enum Response {
    Pong,
}

#[derive(Debug)]
pub enum MyApi {}

impl CustomApi for MyApi {
    type Request = Request;
    type Response = Response;
    type Error = Infallible;
}

let client = Client::build(Url::parse("bonsaidb://localhost")?)
    .with_custom_api::<MyApi>()
    .finish()
    .await?;
let Response::Pong = client.send_api_request(Request::Ping).await?;

Receiving out-of-band messages from the server

If the server sends a message that isn’t in response to a request, the client will invoke it’s custom api callback:

let client = Client::build(Url::parse("bonsaidb://localhost")?)
    .with_custom_api_callback::<MyApi, _>(|result: Result<Response, Infallible>| {
        let Response::Pong = result.unwrap();
    })
    .finish()
    .await?;

Implementations

impl Client<()>

pub fn build(url: Url) -> Builder<()>

Returns a builder for a new client connecting to url.

impl<A> Client<A> where
    A: CustomApi, 

pub async fn new(url: Url) -> Result<Client<A>, Error<<A as CustomApi>::Error>>

Initialize a client connecting to url. This client can be shared by cloning it. All requests are done asynchronously over the same connection.

If the client has an error connecting, the first request made will present that error. If the client disconnects while processing requests, all requests being processed will exit and return Error::Disconnected. The client will automatically try reconnecting.

The goal of this design of this reconnection strategy is to make it easier to build resilliant apps. By allowing existing Client instances to recover and reconnect, each component of the apps built can adopt a “retry-to-recover” design, or “abort-and-fail” depending on how critical the database is to operation.

pub async fn send_api_request(
    &'_ self,
    request: <A as CustomApi>::Request
) -> Result<<A as CustomApi>::Response, Error<<A as CustomApi>::Error>>

Sends an api request.

pub async fn effective_permissions(&'_ self) -> Option<Permissions>

Returns the current effective permissions for the client. Returns None if unauthenticated.

Trait Implementations

impl<A> Clone for Client<A> where
    A: CustomApi, 

fn clone(&self) -> Client<A>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<A> Debug for Client<A> where
    A: Debug + CustomApi, 

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<A> PartialEq<Client<A>> for Client<A> where
    A: CustomApi, 

fn eq(&self, other: &Client<A>) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<A> StorageConnection for Client<A> where
    A: CustomApi, 

type Database = RemoteDatabase<A>

The type that represents a database for this implementation.

fn create_database_with_schema<'life0, 'life1, 'async_trait>(
    &'life0 self,
    name: &'life1 str,
    schema: SchemaName,
    only_if_needed: bool
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Client<A>: 'async_trait, 

Creates a database named name using the SchemaName schema.

fn database<'life0, 'life1, 'async_trait, DB>(
    &'life0 self,
    name: &'life1 str
) -> Pin<Box<dyn Future<Output = Result<<Client<A> as StorageConnection>::Database, Error>> + Send + 'async_trait, Global>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    DB: Schema + 'async_trait,
    Client<A>: 'async_trait, 

Returns a reference to database name with schema DB.

fn delete_database<'life0, 'life1, 'async_trait>(
    &'life0 self,
    name: &'life1 str
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Client<A>: 'async_trait, 

Deletes a database named name.

fn list_databases<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Vec<Database, Global>, Error>> + Send + 'async_trait, Global>> where
    'life0: 'async_trait,
    Client<A>: 'async_trait, 

Lists the databases in this storage.

fn list_available_schemas<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Vec<SchemaName, Global>, Error>> + Send + 'async_trait, Global>> where
    'life0: 'async_trait,
    Client<A>: 'async_trait, 

Lists the SchemaNames registered with this storage.

fn create_user<'life0, 'life1, 'async_trait>(
    &'life0 self,
    username: &'life1 str
) -> Pin<Box<dyn Future<Output = Result<u64, Error>> + Send + 'async_trait, Global>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Client<A>: 'async_trait, 

Creates a user.

fn delete_user<'user, 'life0, 'async_trait, U>(
    &'life0 self,
    user: U
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>> where
    'user: 'async_trait,
    'life0: 'async_trait,
    U: Nameable<'user, u64> + Send + Sync + 'async_trait,
    Client<A>: 'async_trait, 

Deletes a user.

fn set_user_password<'user, 'life0, 'async_trait, U>(
    &'life0 self,
    user: U,
    password: SensitiveString
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>> where
    'user: 'async_trait,
    'life0: 'async_trait,
    U: Nameable<'user, u64> + Send + Sync + 'async_trait,
    Client<A>: 'async_trait, 

Sets a user’s password.

fn authenticate<'user, 'life0, 'async_trait, U>(
    &'life0 self,
    user: U,
    authentication: Authentication
) -> Pin<Box<dyn Future<Output = Result<Authenticated, Error>> + Send + 'async_trait, Global>> where
    'user: 'async_trait,
    'life0: 'async_trait,
    U: Nameable<'user, u64> + Send + Sync + 'async_trait,
    Client<A>: 'async_trait, 

Authenticates as a user with a authentication method.

fn add_permission_group_to_user<'user, 'group, 'life0, 'async_trait, U, G>(
    &'life0 self,
    user: U,
    permission_group: G
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>> where
    'user: 'async_trait,
    'group: 'async_trait,
    'life0: 'async_trait,
    U: Nameable<'user, u64> + Send + Sync + 'async_trait,
    G: Nameable<'group, u64> + Send + Sync + 'async_trait,
    Client<A>: 'async_trait, 

Adds a user to a permission group.

fn remove_permission_group_from_user<'user, 'group, 'life0, 'async_trait, U, G>(
    &'life0 self,
    user: U,
    permission_group: G
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>> where
    'user: 'async_trait,
    'group: 'async_trait,
    'life0: 'async_trait,
    U: Nameable<'user, u64> + Send + Sync + 'async_trait,
    G: Nameable<'group, u64> + Send + Sync + 'async_trait,
    Client<A>: 'async_trait, 

Removes a user from a permission group.

fn add_role_to_user<'user, 'group, 'life0, 'async_trait, U, G>(
    &'life0 self,
    user: U,
    role: G
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>> where
    'user: 'async_trait,
    'group: 'async_trait,
    'life0: 'async_trait,
    U: Nameable<'user, u64> + Send + Sync + 'async_trait,
    G: Nameable<'group, u64> + Send + Sync + 'async_trait,
    Client<A>: 'async_trait, 

Adds a user to a permission group.

fn remove_role_from_user<'user, 'group, 'life0, 'async_trait, U, G>(
    &'life0 self,
    user: U,
    role: G
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>> where
    'user: 'async_trait,
    'group: 'async_trait,
    'life0: 'async_trait,
    U: Nameable<'user, u64> + Send + Sync + 'async_trait,
    G: Nameable<'group, u64> + Send + Sync + 'async_trait,
    Client<A>: 'async_trait, 

Removes a user from a permission group.

fn create_database<'life0, 'life1, 'async_trait, DB>(
    &'life0 self,
    name: &'life1 str,
    only_if_needed: bool
) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + 'async_trait, Global>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    DB: Schema + 'async_trait,
    Self: 'async_trait, 

Creates a database named name with the Schema provided.