activecypher 0.0.0 → 0.2.0

data/lib/active_cypher/bolt/transaction.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Bolt
+    # Manages transaction state (BEGIN/COMMIT/ROLLBACK) and runs queries within a transaction.
+    class Transaction
+      attr_reader :bookmarks, :metadata
+
+      # Initializes a new Transaction instance.
+      #
+      # @param session [Session] The session that owns this transaction.
+      # @param initial_bookmarks [Array<String>] Initial bookmarks for causal consistency.
+      # @param metadata [Hash] Metadata from the BEGIN success response.
+      def initialize(session, initial_bookmarks, metadata = {})
+        @session = session
+        @connection = session.connection
+        @bookmarks = initial_bookmarks || []
+        @metadata = metadata
+        @state = :active
+      end
+
+      # Runs a Cypher query within this transaction.
+      #
+      # @param query [String] The Cypher query to execute.
+      # @param parameters [Hash] Parameters for the query.
+      # @return [Result] The result of the query execution.
+      def run(query, parameters = {})
+        raise ConnectionError, "Cannot run query on a #{@state} transaction" unless @state == :active
+
+        # Ensure query is a string
+        query_str = query.is_a?(String) ? query : query.to_s
+
+        # Send RUN message
+        run_metadata = {}
+        run_msg = Messaging::Run.new(query_str, parameters, run_metadata)
+        @connection.write_message(run_msg)
+
+        # Read response to RUN
+        response = @connection.read_message
+        qid = -1
+        fields = []
+
+        case response
+        when Messaging::Success
+          # RUN succeeded, extract metadata
+
+          qid = response.metadata['qid'] if response.metadata.key?('qid')
+          fields = response.metadata['fields'] if response.metadata.key?('fields')
+
+          # Send PULL to get all records (-1 = all)
+          pull_metadata = { 'n' => -1 }
+          pull_metadata['qid'] = qid if qid != -1
+          pull_msg = Messaging::Pull.new(pull_metadata)
+          @connection.write_message(pull_msg)
+
+          # Process PULL response(s)
+          records = []
+          summary_metadata = {}
+
+          # Read messages until we get a SUCCESS (or FAILURE)
+          loop do
+            msg = @connection.read_message
+            case msg
+            when Messaging::Record
+              # Store record with raw values - processing will happen in the adapter
+              records << msg.values
+            when Messaging::Success
+              # Final SUCCESS with summary metadata
+              summary_metadata = msg.metadata
+              break # Done processing results
+            when Messaging::Failure
+              connection.reset!
+              # PULL failed - transaction is now failed
+              @state = :failed
+              code = msg.metadata['code']
+              message = msg.metadata['message']
+              raise QueryError, "Query execution failed: #{code} - #{message}"
+            else
+              raise ProtocolError, "Unexpected message type: #{msg.class}"
+            end
+          end
+
+          # Create and return Result object
+          Result.new(fields, records, summary_metadata, qid)
+        when Messaging::Failure
+          # RUN failed - transaction is now failed
+          @state = :failed
+          code = response.metadata['code']
+          message = response.metadata['message']
+          raise QueryError, "Query execution failed: #{code} - #{message}"
+        else
+          raise ProtocolError, "Unexpected response to RUN: #{response.class}"
+        end
+      rescue ConnectionError
+        @state = :failed
+        raise
+      end
+
+      # Commits the transaction.
+      #
+      # @return [Array<String>] Any new bookmarks.
+      def commit
+        raise ConnectionError, "Cannot commit a #{@state} transaction" unless @state == :active
+
+        # Send COMMIT message
+        commit_msg = Messaging::Commit.new
+        @connection.write_message(commit_msg)
+
+        # Read response to COMMIT
+        response = @connection.read_message
+
+        case response
+        when Messaging::Success
+          # COMMIT succeeded
+
+          @state = :committed
+
+          # Extract bookmarks if any
+          new_bookmarks = []
+          if response.metadata.key?('bookmark')
+            new_bookmarks = [response.metadata['bookmark']]
+            @bookmarks = new_bookmarks
+          end
+
+          # Mark transaction as completed in the session
+          @session.complete_transaction(self, new_bookmarks)
+
+          new_bookmarks
+        when Messaging::Failure
+          # COMMIT failed
+          @state = :failed
+          code = response.metadata['code']
+          message = response.metadata['message']
+
+          # Mark transaction as completed in the session
+          @session.complete_transaction(self)
+
+          raise QueryError, "Failed to commit transaction: #{code} - #{message}"
+        else
+          raise ProtocolError, "Unexpected response to COMMIT: #{response.class}"
+        end
+      rescue ConnectionError
+        @state = :failed
+        # Mark transaction as completed in the session
+        begin
+          @session.complete_transaction(self)
+        rescue StandardError
+          nil
+        end
+        raise
+      end
+
+      # Rolls back the transaction.
+      def rollback
+        # If already committed or rolled back, do nothing
+        return if @state == :committed || @state == :rolled_back
+
+        begin
+          # Send ROLLBACK message
+          rollback_msg = Messaging::Rollback.new
+          @connection.write_message(rollback_msg)
+
+          # Read response to ROLLBACK
+          response = @connection.read_message
+
+          case response
+          when Messaging::Success
+            # ROLLBACK succeeded
+
+          when Messaging::Failure
+            # ROLLBACK failed - unusual but possible if connection is in a bad state
+            response.metadata['code']
+            response.metadata['message']
+
+            # We don't raise here to ensure the rollback doesn't throw exceptions
+          end
+        rescue StandardError
+          # We catch all exceptions during rollback to ensure it doesn't throw
+        ensure
+          # Always mark as rolled back and complete the transaction
+          @state = :rolled_back
+          begin
+            @session.complete_transaction(self)
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      # Checks if the transaction is active.
+      def active?
+        @state == :active
+      end
+
+      # Checks if the transaction is committed.
+      def committed?
+        @state == :committed
+      end
+
+      # Checks if the transaction is rolled back.
+      def rolled_back?
+        @state == :rolled_back
+      end
+
+      # Checks if the transaction is in a failed state.
+      def failed?
+        @state == :failed
+      end
+    end
+  end
+end

