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

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      # Adapts a `#now_millis` time source (epoch milliseconds) to the driver's
+      # monotonic/realtime Clock interface. The MRI counterpart of the jruby
+      # `ClockAdapter` that bridges `#now_millis` into a `java.time.Clock`;
+      # `DriverFactory#to_clock` wraps testkit-backend's clock in it so the
+      # driver internals consume it like any other Clock.
+      class ClockAdapter
+        def initialize(source)
+          @source = source
+        end
+
+        def monotonic = @source.now_millis / 1000.0
+        def realtime = ::Time.at(@source.now_millis / 1000.0)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      # Thread-safe in-memory implementation behind
+      # `BookmarkManagers.default_manager`. Internal because callers
+      # code against the duck type (`bookmarks` + `update_bookmarks`)
+      # and shouldn't depend on this class name.
+      #
+      # `bookmarks_supplier` runs on every `bookmarks` call so external
+      # state (e.g. bookmarks persisted by another node in a cluster of
+      # app servers) is folded into what we send on BEGIN.
+      # `bookmarks_consumer` runs on every successful `update_bookmarks`
+      # so external listeners can react.
+      class DefaultBookmarkManager
+        def initialize(initial_bookmarks: nil, bookmarks_supplier: nil, bookmarks_consumer: nil)
+          @bookmarks = normalize(initial_bookmarks)
+          @supplier = bookmarks_supplier
+          @consumer = bookmarks_consumer
+          @lock = Mutex.new
+        end
+
+        def bookmarks
+          @lock.synchronize { @bookmarks.dup } | normalize(@supplier&.call)
+        end
+
+        # Java's BookmarkManagerImpl semantics: drop everything in
+        # `previous` (set-difference is a no-op for entries we don't
+        # have, so callers can pass the full "what I sent on BEGIN"
+        # snapshot — including the session's own bookmarks — without
+        # special-casing), then add the new ones from the commit
+        # response. Consumer sees the post-update set.
+        def update_bookmarks(previous, new)
+          prev_set = normalize(previous)
+          new_set = normalize(new)
+          updated_snapshot = nil
+          @lock.synchronize do
+            @bookmarks -= prev_set
+            @bookmarks |= new_set
+            updated_snapshot = @bookmarks.dup
+          end
+          @consumer&.call(updated_snapshot)
+        end
+
+        private
+
+        def normalize(bookmarks)
+          Set.new(Array(bookmarks).map(&Bookmark.method(:from)))
+        end
+      end
+    end
+  end
+end

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

@@ -1,13 +1,17 @@
+# frozen_string_literal: true
+
 module Neo4j
   module Driver
     module Internal
       module Deprecator
-        def self.deprecator
-          @deprecator ||= ActiveSupport::Deprecation.new('6.0', 'neo4j-ruby-driver')
-        end
+        class << self
+          def deprecator
+            self
+          end
 
