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

data/lib/neo4j/driver/direct/connection_provider.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Direct
+      # Single-server connection provider for `bolt://` URIs.
+      #
+      # Sibling of Routing::LoadBalancer — both implement the same interface
+      # (acquire / release / verify_connectivity / supports_multi_db? / close)
+      # so Driver can hold either polymorphically without branching on scheme.
+      #
+      # Direct ignores the `access_mode`, `database`, and `bookmarks`
+      # kwargs to acquire: all sessions hit the same server, so
+      # role/database/bookmark-aware routing is not its concern. The
+      # kwargs are accepted so call sites stay polymorphic with
+      # Routing::LoadBalancer.
+      class ConnectionProvider
+        # `domain_name_resolver` is the factory-injected hostname->IPs hook
+        # (nil = system DNS); baked into every connection this provider builds.
+        def initialize(uri, auth_manager, options = {}, domain_name_resolver: nil, clock: Internal::Clock.new)
+          @uri = uri
+          @auth_manager = auth_manager
+          @options = options
+          @clock = clock
+          @domain_name_resolver = domain_name_resolver
+          # Authorization-expired generation counter (see Connection#auth_epoch).
+          # Bumped when any connection reports AuthorizationExpired so every
+          # other pooled connection re-authenticates on its next acquire.
+          # Guarded by a mutex: the pool is shared across threads and on JRuby
+          # (mri-on-jruby) there's no GIL, so a bare `+= 1` could lose bumps.
+          @auth_epoch = 0
+          @auth_epoch_mutex = Mutex.new
+        end
+
+        # Current auth generation, read atomically.
+        def auth_epoch = @auth_epoch_mutex.synchronize { @auth_epoch }
+
+        # No home-database resolution on the direct path: a bolt:// driver
+        # talks to one server, which resolves the user's home database itself
+        # when the operation omits `db`. Returns nil so the session leaves it
+        # unset (matches Java's DirectConnectionProvider).
+        def home_database(_bookmarks, _imp_user = nil, _auth = nil) = nil
+
+        # No home-db cache on the direct path (one server, no discovery to skip):
+        # never guess, never track SSR. Keeps Session polymorphic across providers.
+        def ssr_enabled? = false
+        def home_db_guess(_imp_user, _auth) = nil
+        def cache_home_db(_imp_user, _auth, _database) = nil
+
+        # The current default identity, sourced from the auth-token
+        # manager (which refreshes / re-fetches as needed). Sessions
+        # re-auth pooled connections to this on acquire unless they carry
+        # their own per-session :auth_token.
+        def current_auth_token = @auth_manager.get_token
+
+        # Feed a security failure back to the manager. Returns true when
+        # the manager considers it retryable (token refreshed), so the
+        # caller can re-auth and retry. An AuthorizationExpired failure also
+        # bumps the auth epoch: the server dropped its authorization cache
+        # for this identity, so every pooled connection must re-authenticate
+        # (with whatever token is current) before its next use.
+        def on_security_exception(token, error, session_scoped = false)
+          # Provider-side invalidation happens regardless of who owns the token.
+          @auth_epoch_mutex.synchronize { @auth_epoch += 1 } if error.is_a?(Exceptions::AuthorizationExpiredException)
+          # A per-session token wasn't issued by the manager — don't notify it
+          # (testkit: handle_security_exception_count stays 0), and don't treat
+          # the failure as manager-retryable.
+          return false if session_scoped
+
+          @auth_manager.handle_security_exception(token, error)
+        end
+
+        # imp_user is accepted for signature parity with
+        # Routing::LoadBalancer#acquire but unused here: the direct path
+        # has no discovery, so impersonation is enforced on RUN/BEGIN by
+        # the protocol handler (Bolt::Protocol::Base#enforce_impersonation_support!).
+        def acquire(access_mode: nil, database: nil, bookmarks: nil, imp_user: nil, auth: nil, deadline: nil)
+          # See Routing::LoadBalancer#acquire for the rationale.
+          raise Exceptions::IllegalStateException, 'Driver is closed' if @closed
+
+          # `auth` is the per-session override (nil = use the manager's
+          # current token). `effective` is the identity this acquire should
+          # hand out; resolving it consults the manager (get_auth_count == 1
+          # for the default identity, 0 when the session carries its own
+          # token). A freshly-built connection authenticates with it directly
+          # (no LOGOFF/LOGON); a reused one is re-authed to it via
+          # ensure_identity on Bolt 5.1+.
+          #
+          # On Bolt 5.0 there is no in-place re-auth, so a *reused* connection
+          # keeps its creation-time identity. If the manager has since rotated
+          # its token, that connection is stale — discard it and loop, letting
+          # the pool build a fresh one authenticated as the current identity
+          # (Java's backwards-compatible behaviour). Re-resolving `effective`
+          # each turn means the replacement issues its own get_token, as the
+          # managed-auth contract expects (one extra get_auth per rotation).
+          loop do
+            # Snapshot the epoch once per turn so the staleness check and the
+            # connection's stamp (in ensure_identity) use one consistent value.
+            epoch = auth_epoch
+            effective = auth || @auth_manager.get_token
+            conn = pool.pop(auth: effective, deadline: deadline)
+            begin
+              ensure_identity(conn, effective, session_auth: auth, epoch: epoch)
+            rescue StandardError
+              # Identity enforcement can raise (per-session auth on Bolt < 5.1,
+              # or a re-auth LOGON failure). Free the just-checked-out slot
+              # instead of leaking it for the driver's lifetime, then re-raise.
+              pool.discard(conn)
+              raise
+            end
+            # On Bolt 5.1+ ensure_identity already brought the connection to
+            # the right identity (and re-auth generation). On 5.0 it can't, so
+            # a reused connection is only usable if its token AND auth epoch
+            # already match — otherwise discard and let the pool rebuild a
+            # fresh one (token rotation, or an AuthorizationExpired refresh).
+            return conn if conn.protocol.supports_re_auth? ||
+                           (conn.auth == effective && conn.auth_epoch == epoch)
+
+            pool.discard(conn)
+          end
+        end
+
+        def release(connection)
+          return unless connection
+
+          # Honor a connection flagged for discard (e.g. after an auth
+          # failure) — close it and free the slot rather than pooling a
+          # compromised / server-closed connection.
+          if connection.discard_on_release
+            pool.discard(connection)
+          else
+            pool.push(connection)
+          end
+        end
+
+        def verify_connectivity
+          # Probe the connection with a RESET so a reused (pooled) connection
+          # is actually exercised on the wire — matches Java's
+          # verifyConnectivity and the routing LoadBalancer, and testkit's
+          # test_direct_from_pool (which asserts one RESET on the pooled
+          # connection). `propagate: true` surfaces a failed probe (rather than
+          # reporting false success); a failed probe means a dead connection,
+          # so discard it instead of returning it to the pool.
+          conn = acquire
+          begin
+            conn.reset!(propagate: true)
+          rescue StandardError
+            pool.discard(conn)
+            raise
+          end
+          release(conn)
+        end
+
+        # Single-address pool snapshot (driver.metrics). Empty until the pool
+        # has been lazily built by the first acquire.
+        def connection_pool_metrics
+          return [] unless @pool
+
+          address = Routing::ServerAddress.new(host: @uri.host,
+                                               port: @uri.port || Routing::ServerAddress::DEFAULT_PORT)
+          in_use, idle = @pool.metrics_snapshot
+          [Internal::Metrics::ConnectionPoolMetrics.new(address, in_use, idle)]
+        end
+
+        # True iff the negotiated Bolt protocol supports multi-database
+        # routing (Bolt 4.0+). Acquires a connection to ensure HELLO has
+        # happened.
+        def supports_multi_db?
+          conn = acquire
+          conn.protocol.supports_multiple_databases?
+        ensure
+          release(conn)
+        end
+
+        # Mirrors Java: a Direct (bolt://) driver has no routing-table
+        # registry. testkit's GetRoutingTable / ForcedRoutingTableUpdate
+        # handlers expect a clean error here rather than NoMethodError
+        # so callers can distinguish "wrong scheme" from a real bug.
+        def routing_table_registry
+          raise Exceptions::ClientException,
+                'Routing table is only available on routing (neo4j://) drivers'
+        end
+
+        def close
+          @closed = true
+          @pool&.shutdown do |conn|
+            conn.close
+          rescue StandardError
+            nil
+          end
+        end
+
+        private
+
+        # Bring a popped connection to the `effective` identity. A fresh
+        # connection was built with it, so authenticate is a no-op; a reused
+        # one currently authenticated as somebody else is re-authed (LOGOFF/
+        # LOGON, Bolt 5.1+).
+        #
+        # When `session_auth` is set (per-session token), the identity must
+        # be enforceable, so we require Bolt 5.1+ even if the popped
+        # connection already happens to hold the token — a 5.0 connection
+        # built with the session token would otherwise silently bypass the
+        # "per-session auth needs re-auth support" contract. With the default
+        # identity, re-auth is applied only where it exists (5.1+); on 5.0 a
+        # pooled connection keeps its creation-time token and the manager's
+        # refresh reaches new connections instead.
+        def ensure_identity(conn, effective, session_auth:, epoch: auth_epoch)
+          # Record whose identity this connection currently holds so a later
+          # security failure knows whether to notify the manager. Updated
+          # every acquire because a pooled connection changes lessee.
+          conn.session_scoped_auth = !session_auth.nil?
+          # Force a re-auth (even to the same token) when this connection was
+          # authed before the latest AuthorizationExpired — the server needs
+          # a fresh LOGON to rebuild its authorization cache.
+          force = conn.auth_epoch < epoch
+          if session_auth
+            unless conn.protocol.supports_re_auth?
+              raise Exceptions::UnsupportedFeatureException,
+                    "Per-session auth requires Bolt 5.1+; negotiated #{conn.protocol.version}"
+            end
+            conn.authenticate(effective, force: force)
+            conn.auth_epoch = epoch
+          elsif conn.protocol.supports_re_auth?
+            conn.authenticate(effective, force: force)
+            conn.auth_epoch = epoch
+          end
+        end
+
+        # Bolt::Pool wraps connection_pool's TimedStack primitive
+        # and adds the lifetime / liveness / acquisition-timeout gates
+        # (see Bolt::Pool docstring). TimedStack is used because, unlike
+        # ConnectionPool#checkout, it does NOT cache per-thread — each
+        # Session in the same thread must hold its own connection
+        # (they can't share server-side transaction state).
+        def pool
+          @pool ||= Bolt::Pool.new(
+            size: max_pool_size,
+            options: @options,
+            clock: @clock,
+            connect_factory: lambda { |auth, deadline = nil|
+              # `auth` is the per-acquire identity resolved in #acquire and
+              # threaded through pool.pop. The `||` is a belt-and-braces
+              # fallback for any future pop path that forgets to pass one.
+              conn = Bolt::Connection.new(@uri, auth || @auth_manager.get_token, @options,
+                                          domain_name_resolver: @domain_name_resolver, clock: @clock).connect(deadline: deadline)
+              conn.security_exception_handler = method(:on_security_exception)
+              # A freshly-authenticated connection belongs to the current
+              # auth generation, so ensure_identity won't force-re-auth it.
+              conn.auth_epoch = auth_epoch
+              conn
+            }
+          )
+        end
+
+        def max_pool_size
+          @options[:max_connection_pool_size] || Driver::DEFAULT_MAX_POOL_SIZE
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/driver.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Driver for connecting to Neo4j.
+    #
+    # Holds a single ConnectionProvider (Direct for `bolt://`, Routing for
+    # `neo4j://`) chosen at construction. All connection work delegates to
+    # the provider — no scheme branching here.
+    class Driver
+      DEFAULT_MAX_POOL_SIZE = 100
+      DEFAULT_ACQUISITION_TIMEOUT = 60
+
+      # URI schemes that imply transport encryption.
+      ENCRYPTED_SCHEMES = %w[bolt+s bolt+ssc neo4j+s neo4j+ssc].freeze
+
+      # The ConnectionProvider is assembled by the DriverFactory (which wires
+      # in non-public hooks like the domain-name resolver), so the Driver
+      # itself never sees those extension points — it just uses the provider.
+      def initialize(uri, options, connection_provider, clock: Internal::Clock.new)
+        @uri = URI(uri)
+        @options = options
+        @clock = clock
+        @closed = false
+        @connection_provider = connection_provider
+        # Driver-wide default BookmarkManager for execute_query: shared across
+        # calls so they're causally chained (a read after a write sees it).
+        # Built once here rather than lazily so concurrent first calls can't
+        # race into two managers. Mirrors Java's default query bookmark manager.
+        @query_bookmark_manager = BookmarkManagers.default_manager
+      end
+
+      def session(**options)
+        raise Exceptions::ClientException, 'Driver is closed' if @closed
+
+        merged_options = @options.merge(options)
+        # A nil session fetch_size means "inherit the driver default", so it
+        # must not clobber a driver-level value the plain merge just overwrote
+        # (callers — the testkit backend included — may pass fetch_size: nil
+        # when the session didn't set one). Mirrors Java's SessionConfig
+        # falling back to Config#fetchSize.
+        merged_options[:fetch_size] ||= @options[:fetch_size]
+        session = Session.new(@connection_provider, merged_options, clock: @clock)
+
+        return session unless block_given?
+
+        begin
+          result = yield session
+        rescue StandardError => e
+          # Block raised; preserve as primary, attach close-time failures
+          # as suppressed (Java try-with-resources semantics).
+          begin
+            session.close
+          rescue Exceptions::Neo4jException => close_error
+            e.add_suppressed(close_error) if e.respond_to?(:add_suppressed)
+          end
+          raise
+        else
+          # Block exited cleanly. Any close-time error here comes from
+          # draining a result the user never iterated — Java semantics
+          # treat that as cancellation, not a real failure.
+          begin
+            session.close
+          rescue Exceptions::Neo4jException
+          end
+          result
+        end
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @connection_provider.close
+      end
+
+      def verify_connectivity
+        @connection_provider.verify_connectivity
+      rescue Exceptions::Neo4jException
+        # Propagate driver exceptions (auth/security/client/service-
+        # unavailable) as-is, like Java — wrapping them would hide the
+        # type and message callers assert on. Only unexpected non-driver
+        # errors get the contextual wrapper.
+        raise
+      rescue StandardError => e
+        raise Exceptions::ServiceUnavailableException, "Failed to verify connectivity: #{e.message}"
+      end
+
+      def supports_multi_db?
+        @connection_provider.supports_multi_db?
+      end
+
+      def closed?
+        @closed
+      end
+
+      # True iff the driver was constructed to enforce transport encryption
+      # — either via a +s/+ssc URI scheme or an explicit `encryption: true`
+      # option. Mirrors Java's Driver.isEncrypted().
+      def encrypted?
+        ENCRYPTED_SCHEMES.include?(@uri.scheme) || @options[:encryption] == true
+      end
+
+      # Whether the connected server supports per-session re-authentication
+      # (Bolt 5.1+). Probes a connection to read the negotiated protocol's
+      # capability flag. Today our handshake only advertises Bolt 4.4, so
+      # this returns false until the Bolt 5.x HELLO/LOGON work lands.
+      def supports_session_auth?
+        connection = @connection_provider.acquire(access_mode: :read)
+        connection.protocol.supports_re_auth?
+      ensure
+        @connection_provider.release(connection) if connection
+      end
+
+      # Run a query in a managed transaction and return EagerResult
+      # (keys, materialised records, summary). Convenience for "I just
+      # want results, don't make me build a session".
+      #
+      # Signature: `(query, params = {}, config = {})`. Same shape
+      # Session#run uses.
+      #
+      # `config` keys (snake_case):
+      #   :database            — string, the database to target.
+      #   :routing             — RoutingControl::READ / ::WRITE.
+      #   :bookmark_manager    — BookmarkManager for cross-session
+      #                          causal consistency. Pass `nil`
+      #                          explicitly to disable; omit to use
+      #                          the driver default.
+      #   :impersonated_user   — server runs the query as if this user
+      #                          had issued it (Bolt 4.4+, requires
+      #                          impersonator privileges).
+      #   :metadata            — map echoed back in summary; used by
+      #                          query-log / monitoring tooling.
+      #   :timeout             — seconds (or ActiveSupport::Duration);
+      #                          server-side transaction timeout.
+      #   :auth_token          — run this query under a specific identity
+      #                          (Bolt 5.1+ re-auths the connection via
+      #                          LOGOFF/LOGON); omit to use the driver's.
+      def execute_query(cypher, params = {}, config = {})
+        routing = config[:routing] || RoutingControl::WRITE
+
+        # `bookmark_manager: nil` is meaningful (explicitly disables the
+        # manager) and differs from omitting the key, so it's added
+        # conditionally rather than via .compact. `:database` /
+        # `:impersonated_user` / `:auth_token` keep .compact semantics
+        # (nil == omitted). A per-query `:auth_token` pins the session (and so
+        # its connection) to that identity — the provider re-auths on Bolt 5.1+
+        # (Feature:API:Driver.ExecuteQuery:WithAuth).
+        session_opts = {
+          database: config[:database],
+          default_access_mode: routing,
+          impersonated_user: config[:impersonated_user],
+          auth_token: config[:auth_token]
+        }.compact
+        # execute_query chains bookmarks across successive calls via a
+        # driver-wide default BookmarkManager, so a read after a write sees
+        # the write (matches Java's Driver.executeQuery). A caller can override
+        # per call; `bookmark_manager: nil` explicitly disables the chaining.
+        session_opts[:bookmark_manager] =
+          config.key?(:bookmark_manager) ? config[:bookmark_manager] : @query_bookmark_manager
+        # The managed tx this session runs reports TELEMETRY api = 3
+        # (DRIVER_EXECUTE_QUERY), not a plain managed transaction (api 0).
+        # Carried on the session since execute_query drives it through
+        # execute_read/write.
+        session_opts[:telemetry_api] = 3
+
+        # Forwarded to the managed-tx call below — the BEGIN extras
+        # honour metadata/timeout per-tx, not session-wide.
+        tx_kwargs = {
+          metadata: config[:metadata],
+          timeout: config[:timeout]
+        }.compact
+
+        keys = nil
+        records = nil
+        summary = nil
+
+        session(**session_opts) do |s|
+          method = routing == RoutingControl::READ ? :execute_read : :execute_write
+          s.send(method, **tx_kwargs) do |tx|
+            result = tx.run(cypher, **params)
+            records = result.to_a
+            keys = result.keys
+            summary = result.consume
+          end
+        end
+
+        EagerResult.new(keys, records, summary)
+      end
+
+      # Verify that the supplied auth token would succeed against the
+      # server, without disturbing the existing connection state. Returns
+      # true when the credentials are accepted, false when the server
+      # rejects them (see VERIFY_AUTH_NEGATIVE_CODES). Any other error
+      # (transport failure, TLS rejection, server unreachable, a security
+      # code outside the negative set) propagates so the caller can
+      # distinguish "credentials rejected" from "couldn't even ask".
+      #
+      # Mirrors Java's `Driver.verifyAuthentication(AuthToken)` — the token
+      # is required; pass AuthTokens.none for the unauthenticated probe.
+
+      # Security failure codes that mean "these credentials are not valid"
+      # (verify_authentication returns false). Every other security error —
+      # AuthorizationExpired, an unknown Security.* code, a rate-limit — is a
+      # condition the caller must see, so it propagates. Mirrors Java's
+      # verifyAuthentication NEGATIVE/PROPAGATE split.
+      VERIFY_AUTH_NEGATIVE_CODES = %w[
+        Neo.ClientError.Security.Unauthorized
+        Neo.ClientError.Security.CredentialsExpired
+        Neo.ClientError.Security.Forbidden
+        Neo.ClientError.Security.TokenExpired
+      ].freeze
+
+      def verify_authentication(auth_token)
+        # Acquire a read connection AS the supplied identity, routing through
+        # `system` exactly like Java's verifyAuthentication: for neo4j:// this
+        # discovers (ROUTE on system) then reaches a reader; for bolt:// it
+        # uses the single server. We then force a LOGON with the token: a clean
+        # response means the credentials are good. The connection is one-shot —
+        # discarded, never pooled under the probe identity.
+        connection = @connection_provider.acquire(
+          access_mode: AccessMode::READ, database: 'system', auth: auth_token
+        )
+        begin
+          # Force a fresh LOGON even when the pooled connection already holds
+          # this identity (warm verify, or verifying the driver's own token):
+          # verification has to actually round-trip the credentials to the
+          # server, not trust a cached auth state. On a freshly built
+          # connection this is a redundant re-auth the scripts tolerate; on a
+          # reused one it's the whole point. Synchronous (pipelined: false): verify
+          # discards the connection with no operation to carry and drain the
+          # LOGOFF/LOGON replies, so it must read the LOGON result itself.
+          connection.authenticate(auth_token, force: true, pipelined: false)
+        ensure
+          connection.discard_on_release = true
+          @connection_provider.release(connection)
+        end
+        true
+      rescue Exceptions::SecurityException => e
+        raise unless VERIFY_AUTH_NEGATIVE_CODES.include?(e.code)
+
+        false
+      end
+
+      # Driver metrics. Currently exposes per-server connection-pool metrics
+      # (in-use / idle counts per address) via `metrics.connection_pool_metrics`
+      # — what testkit's GetConnectionPoolMetrics reads. The provider owns the
+      # pools and produces the snapshots.
+      def metrics
+        Internal::Metrics.new(@connection_provider)
+      end
+
+      # Routing table for `database` (testkit GetRoutingTable). Returns the
+      # routing table from the load balancer; testkit reads routers/writers/
+      # readers + ttl off it without knowing this internal path.
+      def routing_table(database)
+        connection_provider.routing_table_registry.routing_table_handler(database).routing_table
+      end
+
+      # Force a routing-table refresh (testkit ForcedRoutingTableUpdate).
+      def routing_table_refresh(database, bookmarks)
+        connection_provider.routing_table_registry.refresh(database, bookmarks)
+      end
+
+      attr_reader :connection_provider
+    end
+  end
+end

