julewire-core 1.0.0

data/lib/julewire/core/execution/scope.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      class Scope
+        EMPTY_HASH = {}.freeze
+        private_constant :EMPTY_HASH
+
+        attr_reader :finished_at
+
+        def initialize(type:, id: nil, execution: EMPTY_HASH, execution_owned: false, summary_event: nil, # rubocop:disable Metrics/ParameterLists
+                       summary_severity: nil, summary_source: nil, attributes: EMPTY_HASH, carry: EMPTY_HASH,
+                       context: EMPTY_HASH, labels: EMPTY_HASH, neutral: EMPTY_HASH, parent: nil, started_at: nil)
+          @identity = ScopeIdentity.new(
+            type: type,
+            id: id,
+            started_at: started_at,
+            parent: parent,
+            parent_reference: parent&.execution_reference_for_child
+          )
+          @summary_state = summary_state(summary_event, summary_severity, summary_source)
+          @execution = @identity.execution_fields(execution, owned: execution_owned)
+          initialize_state(context: context, attributes: attributes, labels: labels, carry: carry, neutral: neutral)
+        end
+
+        def id = @identity.id
+
+        def type = @identity.type
+
+        def started_at = @identity.started_at
+
+        def lineage = @identity.lineage
+
+        def parent = @identity.parent
+
+        def depth = @identity.depth
+
+        def execution_hash
+          Fields::FieldSet.deep_dup(frozen_execution_hash)
+        end
+
+        def frozen_execution_hash
+          @frozen_execution_hash ||= @identity.frozen_execution_hash(@execution)
+        end
+
+        def inheritable_execution_hash
+          Fields::FieldSet.deep_dup(@execution)
+        end
+
+        def context_hash = @fields.context_hash
+
+        def carry_hash = @fields.carry_hash
+
+        def attributes_hash = @fields.attributes_hash
+
+        def neutral_hash = @fields.neutral_hash
+
+        def field_stacks = @fields.stacks
+
+        def labels_hash = @fields.labels_hash
+
+        def frozen_labels_hash = @fields.frozen_labels_hash
+
+        def field_hash(section)
+          @fields.field_hash(section)
+        end
+
+        def field_stack(section)
+          @fields.field_stack(section)
+        end
+
+        def summary_hash
+          @summary_state.payload_hash
+        end
+
+        def metrics_hash
+          @summary_state.metrics_hash
+        end
+
+        def measure_summary(key)
+          measurement = @summary_state.measurement(key)
+          started = monotonic_time
+          begin
+            yield
+          ensure
+            @summary_state.record_measurement(measurement, ((monotonic_time - started) * 1000).round(3))
+          end
+        end
+
+        def measure_summary_start(key)
+          measurement = @summary_state.measurement(key)
+          started = monotonic_time
+          MeasurementHandle.new do
+            @summary_state.record_measurement(measurement, ((monotonic_time - started) * 1000).round(3))
+          end
+        end
+
+        def add_field(section, fields, owned: false)
+          @fields.add(section, fields, owned: owned)
+        end
+
+        def delete_carry(path)
+          path = Fields::Internal.normalize_path(path)
+          @fields.delete(:carry, path)
+        end
+
+        def with_field(section, fields, owned: false, &)
+          @fields.with(section, fields, owned: owned, &)
+        end
+
+        def with_context(fields, &)
+          with_field(:context, fields, &)
+        end
+
+        def with_carry(fields, &)
+          with_field(:carry, fields, &)
+        end
+
+        def without_carry(path, &)
+          normalized_path = Fields::Internal.normalize_path(path)
+          raise ArgumentError, "carry path is required" if normalized_path.empty?
+
+          @fields.without(:carry, normalized_path, &)
+        end
+
+        def add_summary(fields, owned: false)
+          @summary_state.add(fields, owned: owned)
+        end
+
+        def add_summary_attributes(fields, owned: false)
+          @summary_state.add_attributes(fields, owned: owned)
+        end
+
+        def add_summary_neutral(fields, owned: false)
+          @summary_state.add_neutral(fields, owned: owned)
+        end
+
+        def increment_summary_attribute(path, by: 1)
+          @summary_state.increment_attribute(path, by: by)
+        end
+
+        def increment_summary(key, by: 1)
+          @summary_state.increment(key, by: by)
+        end
+
+        def append_summary(key, value)
+          @summary_state.append(key, value)
+        end
+
+        def summary_record_input
+          @summary_state.record_input(**summary_record_fields(timestamp: finished_at || frozen_time(Time.now.utc)))
+        end
+
+        def owned_summary_record_input
+          @summary_state.owned_record_input(
+            **summary_record_fields(timestamp: finished_at || frozen_time(Time.now.utc))
+          )
+        end
+
+        def finished?
+          !finished_at.nil?
+        end
+
+        def finish_owned(error: nil, severity: nil, finished_at: Time.now.utc)
+          # The first completion snapshot wins; later finish calls are no-ops.
+          return owned_summary_record_input if finished?
+
+          record_error(error, severity: severity) if error
+          @finished_at = frozen_time(finished_at)
+          @summary_state.record_duration(((monotonic_time - @identity.started_monotonic) * 1000).round(3))
+          @summary_state.finalize_record_input(**summary_record_fields(timestamp: @finished_at))
+        end
+
+        def record_error(error, severity: nil)
+          @summary_state.record_error(error, severity: severity)
+        end
+
+        def non_standard_exception?
+          @summary_state.non_standard_exception?
+        end
+
+        private
+
+        def monotonic_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        def frozen_time(value) = @identity.frozen_time(value)
+
+        def initialize_state(context:, attributes:, labels:, carry: {}, neutral: {})
+          @fields = ScopeFields.new(
+            context: context,
+            carry: carry,
+            attributes: attributes,
+            labels: labels,
+            neutral: neutral
+          )
+          @finished_at = nil
+        end
+
+        def summary_state(event, severity, source)
+          SummaryState.new(
+            event: normalize_summary_event(event),
+            severity: normalize_summary_severity(severity),
+            source: normalize_summary_source(source)
+          )
+        end
+
+        def normalize_summary_event(event)
+          normalized = event.nil? ? "#{type}.completed" : event.to_s
+          raise ArgumentError, "summary event is required" if normalized.empty?
+
+          normalized
+        end
+
+        def normalize_summary_severity(severity)
+          Records::Severity.normalize(severity) unless severity.nil?
+        end
+
+        def normalize_summary_source(source)
+          normalized = source.nil? ? "julewire" : source.to_s
+          raise ArgumentError, "summary source is required" if normalized.empty?
+
+          normalized
+        end
+
+        def summary_record_fields(timestamp:)
+          {
+            timestamp: timestamp,
+            execution: execution_hash,
+            context: context_hash,
+            carry: carry_hash,
+            neutral: neutral_hash,
+            attributes: attributes_hash,
+            labels: labels_hash
+          }
+        end
+
+        protected
+
+        def execution_reference_for_child
+          @identity.reference
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/execution/scope_fields.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      class ScopeFields
+        EMPTY_HASH = {}.freeze
+        private_constant :EMPTY_HASH
+
+        attr_reader :stacks
+
+        def initialize(context:, attributes:, labels:, carry:, neutral:)
+          @stacks = Fields::StackSet.new(
+            context: context,
+            carry: carry,
+            attributes: attributes,
+            neutral: neutral
+          )
+          @labels = normalized_static_hash(labels)
+        end
+
+        def context_hash = @stacks.snapshot(:context)
+
+        def carry_hash = @stacks.snapshot(:carry)
+
+        def attributes_hash = @stacks.snapshot(:attributes)
+
+        def neutral_hash = @stacks.snapshot(:neutral)
+
+        def field_hash(section)
+          @stacks.snapshot(section)
+        end
+
+        def field_stack(section)
+          @stacks.stack(section)
+        end
+
+        def labels_hash
+          return {} if @labels.empty?
+
+          Fields::FieldSet.deep_dup(@labels)
+        end
+
+        def frozen_labels_hash
+          return EMPTY_HASH if @labels.empty?
+
+          @frozen_labels_hash ||= Fields::Internal.frozen_copy(@labels)
+        end
+
+        def add(section, fields, owned: false)
+          @stacks.add(section, fields, owned: owned)
+        end
+
+        def delete(section, path)
+          @stacks.delete(section, path)
+        end
+
+        def with(section, fields, owned: false, &)
+          @stacks.with(section, fields, owned: owned, &)
+        end
+
+        def without(section, path, &)
+          @stacks.without(section, path, &)
+        end
+
+        private
+
+        def normalized_static_hash(value)
+          return EMPTY_HASH if value.is_a?(Hash) && value.empty?
+
+          Fields::FieldSet.deep_symbolize_keys(value)
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/execution/scope_identity.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Julewire
+  module Core
+    module Execution
+      class ScopeIdentity
+        attr_reader :id, :lineage, :parent, :reference, :started_at, :started_monotonic, :type
+
+        def initialize(type:, id: nil, started_at: nil, parent: nil, parent_reference: nil)
+          @id = normalize_id(id || SecureRandom.uuid)
+          @type = normalize_type(type)
+          @started_at = frozen_time(started_at || Time.now.utc)
+          @started_monotonic = monotonic_time
+          @parent = parent
+          @reference = { type: @type, id: @id }.freeze
+          @lineage = Lineage.new(
+            reference: @reference,
+            parent_lineage: parent&.lineage,
+            parent_reference: parent_reference
+          )
+        end
+
+        def depth = @lineage.depth
+
+        def execution_fields(execution, owned:)
+          fields = owned ? Lineage.clean_owned_execution_hash(execution) : Lineage.clean_execution_hash(execution)
+          fields[:type] = @type
+          fields[:id] = @id
+          fields
+        end
+
+        def frozen_execution_hash(execution)
+          @lineage.merge_into_frozen(execution)
+        end
+
+        def frozen_time(value)
+          Serialization::ValueCopy.call(value, freeze_values: true)
+        end
+
+        private
+
+        def monotonic_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        def normalize_type(type)
+          normalized = type.to_s
+          raise ArgumentError, "execution type is required" if normalized.empty?
+
+          freeze_identity_value(normalized)
+        end
+
+        def normalize_id(id)
+          freeze_identity_value(id)
+        end
+
+        def freeze_identity_value(value)
+          case value
+          when String
+            copy = value.frozen? ? value : value.dup
+            copy.freeze
+          when Symbol, Numeric, true, false, nil
+            value
+          else
+            Serialization::ValueCopy.call(value, freeze_values: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/execution/scope_snapshot.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      class ScopeSnapshot
+        EMPTY_HASH = {}.freeze
+        private_constant :EMPTY_HASH
+
+        def initialize(execution: {}, carry: {}, attributes: {}, labels: {}, neutral: {}, lineage: nil)
+          @execution = normalized_hash(execution)
+          @carry = normalized_hash(carry)
+          @attributes = normalized_hash(attributes)
+          @neutral = normalized_hash(neutral)
+          @labels = normalized_hash(labels)
+          @lineage = lineage || Lineage.from_execution_hash(@execution)
+        end
+
+        def execution_hash
+          Fields::FieldSet.deep_dup(frozen_execution_hash)
+        end
+
+        def frozen_execution_hash
+          @frozen_execution_hash ||= Fields::Internal.frozen_copy(@execution)
+        end
+
+        attr_reader :lineage
+
+        def id = @execution[:id]
+
+        def type = @execution[:type]
+
+        def started_at = nil
+
+        def finished_at = nil
+
+        def parent = nil
+
+        def context_hash = {}
+
+        def carry_hash
+          return {} if @carry.empty?
+
+          Fields::FieldSet.deep_dup(@carry)
+        end
+
+        def attributes_hash
+          return {} if @attributes.empty?
+
+          Fields::FieldSet.deep_dup(@attributes)
+        end
+
+        def neutral_hash
+          return {} if @neutral.empty?
+
+          Fields::FieldSet.deep_dup(@neutral)
+        end
+
+        def labels_hash
+          return {} if @labels.empty?
+
+          Fields::FieldSet.deep_dup(@labels)
+        end
+
+        def summary_hash = {}
+
+        def metrics_hash = {}
+
+        def frozen_labels_hash
+          return EMPTY_HASH if @labels.empty?
+
+          @frozen_labels_hash ||= Fields::Internal.frozen_copy(@labels)
+        end
+
+        def execution_reference_for_child
+          reference = {}
+          reference[:type] = @execution[:type] if @execution.key?(:type)
+          reference[:id] = @execution[:id] if @execution.key?(:id)
+          reference.empty? ? nil : Fields::Internal.frozen_copy(reference)
+        end
+
+        private
+
+        def normalized_hash(value)
+          return EMPTY_HASH if value.is_a?(Hash) && value.empty?
+
+          Fields::FieldSet.deep_symbolize_keys(value)
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/execution/summary_state.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      class SummaryState
+        Measurement = Data.define(:count_key, :duration_key)
+        private_constant :Measurement
+
+        def initialize(event:, severity:, source:)
+          @event = event
+          @severity = severity
+          @source = source
+          @payload = {}
+          @neutral = {}
+          @attributes = {}
+          @metrics = {}
+          @errors = []
+          @error_severity = nil
+          @record_input = nil
+        end
+
+        def payload_hash
+          Fields::FieldSet.deep_dup(@payload)
+        end
+
+        def metrics_hash
+          Fields::FieldSet.deep_dup(@metrics)
+        end
+
+        def add(fields, owned: false)
+          merge_fields!(@payload, fields, owned: owned)
+        end
+
+        def add_attributes(fields, owned: false)
+          deep_merge_fields!(@attributes, fields, owned: owned)
+        end
+
+        def add_neutral(fields, owned: false)
+          deep_merge_fields!(@neutral, fields, owned: owned)
+        end
+
+        def increment_attribute(path, by: 1)
+          path = Fields::Internal.normalize_path(path)
+          raise ArgumentError, "attribute path is required" if path.empty?
+
+          container = attribute_container(path)
+          key = path.last
+          value = Fields::FieldSet.value_for(container, key, default: MISSING)
+          existing = !value.equal?(MISSING)
+          container[Fields::Internal.normalize_key(key)] = incremented_value(value, by, existing: existing)
+        end
+
+        def increment(key, by: 1)
+          key = Fields::Internal.normalize_key(key)
+          value = Fields::FieldSet.value_for(@payload, key, default: MISSING)
+          existing = !value.equal?(MISSING)
+          @payload[key] = incremented_value(value, by, existing: existing)
+        end
+
+        def append(key, value)
+          key = Fields::Internal.normalize_key(key)
+          current = Fields::FieldSet.value_for(@payload, key, default: MISSING)
+          values = array_value(current, existing: !current.equal?(MISSING))
+          @payload[key] = values
+          values << Fields::FieldSet.deep_dup(value)
+        end
+
+        def record_error(error, severity: nil)
+          @errors << error
+          @error_severity = Records::Severity.normalize(severity) unless severity.nil?
+        end
+
+        def non_standard_exception?
+          @errors.any? { !it.is_a?(StandardError) }
+        end
+
+        def record_duration(duration_ms)
+          @metrics[:duration_ms] = duration_ms
+        end
+
+        def measurement(key)
+          base = measurement_base(key)
+          Measurement.new(:"#{base}_count", :"#{base}_duration_ms")
+        end
+
+        def record_measurement(measurement, duration_ms)
+          increment(measurement.count_key)
+          increment_metric(measurement.duration_key, by: duration_ms)
+        end
+
+        def record_input(**fields)
+          Fields::FieldSet.deep_dup(owned_record_input(**fields))
+        end
+
+        def owned_record_input(**fields)
+          @record_input || build_record_input(**fields)
+        end
+
+        def finalize_record_input(**fields)
+          @record_input = build_record_input(**fields)
+        end
+
+        private
+
+        def merge_fields!(target, fields, owned:)
+          if owned
+            Fields::Internal.merge_owned!(target, fields)
+          else
+            Fields::FieldSet.merge!(target, fields)
+          end
+        end
+
+        def deep_merge_fields!(target, fields, owned:)
+          if owned
+            Fields::Internal.deep_merge_owned!(target, fields)
+          else
+            Fields::Internal.deep_merge!(target, fields)
+          end
+        end
+
+        def build_record_input(timestamp:, execution:, context:, carry:, neutral:, attributes:, labels:)
+          {
+            timestamp: timestamp,
+            kind: :summary,
+            event: @event,
+            source: @source,
+            execution: execution,
+            context: context,
+            carry: carry,
+            neutral: neutral_hash(neutral),
+            attributes: attributes_hash(attributes),
+            labels: labels,
+            metrics: metrics_hash,
+            payload: payload_hash,
+            error: @errors.last
+          }.tap do |record|
+            severity = summary_severity
+            record[:severity] = severity if severity
+          end
+        end
+
+        def attributes_hash(base_attributes)
+          return base_attributes if @attributes.empty?
+
+          Fields::Internal.deep_merge(base_attributes, @attributes)
+        end
+
+        def neutral_hash(base_neutral)
+          return base_neutral if @neutral.empty?
+
+          Fields::Internal.deep_merge(base_neutral, @neutral)
+        end
+
+        def array_value(value, existing:)
+          return [] unless existing
+          return value if value.is_a?(Array)
+
+          [value]
+        end
+
+        def incremented_value(value, by, existing:)
+          return Fields::FieldSet.deep_dup(by) unless existing
+          return value + by if value.is_a?(Numeric) && by.is_a?(Numeric)
+
+          array_value(value, existing: true).tap { it << Fields::FieldSet.deep_dup(by) }
+        end
+
+        def increment_metric(key, by:)
+          value = Fields::FieldSet.value_for(@metrics, key, default: MISSING)
+          existing = !value.equal?(MISSING)
+          @metrics[key] = incremented_value(value, by, existing: existing)
+        end
+
+        def measurement_base(key)
+          unless key.is_a?(String) || key.is_a?(Symbol)
+            raise ArgumentError, "measurement key must be a String or Symbol"
+          end
+
+          base = key.to_s
+          raise ArgumentError, "measurement key is required" if base.empty?
+
+          base
+        end
+
+        def attribute_container(path)
+          path[0...-1].reduce(@attributes) do |container, key|
+            normalized = Fields::Internal.normalize_key(key)
+            child = container[normalized]
+            unless child.is_a?(Hash)
+              child = {}
+              container[normalized] = child
+            end
+            child
+          end
+        end
+
+        def summary_severity
+          return @severity if @errors.empty?
+
+          @error_severity || :error
+        end
+      end
+    end
+  end
+end