Merge pull request #12 from robsdedude/feat/bolt-5.4

Add bolt 5.4 support (telemetry)

CHANGELOG.md

@@ -1,31 +1,52 @@
 # Changelog
 
+⚠️ marks breaking changes or pending breaking changes (deprecations).
+
 ## NEXT
- - Removed useless lifetime parameter from `SessionConfig::with_database()`.
- - Changed return type of `ConnectionConfig::with_encryption_trust_any_certificate() ` from `Result<Self, Error>` to `Self`.
- - Add support for Bolt 5.2, which adds notification filtering.
- - Add `Driver::is_encrypted()`.
- - Reduce the number of lifetime generic parameters in `TransactionQueryBuilder` and `TransactionRecordStream`.
- - Fix `Transaction::rolblack()` failing if a result stream failed before.
- - Introduce `neo4j::driver::Conifg::with_keep_alive()` and `without_keep_alive()`.
- - Add support for Bolt 5.3 (bolt agent).
+***
+**⭐ New Features**
+- Add support for Bolt 5.2, which adds notification filtering.
+- Add support for Bolt 5.3 (bolt agent).
+- Add support for Bolt 5.4 (telemetry).
+- Add `Driver::is_encrypted()`.
+- Introduce `neo4j::driver::Conifg::with_keep_alive()` and `without_keep_alive()`.
+
+**🔧 Fixes**
+- Fix `Transaction::rolblack()` failing if a result stream failed before.
+- Fix errors during transaction `BEGIN` not being properly propagated.
+- Fix propagation of `is_retryable()` of errors within transactions.
+- Fix connection hint `connection.recv_timeout_seconds` not always being respected leading to connections timeing out too late.
+
+**🧹Clean-up**
+- ⚠️ Removed useless lifetime parameter from `SessionConfig::with_database()`.
+- ⚠️ Changed return type of `ConnectionConfig::with_encryption_trust_any_certificate() ` from `Result<Self, Error>` to `Self`.
+- ⚠️ Reduce the number of lifetime generic parameters in `TransactionQueryBuilder` and `TransactionRecordStream`.
+
 
 ## 0.0.2
- - Update dependencies.  
-   Among others `rustls`.
-   To accommodate this change, the `rustls_dangerous_configuration` feature was removed.
-   This update also affects `ConnectionConfig::with_encryption_custom_tls_config()`, which accepts a custom `rustls::ClientConfig`.
- - Make `Record{entries}` private and offer many helper methods instead.
- - Add `EagerResult::into_scalar()`.
- - Renamed `RetryableError` to `RetryError`
- - Fix `Driver::execute_query()::run()` not committing the transaction.
- - Removed `AutoCommitBuilder::without_transaction_timeout` and `AutoCommitBuilder::with_default_transaction_timeout`
-   in favor of `AutoCommitBuilder::with_transaction_timeout` in combination with `TransactionTimeout::none`,
-   `TransactionTimeout::from_millis` and `TransactionTimeout::default`.  
-   Same for `TransactionBuilder`.
- - Move `neo4j::Address` to `neo4j::address::Address`
- - Impl `FromStr` for `neo4j::driver::ConnectionConfig` (besides `TryFrom<&str>`).
- - Much more documentation.
+***
+**👏 Improvements**
+- Impl `FromStr` for `neo4j::driver::ConnectionConfig` (besides `TryFrom<&str>`).
+
+- **🧹Clean-up**
+- ⚠️ Update dependencies.  
+  Among others `rustls`.
+  To accommodate this change, the `rustls_dangerous_configuration` feature was removed.
+  This update also affects `ConnectionConfig::with_encryption_custom_tls_config()`, which accepts a
+  custom `rustls::ClientConfig`.
+- ⚠️ Make `Record{entries}` private and offer many helper methods instead.
+- Add `EagerResult::into_scalar()`.
+- ⚠️ Renamed `RetryableError` to `RetryError`
+- Fix `Driver::execute_query()::run()` not committing the transaction.
+- ⚠️ Removed `AutoCommitBuilder::without_transaction_timeout` and `AutoCommitBuilder::with_default_transaction_timeout`
+  in favor of `AutoCommitBuilder::with_transaction_timeout` in combination with `TransactionTimeout::none`,
+  `TransactionTimeout::from_millis` and `TransactionTimeout::default`.  
+  Same for `TransactionBuilder`.
+- ⚠️ Move `neo4j::Address` to `neo4j::address::Address`
+
+**📚 Docs**
+- Much more documentation.
 
 ## 0.0.1