data/lib/active_cypher/bolt/version_encoding.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module Bolt
+    module VersionEncoding
+      private
+
+      # ----------------------------
+      # Encode: [0,0,minor,major]
+      # ----------------------------
+      # Accepts Float (5.8), String ('5.8'), Integer (5) or [major,minor]
+      def encode_version(ver)
+        major, minor =
+          case ver
+          when Float   then [ver.to_i, (ver * 10).round % 10]
+          when String  then ver.split('.').map(&:to_i)
+          when Integer then [ver, 0]
+          when Array   then ver
+          else
+            raise ArgumentError, "Unsupported version #{ver.inspect}"
+          end
+
+        [0, 0, minor, major].pack('C4')
+      end
+
+      # ----------------------------
+      # Decode: extract minor / major
+      # ----------------------------
+      def decode_version(bytes)
+        raise ArgumentError, 'need 4 bytes' unless bytes.bytesize == 4
+
+        minor = bytes.getbyte(2)
+        major = bytes.getbyte(3)
+
+        return 0.0 if major.zero? && minor.zero?
+
+        "#{major}.#{minor}".to_f # or return [major, minor]
+      end
+    end
+  end
+end

data/lib/active_cypher/bolt.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  # Namespace for the Bolt Protocol Driver implementation.
+  module Bolt
+  end
+end

