neo4j-ruby-driver 6.2.1 → 6.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 701bd350949810304707654ca39de518eda02faeda8b6d1c9575d14a3f5ac703
-  data.tar.gz: 7920f8aa3f11ded084dda941bf7de0882e7858c7b99d69168b816e2ab6b65e44
+  metadata.gz: 57826a02d1e095bb0ceda73c602953499aed1cf4f06b09543606f65873b41a94
+  data.tar.gz: 69b75755af9e3a9491d2ae50a6149529f2052131436b35dfa8fab3662224f980
 SHA512:
-  metadata.gz: 9afb8c944e1661dcc0f5d6f4573d6e797bc218f8f823ee5304c1e7d4ae01bd85fe6804e055f1dd58b41732cbd852a2bb8fd4128f5127c8a3644c73c705903af3
-  data.tar.gz: bfd5dd64dd2cd2709409daeb8f3df67b641119c24683f4e6e2022db3fb3de335bc83c8f3ad04c6cefbcdb701121bc06db6198549a39237346f26fc9939fe2fd5
+  metadata.gz: 647cafdddacd1edd462d9fe131ec7b7fcc28489b4ee6da28c3c6a563fe7fb89f19935bc838b693046c6f77ffae1e4d9d270e6bd84a3471d3c39453cf6f953743
+  data.tar.gz: 8c63e3b41d666d2a03944bc2fef8f314e8b8f05aa9b974952990fd8580bfb88430db7f19c5052dd51e00bb1c14296bde4774f27f1100fc5fa4a4587d82b8c631

data/README.md

@@ -1,5 +1,7 @@
 # Neo4j Ruby Driver
 
