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

data/lib/neo4j/driver/bolt/protocol/v57.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 5.7. FAILURE switches to a GQL-flavoured map: the legacy
+        # `code` key is renamed to `neo4j_code` (optional, defaults to
+        # "N/A"), and new keys appear (`gql_status`, `description`,
+        # `diagnostic_record`, recursive `cause`). The driver's
+        # exception classifier keys off `:code`, so we alias
+        # `neo4j_code → code` here. The other GQL fields ride along in
+        # the metadata for any caller that wants them.
+        #
+        # 5.7+ is also where HandshakeManifestV1 negotiation becomes
+        # mandatory on the server side; that's handled in Bolt::Handshake,
+        # not here.
+        class V57 < V56
+          def customize_hydration(unpacker)
+            super
+            unpacker.register_hydration_handler(Message::FAILURE) do |fields|
+              meta = fields[0] || {}
+              meta = meta.merge(code: meta[:neo4j_code]) if meta[:neo4j_code]
+              Message::Failure.new(meta)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v58.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 5.8. Wire-identical to 5.7 from the client's perspective;
+        # the version bump only flags additional server capabilities
+        # negotiated through the manifest's capabilities bitmask.
+        class V58 < V57
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v6.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 6.0. HELLO / LOGON / TELEMETRY shapes are unchanged vs
+        # 5.8; the major bump exists to (a) gate the manifest as the
+        # only supported negotiation path and (b) introduce two new
+        # server-pushed struct types in result records:
+        #   - VECTOR     0x56 — packed numeric array; 2 fields
+        #                       (element-type byte, raw bytes).
+        #   - UNSUPPORTED 0x3F — forward-compat marker; 4 fields
+        #                       (name, min_major, min_minor, extra-map whose
+        #                       optional `message` key carries a server note).
+        #
+        # UNSUPPORTED hydrates to Types::UnsupportedType (Feature:API:Type.
+        # UnsupportedType). VECTOR stays a plain hash — Feature:API:Type.Vector
+        # is unimplemented, so the goal there is still just "don't crash at
+        # hydration" until there's a public API to wire it to.
+        class V6 < V58
+          VECTOR_SIGNATURE = 0x56
+          UNSUPPORTED_SIGNATURE = 0x3F
+
+          def customize_hydration(unpacker)
+            super
+            unpacker.register_hydration_handler(VECTOR_SIGNATURE) do |fields|
+              { element_type: fields[0], bytes: fields[1] }
+            end
+            unpacker.register_hydration_handler(UNSUPPORTED_SIGNATURE) do |fields|
+              # fields[3] is an extra map (symbol keys) whose :message is the
+              # optional server note. Guard the type so a malformed/absent
+              # 4th field can't crash hydration — the whole point of a
+              # forward-compat marker is to survive the unexpected.
+              extra = fields[3].is_a?(Hash) ? fields[3] : {}
+              Types::UnsupportedType.new(fields[0], fields[1], fields[2], extra[:message])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v61.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 6.1. HELLO / LOGON shapes are unchanged vs 6.0; the minor bump
+        # introduces PackStream V2, whose only new type is UUID — a top-level
+        # value (marker 0xE0 + 16 raw bytes), not a struct. This is the one
+        # protocol version that supports it: pack/unpack the UUID codec here
+        # instead of raising like Protocol::Base (Feature:API:Type.UUID,
+        # Feature:Bolt:6.1).
+        class V61 < V6
+          def pack_uuid(packer, value) = packer.pack_uuid_value(value)
+
+          def unpack_uuid(unpacker) = unpacker.unpack_uuid_value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      # Factory for the per-minor protocol handler matching the
+      # negotiated wire version. Lookup is exact (`major.minor`)
+      # because the Bolt handshake only ever returns a version the
+      # server actually supports — so we don't need fuzzy matching.
+      class ProtocolVersionHandler
+        HANDLERS = {
+          BoltVersion::V6_1.to_i => Protocol::V61,
+          BoltVersion::V6_0.to_i => Protocol::V6,
+          BoltVersion::V5_8.to_i => Protocol::V58,
+          BoltVersion::V5_7.to_i => Protocol::V57,
+          BoltVersion::V5_6.to_i => Protocol::V56,
+          BoltVersion::V5_5.to_i => Protocol::V55,
+          BoltVersion::V5_4.to_i => Protocol::V54,
+          BoltVersion::V5_3.to_i => Protocol::V53,
+          BoltVersion::V5_2.to_i => Protocol::V52,
+          BoltVersion::V5_1.to_i => Protocol::V51,
+          BoltVersion::V5_0.to_i => Protocol::V5,
+          BoltVersion::V4_4.to_i => Protocol::V44,
+          BoltVersion::V4_3.to_i => Protocol::V43,
+          BoltVersion::V4_2.to_i => Protocol::V4,
+          BoltVersion::V3_0.to_i => Protocol::V3
+        }.freeze
+
+        def self.for_version(connection, version_int)
+          version = BoltVersion.from_int(version_int)
+          klass = HANDLERS[version.to_i] ||
+                  raise(Exceptions::ServiceUnavailableException,
+                        "Unsupported Bolt protocol version: #{version}")
+          klass.new(connection, version)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      # Record buffer for one streaming result, with a high/low watermark autopull
+      # policy. Sits between the connection's reader (producer) and the cursor
+      # (consumer), and unifies two things under one mutex + condition variable:
+      # the record queue *and* the batch's "has_more promise".
+      #
+      # Records are delivered incrementally — pushed the instant the reader decodes
+      # them — so the cursor sees record 1 without waiting for the whole batch. The
+      # batch's terminating SUCCESS resolves the promise (`batch_complete`), which
+      # says whether the server has more. The cursor drives flow control:
+      #
+      #   * after each record, once drained to/below the low watermark, it checks
+      #     the promise (`pull_ready?`, non-blocking) and, if fulfilled with
+      #     has_more, issues the next `PULL {n: fetch_size}` — prefetch overlap;
+      #   * when it drains the buffer empty mid-stream, it `await`s — one wait that
+      #     wakes on *either* the next record *or* the promise resolving. That
+      #     shared wait is the crux: mid-batch it wakes on a record (incremental
+      #     delivery preserved), at batch-end it wakes on the promise (so it PULLs
+      #     the next batch instead of blocking forever on a record that, the SUCCESS
+      #     having no payload, will never come).
+      #
+      # The cursor is the sole writer (issues every PULL/DISCARD); the reader only
+      # ever fills. All sync primitives are stdlib + scheduler-aware, so a cursor
+      # running as a fiber under a host reactor yields rather than blocking the
+      # thread. See docs/unified-pipeline.md.
+      class RecordBuffer
+        attr_reader :fetch_size, :high_watermark, :low_watermark
+
+        def initialize(fetch_size:, high_watermark: nil, low_watermark: nil)
+          @fetch_size = fetch_size
+          # Defaults: refill under half of ~2 batches held. fetch_size -1 ("pull
+          # all in one batch") never paginates, so just size the watermarks for a
+          # steady single-batch handoff.
+          @high_watermark = high_watermark || (fetch_size.positive? ? fetch_size * 2 : 1000)
+          @low_watermark = low_watermark || [@high_watermark / 2, 1].max
+          @mutex = Mutex.new
+          @cv = ConditionVariable.new
+          @records = [] # incrementally filled by the reader, drained by the cursor
+          @has_more = true # server may have more records for this stream
+          @pull_in_flight = true # the first PULL is pipelined with RUN — promise unfulfilled
+          @ended = false # terminal SUCCESS/IGNORED seen → no more records
+          @error = nil # stream failed; re-raised to the cursor after buffered records
+          @summary = nil # terminating SUCCESS metadata
+        end
+
+        # --- Producer (reader) side -----------------------------------------
+
+        # Append a decoded record and wake a cursor parked in #await. Never blocks
+        # (unbounded); the cursor's watermark bounds how much the server ships.
+        def push_record(record)
+          @mutex.synchronize do
+            @records.push(record)
+            @cv.broadcast
+          end
+        end
+
+        # The current batch's terminal SUCCESS arrived — resolve the promise.
+        # `has_more` says whether to keep paging; either way no PULL is in flight,
+        # so the cursor may issue the next once it drains past the low watermark.
+        # Wake a cursor parked in #await waiting for exactly this.
+        def batch_complete(has_more:)
+          @mutex.synchronize do
+            @has_more = has_more
+            @pull_in_flight = false
+            @cv.broadcast
+          end
+        end
+
+        # Final batch (terminating SUCCESS without has_more, or IGNORED): stash the
+        # summary, mark ended, and wake the cursor.
+        def finish(summary = nil)
+          @mutex.synchronize do
+            @summary = summary
+            @ended = true
+            @has_more = false
+            @pull_in_flight = false
+            @cv.broadcast
+          end
+        end
+
+        # The stream failed: arm the error the cursor re-raises *after* it drains
+        # the records already delivered (records that preceded the failure are
+        # valid), and wake it.
+        def fail(error)
+          @mutex.synchronize do
+            @error ||= error
+            @ended = true
+            @has_more = false
+            @pull_in_flight = false
+            @cv.broadcast
+          end
+        end
+
+        # The terminating SUCCESS's metadata (nil until finished / on failure).
+        def summary = @mutex.synchronize { @summary }
+
+        # --- Consumer (cursor) side -----------------------------------------
+
+        # Non-blocking: the next buffered record, or :empty when none is buffered
+        # yet, or :ended once the stream is drained and terminal. Buffered records
+        # are handed out before a stream failure is raised (they preceded it).
+        def try_shift
+          @mutex.synchronize do
+            return @records.shift unless @records.empty?
+            raise @error if @error
+
+            @ended ? :ended : :empty
+          end
+        end
+
+        # Block (colorlessly) until there's something to re-evaluate: a record was
+        # delivered, the batch completed (promise resolved), or the stream
+        # ended/failed. Called only when the cursor has drained the buffer empty
+        # and a PULL is still outstanding (records coming, or its SUCCESS pending).
+        def await
+          @mutex.synchronize do
+            @cv.wait(@mutex) while @records.empty? && !@ended && @error.nil? && @pull_in_flight
+          end
+        end
+
+        def empty? = @mutex.synchronize { @records.empty? }
+        def size = @mutex.synchronize { @records.size }
+        def ended? = @mutex.synchronize { @ended }
+        def has_more? = @mutex.synchronize { @has_more }
+
+        # --- Autopull policy (cursor side) ----------------------------------
+
+        # True when the cursor should issue the next PULL: the batch promise is
+        # fulfilled (none in flight) with has_more, and the buffer has drained
+        # to/below the low watermark.
+        def pull_ready? = @mutex.synchronize { @has_more && !@pull_in_flight && @records.size <= @low_watermark }
+
+        # The cursor issued the next PULL — the promise is unfulfilled again; don't
+        # issue another until this batch completes.
+        def note_pull_issued = @mutex.synchronize { @pull_in_flight = true }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      # The wire handler for a streaming PULL/DISCARD: the dedicated reader routes
+      # the result's replies here, and it fills the result's RecordBuffer.
+      #
+      # Records are forwarded to the buffer incrementally — the instant each is
+      # decoded — so the cursor can read record 1 without waiting for the whole
+      # batch. The batch's terminating SUCCESS resolves the buffer's has_more
+      # promise (batch_complete) or ends the stream (finish); a FAILURE/IGNORED
+      # ends it too. The cursor consumes the buffer and drives follow-up PULLs —
+      # this side only fills.
+      #
+      # Runs in the reader thread; same visitor interface as @collector, so the
+      # wire dispatches to it identically.
+      class StreamHandler
+        def initialize(buffer)
+          @buffer = buffer
+        end
+
+        def on_record(message)
+          @buffer.push_record(message)
+        end
+
+        def on_success(message)
+          if message.metadata[:has_more]
+            @buffer.batch_complete(has_more: true)
+          else
+            @buffer.finish(message.metadata)
+          end
+        end
+
+        def on_failure(message)
+          # Records already delivered stay readable; the cursor hits this error
+          # once it drains them (records that preceded the failure are valid).
+          @buffer.fail(message.to_exception)
+        end
+
+        def on_ignored(_message)
+          @buffer.finish
+        end
+
+        # Connection failure fan-out (see Connection#fan_out / Wire#fail_pending):
+        # surface the error to a cursor parked in the buffer.
+        def fail(error)
+          @buffer.fail(error)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      # Resolves the driver's URI scheme + user options into an
+      # OpenSSL::SSL::SSLContext, or nil for plaintext. Mirrors Java's
+      # TrustStrategy modes:
+      #
+      #   :system_certificates  — verify cert chain against system roots
+      #                            + verify hostname. Default for +s schemes.
+      #   :all_certificates     — encrypted but skip both checks. Default
+      #                            for +ssc schemes. Useful for self-signed
+      #                            dev servers; not for production.
+      #   :custom_certificates  — verify against an explicit CA bundle.
+      #
+      # Hostname verification rides along with peer verification — turning
+      # peer verification off (:all_certificates) implicitly turns off
+      # hostname check too, which is why +ssc exists.
+      class TlsConfig
+        # +s / +ssc are scheme-level encryption opt-in (mirrors
+        # Driver::ENCRYPTED_SCHEMES). +ssc additionally implies
+        # trust-all — the whole point of the "self-signed" suffix.
+        ENCRYPTED_SCHEMES = Driver::ENCRYPTED_SCHEMES
+        TRUST_ALL_SCHEMES = %w[bolt+ssc neo4j+ssc].freeze
+
+        def initialize(uri:, options:)
+          @uri = uri
+          @options = options
+        end
+
+        # nil ⇒ plaintext socket; SSLContext ⇒ wrap.
+        def ssl_context
+          return nil unless encrypted?
+
+          ctx = OpenSSL::SSL::SSLContext.new
+          ctx.min_version = OpenSSL::SSL::TLS1_2_VERSION
+          apply_trust(ctx)
+          apply_client_certificate(ctx)
+          ctx
+        end
+
+        def encrypted?
+          ENCRYPTED_SCHEMES.include?(@uri.scheme) || @options[:encryption] == true
+        end
+
+        # Whether the SSLSocket should verify the server hostname after
+        # the TLS handshake. False for the trust-all path; true otherwise.
+        def verify_hostname?
+          encrypted? && resolved_strategy != :all_certificates
+        end
+
+        private
+
+        # Mutual TLS (Feature:API:SSLClientCertificate): present the client
+        # certificate the manager currently holds. Polled per connection so a
+        # rotated certificate takes effect on the next connect; nil manager or
+        # nil certificate leaves the context client-cert-free.
+        def apply_client_certificate(ctx)
+          certificate = @options[:client_certificate_manager]&.get_client_certificate
+          return unless certificate
+
+          ctx.cert = OpenSSL::X509::Certificate.new(File.read(certificate.certfile))
+          # PKey.read handles both encrypted (password used) and unencrypted
+          # (password ignored) PEM keys. Pass "" rather than nil for a missing
+          # password so an encrypted key raises PKeyError instead of blocking
+          # the thread on OpenSSL's interactive stdin passphrase prompt.
+          ctx.key = OpenSSL::PKey.read(File.read(certificate.keyfile), certificate.password || '')
+        end
+
+        def apply_trust(ctx)
+          case resolved_strategy
+          when :all_certificates
+            ctx.verify_mode = OpenSSL::SSL::VERIFY_NONE
+          when :custom_certificates
+            ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
+            ctx.cert_store = custom_cert_store
+          else # :system_certificates
+            ctx.verify_mode = OpenSSL::SSL::VERIFY_PEER
+            ctx.cert_store = OpenSSL::X509::Store.new.tap(&:set_default_paths)
+          end
+        end
+
+        # Custom-trust mode without any `cert_files` paths would produce
+        # a VERIFY_PEER context with an empty store — every connection
+        # would fail with an opaque OpenSSL error. Catch this at config
+        # time with a clear message instead.
+        def custom_cert_store
+          paths = cert_files
+          if paths.empty?
+            raise ArgumentError,
+                  'trust_strategy :trust_custom_certificates requires at least one path in :cert_files'
+          end
+
+          paths.each_with_object(OpenSSL::X509::Store.new) do |path, store|
+            store.add_file(path)
+          end
+        end
+
+        # Resolves trust-strategy option → internal symbol. Falls back
+        # to the URI-implied default (+ssc → all-certs, anything else
+        # → system-certs) when no explicit option was given.
+        def resolved_strategy
+          return uri_default unless explicit_strategy
+
+          case explicit_strategy
+          when :trust_system_certificates then :system_certificates
+          when :trust_all_certificates then :all_certificates
+          when :trust_custom_certificates then :custom_certificates
+          else
+            raise ArgumentError, "Unknown trust_strategy: #{explicit_strategy.inspect}"
+          end
+        end
+
+        def uri_default
+          TRUST_ALL_SCHEMES.include?(@uri.scheme) ? :all_certificates : :system_certificates
+        end
+
+        def explicit_strategy
+          @options.dig(:trust_strategy, :strategy)
+        end
+
+        def cert_files
+          Array(@options.dig(:trust_strategy, :cert_files))
+        end
+      end
+    end
+  end
+end