neo4j-ruby-driver 6.0.0.alpha.2 → 6.2.1.beta.1

data/lib/neo4j/driver/summary/notification.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Summary
+      # Server-emitted notification (e.g. "this query has a missing index").
+      # Mirrors org.neo4j.driver.summary.Notification.
+      class Notification
+        attr_reader :code, :title, :description, :severity_level, :severity,
+                    :raw_severity_level, :category, :raw_category, :position
+
+        # Severity mapping matches the Java driver's NotificationSeverity:
+        # WARNING/INFORMATION/OFF/UNKNOWN. Anything else stays as nil on
+        # severity_level but is preserved verbatim in raw_severity_level.
+        KNOWN_SEVERITIES = %w[WARNING INFORMATION OFF UNKNOWN].freeze
+        KNOWN_CATEGORIES = %w[HINT UNRECOGNIZED UNSUPPORTED PERFORMANCE
+                              DEPRECATION GENERIC SECURITY TOPOLOGY SCHEMA].freeze
+
+        def initialize(data)
+          @code = data[:code]
+          @title = data[:title]
+          @description = data[:description]
+          # Old wire format used :severity, newer uses :severityLevel.
+          @raw_severity_level = data[:severityLevel] || data[:severity]
+          @severity_level = KNOWN_SEVERITIES.include?(@raw_severity_level) ? @raw_severity_level : 'UNKNOWN'
+          @severity = @raw_severity_level
+          @raw_category = data[:category]
+          @category = KNOWN_CATEGORIES.include?(@raw_category) ? @raw_category : 'UNKNOWN'
+          @position = data[:position] && Position.new(data[:position])
+        end
+
+        # Inner type — character offset / line / column where the
+        # notification applies in the query text.
+        class Position
+          attr_reader :offset, :line, :column
+
+          def initialize(position_data)
+            @offset = position_data[:offset]
+            @line = position_data[:line]
+            @column = position_data[:column]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/summary/plan.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Summary
+      # Query execution plan tree. Mirrors org.neo4j.driver.summary.Plan.
+      class Plan
+        attr_reader :operator_type, :identifiers, :arguments, :children
+
+        def initialize(plan_data)
+          @operator_type = plan_data[:operatorType]
+          @identifiers = plan_data[:identifiers] || []
+          @arguments = plan_data[:args] || {}
+          @children = (plan_data[:children] || []).map { |child| self.class.new(child) }
+        end
+
+        # Alias args → arguments to match JRuby's InternalPlan#args helper,
+        # so cross-flavour callers can use either name.
+        alias_method :args, :arguments
+      end
+    end
+  end
+end

data/lib/neo4j/driver/summary/profile.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Summary
+      # Plan plus per-step execution stats. Mirrors the driver-6.2 public
+      # QueryProfile, whose getters are all optional: an absent stat stays
+      # nil (distinguishable from a real 0) rather than collapsing to 0, so
+      # the backend can omit it — Feature:API:Summary:Profile:OptionalStats.
+      # The JRuby flavor gets the same nil-vs-0 distinction from
+      # Ext::Internal::Summary::InternalQueryProfile.
+      class Profile < Plan
+        attr_reader :db_hits, :records, :page_cache_hits, :page_cache_misses,
+                    :page_cache_hit_ratio, :time
+
+        def initialize(profile_data)
+          super
+          @db_hits = profile_data[:dbHits]
+          @records = profile_data[:rows] || profile_data[:records]
+          @page_cache_hits = profile_data[:pageCacheHits]
+          @page_cache_misses = profile_data[:pageCacheMisses]
+          @page_cache_hit_ratio = profile_data[:pageCacheHitRatio]
+          @time = profile_data[:time]
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/summary/query.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Summary
+      # The query (text + parameters) the summary describes. Mirrors
+      # org.neo4j.driver.Query but lives under Summary:: for the same
+      # reason as the rest — the user reaches it via Summary#query.
+      class Query
+        attr_reader :text, :parameters
+
+        def initialize(text, parameters = {})
+          @text = text
+          @parameters = parameters
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/summary/query_type.rb