+[![codecov](https://codecov.io/gh/neo4jrb/neo4j-ruby-driver/branch/main/graph/badge.svg)](https://codecov.io/gh/neo4jrb/neo4j-ruby-driver)
+
 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**:
@@ -126,6 +128,13 @@ age    = record[1]      # or by index
 records = result.to_a
 ```
 
+Node labels and relationship types come back as **symbols** off the entity —
+`node.labels # => [:Person]`, `rel.type # => :KNOWS` — as do record columns and
+map/property keys. Cypher functions that *return* strings (`labels()`, `keys()`,
+`type()`) return **strings**, because their result is an ordinary value on the
+wire, indistinguishable from data you returned yourself. Read the accessor for
+symbols, or convert the function result with `.map(&:to_sym)`.
+
 ## Architecture
 
 The development tree is split so shared code lives in one place and each

data/lib/neo4j/driver/auth_tokens.rb

@@ -2,6 +2,8 @@
 
 module Neo4j
   module Driver
+    # Builds Bolt auth-token hashes (basic, bearer, kerberos, none, custom),
+    # mirroring Java's org.neo4j.driver.AuthTokens factory for the MRI flavour.
     module AuthTokens
       class << self
         # Signatures mirror Java's org.neo4j.driver.AuthTokens. The JRuby

data/lib/neo4j/driver/auto_closeable.rb

@@ -2,6 +2,9 @@
 
 module Neo4j
   module Driver
+    # Class-level helper: wraps the named factory methods so that, when given
+    # a block, the returned resource is yielded and guaranteed closed
+    # afterwards (Java try-with-resources semantics).
     module AutoCloseable
       def auto_closeable(*methods)
         prepend with_block_definer(methods)

data/lib/neo4j/driver/bolt/connection.rb

@@ -710,9 +710,9 @@ module Neo4j
         def advance
           case (chunk = @socket.read_nonblock(READ_CHUNK, exception: false))
           when :wait_readable
-            @socket.wait_readable(current_read_timeout) or fail_broken(read_timeout_error)
+            wait_ready(:wait_readable) or fail_broken(read_timeout_error)
           when :wait_writable # SSL renegotiation mid-read
-            @socket.wait_writable(current_read_timeout) or fail_broken(read_timeout_error)
+            wait_ready(:wait_writable) or fail_broken(read_timeout_error)
           when nil
             raise EOFError, 'end of file reached'
           else
@@ -857,11 +857,27 @@ module Neo4j
           callback&.call(self)
         end
 
+        # Block until the socket is ready to read (or write, during a mid-read
+        # SSL renegotiation), bounded by the current read timeout. A nil timeout
+        # waits indefinitely (steady state with no server hint). When the
+        # acquisition deadline is set and already past, don't wait at all —
+        # report the timeout immediately rather than polling the socket with a
+        # zero or negative interval. Returns falsey on timeout so the caller
+        # raises read_timeout_error.
+        def wait_ready(readiness)
+          timeout = current_read_timeout
+          return false if timeout && !timeout.positive?
+
+          @socket.public_send(readiness, timeout)
+        end
+
         # The timeout the next read may take. During acquisition (handshake,
-        # ROUTE) it's the remaining budget of the total deadline; in steady
-        # state it's the server's recv-timeout hint (nil = block indefinitely).
+        # ROUTE) it's the time left on the total deadline — non-positive once the
+        # deadline has passed, which #wait_ready turns into an immediate timeout.
+        # In steady state it's the server's recv-timeout hint (nil = block
+        # indefinitely).
         def current_read_timeout
-          return [@read_deadline - current_monotonic, 0.001].max if @read_deadline
+          return @read_deadline - current_monotonic if @read_deadline
 
           @recv_timeout
         end
@@ -963,6 +979,7 @@ module Neo4j
         else
           @address = format_address(host, port)
           tcp_socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1)
+          enable_keepalive(tcp_socket)
 
           if timeout
             timeval = [timeout, 0].pack('l_2')
@@ -973,6 +990,27 @@ module Neo4j
           @socket = wrap_with_tls(tcp_socket, bare_host, port)
         end
 
+        # Enable TCP keepalive so a dead peer — a crashed host or a silent network
+        # partition that never delivers FIN/RST — is detected and the blocked read
+        # fails, instead of the socket sitting "ESTABLISHED" until the OS default
+        # idle (~2h on Linux) or, with nothing in flight, forever. Probe after ~60s
+        # idle, every 10s, 3 times (~90s to detection). The per-interval options
+        # are platform-specific (TCP_KEEPIDLE on Linux, TCP_KEEPALIVE on macOS/BSD)
+        # and best-effort — skip any the platform lacks or rejects; SO_KEEPALIVE
+        # alone (OS-default timing) still applies. Does not affect a slow-but-alive
+        # server: its TCP stack keeps ACKing probes, so keepalive never fires on it.
+        def enable_keepalive(socket)
+          socket.setsockopt(Socket::SOL_SOCKET, Socket::SO_KEEPALIVE, 1)
+          idle_opt = if defined?(Socket::TCP_KEEPIDLE) then Socket::TCP_KEEPIDLE
+                     elsif defined?(Socket::TCP_KEEPALIVE) then Socket::TCP_KEEPALIVE
+                     end
+          socket.setsockopt(Socket::IPPROTO_TCP, idle_opt, 60) if idle_opt
+          socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_KEEPINTVL, 10) if defined?(Socket::TCP_KEEPINTVL)
+          socket.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_KEEPCNT, 3) if defined?(Socket::TCP_KEEPCNT)
+        rescue StandardError
+          nil # keepalive stays on with OS-default timing; interval tuning is an optimization
+        end
+
         # When the URI uses a +s/+ssc scheme (or :encryption is set
         # explicitly), wrap the TCP socket in an OpenSSL::SSL::SSLSocket
         # before returning. Errors during the TLS handshake — peer

data/lib/neo4j/driver/bolt/handshake.rb

@@ -158,12 +158,12 @@ module Neo4j
           count = (range_int >> 16) & 0xFF
           return false unless version.major == major
 
-          version.minor <= top_minor && version.minor >= top_minor - count
+          version.minor.between?(top_minor - count, top_minor)
         end
 
         def read_int32
           bytes = read_fully(4)
-          bytes ? bytes.unpack1('L>') : nil
+          bytes&.unpack1('L>')
         end
 
         # Read exactly n bytes, bounded by @deadline. Returns the bytes, or nil