-        def self.log_warning(old_method, new_method, version)
-          deprecator.deprecation_warning(old_method, new_method)
+          def behavior=(value)
+            # No-op for now
+          end
         end
       end
     end

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

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      # MRI flavour of the impl-agnostic `Internal::DriverFactory`
+      # seam. Owns the actual driver-construction logic — URI
+      # validation + `Internal::Driver.new(...)` — so that
+      # `GraphDatabase.driver` is just the convenience entry point
+      # that wraps the user-supplied `AuthToken` in a
+      # `StaticAuthTokenManager` and calls us.
+      #
+      # The factory is also the single owner of the driver's non-public
+      # extension hooks: `getDomainNameResolver` (nil by default = system DNS)
+      # and `create_clock` (the real system clock by default). testkit's
+      # subclass overrides them. Rather than leaking these into the
+      # user-facing config, new_instance threads them as their own parameters
+      # into the ConnectionProvider it assembles, so the Driver and the
+      # user-facing `config` never carry them. `to_domain_name_resolver` is
+      # identity (MRI doesn't bridge resolver types); `to_clock` wraps a
+      # `#now_millis` source in Internal::ClockAdapter.
+      class DriverFactory
+        VALID_SCHEMES = %w[bolt bolt+s bolt+ssc neo4j neo4j+s neo4j+ssc].freeze
+
+        def to_domain_name_resolver(resolver_proc)
+          resolver_proc
+        end
+
+        # Wrap a `#now_millis` time source in the driver's Clock interface. The
+        # jruby flavour wraps it in a java.time.Clock adapter instead.
+        def to_clock(clock)
+          Internal::ClockAdapter.new(clock)
+        end
+
+        # camelCase to match the name Java's DriverFactory exposes and that
+        # subclasses (testkit's DriverFactoryWithDomainNameResolver) call
+        # `super` on. Default: no custom resolver (system DNS is used). The
+        # subclass returns its proc when one is registered, else falls through
+        # to this via `super`.
+        def getDomainNameResolver = nil
+
+        # The clock the driver's internals run on. Default is the real system
+        # clock; testkit's subclass overrides this (returning `to_clock` of its
+        # own time source) so its tests can freeze/advance time — the driver
+        # stays agnostic.
+        def create_clock = Internal::Clock.new
+
+        # Mutual-TLS client certificates (Feature:API:SSLClientCertificate): the
+        # ClientCertificateManager is threaded into the options every connection's
+        # TlsConfig reads, so each connection's SSL context presents the current
+        # (rotatable) client certificate. nil (the common case) leaves TLS
+        # unchanged.
+        def new_instance(uri, auth_token_manager, client_certificate_manager: nil, **config)
+          parsed_uri = validate_uri(uri)
+          validate_security_settings(parsed_uri.scheme, config)
+          config = config.merge(client_certificate_manager: client_certificate_manager) if client_certificate_manager
+          # The factory is the single place that knows about the non-public
+          # extension hooks (the domain-name resolver and the clock). It
+          # assembles a fully-wired ConnectionProvider with
+          # those baked in and hands it to the Driver, so the Driver and the
+          # user-facing `config` never carry these hooks.
+          #
+          # Retain the manager (not a frozen token): the provider consults it
+          # for the current token on every acquire and on security failures,
+          # so token refresh / re-auth works.
+          #
+          # The clock the internals run on (default real, testkit's own
+          # otherwise) is an internal extension hook like the domain-name
+          # resolver — threaded as its own parameter to the provider / pool /
+          # connection / routing / session, never mixed into the user-facing
+          # `config`.
+          clock = create_clock
+          provider = build_connection_provider(parsed_uri, auth_token_manager, config, clock)
+          Driver.new(uri, config, provider, clock: clock)
+        end
+
+        private
+
+        def build_connection_provider(uri, auth_manager, options, clock)
+          klass = uri.scheme.start_with?('neo4j') ? Routing::LoadBalancer : Direct::ConnectionProvider
+          klass.new(uri, auth_manager, options, domain_name_resolver: getDomainNameResolver, clock: clock)
+        end
+
+        def validate_uri(uri)
+          parsed = URI(uri)
+          raise ArgumentError, 'Scheme must not be null' if parsed.scheme.nil? || parsed.scheme.empty?
+          raise ArgumentError, "Unsupported URI scheme: #{parsed.scheme}" unless VALID_SCHEMES.include?(parsed.scheme)
+
+          # Routing context (URI query parameters, e.g. region/policy) only
+          # applies to routing drivers (neo4j://). A direct bolt:// driver
+          # would silently drop it — so reject it instead, matching Java's
+          # IllegalArgumentException. Server Side Routing is not enabled by
+          # passing a routing context to a direct connection.
+          if parsed.scheme.start_with?('bolt') && !parsed.query.to_s.empty?
+            raise ArgumentError,
+                  "Routing parameters are not supported with scheme '#{parsed.scheme}'. Given URI: '#{uri}'"
+          end
+          parsed
+        rescue URI::InvalidURIError
+          raise ArgumentError, 'Scheme must not be null'
+        end
+
+        # A +s/+ssc scheme already fixes the security plan (encrypted, plus
+        # trust-all for +ssc). Combining it with *manually configured*
+        # encryption or trust settings is a conflict — mirror Java's
+        # SecuritySettings.assertSecuritySettingsNotUserConfigured and raise.
+        #
+        # Value equality (Detail:DefaultSecurityConfigValueEquality): a setting
+        # whose value equals the driver default (encryption off; trust = system
+        # certificates) is treated as *not* configured, so it is not a conflict.
+        # That is why `encryption: false` / no trust strategy on a +s scheme is
+        # accepted while `encryption: true` or an explicit trust strategy raises.
+        def validate_security_settings(scheme, config)
+          return unless Driver::ENCRYPTED_SCHEMES.include?(scheme)
+          return unless security_settings_customized?(config)
+
+          raise Exceptions::ClientException,
+                "Scheme #{scheme} is not configurable with manual encryption and trust settings"
+        end
+
+        def security_settings_customized?(config)
+          config[:encryption] == true ||
+            ![nil, :trust_system_certificates].include?(config.dig(:trust_strategy, :strategy))
+        end
+      end
+    end
+  end
+end

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

