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

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

@@ -0,0 +1,321 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      # Sans-I/O Bolt protocol core: a pure state machine with **no socket**.
+      #
+      #   * `enqueue(message)` packs + chunk-frames a request into an outbound
+      #     byte buffer; `take_outbound` hands those bytes to whoever owns the
+      #     socket.
+      #   * `receive(bytes)` feeds inbound bytes and returns the complete
+      #     messages now decodable (Success / Failure / Record / Ignored), in
+      #     order — reassembling chunks across calls, skipping NOOP keepalives,
+      #     and retaining any trailing partial bytes for the next call.
+      #
+      # Because it never touches a socket, the whole Bolt framing + hydration
+      # path is unit-testable without a network, and stays identical regardless
+      # of how I/O is driven (blocking thread, fiber pump, on-demand). See
+      # docs/sans-io-pump.md.
+      #
+      # Created after the handshake — it needs the negotiated protocol to
+      # configure the packer (UTC datetime flag) and to customise hydration for
+      # version-specific message shapes.
+      class Wire
+        # Bolt message chunking: a message is a sequence of `[u16 size][size
+        # bytes]` chunks terminated by a zero-size chunk (the 0x00 0x00 end
+        # marker). A bare end marker with no preceding chunks is a NOOP — an
+        # inline keepalive the server sends to keep a slow response under the
+        # recv-timeout; it carries no message.
+        END_MARKER = "\x00\x00".b
+        MAX_CHUNK = 65_535
+
+        def initialize(protocol)
+          @protocol = protocol
+          @packer = PackStream::Packer.new(@protocol)
+          @protocol.configure_packer(@packer)
+          @outbound = binary_string # consumer-only (enqueue/take_outbound)
+          @inbound = binary_string # reader-only: received bytes not yet parsed
+          @message = binary_string # reader-only: chunks of the in-progress message
+          # Response-ordering FIFO. Bolt replies in request order, so each sent
+          # request pushes the handler that will receive its response(s); the
+          # front handler always owns the next reply. A handler is any response
+          # visitor (responds to on_record/on_success/on_failure/on_ignored —
+          # the same interface Message#accept dispatches to).
+          #
+          # This FIFO is the one piece of wire state touched by two threads: the
+          # consumer pushes (enqueue) while the dedicated reader shifts/dispatches
+          # (receive) and may clear it on failure (fail_pending). @mutex serialises
+          # those — without it JRuby (no GVL) races the Array and loses handlers,
+          # which strands a consumer parked on a buffer that never fills. Handler
+          # delivery is non-blocking (records/replies land on unbounded queues —
+          # flow control is the cursor's watermark, not a bounded buffer), so
+          # dispatching under the lock can't stall the reader.
+          @handlers = []
+          @mutex = Mutex.new
+        end
+
+        # Switch datetime packing to UTC-seconds (0x49/0x69). Connection calls
+        # this when the Bolt 4.3/4.4 HELLO confirms `patch_bolt: ["utc"]`; on
+        # 5.0+ configure_packer already set it, so this only fires on 4.x.
+        def enable_utc_datetime = @packer.use_utc_datetime = true
+
+        # Pack + chunk-frame `message` into the outbound buffer and register the
+        # handler for its reply. Several enqueues before a take_outbound are
+        # exactly the pipelining Bolt expects (HELLO+LOGON, RUN+PULL); the FIFO
+        # keeps each request matched to its response.
+        def enqueue(message, handler)
+          @packer.reset
+          @packer.pack_message(message)
+          data = @packer.bytes
+
+          offset = 0
+          while offset < data.bytesize
+            size = [data.bytesize - offset, MAX_CHUNK].min
+            @outbound << [size].pack('S>') << data.byteslice(offset, size)
+            offset += size
+          end
+          @outbound << END_MARKER
+          @mutex.synchronize { @handlers.push(handler) }
+          self
+        end
+
+        def pending_outbound? = !@outbound.empty?
+
+        # Requests still awaiting their terminal reply.
+        def in_flight = @mutex.synchronize { @handlers.size }
+
+        # Hand over (and clear) the framed bytes to write to the socket.
+        def take_outbound
+          out = @outbound
+          @outbound = binary_string
+          out
+        end
+
+        # Feed inbound bytes and route each fully-decoded message to the front
+        # handler (via its own #accept visitor). A RECORD keeps the handler at
+        # the front (one request streams many); a terminal (SUCCESS/FAILURE/
+        # IGNORED) completes the request and pops it. NOOP keepalives carry no
+        # message and are skipped. Partial bytes are retained for the next call.
+        def receive(bytes)
+          @inbound << bytes
+          # @inbound/@message/next_message are reader-only; only the @handlers
+          # touch needs the lock. Dispatch (accept) happens under it too — that's
+          # safe because delivery is non-blocking — and shifting after accept keeps
+          # in_flight from hitting zero until the terminal has actually been
+          # delivered (the quiescence contract reset!/drain_quiesced rely on).
+          @mutex.synchronize do
+            while (message = next_message)
+              next if message == :noop || @handlers.empty?
+
+              message.accept(@handlers.first)
+              @handlers.shift if message.terminal?
+            end
+          end
+        end
+
+        # Connection failure fan-out: tell every outstanding request's handler
+        # the connection died, so a consumer parked on that handler's buffer
+        # (or completion) wakes and re-raises rather than hanging. Drops them
+        # from the FIFO — the wire is done.
+        def fail_pending(error)
+          @mutex.synchronize do
+            @handlers.each { |handler| handler.fail(error) }
+            @handlers.clear
+          end
+        end
+
+        private
+
+        # Pull one complete message off the front of @inbound, or nil if more
+        # bytes are needed. Reassembles all of a message's chunks; returns
+        # :noop for a bare end marker. Consumes only what it fully parses.
+        def next_message
+          consumed = 0
+          loop do
+            return retain(consumed) if @inbound.bytesize - consumed < 2
+
+            size = @inbound.byteslice(consumed, 2).unpack1('S>')
+            consumed += 2
+
+            if size.zero? # end marker
+              if @message.empty?
+                advance(consumed)
+                return :noop
+              end
+              advance(consumed)
+              return unpack(take_message)
+            end
+
+            return retain(consumed - 2) if @inbound.bytesize - consumed < size
+
+            @message << @inbound.byteslice(consumed, size)
+            consumed += size
+          end
+        end
+
+        # Not enough bytes for the next chunk: drop what we've consumed so far
+        # (its chunks are already accumulated in @message) and signal "need
+        # more" with nil.
+        def retain(consumed)
+          advance(consumed)
+          nil
+        end
+
+        def advance(consumed)
+          return if consumed.zero?
+
+          @inbound = @inbound.byteslice(consumed..) || binary_string
+        end
+
+        def take_message
+          data = @message
+          @message = binary_string
+          data
+        end
+
+        def unpack(data)
+          unpacker = PackStream::Unpacker.new(StringIO.new(data), @protocol)
+          register_hydration_handlers(unpacker)
+          unpacker.unpack
+        end
+
+        def binary_string = String.new(encoding: Encoding::BINARY)
+
+        # --- Hydration (owned by the core; identical to the legacy path) -----
+
+        def register_hydration_handlers(unpacker)
+          unpacker.register_hydration_handler(Message::SUCCESS) { |fields| Message::Success.new(fields[0] || {}) }
+          unpacker.register_hydration_handler(Message::FAILURE) { |fields| Message::Failure.new(fields[0] || {}) }
+          unpacker.register_hydration_handler(Message::RECORD) { |fields| Message::Record.new(fields[0] || []) }
+          unpacker.register_hydration_handler(Message::IGNORED) { |_| Message::Ignored.new }
+
+          # Signature 0x4E - Node
+          unpacker.register_hydration_handler(0x4E) do |fields|
+            Types::Node.new(fields[0], fields[1].map(&:to_sym), fields[2], fields[3])
+          end
+
+          # Signature 0x52 - Relationship (bound). Bolt 5.0+ adds
+          # startNodeElementId/endNodeElementId as fields[6]/fields[7].
+          unpacker.register_hydration_handler(0x52) do |fields|
+            Types::Relationship.new(fields[0], fields[1], fields[2], fields[3].to_sym,
+                                    fields[4], fields[5], fields[6], fields[7])
+          end
+
+          # Signature 0x72 - UnboundRelationship. Bolt 5.0+ adds elementId.
+          unpacker.register_hydration_handler(0x72) do |fields|
+            Types::UnboundRelationship.new(fields[0], fields[1].to_sym, fields[2], fields[3])
+          end
+
+          # Signature 0x50 - Path
+          unpacker.register_hydration_handler(0x50) do |fields|
+            nodes = fields[0]
+            unbound_rels = fields[1]
+            indices = fields[2]
+
+            segments = []
+            bound_rels = []
+            current_node = nodes.first
+
+            indices.each_slice(2) do |rel_idx, node_idx|
+              next_node = nodes[node_idx]
+
+              if rel_idx < 0
+                unbound_rel = unbound_rels[rel_idx.abs - 1]
+                bound_rel = unbound_rel.bind(next_node.id, current_node.id,
+                                             next_node.element_id, current_node.element_id)
+              else
+                unbound_rel = unbound_rels[rel_idx - 1]
+                bound_rel = unbound_rel.bind(current_node.id, next_node.id,
+                                             current_node.element_id, next_node.element_id)
+              end
+              segments << Types::Path::Segment.new(current_node, next_node, bound_rel)
+
+              bound_rels << bound_rel
+              current_node = next_node
+            end
+
+            Types::Path.new(nodes, bound_rels, segments)
+          end
+
+          register_temporal_handlers(unpacker)
+
+          # Version-specific re-registration (V5_7 FAILURE, V6_0 VECTOR /
+          # UNSUPPORTED) wins, so it runs last.
+          @protocol&.customize_hydration(unpacker)
+        end
+
+        def register_temporal_handlers(unpacker)
+          # Date (0x44) → ::Date
+          unpacker.register_hydration_handler(0x44) { |fields| ::Date.new(1970, 1, 1) + fields[0] }
+          # OffsetTime (0x54)
+          unpacker.register_hydration_handler(0x54) { |fields| Types::OffsetTime.from_nanos(fields[0], fields[1]) }
+          # LocalTime (0x74)
+          unpacker.register_hydration_handler(0x74) { |fields| Types::LocalTime.from_nanos(fields[0]) }
+          # DateTime with offset, legacy LOCAL seconds (0x46): subtract offset.
+          unpacker.register_hydration_handler(0x46) do |fields|
+            ::Time.at(fields[0] - fields[2], fields[1], :nanosecond).getlocal(fields[2])
+          end
+          # DateTime with offset, UTC seconds (0x49, Bolt 5.0+).
+          unpacker.register_hydration_handler(0x49) do |fields|
+            ::Time.at(fields[0], fields[1], :nanosecond).getlocal(fields[2])
+          end
+          # LocalDateTime (0x64)
+          unpacker.register_hydration_handler(0x64) { |fields| Types::LocalDateTime.from_epoch(fields[0], fields[1]) }
+          # DateTimeZoneId, legacy LOCAL seconds (0x66).
+          unpacker.register_hydration_handler(0x66) do |fields|
+            wall_clock = ::Time.at(fields[0], fields[1], :nanosecond).utc
+            hydrate_named_zone(wall_clock, fields[2], local_seconds: true)
+          end
+          # DateTimeZoneId, UTC seconds (0x69, Bolt 5.0+).
+          unpacker.register_hydration_handler(0x69) do |fields|
+            utc_instant = ::Time.at(fields[0], fields[1], :nanosecond).utc
+            hydrate_named_zone(utc_instant, fields[2], local_seconds: false)
+          end
+          # Duration (0x45)
+          unpacker.register_hydration_handler(0x45) { |fields| Types::Duration.new(fields[0], fields[1], fields[2], fields[3]) }
+          # Point2D (0x58)
+          unpacker.register_hydration_handler(0x58) { |fields| Types::Point.new(srid: fields[0], x: fields[1], y: fields[2]) }
+          # Point3D (0x59)
+          unpacker.register_hydration_handler(0x59) do |fields|
+            Types::Point.new(srid: fields[0], x: fields[1], y: fields[2], z: fields[3])
+          end
+        end
+
+        # See CLAUDE.md "LOCAL seconds encoding". Both 0x66 (legacy local) and
+        # 0x69 (UTC) resolve a named tz at an instant; the only difference is
+        # whether the caller already has the UTC instant.
+        def hydrate_named_zone(instant, zone_name, local_seconds:)
+          if defined?(ActiveSupport::TimeZone)
+            tz = ActiveSupport::TimeZone[zone_name]
+            # A nil lookup is an unknown zone id — defer it (see below).
+            return unresolvable_zone(zone_name) if tz.nil?
+
+            utc_instant = local_seconds ? tz.tzinfo.local_to_utc(instant) : instant
+            tz.at(utc_instant)
+          else
+            tz = TZInfo::Timezone.get(zone_name) # raises InvalidTimezoneIdentifier if unknown
+            utc_instant = local_seconds ? tz.local_to_utc(instant) : instant
+            utc_instant.getlocal(tz.period_for_utc(utc_instant).utc_total_offset)
+          end
+        rescue TZInfo::InvalidTimezoneIdentifier
+          unresolvable_zone(zone_name)
+        rescue StandardError
+          # The zone id IS known, but the local->UTC mapping failed (a DST gap /
+          # overlap: TZInfo::PeriodNotFound / AmbiguousTime, or similar). Keep
+          # the prior lenient fallback — returning the raw instant — rather than
+          # misreport it as an unknown zone.
+          instant
+        end
+
+        # Placeholder for a zone id this runtime's tz database doesn't know (the
+        # server sent a name we can't resolve). We're on the reader thread
+        # mid-record; raising here would break the connection and strand the
+        # whole result, so defer it — the value raises (naming the zone) only
+        # when a consumer uses it, leaving the record + connection intact so an
+        # open transaction can still roll back.
+        def unresolvable_zone(zone_name) = Types::UnresolvableZonedDateTime.new(zone_name)
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bookmark.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Bookmark for transaction causality
+    class Bookmark < String
+      # Compatibility alias with jruby driver (which wraps java driver)
+      alias value itself
+
+      class << self
+        alias from new
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bookmark_managers.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Factory for the driver's default BookmarkManager. Mirrors
+    # `org.neo4j.driver.BookmarkManagers#defaultManager` — but with a
+    # Ruby keyword-arg surface instead of a config builder, matching
+    # the JRuby flavour's ext shim (lib/jruby/.../ext/bookmark_managers.rb).
+    #
+    # The returned object is duck-typed: any value responding to
+    #
+    #   bookmarks                                  -> Set<Bookmark>
+    #   update_bookmarks(previous, new)            -> void
+    #
+    # is a manager. Pass your own instance to `Driver#session` or
+    # `Driver#execute_query` via `:bookmark_manager` if you want a
+    # store backed by something other than the in-memory default
+    # (e.g. Redis); no inheritance or interface declaration needed.
+    #
+    # `initial_bookmarks`  — seed the manager with bookmarks the caller
+    #                         already has (e.g. from a persisted store).
+    # `bookmarks_supplier` — callable returning extra bookmarks to merge
+    #                         into every `bookmarks` call (lets external
+    #                         bookmark sources participate without being
+    #                         folded into the manager's own state).
+    # `bookmarks_consumer` — callable receiving the new bookmark snapshot
+    #                         after every successful update (lets external
+    #                         observers persist or forward bookmarks).
+    module BookmarkManagers
+      def self.default_manager(initial_bookmarks: nil, bookmarks_supplier: nil, bookmarks_consumer: nil)
+        Internal::DefaultBookmarkManager.new(
+          initial_bookmarks:,
+          bookmarks_supplier:,
+          bookmarks_consumer:
+        )
+      end
+    end
+  end
+end

