[−][src]Struct bolt_client::Client

pub struct Client<S: AsyncRead + AsyncWrite + Unpin> { /* fields omitted */ }

An asynchronous client for Bolt servers.

Implementations

`impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>`[src]

`pub async fn init<'_>( &'_ mut self, client_name: impl Into<String>, auth_token: Metadata ) -> Result<Message>`[src]

Send an INIT message to the server.

Description

The INIT message is a Bolt v1 - v2 client message used once to initialize the session. For Bolt v3+, see hello.

This message is always the first message the client sends after negotiating protocol version via the initial handshake. Sending any message other than INIT as the first message to the server will result in a FAILURE. The client must acknowledge failures using ACK_FAILURE, after which INIT may be reattempted.

Response

SUCCESS {…} if initialization has completed successfully
FAILURE {"code": …, "message": …} if the request was malformed, or if initialization cannot be performed at this time, or if the authorization failed.

`pub async fn run<'_>( &'_ mut self, statement: impl Into<String>, parameters: Option<Params> ) -> Result<Message>`[src]

Send a RUN message to the server.

Description

The RUN message is a Bolt v1 - v2 client message used to pass a statement for execution on the server. For Bolt v3+, see run_with_metadata.

On receipt of a RUN message, the server will start a new job by executing the statement with the parameters (optionally) supplied. If successful, the subsequent response will consist of a single SUCCESS message; if not, a FAILURE response will be sent instead. A successful job will always produce a result stream which must then be explicitly consumed (via PULL_ALL or DISCARD_ALL), even if empty.

Depending on the statement you are executing, additional metadata may be returned in both the SUCCESS message from the RUN, as well as in the final SUCCESS after the stream has been consumed. It is up to the statement you are running to determine what metadata to return. Notably, most queries will contain a fields metadata section in the SUCCESS message for the RUN statement, which lists the result record field names, and a result_available_after section measuring the number of milliseconds it took for the results to be available for consumption.

In the case where a previous result stream has not yet been fully consumed, an attempt to RUN a new job will trigger a FAILURE response.

If an unacknowledged failure is pending from a previous exchange, the server will immediately respond with a single IGNORED message and take no further action.

Response

SUCCESS {…} if the statement has been accepted for execution
FAILURE {"code": …, "message": …} if the request was malformed or if a statement may not be executed at this time

`pub async fn discard_all<'_>(&'_ mut self) -> Result<Message>`[src]

Send a DISCARD_ALL message to the server.

Description

The DISCARD_ALL message is a Bolt v1 - v3 client message used to discard all remaining items from the active result stream. For Bolt v4, see discard.

On receipt of a DISCARD_ALL message, the server will dispose of all remaining items from the active result stream, close the stream and send a single SUCCESS message to the client. If no result stream is currently active, the server will respond with a single FAILURE message.

If an unacknowledged failure is pending from a previous exchange, the server will immediately respond with a single IGNORED message and take no further action.

Response

SUCCESS {…} if the result stream has been successfully discarded
FAILURE {"code": …, "message": …} if no result stream is currently available

`pub async fn pull_all<'_>(&'_ mut self) -> Result<(Message, Vec<Record>)>`[src]

Send a PULL_ALL message to the server. Returns a tuple containing a Vec of the records returned from the server as well as the summary message (SUCCESS or FAILURE).

Description

The PULL_ALL message is a Bolt v1 - v3 client message used to retrieve all remaining items from the active result stream. For Bolt v4, see pull.

On receipt of a PULL_ALL message, the server will send all remaining result data items to the client, each in a single RECORD message. The server will then close the stream and send a single SUCCESS message optionally containing summary information on the data items sent. If an error is encountered, the server must instead send a FAILURE message, discard all remaining data items and close the stream.

If an unacknowledged failure is pending from a previous exchange, the server will immediately respond with a single IGNORED message and take no further action.

Response

SUCCESS {…} if the result stream has been successfully transferred
FAILURE {"code": …, "message": …} if no result stream is currently available or if retrieval fails

`pub async fn ack_failure<'_>(&'_ mut self) -> Result<Message>`[src]

Send an ACK_FAILURE message to the server.

Description

The ACK_FAILURE message is a Bolt v1 - v2 client message used to acknowledge a failure the server has sent.

The following actions are performed by ACK_FAILURE:

clear any outstanding FAILURE state

In some cases, it may be preferable to use RESET after a failure, to clear the entire state of the connection.

Response

SUCCESS {…} if the session was successfully reset
FAILURE {"code": …, "message": …} if there is no failure waiting to be cleared

`pub async fn reset<'_>(&'_ mut self) -> Result<Message>`[src]