data/lib/active_cypher/connection_adapters/abstract_adapter.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'logger'
+require 'date'
+require 'active_support/core_ext/hash/indifferent_access'
+
+module ActiveCypher
+  module ConnectionAdapters
+    # Minimal contract every graph adapter must fulfil.
+    # @note Because every project needs an abstract class to remind you that nothing is ever truly implemented.
+    class AbstractAdapter
+      attr_reader :config
+
+      # Initializes the adapter, because you can't spell "configuration" without "con."
+      # @param config [Hash] The configuration hash for the adapter
+      def initialize(config) = (@config = config)
+
+      # ---- lifecycle ---------------------------------------------------------
+      # The lifecycle methods. Spoiler: most of them do nothing.
+      def connect                 = raise(AdapterNotFoundError)
+      def disconnect              = true
+      def active?                 = false
+      def reconnect               = disconnect && connect
+
+      # ---- Cypher ------------------------------------------------------------
+      # Executes a Cypher query, or at least raises an error about it.
+      # @raise [NotImplementedError] Always, unless implemented by subclass.
+      def execute_cypher(*)
+        raise NotImplementedError, "#{self.class} must implement #execute_cypher"
+      end
+
+      # ---- transactions (optional) ------------------------------------------
+      # Transaction methods: for when you want to pretend you have ACID.
+      def begin_transaction       = nil
+      def commit_transaction(_)   = true
+      def rollback_transaction(_) = true
+
+      # ---- helpers -----------------------------------------------------------
+      # Prepares parameters for Cypher, because the database can't read your mind. Yet.
+      # @param raw [Object] The raw parameter value
+      # @return [Object] The prepared parameter
+      def prepare_params(raw)
+        case raw
+        when Hash  then raw.transform_keys(&:to_s).transform_values { |v| prepare_params(v) }
+        when Array then raw.each_with_index.to_h { |v, i| ["p#{i + 1}", prepare_params(v)] }
+        when Time, Date, DateTime then raw.iso8601
+        when Symbol then raw.to_s
+        else raw # String/Integer/Float/Boolean/NilClass
+        end
+      end
+
+      # Turns rows into symbols, because Rubyists fear strings.
+      # @param rows [Array<Hash>] The rows to process
+      # @return [Array<Hash>] The processed rows
+      def process_records(rows) = rows.map { |r| deep_symbolize(r) }
+
+      private
+
+      # Recursively turns everything into symbols, because that's what all the cool kids do.
+      # @param obj [Object] The object to symbolize
+      # @return [Object] The symbolized object
+      def deep_symbolize(obj)
+        case obj
+        when Hash  then obj.transform_keys(&:to_sym).transform_values { |v| deep_symbolize(v) }
+        when Array then obj.map { |v| deep_symbolize(v) }
+        else obj
+        end
+      end
+
+      # Returns the logger, or creates a new one if Rails isn't watching.
+      # @return [Logger] The logger instance
+      def logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
+    end
+  end
+end

