activecypher 0.10.4 → 0.11.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45703ee8a46ca012c9c4e6bd82708f3846bdea0fae15c4fb7fbff7a46d0fb3b3
-  data.tar.gz: 93e134bd2615288003c16c94159344b48023d3d593f45e47441483a5be3c02b1
+  metadata.gz: a39f60243be9073a1c3e2f05e1239239de9412d95184a321d22c4f582b0cdbdb
+  data.tar.gz: f125c98717432f24b3e0e28e4066f962cc2cb46bbab556bda52a44c3f4f12e7c
 SHA512:
-  metadata.gz: 9232c48290ea388ad7c49b4a3dfb4ffffc5f4493c33fa3000ad7936c40730f5c6b106a9190b61a52576d80f09c4632a903696f0c0c683332fd6c6325a2c9d7af
-  data.tar.gz: d48c94cf08b6aa3d1a7a9659b13fdde62fdb0ca444a281e97ccea3e28646bc0520702e3f90df59a0e9b2650b48a65e6170cedea896e2a7402901d6df7a5615dc
+  metadata.gz: 3bea961b864932446e0c667c7f88c9a428204f62089696b65d32dc62c4297e10e7d86e1f2ce67db8eb32e3a771944d882840b5d416345eed3296a3b23dec1d09
+  data.tar.gz: 1803663082f2fa06c7af69af355d0bd05ad78901c217c8b5f2aa2486b3adc009a6784d11b09731b1bd88d0b533e12420c13b11254b4b0852de5636b1e0d530f3

data/lib/active_cypher/base.rb

@@ -34,7 +34,6 @@ module ActiveCypher
     include Model::Persistence
     include Model::Destruction
     include Model::Countable
-    include Model::Inspectable
 
     class << self
       # Attempts to retrieve a connection from the handler.
@@ -61,6 +60,24 @@ module ActiveCypher
       end
     end
 
+    # Custom object inspection method for pretty-printing a compact,
+    # single-line summary of the object. Output examples:
+    #
+    #   #<UserNode id="26" name="Alice" age=34>   => persisted object
+    #   #<UserNode (new) name="Bob">              => object not yet saved
+    #
+    def inspect
+      # Put 'internal_id' first like it's the main character (even if it's nil)
+      ordered = attributes.dup
+      ordered = ordered.slice('internal_id').merge(ordered.except('internal_id'))
+
+      # Turn each attr into "key: value" because we humans fear raw hashes
+      parts = ordered.map { |k, v| "#{k}: #{v.inspect}" }
+
+      # Wrap it all up in a fake-sane object string, so you can pretend your data is organized.
+      "#<#{self.class} #{parts.join(', ')}>"
+    end
+
     # Because Rails needs to feel included, too.
     ActiveSupport.run_load_hooks(:active_cypher, self)
   end

data/lib/active_cypher/bolt/connection.rb

@@ -133,7 +133,7 @@ module ActiveCypher
       #
       # @note The digital equivalent of ghosting.
       def close
-        @socket&.close if connected?
+        @socket.close if connected?
       rescue IOError
       ensure
         @socket = nil
@@ -230,23 +230,13 @@ module ActiveCypher
       def viable?
         return false unless connected?
 
-        # Perform a lightweight check to verify the connection is still functional
-        begin
-          # Try to send a simple NOOP query to check connection health
-          write_message(Messaging::Run.new('RETURN 1', {}, {}), 'VIABILITY_CHECK')
-          read_message
-
-          # Reset the connection state
-          reset!
+        # Use the health check method to determine viability
+        health = health_check
 
-          # If we got a successful response, the connection is viable
+        if health[:healthy]
           true
-        rescue ConnectionError, ProtocolError
-          # If the connection is broken, close it and return false
-          close
-          false
-        rescue StandardError
-          # For any other errors, also consider the connection non-viable
+        else
+          # If health check failed, close the connection
           close
           false
         end
@@ -480,6 +470,110 @@ module ActiveCypher
         Bolt::Session.new(self, **)
       end
 
