activecypher 0.14.2 → 0.15.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4c164d949a4eedae68ef59d998e8957201ac57e7710ebfc5a599e82254506262
-  data.tar.gz: 6e318063e49efaad59dcee182e1be1f2f6992a296144f0b3c96fd296b6d2a6a5
+  metadata.gz: dc6fb1ecc443117671c36c2b287b44d0059d706c8543ef113915fe0c67e8063d
+  data.tar.gz: 7f7a6e862f2c146dc19e89827e2b0ab2333bcc58f801b07a78e3e0c89f17fc6f
 SHA512:
-  metadata.gz: 560dfa5c4ead5c8d9e8ac6a14925859bd684bc13ec7b1e9e5d42e010240d23dee11985b8aeecbc419fdcca9911671f08d939486a641b0e1ff8cd2517b5192750
-  data.tar.gz: 33c472bdab0d4b5011c82431a12fe263002043b7337550fe89babb1f09388ca9afb772a4ff7a1eeb2081000d1b2a8dcb61faa80fb3fda4720574bde006071bc0
+  metadata.gz: 6cd38267fc15f40e53c9d9d79d11fe52138cc20aa93290043e2aae7834616b6d78afb952a7c1c1ad6baf8e08531170618e43f297d70074c9db806928cd89b807
+  data.tar.gz: c2b0186231f35c838a56272ff6222f64af8a7be53891c8ed90260e297acdccef42992f28b65729ff61410172570cdcd92209c3c817d920d30341cc88906be9ff

data/lib/active_cypher/associations/collection_proxy.rb

@@ -37,12 +37,15 @@ module ActiveCypher
         load_target unless @records
         @records.each(&)
       end
-      alias to_a each
+
+      def to_a
+        each.to_a
+      end
 
       # Returns the size, because counting things is the only certainty in life.
       #
       # @return [Integer] The number of records in the collection
-      def size   = load_target.size
+      def size = load_target.size
       alias length size
 
       # Fully refresh from the database.

data/lib/active_cypher/associations.rb

@@ -114,14 +114,20 @@ module ActiveCypher
 
           # Resolve the target node class
           target_class = target_class_name.constantize
-          a_alias = :start
-          b_alias = :target
 
-          # Pattern nodes (immutable)
-          a_node = Cyrel::Pattern::Node.new(a_alias, labels: self.class.label_name)
-          b_node = Cyrel::Pattern::Node.new(b_alias, labels: target_class.label_name)
+          owner_alias   = :start
+          related_alias = :target
+
+          # owner = the node we're querying from (self)
+          # related = the node we want to fetch
+          owner_node   = Cyrel::Pattern::Node.new(owner_alias,   labels: self.class.label_name)
+          related_node = Cyrel::Pattern::Node.new(related_alias, labels: target_class.label_name)
 
-          # Relationship pattern with correct direction
+          # The relationship token renders the arrow direction itself:
+          #   :out  → -[:TYPE]->   e.g. (start:Person)-[:ENJOYS]->(target:Activity)
+          #   :in   → <-[:TYPE]-   e.g. (start:Activity)<-[:ENJOYS]-(target:Person)
+          #   :both → -[:TYPE]-    e.g. (start)-[:TYPE]-(target)
+          # Node order is always [owner, rel, related] — never swapped.
           rel_direction = case direction
                           when :out  then Cyrel::Direction::OUT
                           when :in   then Cyrel::Direction::IN
@@ -133,17 +139,13 @@ module ActiveCypher
             direction: rel_direction
           )
 
-          # Build undirected / outgoing / incoming path
-          path = case direction
-                 when :in then Cyrel::Pattern::Path.new([b_node, rel_node, a_node])
-                 else Cyrel::Pattern::Path.new([a_node, rel_node, b_node])
-                 end
+          path = Cyrel::Pattern::Path.new([owner_node, rel_node, related_node])
 
           # Compose query  MATCH – WHERE – RETURN
           query = Cyrel::Query.new
                               .match(path)
