activecypher 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56e09b9d8193d2c4c745c1973bb420ba83854cbe0b578d5d37d4e215c96c7687
-  data.tar.gz: a53e722376ff97ae59c6fc0735c16eb15b9e2fe89fe45cda6d42c5d45237a97f
+  metadata.gz: 6116df314b95f0db74a73fcc1746f0e4bf9bd529d65ab04e806953103b4017b0
+  data.tar.gz: d85d13cbb5ad5a9b7434f3457d4dd3b2f899c47619dbdf00f129790466b19fbf
 SHA512:
-  metadata.gz: bd26475b4774f41f37b047c558707c7fe5282718c8970f1a24148c3f6ad57186ad7b0823051e06d420d80373605f8d28721b7f934dd64e0110b05050af6af7f9
-  data.tar.gz: 20b688e0788fe8dd84a51471ee2125d8ce8082304d4e9db724d4970b0e27da638fd4e541030982b582716d5ad1c1f86d1e88c3fbb3605437bab05c96a5e2b832
+  metadata.gz: 1e12458b40696e189c20cf480565446c2d2294cd2fe2b8208560dbb77ca27f38b4971f043c11531f229dee070b5950ca785906660e121b25f74d3157f89b3a38
+  data.tar.gz: 7dd4fbe5fc47b350789f7f55e55321238626e7bed731d56bb83d37417411f257fc53cb0b3a2223292ac64f9b971fd07d5d9a8f9fe666b8d49c872d83a9af60de

data/lib/active_cypher/base.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+require 'active_model'
+require 'active_model/validations'
+require 'active_model/callbacks'
+require 'active_model/attributes'
+require 'active_model/dirty'
+
 module ActiveCypher
   # @!parse
   #   # The One True Base Class. All node models must kneel before it.
@@ -8,18 +14,25 @@ module ActiveCypher
     # @!attribute [rw] connects_to_mappings
     #   @return [Hash] Because every base class needs a mapping it will never use directly.
     class_attribute :connects_to_mappings, default: {}
+
+    # Rails/ActiveModel foundations
     include Logging
+    include ActiveModel::Model
+    include ActiveModel::Validations
+    include ActiveModel::Callbacks
+    include ActiveModel::Attributes
+    include ActiveModel::Dirty
 
     # Let's just include every concern we can find, because why not.
     include Model::Core
+    include Model::Callbacks
+    include Model::Labelling
+    include Model::Querying
+    include Model::Abstract
     include Model::Attributes
     include Model::ConnectionOwner
-    include Model::Callbacks
     include Model::Persistence
-    include Model::Querying
-    include Model::ConnectionHandling
     include Model::Destruction
-    include Model::Abstract
     include Model::Countable
     include Model::Inspectable
 
@@ -29,15 +42,22 @@ module ActiveCypher
       # If you still don't have a connection, you get an error. It's the circle of life.
       # @return [Object] The connection instance
       def connection
-        if (pool = connection_handler.pool(current_role, current_shard))
-          return pool.connection
+        # Determine the current role (e.g., :writing, :reading)
+        # ActiveCypher::RuntimeRegistry.current_role defaults to :writing
+        # Only use db_key for pool lookup
+        if respond_to?(:connects_to_mappings) && connects_to_mappings.is_a?(Hash)
+          db_key = connects_to_mappings[:writing] # or whichever role is appropriate
+          if db_key && (pool = connection_handler.pool(db_key))
+            return pool.connection
+          end
         end
 
-        # fall back to a per‑model connection created by establish_connection
         return @connection if defined?(@connection) && @connection&.active?
 
         raise ActiveCypher::ConnectionNotEstablished,
-              "No pool for role=#{current_role.inspect} shard=#{current_shard.inspect}"
+              "No connection pool found for graph #{name}, db_key=#{db_key.inspect}. " \
+              'Ensure `connects_to` is configured for this model or its ancestors, ' \
+              'and `cypher_databases.yml` has the corresponding entries.'
       end
     end
 

data/lib/active_cypher/bolt/driver.rb

@@ -12,31 +12,21 @@ module ActiveCypher
     class Driver
       DEFAULT_POOL_SIZE = ENV.fetch('BOLT_POOL_SIZE', 10).to_i
 