+      # Synchronously execute a read transaction.
+      def read_transaction(db: nil, timeout: nil, metadata: nil, &)
+        session(database: db).read_transaction(db: db, timeout: timeout, metadata: metadata, &)
+      end
+
+      # Synchronously execute a write transaction.
+      def write_transaction(db: nil, timeout: nil, metadata: nil, &)
+        session(database: db).write_transaction(db: db, timeout: timeout, metadata: metadata, &)
+      end
+
+      # Asynchronously execute a read transaction.
+      def async_read_transaction(db: nil, timeout: nil, metadata: nil, &)
+        session(database: db).async_read_transaction(db: db, timeout: timeout, metadata: metadata, &)
+      end
+
+      # Asynchronously execute a write transaction.
+      def async_write_transaction(db: nil, timeout: nil, metadata: nil, &)
+        session(database: db).async_write_transaction(db: db, timeout: timeout, metadata: metadata, &)
+      end
+
+      # ────────────────────────────────────────────────────────────────────
+      # HEALTH AND VERSION DETECTION METHODS
+      # ────────────────────────────────────────────────────────────────────
+
+      # Returns parsed version information from the server agent string.
+      #
+      # @return [Hash] version information with :database_type, :version, :major, :minor, :patch
+      # @note Extracts version from server_agent captured during handshake
+      def version
+        return @version if defined?(@version)
+
+        @version = parse_version_from_server_agent
+      end
+
+      # Returns the database type detected from server agent.
+      #
+      # @return [Symbol] :neo4j, :memgraph, or :unknown
+      def database_type
+        version[:database_type]
+      end
+
+      # Performs a health check using database-appropriate queries.
+      #
+      # @return [Hash] health check result with :healthy, :response_time_ms, :details
+      # @note Uses different queries based on detected database type
+      def health_check
+        return { healthy: false, response_time_ms: nil, details: 'Not connected' } unless connected?
+
+        result = nil
+
+        begin
+          Async do
+            result = case database_type
+                     when :neo4j
+                       perform_neo4j_health_check
+                     when :memgraph
+                       perform_memgraph_health_check
+                     else
+                       perform_generic_health_check
+                     end
+          end.wait
+
+          result
+        rescue ConnectionError, ProtocolError => e
+          { healthy: false, response_time_ms: nil, details: "Health check failed: #{e.message}" }
+        end
+      end
+
+      # Returns comprehensive database information.
+      #
+      # @return [Hash] database information including version, health, and system details
+      def database_info
+        info = version.dup
+        health = health_check
+
+        info.merge({
+                     healthy: health[:healthy],
+                     response_time_ms: health[:response_time_ms],
+                     server_agent: @server_agent,
+                     connection_id: @connection_id,
+                     protocol_version: @protocol_version
+                   })
+      end
+
+      # Returns server/cluster status information (when available).
+      #
+      # @return [Array<Hash>, nil] array of server status objects or nil if not supported
+      def server_status
+        return nil unless connected?
+
+        begin
+          case database_type
+          when :neo4j
+            get_neo4j_server_status
+          when :memgraph
+            get_memgraph_server_status
+          else
+            nil
+          end
+        rescue ConnectionError, ProtocolError
+          nil # Gracefully handle unsupported operations
+        end
+      end
+
       # ────────────────────────────────────────────────────────────────────
       # PRIVATE HELPER METHODS
       # ────────────────────────────────────────────────────────────────────
@@ -540,6 +634,317 @@ module ActiveCypher
       # @return [Boolean]
       # @note The Schrödinger's cat of sockets.
       def socket_open? = @socket && !@socket.closed?
