activecypher 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b78e44e773d760db977af2feadbb8da2feae14d361e530a9ce0c300b3488316e
-  data.tar.gz: 867b1beeed8d8f2a42d49b61c33be85fbc97e431b1a5d212ffdd676b9fc5cde3
+  metadata.gz: 7d529adab6eb5478a435e3061d317f742373617d8460b14f545d2b66b03cd37d
+  data.tar.gz: 35726eeafd44cc915e3731b3c4557e63f6ace655b87c28761e1ebc426d989af1
 SHA512:
-  metadata.gz: 6ab032c06695810f847c679dcadddec8af51c4c4a6c53425f04561cf92f2d558876b775cd40d535e40c66c654e33474752d7438eeb91fa5d2f3450b1fe46fd53
-  data.tar.gz: 14120d94c9f0fb83765631ab06efe2da72cf2939ea6d24a2fade76911384b4df0cc992f828aa55e10326730e3388b2703746647dcfc577d49c9245be70dfeedd
+  metadata.gz: 0cdb35c5ebeb4d5774a2ff203b6322ef26e1f1abcdaac97b93cea64125322454fdd95b6a91117ced49ea5391815b96e84f274f96fd57725f0de65b1916aef7cf
+  data.tar.gz: 258b065dc249ac957e7eed9025663dbbb12e7f0927dd7555793365bbbbbad36ffff4458aba48f99baedfecc02c214a490ba5e2cf68a9244d27a284291951f79f

data/lib/active_cypher/base.rb

@@ -11,12 +11,12 @@ module ActiveCypher
     include Logging
 
     # Let's just include every concern we can find, because why not.
+    include Model::Querying # Must be before Core so Core can override its methods
     include Model::Core
     include Model::Attributes
     include Model::ConnectionOwner
     include Model::Callbacks
     include Model::Persistence
-    include Model::Querying
     include Model::ConnectionHandling
     include Model::Destruction
     include Model::Abstract

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,6 +4,7 @@ module ActiveCypher
   module Bolt
     # Manages transaction state (BEGIN/COMMIT/ROLLBACK) and runs queries within a transaction.
     class Transaction
+      include Instrumentation
       attr_reader :bookmarks, :metadata
 
       # 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,7 +160,7 @@ 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)

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), 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
 

data/lib/active_cypher/connection_adapters/neo4j_adapter.rb

@@ -16,7 +16,7 @@ module ActiveCypher
       end
 
       # Explicit TX helpers — optional but handy.
-      def begin_transaction = (@tx = @connection.session.begin_transaction)
+      def begin_transaction(**) = (@tx = @connection.session.begin_transaction(**))
       def commit_transaction(_)   = @tx&.commit
       def rollback_transaction(_) = @tx&.rollback
 

data/lib/active_cypher/cypher_config.rb

@@ -15,6 +15,18 @@ module ActiveCypher
       env  ||= defined?(Rails) ? Rails.env : ENV.fetch('CY_ENV', 'development')
       file   = Pathname.new(path || default_path)
 
+      # Handle missing config file gracefully
+      unless file.exist?
+        # If requesting all configs, return empty hash
+        return {}.with_indifferent_access if name.to_s == '*'
+        # If silent missing is set, return nil for specific connection
+        return nil if ENV['ACTIVE_CYPHER_SILENT_MISSING'] == 'true'
+
+        # Otherwise, raise a descriptive error
+        raise "Could not load ActiveCypher configuration. No such file - #{file}. " \
+              "Please run 'rails generate active_cypher:install' to create the configuration file."
+      end
+
       ## ------------------------------------------------------------
       ## 1. Parse YAML using the same algorithm Rails::Application#config_for
       ##    uses (shared‑section merge, ERB, symbolize_keys, etc.)

data/lib/active_cypher/generators/node_generator.rb

@@ -7,6 +7,11 @@ module ActiveCypher
   module Generators
     class NodeGenerator < Rails::Generators::NamedBase
       source_root File.expand_path('templates', __dir__)
+      class_option :suffix, type: :string,
+                            desc: 'Suffix for the node class (default: Node)',
+                            default: 'Node'
+
+      check_class_collision suffix: 'Node'
 
       argument :attributes, type: :array,
                             default: [], banner: 'name:type name:type'
@@ -16,16 +21,40 @@ module ActiveCypher
                             default: ''
 
       def create_node_file
-        template 'node.rb.erb',
-                 File.join('app/graph', class_path, "#{file_name}.rb")
+        check_runtime_class_collision
+        template 'node.rb.erb', File.join('app/graph', class_path, "#{file_name}.rb")
       end
 
       private
 
+      def check_runtime_class_collision
+        suffix = node_suffix
+        base = name.camelize
+        class_name_with_suffix = base.end_with?(suffix) ? base : "#{base}#{suffix}"
+        return unless class_name_with_suffix.safe_constantize
+
+        raise Thor::Error, "Class collision: #{class_name_with_suffix} is already defined"
+      end
+
+      def node_suffix
+        options[:suffix] || 'Node'
+      end
+
+      def class_name
+        base = super
+        base.end_with?(node_suffix) ? base : "#{base}#{node_suffix}"
+      end
+
+      def file_name
+        base = super
+        suffix = "_#{node_suffix.underscore}"
+        base.end_with?(suffix) ? base : "#{base}#{suffix}"
+      end
+
       # helper for ERB
       def labels_list
         lbls = options[:labels].split(',').map(&:strip).reject(&:blank?)
-        lbls.empty? ? [class_name.gsub(/Node$/, '')] : lbls
+        lbls.empty? ? [class_name.gsub(/#{node_suffix}$/, '')] : lbls
       end
     end
   end

data/lib/active_cypher/generators/relationship_generator.rb

@@ -7,6 +7,9 @@ module ActiveCypher
   module Generators
     class RelationshipGenerator < Rails::Generators::NamedBase
       source_root File.expand_path('templates', __dir__)
+      class_option :suffix, type: :string,
+                            desc: 'Suffix for the relationship class (default: Rel)',
+                            default: 'Rel'
 
       argument :attributes, type: :array,
                             default: [], banner: 'name:type name:type'
@@ -19,12 +22,36 @@ module ActiveCypher
                            desc: 'Cypher relationship type (defaults to class name)'
 
       def create_relationship_file
-        template 'relationship.rb.erb',
-                 File.join('app/graph', class_path, "#{file_name}.rb")
+        check_runtime_class_collision
+        template 'relationship.rb.erb', File.join('app/graph', class_path, "#{file_name}.rb")
       end
 
       private
 
+      def relationship_suffix
+        options[:suffix] || 'Rel'
+      end
+
+      def class_name
+        base = super
+        base.end_with?(relationship_suffix) ? base : "#{base}#{relationship_suffix}"
+      end
+
+      def file_name
+        base = super
+        suffix = "_#{relationship_suffix.underscore}"
+        base.end_with?(suffix) ? base : "#{base}#{suffix}"
+      end
+
+      def check_runtime_class_collision
+        suffix = relationship_suffix
+        base = name.camelize
+        class_name_with_suffix = base.end_with?(suffix) ? base : "#{base}#{suffix}"
+        return unless class_name_with_suffix.safe_constantize.present?
+
+        raise Thor::Error, "Class collision: #{class_name_with_suffix} is already defined"
+      end
+
       def relationship_type
         (options[:type].presence || class_name).upcase
       end