julewire-core 1.0.0 → 1.1.0

data/lib/julewire/core/context_store.rb

@@ -6,8 +6,8 @@ module Julewire
     # Fiber-local context stack used by the runtime facade. Use Julewire.context
     # and Julewire.with_execution instead of reaching into this class directly.
     class ContextStore # rubocop:disable Metrics/ClassLength
-      EMPTY_HASH = {}.freeze
-      private_constant :EMPTY_HASH
+      PropagationOverlay = Data.define(:execution, :link_executions)
+      private_constant :PropagationOverlay
 
       class << self
         def current
@@ -26,10 +26,7 @@ module Julewire
         @scopes = []
         @ambient_fields = Fields::StackSet.new
         @execution_overlays = []
-        @execution_lineage_overlays = []
         @propagation_execution_hash = nil
-        @propagation_scope_snapshot = nil
-        @linked_propagation_scope_snapshot = nil
       end
 
       def current_scope = @scopes.last
@@ -72,6 +69,7 @@ module Julewire
         current_field_hash(:neutral)
       end
 
+      # SectionProxy dispatches these dynamically from the public field readers.
       def context_value(key, default:)
         current_field_stack(:context).value_for(key, default: default)
       end
@@ -84,26 +82,24 @@ module Julewire
         current_field_stack(:attributes).value_for(key, default: default)
       end
 
-      def add_context(fields = EMPTY_HASH, owned: false, **keyword_fields)
+      def add_context(fields = nil, owned: false, **keyword_fields)
         add_field(:context, field_input(fields, keyword_fields), owned: owned)
       end
 
-      def add_carry(fields = EMPTY_HASH, owned: false, **keyword_fields)
+      def add_carry(fields = nil, owned: false, **keyword_fields)
         add_field(:carry, field_input(fields, keyword_fields), owned: owned)
       end
 
-      def add_attributes(fields = EMPTY_HASH, owned: false, **keyword_fields)
+      def add_attributes(fields = nil, owned: false, **keyword_fields)
         add_field(:attributes, field_input(fields, keyword_fields), owned: owned)
       end
 
-      def add_neutral(fields = EMPTY_HASH, owned: false, **keyword_fields)
+      def add_neutral(fields = nil, owned: false, **keyword_fields)
         add_field(:neutral, field_input(fields, keyword_fields), owned: owned)
       end
 
       def delete_carry(path)
         path = Fields::Internal.normalize_path(path)
-        return if path.empty?
-
         if current_scope
           current_scope.delete_carry(path)
         else
@@ -111,19 +107,19 @@ module Julewire
         end
       end
 
-      def with_context(fields = EMPTY_HASH, owned: false, **keyword_fields, &)
+      def with_context(fields = nil, owned: false, **keyword_fields, &)
         with_scope_or_ambient_overlay(:context, field_input(fields, keyword_fields), owned: owned, &)
       end
 
-      def with_carry(fields = EMPTY_HASH, owned: false, **keyword_fields, &)
+      def with_carry(fields = nil, owned: false, **keyword_fields, &)
         with_scope_or_ambient_overlay(:carry, field_input(fields, keyword_fields), owned: owned, &)
       end
 
-      def with_attributes(fields = EMPTY_HASH, owned: false, **keyword_fields, &)
+      def with_attributes(fields = nil, owned: false, **keyword_fields, &)
         with_scope_or_ambient_overlay(:attributes, field_input(fields, keyword_fields), owned: owned, &)
       end
 
-      def with_neutral(fields = EMPTY_HASH, owned: false, **keyword_fields, &)
+      def with_neutral(fields = nil, owned: false, **keyword_fields, &)
         with_scope_or_ambient_overlay(:neutral, field_input(fields, keyword_fields), owned: owned, &)
       end
 
@@ -139,26 +135,21 @@ module Julewire
         end
       end
 
