julewire-core 1.0.0

data/lib/julewire/core/diagnostics/tail.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Diagnostics
+      class Tail
+        DEFAULT_CAPACITY = 200
+        DEFAULT_NAME = :tail
+        COUNTER_KEYS = %i[captured failures].freeze
+        Entry = Data.define(:sequence, :at, :record)
+
+        class << self
+          def attach!(runtime = Julewire, **)
+            destination = new(**)
+            runtime.configure { it.destinations.add(destination) }
+            destination
+          end
+        end
+
+        attr_reader :capacity, :name
+
+        def initialize(
+          name: DEFAULT_NAME,
+          capacity: DEFAULT_CAPACITY,
+          formatter: Records::Formatter.new,
+          renderer: Renderer.new,
+          serializer: nil
+        )
+          @name = Core.normalize_name(name)
+          @capacity = Validation.validate_integer_limit!(capacity, name: :capacity, positive: true)
+          Validation.validate_callable!(formatter, name: :formatter)
+          Validation.validate_callable!(renderer, name: :renderer)
+          @formatter = formatter
+          @renderer = renderer
+          @serializer = serializer
+          @serializer_pool_key = :"julewire_core_tail_serializers_#{object_id}"
+          initialize_state
+        end
+
+        def emit(record)
+          snapshot = snapshot_record(record)
+          @mutex.synchronize do
+            @sequence += 1
+            entry = Entry.new(@sequence, Time.now.utc, snapshot)
+            @entries << entry
+            @entries.shift while @entries.length > @capacity
+          end
+          @health.increment(:captured)
+          nil
+        rescue StandardError => e
+          record_failure(e, record)
+          nil
+        end
+
+        def entries(limit: nil)
+          limit = normalize_limit(limit)
+          snapshot = @mutex.synchronize { @entries.dup }
+          limit ? snapshot.last(limit) : snapshot
+        end
+
+        def records(limit: nil)
+          entries(limit: limit).map(&:record)
+        end
+
+        def render(limit: nil, color: false)
+          @renderer.call(entries(limit: limit), color: color)
+        end
+
+        def write(io = $stdout, limit: nil, color: nil)
+          io.write(render(limit: limit, color: color.nil? ? io.tty? : color))
+          io
+        end
+
+        def clear
+          @mutex.synchronize do
+            @entries.clear
+          end
+          @health.clear_degraded!
+          self
+        end
+
+        def flush(*) = self
+
+        def close(*) = self
+
+        def after_fork!
+          initialize_state
+          self
+        end
+
+        def health
+          size = @mutex.synchronize { @entries.length }
+          @health.snapshot(capacity: @capacity, size: size)
+        end
+
+        private
+
+        def initialize_state
+          @mutex = Mutex.new
+          @entries = []
+          @health = Integration::DestinationHealth.new(counter_keys: COUNTER_KEYS)
+          @sequence = 0
+          @serializer_mutex = Mutex.new
+        end
+
+        def normalize_limit(value)
+          return if value.nil?
+
+          Validation.validate_integer_limit!(value, name: :limit, positive: true)
+        end
+
+        def snapshot_record(record)
+          payload = @formatter.call(record)
+          raise TypeError, "formatter must return a payload object" if payload.nil?
+
+          Serialization::DeepFreeze.call(with_display_message(serialize_payload(payload), record))
+        end
+
+        def with_display_message(payload, record)
+          return payload unless payload.is_a?(Hash)
+          return payload unless blank?(payload["message"]) && blank?(payload[:message])
+
+          message = Records::DisplayMessage.call(record)
+          return payload if blank?(message)
+
+          payload = payload.dup if payload.frozen?
+          payload["message"] = message
+          payload
+        end
+
+        def serialize_payload(payload)
+          return serialize_custom_payload(payload) if @serializer
+
+          serializer = cached_serializer
+          return build_serializer.serialize(payload) if serializer.in_use?
+
+          serializer.serialize(payload)
+        end
+
+        def serialize_custom_payload(payload)
+          @serializer_mutex.synchronize { @serializer.serialize(payload) }
+        end
+
+        def cached_serializer
+          Serialization::SerializerPool.serializer(@serializer_pool_key, :default) { build_serializer }
+        end
+
+        def build_serializer
+          Serialization::Serializer.new(compact_empty: true)
+        end
+
+        def blank?(value)
+          value.nil? || (value.respond_to?(:empty?) && value.empty?)
+        end
+
+        def record_failure(error, record)
+          @health.record_failure(
+            error,
+            action: :emit,
+            destination: @name,
+            phase: :tail,
+            record_metadata: Records::Metadata.call(record)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/diagnostics.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Diagnostics
+    end
+  end
+end

data/lib/julewire/core/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    class Error < Julewire::Error; end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      class Boundary
+        EMPTY_HASH = {}.freeze
+        EXECUTION_OPTION_DEFAULTS = {
+          id: nil,
+          fields: EMPTY_HASH,
+          attributes: EMPTY_HASH,
+          neutral: EMPTY_HASH,
+          labels: EMPTY_HASH,
+          owned: false,
+          inherit_attributes: true,
+          emit_summary: true,
+          summary_event: nil,
+          summary_severity: nil,
+          summary_source: nil
+        }.freeze
+        EXECUTION_OPTION_KEYS = EXECUTION_OPTION_DEFAULTS.keys.freeze
+        private_constant :EXECUTION_OPTION_DEFAULTS, :EXECUTION_OPTION_KEYS, :EMPTY_HASH
+
+        def initialize(emit_summary_record:, summary_finalizer_failure:, emit_non_standard_exception_summaries:,
+                       before_call: nil)
+          @before_call = before_call
+          @emit_summary_record = emit_summary_record
+          @summary_finalizer_failure = summary_finalizer_failure
+          @emit_non_standard_exception_summaries = emit_non_standard_exception_summaries
+        end
+
+        def with_execution(type:, **options, &)
+          before_call!(:with_execution)
+          raise ArgumentError, "block required" unless block_given?
+
+          open_context_execution(:with_execution, type: type, options: options, &)
+        end
+
+        def start_execution(type:, **options)
+          before_call!(:start_execution)
+          open_context_execution(:start_execution, type: type, options: options)
+        end
+
+        private
+
+        def before_call!(action)
+          @before_call&.call(action)
+        end
+
+        def open_context_execution(method_name, type:, options:, &)
+          options = normalized_execution_options(options)
+          ContextStore.current.public_send(
+            method_name,
+            type: type,
+            id: options.fetch(:id),
+            execution: options.fetch(:execution),
+            attributes: options.fetch(:attributes),
+            neutral: options.fetch(:neutral),
+            labels: options.fetch(:labels),
+            owned: options.fetch(:owned),
+            inherit_attributes: options.fetch(:inherit_attributes),
+            on_finish: summary_finalizer(emit_summary_enabled: options.fetch(:emit_summary)),
+            on_finish_failure: @summary_finalizer_failure,
+            summary_event: options.fetch(:summary_event),
+            summary_severity: options.fetch(:summary_severity),
+            summary_source: options.fetch(:summary_source),
+            &
+          )
+        end
+
+        def normalized_execution_options(options)
+          unknown = options.keys - EXECUTION_OPTION_KEYS
+          raise ArgumentError, "unknown execution options: #{unknown.join(", ")}" unless unknown.empty?
+
+          EXECUTION_OPTION_DEFAULTS.merge(options).tap do |normalized|
+            normalized[:execution] = execution_fields(normalized.delete(:fields))
+            normalized[:attributes] ||= EMPTY_HASH
+            normalized[:neutral] ||= EMPTY_HASH
+            normalized[:labels] ||= EMPTY_HASH
+          end
+        end
+
+        def execution_fields(fields)
+          return {} if fields.nil?
+          raise ArgumentError, "execution fields must be a Hash" unless fields.is_a?(Hash)
+
+          fields
+        end
+
+        def summary_finalizer(emit_summary_enabled:)
+          return unless emit_summary_enabled
+
+          @summary_finalizer ||= lambda do |scope|
+            next if suppress_summary_for_non_standard_exception?(scope)
+
+            @emit_summary_record.call(scope)
+          end
+        end
+
+        def suppress_summary_for_non_standard_exception?(scope)
+          scope.non_standard_exception? && !@emit_non_standard_exception_summaries.call
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      class Handle
+        def initialize(scope:, on_finish:, on_finish_failure:)
+          @scope = scope
+          @on_finish = on_finish
+          @on_finish_failure = on_finish_failure
+          @mutex = Mutex.new
+          @finished = false
+        end
+
+        attr_reader :scope
+
+        def snapshot = View.new(@scope)
+
+        def run
+          active_exception = nil
+          ContextStore.current.with_scope(@scope) do
+            yield self
+          end
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          active_exception = e
+          raise
+        ensure
+          finish(reason: :error, error: active_exception) if active_exception
+        end
+
+        def with_context(&)
+          ContextStore.current.with_scope(@scope, &)
+        end
+
+        def finish(reason: :closed, fields: {}, attributes: {}, error: nil, severity: nil)
+          return false unless mark_finished
+
+          add_completion_attributes(reason)
+          @scope.add_summary(fields) unless fields.empty?
+          @scope.add_summary_attributes(attributes) unless attributes.empty?
+          @scope.finish_owned(error: error, severity: severity)
+          call_finish
+          true
+        rescue StandardError => e
+          report_finish_failure(e)
+          false
+        end
+
+        private
+
+        def mark_finished
+          @mutex.synchronize do
+            return false if @finished
+
+            @finished = true
+          end
+        end
+
+        def add_completion_attributes(reason)
+          @scope.add_summary_attributes({ "julewire.completion": reason.to_s }, owned: true)
+        end
+
+        def call_finish
+          @on_finish&.call(@scope)
+        rescue StandardError => e
+          report_finish_failure(e)
+        end
+
+        def report_finish_failure(error)
+          @on_finish_failure&.call(error)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      class Lineage
+        # Bounded to cap summary growth; also the Answer to the Ultimate Question.
+        MAX_ANCESTORS = 42
+        RELATIONSHIP_KEYS = %i[depth root parent ancestors ancestors_truncated].freeze
+        LAZY_RELATIONSHIP_KEYS = %i[ancestors ancestors_truncated].freeze
+        attr_reader :depth, :parent_reference, :root_reference
+
+        class << self
+          def clean_execution_hash(execution)
+            clean_hash(execution, RELATIONSHIP_KEYS)
+          end
+
+          def clean_owned_execution_hash(execution)
+            clean_hash!(execution, RELATIONSHIP_KEYS)
+          end
+
+          def clean_lazy_relationship_hash(execution)
+            clean_hash(execution, LAZY_RELATIONSHIP_KEYS)
+          end
+
+          def from_execution_hash(execution)
+            execution = {} unless execution.is_a?(Hash)
+            new(
+              reference: execution_reference(execution),
+              root_reference: relationship_value(execution, :root),
+              parent_reference: relationship_value(execution, :parent),
+              depth: relationship_value(execution, :depth),
+              ancestors: relationship_value(execution, :ancestors),
+              ancestors_truncated: relationship_value(execution, :ancestors_truncated)
+            )
+          end
+
+          private
+
+          def relationship_value(execution, key)
+            Fields::FieldSet.value_for(execution, key)
+          end
+
+          def reference_value(execution, key)
+            Fields::FieldSet.value_for(execution, key, default: MISSING)
+          end
+
+          def clean_hash(execution, keys)
+            copy = execution.is_a?(Hash) ? Fields::FieldSet.deep_symbolize_keys(execution) : {}
+            clean_hash!(copy, keys)
+          end
+
+          def clean_hash!(copy, keys)
+            keys.each do |key|
+              Fields::Internal.delete_key!(copy, key)
+            end
+            copy
+          end
+
+          def execution_reference(execution)
+            reference = {}
+            type = reference_value(execution, :type)
+            id = reference_value(execution, :id)
+            reference[:type] = type unless type.equal?(MISSING)
+            reference[:id] = id unless id.equal?(MISSING)
+            reference.empty? ? nil : reference
+          end
+        end
+
+        def initialize(
+          reference: nil,
+          parent_lineage: nil,
+          parent_reference: nil,
+          root_reference: nil,
+          depth: nil,
+          ancestors: nil,
+          ancestors_truncated: false
+        )
+          @parent_lineage = parent_lineage
+          @depth = depth_value(depth, parent_lineage)
+          @root_reference = freeze_reference(root_reference || root_reference_for(reference, parent_lineage))
+          @parent_reference = freeze_reference(parent_reference)
+          @ancestor_references = freeze_ancestors(ancestors)
+          @ancestors_truncated = ancestors_truncated ? true : false
+          @ancestor_references_for_child = nil
+          @truncated = nil
+          @truncated_computed = false
+        end
+
+        def merge_into_frozen(execution)
+          hash = frozen_hash_copy(execution)
+          hash[:depth] = depth
+          hash[:root] = @root_reference
+          hash[:parent] = @parent_reference if @parent_reference
+          hash.freeze
+        end
+
+        def ancestors
+          references = @ancestor_references_for_child
+          return references if references
+
+          materialize_ancestor_references_for_child
+        end
+
+        def truncated?
+          return @truncated if @truncated_computed
+
+          @truncated = @ancestors_truncated || ancestor_count_exceeds_limit?
+          @truncated_computed = true
+          @truncated
+        end
+
+        def freeze
+          return self if frozen?
+
+          ancestors
+          truncated?
+          @parent_lineage = nil
+          super
+        end
+
+        protected
+
+        def ancestor_references_for_child
+          ancestors
+        end
+
+        def root_reference_for_child
+          @root_reference
+        end
+
+        private
+
+        attr_reader :parent_lineage
+
+        def materialize_ancestor_references_for_child
+          if @ancestor_references
+            @ancestor_references_for_child = @ancestor_references.freeze
+          else
+            references = build_ancestor_references
+            @truncated = references.length > MAX_ANCESTORS
+            @truncated_computed = true
+            @ancestor_references_for_child = references.last(MAX_ANCESTORS).freeze
+          end
+        end
+
+        def ancestor_count_exceeds_limit?
+          return false if @ancestor_references_for_child
+
+          build_ancestor_references.length > MAX_ANCESTORS
+        end
+
+        def depth_value(depth, parent_lineage)
+          return depth if depth.is_a?(Integer) && depth.positive?
+          return parent_lineage.depth + 1 if parent_lineage
+
+          1
+        end
+
+        def root_reference_for(reference, parent_lineage)
+          parent_lineage ? parent_lineage.root_reference_for_child : reference
+        end
+
+        def build_ancestor_references
+          return [] unless parent_lineage && @parent_reference
+
+          parent_lineage.ancestor_references_for_child + [@parent_reference]
+        end
+
+        def freeze_ancestors(ancestors)
+          return unless ancestors.is_a?(Array)
+
+          Serialization::ValueCopy.call(ancestors, freeze_values: true)
+        end
+
+        def freeze_reference(reference)
+          return unless reference
+          return reference if reference.frozen?
+
+          Serialization::ValueCopy.call(reference, freeze_values: true)
+        end
+
+        def frozen_hash_copy(value)
+          value.each_with_object({}) do |(key, field_value), copy|
+            copy[Fields::Internal.normalize_key(key)] =
+              Serialization::ValueCopy.call(field_value, freeze_values: true)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      class MeasurementHandle
+        def initialize(&finish)
+          @finish = finish
+          @finished = false
+          @mutex = Mutex.new
+        end
+
+        def finish
+          @mutex.synchronize do
+            return if @finished
+
+            @finished = true
+            @finish.call
+          end
+        end
+
+        def finished?
+          @mutex.synchronize { @finished }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      class NoCurrentError < Error; end
+    end
+  end
+end