data/lib/neo4j/driver/eager_result.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Materialised query result returned by Driver#execute_query: keys
+    # (column names), records (already-drained array), and the consumed
+    # summary. Modelled on Java's org.neo4j.driver.EagerResult.
+    EagerResult = Struct.new(:keys, :records, :summary)
+  end
+end

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

@@ -4,17 +4,26 @@ module Neo4j
   module Driver
     module Exceptions
       class Neo4jException < RuntimeError
-        attr_reader :code, :suppressed
+        attr_reader :code, :suppressed, :gql_status, :status_description,
+                    :classification, :raw_classification, :diagnostic_record, :gql_cause
 
-        def initialize(*args)
-          args, exceptions = args.partition { |arg| arg.is_a?(String) }
-          super(args.pop)
-          @code = args.pop
-          add_suppressed(*exceptions)
+        def initialize(message = nil, code: nil, suppressed: nil,
+                       gql_status: nil, status_description: nil,
+                       classification: nil, raw_classification: nil,
+                       diagnostic_record: nil, gql_cause: nil)
+          super(message)
+          @code = code
+          @suppressed = Array(suppressed)
+          @gql_status = gql_status
+          @status_description = status_description
+          @classification = classification
+          @raw_classification = raw_classification
+          @diagnostic_record = diagnostic_record
+          @gql_cause = gql_cause
         end
 
         def add_suppressed(*exceptions)