@@ -1,10 +1,14 @@
+# frozen_string_literal: true
+
 module Neo4j
   module Driver
     module Summary
+      # Mirrors org.neo4j.driver.summary.QueryType — coarse classification
+      # of what a query did (read, write, both, or schema mutation).
       module QueryType
         READ_ONLY = 'r'
-        READ_WRITE = 'rw'
         WRITE_ONLY = 'w'
+        READ_WRITE = 'rw'
         SCHEMA_WRITE = 's'
       end
     end

data/lib/neo4j/driver/summary/result_summary.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Summary
+      # Summary of query execution. Mirrors Java's
+      # org.neo4j.driver.summary.ResultSummary — same name and place in
+      # the namespace; no public `metadata` accessor, no Bolt-wire-format
+      # leakage.
+      class ResultSummary
+        def initialize(metadata, query_text = nil, parameters = {}, connection = nil, had_record: false)
+          @metadata = metadata
+          @query_text = query_text
+          @parameters = parameters
+          @connection = connection
+          @had_record = had_record
+        end
+
+        def query
+          Query.new(@query_text, @parameters)
+        end
+
+        # Mirrors Java's ResultSummary#queryType — returns nil only when the
+        # server omitted the :type field (testkit relies on this). A field
+        # that is present but holds anything other than a known code — an
+        # unrecognised string, or an explicit null — is a protocol
+        # violation, so we raise (Java's extractQueryType chokes on those
+        # too) rather than silently returning nil.
+        def query_type
+          return nil unless @metadata.key?(:type)
+
+          case @metadata[:type]
+          when 'r' then QueryType::READ_ONLY
+          when 'w' then QueryType::WRITE_ONLY
+          when 'rw' then QueryType::READ_WRITE
+          when 's' then QueryType::SCHEMA_WRITE
+          else
+            raise Exceptions::ProtocolException, "Unexpected query type: #{@metadata[:type].inspect}"
+          end
+        end
+
+        def counters
+          @counters ||= SummaryCounters.new(@metadata[:stats] || {})
+        end
+
+        def server
+          @server_info ||=
+            if @metadata[:server]
+              ServerInfo.new(@metadata[:server])
+            elsif @connection
+              ServerInfo.new(
+                address: @connection.address,
+                agent: @connection.server_agent,
+                protocol_version: @connection.protocol&.version
+              )
+            else
+              ServerInfo.new(nil)
+            end
+        end
+
+        def database
+          @database_info ||= DatabaseInfo.new(@metadata[:db])
+        end
+
+        # Time until results are available (milliseconds). 't_first' on the wire.
+        def result_available_after
+          @metadata[:t_first]
+        end
+
+        # Time to consume results (milliseconds). 't_last' on the wire.
+        def result_consumed_after
+          @metadata[:t_last]
+        end
+
+        def plan
+          return @plan if defined?(@plan)
+          @plan =
+            if @metadata[:plan]
+              Plan.new(@metadata[:plan])
+            elsif @metadata[:profile]
+              # A profiled query exposes both: `plan` is the plan-only view
+              # (no stats), `profile` adds them. Distinct objects, matching
+              # the Java driver 6.2 model.
+              Plan.new(@metadata[:profile])
+            end
+        end
+
+        def profile
+          return @profile if defined?(@profile)
+          @profile = @metadata[:profile] ? Profile.new(@metadata[:profile]) : nil
+        end
+
+        # MRI has a single profile concept; the modern (JRuby 6.2) query_profile
+        # accessor maps to it. MRI doesn't advertise OptionalStats, so absent
+        # stats still default to 0 (testkit uses its strict-driver path).
+        def query_profile = profile
+
+        def has_plan?
+          !@metadata[:plan].nil? || !@metadata[:profile].nil?
+        end
+
+        def has_profile?
+          !@metadata[:profile].nil?
+        end
+
+        # Bolt 5.5+ servers report query info via `statuses` (GQL status
+        # objects) rather than the legacy `notifications` list. Statuses
+        # without a `neo4j_code` are pure-GQL info (e.g. "successful
+        # completion") and have no legacy-notification equivalent, so we
+        # drop them; the rest are reshaped to look like `notifications`.
+        def notifications
+          (@metadata[:notifications] || statuses_as_notifications)
+            .map { |n| Notification.new(n) }
+        end
+
+        # GQL status objects. Bolt 5.6+ servers report them natively in the
+        # summary `statuses` list, which we preserve verbatim (server order —
+        # the driver must not reorder them). Older servers (or any SUCCESS
+        # without `statuses`) don't, so we synthesise the list from the legacy
+        # `notifications` plus a mandatory outcome status — the pre-5.6
+        # backfill. A status carrying a `neo4j_code` is also a notification
+        # (GqlNotification); the rest are plain status objects.
+        def gql_status_objects
+          (@metadata[:statuses] || polyfilled_statuses).map do |status|
+            (status[:neo4j_code] ? GqlNotification : GqlStatusObject).new(status)
+          end
+        end
+
+        private
+
+        # Synthesise `statuses` from the legacy `notifications` list plus a
+        # single outcome status, mirroring the Java driver's MetadataExtractor.
+        # The whole set is ordered by GQL status class (02 no-data, 01 warning,
+        # 00 success, 03 info, then everything else); the sort is stable so
+        # same-class notifications keep their server order.
+        def polyfilled_statuses
+          statuses = (@metadata[:notifications] || []).map { notification_as_status(it) }
+          statuses << outcome_status
+          statuses.each_with_index.sort_by { |status, i| [gql_status_class(status), i] }.map(&:first)
+        end
+
+        # The mandatory outcome status. The driver reached the summary having
+        # streamed the whole result (eager pull), so it knows whether a record
+        # arrived: yes -> successful completion; no -> "no data", or "omitted
+        # result" when the query produced no fields at all (e.g. a write).
+        def outcome_status
+          if @had_record
+            { gql_status: '00000', status_description: 'note: successful completion' }
+          elsif Array(@metadata[:fields]).empty?
+            { gql_status: '00001', status_description: 'note: successful completion - omitted result' }
+          else
+            { gql_status: '02000', status_description: 'note: no data' }
+          end
+        end
+
+        # Reshape one legacy notification into a `statuses`-list entry so it
+        # flows through GqlNotification unchanged. WARNING -> 01N42, everything
+        # else -> 03N42; the notification facets move into the diagnostic
+        # record under `_severity` / `_classification` / `_position`.
+        def notification_as_status(notification)
+          # Legacy notifications carry severity under :severity — the only key
+          # the Java driver's MetadataExtractor reads here; :severityLevel never
+          # appears on this wire structure.
+          severity = notification[:severity]
+          warning = severity == 'WARNING'
+          description = notification[:description] unless notification[:description] == 'null'
+          {
+            gql_status: warning ? '01N42' : '03N42',
+            status_description: description || (warning ? 'warn: unknown warning' : 'info: unknown notification'),
+            neo4j_code: notification[:code],
+            title: notification[:title],
+            diagnostic_record: { _severity: severity, _classification: notification[:category],
+                                 _position: notification[:position] }.compact
+          }
+        end
+
+        # Sort key from the GQL status class (first two chars of the code).
+        def gql_status_class(status)
+          case status[:gql_status]
+          when /\A02/ then 0
+          when /\A01/ then 1
+          when /\A00/ then 2
+          when /\A03/ then 3
+          else 4
+          end
+        end
+
+        def statuses_as_notifications
+          (@metadata[:statuses] || []).filter_map do |s|
+            next unless s[:neo4j_code]
+
+            dr = s[:diagnostic_record] || {}
+            {
+              code: s[:neo4j_code],
+              title: s[:title],
+              description: s[:description],
+              severity: dr[:_severity],
+              category: dr[:_classification],
+              position: dr[:_position]
+            }.compact
+          end
+        end
+
+        # Internal-only accessor. NOT part of the public API — Java's
+        # ResultSummary doesn't expose the raw wire metadata either. The
+        # one in-tree consumer is Session#harvest_auto_commit_bookmark
+        # (which reaches in via send) because the auto-commit bookmark
+        # only ever lives on the wire SUCCESS metadata.
+        attr_reader :metadata
+      end
+    end
+  end
+end

