1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172

//! An asynchronous client for Bolt-compatible servers.
//!
//! # Example
//! The below example demonstrates how to communicate with a Neo4j server using Bolt protocol version 3.
//! ```
//! use std::collections::HashMap;
//! use std::convert::TryFrom;
//! use std::env;
//! use std::iter::FromIterator;
//!
//! use tokio::prelude::*;
//!
//! use bolt_client::Client;
//! use bolt_proto::{Message, Value};
//! use bolt_proto::message::*;
//! use bolt_proto::value::*;
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create a new connection to the server and perform a handshake to establish a
//!     // protocol version. In this example, all connection/authentication details are
//!     // stored in environment variables. A domain is optional - including it will
//!     // create a client that uses a TLS-secured connection.
//!     let mut client = Client::new(env::var("BOLT_TEST_ADDR")?,
//!                                  env::var("BOLT_TEST_DOMAIN").ok().as_deref()).await?;
//!     // This example demonstrates usage of the v3 protocol
//!     let handshake_result = client.handshake(&[3, 0, 0, 0]).await;
//!     # if let Err(bolt_client::error::Error::HandshakeFailed) = handshake_result {
//!     #     println!("Skipping test: client handshake failed");
//!     #     return Ok(());
//!     # }
//!     
//!     // Send a HELLO message with authorization details to the server to initialize
//!     // the session.
//!     let response: Message = client.hello(
//!         HashMap::from_iter(vec![
//!             ("user_agent".to_string(), "my-client-name/1.0".to_string()),
//!             ("scheme".to_string(), "basic".to_string()),
//!             ("principal".to_string(), env::var("BOLT_TEST_USERNAME")?),
//!             ("credentials".to_string(), env::var("BOLT_TEST_PASSWORD")?),
//!         ])).await?;
//!     assert!(Success::try_from(response).is_ok());
//!
//!     // Run a query on the server and retrieve the results
//!     let response = client.run_with_metadata("RETURN 1 as num;".to_string(), None, None).await?;
//!     // Successful responses will include a SUCCESS message with related metadata
//!     // Consuming these messages is optional and will be skipped for the rest of the example
//!     assert!(Success::try_from(response).is_ok());
//!
//!     // Use PULL_ALL to retrieve results of the query, organized into RECORD messages
//!     let (response, records): (Message, Vec<Record>) = client.pull_all().await?;
//!     # assert!(Success::try_from(response).is_ok());
//!
//!     // Integers are automatically packed into the smallest possible byte representation
//!     assert_eq!(records[0].fields(), &[Value::from(1 as i8)]);
//!     #
//!     # client.run_with_metadata("MATCH (n) DETACH DELETE n;".to_string(), None, None).await?;
//!     # client.pull_all().await?;
//!
//!     // Run a more complex query with parameters
//!     let params = HashMap::from_iter(vec![("name".to_string(), Value::from("Rust"))]);
//!     client.run_with_metadata(
//!         "CREATE (:Client)-[:WRITTEN_IN]->(:Language {name: $name});".to_string(),
//!         Some(params), None).await?;
//!     client.pull_all().await?;
//!
//!     // Grab a node from the database and convert it to a native type
//!     client.run_with_metadata(
//!         "MATCH (rust:Language) RETURN rust;".to_string(), None, None).await?;
//!     let (response, records): (Message, Vec<Record>) = client.pull_all().await?;
//!     # assert!(Success::try_from(response).is_ok());
//!     let node = Node::try_from(records[0].fields()[0].clone())?;
//!
//!     // Access properties from returned values
//!     assert_eq!(node.labels(), &["Language".to_string()]);
//!     assert_eq!(node.properties(),
//!                &HashMap::from_iter(vec![("name".to_string(), Value::from("Rust"))]));
//!
//!     // End the connection with the server
//!     client.goodbye().await?;
//!
//!     Ok(())
//! }
//! ```
//!
//! For versions 1 and 2 of the protocol, the above example would have a few key differences:
//! ```
//! # use std::collections::HashMap;
//! # use std::convert::TryFrom;
//! # use std::env;
//! # use std::iter::FromIterator;
//! #
//! # use tokio::prelude::*;
//! #
//! # use bolt_client::Client;
//! # use bolt_proto::{Message, Value};
//! # use bolt_proto::message::*;
//! # use bolt_proto::value::*;
//! #
//! # #[tokio::main]
//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
//! #     let mut client = Client::new(env::var("BOLT_TEST_ADDR")?,
//! #                                  env::var("BOLT_TEST_DOMAIN").ok().as_deref()).await?;
//! // For the handshake we want to support versions 1 and 2 only, preferring version 2.
//! let handshake_result = client.handshake(&[2, 1, 0, 0]).await;
//!     # if let Err(bolt_client::error::Error::HandshakeFailed) = handshake_result {
//!     #     println!("Skipping test: client handshake failed");
//!     #     return Ok(());
//!     # }
//!     
//! // Instead of `hello`, we call `init`, and the user agent string is provided separately.
//! let response: Message = client.init(
//!     "my-client-name/1.0".to_string(),
//!     HashMap::from_iter(vec![
//!         ("scheme".to_string(), "basic".to_string()),
//!         ("principal".to_string(), env::var("BOLT_TEST_USERNAME")?),
//!         ("credentials".to_string(), env::var("BOLT_TEST_PASSWORD")?),
//!     ])).await?;
//!     # assert!(Success::try_from(response).is_ok());
//!
//! // Instead of `run_with_metadata`, we call `run`, and there is no third parameter for metadata.
//! let response = client.run("RETURN 1 as num;".to_string(), None).await?;
//!     # assert!(Success::try_from(response).is_ok());
//!     # let (response, records): (Message, Vec<Record>) = client.pull_all().await?;
//!     # assert!(Success::try_from(response).is_ok());
//!     # assert_eq!(records[0].fields(), &[Value::from(1 as i8)]);
//!     #
//!     # client.run("MATCH (n) DETACH DELETE n;".to_string(), None).await?;
//!     # client.pull_all().await?;
//!     #
//!     # client.run("CREATE (:Client)-[:WRITTEN_IN]->(:Language {name: $name});".to_string(),
//!     #            Some(HashMap::from_iter(
//!     #                vec![("name".to_string(), Value::from("Rust"))]
//!     #            ))).await?;
//!     # client.pull_all().await?;
//!     # client.run("MATCH (rust:Language) RETURN rust;".to_string(), None).await?;
//!     # let (response, records): (Message, Vec<Record>) = client.pull_all().await?;
//!     # assert!(Success::try_from(response).is_ok());
//!     #
//!     # let node = Node::try_from(records[0].fields()[0].clone())?;
//!     # assert_eq!(node.labels(), &["Language".to_string()]);
//!     # assert_eq!(node.properties(),
//!     #            &HashMap::from_iter(vec![("name".to_string(), Value::from("Rust"))]));
//!
//! // There is no call to `goodbye`
//!     # Ok(())
//! # }
//! ```
//! See the documentation of the `Client` struct for information on transaction management, error handling, and more.
#[doc(inline)]
pub use self::client::Client;

pub mod client;
pub mod error;
mod stream;

#[doc(hidden)]
#[macro_export]
macro_rules! skip_if_handshake_failed {
    ($var:expr) => {
        if let ::std::result::Result::Err(crate::error::Error::HandshakeFailed) = $var {
            println!("Skipping test: client handshake failed");
            return;
        }
    };
    ($var:expr, $ret:expr) => {
        if let ::std::result::Result::Err(crate::error::Error::HandshakeFailed) = $var {
            println!("Skipping test: client handshake failed");
            return $ret;
        }
    };
}