activecypher 0.0.0 → 0.3.0

data/lib/active_cypher/bolt/packstream.rb

@@ -0,0 +1,319 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module ActiveCypher
+  module Bolt
+    # Handles Packstream serialization and deserialization.
+    # Based on Bolt Protocol Specification version 5.0
+    # https://7687.org/bolt/bolt-protocol-specification-5.0.html#packstream-structures
+    module Packstream
+      # Marker Bytes & Limits
+      TINY_STRING_MARKER_BASE = 0x80
+      STRING_8_MARKER = 0xD0
+      STRING_16_MARKER = 0xD1
+      # STRING_32_MARKER = 0xD2
+
+      TINY_LIST_MARKER_BASE = 0x90 # Added List marker base
+      LIST_8_MARKER = 0xD4       # Added List marker
+      LIST_16_MARKER = 0xD5      # Added List marker
+      # LIST_32_MARKER = 0xD6      # Added List marker
+      # STRING_32_MARKER = 0xD2 # Not implementing 32-bit sizes for now
+
+      TINY_MAP_MARKER_BASE = 0xA0
+      MAP_8_MARKER = 0xD8
+      MAP_16_MARKER = 0xD9
+      # MAP_32_MARKER = 0xDA # Not implementing 32-bit sizes for now
+
+      INT_8 = 0xC8
+      INT_16 = 0xC9
+      INT_32 = 0xCA
+      INT_64 = 0xCB
+
+      TINY_INT_MIN = -16
+      TINY_INT_MAX = 127
+      INT_8_MIN = -128
+      INT_8_MAX = 127
+      INT_16_MIN = -32_768
+      INT_16_MAX = 32_767
+      INT_32_MIN = -2_147_483_648
+      INT_32_MAX = 2_147_483_647
+      # INT_64 limits are typically Ruby's standard Integer limits
+
+      # Packs Ruby objects into Packstream byte format.
+      class Packer
+        # Define constants inside Packer where they are used
+        NULL = 0xC0
+        FALSEY = 0xC2
+        TRUETHY = 0xC3
+
+        def initialize(io)
+          @io = io
+        end
+
+        def pack(value)
+          case value
+          when String then pack_string(value)
+          when Hash then pack_map(value)
+          when Integer then pack_integer(value)
+          when TrueClass then write_marker([TRUETHY].pack('C'))
+          when FalseClass then write_marker([FALSEY].pack('C'))
+          when NilClass then write_marker([NULL].pack('C'))
+          when Array then pack_list(value)
+          # TODO: Add other types as needed (Float, Structure)
+          else
+            raise ProtocolError, "Cannot pack type: #{value.class}"
+          end
+        end
+
+        private
+
+        def pack_string(str)
+          bytes = str.encode('UTF-8')
+          size = bytes.bytesize
+
+          if size < 16 # TinyString
+            write_marker_and_data([TINY_STRING_MARKER_BASE | size].pack('C'), bytes)
+          elsif size < 256 # STRING_8
+            write_marker_and_data([STRING_8_MARKER, size].pack('CC'), bytes)
+          elsif size < 65_536 # STRING_16
+            write_marker_and_data([STRING_16_MARKER, size].pack('Cn'), bytes)
+          else
+            raise ProtocolError, "String too large to pack (size: #{size})"
+            # write_marker_and_data([STRING_32_MARKER, size].pack('CN>'), bytes)
+          end
+        end
+
+        def pack_map(map)
+          size = map.size
+
+          if size < 16 # TinyMap
+            write_marker([TINY_MAP_MARKER_BASE | size].pack('C'))
+          elsif size < 256 # MAP_8
+            write_marker([MAP_8_MARKER, size].pack('CC'))
+          elsif size < 65_536 # MAP_16
+            write_marker([MAP_16_MARKER, size].pack('Cn'))
+          else
+            raise ProtocolError, "Map too large to pack (size: #{size})"
+            # write_marker([MAP_32_MARKER, size].pack('CN>'))
+          end
+
+          map.each do |key, value|
+            pack(key.to_s) # Keys must be strings
+            pack(value)
+          end
+        end
+
+        def pack_list(list)
+          size = list.size
+          if size < 16 # TinyList
+            write_marker([TINY_LIST_MARKER_BASE | size].pack('C'))
+          elsif size < 256 # LIST_8
+            write_marker([LIST_8_MARKER, size].pack('CC'))
+          elsif size < 65_536 # LIST_16
+            write_marker([LIST_16_MARKER, size].pack('Cn')) # n is already network byte order
+          else
+            raise ProtocolError, "List too large to pack (size: #{size})"
+            # write_marker([LIST_32_MARKER, size].pack('CN>')) # Use N> for network byte order
+          end
+
+          list.each { |item| pack(item) }
+        end
+
+        def pack_integer(int)
+          if int.between?(TINY_INT_MIN, TINY_INT_MAX) # Tiny Integer
+            write_marker([int].pack('c')) # Signed char for range -128 to 127
+          elsif int.between?(INT_8_MIN, INT_8_MAX) # INT_8
+            write_marker_and_data([INT_8].pack('C'), [int].pack('c'))
+          elsif int.between?(INT_16_MIN, INT_16_MAX) # INT_16
+            write_marker_and_data([INT_16].pack('C'), [int].pack('s>'))
+          elsif int.between?(INT_32_MIN, INT_32_MAX) # INT_32
+            write_marker_and_data([INT_32].pack('C'), [int].pack('l>'))
+          else # INT_64
+            write_marker_and_data([INT_64].pack('C'), [int].pack('q')) # q is already network byte order
+          end
+        end
+
+        def write_marker(marker_bytes)
+          @io.write(marker_bytes)
+        end
+
+        def write_marker_and_data(marker_bytes, data_bytes)
+          @io.write(marker_bytes)
+          @io.write(data_bytes) if data_bytes && !data_bytes.empty?
+        end
+      end
+
+      # Unpacks Packstream byte format into Ruby objects.
+      class Unpacker
+        # Marker Bytes
+        NULL = 0xC0
+        FALSEY = 0xC2
+        TRUETHY = 0xC3
+        INT_8 = 0xC8
+        INT_16 = 0xC9
+        INT_32 = 0xCA
+        INT_64 = 0xCB
+        FLOAT_64 = 0xC1 # Added Float marker
+
+        TINY_STRING_MARKER_BASE = 0x80
+        STRING_8_MARKER = 0xD0
+        STRING_16_MARKER = 0xD1
+        STRING_32_MARKER = 0xD2
+
+        TINY_LIST_MARKER_BASE = 0x90
+        LIST_8_MARKER = 0xD4
+        LIST_16_MARKER = 0xD5
+        LIST_32_MARKER = 0xD6
+
+        TINY_MAP_MARKER_BASE = 0xA0
+        MAP_8_MARKER = 0xD8
+        MAP_16_MARKER = 0xD9
+        MAP_32_MARKER = 0xDA
+
+        TINY_STRUCT_MARKER_BASE = 0xB0
+        STRUCT_8_MARKER = 0xDC
+        STRUCT_16_MARKER = 0xDD
+        STRUCT_32_MARKER = 0xDE
+
+        MARKER_HIGH_NIBBLE_MASK = 0xF0
+        MARKER_LOW_NIBBLE_MASK = 0x0F
+
+        def initialize(io)
+          @io = io
+        end
+
+        # Unpacks the next value from the stream.
+        def unpack
+          marker = read_byte
+          unpack_value(marker)
+        end
+
+        private
+
+        def unpack_value(marker)
+          # Add logging here
+          # Tiny types
+          return marker if marker >= 0 && marker < TINY_STRING_MARKER_BASE # Tiny Positive Int
+          return marker - 256 if marker >= 0xF0 # Tiny Negative Int (-1 to -16)
+
+          high_nibble = marker & MARKER_HIGH_NIBBLE_MASK
+          low_nibble = marker & MARKER_LOW_NIBBLE_MASK
+
+          case high_nibble
+          when TINY_STRING_MARKER_BASE then return unpack_string(low_nibble)
+          when TINY_LIST_MARKER_BASE   then return unpack_list(low_nibble)
+          when TINY_MAP_MARKER_BASE    then return unpack_map(low_nibble)
+          when TINY_STRUCT_MARKER_BASE then return unpack_structure(low_nibble)
+          end
+
+          # Other markers
+          case marker
+          when NULL then nil
+          when FALSEY then false
+          when TRUETHY then true
+          when INT_8 then read_int(1, 'c')
+          when INT_16 then read_int(2, 's>')
+          when INT_32 then read_int(4, 'l>')
+          when INT_64 then read_int(8, 'q>')
+          when STRING_8_MARKER then unpack_string(read_size(1))
+          when STRING_16_MARKER then unpack_string(read_size(2))
+          when STRING_32_MARKER then unpack_string(read_size(4))
+          when LIST_8_MARKER then unpack_list(read_size(1))
+          when LIST_16_MARKER then unpack_list(read_size(2))
+          when LIST_32_MARKER then unpack_list(read_size(4))
+          when MAP_8_MARKER then unpack_map(read_size(1))
+          when MAP_16_MARKER then unpack_map(read_size(2))
+          when MAP_32_MARKER then unpack_map(read_size(4))
+          when STRUCT_8_MARKER then unpack_structure(read_size(1))
+          when STRUCT_16_MARKER then unpack_structure(read_size(2))
+          when STRUCT_32_MARKER then unpack_structure(read_size(4))
+          when FLOAT_64 then unpack_float64
+          # TODO: Add Bytes
+          else
+            raise ProtocolError, "Unknown Packstream marker: 0x#{marker.to_s(16)}"
+          end
+        end
+
+        def unpack_string(size)
+          read_bytes(size).force_encoding('UTF-8')
+        end
+
+        def unpack_list(size)
+          Array.new(size) { unpack }
+        end
+
+        def unpack_map(size)
+          Array.new(size) { [unpack, unpack] }.to_h # Assumes keys are strings after unpack
+        end
+
+        # Unpacks a structure into a [signature, [fields]] array
+        def unpack_structure(size)
+          signature = read_byte
+          fields = Array.new(size) { unpack }
+          [signature, fields]
+        end
+
+        def unpack_float64
+          # Reads 8 bytes and unpacks as a double-precision float, big-endian
+          read_bytes(8).unpack1('G')
+        end
+
+        # Helper to read a single byte as an integer
+        def read_byte
+          byte = @io.read(1)
+          raise EOFError, 'Unexpected end of stream while reading byte' if byte.nil?
+
+          byte.unpack1('C')
+        end
+
+        # Helper to read size markers (unsigned integers)
+        # Helper to read size markers (unsigned integers)
+        def read_size(num_bytes)
+          bytes = read_bytes(num_bytes) # Read first
+          case num_bytes
+          when 1 then bytes.unpack1('C')
+          when 2 then bytes.unpack1('n') # Use 'n' (network byte order = big-endian)
+          when 4 then bytes.unpack1('N') # Use 'N' (network byte order = big-endian)
+          else raise ArgumentError, "Invalid size length: #{num_bytes}"
+          end
+        end
+
+        # Helper to read signed integers
+        def read_int(num_bytes, format)
+          bytes = read_bytes(num_bytes) # Read first
+          # Add logging immediately before unpack
+          #
+          # Put '>' back as it's needed for big-endian
+          bytes.unpack1(format)
+        end
+
+        # Helper to read exactly n bytes
+        def read_bytes(n)
+          return ''.b if n.zero? # Handle zero-length reads
+
+          data = @io.read(n)
+          # More robust check
+          raise EOFError, "Unexpected end of stream while reading #{n} bytes (got #{data&.bytesize || 'nil'})" unless data && data.bytesize == n
+
+          data
+        end
+      end
+
+      # Helper function to pack a value into a string
+      def self.pack(value)
+        io = StringIO.new(+'', 'wb') # Binary mode important
+        packer = Packer.new(io)
+        packer.pack(value)
+        io.string
+      end
+
+      # Helper function to unpack a value from a string
+      def self.unpack(bytes)
+        io = StringIO.new(bytes, 'rb') # Binary mode important
+        unpacker = Unpacker.new(io)
+        unpacker.unpack
+      end
+    end
+  end
+end