-          (@suppressed ||= []).concat(exceptions) if exceptions.any?
+          @suppressed.concat(exceptions)
         end
       end
     end

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

@@ -6,7 +6,7 @@ module Neo4j
       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 ' \
-          'contains at least one more. Ensure your query returns only one record.'
+                   'contains at least one more. Ensure your query returns only one record.'
         NO_MORE = 'No more records'
         NO_PEEK_PAST = 'Cannot peek past the last record'
 

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

@@ -6,11 +6,6 @@ module Neo4j
       # 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/security_retryable_exception.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Exceptions
+      # A security exception the driver considers retryable: the auth-token
+      # manager handled the underlying security failure (e.g. an expired
+      # token), so a managed transaction may retry with a fresh token.
+      # Mirrors org.neo4j.driver.exceptions.SecurityRetryableException.
+      class SecurityRetryableException < SecurityException
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Exceptions
+      # The transaction has been terminated, so the work it was running
+      # cannot continue. Mirrors
+      # org.neo4j.driver.exceptions.TransactionTerminatedException.
+      class TransactionTerminatedException < ClientException
+      end
+    end
+  end
+end

data/lib/neo4j/driver/graph_database.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Main entry point for creating Neo4j drivers. Wraps the supplied
+    # `AuthToken` in a `StaticAuthTokenManager` and delegates the
+    # actual construction to `Internal::DriverFactory#new_instance`
+    # — same shape as Java's `GraphDatabase.driver(...)` →
+    # `DriverFactory#newInstance(...)`.
+    module GraphDatabase
+      class << self
+        def driver(uri, auth_token = nil, auth_token_manager: nil, **config, &block)
+          mgr = auth_token_manager || Internal::Security::StaticAuthTokenManager.new(auth_token || AuthTokens.none)
+          driver = Internal::DriverFactory.new.new_instance(uri, mgr, **config)
+
+          if block_given?
+            begin
+              yield driver
+            ensure
+              driver.close
+            end
+          else
+            driver
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Internal
+      # The driver's clock. Every internal that measures elapsed time — pool
+      # idle/lifetime/acquisition, connection deadlines, routing-table ttl,
+      # managed-tx retry budget — reads it instead of calling Process/Time
+      # directly, and gets it injected (DriverFactory#create_clock, threaded
+      # through as its own `clock:` parameter). This default reads the real monotonic
+      # and wall clocks; testkit-backend supplies its own via the same seam
+      # (see Internal::ClockAdapter). The internals are agnostic to which clock
+      # they hold — there is no notion of "real" vs "mock" below this line.
+      class Clock
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        def realtime = ::Time.now
+      end
+    end
+  end
+end