-                              .where(Cyrel.node_id(a_alias).eq(internal_id))
-                              .return_(b_alias)
+                              .where(Cyrel.node_id(owner_alias).eq(internal_id))
+                              .return_(related_alias)
 
           base_relation = Relation.new(target_class, query)
 
@@ -283,6 +285,12 @@ module ActiveCypher
           instance_variable_set(instance_var, associate)
         end
 
+        define_build_and_create_methods(name, target_class_name)
+      end
+
+      # Defines build_<name> and create_<name> for singular associations
+      # (shared by belongs_to and has_one).
+      def define_build_and_create_methods(name, target_class_name)
         # Define build method (e.g., build_author(name: "New Author"))
         define_method("build_#{name}") do |attributes = {}|
           target_class = target_class_name.constantize
@@ -429,25 +437,7 @@ module ActiveCypher
           instance_variable_set(instance_var, associate)
         end
 
-        # Define build method (e.g., build_profile(data: {...}))
-        define_method("build_#{name}") do |attributes = {}|
-          target_class = target_class_name.constantize
-          # TODO: Potentially set the inverse association reference here
-          # For now, just instantiate the target class
-          target_class.new(attributes)
-        end
-
-        # Define create method (e.g., create_profile(data: {...}))
-        define_method("create_#{name}") do |attributes = {}|
-          # Build the instance
-          instance = public_send("build_#{name}", attributes)
-          # Save the instance
-          instance.save
-          # If save is successful, associate it using the = method
-          public_send("#{name}=", instance) if instance.persisted?
-          # Return the instance
-          instance
-        end
+        define_build_and_create_methods(name, target_class_name)
       end
     end
 

data/lib/active_cypher/base.rb

@@ -13,7 +13,7 @@ module ActiveCypher
   class Base
     # @!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: {}
+    class_attribute :connects_to_mappings, default: { reading: :primary, writing: :primary }
 
     # Rails/ActiveModel foundations
     include Logging
@@ -30,6 +30,7 @@ module ActiveCypher
     include Model::Querying
     include Model::Abstract
     include Model::Attributes
+    include Model::ConnectionHandling
     include Model::ConnectionOwner
     include Model::Persistence
     include Model::Destruction
@@ -44,7 +45,7 @@ module ActiveCypher
         # Determine the current role (e.g., :writing, :reading)
         # ActiveCypher::RuntimeRegistry.current_role defaults to :writing
         # Only use db_key for pool lookup
-        mapping = connects_to_mappings if respond_to?(:connects_to_mappings)
+        mapping = connects_to_mappings
         role = ActiveCypher::RuntimeRegistry.current_role || :writing
         # Debug guardrails removed in release code; rely on role/shard registry.
 
@@ -82,6 +83,17 @@ module ActiveCypher
       "#<#{self.class} #{parts.join(', ')}>"
     end
 
+    def internal_id
+      working_id = super
+      return working_id if working_id.nil?
+
+      if connection.respond_to?(:id_type_conversion)
+        connection.id_type_conversion(working_id)
+      else
+        working_id
+      end
+    end
+
     # Because Rails needs to feel included, too.
     ActiveSupport.run_load_hooks(:active_cypher, self)
   end

data/lib/active_cypher/bolt/connection.rb

@@ -485,7 +485,6 @@ module ActiveCypher
         session(database: db).write_transaction(db: db, timeout: timeout, metadata: metadata, &)
       end
 
-
       # ────────────────────────────────────────────────────────────────────
       # HEALTH AND VERSION DETECTION METHODS
       # ────────────────────────────────────────────────────────────────────
@@ -514,21 +513,17 @@ module ActiveCypher
       def health_check
         return { healthy: false, response_time_ms: nil, details: 'Not connected' } unless connected?
 
-        result = nil
+        nil
 
         begin