@@ -208,7 +208,7 @@ module Neo4j
             raise IOError, 'Unexpected end of stream while reading varint' if byte.nil?
 
             value |= (byte & 0x7F) << shift
-            return value if byte & 0x80 == 0
+            return value if byte.nobits?(0x80)
 
             shift += 7
           end

data/lib/neo4j/driver/bolt/wire.rb

@@ -220,7 +220,7 @@ module Neo4j
             indices.each_slice(2) do |rel_idx, node_idx|
               next_node = nodes[node_idx]
 
-              if rel_idx < 0
+              if rel_idx.negative?
                 unbound_rel = unbound_rels[rel_idx.abs - 1]
                 bound_rel = unbound_rel.bind(next_node.id, current_node.id,
                                              next_node.element_id, current_node.element_id)

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

@@ -3,6 +3,12 @@
 module Neo4j
   module Driver
     module Exceptions
+      # Base class for the driver's Neo4j-error exceptions — those carrying a
+      # server error code plus the GQL status fields (status, description,
+      # classification, cause, diagnostic record) and a list of suppressed
+      # exceptions. (A few driver exceptions — NoSuchRecordException,
+      # IllegalStateException, UntrustedServerException — subclass RuntimeError
+      # directly and sit outside this hierarchy.)
       class Neo4jException < RuntimeError
         attr_reader :code, :suppressed, :gql_status, :status_description,
                     :classification, :raw_classification, :diagnostic_record, :gql_cause

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

@@ -3,6 +3,8 @@
 module Neo4j
   module Driver
     module Exceptions
+      # Raised when a single record is requested but the result is empty or
+      # holds more than one, or when iteration/peek runs past the last record.
       class NoSuchRecordException < RuntimeError
         EMPTY = 'Cannot retrieve a single record, because this result is empty.'
         TOO_MANY = 'Expected a result with a single record, but this result ' \

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Neo4j
   module Driver
     module Exceptions

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Neo4j
   module Driver
     module Exceptions

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Neo4j
   module Driver
     module Exceptions

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Neo4j
   module Driver
     module Exceptions

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Neo4j
   module Driver
     module Exceptions

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

@@ -3,6 +3,8 @@
 module Neo4j
   module Driver
     module Internal
+      # No-op stand-in for an ActiveSupport-style deprecator; swallows the
+      # `behavior=` configuration the driver would otherwise forward.
       module Deprecator
         class << self
           def deprecator

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

@@ -3,6 +3,10 @@
 module Neo4j
   module Driver
     module Internal
+      # Converts a timeout from seconds (or ActiveSupport::Duration) to integer
+      # milliseconds, rejecting negatives. Used for the Bolt tx_timeout (MRI
+      # session) and, on JRuby, for the connection / routing-table and other
+      # config timeouts handed to the Java driver.
       module DurationNormalizer
         # Convert timeout from seconds (or ActiveSupport::Duration) to
         # milliseconds for the Bolt protocol. A negative timeout is

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

@@ -3,6 +3,8 @@
 module Neo4j
   module Driver
     module Internal
+      # Client-side argument checks (hash parameters, non-nil values, non-empty
+      # query text, credentials) mirroring the Java driver's own validation.
       module Validator
         def self.require_hash_parameters!(parameters)
           require_hash!(parameters) do

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      # The IANA zone identifier for a TimeWithZone-like value's zone, for the
+      # Bolt DateTimeZoneId structure. Matches the Java driver, which sends
+      # ZonedDateTime#getZone#getId verbatim: a zone whose own name is already a
+      # valid IANA id is kept as-is — so "UTC" stays "UTC" rather than TZInfo's
+      # canonical "Etc/UTC" — while an ActiveSupport::TimeZone built from a Rails
+      # display name ("Mountain Time (US & Canada)"), which is not a valid id,
+      # falls back to its tzinfo identifier ("America/Denver"). Returns nil when
+      # the zone exposes no usable identifier (e.g. an offset-only zone), so the
+      # caller can fall back to the offset form.
+      module ZoneIdentifier
+        module_function
+
+        def call(zone)
+          name = zone.name if zone.respond_to?(:name)
+          return name if name && valid?(name)
+
+          zone.tzinfo.identifier if zone.respond_to?(:tzinfo)
+        end
+
+        def valid?(name)
+          TZInfo::Timezone.get(name)
+          true
+        rescue TZInfo::InvalidTimezoneIdentifier
+          false
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/packstream/packer.rb