data/lib/neo4j/driver/summary/server_info.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Summary
+      # Server metadata reported in the SUCCESS response.
+      class ServerInfo
+        attr_reader :address, :agent, :protocol_version
+
+        def initialize(server_data = nil, address: nil, agent: nil, protocol_version: nil)
+          case server_data
+          when String
+            @agent = server_data
+            @address = address
+            @protocol_version = protocol_version
+          when Hash
+            @address = server_data[:address] || address
+            @agent = server_data[:agent] || agent
+            @protocol_version = server_data[:protocol_version] || protocol_version
+          else
+            @address = address
+            @agent = agent
+            @protocol_version = protocol_version
+          end
+        end
+
+        def to_s
+          @agent || 'Unknown'
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/summary/summary_counters.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Summary
+      # Per-operation counts produced by the query.
+      # Mirrors org.neo4j.driver.summary.SummaryCounters.
+      class SummaryCounters
+        attr_reader :nodes_created, :nodes_deleted,
+                    :relationships_created, :relationships_deleted,
+                    :properties_set,
+                    :labels_added, :labels_removed,
+                    :indexes_added, :indexes_removed,
+                    :constraints_added, :constraints_removed,
+                    :system_updates
+
+        # Mapping from server metadata keys (kebab-case strings sent on the
+        # wire as Symbols) to Ruby attribute names.
+        COUNTER_KEYS = {
+          'nodes-created': :nodes_created,
+          'nodes-deleted': :nodes_deleted,
+          'relationships-created': :relationships_created,
+          'relationships-deleted': :relationships_deleted,
+          'properties-set': :properties_set,
+          'labels-added': :labels_added,
+          'labels-removed': :labels_removed,
+          'indexes-added': :indexes_added,
+          'indexes-removed': :indexes_removed,
+          'constraints-added': :constraints_added,
+          'constraints-removed': :constraints_removed,
+          'system-updates': :system_updates
+        }.freeze
+
+        def initialize(stats)
+          # Initialize all counters to 0 — server only reports nonzero ones.
+          COUNTER_KEYS.each_value { |attr| instance_variable_set("@#{attr}", 0) }
+
+          stats.each do |key, value|
+            attr_name = COUNTER_KEYS[key]
+            instance_variable_set("@#{attr_name}", value.to_i) if attr_name
+          end
+        end
+
+        def contains_updates?
+          nodes_created.positive? ||
+            nodes_deleted.positive? ||
+            relationships_created.positive? ||
+            relationships_deleted.positive? ||
+            properties_set.positive? ||
+            labels_added.positive? ||
+            labels_removed.positive? ||
+            indexes_added.positive? ||
+            indexes_removed.positive? ||
+            constraints_added.positive? ||
+            constraints_removed.positive?
+        end
+
+        def contains_system_updates?
+          system_updates.positive?
+        end
+
+        def to_h
+          COUNTER_KEYS.values.to_h { |attr| [attr, instance_variable_get("@#{attr}")] }
+        end
+
+        def to_s
+          to_h.select { |_, v| v.positive? }.map { |k, v| "#{k}: #{v}" }.join(', ')
+        end
+      end
+    end
+  end
+end