Struct bonsaidb::client::Client[][src]

pub struct Client { /* fields omitted */ }
Expand description

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

Returns a builder for a new client connecting to url.

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.

Sends an api request.

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

Sends an api request.

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

Trait Implementations

The type that represents a database for this implementation.

The StorageConnection type returned from authentication calls.

Returns the currently authenticated session, if any.

Creates a database named name using the SchemaName schema. Read more

Returns a reference to database name with schema DB.

Deletes a database named name. Read more

Lists the databases in this storage.

Lists the SchemaNames registered with this storage.

Creates a user.

Deletes a user.

Sets a user’s password.

Authenticates as a user with a authentication method.

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

Adds a user to a permission group.

Removes a user from a permission group.

Adds a user to a permission group.

Removes a user from a permission group.

Creates a database named name with the Schema provided. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Executes the destructor for this type. Read more

Returns the currently authenticated session, if any.

Checks if action is permitted against resource_name.

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

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

This method tests for !=.

The type that represents a database for this implementation.

The StorageConnection type returned from authentication calls.

Returns the administration database.

Returns a reference to database name with schema DB.

Creates a database named name using the SchemaName schema. Read more

Deletes a database named name. Read more

Lists the databases in this storage.

Lists the SchemaNames registered with this storage.

Creates a user.

Deletes a user.

Sets a user’s password.

Authenticates as a user with a authentication method.

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

Adds a user to a permission group.

Removes a user from a permission group.

Adds a user to a permission group.

Removes a user from a permission group.

Creates a database named name with the Schema provided. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

The alignment of pointer.

The type for initializers.

Initializes a with the given initializer. Read more

Dereferences the given pointer. Read more

Mutably dereferences the given pointer. Read more

Drops the object pointed to by the given pointer. Read more

Should always be Self

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more