data/lib/active_cypher/bolt/result.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Bolt
+    # Handles query results, streams records, and provides summary information.
+    # Represents the result of a Cypher query execution.
+    class Result
+      include Enumerable # Allows iteration over records
+
+      attr_reader :fields, :summary_metadata, :qid
+
+      # @param fields [Array<String>] List of field names in the result.
+      # @param records [Array<Array>] List of records, where each record is a list of values.
+      # @param summary_metadata [Hash] Metadata received in the final SUCCESS message.
+      # @param qid [Integer, nil] The query ID associated with this result (-1 if none).
+      def initialize(fields, records, summary_metadata, qid = -1)
+        @fields = fields || [] # Ensure fields is an array
+        @records = records
+        @summary_metadata = summary_metadata || {}
+        @qid = qid
+        @consumed = false
+        @record_index = 0
+      end
+
+      # Allows iterating over the records using `each`.
+      # Yields each record as a Hash with field names as keys (symbols).
+      def each
+        raise 'Result already consumed or closed' if @consumed
+        return enum_for(:each) unless block_given? # Return enumerator if no block
+
+        @records.each do |record_values|
+          yield @fields.map(&:to_sym).zip(record_values).to_h
+        end
+        consume # Mark as consumed after successful iteration
+      end
+
+      # Retrieves a single record. Raises error if no records or more than one.
+      # @return [Hash] The single record as a symbol-keyed hash.
+      # @raise [RuntimeError] If the number of records is not exactly one.
+      def single
+        raise 'Result already consumed or closed' if @consumed
+        raise "Expected exactly one record, but found #{@records.size}" unless @records.size == 1
+
+        record = @fields.map(&:to_sym).zip(@records.first).to_h
+        consume
+        record
+      end
+
+      # Retrieves all records as an array of hashes.
+      # @return [Array<Hash>]
+      def to_a
+        raise 'Result already consumed or closed' if @consumed
+
+        result_array = @records.map do |record_values|
+          @fields.map(&:to_sym).zip(record_values).to_h
+        end
+        consume
+        result_array
+      end
+
+      # Checks if the result stream is still open (i.e., not fully consumed).
+      # @return [Boolean]
+      def open?
+        !@consumed
+      end
+
+      # Marks the result as fully consumed.
+      def consume
+        @consumed = true
+        # Potentially release resources if streaming was implemented differently
+      end
+
+      # Provides summary information about the query execution.
+      # @return [Hash] Summary metadata (e.g., counters, query type).
+      def summary
+        # TODO: Parse summary_metadata into a more structured Summary object?
+        consume unless @consumed # Ensure result is consumed before accessing summary
+        @summary_metadata
+      end
+    end
+  end
+end