+
 Initial release

README.md

@@ -2,117 +2,113 @@ Neo4j Driver for Rust
 =====================
 
 Disclaimer:
+ * While I'm currently affiliated with Neo4j, this is my private hobby project.
+   It's not an officially supported piece of software by Neo4j.
+ * This is a work in progress, and it's mostly developed in my spare time.
+ * This project is primarily meant for private studies.
+   Yet, I decided to publish it as it might be useful for others as well.
 
-* While I'm currently affiliated with Neo4j, this is my private hobby project.
-  It's not an officially supported piece of software by Neo4j.
-* This is a work in progress, and it's mostly developed in my spare time.
-* This project is primarily meant for private studies.
-  Yet, I decided to publish it as it might be useful for others as well.
 
 ## MSRV
-
 Currently, this crate's minimum supported Rust version is `1.70`.
 A bump in MSRV is considered a minor breaking change.
 
-## Feature Progress
-
-* [x] (Well-Written) Docs and Examples
-* [ ] Driver
-    * [ ] Config
-        * [x] `user_agent`
-        * [x] `auth`
-            * [x] basic
-            * [x] kerberos
-            * [x] bearer
-            * [x] custom
-        * [x] `max_connection_pool_size`
-        * [x] `fetch_size`
-        * [x] `connection_timeout`
-        * [x] `connection_acquisition_timeout`
-        * [x] `resolver`
-        * [x] `max_connection_lifetime`
-        * [x] routing and direct connections
-        * [x] `keep_alive`
-        * [x] `TLS`
-        * [ ] mTLS for 2FA
-    * [x] `.session`
-    * [x] `.supports_multi_db`
-    * [x] `.supports_session_auth`
-    * [x] `.execute_query`
-    * [x] `.verify_connectivity`
-    * [x] `.verify_authentication`
-    * [x] `.get_server_info`
-    * [x] `.is_encrypted`
-* [x] Session
-    * [x] Config
-        * [x] database
-        * [x] bookmarks
-        * [x] impersonated_user
-        * [x] fetch_size
-        * [x] session_auth
-    * [x] Auto Commit
-    * [x] Transaction
-        * [x] Config
-            * [x] Metadata
-            * [x] Timeout
-        * [x] Unmanaged
-        * [x] With Retry
-* [ ] Result (`RecordStream`)
-    * [x] `.keys`
-    * [x] `.consume` (Summary)
-        * [x] `.server_info`
-            * [x] `.address`
-            * [x] `.server_agent`
-            * [x] `.protocol_version`
-        * [x] `.database`
-        * [x] `.query`, `.parameters` (won't implement)
-        * [x] `.query_type`
-        * [x] `.plan`
-        * [x] `.profile`
-        * [x] `.notifications`
-        * [x] `.counters`
-        * [x] `.result_available_after`
-        * [x] `.result_consumed_after`
-    * [x] `.single`
-    * [ ] `.into::<EagerResult>()`
-    * [ ] `.closed` (not sure if needed?)
-    * [ ] Record
-        * [x] most basic functionality
-        * [ ] ergonomic way to access by key
-* [x] Bookmark Management
-* [ ] Protocol Versions
-    * [x] 4.4
-    * [x] 5.0 (utc fix)
-    * [x] 5.1 (re-auth)
-    * [x] 5.2 (notification filtering)
-    * [x] 5.3 (bolt agent)
-    * [ ] 5.4 (telemetry)
-* [x] Types
-    * [x] `Null`
-    * [x] `Integer`
-    * [x] `Float`
-    * [x] `String`
-    * [x] `Boolean`
-    * [x] `Bytes`
-    * [x] `List`
-    * [x] `Map`
-    * [x] `Node`
-    * [x] `Relationship`
-    * [x] `Path`
-    * [x] `Spatial` (point)
-    * [x] `Temporal` (date, time, datetime, duration)
-* [ ] Proper Unit Tests
-* [x] CI
-    * [x] rustfmt
-    * [x] clippy
-    * [x] Unit Tests
-        * [ ] Public API SemVer Compatibility Tests ([cargo-public-api](https://github.com/enselic/cargo-public-api))
-    * [x] TestKit
 
-## Note on async
+## Feature Progress
+ * [x] (Well-Written) Docs and Examples
+ * [ ] Driver
+   * [ ] Config
+     * [x] `user_agent`
+     * [x] `auth`
+       * [x] basic
+       * [x] kerberos
+       * [x] bearer
+       * [x] custom
+     * [x] `max_connection_pool_size`
+     * [x] `fetch_size`
+     * [x] `connection_timeout`
+     * [x] `connection_acquisition_timeout`
+     * [x] `resolver`
+     * [x] `max_connection_lifetime`
+     * [x] routing and direct connections
+     * [x] `keep_alive`
+     * [x] `TLS`
+     * [ ] mTLS for 2FA
+   * [x] `.session`
+   * [x] `.supports_multi_db`
+   * [x] `.supports_session_auth`
+   * [x] `.execute_query`
+   * [x] `.verify_connectivity`
+   * [x] `.verify_authentication`
+   * [x] `.get_server_info`
+   * [x] `.is_encrypted`
+ * [x] Session
+   * [x] Config
+     * [x] database
+     * [x] bookmarks
+     * [x] impersonated_user
+     * [x] fetch_size
+     * [x] session_auth
+   * [x] Auto Commit
+   * [x] Transaction
+     * [x] Config
+       * [x] Metadata
+       * [x] Timeout
+     * [x] Unmanaged
+     * [x] With Retry
+ * [ ] Result (`RecordStream`)
+   * [x] `.keys`
+   * [x] `.consume` (Summary)
+     * [x] `.server_info`
+       * [x] `.address`
+       * [x] `.server_agent`
+       * [x] `.protocol_version`
+     * [x] `.database`
+     * [x] `.query`, `.parameters` (won't implement)
+     * [x] `.query_type`
+     * [x] `.plan`
+     * [x] `.profile`
+     * [x] `.notifications`
+     * [x] `.counters`
+     * [x] `.result_available_after`
+     * [x] `.result_consumed_after`
+   * [x] `.single`
+   * [ ] `.into::<EagerResult>()`
+   * [ ] `.closed` (not sure if needed?)
+   * [ ] Record
+     * [x] most basic functionality
+     * [ ] ergonomic way to access by key
+ * [x] Bookmark Management
+ * [x] Protocol Versions
+   * [x] 4.4
+   * [x] 5.0 (utc fix)
+   * [x] 5.1 (re-auth)
+   * [x] 5.2 (notification filtering)
+   * [x] 5.3 (bolt agent)
+   * [x] 5.4 (telemetry)
+ * [x] Types
+   * [x] `Null`
+   * [x] `Integer`
+   * [x] `Float`
+   * [x] `String`
+   * [x] `Boolean`
+   * [x] `Bytes`
+   * [x] `List`
+   * [x] `Map`
+   * [x] `Node`
+   * [x] `Relationship`
+   * [x] `Path`
+   * [x] `Spatial` (point)
+   * [x] `Temporal` (date, time, datetime, duration)
+ * [ ] Proper Unit Tests
+ * [x] CI
+   * [x] rustfmt
+   * [x] clippy
+   * [x] Unit Tests
+     * [ ] Public API SemVer Compatibility Tests ([cargo-public-api](https://github.com/enselic/cargo-public-api))
+   * [x] TestKit
 
-Currently, there are no plans to add async support until a proper abstraction over multiple runtimes is available so
-that users can choose their preferred runtime.
-As it stands, the async ecosystem would either force this crate to dictate a runtime or do an ugly dance to support
-multiple runtimes.
+## Note on async  
+Currently, there are no plans to add async support until a proper abstraction over multiple runtimes is available so that users can choose their preferred runtime.
+As it stands, the async ecosystem would either force this crate to dictate a runtime or do an ugly dance to support multiple runtimes.
 Even then, the supported runtimes would be limited to the ones chosen by this crate.

neo4j/src/driver.rs

@@ -40,6 +40,7 @@ pub use config::{
     InvalidRoutingContextError, KeepAliveConfig, TlsConfigError,
 };
 pub use eager_result::{EagerResult, ScalarError};
+use io::bolt::message_parameters::TelemetryAPI;
 #[cfg(feature = "_internal_testkit_backend")]
 pub use io::ConnectionPoolMetrics;
 use io::{AcquireConfig, Pool, PoolConfig, PooledBolt, SessionAuth, UpdateRtArgs};
@@ -111,6 +112,7 @@ impl Driver {
             connection_acquisition_timeout: config.connection_acquisition_timeout,
             resolver: config.resolver,
             notification_filters: Arc::new(config.notification_filter),
+            telemetry: config.telemetry,
         };
         Driver {
             config: ReducedDriverConfig {
@@ -926,7 +928,8 @@ impl<
             .transaction()
             .with_transaction_meta(meta.borrow())
             .with_transaction_timeout(timeout)
-            .with_routing_control(mode);
+            .with_routing_control(mode)
+            .with_api_overwrite(Some(TelemetryAPI::DriverLevel));
         tx_builder.run(move |tx| {
             let mut result_stream = tx.query(query).with_parameters(param).run()?;
             let res = receiver(result_stream.raw_stream_mut())?;
@@ -971,7 +974,8 @@ impl<
             .transaction()
             .with_transaction_meta(meta.borrow())
             .with_transaction_timeout(timeout)
-            .with_routing_control(mode);
+            .with_routing_control(mode)
+            .with_api_overwrite(Some(TelemetryAPI::DriverLevel));
         tx_builder.run_with_retry(retry_policy, move |tx| {
             let mut result_stream = tx
                 .query(query.as_ref())

neo4j/src/driver/config.rs

@@ -37,7 +37,7 @@ use notification::NotificationFilter;
 
 // imports for docs
 #[allow(unused)]
-use super::session::SessionConfig;
+use super::session::{AutoCommitBuilder, SessionConfig, TransactionBuilder};
 #[allow(unused)]
 use super::ExecuteQueryBuilder;
 #[allow(unused)]
@@ -63,6 +63,7 @@ pub struct DriverConfig {
     pub(crate) resolver: Option<Box<dyn AddressResolver>>,
     pub(crate) notification_filter: NotificationFilter,
     pub(crate) keep_alive: Option<KeepAliveConfig>,
+    pub(crate) telemetry: bool,
 }
 
 #[derive(Debug)]
@@ -155,6 +156,7 @@ impl Default for DriverConfig {
             resolver: None,
             notification_filter: Default::default(),
             keep_alive: None,
+            telemetry: true,
         }
     }
 }
@@ -532,6 +534,31 @@ impl DriverConfig {
         self.keep_alive = None;
         self
     }
+
+    /// Enable or disable telemetry.
+    ///
+    /// If enabled (default) and the server requests is, the driver will send anonymous API usage
+    /// statistics to the server.
+    /// Currently, everytime one of the following APIs is used to execute a query
+    /// (for the first time), the server is informed of this
+    /// (without any further information like arguments, client identifiers, etc.):
+    ///
+    /// * [`ExecuteQueryBuilder::run()`] / [`ExecuteQueryBuilder::run_with_retry()`]
+    /// * [`TransactionBuilder::run()`]
+    /// * [`TransactionBuilder::run_with_retry()`]
+    /// * [`AutoCommitBuilder::run()`]
+    ///
+    /// # Example
+    /// ```
+    /// use neo4j::driver::DriverConfig;
+    ///
+    /// let config = DriverConfig::new().with_telemetry(false);
+    /// ```
+    #[inline]
+    pub fn with_telemetry(mut self, telemetry: bool) -> Self {
+        self.telemetry = telemetry;
+        self
+    }
 }
 
 impl ConnectionConfig {