@@ -4,47 +4,22 @@ module Neo4j
   module Driver
     module Internal
       module DurationNormalizer
-        class << self
-          def normalize(object)
-            parts = object.parts.to_h
-            parts.default = 0
-            months_i, months_remainder_seconds = divmod(months(parts), ActiveSupport::Duration::SECONDS_PER_MONTH)
-            months_days, months_remainder_seconds =
-              months_remainder_seconds.divmod(ActiveSupport::Duration::SECONDS_PER_DAY)
-            days_i, days_remainder_seconds = divmod(months_days + days(parts), ActiveSupport::Duration::SECONDS_PER_DAY)
-            seconds_i, nonanoseconds = divmod(months_remainder_seconds + days_remainder_seconds + seconds(parts),
-                                              1_000_000_000)
-            [months_i, days_i, seconds_i, nonanoseconds.round]
+        # Convert timeout from seconds (or ActiveSupport::Duration) to
+        # milliseconds for the Bolt protocol. A negative timeout is
+        # invalid — reject it client-side (matches Java, which raises
+        # rather than sending a negative tx_timeout to the server).
+        def timeout_to_milliseconds(timeout)
+          return if timeout.nil?
+
+          # Check the sign before rounding: a tiny negative timeout
+          # (e.g. -0.4ms) would otherwise round to 0 and slip through.
+          ms = timeout.to_f * 1000
+          if ms.negative?
+            raise Exceptions::ClientException,
+                  "Transaction timeout must not be negative, but was #{ms}ms"
           end
 
-          def milliseconds(duration)
-            duration&.in_milliseconds&.round
-          end
-
-          def create(months, days, seconds, nanoseconds)
-            { months:, days:, seconds: seconds + (nanoseconds.zero? ? 0 : nanoseconds * BigDecimal('1e-9')) }
-              .sum { |key, value| ActiveSupport::Duration.send(key, value) }
-          end
-
-          private
-
-          def divmod(number, factor)
-            number_i, remainder = number.divmod(1)
-            [number_i.to_i, remainder * factor]
-          end
-
-          def months(parts)
-            parts[:years] * 12 + parts[:months]
-          end
-
-          def days(parts)
-            parts[:weeks] * 7 + parts[:days]
-          end
-
-          def seconds(parts)
-            parts[:hours] * ActiveSupport::Duration::SECONDS_PER_HOUR +
-              parts[:minutes] * ActiveSupport::Duration::SECONDS_PER_MINUTE + parts[:seconds]
-          end
+          ms.round
         end
       end
     end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      # Shared helpers for building Bolt protocol extras maps (RUN /