@@ -114,16 +114,16 @@ module Neo4j
         end
 
         def pack_integer(value)
-          if value >= -16 && value <= 127
+          if value.between?(-16, 127)
             # TINY_INT: -16 to +127
             @buffer << [value].pack('c')
-          elsif value >= -128 && value <= 127
+          elsif value.between?(-128, 127)
             @buffer << [INT_8, value].pack('Cc')
-          elsif value >= -32_768 && value <= 32_767
+          elsif value.between?(-32_768, 32_767)
             @buffer << [INT_16, value].pack('Cs>')
-          elsif value >= -2_147_483_648 && value <= 2_147_483_647
+          elsif value.between?(-2_147_483_648, 2_147_483_647)
             @buffer << [INT_32, value].pack('Cl>')
-          elsif value >= -9_223_372_036_854_775_808 && value <= 9_223_372_036_854_775_807
+          elsif value.between?(-9_223_372_036_854_775_808, 9_223_372_036_854_775_807)
             @buffer << [INT_64, value].pack('Cq>')
           else
             raise ArgumentError, "Integer value out of range: #{value}"
@@ -270,18 +270,16 @@ module Neo4j
           end
         end
 
-        # Return the IANA zone name for a TimeWithZone-like value when it has
-        # one, otherwise nil (so the caller falls back to offset-only 0x46).
-        # Offset-shaped names like "+07:00" or "-05:00" don't round-trip
-        # through Neo4j's zoned DateTime and are treated as nil.
+        # The IANA zone identifier for a TimeWithZone-like value's zone, or nil
+        # when it has none (so the caller falls back to the offset-only 0x46
+        # form). Internal::ZoneIdentifier keeps a zone name that is already a
+        # valid IANA id (so "UTC" stays "UTC") and maps a Rails display name
+        # ("Mountain Time (US & Canada)") to its tzinfo id ("America/Denver"),
+        # returning nil when neither yields an identifier.
         def named_zone_for(value)
           return nil unless value.respond_to?(:time_zone)
 
-          tz = value.time_zone
-          name = tz.respond_to?(:name) ? tz.name : nil
-          return nil if name.nil? || name.empty? || name.match?(/\A[+-]?\d/)
-
-          name
+          Neo4j::Driver::Internal::ZoneIdentifier.call(value.time_zone)
         end
 
         def pack_local_datetime(value)

data/lib/neo4j/driver/routing/load_balancer.rb

@@ -51,6 +51,11 @@ module Neo4j
           # server's authorization cache is per-server — a reader's expiry must
           # not force the writer pool to re-auth.
           @auth_epochs = Hash.new(0)
+          # Leaf lock for @auth_epochs: never held while taking another lock.
+          # Must not be @refresh_lock: open_connection reads the epoch from
+          # inside the pool's create block (under TimedStack's mutex), while
+          # release and refresh take that pool mutex under @refresh_lock.
+          @auth_epoch_lock = Mutex.new
           # Monitor (reentrant) because ensure_routing_table_is_fresh holds
           # the lock while it goes through pool_for, which also locks.
           @refresh_lock = Monitor.new
@@ -238,16 +243,16 @@ module Neo4j
           # owns the token; the manager notification is skipped for a
           # per-session identity.
           if error.is_a?(Exceptions::AuthorizationExpiredException)
-            @refresh_lock.synchronize { @auth_epochs[address] += 1 }
+            @auth_epoch_lock.synchronize { @auth_epochs[address] += 1 }
           end
           return false if session_scoped
 
           @auth_manager.handle_security_exception(token, error)
         end
 