-          result = Sync do
-            case database_type
-            when :neo4j
-              perform_neo4j_health_check
-            when :memgraph
-              perform_memgraph_health_check
-            else
-              perform_generic_health_check
-            end
+          Sync do
+            query = case database_type
+                    when :neo4j then 'RETURN 1 AS result'
+                    when :memgraph then 'SHOW STORAGE INFO'
+                    else 'RETURN 1'
+                    end
+            perform_health_check_query(query)
           end
-
-          result
         rescue ConnectionError, ProtocolError => e
           { healthy: false, response_time_ms: nil, details: "Health check failed: #{e.message}" }
         end
@@ -707,96 +702,15 @@ module ActiveCypher
         }
       end
 
-      # Performs Neo4j-specific health check using RETURN 1 (fallback from db.ping).
-      #
-      # @return [Hash] health check result
-      def perform_neo4j_health_check
-        start_time = Time.now
-
-        begin
-          write_message(Messaging::Run.new('RETURN 1 AS result', {}, {}), 'HEALTH_CHECK')
-          run_response = read_message
-
-          case run_response
-          when Messaging::Success
-            # Send PULL message to complete the transaction
-            write_message(Messaging::Pull.new({ 'n' => -1 }), 'PULL')
-
-            # Read messages until we get SUCCESS or FAILURE
-            response_time = nil
-            loop do
-              msg = read_message
-              case msg
-              when Messaging::Record
-                # Skip records, we just want to know if the query succeeded
-                next
-              when Messaging::Success
-                response_time = ((Time.now - start_time) * 1000).round(2)
-                return { healthy: true, response_time_ms: response_time, details: 'RETURN 1 succeeded' }
-              when Messaging::Failure
-                return { healthy: false, response_time_ms: nil, details: 'RETURN 1 failed with error' }
-              else
-                return { healthy: false, response_time_ms: nil, details: 'RETURN 1 unexpected response' }
-              end
-            end
-          else
-            { healthy: false, response_time_ms: nil, details: 'RETURN 1 run failed' }
-          end
-        ensure
-          # Reset connection state after health check
-          reset!
-        end
-      end
-
-      # Performs Memgraph-specific health check using SHOW STORAGE INFO.
-      #
-      # @return [Hash] health check result
-      def perform_memgraph_health_check
-        start_time = Time.now
-
-        begin
-          write_message(Messaging::Run.new('SHOW STORAGE INFO', {}, {}), 'HEALTH_CHECK')
-          run_response = read_message
-
-          case run_response
-          when Messaging::Success
-            # Send PULL message to complete the transaction
-            write_message(Messaging::Pull.new({ 'n' => -1 }), 'PULL')
-
-            # Read messages until we get SUCCESS or FAILURE
-            response_time = nil
-            loop do
-              msg = read_message
-              case msg
-              when Messaging::Record
-                # Skip records, we just want to know if the query succeeded
-                next
-              when Messaging::Success
-                response_time = ((Time.now - start_time) * 1000).round(2)
-                return { healthy: true, response_time_ms: response_time, details: 'SHOW STORAGE INFO succeeded' }
-              when Messaging::Failure
-                return { healthy: false, response_time_ms: nil, details: 'SHOW STORAGE INFO failed with error' }
-              else
-                return { healthy: false, response_time_ms: nil, details: 'SHOW STORAGE INFO unexpected response' }
-              end
-            end
-          else
-            { healthy: false, response_time_ms: nil, details: 'SHOW STORAGE INFO run failed' }
-          end
-        ensure
-          # Reset connection state after health check
-          reset!
-        end
-      end
-
-      # Performs generic health check using simple RETURN 1 query.
+      # Performs a health check by running the given query and draining the result.
       #
+      # @param query [String] database-appropriate health check query
       # @return [Hash] health check result
-      def perform_generic_health_check
+      def perform_health_check_query(query)
         start_time = Time.now
 
         begin
-          write_message(Messaging::Run.new('RETURN 1', {}, {}), 'HEALTH_CHECK')
+          write_message(Messaging::Run.new(query, {}, {}), 'HEALTH_CHECK')
           run_response = read_message
 
           case run_response
