Struct bolt_client::Client

pub struct Client { /* fields omitted */ }

Methods

impl Client

pub async fn new_tcp(addr: impl ToSocketAddrs) -> Fallible<Self>

Create a new TCP connection to the server at the given address.

pub async fn new_secure_tcp<'_>(
    domain: &'_ str,
    addr: impl ToSocketAddrs
) -> Fallible<Self>

Create a new TCP connection to the server at the given address, secured using TLS.

pub async fn init<'_>(
    &'_ mut self,
    client_name: String,
    auth_token: HashMap<String, String>
) -> Fallible<Message>

Send an INIT message to the server.

Description

The INIT message is a client message used once to initialize the session. 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: String,
    parameters: Option<HashMap<String, Value>>
) -> Fallible<Message>

Send a RUN message to the server.

Description

The RUN message is a client message used to pass a statement for execution on the server. 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 meta data 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 {"fields": …​, "result_available_after"} 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 run_pipelined<'_>(
    &'_ mut self,
    messages: Vec<Message>
) -> Fallible<Vec<Message>>

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 an ACK_FAILURE message to the server. Until the server receives the 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.

pub async fn discard_all<'_>(&'_ mut self) -> Fallible<Message>

Send a DISCARD_ALL message to the server.

Description

The DISCARD_ALL message is a client message used to discard all remaining items from the active result stream.

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) -> Fallible<(Message, Vec<Record>)>

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 client message used to retrieve all remaining items from the active result stream.

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) -> Fallible<Message>

Send an ACK_FAILURE message to the server.

Description

The ACK_FAILURE message is a 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) -> Fallible<Message>

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)

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

Trait Implementations

impl Debug for Client

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

Formats the value using the given formatter.