Struct bonsaidb_client::Client

pub struct Client { /* 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()?;

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()?;

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()?;

With TLS

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

Using a Api

Our user guide has a section on creating and using an Api.

// `bonsaidb_core` is re-exported to `bonsaidb::core` or `bonsaidb_client::core`.
use bonsaidb_core::{
    api::{Api, Infallible},
    schema::{ApiName, Qualified},
};
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
pub struct Ping;

#[derive(Serialize, Deserialize, Clone, Debug)]
pub struct Pong;

impl Api for Ping {
    type Response = Pong;
    type Error = Infallible;

    fn name() -> ApiName {
        ApiName::private("ping")
    }
}

let client = Client::build(Url::parse("bonsaidb://localhost")?).finish()?;
let Pong = client.send_api_request_async(&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 api callback:

let client = Client::build(Url::parse("bonsaidb://localhost")?)
    .with_api_callback(ApiCallback::<Ping>::new(|result: Pong| async move {
        println!("Received out-of-band Pong");
    }))
    .finish()?;

Implementations

impl Client

pub fn build(url: Url) -> Builder

Returns a builder for a new client connecting to url.

impl Client

pub fn new(url: Url) -> Result<Self, 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_async<Api: Api>(
    &self,
    request: &Api
) -> Result<Api::Response, ApiError<Api::Error>>

Sends an api request.

pub fn invoke_api_request<Api: Api>(&self, request: &Api) -> Result<(), Error>

Sends an api request without waiting for a result. The response from the server will be ignored.

pub fn send_api_request<Api: Api>(
    &self,
    request: &Api
) -> Result<Api::Response, ApiError<Api::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 AsyncStorageConnection for Client

type Database = RemoteDatabase

The type that represents a database for this implementation.

type Authenticated = Self

The StorageConnection type returned from authentication calls.

fn admin<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Self::Database> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: 'async_trait, 

Returns the currently authenticated session, if any.

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>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: '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<Self::Database, Error>> + Send + 'async_trait>> where
    DB: 'async_trait + Schema,
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: '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>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: 'async_trait, 

Deletes a database named name.

fn list_databases<'life0, 'async_trait>(
    &'life0 self
) -> Pin<Box<dyn Future<Output = Result<Vec<Database>, Error>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: '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>, Error>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    Self: '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>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: '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>> where
    'user: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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>> where
    'user: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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<Self::Authenticated, Error>> + Send + 'async_trait>> where
    'user: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: 'async_trait, 

Authenticates as a user with a authentication method.

fn assume_identity<'life0, 'life1, 'async_trait>(
    &'life0 self,
    identity: IdentityReference<'life1>
) -> Pin<Box<dyn Future<Output = Result<Self::Authenticated, Error>> + Send + 'async_trait>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    Self: 'async_trait, 

Assumes the identity. If successful, the returned instance will have the merged permissions of the current authentication session and the permissions from identity.

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>> where
    'user: 'async_trait,
    'group: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    G: 'async_trait + Nameable<'group, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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>> where
    'user: 'async_trait,
    'group: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    G: 'async_trait + Nameable<'group, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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>> where
    'user: 'async_trait,
    'group: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    G: 'async_trait + Nameable<'group, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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>> where
    'user: 'async_trait,
    'group: 'async_trait,
    U: 'async_trait + Nameable<'user, u64> + Send + Sync,
    G: 'async_trait + Nameable<'group, u64> + Send + Sync,
    'life0: 'async_trait,
    Self: '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<Self::Database, Error>> + Send + 'async_trait, Global>> where
    'life0: 'async_trait,
    'life1: 'async_trait,
    DB: 'async_trait + Schema,
    Self: 'async_trait, 

Creates a database named name with the Schema provided.

impl Clone for Client

fn clone(&self) -> Client

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Client

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

Formats the value using the given formatter.

impl Drop for Client

fn drop(&mut self)

Executes the destructor for this type.

impl HasSession for Client

fn session(&self) -> Option<&Session>

Returns the currently authenticated session, if any.

fn allowed_to<'a, R, P>(&self, resource_name: R, action: &P) -> bool where
    R: AsRef<[Identifier<'a>]>,
    P: Action, 

Checks if action is permitted against resource_name.

fn check_permission<'a, R, P>(
    &self,
    resource_name: R,
    action: &P
) -> Result<(), Error> where
    R: AsRef<[Identifier<'a>]>,
    P: Action, 

Checks if action is permitted against resource_name. If permission is denied, returns a PermissionDenied error.

impl PartialEq<Client> for Client

fn eq(&self, other: &Self) -> 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 StorageConnection for Client

type Database = RemoteDatabase

The type that represents a database for this implementation.

type Authenticated = Self

The StorageConnection type returned from authentication calls.

fn admin(&self) -> Self::Database

Returns the administration database.

fn database<DB: Schema>(&self, name: &str) -> Result<Self::Database, Error>

Returns a reference to database name with schema DB.

fn create_database_with_schema(
    &self,
    name: &str,
    schema: SchemaName,
    only_if_needed: bool
) -> Result<(), Error>

Creates a database named name using the SchemaName schema.

fn delete_database(&self, name: &str) -> Result<(), Error>

Deletes a database named name.

fn list_databases(&self) -> Result<Vec<Database>, Error>

Lists the databases in this storage.

fn list_available_schemas(&self) -> Result<Vec<SchemaName>, Error>

Lists the SchemaNames registered with this storage.

fn create_user(&self, username: &str) -> Result<u64, Error>

Creates a user.

fn delete_user<'user, U: Nameable<'user, u64> + Send + Sync>(
    &self,
    user: U
) -> Result<(), Error>

Deletes a user.

fn set_user_password<'user, U: Nameable<'user, u64> + Send + Sync>(
    &self,
    user: U,
    password: SensitiveString
) -> Result<(), Error>

Sets a user’s password.

fn authenticate<'user, U: Nameable<'user, u64> + Send + Sync>(
    &self,
    user: U,
    authentication: Authentication
) -> Result<Self::Authenticated, Error>

Authenticates as a user with a authentication method.

fn assume_identity(
    &self,
    identity: IdentityReference<'_>
) -> Result<Self::Authenticated, Error>

Assumes the identity. If successful, the returned instance will have the merged permissions of the current authentication session and the permissions from identity.

fn add_permission_group_to_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
    &self,
    user: U,
    permission_group: G
) -> Result<(), Error>

Adds a user to a permission group.

fn remove_permission_group_from_user<'user, 'group, U: Nameable<'user, u64> + Send + Sync, G: Nameable<'group, u64> + Send + Sync>(
    &self,
    user: U,
    permission_group: G
) -> Result<(), Error>

Removes a user from a permission group.

fn add_role_to_user<'user, 'role, U: Nameable<'user, u64> + Send + Sync, R: Nameable<'role, u64> + Send + Sync>(
    &self,
    user: U,
    role: R
) -> Result<(), Error>

Adds a user to a permission group.

fn remove_role_from_user<'user, 'role, U: Nameable<'user, u64> + Send + Sync, R: Nameable<'role, u64> + Send + Sync>(
    &self,
    user: U,
    role: R
) -> Result<(), Error>

Removes a user from a permission group.

fn create_database<DB>(
    &self,
    name: &str,
    only_if_needed: bool
) -> Result<Self::Database, Error> where
    DB: Schema, 

Creates a database named name with the Schema provided.