activecypher 0.0.0 → 0.3.0

data/lib/active_cypher/bolt/message_reader.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require 'stringio'
+
+module ActiveCypher
+  module Bolt
+    # Handles decoding chunked Packstream data into Bolt messages for Bolt v5.x.
+    class MessageReader
+      MAX_CHUNK_SIZE = 65_535 # Maximum size for a single chunk (unsigned 16-bit int)
+      READ_TIMEOUT = 15 # Seconds to wait for a read operation
+
+      def initialize(io)
+        @io = io
+        @buffer = StringIO.new(+'', 'rb+') # Internal buffer for chunked data
+      end
+
+      # Reads and decodes the next Bolt message from the stream.
+      # Handles Bolt's chunking mechanism.
+      #
+      # @return [Messaging::Message] The decoded message object.
+      # @raise [ProtocolError] If decoding fails or an unknown message type is received.
+      # @raise [ConnectionError] If the connection is lost during reading.
+      def read_message
+        message_bytes = read_message_chunks
+        return nil if message_bytes.nil? || message_bytes.empty?
+
+        unpacker = Packstream::Unpacker.new(StringIO.new(message_bytes, 'rb'))
+        signature, fields = unpacker.unpack
+
+        klass = find_message_class(signature) or
+          raise ProtocolError, "Unknown message signature 0x#{signature.to_s(16)}"
+
+        klass.new(*fields)
+      rescue EOFError => e
+        raise ConnectionError, "Connection closed while reading message: #{e.message}"
+      rescue ConnectionError
+        raise
+      rescue StandardError => e
+        raise ProtocolError, "Failed to decode message: #{e.class} - #{e.message}"
+      end
+
+      private
+
+      def read_raw_from_io(n)
+        Async::Task.current.with_timeout(READ_TIMEOUT) do
+          data = @io.read_exactly(n)
+          raise EOFError, 'Connection closed during read' unless data
+
+          return data
+        end
+      rescue Async::TimeoutError
+        raise ConnectionError, "Read operation timed out after #{READ_TIMEOUT}s"
+      rescue Errno::ECONNRESET, Errno::EPIPE, IOError, EOFError => e
+        raise ConnectionError, "Connection lost: #{e.message}"
+      end
+
+      # Reads message chunks from the IO stream until a zero chunk is found.
+      # @return [String] The concatenated bytes of the message.
+      def read_message_chunks
+        @buffer.rewind
+        @buffer.truncate(0)
+
+        loop do
+          chunk_size_bytes = read_raw_from_io(2)
+          chunk_size       = chunk_size_bytes.unpack1('n')
+
+          break if chunk_size.zero?
+          raise ProtocolError, "Chunk too large (#{chunk_size})" if chunk_size > MAX_CHUNK_SIZE
+
+          @buffer.write(read_raw_from_io(chunk_size))
+        end
+
+        @buffer.string
+      end
+
+      # Finds the message class corresponding to a signature byte.
+      def find_message_class(signature)
+        case signature
+        when Messaging::Success::SIGNATURE then Messaging::Success
+        when Messaging::Failure::SIGNATURE then Messaging::Failure
+        when Messaging::Ignored::SIGNATURE then Messaging::Ignored
+        when Messaging::Hello::SIGNATURE   then Messaging::Hello # Technically shouldn't receive HELLO, its old stuff
+        when Messaging::Run::SIGNATURE     then Messaging::Run   # Shouldn't receive RUN either
+        when Messaging::Pull::SIGNATURE    then Messaging::Pull  # Shouldn't receive PULL
+        when Messaging::Discard::SIGNATURE then Messaging::Discard # Shouldn't receive DISCARD
+        when Messaging::Record::SIGNATURE  then Messaging::Record
+        when Messaging::Begin::SIGNATURE   then Messaging::Begin   # Shouldn't receive BEGIN
+        when Messaging::Commit::SIGNATURE  then Messaging::Commit  # Shouldn't receive COMMIT
+        when Messaging::Rollback::SIGNATURE then Messaging::Rollback # Shouldn't receive ROLLBACK
+        when Messaging::Goodbye::SIGNATURE then Messaging::Goodbye
+        when Messaging::Logon::SIGNATURE then Messaging::Logon
+        when Messaging::Logoff::SIGNATURE then Messaging::Logoff
+        when Messaging::Route::SIGNATURE then Messaging::Route
+        when Messaging::Reset::SIGNATURE then Messaging::Reset
+        when Messaging::Telemetry::SIGNATURE then Messaging::Telemetry
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/bolt/message_writer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Bolt
+    # Handles encoding Bolt messages into Packstream format for Bolt v5.0
+    class MessageWriter
+      # Structure Markers
+      TINY_STRUCT_MARKER_BASE = 0xB0
+      STRUCT_8_MARKER = 0xDC
+      STRUCT_16_MARKER = 0xDD
+      # STRUCT_32_MARKER = 0xDE # Not implementing 32-bit sizes for now
+
+      def initialize(io)
+        @packer = Packstream::Packer.new(io)
+        @io = io # Keep a reference for direct writing if needed
+      end
+
+      # Encodes and writes a Bolt message to the underlying IO stream.
+      # @param message [Messaging::Message] The message object to write.
+      def write(message)
+        # Bolt 4.3 requires different chunking
+        size = message.fields.size
+
+        # Write structure header with size and signature
+        if size < 16
+          write_marker([TINY_STRUCT_MARKER_BASE | size].pack('C'))
+        else
+          write_marker([STRUCT_8_MARKER, size].pack('CC'))
+        end
+
+        # Write signature
+        write_marker([message.signature].pack('C'))
+
+        # Pack fields with careful handling of nils
+        message.fields.each do |field|
+          if field.nil?
+            @packer.pack(nil)
+          else
+            @packer.pack(field)
+          end
+        end
+      end
+
+      private
+
+      # Method removed as it's not used anymore - we're using the new write method above
+
+      def write_marker(marker_bytes)
+        @io.write(marker_bytes)
+      end
+    end
+  end
+end