Send a RESET message to the server.

Description

The RESET message is a client message used to return the current session to a "clean" state. It will cause the session to IGNORE any message it is currently processing, as well as any message before RESET that had not yet begun processing. This allows RESET to abort long-running operations. It also means clients must be careful about pipelining RESET. Only send this if you are not currently waiting for a result from a prior message, or if you want to explicitly abort any prior message.

The following actions are performed by RESET:

force any currently processing message to abort with IGNORED
force any pending messages that have not yet started processing to be IGNORED
clear any outstanding FAILURE state
dispose of any outstanding result records
rollback the current transaction (if any)

For Bolt v1 - v2, see ack_failure for sending a message that only clears FAILURE state.

Response

SUCCESS {…} if the session was successfully reset
FAILURE {"code": …, "message": …} if a reset is not currently possible

`impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>`[src]

`pub async fn hello<'_>( &'_ mut self, metadata: Option<Metadata> ) -> Result<Message>`[src]

Send a HELLO message to the server.

Description

This message is the equivalent of INIT for Bolt v3+ clients, but the client name and auth token are merged into a single metadata object.

Response

SUCCESS {…} if initialization has completed successfully
FAILURE {"code": …, "message": …} if the request was malformed, or if initialization cannot be performed at this time, or if the authorization failed.

`pub async fn goodbye<'_>(&'_ mut self) -> Result<()>`[src]

Send a GOODBYE message to the server.

Description

The GOODBYE message is a Bolt v3+ client message used to end the session. The server will end the connection upon receipt of this message.

`pub async fn run_with_metadata<'_>( &'_ mut self, statement: impl Into<String>, parameters: Option<Params>, metadata: Option<Metadata> ) -> Result<Message>`[src]

Send a RUN_WITH_METADATA message to the server.

Description

This message is the equivalent of RUN for Bolt v3+ clients, but allows passing an arbitrary metadata hash along with the request.

Response

SUCCESS {…} if the statement has been accepted for execution
FAILURE {"code": …, "message": …} if the request was malformed or if a statement may not be executed at this time

`pub async fn begin<'_>( &'_ mut self, metadata: Option<Metadata> ) -> Result<Message>`[src]

Send a BEGIN message to the server.

Description

This Bolt v3+ message begins a transaction. A hash of arbitrary metadata can be passed along with the request.

Response

SUCCESS {…} if transaction has started successfully
FAILURE {"code": …, "message": …} if the request was malformed, or if transaction could not be started

`pub async fn commit<'_>(&'_ mut self) -> Result<Message>`[src]

Send a COMMIT message to the server.

Description

This Bolt v3+ message commits a transaction. Any changes made since the transaction was started will be persisted to the database. To instead cancel pending changes, send a ROLLBACK message.

Response

SUCCESS {…} if transaction has been committed successfully
FAILURE {"code": …, "message": …} if the request was malformed, or if transaction could not be committed

`pub async fn rollback<'_>(&'_ mut self) -> Result<Message>`[src]

Send a ROLLBACK message to the server.

Description

This Bolt v3+ message cancels a transaction. Any changes made since the transaction was started will be undone. To instead keep pending changes, send a COMMIT message.

Response

SUCCESS {…} if transaction has been rolled back successfully
FAILURE {"code": …, "message": …} if the request was malformed, or if transaction could not be rolled back

`impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>`[src]

`pub async fn discard<'_>( &'_ mut self, metadata: Option<Metadata> ) -> Result<Message>`[src]

Send a DISCARD message to the server.

Description

This message is the equivalent of DISCARD_ALL for Bolt v4+ clients, but allows passing an arbitrary metadata hash along with the request.

Response

SUCCESS {…} if the result stream has been successfully discarded
FAILURE {"code": …, "message": …} if no result stream is currently available

`pub async fn pull<'_>( &'_ mut self, metadata: Option<Metadata> ) -> Result<(Message, Vec<Record>)>`[src]

Send a PULL message to the server.

Description

This message is the equivalent of PULL_ALL for Bolt v4+ clients, but allows passing an arbitrary metadata hash along with the request.

Response

SUCCESS {…} if the result stream has been successfully transferred
FAILURE {"code": …, "message": …} if no result stream is currently available or if retrieval fails

`impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>`[src]

`pub async fn new<'_>( __arg0: S, preferred_versions: &'_ [u32; 4] ) -> Result<Self>`[src]

Attempt to create a new client from an asynchronous stream. A handshake will be performed with the provided protocol versions, and, if this succeeds, a Client will be returned.

`pub fn version(&self) -> u32`[src]

Get the current version of this client.