-      def with_propagation(context: {}, carry: {}, execution: {}, link_executions: false, &)
-        scope = current_scope
-        execution = Fields::FieldSet.deep_symbolize_keys(execution)
-        @execution_overlays.push(execution)
-        @execution_lineage_overlays.push(link_executions ? Execution::Lineage.from_execution_hash(execution) : nil)
+      def with_propagation(context:, carry:, execution:, link_executions:, owned:, &)
+        execution = if owned
+                      Serialization::DeepFreeze.validate_symbol_hash(execution)
+                    else
+                      Fields::FieldSet.deep_symbolize_keys(execution)
+                    end
+        @execution_overlays.push(PropagationOverlay.new(execution: execution, link_executions: link_executions))
         invalidate_propagation_cache!
 
         begin
-          if scope
-            scope.with_carry(carry) do
-              scope.with_context(context, &)
-            end
-          else
-            @ambient_fields.with(:carry, carry) do
-              @ambient_fields.with(:context, context, &)
-            end
+          with_carry(carry, owned: owned) do
+            with_context(context, owned: owned, &)
           end
         ensure
           @execution_overlays.pop
-          @execution_lineage_overlays.pop
           invalidate_propagation_cache!
         end
       end
@@ -209,12 +200,12 @@ module Julewire
         Execution::Scope.new(
           type: options.fetch(:type),
           id: options[:id],
-          execution: merged_execution_hash(options.fetch(:execution, EMPTY_HASH)),
+          execution: merged_execution_hash(options.fetch(:execution, {}), owned: options.fetch(:owned, false)),
           execution_owned: true,
           context: fields.stack(:context),
           attributes: fields.stack(:attributes),
           neutral: fields.stack(:neutral),
-          labels: options.fetch(:labels, EMPTY_HASH),
+          labels: options[:labels],
           carry: fields.stack(:carry),
           parent: parent_scope || linked_propagation_scope_snapshot,
           started_at: options[:started_at],
@@ -233,7 +224,7 @@ module Julewire
       end
 
       def add_scope_stack(stack_set, options, section:, key:)
-        value = options.fetch(key, EMPTY_HASH)
+        value = options[key]
         if options.fetch(:owned, false)
           stack_set.add(section, value, owned: true)
         else
@@ -241,37 +232,26 @@ module Julewire
         end
       end
 
-      def add_field(section, fields, owned: false)
+      def add_field(section, fields, owned:)
         scope = current_scope
         if scope
           scope.add_field(section, fields, owned: owned)
-        elsif owned
-          @ambient_fields.add(section, fields, owned: true)
         else
-          @ambient_fields.add(section, fields)
+          @ambient_fields.add(section, fields, owned: owned)
         end
       end
 
       def field_input(fields, keyword_fields)
         return fields if keyword_fields.empty?
-        return keyword_fields if empty_field_input?(fields)
-
-        fields.is_a?(Hash) ? fields.merge(keyword_fields) : fields
-      end
 
-      def empty_field_input?(fields)
-        fields.nil? || (fields.respond_to?(:empty?) && fields.empty?)
+        Fields::FieldSet.coerce(fields, keyword_fields, invalid: :wrap)
       end
 
-      def with_scope_or_ambient_overlay(section, fields, owned: false, &)
+      def with_scope_or_ambient_overlay(section, fields, owned:, &)
         scope = current_scope
         return scope.with_field(section, fields, owned: owned, &) if scope
 
-        if owned
-          @ambient_fields.with(section, fields, owned: true, &)
-        else
-          @ambient_fields.with(section, fields, &)
-        end
+        @ambient_fields.with(section, fields, owned: owned, &)
       end
 
       def current_field_stack(section)
@@ -292,32 +272,31 @@ module Julewire
       end
 
       def execution_hash
-        return {} if @execution_overlays.empty?
-
-        Fields::FieldSet.deep_dup(propagation_execution_hash)
+        Fields::FieldSet.deep_dup_owned(propagation_execution_hash)
       end
 
       def propagation_execution_hash
-        @propagation_execution_hash ||= Fields::Internal.frozen_copy(@execution_overlays.reduce({}) do |memo, overlay|
-          Fields::FieldSet.merge!(memo, overlay)
-        end)
+        @propagation_execution_hash ||= Fields::Internal.frozen_owned_copy(
+          @execution_overlays.reduce({}) do |memo, overlay|
+            Fields::Internal.merge_owned!(memo, overlay.execution)
+          end
+        )
       end
 
       def propagation_scope_snapshot
         execution = propagation_execution_hash
         return if execution.empty?
 
-        @propagation_scope_snapshot ||= Execution::ScopeSnapshot.new(execution: execution)
+        @propagation_scope_snapshot ||= Execution::ScopeSnapshot.new(execution: execution, owned: true)
       end
 
       def linked_propagation_scope_snapshot
-        lineage = linked_propagation_lineage
-        return unless lineage
+        return unless linked_propagation?
 
-        execution = propagation_execution_hash
-        return if execution.empty?
-
-        @linked_propagation_scope_snapshot ||= Execution::ScopeSnapshot.new(execution: execution, lineage: lineage)
+        @linked_propagation_scope_snapshot ||= Execution::ScopeSnapshot.new(
+          execution: propagation_execution_hash,
+          owned: true
+        )
       end
 
       def invalidate_propagation_cache!
@@ -326,56 +305,46 @@ module Julewire
         @linked_propagation_scope_snapshot = nil
       end
 
-      def linked_propagation_lineage
-        (@execution_overlays.length - 1).downto(0) do |index|
-          execution = @execution_overlays.fetch(index)
-          next if execution.empty?
-
-          return @execution_lineage_overlays.fetch(index)
-        end
-        nil
+      def linked_propagation?
+        @execution_overlays.reverse_each.find { |overlay| !overlay.execution.empty? }&.link_executions
       end
 
-      def merged_execution_hash(execution)
-        inherited = inherited_execution_hash
-        return inherited unless execution.is_a?(Hash) && !execution.empty?
+      def merged_execution_hash(execution, owned:)
+        return Fields::FieldSet.merge!(inherited_execution_hash, execution) unless owned
 
-        Fields::FieldSet.merge!(inherited, execution)
+        Serialization::DeepFreeze.validate_symbol_hash(execution)
+        Fields::Internal.merge_owned!(inherited_execution_hash, execution)
       end
 
       def inherited_execution_hash
         scope = current_scope
         return execution_hash unless scope
 
-        inherited = scope.inheritable_execution_hash
-        return inherited if @execution_overlays.empty?
-
-        overlay = execution_hash
-        return inherited if overlay.empty?
-
-        Fields::FieldSet.merge!(inherited, overlay)
+        Fields::Internal.merge_owned!(scope.inheritable_execution_hash, execution_hash)
       end
 
       def finish_scope(scope, on_finish, on_finish_failure, active_exception: nil)
         return unless on_finish
 
-        contain_finish_failure(on_finish_failure, active_exception) { scope.finish_owned unless scope.finished? }
-        contain_finish_failure(on_finish_failure, active_exception) { on_finish.call(scope) }
+        contain_finish_failure(on_finish_failure, active_exception, phase: :summary_finish) do
+          scope.finish_owned unless scope.finished?
+        end
+        contain_finish_failure(on_finish_failure, active_exception, phase: :summary_emit) { on_finish.call(scope) }
       end
 
-      def contain_finish_failure(on_finish_failure, active_exception)
+      def contain_finish_failure(on_finish_failure, active_exception, phase:)
         yield
       rescue StandardError => e
-        report_finish_failure(on_finish_failure, e)
+        report_finish_failure(on_finish_failure, e, phase: phase)
       rescue SystemStackError => e
         # Preserve the app's active stack error during unwind.
         raise unless active_exception
 
-        report_finish_failure(on_finish_failure, e)
+        report_finish_failure(on_finish_failure, e, phase: phase)
       end
 
-      def report_finish_failure(on_finish_failure, error)
-        on_finish_failure&.call(error)
+      def report_finish_failure(on_finish_failure, error, phase:)
+        on_finish_failure.call(error, phase: phase)
       rescue StandardError
         nil
       end

data/lib/julewire/core/destinations/chaos_output.rb

@@ -25,7 +25,7 @@ module Julewire
           when :raise then raise "julewire punk chaos output failure"
           when :reject then false
           when :sleep
-            sleep(@sleep_seconds)
+            Kernel.sleep(@sleep_seconds)
             @output.write(value)
           end
         end
@@ -77,7 +77,7 @@ module Julewire
         end
 
         def trigger?
-          @rate.positive? && @random.rand < @rate
+          @random.rand < @rate
         end
 
         def chaos_mode

data/lib/julewire/core/destinations/collection.rb

@@ -6,7 +6,7 @@ module Julewire
     module Destinations
       class Collection
         def initialize(destinations, on_drop:, on_failure:)
-          @destinations = destinations.freeze
+          @destinations = destinations.dup.freeze
           @on_drop = on_drop
           @on_failure = on_failure
         end
@@ -23,9 +23,9 @@ module Julewire
           private
 
           def validate_destinations(destinations)
-            destinations.map do |destination|
+            destinations.each do |destination|
               Registry.validate!(destination)
-            end.freeze
+            end
           end
         end
 
@@ -76,7 +76,7 @@ module Julewire
 
           lifecycle_destinations(skip_resource_identities).each do |destination|
             remaining_timeout = Scheduling::Deadline.remaining(deadline)
-            if attempted && deadline && remaining_timeout <= 0
+            if attempted && deadline && remaining_timeout.zero?
               ok = false
               break
             end
@@ -96,7 +96,7 @@ module Julewire
         def lifecycle_destinations(skip_resource_identities)
           return @destinations unless skip_resource_identities
 
-          @destinations.reject { skip_lifecycle_destination?(it, skip_resource_identities) }
+          @destinations.reject { skip_resource_identities.key?(resource_identity(it)) }
         end
 
         def call_destination_after_fork(destination)
@@ -108,13 +108,6 @@ module Julewire
             destination: destination_name(destination),
             phase: :destination_lifecycle
           )