data/lib/active_cypher/connection_adapters/abstract_bolt_adapter.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module ActiveCypher
+  module ConnectionAdapters
+    # Abstract adapter for Bolt-based graph databases.
+    # Concrete subclasses must provide protocol_handler_class, validate_connection, and execute_cypher.
+    # It's like ActiveRecord::ConnectionAdapter, but for weirdos like me who use graph databases.
+    class AbstractBoltAdapter < AbstractAdapter
+      attr_reader :connection
+
+      # Establish a connection if not already active.
+      # This includes auth token prep, URI parsing, and quiet suffering.
+      def connect
+        return true if active?
+
+        # Determine host and port from config
+        host, port = if config[:uri]
+                       # Legacy URI format
+                       uri = URI(config[:uri])
+                       [uri.host, uri.port || 7687]
+                     else
+                       # New URL format via ConnectionUrlResolver
+                       [config[:host] || 'localhost', config[:port] || 7687]
+                     end
+
+        # Prepare auth token
+        auth = if config[:username]
+                 { scheme: 'basic', principal: config[:username], credentials: config[:password] }
+               else
+                 { scheme: 'none' }
+               end
+
+        @connection = Bolt::Connection.new(
+          host, port, self,
+          auth_token: auth, timeout_seconds: config.fetch(:timeout, 15)
+        )
+        @connection.connect
+        validate_connection
+      end
+
+      # Connection health check. If this returns false, you're probably in trouble.
+      def active? = @connection&.connected?
+
+      # Clean disconnection. Resets the internal state.
+      def disconnect
+        @connection&.close
+        @connection = nil
+        true
+      end
+
+      # Runs a Cypher query via Bolt session.
+      # Automatically handles connect, logs query, cleans up session. Very adult.
+      def run(cypher, params = {}, context: 'Query', db: nil, access_mode: :write)
+        connect
+        logger.debug { "[#{context}] #{cypher} #{params.inspect}" }
+        session = Bolt::Session.new(connection, default_db: db)
+        result  = session.run(cypher, prepare_params(params), access_mode:)
+        rows    = result.respond_to?(:to_a) ? result.to_a : result
+        session.close
+        rows
+      end
+
+      # Convert access mode to database-specific format
+      def convert_access_mode(mode)
+        mode.to_s # Default implementation
+      end
+
+      # Prepare transaction metadata with database-specific attributes
+      def prepare_tx_metadata(metadata, _db, _access_mode)
+        metadata # Default implementation
+      end
+
+      # Create a protocol handler for the connection
+      def create_protocol_handler(connection)
+        protocol_handler_class.new(connection)
+        # Return handler for connection to store
+      end
+
+      protected
+
+      # These must be defined by subclasses. If you don't override them,
+      # you will be publicly shamed by a NotImplementedError.
+      def protocol_handler_class = raise(NotImplementedError)
+      def validate_connection = raise(NotImplementedError)
+      def execute_cypher(*) = raise(NotImplementedError)
+
+      private
+
+      # ------------------------------------------------------------------
+      # DANGER‑ZONE ‑‑ full‑graph eraser
+      #
+      # 🔥  Use *only* when you're absolutely certain, or when you need
+      #     a dramatic way to prove you're "senior‑material."  (Nothing
+      #     says "promotion potential" like nuking the staging graph in
+      #     front of the team, right?)
+      #
+      # Call it with:
+      #   adapter.send(:wipe_database, confirm: "yes, really")
+      #
+      # Options:
+      #   :confirm => string   # mandatory safety latch
+      #   :batch   => integer  # optional batch size for huge graphs
+      #
+      # Returns true on success.
+      # ------------------------------------------------------------------
+      def wipe_database(confirm:, batch: nil)
+        raise 'Refusing to wipe without explicit confirmation' unless confirm == 'yes, really'
+
+        if batch
+          # Manual batch wipe in case of ginormous graphs.
+          loop do
+            deleted = execute_cypher(<<~CYPHER, {}, 'Batch‑Delete')
+              CALL {
+                MATCH ()-[r]-()
+                WITH r LIMIT #{batch}
+                DELETE r
+                RETURN count(r) AS rels
+              }
+              CALL {
+                MATCH (n)
+                WITH n LIMIT #{batch}
+                DELETE n
+                RETURN count(n) AS nodes
+              }
+              RETURN rels + nodes AS total
+            CYPHER
+            break if deleted.first[:total].zero?
+          end
+        else
+          # Regular wipe: burn it all.
+          execute_cypher('MATCH (n) DETACH DELETE n', {}, 'WipeDB')
+        end
+        true
+      end
+
+      # ------------------------------------------------------------------
+      # Converts a Bolt‑encoded Node into a simple Ruby hash.
+      # Because we just want the props, not a dissertation on labels.
+      # ------------------------------------------------------------------
+      def process_node(bolt_array)
+        return bolt_array unless bolt_array.is_a?(Array) && bolt_array.first == 78
+
+        _id, _labels, props = bolt_array[1] # we only care about the props
+        props
+      end
+    end
+
+    # ------------------------------------------------------------------
+    # AbstractProtocolHandler
+    # Handles low‑level connection protocol things like version parsing
+    # and resetting the session state. It's like a janitor for Bolt.
+    # ------------------------------------------------------------------
+    class AbstractProtocolHandler
+      attr_reader :connection, :server_version
+
+      def initialize(connection)
+        @connection      = connection
+        @server_version  = extract_version(connection.server_agent.to_s)
+      end
+
+      # Extract the server version string from the agent header.
+      # Subclass this if you want to pretend you're compatible.
+      def extract_version(_agent) = 'unknown'
+
+      # Sends a Bolt RESET to clear the server's mental state.
+      # Great for when you've made a mess and don't want to talk about it.
+      def reset!
+        connection.write_message(Bolt::Messaging::Reset.new)
+        msg = connection.read_message
+        msg.is_a?(Bolt::Messaging::Success)
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/active_cypher/connection_adapters/memgraph_adapter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module ConnectionAdapters
+    class MemgraphAdapter < AbstractBoltAdapter
+      # Memgraph defaults to **implicit auto‑commit** transactions :contentReference[oaicite:1]{index=1},
+      # so we simply run the Cypher and return the rows.
+      def execute_cypher(cypher, params = {}, ctx = 'Query')
+        rows = run(cypher.gsub(/\belementId\(/i, 'id('), params, context: ctx)
+        process_records(rows)
+      end
+
+      # Implement database-specific methods for Memgraph
+
+      def convert_access_mode(mode)
+        # Memgraph doesn't distinguish between read/write modes
+        # but we'll keep the conversion here for consistency
+        mode.to_s
+      end
+
+      def prepare_tx_metadata(metadata, _db, _access_mode)
+        # Memgraph doesn't use db or access_mode in metadata
+        # but we'll ensure metadata is returned with compact
+        metadata.compact
+      end
+
+      protected
+
+      def protocol_handler_class = ProtocolHandler
+
+      def validate_connection
+        raise ActiveCypher::ConnectionError, "Server at #{config[:uri]} is not Memgraph" unless connection.server_agent.to_s.include?('Memgraph')
+
+        true
+      end
+
+      class ProtocolHandler < AbstractProtocolHandler
+        def extract_version(agent)
+          agent[%r{Memgraph/([\d.]+)}, 1] || 'unknown'
+        end
+      end
+    end
+  end
+end

data/lib/active_cypher/connection_adapters/neo4j_adapter.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ActiveCypher
+  module ConnectionAdapters
+    class Neo4jAdapter < AbstractBoltAdapter
+      def execute_cypher(cypher, params = {}, ctx = 'Query')
+        connect
+        session = connection.session # thin wrapper around Bolt::Session
+        result  = session.write_transaction do |tx|
+          logger.debug { "[#{ctx}] #{cypher} #{params.inspect}" }
+          tx.run(cypher, prepare_params(params))
+        end
+        process_records(result.to_a)
+      ensure
+        session&.close
+      end
+
+      # Explicit TX helpers — optional but handy.
+      def begin_transaction = (@tx = @connection.session.begin_transaction)
+      def commit_transaction(_)   = @tx&.commit
+      def rollback_transaction(_) = @tx&.rollback
+
+      # Implement database-specific methods
+
+      def convert_access_mode(mode)
+        case mode.to_s
+        when 'r', 'read'
+          'r'
+        when 'w', 'write'
+          'w'
+        else
+          'w' # Default to write
+        end
+      end
+
+      def prepare_tx_metadata(metadata, db, access_mode)
+        # Handle Neo4j-specific metadata
+        metadata['db'] = db if db
+        metadata['mode'] = convert_access_mode(access_mode)
+        metadata.compact
+      end
+
+      protected
+
+      def protocol_handler_class = ProtocolHandler
+
+      def validate_connection
+        raise ActiveCypher::ConnectionError, "Server at #{config[:uri]} is not Neo4j" unless connection.server_agent.to_s.include?('Neo4j/')
+
+        true
+      end
+
+      class ProtocolHandler < AbstractProtocolHandler
+        def extract_version(agent) = agent[%r{Neo4j/([\d.]+)}, 1] || 'unknown'
+      end
+    end
+  end
+end