`pub async fn pipeline<'_>( &'_ mut self, messages: Vec<Message> ) -> Result<Vec<Message>>`[src]

Send multiple messages to the server without waiting for a response. Returns a Vec containing the server's response messages for each of the sent messages, in the order they were provided.

Description

The client is not required to wait for a response before sending more messages. Sending multiple messages together like this is called pipelining. For performance reasons, it is recommended that clients use pipelining as much as possible. Through pipelining, multiple messages can be transmitted together in the same network package, significantly reducing latency and increasing throughput.

A common technique is to buffer outgoing messages on the client until the last possible moment, such as when a commit is issued or a result is read by the application, and then sending all messages in the buffer together.

Failure Handling

Because the protocol leverages pipelining, the client and the server need to agree on what happens when a failure occurs, otherwise messages that were sent assuming no failure would occur might have unintended effects.

When requests fail on the server, the server will send the client a FAILURE message. The client must acknowledge the FAILURE message by sending a RESET (Bolt v3+) or ACK_FAILURE (Bolt v1-2) message to the server. Until the server receives the RESET/ACK_FAILURE message, it will send an IGNORED message in response to any other message from the client, including messages that were sent in a pipeline.

Trait Implementations

`impl<S: Debug + AsyncRead + AsyncWrite + Unpin> Debug for Client<S>`[src]

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

Auto Trait Implementations

`impl<S> RefUnwindSafe for Client<S> where S: RefUnwindSafe,`

`impl<S> Send for Client<S> where S: Send,`

`impl<S> Sync for Client<S> where S: Sync,`

`impl<S> Unpin for Client<S>`

`impl<S> UnwindSafe for Client<S> where S: UnwindSafe,`

Blanket Implementations

`impl<T> Any for T where T: 'static + ?Sized,` [src]

`fn type_id(&self) -> TypeId`[src]

`impl<T> Borrow<T> for T where T: ?Sized,` [src]

`fn borrow(&self) -> &T`[src]

`impl<T> BorrowMut<T> for T where T: ?Sized,` [src]

`fn borrow_mut(&mut self) -> &mut T`[src]

`impl<T> From<T> for T`[src]

`fn from(t: T) -> T`[src]

`impl<T, U> Into for T where U: From<T>,` [src]

`fn into(self) -> U`[src]

`impl<T, U> TryFrom for T where U: Into<T>,` [src]

`type Error = Infallible`

The type returned in the event of a conversion error.

`fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>`[src]

`impl<T, U> TryInto for T where U: TryFrom<T>,` [src]

`type Error = >::Error`

The type returned in the event of a conversion error.

[−][src]Struct bolt_client::Client

Implementations

impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>[src]

pub async fn init<'_>( &'_ mut self, client_name: impl Into<String>, auth_token: Metadata) -> Result<Message>[src]

pub async fn run<'_>( &'_ mut self, statement: impl Into<String>, parameters: Option<Params>) -> Result<Message>[src]

pub async fn discard_all<'_>(&'_ mut self) -> Result<Message>[src]

pub async fn pull_all<'_>(&'_ mut self) -> Result<(Message, Vec<Record>)>[src]

pub async fn ack_failure<'_>(&'_ mut self) -> Result<Message>[src]

pub async fn reset<'_>(&'_ mut self) -> Result<Message>[src]

impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>[src]

pub async fn hello<'_>( &'_ mut self, metadata: Option<Metadata>) -> Result<Message>[src]

pub async fn goodbye<'_>(&'_ mut self) -> Result<()>[src]

pub async fn run_with_metadata<'_>( &'_ mut self, statement: impl Into<String>, parameters: Option<Params>, metadata: Option<Metadata>) -> Result<Message>[src]

pub async fn begin<'_>( &'_ mut self, metadata: Option<Metadata>) -> Result<Message>[src]

pub async fn commit<'_>(&'_ mut self) -> Result<Message>[src]

pub async fn rollback<'_>(&'_ mut self) -> Result<Message>[src]

impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>[src]

pub async fn discard<'_>( &'_ mut self, metadata: Option<Metadata>) -> Result<Message>[src]

pub async fn pull<'_>( &'_ mut self, metadata: Option<Metadata>) -> Result<(Message, Vec<Record>)>[src]

impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>[src]

pub async fn new<'_>( __arg0: S, preferred_versions: &'_ [u32; 4]) -> Result<Self>[src]

pub fn version(&self) -> u32[src]

pub async fn pipeline<'_>( &'_ mut self, messages: Vec<Message>) -> Result<Vec<Message>>[src]

Trait Implementations