-          nil
-        end
-
-        def skip_lifecycle_destination?(destination, identities)
-          return false unless identities
-
-          identities.key?(resource_identity(destination))
         end
 
         def resource_identity(destination)
@@ -125,7 +118,7 @@ module Julewire
 
         def emit_to_destination(destination, record)
           result = destination.emit(record)
-          record_drop(:destination_rejected, destination, record) if result == false
+          record_drop(:destination_rejected, metadata: destination_metadata(destination, record)) if result == false
         rescue StandardError => e
           metadata = destination_metadata(destination, record)
           notify_failure(
@@ -133,8 +126,7 @@ module Julewire
             **metadata,
             phase: :destination
           )
-          record_drop(:destination_exception, destination, record, metadata: metadata)
-          nil
+          record_drop(:destination_exception, metadata: metadata)
         end
 
         def destination_name(destination)
@@ -161,7 +153,7 @@ module Julewire
           @on_failure.call(error, **metadata)
         end
 
-        def record_drop(reason, destination, record, metadata: destination_metadata(destination, record))
+        def record_drop(reason, metadata:)
           @on_drop.call(reason, phase: :destination, **metadata)
         end
 

data/lib/julewire/core/destinations/definition.rb

@@ -43,7 +43,6 @@ module Julewire
             on_drop: resolve(:on_drop, defaults),
             on_failure: resolve(:on_failure, defaults),
             output: output,
