neo4j-ruby-driver 6.0.3.alpha.0-java → 6.2.1.beta.2-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b150718dde06f62283bdde11edaca77f17a31cd9d5988229c7f9f11d0579f5fb
-  data.tar.gz: 685a04443a4a9c8e8c90a3524a650166a6d63976d92e2e6418cd2807e2a531ef
+  metadata.gz: 8c23247c73132c7a801d9c4236df0e5ec06f7f89ca62e6a4bb5b5613a9ba0ca9
+  data.tar.gz: ad8bff687e3c0429cc26cc4c3663a7fcceb63f9c32c362dcb9a2cc968d416b38
 SHA512:
-  metadata.gz: c988f11be9f369490e07f0de554590059f6b61f782abf9e16d48c16237e9298b88a5f7776d632bab79a6e0138f973cf11e2058a8d611e099ff59349d15668bb1
-  data.tar.gz: 5ebe999f029edd2b4a20953b39176c1d3a6fd1c6fcf739c95084dabb7499b2e37f3fcd832a780d1dc8b2485a070ad18f6e72a0be62e2cfed62182b847c44dc9c
+  metadata.gz: e13cba51cf61aa2cf912d6cbf404acd8cd016e7d26aafbb50b89b988d30611e5e6b33ce22d1f786350389dc53730db535c92dc66fe94110e1a9dc7e892814094
+  data.tar.gz: 293189542dd4e549f20aaf0641734d677f94b12b6e323a07912e0c4d3caf08fa4d4706431b50a9e696ce3abbfc00ba7843e1f6499739760a00c2534fbc20ebcd

data/README.md

@@ -1,87 +1,52 @@
 # Neo4j Ruby Driver
 