impl<S: Debug + AsyncRead + AsyncWrite + Unpin> Debug for Client<S>[src]

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

Auto Trait Implementations

impl<S> RefUnwindSafe for Client<S> where S: RefUnwindSafe,

impl<S> Send for Client<S> where S: Send,

impl<S> Sync for Client<S> where S: Sync,

impl<S> Unpin for Client<S>

impl<S> UnwindSafe for Client<S> where S: UnwindSafe,

Blanket Implementations

impl<T> Any for T where T: 'static + ?Sized, [src]

fn type_id(&self) -> TypeId[src]

impl<T> Borrow<T> for T where T: ?Sized, [src]

fn borrow(&self) -> &T[src]

impl<T> BorrowMut<T> for T where T: ?Sized, [src]

fn borrow_mut(&mut self) -> &mut T[src]

impl<T> From<T> for T[src]

fn from(t: T) -> T[src]

impl<T, U> Into<U> for T where U: From<T>, [src]

fn into(self) -> U[src]

impl<T, U> TryFrom<U> for T where U: Into<T>, [src]

type Error = Infallible

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>[src]

impl<T, U> TryInto<U> for T where U: TryFrom<T>, [src]

type Error = <U as TryFrom<T>>::Error

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>[src]

`impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>`[src]

`pub async fn init<'_>( &'_ mut self, client_name: impl Into<String>, auth_token: Metadata ) -> Result<Message>`[src]

`pub async fn run<'_>( &'_ mut self, statement: impl Into<String>, parameters: Option<Params> ) -> Result<Message>`[src]

`pub async fn discard_all<'_>(&'_ mut self) -> Result<Message>`[src]

`pub async fn pull_all<'_>(&'_ mut self) -> Result<(Message, Vec<Record>)>`[src]

`pub async fn ack_failure<'_>(&'_ mut self) -> Result<Message>`[src]

`pub async fn reset<'_>(&'_ mut self) -> Result<Message>`[src]

`impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>`[src]

`pub async fn hello<'_>( &'_ mut self, metadata: Option<Metadata> ) -> Result<Message>`[src]

`pub async fn goodbye<'_>(&'_ mut self) -> Result<()>`[src]

`pub async fn run_with_metadata<'_>( &'_ mut self, statement: impl Into<String>, parameters: Option<Params>, metadata: Option<Metadata> ) -> Result<Message>`[src]

`pub async fn begin<'_>( &'_ mut self, metadata: Option<Metadata> ) -> Result<Message>`[src]

`pub async fn commit<'_>(&'_ mut self) -> Result<Message>`[src]

`pub async fn rollback<'_>(&'_ mut self) -> Result<Message>`[src]

`impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>`[src]

`pub async fn discard<'_>( &'_ mut self, metadata: Option<Metadata> ) -> Result<Message>`[src]

`pub async fn pull<'_>( &'_ mut self, metadata: Option<Metadata> ) -> Result<(Message, Vec<Record>)>`[src]

`impl<S: AsyncRead + AsyncWrite + Unpin> Client<S>`[src]

`pub async fn new<'_>( __arg0: S, preferred_versions: &'_ [u32; 4] ) -> Result<Self>`[src]

`pub fn version(&self) -> u32`[src]

`pub async fn pipeline<'_>( &'_ mut self, messages: Vec<Message> ) -> Result<Vec<Message>>`[src]

`impl<S: Debug + AsyncRead + AsyncWrite + Unpin> Debug for Client<S>`[src]

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

`impl<S> RefUnwindSafe for Client<S> where S: RefUnwindSafe,`

`impl<S> Send for Client<S> where S: Send,`

`impl<S> Sync for Client<S> where S: Sync,`

`impl<S> Unpin for Client<S>`

`impl<S> UnwindSafe for Client<S> where S: UnwindSafe,`

`impl<T> Any for T where T: 'static + ?Sized,` [src]

`fn type_id(&self) -> TypeId`[src]

`impl<T> Borrow<T> for T where T: ?Sized,` [src]

`fn borrow(&self) -> &T`[src]

`impl<T> BorrowMut<T> for T where T: ?Sized,` [src]

`fn borrow_mut(&mut self) -> &mut T`[src]

`impl<T> From<T> for T`[src]

`fn from(t: T) -> T`[src]

`impl<T, U> Into<U> for T where U: From<T>,` [src]

`fn into(self) -> U`[src]

`impl<T, U> TryFrom<U> for T where U: Into<T>,` [src]

`type Error = Infallible`

`fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`[src]

`impl<T, U> TryInto<U> for T where U: TryFrom<T>,` [src]

`type Error = <U as TryFrom<T>>::Error`

`fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>`[src]