-            error_backtrace_lines: defaults.fetch(:error_backtrace_lines),
             processors: resolve(:processors, defaults)
           )
         end
@@ -95,17 +94,10 @@ module Julewire
           return defaults.fetch(key) if defaults.key?(key)
 
           case key
-          when :close_output
-            false
-          when :encoder, :formatter, :on_drop, :on_failure
+          when :encoder, :formatter
             raise ArgumentError, "destination default #{key} is required"
           when :max_record_bytes
             DEFAULT_MAX_RECORD_BYTES
-          when :processors
-            []
-          when :output
-            # No inherited output exists; build raises the required-output error.
-            nil
           end
         end
 

data/lib/julewire/core/destinations/destination.rb

@@ -4,6 +4,8 @@ module Julewire
   module Core
     module Destinations
       class Destination
+        include ProcessorHandling
+
         COUNTER_KEYS = %i[
           callback_error
           encode_error
@@ -15,6 +17,7 @@ module Julewire
           output_rejected
           processor_dropped
           processor_error
+          processor_invalid
           received
           record_too_large
         ].freeze
@@ -30,8 +33,7 @@ module Julewire
           on_drop:,
           on_failure:,
           output:,
-          error_backtrace_lines: Core::MAX_BACKTRACE_LINES,
-          processors: []
+          processors: nil
         )
           @name = Destinations.normalize_name(name)
           @formatter = validate_callable(formatter, name: :formatter)