-      # Map URI schemes ➞ security/verification flags
-      # Because nothing says "enterprise" like six ways to spell 'bolt'.
-      SCHEMES = {
-        'bolt' => { secure: false, verify: true },
-        'bolt+s' => { secure: true, verify: true },
-        'bolt+ssc' => { secure: true, verify: false },
-        'neo4j' => { secure: false, verify: true },
-        'neo4j+s' => { secure: true, verify: true },
-        'neo4j+ssc' => { secure: true, verify: false }
-      }.freeze
-
       # Initializes the driver, because you can't spell "abstraction" without "action".
       #
       # @param uri [String] The Bolt URI
       # @param adapter [Object] The adapter instance
       # @param auth_token [Hash] Authentication token
       # @param pool_size [Integer] Connection pool size
-      def initialize(uri:, adapter:, auth_token:, pool_size: DEFAULT_POOL_SIZE)
-        @uri     = URI(uri)
-        scheme   = SCHEMES.fetch(@uri.scheme) { raise ArgumentError, "Unsupported Bolt scheme: #{@uri.scheme}" }
+      # @param secure [Boolean] Use SSL (default: false)
+      # @param verify_cert [Boolean] Verify SSL certificate (default: true)
+      def initialize(uri:, adapter:, auth_token:, pool_size: DEFAULT_POOL_SIZE, secure: false, verify_cert: true)
+        @uri = URI(uri)
 
         @adapter       = adapter
         @auth          = auth_token
-        @secure        = scheme[:secure]
-        @verify_cert   = scheme[:verify]
+        @secure        = secure
+        @verify_cert   = verify_cert
 
         # Create a connection pool with the specified size
         # Because one connection is never enough for true disappointment.

data/lib/active_cypher/bolt/session.rb

@@ -1,12 +1,12 @@
 # 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
+      include Instrumentation
       attr_reader :connection, :database
 
       def initialize(connection, database: nil)
@@ -34,13 +34,15 @@ module ActiveCypher
         # 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)
+        instrument_query(query, parameters, context: 'Session#run', metadata: { mode: mode, db: db }) do
+          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
       end
@@ -55,40 +57,46 @@ module ActiveCypher
       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}"
+        metadata = { access_mode: access_mode }
+        metadata[:db] = db if db
+        metadata[:timeout] = tx_timeout if tx_timeout
+
+        instrument_transaction(:begin, nil, metadata: metadata) do
+          # 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
       end
 
@@ -181,20 +189,24 @@ module ActiveCypher
       def reset
         return if @current_transaction.nil?
 
-        # Mark the current transaction as no longer active
-        complete_transaction(@current_transaction)
+        instrument('session.reset') do
+          # Mark the current transaction as no longer active
+          complete_transaction(@current_transaction)
 
-        # Reset the connection
-        @connection.reset!
+          # Reset the connection
+          @connection.reset!
+        end
       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?
+        instrument('session.close') do
+          # 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
+          # Mark current transaction as complete
+          complete_transaction(@current_transaction) if @current_transaction
+        end
       end
     end
   end

data/lib/active_cypher/bolt/transaction.rb

@@ -4,7 +4,8 @@ module ActiveCypher
   module Bolt
     # Manages transaction state (BEGIN/COMMIT/ROLLBACK) and runs queries within a transaction.
     class Transaction
-      attr_reader :bookmarks, :metadata
+      include Instrumentation
+      attr_reader :bookmarks, :metadata, :connection
 
       # Initializes a new Transaction instance.
       #
@@ -30,66 +31,68 @@ module ActiveCypher
         # 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}"
+        instrument_query(query_str, parameters, context: 'Transaction#run', metadata: { transaction_id: object_id }) do
+          # 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
-          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}"
+            # 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
         end
       rescue ConnectionError
         @state = :failed
@@ -102,42 +105,44 @@ module ActiveCypher
       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)
+        instrument_transaction(:commit, object_id) do
+          # Send COMMIT message
+          commit_msg = Messaging::Commit.new
+          connection.write_message(commit_msg)
 
-        # Read response to COMMIT
-        response = @connection.read_message
+          # Read response to COMMIT
+          response = connection.read_message
 