+
+      # ────────────────────────────────────────────────────────────────────
+      # HEALTH AND VERSION DETECTION HELPERS
+      # ────────────────────────────────────────────────────────────────────
+
+      # Parses version information from the server_agent string.
+      #
+      # @return [Hash] parsed version information
+      def parse_version_from_server_agent
+        return default_version_info unless @server_agent
+
+        case @server_agent
+        when %r{^Neo4j/(\d+\.\d+(?:\.\d+)?)}i
+          version_string = ::Regexp.last_match(1)
+          parts = version_string.split('.').map(&:to_i)
+          {
+            database_type: :neo4j,
+            version: version_string,
+            major: parts[0] || 0,
+            minor: parts[1] || 0,
+            patch: parts[2] || 0
+          }
+        when %r{^Memgraph/(\d+\.\d+(?:\.\d+)?)}i
+          version_string = ::Regexp.last_match(1)
+          parts = version_string.split('.').map(&:to_i)
+          {
+            database_type: :memgraph,
+            version: version_string,
+            major: parts[0] || 0,
+            minor: parts[1] || 0,
+            patch: parts[2] || 0
+          }
+        when /.*Memgraph/i
+          # Handle Memgraph server agent: "Neo4j/v5.11.0 compatible graph database server - Memgraph"
+          if @server_agent =~ %r{Neo4j/v(\d+\.\d+(?:\.\d+)?)}
+            version_string = ::Regexp.last_match(1)
+            parts = version_string.split('.').map(&:to_i)
+            {
+              database_type: :memgraph,
+              version: version_string,
+              major: parts[0] || 0,
+              minor: parts[1] || 0,
+              patch: parts[2] || 0
+            }
+          else
+            {
+              database_type: :memgraph,
+              version: 'unknown',
+              major: 0,
+              minor: 0,
+              patch: 0
+            }
+          end
+        else
+          {
+            database_type: :unknown,
+            version: @server_agent,
+            major: 0,
+            minor: 0,
+            patch: 0
+          }
+        end
+      end
+
+      # Returns default version info when server_agent is not available.
+      #
+      # @return [Hash] default version information
+      def default_version_info
+        {
+          database_type: :unknown,
+          version: 'unknown',
+          major: 0,
+          minor: 0,
+          patch: 0
+        }
+      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.
+      #
+      # @return [Hash] health check result
+      def perform_generic_health_check
+        start_time = Time.now
+
+        begin
+          write_message(Messaging::Run.new('RETURN 1', {}, {}), '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
+
+      # Gets Neo4j server status using SHOW SERVERS query.
+      #
+      # @return [Array<Hash>] server status information
+      def get_neo4j_server_status
+        write_message(Messaging::Run.new('SHOW SERVERS', {}, {}), 'SERVER_STATUS')
+        response = read_message
+
+        case response
+        when Messaging::Success
+          servers = []
+
+          # Read records until we get SUCCESS
+          loop do
+            record_response = read_message
+            case record_response
+            when Messaging::Record
+              # Parse server record - this is a simplified version
+              servers << parse_neo4j_server_record(record_response)
+            when Messaging::Success
+              break
+            else
+              break
+            end
+          end
+
+          servers
+        else
+          []
+        end
+      ensure
+        reset!
+      end
+
+      # Gets Memgraph server status using SHOW DATABASES query.
+      #
+      # @return [Array<Hash>] database status information
+      def get_memgraph_server_status
+        write_message(Messaging::Run.new('SHOW DATABASES', {}, {}), 'SERVER_STATUS')
+        response = read_message
+
+        case response
+        when Messaging::Success
+          databases = []
+
+          # Read records until we get SUCCESS
+          loop do
+            record_response = read_message
+            case record_response
+            when Messaging::Record
+              # Parse database record
+              databases << parse_memgraph_database_record(record_response)
+            when Messaging::Success
+              break
+            else
+              break
+            end
+          end
+
+          databases
+        else
+          # Fallback to SHOW DATABASE for single database info
+          get_memgraph_current_database
+        end
+      ensure
+        reset!
+      end
+
+      # Gets current Memgraph database info using SHOW DATABASE.
+      #
+      # @return [Array<Hash>] current database information
+      def get_memgraph_current_database
+        write_message(Messaging::Run.new('SHOW DATABASE', {}, {}), 'CURRENT_DATABASE')
+        response = read_message
+
+        case response
+        when Messaging::Success
+          [{ name: 'current', status: 'active', type: 'memgraph' }]
+        else
+          []
+        end
+      ensure
+        reset!
+      end
+
+      # Parses a Neo4j server record from SHOW SERVERS result.
+      #
+      # @param record [Messaging::Record] the record message
+      # @return [Hash] parsed server information
+      def parse_neo4j_server_record(_record)
+        # Simplified parsing - in reality this would extract specific fields
+        {
+          name: 'server',
+          address: "#{@host}:#{@port}",
+          state: 'Enabled',
+          health: 'Available',
+          type: 'neo4j'
+        }
+      end
+
+      # Parses a Memgraph database record from SHOW DATABASES result.
+      #
+      # @param record [Messaging::Record] the record message
+      # @return [Hash] parsed database information
+      def parse_memgraph_database_record(_record)
+        # Simplified parsing
+        {
+          name: 'database',
+          status: 'active',
+          type: 'memgraph'
+        }
+      end
     end
   end
 end

data/lib/active_cypher/bolt/driver.rb

@@ -47,11 +47,7 @@ module ActiveCypher
             # Check if connection is viable before using it
             unless conn.viable?
               # Create a fresh connection, because hope springs eternal
-              begin
-                conn.close
-              rescue StandardError
-                nil
-              end
+              conn.close
               conn = build_connection
             end
 
@@ -64,11 +60,7 @@ module ActiveCypher
               # Check if connection is viable before using it
               unless conn.viable?
                 # Create a fresh connection, because why not
-                begin
-                  conn.close
-                rescue StandardError
-                  nil
-                end
+                conn.close
                 conn = build_connection
               end
 
@@ -88,8 +80,6 @@ module ActiveCypher
       def verify_connectivity
         with_session { |s| s.run('RETURN 1') }
         true
-      rescue StandardError
-        false
       end
 
       # Closes the connection pool. Because sometimes you just need to let go.
@@ -119,11 +109,7 @@ module ActiveCypher
         begin
           connection.connect
         rescue StandardError => e
-          begin
-            connection.close
-          rescue StandardError
-            nil
-          end
+          connection.close
           raise e
         end