@@ -43,7 +45,7 @@ module Julewire
           raise ArgumentError, "destination #{@name.inspect} output is required" if output.nil?
 
           @output = Sink.wrap(output, close_output: close_output)
-          @processor_chain = processor_chain(processors, error_backtrace_lines)
+          @processor_chain = processor_chain(processors)
           initialize_tracking
           @write_step = build_write_step
         end
@@ -57,10 +59,7 @@ module Julewire
         end
 
         def emit_processed_record(record, degradation_marker:)
-          return unless @write_step.call(record) == :accepted
-
-          clear_degradation_if_unchanged(degradation_marker)
-          nil
+          clear_degradation_if_unchanged(degradation_marker) if @write_step.call(record)
         end
 
         def flush(timeout: nil)
@@ -73,7 +72,7 @@ module Julewire
 
         def after_fork!
           initialize_tracking
-          @output.after_fork! if @output.respond_to?(:after_fork!)
+          @output.after_fork!
           self
         rescue StandardError => e
           notify_failure(
@@ -86,9 +85,7 @@ module Julewire
         end
 
         def resource_identity
-          return @output.resource_identity if @output.respond_to?(:resource_identity)
-
-          @output
+          @output.resource_identity
         end
 
         def health
@@ -146,7 +143,7 @@ module Julewire
 
         def record_step_metadata(metadata)
           record = metadata.delete(:record)
-          metadata[:record_metadata] = Records::Metadata.call(record) if record
+          metadata[:record_metadata] = Records::Metadata.call(record)
           metadata
         end
 
@@ -166,7 +163,7 @@ module Julewire
         end
 
         def record_loss(reason, metadata)
-          record_metadata = metadata.fetch(:record_metadata, {})
+          record_metadata = metadata.fetch(:record_metadata)
           @health.record_loss(
             reason: reason,
             counter: nil,
@@ -177,10 +174,6 @@ module Julewire
           )
         end
 
-        def clear_degradation
-          @health.clear_degradation
-        end
-
         def clear_degradation_if_unchanged(marker)
           @health.clear_degradation_if_unchanged(marker)
         end
@@ -195,57 +188,16 @@ module Julewire
           callback
         end
 
-        def processor_chain(processors, error_backtrace_lines)
-          processors = processor_entries(processors)
-          return if processors.empty?
-
-          Processing::ProcessorChain.new(
-            processors: processors,
-            error_backtrace_lines: error_backtrace_lines,
-            on_error: method(:record_processor_error)
-          )
-        end
-
-        def processor_entries(value)
-          case value
-          when Processing::ProcessorRegistry
-            value.to_a
-          else
-            Processing::ProcessorRegistry.new(Array(value)).to_a
-          end
-        end
-
-        def process_record(record)
-          return record unless @processor_chain
-
-          processed = @processor_chain.call(Records::Draft.from_record(record, freeze_sections: false))
-          if processed.equal?(Processing::ProcessorChain::DROP)
-            increment_counter(:processor_dropped)
-            nil
-          elsif processed.is_a?(Processing::ProcessorChain::ErrorResult)
-            processed.draft.to_record
-          else
-            processed.to_record
-          end
-        rescue StandardError => e
-          notify_failure(e, phase: :destination_processor, record_metadata: Records::Metadata.call(record))
-          nil
-        end
-
-        def record_processor_error(error, record_metadata)
-          increment_counter(:processor_error)
-          notify_failure(error, phase: :destination_processor, record_metadata: record_metadata)
-        end
-
         def call_output_lifecycle(method_name, timeout:)
           Validation.validate_timeout!(timeout, name: :timeout)
           call_output_lifecycle_safely(method_name, timeout)
         end
 
-        def call_output_lifecycle_safely(method_name, _timeout)
-          # Collection owns the shared deadline; plain outputs expose no timeout API.
-          result = @output.public_send(method_name)
-          clear_degradation if method_name == :flush && result != false
+        def call_output_lifecycle_safely(method_name, timeout)
+          # Sink.wrap centralizes timeout-aware lifecycle dispatch for every output.
+          degradation_marker = @health.degradation_marker
+          result = @output.public_send(method_name, timeout: timeout)
+          clear_degradation_if_unchanged(degradation_marker) if method_name == :flush && result
           result
         rescue StandardError => e
           notify_failure(
@@ -258,9 +210,7 @@ module Julewire
         end
 
         def output_class_name
-          return @output.output_class_name if @output.respond_to?(:output_class_name)
-
-          @output.class.name
+          @output.output_class_name
         end
       end
     end

data/lib/julewire/core/destinations/processor_handling.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Destinations
+      # @api internal
+      module ProcessorHandling
+        private
+
+        def processor_chain(processors)
+          processors = processor_entries(processors)
+          return if processors.empty?
+
+          Processing::ProcessorChain.new(
+            processors: processors,
+            on_error: method(:record_processor_error),
+            on_invalid: method(:record_invalid_processor_result),
+            on_invalid_draft: method(:record_invalid_processor_draft)
+          )
+        end
+
+        def processor_entries(value)
+          case value
+          when Processing::ProcessorRegistry
+            value.to_a
+          else
+            Processing::ProcessorRegistry.new(Array(value)).to_a
+          end
+        end
+
+        def process_record(record)
+          return record unless @processor_chain
+
+          processed = @processor_chain.call(Records::Draft.from_record(record))
+          if processed.equal?(Processing::ProcessorChain::DROP)
+            drop_processed_record
+          elsif processed.instance_of?(Processing::ProcessorChain::ErrorResult)
+            processed.draft.to_record
+          else
+            processed.to_record
+          end
+        end
+
+        def drop_processed_record
+          increment_counter(:processor_dropped)
+          nil
+        end
+
+        def record_processor_error(error, record_metadata)
+          increment_counter(:processor_error)
+          notify_failure(error, phase: :destination_processor, record_metadata: record_metadata)
+        end
+
+        def record_invalid_processor_result(processor_name, result, record_metadata)
+          increment_counter(:processor_invalid)
+          error, metadata = Processing::InvalidResultFailure.build(
+            message: "destination processor returned unsupported result",
+            phase: :destination_processor_result,
+            processor_name: processor_name,
+            record_metadata: record_metadata,
+            result: result
+          )
+          notify_failure(error, **metadata)
+        end
+
+        def record_invalid_processor_draft(processor_name, error, record_metadata)
+          increment_counter(:processor_invalid)
+          notify_failure(
+            error,
+            phase: :destination_processor_data,
+            processor: processor_name,
+            record_metadata: record_metadata
+          )
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/destinations/registry.rb

@@ -49,7 +49,7 @@ module Julewire
         def build(defaults:)
           output_identities = {}.compare_by_identity
           @definitions.map do |definition|
-            if definition.is_a?(Definition)
+            if definition.instance_of?(Definition)
               definition.build(defaults: defaults, output_identities: output_identities)
             else
               definition