@@ -814,15 +728,15 @@ module ActiveCypher
                 next
               when Messaging::Success
                 response_time = ((Time.now - start_time) * 1000).round(2)
-                return { healthy: true, response_time_ms: response_time, details: 'RETURN 1 succeeded' }
+                return { healthy: true, response_time_ms: response_time, details: "#{query} succeeded" }
               when Messaging::Failure
-                return { healthy: false, response_time_ms: nil, details: 'RETURN 1 failed with error' }
+                return { healthy: false, response_time_ms: nil, details: "#{query} failed with error" }
               else
-                return { healthy: false, response_time_ms: nil, details: 'RETURN 1 unexpected response' }
+                return { healthy: false, response_time_ms: nil, details: "#{query} unexpected response" }
               end
             end
           else
-            { healthy: false, response_time_ms: nil, details: 'RETURN 1 run failed' }
+            { healthy: false, response_time_ms: nil, details: "#{query} run failed" }
           end
         ensure
           # Reset connection state after health check

data/lib/active_cypher/bolt/driver.rb

@@ -40,9 +40,9 @@ module ActiveCypher
       #
       # @yieldparam session [Bolt::Session] The session to use
       # @return [Object] The result of the block
-      def with_session(**kw, &block)
+      def with_session(**kw, &)
         Sync do
-          _acquire_session(**kw, &block)
+          _acquire_session(**kw, &)
         end
       rescue Async::TimeoutError => e
         raise ActiveCypher::ConnectionError, "Connection pool timeout: #{e.message}"
@@ -55,11 +55,11 @@ module ActiveCypher
       #
       # @yieldparam session [Bolt::Session] The session to use
       # @return [Async::Task] A task that resolves to the block's result
-      def async_with_session(**kw, &block)
+      def async_with_session(**kw, &)
         raise 'Cannot run async_with_session outside of an Async task' unless Async::Task.current?
 
         Async do
-          _acquire_session(**kw, &block)
+          _acquire_session(**kw, &)
         end
       end
 

data/lib/active_cypher/bolt/messaging.rb

@@ -67,13 +67,12 @@ module ActiveCypher
         end
       end
 
-      # The HELLO message. Because every protocol needs to start with a greeting before the disappointment.
-      class Hello < Message
-        SIGNATURE = 0x01
-
+      # Base for messages whose single field is a normalized metadata map.
+      # Subclasses only need to define their SIGNATURE.
+      class MetadataMessage < Message
         def initialize(metadata)
           meta = Messaging.normalize_map(metadata)
-          super(SIGNATURE, [meta])
+          super(self.class::SIGNATURE, [meta])
         end
 
         def metadata
@@ -81,22 +80,27 @@ module ActiveCypher
         end
       end
 
-      # The GOODBYE message. For when you've had enough of this session, or life.
-      class Goodbye < Message
-        SIGNATURE = 0x02
-
+      # Base for messages that carry no fields at all.
+      # Subclasses only need to define their SIGNATURE.
+      class EmptyMessage < Message
         def initialize
-          super(SIGNATURE, [])
+          super(self.class::SIGNATURE, [])
         end
       end
 
+      # The HELLO message. Because every protocol needs to start with a greeting before the disappointment.
+      class Hello < MetadataMessage
+        SIGNATURE = 0x01
+      end
+
+      # The GOODBYE message. For when you've had enough of this session, or life.
+      class Goodbye < EmptyMessage
+        SIGNATURE = 0x02
+      end
+
       # The RESET message. Because sometimes you just want to pretend nothing ever happened.
-      class Reset < Message
+      class Reset < EmptyMessage
         SIGNATURE = 0x0F
-
-        def initialize
-          super(SIGNATURE, [])
-        end
       end
 
       # The RUN message. Because what else would you do with a database connection?
@@ -148,115 +152,52 @@ module ActiveCypher
       end
 
       # The COMMIT message. For when you want to pretend your changes are permanent.
