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

data/lib/neo4j/driver/packstream/packer.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module PackStream
+      # PackStream Packer - serializes Ruby objects to PackStream binary format
+      # Based on https://neo4j.com/docs/bolt/current/packstream/
+      class Packer
+        include Markers
+
+        # When true, datetimes are packed as the UTC-seconds Bolt 5.0+
+        # structures (0x49 / 0x69) instead of the legacy local-seconds
+        # variants (0x46 / 0x66). Connection sets this after a
+        # successful handshake negotiates Bolt 5.0+; ignored on 4.x.
+        attr_accessor :use_utc_datetime
+
+        def initialize(protocol)
+          @buffer = String.new(encoding: Encoding::BINARY)
+          @use_utc_datetime = false
+          @protocol = protocol
+        end
+
+        def pack(value)
+          case value
+          when nil
+            pack_null
+          when true, false
+            pack_boolean(value)
+          when Integer
+            pack_integer(value)
+          when Float
+            pack_float(value)
+          when String
+            # Pack binary strings as BYTES, text strings as STRING
+            value.encoding == Encoding::BINARY ? pack_bytes(value) : pack_string(value)
+          when Symbol
+            pack_string(value.to_s)
+          when Hash
+            # Check Hash before Enumerable since Hash is also Enumerable
+            pack_map(value)
+          when Types::Node, Types::Relationship, Types::Path, Types::UnsupportedType
+            # Graph types are not valid query parameters; neither is an
+            # UnsupportedType (a value the driver couldn't materialise — it
+            # must not be sent back to the server). Reject before the Enumerable
+            # branch since Path includes Enumerable.
+            Exceptions::ClientException.unable_to_convert(value)
+          when Array, Set, Range
+            # Known sized collections — pack_list uses #size, which is O(1) here.
+            pack_list(value)
+          when Enumerable
+            # Generic Enumerable (lazy enumerators, custom collections) — materialise
+            # so #size is well-defined.
+            pack_list(value.to_a)
+          when ::DateTime, ::Time
+            # Check DateTime before Date — DateTime < Date in Ruby, so the
+            # Date branch would match first and pack away the time component.
+            pack_datetime(value)
+          when ::Date
+            # Pack Ruby Date as Neo4j Date structure
+            pack_date(value)
+          when Types::LocalDateTime
+            pack_local_datetime(value)
+          when Types::LocalTime
+            pack_local_time(value)
+          when Types::OffsetTime
+            pack_offset_time(value)
+          when Types::Point
+            pack_point(value)
+          when Types::Duration
+            pack_duration(value)
+          when Types::UUID
+            # A PackStream V2 type: only the negotiated protocol decides whether
+            # it can be sent — V61 packs it, every earlier version rejects it.
+            @protocol.pack_uuid(self, value)
+          else
+            Exceptions::ClientException.unable_to_convert(value)
+          end
+          self
+        end
+
+        # Serialise a Bolt protocol message (a PackStream::Structure) onto the buffer.
+        # Distinct from #pack so the user-value path doesn't carry knowledge of
+        # the wire-level Structure type.
+        def pack_message(structure)
+          pack_structure(structure)
+          self
+        end
+
+        def bytes
+          @buffer
+        end
+
+        def reset
+          @buffer.clear
+          self
+        end
+
+        # PackStream V2 UUID (Bolt 6.1+): marker 0xE0 + 16 raw bytes. Called by
+        # Protocol::V61#pack_uuid — every earlier protocol rejects a UUID
+        # instead, so this is only reached once 6.1 is negotiated.
+        def pack_uuid_value(value)
+          @buffer << [UUID].pack('C')
+          @buffer << [value.to_s.delete('-')].pack('H*')
+        end
+
+        private
+
+        def pack_null
+          @buffer << [NULL].pack('C')
+        end
+
+        def pack_boolean(value)
+          @buffer << [value ? BOOLEAN_TRUE : BOOLEAN_FALSE].pack('C')
+        end
+
+        def pack_integer(value)
+          if value >= -16 && value <= 127
+            # TINY_INT: -16 to +127
+            @buffer << [value].pack('c')
+          elsif value >= -128 && value <= 127
+            @buffer << [INT_8, value].pack('Cc')
+          elsif value >= -32_768 && value <= 32_767
+            @buffer << [INT_16, value].pack('Cs>')
+          elsif value >= -2_147_483_648 && value <= 2_147_483_647
+            @buffer << [INT_32, value].pack('Cl>')
+          elsif value >= -9_223_372_036_854_775_808 && value <= 9_223_372_036_854_775_807
+            @buffer << [INT_64, value].pack('Cq>')
+          else
+            raise ArgumentError, "Integer value out of range: #{value}"
+          end
+        end
+
+        def pack_float(value)
+          @buffer << [FLOAT_64].pack('C')
+          @buffer << [value].pack('G')
+        end
+
+        def pack_string(value)
+          bytes = value.encode(Encoding::UTF_8).b
+          size = bytes.bytesize
+
+          if size < 16
+            @buffer << [TINY_STRING | size].pack('C')
+          elsif size <= 255
+            @buffer << [STRING_8, size].pack('CC')
+          elsif size <= 65_535
+            @buffer << [STRING_16, size].pack('CS>')
+          elsif size <= 2_147_483_647
+            @buffer << [STRING_32, size].pack('CL>')
+          else
+            raise ArgumentError, "String too long: #{size} bytes"
+          end
+
+          @buffer << bytes
+        end
+
+        def pack_bytes(value)
+          size = value.bytesize
+
+          if size <= 255
+            @buffer << [BYTES_8, size].pack('CC')
+          elsif size <= 65_535
+            @buffer << [BYTES_16, size].pack('CS>')
+          elsif size <= 2_147_483_647
+            @buffer << [BYTES_32, size].pack('CL>')
+          else
+            raise ArgumentError, "Bytes too long: #{size} bytes"
+          end
+
+          @buffer << value
+        end
+
+        def pack_list(value)
+          size = value.size
+
+          if size < 16
+            @buffer << [TINY_LIST | size].pack('C')
+          elsif size <= 255
+            @buffer << [LIST_8, size].pack('CC')
+          elsif size <= 65_535
+            @buffer << [LIST_16, size].pack('CS>')
+          elsif size <= 2_147_483_647
+            @buffer << [LIST_32, size].pack('CL>')
+          else
+            raise ArgumentError, "List too long: #{size} items"
+          end
+
+          value.each { pack(it) }
+        end
+
+        def pack_map(value)
+          size = value.size
+
+          if size < 16
+            @buffer << [TINY_MAP | size].pack('C')
+          elsif size <= 255
+            @buffer << [MAP_8, size].pack('CC')
+          elsif size <= 65_535
+            @buffer << [MAP_16, size].pack('CS>')
+          elsif size <= 2_147_483_647
+            @buffer << [MAP_32, size].pack('CL>')
+          else
+            raise ArgumentError, "Map too long: #{size} entries"
+          end
+
+          value.each do |key, val|
+            pack(key.to_s)
+            pack(val)
+          end
+        end
+
+        def pack_structure(value)
+          size = value.fields.size
+
+          if size < 16
+            @buffer << [TINY_STRUCT | size].pack('C')
+          elsif size <= 255
+            @buffer << [STRUCT_8, size].pack('CC')
+          elsif size <= 65_535
+            @buffer << [STRUCT_16, size].pack('CS>')
+          else
+            raise ArgumentError, "Structure too large: #{size} fields"
+          end
+
+          @buffer << [value.signature].pack('C')
+          value.fields.each { |field| pack(field) }
+        end
+
+        def pack_date(value)
+          days = (value - ::Date.new(1970, 1, 1)).to_i
+          # Date structure: signature 0x44, 1 field (days)
+          @buffer << [TINY_STRUCT | 1, 0x44].pack('CC')
+          pack_integer(days)
+        end
+
+        def pack_datetime(value)
+          # Normalise DateTime to Time so we can rely on Time's API (nsec,
+          # utc_offset, to_i) uniformly.
+          value = value.to_time if value.is_a?(::DateTime)
+
+          tz_offset = value.utc_offset
+          nanoseconds = value.nsec
+          # Bolt 5.0+ (and 4.4-with-patch_bolt:utc) want true UTC
+          # seconds in 0x49 / 0x69; the legacy 0x46 / 0x66 carry LOCAL
+          # seconds (wall-clock treated as if it were UTC). See the
+          # matching hydration handlers in Bolt::Connection.
+          if @use_utc_datetime
+            epoch_seconds = value.to_i
+            offset_sig = 0x49
+            zone_sig = 0x69
+          else
+            epoch_seconds = value.to_i + tz_offset
+            offset_sig = 0x46
+            zone_sig = 0x66
+          end
+          zone_name = named_zone_for(value)
+
+          if zone_name
+            # ZonedDateTime: fields [seconds, nanos, tz_name]
+            @buffer << [TINY_STRUCT | 3, zone_sig].pack('CC')
+            pack_integer(epoch_seconds)
+            pack_integer(nanoseconds)
+            pack_string(zone_name)
+          else
+            # DateTime with offset: fields [seconds, nanos, tz_offset]
+            @buffer << [TINY_STRUCT | 3, offset_sig].pack('CC')
+            pack_integer(epoch_seconds)
+            pack_integer(nanoseconds)
+            pack_integer(tz_offset)
+          end
+        end
+
+        # Return the IANA zone name for a TimeWithZone-like value when it has
+        # one, otherwise nil (so the caller falls back to offset-only 0x46).
+        # Offset-shaped names like "+07:00" or "-05:00" don't round-trip
+        # through Neo4j's zoned DateTime and are treated as nil.
+        def named_zone_for(value)
+          return nil unless value.respond_to?(:time_zone)
+
+          tz = value.time_zone
+          name = tz.respond_to?(:name) ? tz.name : nil
+          return nil if name.nil? || name.empty? || name.match?(/\A[+-]?\d/)
+
+          name
+        end
+
+        def pack_local_datetime(value)
+          # LocalDateTime structure: signature 0x64, 2 fields (seconds, nanos)
+          @buffer << [TINY_STRUCT | 2, 0x64].pack('CC')
+          pack_integer(value.epoch_seconds)
+          pack_integer(value.nanoseconds)
+        end
+
+        def pack_offset_time(value)
+          # OffsetTime structure: signature 0x54, 2 fields (nanos, tz_offset)
+          @buffer << [TINY_STRUCT | 2, 0x54].pack('CC')
+          pack_integer(value.nanoseconds)
+          pack_integer(value.tz_offset_seconds)
+        end
+
+        def pack_local_time(value)
+          # LocalTime structure: signature 0x74, 1 field (nanos)
+          @buffer << [TINY_STRUCT | 1, 0x74].pack('CC')
+          pack_integer(value.nanoseconds)
+        end
+
+        def pack_point(value)
+          if value.z.nil?
+            # Point2D: signature 0x58, 3 fields (srid, x, y)
+            @buffer << [TINY_STRUCT | 3, 0x58].pack('CC')
+            pack_integer(value.srid)
+            pack_float(value.x)
+            pack_float(value.y)
+          else
+            # Point3D: signature 0x59, 4 fields (srid, x, y, z)
+            @buffer << [TINY_STRUCT | 4, 0x59].pack('CC')
+            pack_integer(value.srid)
+            pack_float(value.x)
+            pack_float(value.y)
+            pack_float(value.z)
+          end
+        end
+
+        def pack_duration(value)
+          # Duration: signature 0x45, 4 fields (months, days, seconds, nanoseconds)
+          @buffer << [TINY_STRUCT | 4, 0x45].pack('CC')
+          pack_integer(value.months)
+          pack_integer(value.days)
+          pack_integer(value.seconds)
+          pack_integer(value.nanoseconds)
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/packstream/structure.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module PackStream
+      # Represents a PackStream Structure with a signature and fields
+      class Structure
+        attr_reader :signature, :fields
+
+        def initialize(signature, fields = [])
+          @signature = signature
+          @fields = fields
+        end
+
+        def ==(other)
+          other.is_a?(Structure) &&
+            other.signature == @signature &&
+            other.fields == @fields
+        end
+
+        def to_s
+          "Structure(0x#{@signature.to_s(16).upcase}, #{@fields.inspect})"
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/packstream/unpacker.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module PackStream
+      # PackStream Unpacker - deserializes PackStream binary format to Ruby objects
+      class Unpacker
+        include Markers
+
+        def initialize(io, protocol)
+          @io = io
+          @hydration_handlers = {}
+          @protocol = protocol
+        end
+
+        def register_hydration_handler(signature, handler = nil, &block)
+          @hydration_handlers[signature] = handler || block
+        end
+
+        def unpack
+          marker_byte = read_bytes(1).unpack1('C')
+          unpack_value(marker_byte)
+        end
+
+        # PackStream V2 UUID (Bolt 6.1+): 16 raw bytes (big-endian) after the
+        # marker, rendered to the canonical hyphenated form for Types::UUID.
+        # Called by Protocol::V61#unpack_uuid — earlier protocols reject the
+        # marker instead, so this is only reached once 6.1 is negotiated.
+        def unpack_uuid_value
+          hex = read_bytes(16).unpack1('H*')
+          Types::UUID.from_string(
+            "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+          )
+        end
+
+        # A ProtocolException (not a bare RuntimeError) so the failure reaches
+        # the user as a DriverError. The wording carries "PackStream" and the
+        # zero-padded marker byte — e.g. a UUID (0xE0) received before Bolt 6.1,
+        # which Protocol::Base#unpack_uuid routes here. testkit's UUID-over-6.0
+        # assertion greps the lowercased message for "unknown packstream" and
+        # "e0", both of which this satisfies.
+        def raise_unknown_marker(marker)
+          raise Exceptions::ProtocolException,
+                format('Unknown PackStream type marker: 0x%02x', marker)
+        end
+
+        private
+
+        def unpack_value(marker)
+          case marker
+          when NULL
+            nil
+          when BOOLEAN_FALSE
+            false
+          when BOOLEAN_TRUE
+            true
+          when FLOAT_64
+            read_bytes(8).unpack1('G')
+          when INT_8
+            read_bytes(1).unpack1('c')
+          when INT_16
+            read_bytes(2).unpack1('s>')
+          when INT_32
+            read_bytes(4).unpack1('l>')
+          when INT_64
+            read_bytes(8).unpack1('q>')
+          when 0xC8..0xCB
+            # Already handled above, but needed for case coverage
+            raise "Unexpected marker in unpack_value: #{marker}"
+          when BYTES_8
+            size = read_bytes(1).unpack1('C')
+            read_bytes(size).force_encoding(Encoding::BINARY)
+          when BYTES_16
+            size = read_bytes(2).unpack1('S>')
+            read_bytes(size).force_encoding(Encoding::BINARY)
+          when BYTES_32
+            size = read_bytes(4).unpack1('L>')
+            read_bytes(size).force_encoding(Encoding::BINARY)
+          when STRING_8
+            size = read_bytes(1).unpack1('C')
+            read_bytes(size).force_encoding(Encoding::UTF_8)
+          when STRING_16
+            size = read_bytes(2).unpack1('S>')
+            read_bytes(size).force_encoding(Encoding::UTF_8)
+          when STRING_32
+            size = read_bytes(4).unpack1('L>')
+            read_bytes(size).force_encoding(Encoding::UTF_8)
+          when LIST_8
+            size = read_bytes(1).unpack1('C')
+            unpack_list(size)
+          when LIST_16
+            size = read_bytes(2).unpack1('S>')
+            unpack_list(size)
+          when LIST_32
+            size = read_bytes(4).unpack1('L>')
+            unpack_list(size)
+          when MAP_8
+            size = read_bytes(1).unpack1('C')
+            unpack_map(size)
+          when MAP_16
+            size = read_bytes(2).unpack1('S>')
+            unpack_map(size)
+          when MAP_32
+            size = read_bytes(4).unpack1('L>')
+            unpack_map(size)
+          when STRUCT_8
+            size = read_bytes(1).unpack1('C')
+            unpack_structure(size)
+          when STRUCT_16
+            size = read_bytes(2).unpack1('S>')
+            unpack_structure(size)
+          when UUID
+            # A PackStream V2 type: only the negotiated protocol decides whether
+            # the marker is known — V61 reads it, every earlier version rejects
+            # it as an unknown marker.
+            @protocol.unpack_uuid(self)
+          else
+            # Check for TINY types
+            if (marker & 0xF0) == TINY_STRING
+              size = marker & 0x0F
+              read_bytes(size).force_encoding(Encoding::UTF_8)
+            elsif (marker & 0xF0) == TINY_LIST
+              size = marker & 0x0F
+              unpack_list(size)
+            elsif (marker & 0xF0) == TINY_MAP
+              size = marker & 0x0F
+              unpack_map(size)
+            elsif (marker & 0xF0) == TINY_STRUCT
+              size = marker & 0x0F
+              unpack_structure(size)
+            elsif marker >= 0xF0 || marker <= 0x7F
+              # TINY_INT range: -16 to 127
+              # Values from 0xF0-0xFF represent -16 to -1
+              # Values from 0x00-0x7F represent 0 to 127
+              if marker >= 0xF0
+                marker - 256 # Convert to negative
+              else
+                marker
+              end
+            else
+              raise_unknown_marker(marker)
+            end
+          end
+        end
+
+        def unpack_list(size) = Array.new(size) { unpack }
+
+        def unpack_map(size)
+          {}.tap { |map| size.times { map[unpack.to_sym] = unpack } }
+        end
+
+        def unpack_structure(size)
+          signature = read_bytes(1).unpack1('C')
+          fields = Array.new(size) { unpack }
+          handler = @hydration_handlers[signature] or
+            raise "No hydration handler for PackStream structure signature 0x#{signature.to_s(16)}"
+
+          handler.call(fields)
+        end
+
+        def read_bytes(n)
+          data = @io.read(n)
+          raise IOError, 'Unexpected end of stream' if data.nil? || data.bytesize < n
+
+          data
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/record.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    # Represents a single record (row) in a result
+    class Record
+      def initialize(keys, values)
+        @keys = keys
+        @values = values
+        # Create map with string keys for consistent lookup
+        @map = {}
+        @keys.each_with_index do |key, idx|
+          @map[key.to_s] = @values[idx]
+        end
+      end
+
+      attr_reader :keys, :values
+
+      def [](key)
+        case key
+        when Integer
+          @values[key]
+        when String, Symbol
+          @map[key.to_s]
+        else
+          raise ArgumentError, "Invalid key type: #{key.class}"
+        end
+      end
+
+      def first
+        @values.first
+      end
+
+      def to_h
+        @map.dup
+      end
+
+      def each(&)
+        @map.each(&)
+      end
+    end
+  end
+end