data/lib/active_cypher/bolt/messaging.rb

@@ -0,0 +1,307 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/hash/indifferent_access'
+
+module ActiveCypher
+  module Bolt
+    # @!parse
+    #   # Messaging: Because every protocol needs a registry, and every registry needs a protocol.
+    module Messaging
+      # Internal registry: signature byte → Message subclass
+      @registry = {}
+
+      class << self
+        # For introspection
+        def registry
+          @registry.dup
+        end
+
+        # Lookup-and-instantiate based on signature + raw fields
+        #
+        # @param signature [Integer] the Bolt message signature
+        # @param fields    [Array]   the decoded fields for this message
+        # @return [Message] instance of the right subclass, or generic Message
+        def for_signature(signature, *fields)
+          if (klass = @registry[signature])
+            klass.new(*fields)
+          else
+            Message.new(signature, fields)
+          end
+        end
+
+        # Register a subclass if it defines SIGNATURE
+        def register(subclass)
+          return unless subclass.const_defined?(:SIGNATURE)
+
+          sig = subclass.const_get(:SIGNATURE)
+          @registry[sig] = subclass
+        end
+
+        # Normalize any metadata or parameters map
+        def normalize_map(map)
+          (map || {}).with_indifferent_access
+        end
+      end
+
+      # Base class — automatically registers subclasses with SIGNATURE
+      # Because inheritance hierarchies are the only thing deeper than this protocol.
+      class Message
+        attr_reader :signature, :fields
+
+        def initialize(signature, fields)
+          @signature = signature
+          @fields    = fields
+        end
+
+        def ==(other)
+          other.class == self.class &&
+            other.signature == signature &&
+            other.fields    == fields
+        end
+        alias eql? ==
+
+        def self.inherited(subclass)
+          Messaging.register(subclass)
+          super
+        end
+      end
+
+      # The HELLO message. Because every protocol needs to start with a greeting before the disappointment.
+      class Hello < Message
+        SIGNATURE = 0x01
+
+        def initialize(metadata)
+          meta = Messaging.normalize_map(metadata)
+          super(SIGNATURE, [meta])
+        end
+
+        def metadata
+          fields.first
+        end
+      end
+
+      # The GOODBYE message. For when you've had enough of this session, or life.
+      class Goodbye < Message
+        SIGNATURE = 0x02
+
+        def initialize
+          super(SIGNATURE, [])
+        end
+      end
+
+      # The RESET message. Because sometimes you just want to pretend nothing ever happened.
+      class Reset < Message
+        SIGNATURE = 0x0F
+
+        def initialize
+          super(SIGNATURE, [])
+        end
+      end
+
+      # The RUN message. Because what else would you do with a database connection?
+      class Run < Message
+        SIGNATURE = 0x10
+
+        # metadata may include bookmarks, tx_timeout, tx_metadata, mode, db
+        def initialize(query, parameters, metadata = {})
+          meta = Messaging.normalize_map(metadata)
+          params = Messaging.normalize_map(parameters)
+
+          # Neo4j mode normalization: single-char 'r' or 'w'
+          meta['mode'] = meta['mode'][0] if meta['mode'].is_a?(String) && meta['mode'].length > 1
+
+          super(SIGNATURE, [query, params, meta])
+        end
+
+        def query      = fields[0]
+        def parameters = fields[1]
+        def metadata   = fields[2]
+      end
+
+      # The BEGIN message. Because transactions are just promises waiting to be broken.
+      class Begin < Message
+        SIGNATURE = 0x11
+
+        # metadata may include mode, db, tx_metadata, etc.
+        def initialize(metadata = {})
+          meta = Messaging.normalize_map(metadata)
+
+          # Never set db to neo4j for memgraph
+          if meta['adapter'] == 'memgraph'
+            # For Memgraph, remove db key entirely if present
+            meta.delete('db')
+          elsif meta['mode'].is_a?(String) && meta['mode'].length == 1
+            # This is for Neo4j only
+            meta['db'] ||= 'neo4j'
+          end
+
+          # Set default mode if not present
+          meta['mode'] ||= 'write'
+
+          super(SIGNATURE, [meta])
+        end
+
+        def metadata
+          fields.first
+        end
+      end
+
+      # The COMMIT message. For when you want to pretend your changes are permanent.
+      class Commit < Message
+        SIGNATURE = 0x12
+
+        def initialize
+          super(SIGNATURE, [])
+        end
+      end
+
+      # The ROLLBACK message. Because sometimes you just want to undo your mistakes.
+      class Rollback < Message
+        SIGNATURE = 0x13
+
+        def initialize
+          super(SIGNATURE, [])
+        end
+      end
+
+      # The DISCARD message. For when you want to throw away results, or your hopes.
+      class Discard < Message
+        SIGNATURE = 0x2F
+
+        # metadata: { n: <N>, qid: <QID> }, where n = -1 means all
+        def initialize(metadata)
+          meta = Messaging.normalize_map(metadata)
+          super(SIGNATURE, [meta])
+        end
+
+        def metadata = fields.first
+        def n        = metadata[:n] || metadata['n']
+        def qid      = metadata[:qid] || metadata['qid']
+      end
+
+      # The PULL message. Because sometimes you just want to see what you got.
+      class Pull < Message
+        SIGNATURE = 0x3F
+
+        def initialize(metadata)
+          meta = Messaging.normalize_map(metadata)
+          super(SIGNATURE, [meta])
+        end
+
+        def metadata
+          fields.first
+        end
+      end
+
+      # The ROUTE message. For when you want to pretend you have control over routing.
+      class Route < Message
+        SIGNATURE = 0x66
+
+        def initialize(metadata)
+          meta = Messaging.normalize_map(metadata)
+          super(SIGNATURE, [meta])
+        end
+
+        def metadata
+          fields.first
+        end
+      end
+
+      # The LOGON message. Because authentication is just another chance to be rejected.
+      class Logon < Message
+        SIGNATURE = 0x6A
+
+        def initialize(metadata)
+          meta = Messaging.normalize_map(metadata)
+          super(SIGNATURE, [meta])
+        end
+
+        def metadata
+          fields.first
+        end
+      end
+
+      # The LOGOFF message. For when you want to leave quietly, without making a scene.
+      class Logoff < Message
+        SIGNATURE = 0x6B
+
+        def initialize
+          super(SIGNATURE, [])
+        end
+      end
+
+      # The TELEMETRY message. Because someone, somewhere, cares about your metrics. Probably.
+      class Telemetry < Message
+        SIGNATURE = 0x54
+
+        def initialize(metadata)
+          meta = Messaging.normalize_map(metadata)
+          super(SIGNATURE, [meta])
+        end
+
+        def metadata
+          fields.first
+        end
+      end
+
+      # The SUCCESS message. The rarest of all Bolt messages.
+      class Success < Message
+        SIGNATURE = 0x70
+
+        def initialize(metadata)
+          meta = Messaging.normalize_map(metadata)
+          super(SIGNATURE, [meta])
+        end
+
+        def metadata
+          fields.first
+        end
+      end
+
+      # The RECORD message. For when you actually get data back, against all odds.
+      class Record < Message
+        SIGNATURE = 0x71
+
+        def initialize(values)
+          super(SIGNATURE, [values])
+        end
+
+        def values
+          fields.first
+        end
+      end
+
+      # The IGNORED message. For when the server just can't be bothered.
+      class Ignored < Message
+        SIGNATURE = 0x7E
+
+        def initialize
+          super(SIGNATURE, [])
+        end
+      end
+
+      # The FAILURE message. The most honest message in the protocol.
+      class Failure < Message
+        SIGNATURE = 0x7F
+
+        def initialize(metadata)
+          meta = Messaging.normalize_map(metadata)
+          super(SIGNATURE, [meta])
+        end
+
+        def metadata
+          fields.first
+        end
+
+        def code
+          metadata['code']
+        end
+
+        def message
+          metadata['message']
+        end
+      end
+    end
+  end
+end