-      class Commit < Message
+      class Commit < EmptyMessage
         SIGNATURE = 0x12
-
-        def initialize
-          super(SIGNATURE, [])
-        end
       end
 
       # The ROLLBACK message. Because sometimes you just want to undo your mistakes.
-      class Rollback < Message
+      class Rollback < EmptyMessage
         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
+      class Discard < MetadataMessage
         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']
+        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
+      class Pull < MetadataMessage
         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
+      class Route < MetadataMessage
         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
+      class Logon < MetadataMessage
         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
+      class Logoff < EmptyMessage
         SIGNATURE = 0x6B
-
-        def initialize
-          super(SIGNATURE, [])
-        end
       end
 
       # The TELEMETRY message. Because someone, somewhere, cares about your metrics. Probably.
-      class Telemetry < Message
+      class Telemetry < MetadataMessage
         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
+      class Success < MetadataMessage
         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.
@@ -273,27 +214,14 @@ module ActiveCypher
       end
 
       # The IGNORED message. For when the server just can't be bothered.
-      class Ignored < Message
+      class Ignored < EmptyMessage
         SIGNATURE = 0x7E
-
-        def initialize
-          super(SIGNATURE, [])
-        end
       end
 
       # The FAILURE message. The most honest message in the protocol.
-      class Failure < Message
+      class Failure < MetadataMessage
         SIGNATURE = 0x7F
 
-        def initialize(metadata)
-          meta = Messaging.normalize_map(metadata)
-          super(SIGNATURE, [meta])
-        end
-
-        def metadata
-          fields.first
-        end
-
         def code
           metadata['code']
         end

data/lib/active_cypher/bolt/packstream.rb

@@ -89,18 +89,7 @@ module ActiveCypher
         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
+          write_collection_marker(map.size, TINY_MAP_MARKER_BASE, MAP_8_MARKER, MAP_16_MARKER, 'Map')
 
           map.each do |key, value|
             pack(key.to_s) # Keys must be strings
@@ -109,21 +98,24 @@ module ActiveCypher
         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
+          write_collection_marker(list.size, TINY_LIST_MARKER_BASE, LIST_8_MARKER, LIST_16_MARKER, 'List')
 
           list.each { |item| pack(item) }
         end
 
+        # Writes the size marker shared by maps and lists (tiny / 8-bit / 16-bit).
+        def write_collection_marker(size, tiny_base, marker8, marker16, label)
+          if size < 16 # Tiny
+            write_marker([tiny_base | size].pack('C'))
+          elsif size < 256 # 8-bit size
+            write_marker([marker8, size].pack('CC'))
+          elsif size < 65_536 # 16-bit size ('n' is network byte order)
+            write_marker([marker16, size].pack('Cn'))
+          else
+            raise ProtocolError, "#{label} too large to pack (size: #{size})"
+          end
+        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

data/lib/active_cypher/connection_adapters/abstract_adapter.rb

@@ -54,7 +54,23 @@ module ActiveCypher
       # @param node_alias [Symbol] The alias used for the node in the query
       # @return [Hash] The hydrated attributes
       def hydrate_record(record, node_alias)
-        raise NotImplementedError, "#{self.class} must implement #hydrate_record"
+        attrs = {}
+        node_data = record[node_alias] || record[node_alias.to_s]
+
+        if node_data.is_a?(Array) && node_data.length >= 2
+          properties_container = node_data[1]
+          if properties_container.is_a?(Array) && properties_container.length >= 3
+            properties = properties_container[2]
+            properties.each { |k, v| attrs[k.to_sym] = v } if properties.is_a?(Hash)
+          end
+        elsif node_data.is_a?(Hash)
+          node_data.each { |k, v| attrs[k.to_sym] = v }
+        elsif node_data.respond_to?(:properties)
+          attrs = node_data.properties.symbolize_keys
+        end
+
+        attrs[:internal_id] = record[:internal_id] || record['internal_id']
+        attrs
       end
 
       # Turns rows into symbols, because Rubyists fear strings.