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

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

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Routing
+      # Bolt::Connection wrapper that classifies routing-relevant
+      # errors and feeds the routing table back. Mirrors Java's
+      # RoutedBoltConnection + RoutingErrorHandler.onWriteFailure /
+      # onConnectionFailure.
+      #
+      # The wrapper is a pure delegator on the read/write path — every
+      # method is forwarded straight to the inner Bolt::Connection.
+      # Classification doesn't happen on the wire-call boundary because
+      # Bolt failures only become exceptions when the caller does
+      # `.assert_success!` on the response (which raises outside the
+      # delegator), and streaming failures only become exceptions when
+      # Result's visitor dispatches to `on_failure`. Both of those call
+      # sites — plus session.rb / transaction.rb's wire-error rescues —
+      # invoke `classify_failure(error)` explicitly to run the side
+      # effects (deactivate / on_write_failure) and get the
+      # (possibly-swapped) exception to re-raise.
+      class RoutedConnection
+        extend Forwardable
+
+        # Server-side error codes that indicate the connected node is no
+        # longer the leader for the database we wrote to. Surface is
+        # narrow on purpose — anything else (constraint violations,
+        # syntax errors, etc.) is a user-facing failure that mustn't
+        # invalidate the routing table.
+        WRITE_FAILURE_CODES = %w[
+          Neo.ClientError.Cluster.NotALeader
+          Neo.ClientError.General.ForbiddenOnReadOnlyDatabase
+        ].freeze
+
+        DATABASE_UNAVAILABLE_CODE = 'Neo.TransientError.General.DatabaseUnavailable'
+
+        attr_reader :inner, :address_obj
+        attr_accessor :discard_on_release
+
+        def initialize(pool, inner, address_obj, access_mode, database)
+          @pool = pool
+          @inner = inner
+          @address_obj = address_obj
+          @access_mode = access_mode
+          @database = database
+          @discard_on_release = false
+        end
+
+        def_delegators :@inner,
+                       :address, :server_agent, :server_version, :protocol,
+                       :closed?, :close, :pending_responses?,
+                       :send_message, :send_all, :flush, :telemetry,
+                       :fetch_response, :fetch_all,
+                       :reset!, :route,
+                       :auth, :driver_auth, :authenticate,
+                       :auth_failed, :notify_security_exception, :ssr_enabled?
+
+        # Run a caught exception through the routing classifier:
+        # - ServiceUnavailableException → deactivate(address); mark
+        #   the connection discardable; return the same exception.
+        # - TransientException with DatabaseUnavailable → same.
+        # - ClientException with NotALeader / ForbiddenOnReadOnly on
+        #   a WRITE → on_write_failure(address, database) to forget the
+        #   writer (forces a re-route); the connection is NOT discarded
+        #   (the node is fine, just not the leader) — RESET on release
+        #   makes it reusable. Returns a SessionExpiredException (so
+        #   session retry catches it) with the original error code preserved.
+        # - Anything else → return the same exception unchanged.
+        #
+        # Callers: session.rb (RUN-response rescue), transaction.rb
+        # (BEGIN/RUN/COMMIT rescues), Result#on_failure (streaming
+        # PULL/DISCARD). Each invokes this in its catch-Neo4jException
+        # block and re-raises whatever we return.
+        def classify_failure(error)
+          # Funnel security failures to the auth-token manager first (via
+          # the inner connection's provider-set handler); a retryable one
+          # comes back wrapped as SecurityRetryableException. Then apply
+          # routing classification to whatever we surface.
+          error = @inner.notify_security_exception(error)
+          # A security failure compromises the connection (server closes
+          # it; identity is bad) — discard regardless of routing role.
+          @discard_on_release = true if error.is_a?(Exceptions::SecurityException)
+
+          case error
+          when Exceptions::SessionExpiredException
+            # Already routing-classified — deactivate and keep the type.
+            @discard_on_release = true
+            @pool.deactivate(@address_obj)
+            error
+          when Exceptions::ServiceUnavailableException
+            @discard_on_release = true
+            @pool.deactivate(@address_obj)
+            # In routing, a dead connection means this server can no longer
+            # serve the session — surface as SessionExpired so managed-tx
+            # retry picks a different server (mirrors Java's RoutingConnection
+            # mapping connection failures to SessionExpired). Both are
+            # retryable, so retry behaviour is unchanged; only the surfaced
+            # type differs. The original is chained as `cause` automatically
+            # when the caller re-raises this inside its `rescue => error`.
+            Exceptions::SessionExpiredException.new(error.message, code: error.code)
+          when Exceptions::TransientException
+            if error.code == DATABASE_UNAVAILABLE_CODE
+              @discard_on_release = true
+              @pool.deactivate(@address_obj)
+            end
+            error
+          when Exceptions::ClientException
+            if @access_mode == :write && WRITE_FAILURE_CODES.include?(error.code)
+              # NotALeader / ForbiddenOnReadOnlyDatabase: the node is no longer
+              # the leader, but the connection itself is fine. Forget it as a
+              # writer (forces a re-route) but DON'T discard it — RESET on
+              # release (Bolt::Pool#push) clears the FAILED state so the retry
+              # can reuse it (matches Java's onWriteFailure, which keeps the
+              # connection; testkit's retry_with_fail_after_pull reuses it).
+              @pool.on_write_failure(@address_obj, @database)
+              # Original ClientException chained as `cause` at re-raise.
+              Exceptions::SessionExpiredException.new(
+                "Server at #{@address_obj} no longer accepts writes for database " \
+                "#{@database.inspect} (#{error.code})",
+                code: error.code
+              )
+            else
+              error
+            end
+          else
+            error
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Routing
+      # Snapshot of the cluster's routing roles, plus mutators used by the
+      # error→action handlers (`forget` on connection failure, `forget_writer`
+      # on NotALeader / ForbiddenOnReadOnlyDatabase). Mirrors the design of
+      # Java's ClusterRoutingTable + Python's _routing.RoutingTable.
+      #
+      # Threading: callers (LoadBalancer) hold @refresh_lock while mutating
+      # or reading. Methods here are not internally synchronised.
+      class RoutingTable
+        # Servers don't always return a writer right away (e.g. cluster
+        # mid-leader-election). The table is still usable for reads in
+        # that window, but the next routing refresh should prefer the
+        # initial address (the seed router) over the existing routers list
+        # since the latter may have been populated by a leaderless reply.
+        attr_reader :database, :routers, :readers, :writers,
+                    :last_updated, :ttl, :initialized_without_writers
+
+        ROLE_TO_KEY = { 'READ' => :readers, 'WRITE' => :writers, 'ROUTE' => :routers }.freeze
+
+        # Build a table from the `rt` map returned by the BOLT ROUTE message:
+        #   {ttl: 1000, db: "homedb", servers: [{addresses: [...], role: "READ"}, ...]}
+        def self.from_response(rt, requested_database, clock: Internal::Clock.new)
+          buckets = { readers: [], writers: [], routers: [] }
+          (rt[:servers] || []).each do |server|
+            key = ROLE_TO_KEY[server[:role]] or next
+            (server[:addresses] || []).each { |addr| buckets[key] << ServerAddress.parse(addr) }
+          end
+
+          new(
+            database: requested_database || rt[:db],
+            routers: buckets[:routers].uniq,
+            readers: buckets[:readers].uniq,
+            writers: buckets[:writers].uniq,
+            ttl: (rt[:ttl] || 0).to_f,
+            clock: clock
+          )
+        end
+
+        def initialize(database:, routers: [], readers: [], writers: [], ttl: 0, clock: Internal::Clock.new)
+          @database = database
+          @routers = routers.to_set
+          @readers = readers.to_set
+          @writers = writers.to_set
+          @ttl = ttl
+          @clock = clock
+          @last_updated = @clock.realtime
+          @initialized_without_writers = @writers.empty?
+        end
+
+        # A table is fresh when it isn't expired AND has the servers needed
+        # for the requested access mode. An empty writers list is acceptable
+        # for read-only acquires (initialized_without_writers state), but a
+        # write-mode acquire needs a writer.
+        def fresh?(readonly:, now: @clock.realtime)
+          return false if expired?(now)
+          return false if @routers.empty?
+
+          readonly ? @readers.any? : @writers.any?
+        end
+
+        def expired?(now = @clock.realtime)
+          now >= @last_updated + @ttl
+        end
+
+        # Absolute expiry in epoch millis (last_updated + ttl). testkit's
+        # backend derives the relative ttl from this — uniformly with JRuby,
+        # whose Java RoutingTable exposes only this absolute timestamp.
+        def expiration_timestamp
+          ((@last_updated + @ttl).to_f * 1000).round
+        end
+
+        # Past the cache grace period? Used by LoadBalancer to drop tables
+        # for databases nobody is touching anymore.
+        def purge?(grace:, now: @clock.realtime)
+          now >= @last_updated + @ttl + grace
+        end
+
+        # Replace the contents in place with another table's roles. The
+        # existing table identity is preserved so anyone holding a reference
+        # sees the new state.
+        def update(other)
+          @routers = other.routers.dup
+          @readers = other.readers.dup
+          @writers = other.writers.dup
+          @ttl = other.ttl
+          @last_updated = @clock.realtime
+          @initialized_without_writers = @writers.empty?
+        end
+
+        # Remove an address from every role bucket. Called on connection
+        # failure: the server is gone, drop it everywhere.
+        def forget(address)
+          @routers.delete(address)
+          @readers.delete(address)
+          @writers.delete(address)
+        end
+
+        # Remove an address only from the writers bucket. Called when a
+        # WRITE op fails with NotALeader / ForbiddenOnReadOnlyDatabase:
+        # the server is alive but no longer the leader, so it can still
+        # serve reads.
+        def forget_writer(address)
+          @writers.delete(address)
+        end
+
+        def servers_for(access_mode)
+          case access_mode
+          when :read  then @readers
+          when :write then @writers
+          when :route then @routers
+          else raise ArgumentError, "Unknown access mode: #{access_mode.inspect}"
+          end
+        end
+
+        # Union of all role buckets — used when shutting down per-server
+        # pools that no current routing table references.
+        def servers
+          @routers | @readers | @writers
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Routing
+      # Host:port pair for a single Bolt server. Hashable so it works as
+      # a key in the LoadBalancer's per-server pool map.
+      class ServerAddress < Data.define(:host, :port)
+        DEFAULT_PORT = 7687
+
+        # Parse "host:port" or "[ipv6]:port" (or bare "host" → default port).
+        def self.parse(string)
+          host, sep, port = string.to_s.rpartition(':')
+          return new(host: string.to_s, port: DEFAULT_PORT) if sep.empty?
+
+          new(host: host, port: Integer(port))
+        end
+
+        def to_s
+          host.include?(':') && !host.start_with?('[') ? "[#{host}]:#{port}" : "#{host}:#{port}"
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/routing_control.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Per-query routing for `driver.execute_query` — the Java driver's
+    # RoutingControl. It is the same READ/WRITE concept as AccessMode (Java's
+    # execute_query lowers RoutingControl to AccessMode internally), so on MRI
+    # we make it a synonym. Kept as a distinct name to mirror the Java API
+    # surface (AccessMode for sessions, RoutingControl for queries) and to
+    # allow the two to diverge later without an API change.
+    RoutingControl = AccessMode
+  end
+end