+      # BEGIN / etc). Kept tiny on purpose — we don't depend on
+      # ActiveSupport so this is the local replacement for
+      # `Hash#compact_blank!`.
+      module Extras
+        # Use as a Hash#reject! predicate to drop nil and
+        # empty-collection values:
+        #
+        #   extras.reject!(&Internal::Extras::BLANK)
+        #
+        # Matches what other drivers serialise — testkit stub scripts
+        # strictly compare the map, so an empty `tx_metadata: {}` or
+        # an empty `bookmarks: []` left in the payload would mismatch.
+        BLANK = ->(_, v) { v.nil? || (v.respond_to?(:empty?) && v.empty?) }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      # Driver-level cache mapping a user identity to their most recently
+      # resolved home database (Optimization:HomeDatabaseCache). It lets a routed
+      # session skip home-database discovery by optimistically guessing the
+      # cached database — safe only when every pooled connection advertised
+      # server-side routing (`ssr.enabled`), so the server transparently
+      # re-routes a wrong guess. Bounded, least-recently-used eviction.
+      class HomeDbCache
+        DEFAULT_MAX_SIZE = 10_000
+
+        def initialize(max_size: DEFAULT_MAX_SIZE)
+          @max_size = max_size
+          # Insertion order doubles as LRU recency: a Ruby Hash preserves it, so
+          # #get re-inserts the touched key at the end and #set evicts from the
+          # front once the cache is full.
+          @entries = {}
+          @mutex = Mutex.new
+        end
+
+        # The cache key for an identity: the impersonated user when set, else the
+        # per-session auth token (driver-level auth is nil, so every default-auth
+        # session shares one entry — the cache is bound to the identity, not the
+        # rotating token). Matches the Java driver: a basic-auth principal is NOT
+        # folded into the impersonated-user space
+        # (Optimization:HomeDbCacheBasicPrincipalIsImpersonatedUser stays off).
+        def compute_key(imp_user, auth) = imp_user || auth
+
+        # The cached database for this key, or nil on a miss. Touches recency.
+        def get(key)
+          @mutex.synchronize do
+            next nil unless @entries.key?(key)
+
+            database = @entries.delete(key)
+            @entries[key] = database
+            database
+          end
+        end
+
+        # Remember (or refresh) the resolved home database for this key. A nil
+        # database is ignored — there's nothing to guess next time.
+        def set(key, database)
+          return if database.nil?
+
+          @mutex.synchronize do
+            @entries.delete(key)
+            @entries[key] = database
+            @entries.shift while @entries.size > @max_size
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      # Auth-token manager: anything responding to
+      #
+      #   get_token                                   -> AuthToken
+      #   handle_security_exception(token, exception) -> Boolean
+      #
+      # is a manager. Pass an instance to `GraphDatabase.driver` via the
+      # `:auth_token_manager` kw arg and the driver will call back into
+      # it when it needs a fresh token or when the server rejects the
+      # current one.
+      #
+      # This concrete class is the Proc-based shortcut — supply two
+      # callables and you're done. Clients that need richer behaviour
+      # subclass and override the methods; the JRuby flavour's class
+      # additionally implements `org.neo4j.driver.AuthTokenManager`, so
+      # subclasses there automatically slot into the Java driver.
+      class InternalAuthTokenManager
+        def initialize(get_token:, handle_security_exception:)
+          @get_token = get_token
+          @handle_security_exception = handle_security_exception
+        end
+
+        def get_token
+          @get_token.call
+        end
+
+        def handle_security_exception(token, exception)
+          @handle_security_exception.call(token, exception)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      # Driver metrics surface (testkit's `driver.metrics`). Today only the
+      # per-server connection-pool metrics are exposed — how many connections
+      # to each server address are in use vs. idle — which is what testkit's
+      # GetConnectionPoolMetrics / test_should_drop_connections_failing_
+      # liveness_check reads. The provider (Direct or Routing::LoadBalancer)
+      # owns the pools, so it produces the per-address snapshots.
+      class Metrics
+        # Per-server-address snapshot. `address` is a Routing::ServerAddress
+        # (responds to #host/#port so the testkit handler can match it). `#id`
+        # is the "host:port" string form, the forward-compatible duck-typed key
+        # DECISIONS.md (2026-06-05) describes for a future metrics contract.
+        ConnectionPoolMetrics = Struct.new(:address, :in_use, :idle) do
+          def id = address.to_s
+        end
+
+        def initialize(connection_provider)
+          @connection_provider = connection_provider
+        end
+
+        def connection_pool_metrics
+          @connection_provider.connection_pool_metrics
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/internal/security/static_auth_token_manager.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      module Security
+        # MRI counterpart to Java's
+        # `org.neo4j.driver.internal.security.StaticAuthTokenManager`.
+        # Returns the same `AuthToken` forever and never treats a
+        # security exception as retryable. Subclasses our
+        # duck-typed `Neo4j::Driver::AuthTokenManager` so the protocol
+        # — `get_token` / `handle_security_exception` — matches
+        # everything else MRI consumes.
+        class StaticAuthTokenManager < InternalAuthTokenManager
+          def initialize(token)
+            super(
+              get_token: -> { token },
+              handle_security_exception: ->(_, _) { false }
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -16,12 +16,26 @@ module Neo4j
 
         def self.require_non_nil!(obj, message = nil)
           raise ArgumentError, [message, "can't be nil"].compact.join(' ') if obj.nil?
+
           obj
         end
 
+        # Matches Java's driver-side query-text validation (the JRuby
+        # flavour gets this for free from the Java driver). A Query
+        # object carries its own text, so only bare strings are checked.
+        def self.require_query_text!(query)
+          raise ArgumentError, 'Cypher query text should not be null' if query.nil?
+          if query.is_a?(String) && query.strip.empty?
+            raise ArgumentError,
+                  'Cypher query text should not be an empty string'
+          end
+
+          query
+        end
+
         def self.require_non_nil_credentials!(username, password)
-          require_non_nil! username, "Username"
-          require_non_nil! password, "Password"
+          require_non_nil! username, 'Username'
+          require_non_nil! password, 'Password'
         end
       end
     end

data/lib/neo4j/driver/net.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Mirrors Java's org.neo4j.driver.net package — just enough to let
+    # cross-flavour callers (testkit-backend, user resolver code) build
+    # ServerAddress values without branching on flavour.
+    module Net
+      ServerAddress = Data.define(:host, :port) do
+        def self.of(host, port)
+          new(host, port)
+        end
+
+        # "host:port" (IPv6 hosts bracketed) — matches Java's
+        # ServerAddress.toString and Routing::ServerAddress#to_s. Without
+        # this, the default Data inspect (`#<data … host="h", port=N>`)
+        # leaks anywhere a caller stringifies the address: a custom
+        # resolver returns Net::ServerAddress values and
+        # Bolt::Connection#split_addr does `addr.to_s.rpartition(":")`,
+        # which then split on the `::` inside the class name and fed the
+        # tail to Integer() — the ArgumentError across the v4x4/v5x0
+        # resolver routing tests.
+        def to_s
+          host.include?(':') && !host.start_with?('[') ? "[#{host}]:#{port}" : "#{host}:#{port}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module PackStream
+      # PackStream wire-format marker bytes.
+      # See https://neo4j.com/docs/bolt/current/packstream/ for the full table.
+      module Markers
+        TINY_STRING = 0x80
+        TINY_LIST = 0x90
+        TINY_MAP = 0xA0
+        TINY_STRUCT = 0xB0
+
+        NULL = 0xC0
+        FLOAT_64 = 0xC1
+        BOOLEAN_FALSE = 0xC2
+        BOOLEAN_TRUE = 0xC3
+
+        INT_8 = 0xC8
+        INT_16 = 0xC9
+        INT_32 = 0xCA
+        INT_64 = 0xCB
+
+        BYTES_8 = 0xCC
+        BYTES_16 = 0xCD
+        BYTES_32 = 0xCE
+
+        STRING_8 = 0xD0
+        STRING_16 = 0xD1
+        STRING_32 = 0xD2
+
+        LIST_8 = 0xD4
+        LIST_16 = 0xD5
+        LIST_32 = 0xD6
+
+        MAP_8 = 0xD8
+        MAP_16 = 0xD9
+        MAP_32 = 0xDA
+
+        STRUCT_8 = 0xDC
+        STRUCT_16 = 0xDD
+
+        # PackStream V2 (Bolt 6.1+): a UUID is a top-level value — the marker
+        # 0xE0 followed by the 16 raw bytes (big-endian) — not a struct.
+        UUID = 0xE0
+      end
+    end
+  end
+end