-        # Current auth generation for a server, read under the lock that guards
-        # the @auth_epochs Hash (mutated in on_security_exception).
-        def auth_epoch_for(address) = @refresh_lock.synchronize { @auth_epochs[address] }
+        # Current auth generation for a server, read under the leaf lock that
+        # guards the @auth_epochs Hash (mutated in on_security_exception).
+        def auth_epoch_for(address) = @auth_epoch_lock.synchronize { @auth_epochs[address] }
 
         def release(connection)
           # Direct provider tolerates nil; mirror that. Internal callers
@@ -423,7 +428,7 @@ module Neo4j
         def ensure_routing_table_is_fresh(database, access_mode, bookmarks: nil, imp_user: nil, auth: nil)
           @refresh_lock.synchronize do
             table = @routing_tables[database]
-            return table if table && table.fresh?(readonly: access_mode == :read)
+            return table if table&.fresh?(readonly: access_mode == :read)
 
             update_routing_table(database, bookmarks: bookmarks, imp_user: imp_user, auth: auth)
           end

data/lib/neo4j/driver/summary/result_summary.rb

@@ -44,7 +44,7 @@ module Neo4j
         end
 
         def server
-          @server_info ||=
+          @server ||=
             if @metadata[:server]
               ServerInfo.new(@metadata[:server])
             elsif @connection
@@ -59,7 +59,7 @@ module Neo4j
         end
 
         def database
-          @database_info ||= DatabaseInfo.new(@metadata[:db])
+          @database ||= DatabaseInfo.new(@metadata[:db])
         end
 
         # Time until results are available (milliseconds). 't_first' on the wire.

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

@@ -60,7 +60,7 @@ module Neo4j
         # Normalize nanoseconds overflow/underflow into seconds:
         # -1ns becomes -1s + 999999999ns; 1.5e9 ns becomes 1s + 5e8 ns.
         def normalize!
-          if @nanoseconds < 0
+          if @nanoseconds.negative?
             sec_adjust = (@nanoseconds.abs / NANOS_PER_SECOND.to_f).ceil
             @seconds -= sec_adjust
             @nanoseconds += sec_adjust * NANOS_PER_SECOND

data/lib/neo4j/driver/version.rb

@@ -2,6 +2,6 @@
 
 module Neo4j
   module Driver
-    VERSION = '6.2.1'
+    VERSION = '6.3.0'
   end
 end

data/lib/neo4j/driver.rb

@@ -8,6 +8,8 @@ require 'stringio'
 require 'tzinfo'
 
 module Neo4j
+  # Top-level namespace for the MRI flavour; boots the pure-Ruby Bolt
+  # implementation through the shared Zeitwerk loader.
   module Driver
     Loader.load(:mri)
     AuthTokenManager = Internal::InternalAuthTokenManager

data/lib/neo4j-ruby-driver.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This file is here so that there is a file with the same name as the gem that
 # can be required by Bundler.require. Applications should normally
 # require 'neo4j/driver'.

data/lib/neo4j-ruby-driver_loader.rb

@@ -8,6 +8,8 @@ require 'zeitwerk'
 
 module Neo4j
   module Driver
+    # Boots the driver for a given flavour (:mri or :jruby): configures the
+    # Zeitwerk loader over the shared and impl roots, then eager-loads them.
     class Loader
       class << self
         # `__dir__` resolves to:

data/lib/neo4j_ruby_driver.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # This file is for backwards compatibility only.
 # Applications should require 'neo4j/driver'.
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: neo4j-ruby-driver
 version: !ruby/object:Gem::Version
-  version: 6.2.1
+  version: 6.3.0
 platform: ruby
 authors:
 - Neo4j Driver Team
@@ -149,6 +149,7 @@ files:
 - lib/neo4j/driver/internal/metrics.rb
 - lib/neo4j/driver/internal/security/static_auth_token_manager.rb
 - lib/neo4j/driver/internal/validator.rb
+- lib/neo4j/driver/internal/zone_identifier.rb
 - lib/neo4j/driver/net.rb
 - lib/neo4j/driver/packstream/markers.rb
 - lib/neo4j/driver/packstream/packer.rb