neo4j-ruby-driver 6.0.0.alpha.2 → 6.2.1.beta.1

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

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      # Bolt handshake negotiation. Two paths share the same 20-byte
+      # preamble (magic + four 4-byte slots, slot 1 = manifest sentinel):
+      #
+      #   Legacy: server replies with one of the proposed versions
+      #           (4 bytes, big-endian). Pre-5.7 servers always take
+      #           this path because they don't speak manifest.
+      #
+      #   Manifest v1: server replies with the sentinel 0x000001FF,
+      #           then sends a varint count + N×4-byte version ranges +
+      #           a varlong capabilities mask. Client picks the highest
+      #           version it supports and writes back the chosen
+      #           version (4 bytes) + a varlong of capabilities
+      #           (currently always 0 — we negotiate no capabilities).
+      #
+      # Mirrors `BoltProtocolUtil` / `HandshakeHandler` / `ManifestHandlerV1`
+      # in neo4j-bolt-connection-java.
+      class Handshake
+        MAGIC_PREAMBLE = "\x60\x60\xB0\x17".b
+
+        # First four bytes of an HTTP response ("HTTP") read as a
+        # big-endian int — a server speaking HTTP on the Bolt port.
+        HTTP_REPLY = 0x4854_5450
+
+        # Slot 1 advertises "I speak HandshakeManifestV1". Decodes as
+        # BoltVersion(major=255, minor=1); servers that don't understand
+        # the sentinel ignore it and pick from slots 2-4 instead.
+        MANIFEST_SENTINEL = 0x00_00_01_FF
+
+        # Range encoding: [reserved=0, range=N, minor, major]. Each
+        # slot covers `major.minor` down to `major.(minor-N)`. We
+        # advertise 5.0–5.8 (slot 2), 4.2–4.4 (slot 3) and 3.0 (slot 4).
+        # Bolt 3.0 is fully wired now (Protocol::V3: PULL_ALL /
+        # DISCARD_ALL, single-DB, no routing in HELLO).
+        SLOTS = [
+          MANIFEST_SENTINEL,
+          0x00_08_08_05,  # 5.0–5.8
+          0x00_02_04_04,  # 4.2–4.4
+          0x00_00_00_03   # 3.0
+        ].freeze
+
+        # Versions we'd accept from a manifest, highest-preference first.
+        # Used to pick a winner from whatever the server advertises.
+        SUPPORTED_VERSIONS = [
+          BoltVersion::V6_1,
+          BoltVersion::V6_0,
+          BoltVersion::V5_8,
+          BoltVersion::V5_7,
+          BoltVersion::V5_6,
+          BoltVersion::V5_5,
+          BoltVersion::V5_4,
+          BoltVersion::V5_3,
+          BoltVersion::V5_2,
+          BoltVersion::V5_1,
+          BoltVersion::V5_0,
+          BoltVersion::V4_4,
+          BoltVersion::V4_3,
+          BoltVersion::V4_2,
+          BoltVersion::V3_0
+        ].freeze
+
+        # `deadline` (monotonic) bounds the negotiation reads so a server that
+        # stalls the magic-byte exchange can't outlast the acquisition timeout.
+        # We read via wait_readable + read_nonblock rather than read(n)+IO#timeout
+        # because IO#timeout is honored for read() only on CRuby, not JRuby —
+        # wait_readable times out on both, so the bound works on every flavor.
+        def initialize(socket, deadline: nil, clock: Internal::Clock.new)
+          @socket = socket
+          @deadline = deadline
+          @clock = clock
+        end
+
+        # Run the handshake to completion. Returns the negotiated
+        # version as a 32-bit int in the wire's slot encoding
+        # ([reserved, range=0, minor, major]).
+        # Sanity cap on the manifest's range-count varint. The varint
+        # itself is bounded to 63 usable bits but a server (malicious
+        # or buggy) could still ask us to allocate billions of slots.
+        # 256 is comfortably above the realistic upper bound (Java
+        # currently advertises ~5 ranges) and well below anything
+        # that'd hurt to allocate.
+        MAX_MANIFEST_RANGES = 256
+
+        def negotiate
+          @socket.write(MAGIC_PREAMBLE)
+          SLOTS.each { |slot| @socket.write([slot].pack('L>')) }
+          @socket.flush
+
+          server_reply = read_int32!('Server closed the connection during handshake')
+          raise Exceptions::ServiceUnavailableException,
+                'Server does not support any of the proposed Bolt versions' if server_reply.zero?
+
+          # An HTTP server on the Bolt port replies with an HTTP status
+          # line; its first four bytes spell "HTTP". Mirror Java's helpful
+          # error instead of reporting a bogus protocol version.
+          raise Exceptions::ClientException,
+                'Server responded HTTP. Make sure you are not trying to connect to the http ' \
+                'endpoint (HTTP defaults to port 7474 whereas BOLT defaults to port 7687)' if server_reply == HTTP_REPLY
+
+          server_reply == MANIFEST_SENTINEL ? negotiate_manifest : server_reply
+        end
+
+        private
+
+        # The manifest path: read the server's supported-version list
+        # and capabilities, pick the highest version we know, write
+        # back our choice + an empty-capabilities varlong.
+        def negotiate_manifest
+          count = read_varint
+          if count > MAX_MANIFEST_RANGES
+            raise Exceptions::ServiceUnavailableException,
+                  "Server's manifest range count #{count} exceeds the #{MAX_MANIFEST_RANGES} cap"
+          end
+
+          ranges = Array.new(count) { read_int32!('Connection closed mid-manifest while reading version ranges') }
+          read_varlong # server capabilities — consume but ignore (no caps requested)
+
+          chosen = pick_version(ranges)
+          unless chosen
+            # Tell the server we couldn't agree (4 bytes of zero +
+            # zero-varlong cap), then bail. Same shape as Java's
+            # ManifestHandlerV1 no-match path.
+            @socket.write([0].pack('L>'))
+            write_varlong(0)
+            @socket.flush
+            raise Exceptions::ServiceUnavailableException,
+                  "Server's manifest offered no Bolt version we support"
+          end
+
+          @socket.write([chosen.to_wire].pack('L>'))
+          # We don't request any capabilities yet (BoltCapability.FABRIC
+          # is the only one Java defines, and we don't use Fabric).
+          write_varlong(0)
+          @socket.flush
+
+          chosen.to_wire
+        end
+
+        # The server's version list comes as raw ints encoded
+        # `(minor_count << 16) | (minor << 8) | major`. Walk our
+        # preference list and pick the first that any advertised range
+        # covers.
+        def pick_version(ranges)
+          SUPPORTED_VERSIONS.find { |v| ranges.any? { |range_int| range_covers?(range_int, v) } }
+        end
+
+        def range_covers?(range_int, version)
+          major = range_int & 0xFF
+          top_minor = (range_int >> 8) & 0xFF
+          count = (range_int >> 16) & 0xFF
+          return false unless version.major == major
+
+          version.minor <= top_minor && version.minor >= top_minor - count
+        end
+
+        def read_int32
+          bytes = read_fully(4)
+          bytes ? bytes.unpack1('L>') : nil
+        end
+
+        # Read exactly n bytes, bounded by @deadline. Returns the bytes, or nil
+        # on EOF / deadline (callers turn nil into the right handshake error).
+        # wait_readable yields under a Fiber scheduler and times out on every
+        # Ruby (unlike read()+IO#timeout, which only times out on CRuby).
+        def read_fully(n)
+          buf = String.new(encoding: Encoding::BINARY)
+          while buf.bytesize < n
+            case (chunk = @socket.read_nonblock(n - buf.bytesize, exception: false))
+            when :wait_readable then (@socket.wait_readable(remaining_budget) || return)
+            when :wait_writable then (@socket.wait_writable(remaining_budget) || return)
+            when nil then return
+            else buf << chunk
+            end
+          end
+          buf
+        end
+
+        def remaining_budget
+          return nil unless @deadline
+
+          [@deadline - @clock.monotonic, 0.0].max
+        end
+
+        # Same as read_int32 but raises a ServiceUnavailableException
+        # on short read instead of returning nil. Use this whenever a
+        # nil result would propagate into bitmasks / arithmetic and
+        # crash with a less helpful TypeError downstream.
+        def read_int32!(message)
+          read_int32 || raise(Exceptions::ServiceUnavailableException, message)
+        end
+
+        # LEB128 unsigned varint / varlong. 7 data bits per byte, MSB
+        # is the continuation flag. Java caps at 9 bytes (63 usable
+        # bits) and so do we — anything wider is a malformed peer.
+        def read_varint
+          value = 0
+          shift = 0
+          9.times do
+            byte = read_fully(1)&.unpack1('C')
+            raise IOError, 'Unexpected end of stream while reading varint' if byte.nil?
+
+            value |= (byte & 0x7F) << shift
+            return value if byte & 0x80 == 0
+
+            shift += 7
+          end
+          raise Exceptions::ServiceUnavailableException, 'Varint overflow during handshake'
+        end
+        alias read_varlong read_varint
+
+        def write_varlong(value)
+          # do/while so zero still emits a single 0x00 byte (matches
+          # Java's writeVarLong).
+          loop do
+            byte = value & 0x7F
+            value >>= 7
+            if value.zero?
+              @socket.write([byte].pack('C'))
+              break
+            else
+              @socket.write([byte | 0x80].pack('C'))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/message/failure.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Message
+        # Failure response from Neo4j server.
+        #
+        # Two wire shapes, both handled by #to_exception:
+        #   * Legacy (pre-Bolt 5.7): { code:, message: }.
+        #   * GQL (Bolt 5.7+): { gql_status:, description:, message:, neo4j_code:,
+        #     diagnostic_record:, cause: } — `cause` nests the same shape.
+        # Since the driver speaks 5.7, a legacy failure is *synthesised* into the
+        # GQL shape (gql_status 50N42, default diagnostic record) so the exception
+        # exposes the same fields regardless of the server's protocol version —
+        # matching the Java driver's GqlStatusException behaviour.
+        class Failure
+          # Code-prefix → driver exception class. Order matters: more specific
+          # patterns must come first.
+          EXCEPTION_FOR_CODE = [
+            [%r{^Neo\.ClientError\.Security\.Unauthorized},         Exceptions::AuthenticationException],
+            [%r{^Neo\.ClientError\.Security\.AuthorizationExpired}, Exceptions::AuthorizationExpiredException],
+            [%r{^Neo\.ClientError\.Security\.TokenExpired},         Exceptions::TokenExpiredException],
+            [%r{^Neo\.ClientError\.Security},                       Exceptions::SecurityException],
+            [%r{^Neo\.ClientError\.Database\.DatabaseNotFound},     Exceptions::FatalDiscoveryException],
+            [%r{^Neo\.ClientError},                                 Exceptions::ClientException],
+            [%r{^Neo\.TransientError},                              Exceptions::TransientException],
+            [%r{^Neo\.DatabaseError},                               Exceptions::DatabaseException]
+          ].freeze
+
+          # Two `TransientError` codes the server may send that are actually
+          # non-retryable: the driver rewrites them to their `ClientError` form
+          # (so they map to a non-retryable ClientException, not a retryable
+          # TransientException) and surfaces the rewritten code. Mirrors the
+          # Java driver's ErrorUtil special-case; testkit's
+          # test_should_not_retry_non_retryable_tx_failures asserts both the
+          # rewritten code and that the managed-tx executor does not retry.
+          CODE_REWRITES = {
+            'Neo.TransientError.Transaction.Terminated' => 'Neo.ClientError.Transaction.Terminated',
+            'Neo.TransientError.Transaction.LockClientStopped' => 'Neo.ClientError.Transaction.LockClientStopped'
+          }.freeze
+
+          # GQL diagnostic-record keys the server may omit; filled with these
+          # defaults so the record is always complete (mirrors the Java driver).
+          DEFAULT_DIAGNOSTIC_RECORD = { OPERATION: '', OPERATION_CODE: '0', CURRENT_SCHEMA: '/' }.freeze
+
+          # Fallback GQL status for a legacy (non-GQL) failure: 50N42 =
+          # "general processing exception - unexpected error".
+          DEFAULT_GQL_STATUS = '50N42'
+          DEFAULT_STATUS_DESCRIPTION_PREFIX = 'error: general processing exception - unexpected error. '
+
+          # Diagnostic-record classifications the spec recognises; anything else
+          # (or absent) surfaces as the catch-all UNKNOWN.
+          KNOWN_CLASSIFICATIONS = %w[CLIENT_ERROR DATABASE_ERROR TRANSIENT_ERROR].freeze
+
+          attr_reader :metadata
+
+          def initialize(metadata)
+            @metadata = metadata
+          end
+
+          def code
+            @metadata[:neo4j_code] || @metadata[:code]
+          end
+
+          def message
+            @metadata[:message]
+          end
+
+          # Map this server FAILURE to its driver-side exception. Single owner of
+          # the code→exception logic — used to live in 4+ places.
+          def to_exception
+            gql?(@metadata) ? build_gql(@metadata) : build_legacy(@metadata)
+          end
+
+          def accept(visitor)
+            visitor.on_failure(self)
+          end
+
+          def assert_success!
+            raise to_exception
+          end
+
+          def terminal? = true
+
+          private
+
+          def gql?(meta) = meta.key?(:gql_status)
+
+          def exception_class(code)
+            (EXCEPTION_FOR_CODE.find { |pattern, _| code.to_s.match?(pattern) }&.last if code) ||
+              Exceptions::Neo4jException
+          end
+
+          # A handful of TransientError codes are non-retryable and surface
+          # under their ClientError code (see CODE_REWRITES).
+          def rewrite_code(code) = CODE_REWRITES[code] || code
+
+          # Bolt 5.7+ GQL failure: read the fields straight off the wire, fill the
+          # diagnostic-record defaults, and recurse into the cause chain.
+          def build_gql(meta)
+            diagnostic_record = fill_defaults(meta[:diagnostic_record])
+            raw_classification = diagnostic_record[:_classification]
+            raw_classification = nil unless raw_classification.is_a?(String)
+
+            code = rewrite_code(meta[:neo4j_code])
+            exception_class(code).new(
+              meta[:message],
+              code: code,
+              gql_status: meta[:gql_status],
+              status_description: meta[:description],
+              diagnostic_record: diagnostic_record,
+              raw_classification: raw_classification,
+              classification: (raw_classification if KNOWN_CLASSIFICATIONS.include?(raw_classification)),
+              gql_cause: meta[:cause] && build_gql(meta[:cause])
+            )
+          end
+
+          # Legacy { code:, message: } failure — synthesise the GQL shape so the
+          # exception carries the same fields a 5.7 server would have sent.
+          def build_legacy(meta)
+            code = rewrite_code(meta[:code])
+            exception_class(code).new(
+              meta[:message],
+              code: code,
+              gql_status: DEFAULT_GQL_STATUS,
+              status_description: "#{DEFAULT_STATUS_DESCRIPTION_PREFIX}#{meta[:message]}",
+              diagnostic_record: DEFAULT_DIAGNOSTIC_RECORD.dup
+            )
+          end
+
+          def fill_defaults(record)
+            DEFAULT_DIAGNOSTIC_RECORD.merge(record || {})
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/message/ignored.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Message
+        # Ignored response from Neo4j server (previous request was ignored)
+        class Ignored
+          def initialize(metadata = {})
+            @metadata = metadata
+          end
+
+          def accept(visitor)
+            visitor.on_ignored(self)
+          end
+
+          def assert_success!
+            raise Exceptions::ClientException,
+                  'Server IGNORED the request — a previous request in this batch failed'
+          end
+
+          def terminal? = true
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/message/record.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Message
+        # Record response from Neo4j server containing result data
+        class Record
+          attr_reader :fields
+
+          def initialize(fields)
+            @fields = fields
+          end
+
+          def accept(visitor)
+            visitor.on_record(self)
+          end
+
+          def assert_success!
+            raise Exceptions::ClientException, "Unexpected RECORD where SUCCESS was expected"
+          end
+
+          # A RECORD is a streamed row, not a request summary — it never
+          # completes the request, so it doesn't decrement the in-flight count.
+          def terminal? = false
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/message/success.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Message
+        # Success response from Neo4j server
+        class Success
+          attr_reader :metadata
+
+          def initialize(metadata = {})
+            @metadata = metadata
+          end
+
+          # Visitor double-dispatch: streaming consumers use this to avoid
+          # `case/when` on the response class.
+          def accept(visitor)
+            visitor.on_success(self)
+          end
+
+          # One-shot pattern: caller expects a SUCCESS, raises otherwise.
+          # Returns self so callers can chain `.metadata`.
+          def assert_success!
+            self
+          end
+
+          # A SUCCESS completes the request it answers — the connection uses
+          # this to tell summary responses apart from streamed RECORDs.
+          def terminal? = true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      # Bolt Protocol Messages
+      module Message
+        # Request messages (sent from client to server)
+        HELLO = 0x01
+        GOODBYE = 0x02
+        RESET = 0x0F
+        RUN = 0x10
+        BEGIN_TX = 0x11
+        COMMIT = 0x12
+        ROLLBACK = 0x13
+        PULL = 0x3F
+        DISCARD = 0x2F
+        ROUTE = 0x66
+        LOGON = 0x6A
+        LOGOFF = 0x6B
+        TELEMETRY = 0x54
+
+        # Response messages (sent from server to client)
+        SUCCESS = 0x70
+        RECORD = 0x71
+        IGNORED = 0x7E
+        FAILURE = 0x7F
+
+        class << self
+          # Note: HELLO message building is now handled by protocol-specific handlers
+          # This method kept for backward compatibility but shouldn't be used directly
+          def hello(user_agent:, auth:, routing: nil)
+            extra = { user_agent: user_agent }
+            extra[:routing] = routing if routing
+            # Default to Bolt 5.0+ format (merged auth)
+            extra.merge!(auth) if auth
+            PackStream::Structure.new(HELLO, [extra])
+          end
+
+          def run(query, parameters = {}, extra = {})
+            PackStream::Structure.new(RUN, [query, parameters, extra])
+          end
+
+          def begin_transaction(extra = {})
+            PackStream::Structure.new(BEGIN_TX, [extra])
+          end
+
+          def commit
+            PackStream::Structure.new(COMMIT, [])
+          end
+
+          def rollback
+            PackStream::Structure.new(ROLLBACK, [])
+          end
+
+          # Caller must specify n explicitly — Java/Python default is 1000
+          # records per batch but the call site (Session/Transaction) knows
+          # the configured fetch_size and passes it through. Default-here
+          # would silently mask "forgot to plumb fetch_size".
+          def pull(extra = {})
+            PackStream::Structure.new(PULL, [extra])
+          end
+
+          def discard(extra = {})
+            extra = { n: -1 }.merge(extra)
+            PackStream::Structure.new(DISCARD, [extra])
+          end
+
+          # Bolt 5.4+ TELEMETRY: reports which driver API opened the coming
+          # transaction/query (0 tx-function, 1 unmanaged tx, 2 auto-commit,
+          # 3 execute_query). Sent only when the server advertised
+          # `telemetry.enabled` and the driver didn't disable it.
+          def telemetry(api)
+            PackStream::Structure.new(TELEMETRY, [api])
+          end
+
+          def reset
+            PackStream::Structure.new(RESET, [])
+          end
+
+          def goodbye
+            PackStream::Structure.new(GOODBYE, [])
+          end
+
+          # LOGON (Bolt 5.1+). Carries the auth fields that 5.0 used to
+          # send inside HELLO. The server's success here marks the
+          # connection authenticated and READY.
+          def logon(auth)
+            PackStream::Structure.new(LOGON, [auth || {}])
+          end
+
+          # LOGOFF (Bolt 5.1+). De-authenticates the connection; the
+          # next LOGON re-authenticates with a possibly-different
+          # token. Used by per-session auth (`driver.session(auth: …)`)
+          # to switch identity on a pooled connection without tearing
+          # it down.
+          def logoff
+            PackStream::Structure.new(LOGOFF, [])
+          end
+
+          # ROUTE (Bolt 4.3+) — fetch the cluster's routing table.
+          #   routing_context  : map (typically built from the URI query string)
+          #   bookmarks        : list of bookmarks (or nil for Bolt 4.3 compat)
+          #   extra            : {db: <database or nil>, imp_user: <or nil>}
+          def route(routing_context, bookmarks, extra)
+            PackStream::Structure.new(ROUTE, [routing_context, bookmarks, extra])
+          end
+        end
+      end
+    end
+  end
+end