data/lib/active_cypher/bolt/session.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require 'async'
+
+module ActiveCypher
+  module Bolt
+    # A Session is the primary unit of work in the Bolt Protocol.
+    # It maintains a connection to the database server and allows running queries.
+    class Session
+      attr_reader :connection, :database
+
+      def initialize(connection, database: nil)
+        @connection = connection
+
+        # For Memgraph, never set a database (they don't support multiple DBs)
+        @database = if connection.adapter.is_a?(ConnectionAdapters::MemgraphAdapter)
+                      nil
+                    else
+                      database
+                    end
+
+        @current_transaction = nil
+        @bookmarks = []
+      end
+
+      # Executes a Cypher query and returns the result.
+      #
+      # @param query [String] The Cypher query to execute.
+      # @param parameters [Hash] Parameters for the query.
+      # @param mode [Symbol] The access mode (:read or :write).
+      # @param db [String] The database name to run the query against.
+      # @return [Result] The result of the query execution.
+      def run(query, parameters = {}, mode: :write, db: nil)
+        # For Memgraph, explicitly set db to nil
+        db = nil if @connection.adapter.is_a?(ConnectionAdapters::MemgraphAdapter)
+
+        if @current_transaction&.active?
+          # If we have an active transaction, run the query within it
+          @current_transaction.run(query, parameters)
+        else
+          # Auto-transaction mode: each query gets its own transaction
+          run_transaction(mode, db: db) do |tx|
+            tx.run(query, parameters)
+          end
+        end
+      end
+
+      # Begin a new transaction.
+      #
+      # @param db [String] The database name to begin the transaction against.
+      # @param access_mode [Symbol] The access mode (:read or :write).
+      # @param tx_timeout [Integer] Transaction timeout in milliseconds.
+      # @param tx_metadata [Hash] Transaction metadata to send to the server.
+      # @return [Transaction] The new transaction.
+      def begin_transaction(db: nil, access_mode: :write, tx_timeout: nil, tx_metadata: nil)
+        raise ConnectionError, 'Already in a transaction' if @current_transaction&.active?
+
+        # Send BEGIN message with appropriate metadata
+        begin_meta = {}
+        # For Memgraph, NEVER set a database name - it doesn't support them
+        if @connection.adapter.is_a?(ConnectionAdapters::MemgraphAdapter)
+          # Explicitly don't set db for Memgraph
+          begin_meta['adapter'] = 'memgraph'
+          # Force db to nil for Memgraph
+          nil
+        elsif db || @database
+          begin_meta['db'] = db || @database
+        end
+        begin_meta['mode'] = access_mode == :read ? 'r' : 'w'
+        begin_meta['tx_timeout'] = tx_timeout if tx_timeout
+        begin_meta['tx_metadata'] = tx_metadata if tx_metadata
+        begin_meta['bookmarks'] = @bookmarks if @bookmarks&.any?
+
+        begin_msg = Messaging::Begin.new(begin_meta)
+        @connection.write_message(begin_msg)
+
+        # Read response to BEGIN
+        response = @connection.read_message
+
+        case response
+        when Messaging::Success
+          # BEGIN succeeded, create a new transaction
+          @current_transaction = Transaction.new(self, @bookmarks, response.metadata)
+        when Messaging::Failure
+          # BEGIN failed
+          code = response.metadata['code']
+          message = response.metadata['message']
+          @connection.reset!
+          raise QueryError, "Failed to begin transaction: #{code} - #{message}"
+        else
+          raise ProtocolError, "Unexpected response to BEGIN: #{response.class}"
+        end
+      end
+
+      # Marks a transaction as completed and removes it from the session.
+      #
+      # @param transaction [Transaction] The transaction to complete.
+      # @param new_bookmarks [Array<String>] New bookmarks to update.
+      def complete_transaction(transaction, new_bookmarks = nil)
+        return unless transaction == @current_transaction
+
+        @current_transaction = nil
+        @bookmarks = new_bookmarks if new_bookmarks
+      end
+
+      # Execute a block of code within a transaction.
+      #
+      # @param mode [Symbol] The access mode (:read or :write).
+      # @param db [String] The database name to run the transaction against.
+      # @param timeout [Integer] Transaction timeout in milliseconds.
+      # @param metadata [Hash] Transaction metadata to send to the server.
+      # @yield [tx] The transaction to use for queries.
+      # @return The result of the block.
+      def run_transaction(mode = :write, db: nil, timeout: nil, metadata: nil, &)
+        # Ensure we're running in an Async context
+        if Async::Task.current?
+          # Already in an Async task, proceed normally
+          begin
+            execute_transaction(mode, db: db, timeout: timeout, metadata: metadata, &)
+          rescue StandardError => e
+            # Ensure errors are properly propagated
+            raise e
+          end
+        else
+          # Wrap in an Async task
+          result = nil
+          error = nil
+
+          Async do
+            result = execute_transaction(mode, db: db, timeout: timeout, metadata: metadata, &)
+          rescue StandardError => e
+            error = e
+          end.wait
+
+          # Re-raise any error outside the async block
+          raise error if error
+
+          result
+        end
+      end
+
+      # Helper method to execute the transaction
+      def execute_transaction(mode, db:, timeout:, metadata:)
+        tx = begin_transaction(db: db,
+                               access_mode: mode,
+                               tx_timeout: timeout,
+                               tx_metadata: metadata)
+
+        result = yield tx           # your block runs here
+        tx.commit                   # happy path
+        result
+      rescue StandardError => e     # any error → rollback → wrap
+        begin
+          tx.rollback
+        rescue StandardError => rollback_error
+          # Log rollback error but continue with the original error
+          puts "Error during rollback: #{rollback_error.message}" if ENV['DEBUG']
+        end
+
+        # Preserve the original error
+        raise ActiveCypher::TransactionError, e.message
+      end
+
+      def write_transaction(db: nil, timeout: nil, metadata: nil, &)
+        run_transaction(:write, db: db, timeout: timeout, metadata: metadata, &)
+      end
+
+      def read_transaction(db: nil, timeout: nil, metadata: nil, &)
+        run_transaction(:read, db: db, timeout: timeout, metadata: metadata, &)
+      end
+
+      # Access the current bookmarks for this session.
+      def bookmarks
+        @bookmarks || []
+      end
+
+      # Update session bookmarks for causal consistency.
+      attr_writer :bookmarks
+
+      # Reset any session and transaction state (e.g., after errors).
+      def reset
+        return if @current_transaction.nil?
+
+        # Mark the current transaction as no longer active
+        complete_transaction(@current_transaction)
+
+        # Reset the connection
+        @connection.reset!
+      end
+
+      # Close the session and any active transaction.
+      def close
+        # If there's an active transaction, try to roll it back
+        @current_transaction&.rollback if @current_transaction&.active?
+
+        # Mark current transaction as complete
+        complete_transaction(@current_transaction) if @current_transaction
+      end
+    end
+  end
+end