-        case response
-        when Messaging::Success
-          # COMMIT succeeded
+          case response
+          when Messaging::Success
+            # COMMIT succeeded
 
-          @state = :committed
+            @state = :committed
 
-          # Extract bookmarks if any
-          new_bookmarks = []
-          if response.metadata.key?('bookmark')
-            new_bookmarks = [response.metadata['bookmark']]
-            @bookmarks = new_bookmarks
-          end
+            # 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)
+            # 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']
+            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)
+            # 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}"
+            raise QueryError, "Failed to commit transaction: #{code} - #{message}"
+          else
+            raise ProtocolError, "Unexpected response to COMMIT: #{response.class}"
+          end
         end
       rescue ConnectionError
         @state = :failed
@@ -155,13 +160,13 @@ module ActiveCypher
         # If already committed or rolled back, do nothing
         return if @state == :committed || @state == :rolled_back
 
-        begin
+        instrument_transaction(:rollback, object_id) do
           # Send ROLLBACK message
           rollback_msg = Messaging::Rollback.new
-          @connection.write_message(rollback_msg)
+          connection.write_message(rollback_msg)
 
           # Read response to ROLLBACK
-          response = @connection.read_message
+          response = connection.read_message
 
           case response
           when Messaging::Success

data/lib/active_cypher/connection_adapters/abstract_adapter.rb

@@ -49,6 +49,34 @@ module ActiveCypher
         end
       end
 
+      # Get current adapter type for ID handling
+      # Helper for generating ID-related Cypher functions that are database-specific
+      module CypherFunction
+        # Generate ID equality clause with the ID value embedded in the query for Memgraph
+        def self.id_equals(var, id_value, adapter)
+          func = id_function(adapter)
+          "#{func}(#{var}) = #{id_value}"
+        end
+
+        # Generate ID equality clause using a parameterized ID value for Neo4j
+        def self.id_equals_param(var, param_name, adapter)
+          func = id_function(adapter)
+          "#{func}(#{var}) = $#{param_name}"
+        end
+
+        # Generate a node variable with ID predicate
+        def self.node_with_id(node_var, id_value, adapter)
+          func = id_function(adapter)
+          "#{func}(#{node_var}) = #{id_value}"
+        end
+
+        # Return ID expression
+        def self.return_id(var, as_name, adapter)
+          func = id_function(adapter)
+          "#{func}(#{var}) AS #{as_name}"
+        end
+      end
+
       # Turns rows into symbols, because Rubyists fear strings.
       # @param rows [Array<Hash>] The rows to process
       # @return [Array<Hash>] The processed rows

data/lib/active_cypher/connection_adapters/abstract_bolt_adapter.rb

@@ -8,6 +8,7 @@ module ActiveCypher
     # 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
+      include Instrumentation
       attr_reader :connection
 
       # Establish a connection if not already active.
@@ -15,29 +16,31 @@ module ActiveCypher
       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
+        instrument_connection(:connect, config) do
+          # 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
       end
 
       # Connection health check. If this returns false, you're probably in trouble.
@@ -45,9 +48,11 @@ module ActiveCypher
 
       # Clean disconnection. Resets the internal state.
       def disconnect
-        @connection&.close
-        @connection = nil
-        true
+        instrument_connection(:disconnect) do
+          @connection&.close
+          @connection = nil
+          true
+        end
       end
 
       # Runs a Cypher query via Bolt session.
@@ -55,11 +60,14 @@ module ActiveCypher
       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
+
+        instrument_query(cypher, params, context: context, metadata: { db: db, access_mode: access_mode }) do
+          session = Bolt::Session.new(connection, database: db)
+          result  = session.run(cypher, prepare_params(params), mode: access_mode)
+          rows    = result.respond_to?(:to_a) ? result.to_a : result
+          session.close
+          rows
+        end
       end
 
       # Convert access mode to database-specific format
@@ -84,7 +92,7 @@ module ActiveCypher
       # you will be publicly shamed by a NotImplementedError.
       def protocol_handler_class = raise(NotImplementedError)
       def validate_connection = raise(NotImplementedError)
-      def execute_cypher(*) = raise(NotImplementedError)
+      def execute_cypher(*) = raise(NotImplementedError, "#{self.class} must implement #execute_cypher")
 
       private