-This repository contains 2 implementation of a Neo4j driver for Ruby:
-
-- based on official Java implementation. It provides a thin wrapper over the Java driver (only on jruby).
-- pure Ruby implementation. Available on all Ruby versions >= 3.1.
-
-Network communication is handled using [Bolt Protocol](https://7687.org/).
-
-<details>
-<summary>Table of Contents</summary>
-
-* [Getting started](#getting-started)
-    * [Installation](#installation)
-    * [Getting a Neo4j instance](#getting-a-neo4j-instance)
-    * [Quick start example](#quick-start-example)
-* [Server Compatibility](#server-compatibility)
-* [Usage](#usage)
-    * [Connecting to a database](#connecting-to-a-database)
-        * [URI schemes](#uri-schemes)
-        * [Authentication](#authentication)
-        * [Configuration](#configuration)
-        * [Connectivity check](#connectivity-check)
-    * [Sessions & transactions](#sessions--transactions)
-        * [Session](#session)
-        * [Auto-commit transactions](#auto-commit-transactions)
-        * [Explicit transactions](#explicit-transactions)
-        * [Read transactions](#read-transactions)
-        * [Write transactions](#write-transactions)
-    * [Working with results](#working-with-results)
-        * [Accessing Node and Relationship data](#accessing-node-and-relationship-data)
-        * [Working with Paths](#working-with-paths)
-        * [Working with temporal types](#working-with-temporal-types)
-    * [Type mapping](#type-mapping)
-    * [Advanced](#advanced)
-        * [Connection pooling](#connection-pooling)
-        * [Logging](#logging)
-* [For Driver Engineers](#for-driver-engineers)
-    * [Testing](#testing)
-* [Contributing](#contributing)
-* [License](#license)
-
-</details>
-
-## Getting started
-
-### Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
+A driver for [Neo4j](https://neo4j.com) that speaks the
+[Bolt protocol](https://neo4j.com/docs/bolt/current/), with **two
+implementations behind one public Ruby API**:
+
+- **MRI** (CRuby) — a pure-Ruby implementation of the Bolt protocol and
+  PackStream, with no Java dependency.
+- **JRuby** — a thin wrapper over the official
+  [neo4j-java-driver](https://github.com/neo4j/neo4j-java-driver), whose jars
+  are managed by [jar-dependencies](https://github.com/mkristian/jar-dependencies).
+
+Bundler installs the implementation matching your platform automatically, and
+your code is identical either way. The gem version tracks the Java-driver
+version it targets (e.g. `6.2.x`).
+
+## Features
+
+- **Bolt 3.0 – 6.1** with handshake-manifest version negotiation
+- **Complete type system**: Node, Relationship, Path, temporal types, spatial
+  Point, Duration, UUID, and a forward-compatible `UnsupportedType`
+- **Transactions**: auto-commit, explicit (default-rollback), and managed
+  read/write with automatic retry
+- **Sessions & causal consistency** via bookmarks
+- **Authentication**: basic, bearer, Kerberos, custom, and managed auth-token
+  managers (with re-auth); per-session and per-`execute_query` auth
+- **Cluster routing** with home-database resolution and caching
+- **Security**: TLS 1.2/1.3, `bolt+s`/`bolt+ssc` schemes, and mutual-TLS client
+  certificates
+- **Notifications config, GQL status objects, query telemetry**, connection
+  pooling, and a range of wire optimisations
+- Verified against the shared driver
+  [testkit](https://github.com/neo4j-drivers/testkit) conformance suite on both
+  implementations
+
+## Installation
+
+```ruby
+# Gemfile
 gem 'neo4j-ruby-driver'
 ```
 
-And then execute:
-
 ```bash
 bundle install
 ```
 
-Or install it yourself as:
-
-```bash
-gem install neo4j-ruby-driver
-```
-
-### Getting a Neo4j instance
-
-You need a running Neo4j database in order to use the driver with it. The easiest way to spin up a **local instance** is
-through a Docker container.
-
-The command below runs the latest Neo4j version in Docker, setting the admin username and password to `neo4j` and
-`password` respectively:
-
-```bash
-docker run \
-        -p7474:7474 \
-        -p7687:7687 \
-        -d \
-        -e NEO4J_AUTH=neo4j/password \
-        neo4j:latest
-```
+## Usage
 
-### Quick start example
+### Basic connection
 
 ```ruby
 require 'neo4j/driver'
@@ -90,394 +55,131 @@ Neo4j::Driver::GraphDatabase.driver(
   'bolt://localhost:7687',
   Neo4j::Driver::AuthTokens.basic('neo4j', 'password')
 ) do |driver|
-  driver.session(database: 'neo4j') do |session|
-    query_result = session.run('RETURN 2+2 AS value')
-    puts "2+2 equals #{query_result.single['value']}"
-
-    # consume gives the execution summary
-    create_result = session.run('CREATE (n)').consume
-    puts "Nodes created: #{create_result.counters.nodes_created}"
+  driver.session do |session|
+    result = session.run('RETURN 1 AS num')
+    puts result.single[:num] # => 1
   end
 end
 ```
 
-## Server Compatibility
-
-The compatibility with Neo4j Server versions is documented in
-the [Neo4j Knowledge Base](https://neo4j.com/developer/kb/neo4j-supported-versions/).
-
-## Usage
-
-The API is to highest possible degree consistent with the official Java driver. Please refer to
-the [Neo4j Java Driver Manual](https://neo4j.com/docs/java-manual/current/), [examples in Ruby](https://github.com/neo4jrb/neo4j-ruby-driver/blob/master/docs/dev_manual_examples.rb),
-and code snippets below to understand how to use it.
-[Neo4j Java Driver API Docs](https://neo4j.com/docs/api/java-driver/current/) can be helpful as well.
-
-### Connecting to a database
-
-#### URI schemes
-
-The driver supports the following URI schemes:
-
-| URI Scheme     | Description                                                                     |
-|----------------|---------------------------------------------------------------------------------|
-| `neo4j://`     | Connect using routing to a cluster/causal cluster.                              |
-| `neo4j+s://`   | Same as `neo4j://` but with full TLS encryption.                                |
-| `neo4j+ssc://` | Same as `neo4j://` but with full TLS encryption, without hostname verification. |
-| `bolt://`      | Connect directly to a server using the Bolt protocol.                           |
-| `bolt+s://`    | Same as `bolt://` but with full TLS encryption.                                 |
-| `bolt+ssc://`  | Same as `bolt://` but with full TLS encryption, without hostname verification.  |
-
-Example:
-
-```ruby
-# Connect to a single instance
-driver = Neo4j::Driver::GraphDatabase.driver(
-  'bolt://localhost:7687',
-  Neo4j::Driver::AuthTokens.basic('neo4j', 'password')
-)
-
-# Connect to a cluster
-driver = Neo4j::Driver::GraphDatabase.driver(
-  'neo4j://graph.example.com:7687',
-  Neo4j::Driver::AuthTokens.basic('neo4j', 'password')
-)
-```
-
-#### Authentication
+Use a `bolt://` URL for a single instance, `neo4j://` for a routed (cluster)
+connection, and the `+s`/`+ssc` variants for TLS.
 
-The driver provides multiple authentication methods:
+### Parameterized queries
 
 ```ruby
-# Basic authentication
-auth = Neo4j::Driver::AuthTokens.basic('neo4j', 'password')
+driver.session do |session|
+  node = session.run(
+    'CREATE (n:Person {name: $name, age: $age}) RETURN n',
+    name: 'Alice', age: 30
+  ).single[:n]
 
-# With realm specification
-auth = Neo4j::Driver::AuthTokens.basic('neo4j', 'password', 'realm')
-
-# Kerberos authentication
-auth = Neo4j::Driver::AuthTokens.kerberos('ticket')
-
-# Bearer authentication
-auth = Neo4j::Driver::AuthTokens.bearer('token')
-
-# Custom authentication
-auth = Neo4j::Driver::AuthTokens.custom('principal', 'credentials', 'realm', 'scheme')
-
-# No authentication
-auth = Neo4j::Driver::AuthTokens.none
-```
-
-#### Configuration
-
-You can configure the driver with additional options:
-
-```ruby
-config = {
-  connection_timeout: 15.seconds,
-  connection_acquisition_timeout: 1.minute,
-  max_transaction_retry_time: 30.seconds,
-  encryption: true,
-  trust_strategy: :trust_all_certificates
-}
-
-driver = Neo4j::Driver::GraphDatabase.driver(
-  'neo4j://localhost:7687',
-  Neo4j::Driver::AuthTokens.basic('neo4j', 'password'),
-  **config
-)
-```
-
-#### Connectivity check
-
-```ruby
-if driver.verify_connectivity
-  puts "Driver is connected to the database"
-else
-  puts "Driver cannot connect to the database"
-end
-```
-
-### Sessions & transactions
-
-The driver provides sessions to interact with the database and to execute queries.
-
-#### Session
-
-Sessions are lightweight and disposable database connections. Always close your sessions when done:
-
-```ruby
-session = driver.session(database: 'neo4j')
-begin
-  session.run('MATCH (n) RETURN n LIMIT 10')
-ensure
-  session.close
+  puts node[:name] # => "Alice"
 end
 ```
 
-Or use a block that automatically closes the session:
-
-```ruby
-driver.session(database: 'neo4j') do |session|
-  session.run('MATCH (n) RETURN n LIMIT 10')
-end
-```
-
-Session options:
-
-```ruby
-# Default database
-session = driver.session
-
-# Specific database
-session = driver.session(database: 'neo4j')
-
-# With access mode
-session = driver.session(database: 'neo4j', default_access_mode: Neo4j::Driver::AccessMode::READ)
-
-# With bookmarks for causal consistency
-session = driver.session(
-  database: 'neo4j',
-  bookmarks: [Neo4j::Driver::Bookmark.from('bookmark-1')]
-)
-```
-
-#### Auto-commit transactions
-
-For simple, one-off queries, use auto-commit transactions:
+`session.run(query, parameters = {}, config = {})` keeps parameters and config
+as separate explicit hashes.
 
-```ruby
-session.run('CREATE (n:Person {name: $name})', name: 'Alice')
-```
+### Explicit transactions
 
-#### Explicit transactions
-
-For multiple queries that need to be executed as a unit, use explicit transactions:
+Explicit transactions are **default-rollback** — you must call `tx.commit`.
 
 ```ruby
-tx = session.begin_transaction
-begin
-  tx.run('CREATE (n:Person {name: $name})', name: 'Alice')
-  tx.run('CREATE (n:Person {name: $name})', name: 'Bob')
-  tx.commit
-rescue
-  tx.rollback
-  raise
+driver.session do |session|
+  session.begin_transaction do |tx|
+    tx.run('CREATE (:Person {name: "Bob"})')
+    tx.run('CREATE (:Person {name: "Charlie"})')
+    tx.commit
+  end
 end
 ```
 
-#### Read transactions
+### Managed transaction functions
 
-Specifically for read operations:
+Auto-commit on clean exit; transient failures are retried with exponential
+backoff.
 
 ```ruby
-result = session.read_transaction do |tx|
-  tx.run('MATCH (n:Person) RETURN n.name').map { |record| record['n.name'] }
-end
-puts result
-```
-
-#### Write transactions
-
-Specifically for write operations:
+driver.session do |session|
+  session.execute_write do |tx|
+    tx.run('CREATE (n:Person {name: "Diana"}) RETURN n').single
+  end
 
-```ruby
-session.write_transaction do |tx|
-  tx.run('CREATE (n:Person {name: $name})', name: 'Charlie')
+  people = session.execute_read do |tx|
+    tx.run('MATCH (p:Person) RETURN p.name AS name').collect { |r| r[:name] }
+  end
 end
 ```
 
 ### Working with results
 
 ```ruby
-result = session.run('MATCH (n:Person) RETURN n.name AS name, n.age AS age')
+result = session.run('MATCH (p:Person) RETURN p.name AS name, p.age AS age')
 
-# Process results
-result.each do |record|
-  puts "#{record['name']} is #{record['age']} years old"
-end
+result.each { |record| puts "#{record[:name]} is #{record[:age]}" }
 
-# Check if there are more results
-puts "Has more results: #{result.has_next?}"
+record = result.single  # exactly one row
+name   = record[:name]  # by key (string or symbol)
+age    = record[1]      # or by index
 
-# Get a single record
-single = result.single
-puts single['name'] if single
-
-# Get keys available in the result
-puts "Keys: #{result.keys}"
-
-# Access by field index
-result.each do |record|
-  puts "First field: #{record[0]}"
-end
-
-# Convert to array
 records = result.to_a
 ```
 
-#### Accessing Node and Relationship data
+## Architecture
 
-Working with graph entities:
+The development tree is split so shared code lives in one place and each
+implementation adds only its own wire layer:
 
-```ruby
-result = session.run('MATCH (p:Person)-[r:KNOWS]->(friend) RETURN p, r, friend')
-
-result.each do |record|
-  # Working with nodes
-  person = record['p']
-  puts "Node ID: #{person.id}"
-  puts "Labels: #{person.labels.join(', ')}"
-  puts "Properties: #{person.properties}"
-  puts "Name property: #{person.properties['name']}"
-
-  # Working with relationships
-  relationship = record['r']
-  puts "Relationship ID: #{relationship.id}"
-  puts "Type: #{relationship.type}"
-  puts "Properties: #{relationship.properties}"
-
-  # Start and end nodes of the relationship
-  puts "Relationship: #{relationship.start_node_id} -> #{relationship.end_node_id}"
-end
 ```
-
-#### Working with Paths
-
-Processing paths returned from Cypher:
-
-```ruby
-result = session.run('MATCH p = (:Person)-[:KNOWS*]->(:Person) RETURN p')
-
-result.each do |record|
-  path = record['p']
-
-  # Get all nodes in the path
-  nodes = path.nodes
-  puts "Nodes in path: #{nodes.map { |n| n.properties['name'] }.join(' -> ')}"
-
-  # Get all relationships in the path
-  relationships = path.relationships
-  puts "Relationship types: #{relationships.map(&:type).join(', ')}"
-
-  # Iterate through the path segments
-  path.each do |segment|
-    puts "#{segment.start_node.properties['name']} -[#{segment.relationship.type}]-> #{segment.end_node.properties['name']}"
-  end
-end
-```
-
-#### Working with temporal types
-
-Creating a node with properties of temporal types:
-
-```ruby
-session.run(
-  'CREATE (e:Event {datetime: $datetime, duration: $duration})',
-  datetime: DateTime.new(2025, 5, 5, 5, 55, 55), duration: 1.hour
-)
-```
-
-Querying temporal values:
-
-```ruby
-session.run('MATCH (e:Event) LIMIT 1 RETURN e.datetime, e.duration').single.to_h
-# => {"e.datetime": 2025-05-05 05:55:55 +0000, "e.duration": 3600 seconds}
-```
-
-### Type mapping
-
-The Neo4j Ruby Driver maps Cypher types to Ruby types:
-
-| Cypher Type    | Ruby Type                                     |
-|----------------|-----------------------------------------------|
-| null           | nil                                           |
-| List           | Enumerable                                    |
-| Map            | Hash (symbolized keys)                        |
-| Boolean        | TrueClass/FalseClass                          |
-| Integer        | Integer/String[^1]                            |
-| Float          | Float                                         |
-| String         | String/Symbol[^2] (encoding: UTF-8)           |
-| ByteArray      | String (encoding: BINARY)                     |
-| Date           | Date                                          |
-| Zoned Time     | Neo4j::Driver::Types::OffsetTime              |
-| Local Time     | Neo4j::Driver::Types::LocalTime               |
-| Zoned DateTime | Time/ActiveSupport::TimeWithZone/DateTime[^3] |
-| Local DateTime | Neo4j::Driver::Types::LocalDateTime           |
-| Duration       | ActiveSupport::Duration                       |
-| Point          | Neo4j::Driver::Types::Point                   |
-| Node           | Neo4j::Driver::Types::Node                    |
-| Relationship   | Neo4j::Driver::Types::Relationship            |
-| Path           | Neo4j::Driver::Types::Path                    |
-
-[^1]: An Integer smaller than -2 ** 63 or larger than 2 ** 63 will always be implicitly converted to String
-[^2]: A Symbol passed as a parameter will always be implicitly converted to String. All Strings other than BINARY
-encoded are converted to UTF-8 when stored in Neo4j
-[^3]: A Ruby DateTime passed as a parameter will always be implicitly converted to Time
-
-### Advanced
-
-#### Connection pooling
-
-The driver handles connection pooling automatically. Configure the connection pool:
-
-```ruby
-config = {
-  max_connection_pool_size: 100,
-  max_connection_lifetime: 1.hour
-}
-
-driver = Neo4j::Driver::GraphDatabase.driver('neo4j://localhost:7687', auth, **config)
+lib/
+├── shared/   # public API + shared types, loaded by both implementations
+├── mri/      # pure-Ruby Bolt protocol, PackStream, connection pool
+└── jruby/    # thin wrapper over the official Java driver jars
 ```
 
-#### Logging
+The published gem is flattened to a single `lib/` for the platform via a staged
+build (see `JRUBY.md`). See `CLAUDE.md` for the layout and conventions,
+`DEVELOPMENT.md` for the dev loop, and `DECISIONS.md` for architectural history.
 
-Configure logging for the driver:
+### Dependencies
 
-```ruby
-config = {
-  logger: Logger.new(STDOUT).tap { |log| log.level = Logger::DEBUG }
-}
-
-driver = Neo4j::Driver::GraphDatabase.driver('neo4j://localhost:7687', auth, **config)
-```
-
-## For Driver Engineers
+- **MRI**: `tzinfo`, `zeitwerk`, `connection_pool` — no Java, no server-side
+  components.
+- **JRuby**: the official `neo4j-java-driver` jars, resolved by
+  `jar-dependencies`; runs on a JVM (Java 17+).
 
-This gem includes 2 different implementations: a Java driver wrapper and a pure Ruby driver, so you will have to run
-this command every time you switch the Ruby engine:
+## Testing
 
 ```bash
-bin/setup
-```
-
-### Testing
-
-There are two sets of tests for the driver. To run the specs placed in this repository, use a normal rspec command:
+export TEST_NEO4J_URL=bolt://localhost:7687
+export TEST_NEO4J_USER=neo4j
+export TEST_NEO4J_PASS=password
 
-```bash
-rspec spec
+bundle exec rspec
 ```
 
-To run the [Testkit](https://github.com/neo4j-drivers/testkit) that is used to test all Neo4j driver implementations,
-use the following:
+- `spec/shared/integration/` — end-to-end against a running Neo4j instance
+- `spec/shared/neo4j/driver/` — public-API unit tests
+- `spec/mri/`, `spec/jruby/` — implementation-specific tests
 
-```bash
-git clone git@github.com:neo4j-drivers/testkit.git
-cd testkit
-export TEST_DRIVER_NAME=ruby
-export TEST_DRIVER_REPO=`realpath ../neo4j-ruby-driver`
-export TEST_NEO4J_PASS=password
-python3 main.py --tests UNIT_TESTS --configs 4.3-enterprise
-```
-
-Please refer to the [Testkit](https://github.com/neo4j-drivers/testkit) documentation to learn more about its features.
+Conformance is additionally exercised through the Neo4j
+[testkit](https://github.com/neo4j-drivers/testkit) suite via the Ruby backend
+under `testkit-backend/`.
 
 ## Contributing
 
-Suggestions, improvements, bug reports and pull requests are welcome on GitHub
-at https://github.com/neo4jrb/neo4j-ruby-driver.
+Contributions are welcome. Keep the public API flavour-agnostic (no
+implementation type may leak across it), follow the conventions in `CLAUDE.md`,
+and add coverage on both implementations. See `CHANGELOG.md` for recent changes.
+
+## References
+
+- [Bolt Protocol Specification](https://neo4j.com/docs/bolt/current/)
+- [PackStream Specification](https://neo4j.com/docs/bolt/current/packstream/)
+- [neo4j-java-driver](https://github.com/neo4j/neo4j-java-driver) (reference implementation)
+- [Neo4j testkit](https://github.com/neo4j-drivers/testkit)
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Released under the [MIT License](LICENSE.txt).

data/lib/neo4j/driver/auth_token_manager.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # JRuby flavour of the auth-token manager. Same Proc-based public
+    # surface as the MRI sibling, but the class `include`s
+    # `org.neo4j.driver.AuthTokenManager` in its body — JRuby only
+    # generates the Java-side proxy at class-definition time, so a
+    # retroactive include (via prepend or class_eval) doesn't produce
+    # a usable interface impl. Subclasses inherit the interface, so a
+    # user-written `class MyManager < Neo4j::Driver::AuthTokenManager`
+    # slots into the Java driver the same as on MRI.
+    #
+    # The Java interface asks for `CompletionStage<AuthToken>` from
+    # `getToken`; our sync Proc gets wrapped in a pre-completed future.
+    # The `handleSecurityException` callback receives a Java exception
+    # which we map to its Ruby counterpart before handing to the user.
+    class AuthTokenManager < Internal::InternalAuthTokenManager
+      include Java::OrgNeo4jDriver::AuthTokenManager
+      include Ext::ExceptionMapper
+
+      def get_token = java.util.concurrent.CompletableFuture.completed_future(super)
+
+      def handle_security_exception(token, exception)
+        super(token, mapped_exception_with_cause(exception))
+      end
+    end
+  end
+end

data/lib/neo4j/driver/client_certificate_manager.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # JRuby flavour of a client-certificate manager: supply a block that
+    # returns the current client certificate — or `nil` when nothing has
+    # changed since the last call — and pass an instance to
+    # `GraphDatabase.driver` via `client_certificate_manager:`. The driver
+    # calls back whenever it needs a (possibly rotated) certificate for the
+    # mutual-TLS handshake.
+    #
+    # The class `include`s org.neo4j.driver.ClientCertificateManager in its
+    # body because JRuby only builds the Java interface proxy at
+    # class-definition time; a retroactive include wouldn't produce a usable
+    # impl, and subclasses inherit the interface. The Java SPI asks for a
+    # CompletionStage<ClientCertificate>, so the synchronous block result is
+    # wrapped in a pre-completed future (a `nil` result is a valid "no
+    # change" answer).
+    class ClientCertificateManager
+      include Java::OrgNeo4jDriver::ClientCertificateManager
+
+      def initialize(&get_client_certificate)
+        @get_client_certificate = get_client_certificate
+      end
+
+      def get_client_certificate
+        java.util.concurrent.CompletableFuture.completed_future(@get_client_certificate.call)
+      end
+    end
+  end
+end