neo4j-ruby-driver 1.7.4 → 4.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10b401fcd6765f428d7b377cb9ed6e6dc021d7e6c1fa41bc95839a991d3a8d11
-  data.tar.gz: 29bd664e4481f3e42bd5cd369603887d1c349c3caa472747179b4bffe7c96e0d
+  metadata.gz: aad2e30fa3fa23dc95e7db9f27847b1c5382c23600c019d93a7625fc5a66d085
+  data.tar.gz: 534c14f354f92df7a85b153e1451951ded71863fbbb10c61a50a280a8bf3bea7
 SHA512:
-  metadata.gz: 006d20096a8a7643f9ae842a0b3340bb2517d46cc1781dd3e7f95cd7aa262eb4c4a524687ec87324910e3e8e25c8fcaa077773b226a8173d8383e42ec86380b9
-  data.tar.gz: ad244e09f318ca75a63d7b8fb1d345cb04e0567ea0e6e6ffdc0b86b73817b5adf2e1c673201e1afb4ac5a0adcfe661353d1e854897baf03007030a1704656d84
+  metadata.gz: 909be9c6542e378161b3e9b9c62ad9e45ef08c54f7410b4ea5a2ba3f15267fd445995757f74210aadcaa10f94475f839cddeb2294c23d44a9925e044e23cc162
+  data.tar.gz: 4d22446e5a24c6f7f99072202bfc4dbab1e222b535c64b1c716a31f4993f9fe0da07c8d5dfbd3f68d793fc1b11f6782f4a6062e3171f41b7b26a8c7260b0966a

data/README.md

@@ -3,37 +3,11 @@
 home  :: https://github.com/neo4jrb/neo4j-ruby-driver
 
 This repository contains 2 implementation of a neo4j driver for ruby:
-- `neo4j-java-driver` based on official java implementation. It provides a thin wrapper over java driver (only in jruby).
-- `neo4j-ruby-driver` based on [seabolt](https://github.com/neo4j-drivers/seabolt) and [ffi](https://github.com/ffi/ffi). Available on all rubies (including jruby) and all platforms supported by seabolt.
+- based on official java implementation. It provides a thin wrapper over the java driver (only on jruby).
+- pure ruby implmementation. Available on all ruby versions >= 3.1.
 
 ## Installation
 
-### neo4j-java-driver
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'neo4j-java-driver'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install neo4j-java-driver
-    
-### neo4j-ruby-driver
-
-As a prerequisite seabolt must be installed.
- 
-On macOS
-
-    $ brew install michael-simons/homebrew-seabolt/seabolt 
-    
-On other systems please follow the instructions to install [seabolt](https://github.com/neo4j-drivers/seabolt) either from package or source. Make sure the libseabolt17 ends up in a system lib path e.g. /usr/local/lib
- 
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -48,22 +22,20 @@ Or install it yourself as:
 
     $ gem install neo4j-ruby-driver
 
-## Usage
+## Server Compatibility
 
-Both drivers implement identical API and can be used interchangeably. The API is to highest possible degree consistent with the official java driver. 
-At this moment [The Neo4j Drivers Manual v1.7](https://neo4j.com/docs/driver-manual/1.7/) along with the ruby version of the [code fragments](https://github.com/neo4jrb/neo4j-ruby-driver/blob/master/docs/dev_manual_examples.rb) and the ruby specs provide the only documentation. 
+The compatibility with Neo4j Server versions is documented in the [Neo4j Knowledge Base](https://neo4j.com/developer/kb/neo4j-supported-versions/).
 
-[Neo4j Java Driver 1.7 API](https://neo4j.com/docs/api/java-driver/current/) can be helpful as well..
+## Usage
 
-## Development
+The API is to highest possible degree consistent with the official java driver. 
+At this moment [The Neo4j Drivers Manual v4.4](https://neo4j.com/docs/java-manual/current/) along with the ruby version of the [code fragments](https://github.com/neo4jrb/neo4j-ruby-driver/blob/master/docs/dev_manual_examples.rb) and the ruby specs provide the only documentation. 
 
-This gem includes 2 different implementations: java driver based and another one using seabolt via ffi
+[Neo4j Java Driver 4.3 API](https://neo4j.com/docs/api/java-driver/current/) can be helpful as well..
 
-For java driver based:
+## Development
 
-    $ driver=java bin/setup
-    
-FFI based same as above but with driver variable set:
+This gem includes 2 different implementations: java driver wrapper and pure ruby driver
 
     $ bin/setup 
      
@@ -73,10 +45,33 @@ To run the tests the following tools need to be installed:
 
     $ brew install python
     $ pip3 install --user git+https://github.com/klobuczek/boltkit@1.3#egg=boltkit
-    $ neoctrl-install -e 4.0.2 servers
-    $ neoctrl-configure servers/neo4j-enterprise-4.0.2 dbms.directories.import= dbms.default_listen_address=::
-    $ neoctrl-set-initial-password password servers/neo4j-enterprise-4.0.2
-    $ neoctrl-start servers/neo4j-enterprise-4.0.2
+    $ neoctrl-install -e 4.4.5 servers
+    $ neoctrl-configure servers/neo4j-enterprise-4.4.5 dbms.directories.import= dbms.default_listen_address=::
+    $ neoctrl-set-initial-password pass servers/neo4j-enterprise-4.4.5
+    $ neoctrl-start servers/neo4j-enterprise-4.4.5
+
+To run the tests:
+```console
+$ bin/setup
+$ rspec spec
+```
+
+Known errors:
+
+1. In case of heap space memory error (`org.neo4j.driver.exceptions.DatabaseException: Java heap space`), you should limit the dbms memory, for example:
+
+```console
+$ neoctrl-configure servers/neo4j-enterprise-4.4.5 dbms.memory.pagecache.size=600m dbms.memory.heap.max_size=600m dbms.memory.heap.initial_size=600m dbms.directories.import= dbms.connectors.default_listen_address=::
+```
+
+2. When using command `pip3 install --user git+https://github.com/klobuczek/boltkit@1.3#egg=boltkit`, if you have m1 mac chip, you may get error when pip3 tries to install `cryptography`. Steps to take in that case (reference https://stackoverflow.com/a/70074869/2559490)
+
+```console
+$ pip uninstall cffi
+$ python -m pip install --upgrade pip
+$ pip install cffi
+$ pip install cryptography
+```
 
 ## Contributing
 

data/lib/loader.rb

@@ -7,11 +7,13 @@ class Loader
     loader = Zeitwerk::Loader.new
     loader.tag = 'neo4j-ruby-driver'
     loader.push_dir(File.expand_path(__dir__))
-    loader.push_dir(File.dirname(File.dirname(caller_locations(1..1).first.path)))
-    loader.ignore(File.expand_path('neo4j-java-driver_jars.rb', __dir__))
+    driver_specific_dir = File.dirname(File.dirname(caller_locations(1..1).first.path))
+    loader.push_dir(driver_specific_dir)
+    yield loader if block_given?
+    loader.ignore(File.expand_path('neo4j-*-driver_jars.rb', __dir__))
     loader.ignore(File.expand_path('neo4j_ruby_driver.rb', __dir__))
     loader.ignore(File.expand_path('org', __dir__))
-    loader.inflector = Zeitwerk::GemInflector.new(File.expand_path('neo4j/driver', __dir__))
+    loader.inflector = Zeitwerk::GemInflector.new(File.expand_path('neo4j/driver', driver_specific_dir))
     loader.setup
     loader.eager_load
   end

data/lib/neo4j/driver/auto_closable.rb

@@ -12,8 +12,8 @@ module Neo4j
       def with_block_definer(methods)
         Module.new do
           methods.each do |method|
-            define_method(method) do |*args, &block|
-              closable = super(*args)
+            define_method(method) do |*args, **kwargs, &block|
+              closable = super(*args, **kwargs)
               if block
                 begin
                   block.arity.zero? ? closable.instance_eval(&block) : block.call(closable)

data/lib/neo4j/driver/exceptions/authentication_exception.rb

@@ -3,7 +3,12 @@
 module Neo4j
   module Driver
     module Exceptions
-      class AuthenticationException < Neo4jException
+      # Failed to authenticate the driver to the server due to bad credentials provided.
+      # When this error happens, the error could be recovered by closing the current driver and restart a new driver with
+      # the correct credentials.
+
+      # @since 1.1
+      class AuthenticationException < SecurityException
       end
     end
   end

data/lib/neo4j/driver/exceptions/authorization_expired_exception.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Exceptions
+      # The authorization info maintained on the server has expired. The client should reconnect.
+      # <p>
+      # Error code: Neo.ClientError.Security.AuthorizationExpired
+      class AuthorizationExpiredException < SecurityException
+        DESCRIPTION = 'Authorization information kept on the server has expired, this connection is no longer valid.'
+      end
+    end
+  end
+end

data/lib/neo4j/driver/{types/bytes.rb → exceptions/certificate_exception.rb}

@@ -2,8 +2,8 @@
 
 module Neo4j
   module Driver
-    module Types
-      class Bytes < String
+    module Exceptions
+      class CertificateException
       end
     end
   end

data/lib/neo4j/driver/exceptions/client_exception.rb

@@ -3,6 +3,9 @@
 module Neo4j
   module Driver
     module Exceptions
+      # A <em>ClientException</em> indicates that the client has carried out an operation incorrectly.
+      # The error code provided can be used to determine further detail for the problem.
+      # @since 1.0
       class ClientException < Neo4jException
         class << self
           def unable_to_convert(object)

data/lib/neo4j/driver/exceptions/connection_read_timeout_exception.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Exceptions
+      # Indicates that read timed out due to it taking longer than the server-supplied timeout value via the {@code connection.recv_timeout_seconds} configuration
+      # hint. The server might provide this value to clients to let them know when a given connection may be considered broken if client does not get any
+      # communication from the server within the specified timeout period. This results in the server being removed from the routing table.
+      class ConnectionReadTimeoutException < ServiceUnavailableException
+        INSTANCE = new('Connection read timed out due to it taking longer than the server-supplied timeout value via configuration hint.')
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/database_exception.rb

@@ -3,6 +3,9 @@
 module Neo4j
   module Driver
     module Exceptions
+      # A <em>DatabaseException</em> indicates that there is a problem within the underlying database.
+      # The error code provided can be used to determine further detail for the problem.
+      # @since 1.0
       class DatabaseException < Neo4jException
       end
     end

data/lib/neo4j/driver/exceptions/discovery_exception.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Exceptions
+      # An error has happened while getting routing table with a remote server.
+      # While this error is not fatal and we might be able to recover if we continue trying on another server.
+      # If we fail to get a valid routing table from all routing servers known to this driver,
+      # then we will end up with a fatal error {@link ServiceUnavailableException}.
+
+      # If you see this error in your logs, it is safe to ignore if your cluster is temporarily changing structure during that time.
+      class DiscoveryException < Neo4jException
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/fatal_discovery_exception.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Exceptions
+      # This error indicate a fatal problem to obtain routing tables such as the routing table for a specified database does not exist.
+      # This exception should not be retried.
+      # @since 4.0
+      class FatalDiscoveryException < ClientException
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/protocol_exception.rb

@@ -3,7 +3,14 @@
 module Neo4j
   module Driver
     module Exceptions
+      # A signal that the contract for client-server communication has broken down.
+      # The user should contact support and cannot resolve this his or herself.
       class ProtocolException < Neo4jException
+        CODE = "Protocol violation: "
+
+        def initialize(message, e = nil)
+          super(nil, "#{CODE}#{message}", e)
+        end
       end
     end
   end

data/lib/neo4j/driver/exceptions/result_consumed_exception.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Exceptions
+      # A user is trying to access resources that are no longer valid due to
+      # the resources have already been consumed or
+      # the {@link QueryRunner} where the resources are created has already been closed.
+      class ResultConsumedException < ClientException
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/security_exception.rb

@@ -3,7 +3,11 @@
 module Neo4j
   module Driver
     module Exceptions
-      class SecurityException < Neo4jException
+      # Failed to communicate with the server due to security errors.
+      # When this type of error happens, the security cause of the error should be fixed to ensure the safety of your data.
+      # Restart of server/driver/cluster might be required to recover from this error.
+      # @since 1.1
+      class SecurityException < ClientException
       end
     end
   end

data/lib/neo4j/driver/exceptions/service_unavailable_exception.rb

@@ -3,6 +3,8 @@
 module Neo4j
   module Driver
     module Exceptions
+      # An <em>ServiceUnavailableException</em> indicates that the driver cannot communicate with the cluster.
+      # @since 1.1
       class ServiceUnavailableException < Neo4jException
       end
     end

data/lib/neo4j/driver/exceptions/session_expired_exception.rb

@@ -3,6 +3,10 @@
 module Neo4j
   module Driver
     module Exceptions
+      # A <em>SessionExpiredException</em> indicates that the session can no longer satisfy the criteria under which it
+      # was acquired, e.g. a server no longer accepts write requests. A new session needs to be acquired from the driver
+      # and all actions taken on the expired session must be replayed.
+      # @since 1.1
       class SessionExpiredException < Neo4jException
       end
     end

data/lib/neo4j/driver/exceptions/token_expired_exception.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Exceptions
+      # The provided token has expired.
+      # <p>
+      # The current driver instance is considered invalid. It should not be used anymore. The client must create a new driver instance with a valid token.
+      # <p>
+      # Error code: Neo.ClientError.Security.TokenExpired
+      class TokenExpiredException < SecurityException
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/transaction_nesting_exception.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Exceptions
+      # This exception indicates a user is nesting new transaction with an on-going transaction (unmanaged and/or auto-commit).
+      class TransactionNestingException < ClientException
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/transient_exception.rb

@@ -3,6 +3,9 @@
 module Neo4j
   module Driver
     module Exceptions
+      # A <em>TransientException</em> signals a temporary fault that may be worked around by retrying.
+      # The error code provided can be used to determine further detail for the problem.
+      # @since 1.0
       class TransientException < Neo4jException
       end
     end

data/lib/neo4j/driver/exceptions/untrusted_server_exception.rb

@@ -3,6 +3,7 @@
 module Neo4j
   module Driver
     module Exceptions
+      # Thrown if the remote server cannot be verified as Neo4j.
       class UntrustedServerException < RuntimeError
       end
     end

data/lib/neo4j/driver/exceptions/value/lossy_coercion.rb

@@ -0,0 +1,15 @@
+module Neo4j
+  module Driver
+    module Exceptions
+      module Value
+        # A <em>LossyCoercion</em> exception indicates that the conversion cannot be achieved without losing precision.
+        # @since 1.0
+        class LossyCoercion < ValueException
+          def initialize(source_type_name, destination_type_name)
+            super("Cannot coerce #{source_type_name} to #{destination_type_name} without losing precision")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/value/not_multi_valued.rb

@@ -0,0 +1,13 @@
+module Neo4j
+  module Driver
+    module Exceptions
+      module Value
+        # A <em>NotMultiValued</em> exception indicates that the value does not consist of multiple values, a.k.a. not a map
+        # or array.
+        # @since 1.0
+        class NotMultiValued < ValueException
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/value/uncoercible.rb

@@ -0,0 +1,15 @@
+module Neo4j
+  module Driver
+    module Exceptions
+      module Value
+        # A <em>Uncoercible</em> exception indicates that the conversion cannot be achieved.
+        # @since 1.0
+        class Uncoercible < ValueException
+          def initialize(source_type_name, destination_type_name)
+            super("Cannot coerce #{source_type_name} to #{destination_type_name}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/value/unsizable.rb

@@ -0,0 +1,12 @@
+module Neo4j
+  module Driver
+    module Exceptions
+      module Value
+        # An <em>Unsizable</em> exception indicates that the value does not have a size.
+        # @since 1.0
+        class Unsizable < ValueException
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/exceptions/value/value_exception.rb

@@ -0,0 +1,12 @@
+module Neo4j
+  module Driver
+    module Exceptions
+      module Value
+        # A <em>ValueException</em> indicates that the client has carried out an operation on values incorrectly.
+        # @since 1.0
+        class ValueException < ClientException
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/internal/bolt_server_address.rb

@@ -0,0 +1,97 @@
+module Neo4j::Driver
+  module Internal
+    # Holds a host and port pair that denotes a Bolt server address.
+    class BoltServerAddress
+      attr_reader :host, :connection_host, :port
+      delegate :hash, to: :attributes
+
+      DEFAULT_PORT = 7687
+
+      class << self
+        def host_from(uri)
+          uri&.host || (raise invalid_address_format(uri))
+        end
+
+        def port_from(uri)
+          uri&.port || DEFAULT_PORT
+        end
+
+        def uri_from(address)
+          scheme_split = address.split('://')
+
+          if scheme_split.length == 1
+            # URI can't parse addresses without scheme, prepend fake "bolt://" to reuse the parsing facility
+            scheme = 'bolt://'
+            host_port = host_port_from(scheme_split.first)
+          elsif scheme_split.length == 2
+            scheme = "#{scheme_split.first}://"
+            host_port = host_port_from(scheme_split.second)
+          else
+            raise invalid_address_format(address)
+          end
+
+          URI(scheme + host_port)
+        end
+
+        def host_port_from(address)
+          # expected to be an IPv6 address like [::1] or [::1]:7687
+          return address if address.start_with?('[')
+
+          contains_single_colon = address.index(':') == address.rindex(':')
+
+          # expected to be an IPv4 address with or without port like 127.0.0.1 or 127.0.0.1:7687
+          return address if contains_single_colon
+
+          # address contains multiple colons and does not start with '['
+          # expected to be an IPv6 address without brackets
+          "[#{address}]"
+        end
+
+        def invalid_address_format(address)
+          ArgumentError.new("Invalid address format #{address}")
+        end
+
+        def require_valid_port(port)
+          return port if port >= 0 && port <= 65_535
+
+          raise ArgumentError, "Illegal port: #{port}"
+        end
+      end
+
+      def initialize(uri: nil, host: self.class.host_from(uri), port: self.class.port_from(uri), connection_host: host)
+        @host = Validator.require_non_nil!(host)
+        @connection_host = Validator.require_non_nil!(connection_host)
+        @port = self.class.require_valid_port(port)
+      end
+
+      LOCAL_DEFAULT = new(host: 'localhost', port: DEFAULT_PORT)
+
+      def self.from(address)
+        address.is_a?(BoltServerAddress) ? address : new(host: address.host, port: address.port)
+      end
+
+      def ==(other)
+        attributes == other&.attributes
+      end
+
+      alias eql? ==
+
+      def to_s
+        "#{host}#{"(#{connection_host})" unless host == connection_host}:#{port}"
+      end
+
+      # Create a stream of unicast addresses.
+      # <p>
+      # While this implementation just returns a stream of itself, the subclasses may provide multiple addresses.
+
+      # @return stream of unicast addresses.
+      def unicast_stream
+        Set[self]
+      end
+
+      def attributes
+        [@host, @connection_host, @port]
+      end
+    end
+  end
+end

data/lib/neo4j/driver/internal/duration_normalizer.rb

@@ -18,7 +18,7 @@ module Neo4j
           end
 
           def milliseconds(duration)
-            duration.in_milliseconds.round
+            duration&.in_milliseconds&.round
           end
 
           private

data/lib/neo4j/driver/internal/validator.rb

@@ -14,13 +14,14 @@ module Neo4j
           raise(ArgumentError, yield) unless obj.nil? || obj.is_a?(Hash)
         end
 
-        def self.require_non_nil!(obj, message)
-          raise ArgumentError, message if obj.nil?
+        def self.require_non_nil!(obj, message = nil)
+          raise ArgumentError, [message, "can't be nil"].compact.join(' ') if obj.nil?
+          obj
         end
 
         def self.require_non_nil_credentials!(username, password)
-          require_non_nil! username, "Username can't be nil"
-          require_non_nil! password, "Password can't be nil"
+          require_non_nil! username, "Username"
+          require_non_nil! password, "Password"
         end
       end
     end

data/{ffi/neo4j/driver/summary/statement_type.rb → lib/neo4j/driver/summary/query_type.rb}

@@ -1,9 +1,7 @@
-# frozen_string_literal: true
-
 module Neo4j
   module Driver
     module Summary
-      module StatementType
+      module QueryType
         READ_ONLY = 'r'
         READ_WRITE = 'rw'
         WRITE_ONLY = 'w'

data/lib/neo4j/driver/synchronizable.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Synchronizable
+      def sync(*methods)
+        prepend with_sync_wrapper(methods)
+      end
+
+      private
+
+      def with_sync_wrapper(methods)
+        Module.new do
+          methods.each do |method|
+            define_method(method) do |*args, **kwargs, &block|
+              Sync { super(*args, **kwargs, &block) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/types/time.rb

@@ -30,10 +30,12 @@ module Neo4j
           end
         end
 
-        def eql?(other)
-          other.is_a?(self.class) && self.class.significant_fields.all? { |elem| send(elem).eql?(other.send(elem)) }
+        def ==(other)
+          other.is_a?(self.class) && self.class.significant_fields.all? { |elem| send(elem) == other.send(elem) }
         end
 
+        alias eql? ==
+
         def +(numeric)
           self.class.new(@time + numeric)
         end