data/lib/neo4j/driver/client_certificate.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # A client certificate for mutual TLS (Feature:API:SSLClientCertificate):
+    # the certificate PEM file, its private-key PEM file, and the key's
+    # optional password. Built via ClientCertificates.of and served by a
+    # ClientCertificateManager. Mirrors org.neo4j.driver.ClientCertificate.
+    class ClientCertificate
+      attr_reader :certfile, :keyfile, :password
+
+      def initialize(certfile, keyfile, password = nil)
+        @certfile = certfile
+        @keyfile = keyfile
+        @password = password
+      end
+    end
+  end
+end

data/lib/neo4j/driver/client_certificate_manager.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Supplies the current client certificate for mutual TLS
+    # (Feature:API:SSLClientCertificate). Wrap a block that returns a
+    # ClientCertificate — or nil when nothing changed since the last call, in
+    # which case the previously supplied certificate is kept. Pass an instance
+    # to GraphDatabase.driver via `client_certificate_manager:`; the driver
+    # consults it whenever a connection needs a (possibly rotated) certificate.
+    #
+    # The MRI counterpart of the Java driver's org.neo4j.driver
+    # .ClientCertificateManager (whose get returns null for "no change"); the
+    # last non-nil certificate is retained here so a fresh per-connection TLS
+    # context always presents the current one.
+    class ClientCertificateManager
+      def initialize(&get_client_certificate)
+        @get_client_certificate = get_client_certificate
+        @current = nil
+        @mutex = Mutex.new
+      end
+
+      # The current client certificate. Polls the block; a non-nil result
+      # rotates the retained certificate, a nil result keeps it. Connections
+      # are acquired concurrently, so the poll-and-update is serialized: it
+      # keeps @current consistent and stops a blocking provider (the testkit
+      # callback round-trips to the frontend) from being entered concurrently.
+      def get_client_certificate
+        @mutex.synchronize do
+          certificate = @get_client_certificate.call
+          @current = certificate if certificate
+          @current
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/client_certificate_managers.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Factory for ClientCertificateManager, mirroring
+    # org.neo4j.driver.ClientCertificateManagers.
+    module ClientCertificateManagers
+      # A manager that presents the given (static) client certificate on every
+      # request — the non-rotating case.
+      def self.rotating(client_certificate)
+        ClientCertificateManager.new { client_certificate }
+      end
+    end
+  end
+end

data/lib/neo4j/driver/client_certificates.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Factory for ClientCertificate, mirroring org.neo4j.driver.ClientCertificates.
+    # Accepts path strings (or anything with #to_s, e.g. a Pathname) for the
+    # certificate and private-key PEM files, plus the key's optional password.
+    module ClientCertificates
+      def self.of(certfile, keyfile, password = nil)
+        ClientCertificate.new(certfile.to_s, keyfile.to_s, password)
+      end
+    end
+  end
+end