julewire-core 1.0.0 → 1.1.0

data/lib/julewire/core/processing/pipeline.rb

@@ -11,10 +11,8 @@ module Julewire
           no_output_dropped
           processor_dropped
           processor_error
+          processor_invalid
         ].freeze
-        EMPTY_HASH = {}.freeze
-        private_constant :EMPTY_HASH
-
         # @api integration_spi
         # Integration-facing raw/normalized record pipeline.
         def initialize(configuration:, invalid_severity_reporter: Diagnostics::InvalidSeverityReporter.counter)
@@ -32,11 +30,11 @@ module Julewire
           initialize_tracking
         end
 
-        def emit(input = Core::UNSET, **fields, &)
+        def emit(input = UNSET, **fields, &)
           emit_with_level_check(input, true, fields, &)
         end
 
-        def emit_without_level(input = Core::UNSET, **fields, &)
+        def emit_without_level(input = UNSET, **fields, &)
           emit_with_level_check(input, false, fields, &)
         end
 
@@ -50,7 +48,7 @@ module Julewire
         # Runtime summaries already carry their captured scope fields.
         def emit_isolated_input(input, enforce_level: true)
           emit_input_with_guard(input, enforce_level: enforce_level, lazy: false) do
-            build_isolated_draft(input)
+            build_isolated_owned_draft(input)
           end
         end
 
@@ -109,7 +107,6 @@ module Julewire
           {
             encoder: Serialization::JsonEncoder.new(max_backtrace_lines: configuration.error_backtrace_lines),
             formatter: Records::Formatter.new,
-            error_backtrace_lines: configuration.error_backtrace_lines,
             on_drop: configuration.on_drop,
             on_failure: configuration.on_failure
           }
@@ -124,9 +121,10 @@ module Julewire
 
         def build_processor_chain(configuration)
           ProcessorChain.new(
-            processors: configuration.processors.to_a.freeze,
-            error_backtrace_lines: @error_backtrace_lines,
-            on_error: method(:record_processor_error)
+            processors: configuration.processors.to_a,
+            on_error: method(:record_processor_error),
+            on_invalid: method(:record_invalid_processor_result),
+            on_invalid_draft: method(:record_invalid_processor_draft)
           )
         end
 
@@ -146,7 +144,7 @@ module Julewire
           if raw_input_blocked?(input, enforce_level: enforce_level, lazy: lazy)
             increment_pipeline_counter(:level_dropped)
           else
-            emit_prepared_draft(yield, enforce_level: enforce_level, merge_static_labels: false)
+            emit_prepared_draft(yield, enforce_level: enforce_level)
           end
           finish_emit_attempt(degradation_marker)
         rescue StandardError => e
@@ -159,7 +157,6 @@ module Julewire
           return false unless @destinations.empty?
 
           record_no_output_drop
-          true
         end
 
         def finish_emit_attempt(degradation_marker)
@@ -171,9 +168,7 @@ module Julewire
           Records::Record.validate_normalized!(record)
           return emit_fast_record(record, enforce_level: enforce_level) if fast_record_path?
 
-          emit_prepared_draft(Records::Draft.from_record(record, freeze_sections: false),
-                              enforce_level: enforce_level)
-          nil
+          emit_prepared_draft(Records::Draft.from_record(record), enforce_level: enforce_level)
         end
 
         def fast_record_path?
@@ -188,7 +183,6 @@ module Julewire
 
           increment_pipeline_counter(:entered)
           emit_to_destinations(record)
-          nil
         end
 
         def raw_input_blocked?(input, enforce_level:, lazy:)
@@ -210,14 +204,14 @@ module Julewire
           )
         end
 
-        def build_isolated_draft(input, input_owned: false)
+        def build_isolated_owned_draft(input)
           build_draft_from(
             input,
-            input_owned: input_owned,
-            context: EMPTY_HASH,
-            neutral: EMPTY_HASH,
-            attributes: EMPTY_HASH,
-            carry: EMPTY_HASH,
+            input_owned: true,
+            context: nil,
+            neutral: nil,
+            attributes: nil,
+            carry: nil,
             scope: nil
           )
         end
@@ -229,9 +223,7 @@ module Julewire
             neutral: neutral,
             attributes: attributes,
             carry: carry,
-            static_labels: @labels,
             input_owned: input_owned,
-            freeze_sections: @processors_empty,
             scope: scope,
             error_backtrace_lines: @error_backtrace_lines,
             invalid_severity_reporter: @invalid_severity_reporter
@@ -241,7 +233,6 @@ module Julewire
         def initialize_tracking
           @health = Diagnostics::Health.new(
             counter_keys: COUNTER_KEYS,
-            callback_metadata: {},
             callback_failure_counter: :callback_error
           )
         end
@@ -267,13 +258,13 @@ module Julewire
           @threshold.allow?(record_or_draft.fetch(:severity))
         end
 
-        def emit_prepared_draft(draft, enforce_level:, merge_static_labels: true)
+        def emit_prepared_draft(draft, enforce_level:)
           if enforce_level && !emit_record?(draft)
             increment_pipeline_counter(:level_dropped)
             return
           end
 
-          draft = merge_static_labels(draft) if merge_static_labels
+          draft = merge_static_labels(draft)
           increment_pipeline_counter(:entered)
           emit_processed_draft(draft, enforce_level: enforce_level)
         rescue StandardError => e
@@ -289,9 +280,12 @@ module Julewire
             return
           end
 
-          processed, enforce_processed_level = processed_draft_and_level(processed, enforce_level)
+          if processed.instance_of?(ProcessorChain::ErrorResult)
+            processed = processed.draft
+            enforce_level = false
+          end
 
-          if enforce_processed_level && !emit_record?(processed)
+          if enforce_level && !emit_record?(processed)
             increment_pipeline_counter(:level_dropped)
             return
           end
@@ -299,27 +293,40 @@ module Julewire
           emit_to_destinations(processed.to_record)
         end
 
-        def processed_draft_and_level(processed, default_enforce_level)
-          if processed.is_a?(ProcessorChain::ErrorResult)
-            [processed.draft, false]
-          else
-            [processed, default_enforce_level]
-          end
-        end
-
         def record_processor_error(error, record_metadata)
           increment_pipeline_counter(:processor_error)
           notify_failure(error, phase: :processor, record_metadata: record_metadata)
         end
 
+        def record_invalid_processor_result(processor_name, result, record_metadata)
+          increment_pipeline_counter(:processor_invalid)
+          error, metadata = InvalidResultFailure.build(
+            message: "processor returned unsupported result",
+            phase: :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_pipeline_counter(:processor_invalid)
+          notify_failure(
+            error,
+            phase: :processor_data,
+            processor: processor_name,
+            record_metadata: record_metadata
+          )
+        end
+
         def emit_internal_error_record(error)
           emit_prepared_draft(
-            Diagnostics::InternalRecords.emit_error(error, error_backtrace_lines: @error_backtrace_lines),
+            Diagnostics::InternalRecords.emit_error(error),
             enforce_level: false
           )
         rescue StandardError => e
           notify_failure(e, phase: :internal_error_record)
-          nil
         end
 
         def emit_to_destinations(record)
@@ -328,7 +335,6 @@ module Julewire
 
         def record_no_output_drop
           increment_pipeline_counter(:no_output_dropped)
-          nil
         end
 
         def notify_failure(error, **metadata)

data/lib/julewire/core/processing/processor_chain.rb

@@ -7,10 +7,11 @@ module Julewire
         DROP = Core.sentinel(:drop)
         ErrorResult = Data.define(:draft)
 
-        def initialize(processors:, error_backtrace_lines:, on_error:)
+        def initialize(processors:, on_error:, on_invalid:, on_invalid_draft:)
           @processors = processors
-          @error_backtrace_lines = error_backtrace_lines
           @on_error = on_error
+          @on_invalid = on_invalid
+          @on_invalid_draft = on_invalid_draft
         end
 
         def empty? = @processors.empty?
@@ -19,13 +20,15 @@ module Julewire
           current = draft
 
           @processors.each do |processor|
-            current = apply_processor_result(current, processor.call(current))
-            break if current == :drop
+            result = processor.call(current)
+            current = apply_processor_result(current, processor, result)
+            return DROP if current.equal?(DROP)
+            return DROP unless valid_processor_draft?(processor, current)
           rescue StandardError => e
             action = handle_processor_error(processor, e, current)
             case action
             when :continue
-              next
+              return DROP unless valid_processor_draft?(processor, current)
             when :drop
               return DROP
             else
@@ -33,15 +36,17 @@ module Julewire
             end
           end
 
-          current == :drop ? DROP : current
+          current
         end
 
         private
 
-        def apply_processor_result(current, result)
-          return :drop if result == :drop
-          return result if result.is_a?(Records::Draft)
+        def apply_processor_result(current, processor, result)
+          return DROP if result == :drop
+          return current if result.nil?
+          return result if result.instance_of?(Records::Draft)
 
+          @on_invalid.call(processor.processor_name, result, Records::Metadata.call(current))
           current
         end
 
@@ -55,12 +60,18 @@ module Julewire
           ErrorResult.new(processor_error_record(processor, error, record_metadata))
         end
 
+        def valid_processor_draft?(processor, draft)
+          draft.validate!
+        rescue StandardError => e
+          @on_invalid_draft.call(processor.processor_name, e, Records::Metadata.call(draft))
+          false
+        end
+
         def processor_error_record(processor, error, record_metadata)
           Diagnostics::InternalRecords.processor_error(
             processor_name: processor.processor_name,
             error: error,
-            record_metadata: record_metadata,
-            error_backtrace_lines: @error_backtrace_lines
+            record_metadata: record_metadata
           )
         end
       end

data/lib/julewire/core/processing/processor_registry.rb

@@ -49,7 +49,6 @@ module Julewire
 
           entry = build_entry(processor, arguments, options)
           prepend ? @entries.unshift(entry) : @entries << entry
-          self
         end
 
         def build_entry(processor, arguments = [], options = {})
@@ -66,7 +65,7 @@ module Julewire
               on_error: on_error,
               factory: true
             )
-          elsif processor.is_a?(Class)
+          elsif processor.instance_of?(Class)
             Entry.new(
               entry: processor,
               arguments: arguments.dup.freeze,
@@ -81,13 +80,13 @@ module Julewire
         end
 
         def normalize_entry(entry)
-          entry.is_a?(Entry) ? entry : build_entry(entry)
+          entry.instance_of?(Entry) ? entry : build_entry(entry)
         end
 
         def materialize(entry)
           processor = if entry.factory
                         Processing.build(entry.entry, *entry.arguments, **entry.options)
-                      elsif entry.entry.is_a?(Class)
+                      elsif entry.entry.instance_of?(Class)
                         entry.entry.new(*entry.arguments, **entry.options)
                       else
                         entry.entry

data/lib/julewire/core/processing/record_field_transform.rb

@@ -14,10 +14,6 @@ module Julewire
         private_constant :SCALAR_KEY_SET
 
         class << self
-          def container_keys = CONTAINER_KEYS
-
-          def scalar_keys = SCALAR_KEYS
-
           def container_key?(key) = CONTAINER_KEY_SET.key?(key)
 
           def scalar_key?(key) = SCALAR_KEY_SET.key?(key)

data/lib/julewire/core/processing/sampling.rb

@@ -77,7 +77,7 @@ module Julewire
             return :drop if value.nil?
             return if @threshold == HASH_SPACE
 
-            Sampling.stable_hash(value) < @threshold ? nil : :drop
+            :drop unless Sampling.stable_hash(value) < @threshold
           end
 
           private
@@ -98,8 +98,6 @@ module Julewire
           end
 
           def field_value(hash, key)
-            return unless hash.is_a?(Hash)
-
             Fields::FieldSet.value_for(hash, key)
           end
         end

data/lib/julewire/core/processing.rb

@@ -10,7 +10,6 @@ module Julewire
           raise ArgumentError, "processor factory block required" unless factory
 
           @factories[normalize_kind(kind)] = factory
-          nil
         end
 
         def build(kind, ...)
@@ -31,7 +30,8 @@ module Julewire
           raise ArgumentError, "processor kind must respond to #to_sym" unless kind.respond_to?(:to_sym)
 
           name = kind.to_sym
-          raise ArgumentError, "processor kind cannot be empty" if name.name.empty?
+          raise ArgumentError, "processor kind #to_sym must return a Symbol" unless name.instance_of?(Symbol)
+          raise ArgumentError, "processor kind cannot be empty" if name.empty?
 
           name
         end

data/lib/julewire/core/propagation/carrier.rb

@@ -8,14 +8,40 @@ module Julewire
       # @api public
       module Carrier
         DEFAULT_KEY = "julewire"
+        DEFAULT_MAX_BYTES = 65_536
         DEFAULT_ENVELOPE = Core.sentinel(:default_envelope)
+
+        # @api integration_spi
+        class Extracted
+          attr_reader :envelope, :status, :reason, :error
+
+          def initialize(envelope:, status:, reason: nil, error: nil)
+            @envelope = envelope
+            @status = status
+            @reason = reason
+            @error = error
+          end
+
+          def failure? = !error.nil?
+        end
         private_constant :DEFAULT_ENVELOPE
 
+        # @api integration_spi
+        class ExtractionError < StandardError
+          attr_reader :status, :reason
+
+          def initialize(status, reason)
+            @status = status
+            @reason = reason
+            super(reason)
+          end
+        end
+
         class << self
           def encode(envelope: DEFAULT_ENVELOPE, max_bytes: nil)
             Validation.validate_byte_limit!(max_bytes, name: :max_bytes)
 
-            encoded = JSON.generate(serialized_envelope(envelope), allow_nan: false)
+            encoded = JSON.generate(serialized_envelope(envelope))
             return if max_bytes && encoded.bytesize > max_bytes
 
             encoded
@@ -24,25 +50,27 @@ module Julewire
           def inject(carrier = {}, envelope: DEFAULT_ENVELOPE, key: DEFAULT_KEY, max_bytes: nil)
             validate_carrier!(carrier)
             encoded = encode(envelope: envelope, max_bytes: max_bytes)
-            clear_carrier_key!(carrier, key) unless encoded
+            clear_carrier_key!(carrier, key)
             return unless encoded
 
             carrier[key.to_s] = encoded
             carrier
           end
 
-          def extract(carrier, key: DEFAULT_KEY)
-            value = carrier_value(carrier, key)
-            return {} unless value
+          def extract_envelope(carrier, key: DEFAULT_KEY, max_bytes: DEFAULT_MAX_BYTES)
+            extract_result(carrier, key: key, max_bytes: max_bytes).envelope
+          end
 
-            parsed = JSON.parse(value.to_s)
-            parsed.is_a?(Hash) ? Fields::FieldSet.deep_symbolize_keys(parsed) : {}
-          rescue StandardError
-            {}
+          # @api integration_spi
+          def extract_result(carrier, key: DEFAULT_KEY, max_bytes: DEFAULT_MAX_BYTES)
+            Validation.validate_byte_limit!(max_bytes, name: :max_bytes)
+
+            extract_payload(carrier, key: key, max_bytes: max_bytes)
           end
 
-          def restore(carrier, key: DEFAULT_KEY, link_executions: false, &)
-            Propagation.restore(extract(carrier, key: key), link_executions: link_executions, &)
+          def restore(carrier, key: DEFAULT_KEY, link_executions: false, max_bytes: DEFAULT_MAX_BYTES, &)
+            envelope = extract_result(carrier, key: key, max_bytes: max_bytes).envelope
+            Propagation.restore(envelope, link_executions: link_executions, owned: true, &)
           end
 
           def serialized_envelope(envelope)
@@ -53,6 +81,36 @@ module Julewire
 
           private
 
+          def extract_payload(carrier, key:, max_bytes:)
+            value = carrier_value(carrier, key)
+            return extracted({}, :missing) unless value
+
+            string = value.to_s
+            if max_bytes && string.bytesize > max_bytes
+              return extracted_failure(:oversized, "carrier payload exceeds max_bytes")
+            end
+
+            parsed = JSON.parse(string)
+            unless parsed.instance_of?(Hash)
+              return extracted_failure(:non_hash,
+                                       "carrier payload must be a JSON object")
+            end
+
+            extracted(Fields::FieldSet.deep_symbolize_owned_keys(parsed), :ok)
+          rescue StandardError => e
+            extracted_failure(:malformed, "carrier payload is not valid JSON", e)
+          end
+
+          def extracted(envelope, status)
+            Extracted.new(envelope: envelope, status: status)
+          end
+
+          def extracted_failure(status, reason, cause = nil)
+            error = ExtractionError.new(status, reason)
+            error.set_backtrace(cause.backtrace) if cause
+            Extracted.new(envelope: {}, status: status, reason: reason, error: error)
+          end
+
           def carrier_value(carrier, key)
             return unless carrier.respond_to?(:[])
 
@@ -68,14 +126,10 @@ module Julewire
           def clear_carrier_key!(carrier, key)
             string_key = key.to_s
             symbol_key = Fields::Internal.normalize_key(key)
-            if carrier.respond_to?(:delete)
-              begin
-                carrier.delete(string_key)
-                carrier.delete(symbol_key)
-              rescue StandardError
-                clear_carrier_key_by_assignment(carrier, string_key, symbol_key)
-              end
-            else
+            begin
+              carrier.delete(string_key)
+              carrier.delete(symbol_key)
+            rescue StandardError
               clear_carrier_key_by_assignment(carrier, string_key, symbol_key)
             end
           end

data/lib/julewire/core/propagation.rb

@@ -13,18 +13,22 @@ module Julewire
         end
 
         def capture_local
-          capture_with { Fields::FieldSet.deep_dup(it) }
+          capture_with { Fields::FieldSet.deep_dup_owned(it) }
         end
 
-        def restore(envelope, link_executions: false, &)
+        def restore(envelope, link_executions: false, owned: false, &)
           raise ArgumentError, "block required" unless block_given?
 
-          sections = FIELD_SECTIONS.to_h { |section| [section, hash_value(envelope, section)] }
-          execution = hash_value(envelope, :execution)
+          Integration::Protocol.validate_symbol_hash(envelope) if owned
+          sections = FIELD_SECTIONS.to_h do |section|
+            [section, restore_hash_value(envelope, section, owned: owned)]
+          end
+          execution = restore_hash_value(envelope, :execution, owned: owned)
           ContextStore.current.with_propagation(
             **sections,
             execution: execution,
             link_executions: link_executions,
+            owned: owned,
             &
           )
         end
@@ -44,6 +48,16 @@ module Julewire
           value = Fields::FieldSet.value_for(hash, key)
           value.is_a?(Hash) ? value : {}
         end
+
+        def restore_hash_value(envelope, key, owned:)
+          return hash_value(envelope, key) unless owned
+          return {} unless envelope.key?(key)
+
+          value = envelope.fetch(key)
+          return value if value.is_a?(Hash)
+
+          raise TypeError, "propagation #{key} must be a Hash"
+        end
       end
     end
   end

data/lib/julewire/core/records/build_input.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Records
+      # Converts raw emit input into known record fields plus payload fields.
+      # @api bridge_spi
+      module BuildInput
+        RECORD_INPUT_KEYS = Record::REQUIRED_KEYS.freeze
+        RECORD_INPUT_KEY_SET = RECORD_INPUT_KEYS.to_h { [it, true] }.freeze
+        private_constant :RECORD_INPUT_KEYS, :RECORD_INPUT_KEY_SET
+
+        class << self
+          def normalize_public(input)
+            return {} if input.nil?
+            return normalize_public_hash(input) if RawInput.hash_input?(input)
+
+            { message: input.to_s }
+          end
+
+          def validate_owned(input)
+            raise TypeError, "owned record input must be a Hash" unless input.is_a?(Hash)
+
+            Serialization::DeepFreeze.validate_symbol_keys(input)
+            validate_known_keys!(input)
+            input
+          end
+
+          private
+
+          def validate_known_keys!(input)
+            unknown = input.each_key.reject { RECORD_INPUT_KEY_SET.key?(it) }
+            return if unknown.empty?
+
+            raise TypeError, "owned record input has unknown top-level keys: #{unknown.join(", ")}"
+          end
+
+          def normalize_public_hash(input)
+            normalized = {}
+            payload_fields = {}
+            input.each do |key, raw_value|
+              normalized_key = Fields::Internal.normalize_key(key)
+              value = raw_value.equal?(input) ? CIRCULAR_REFERENCE : raw_value
+              if RECORD_INPUT_KEY_SET.key?(normalized_key)
+                normalized[normalized_key] = value
+              else
+                payload_fields[normalized_key] = value
+              end
+            end
+            merge_unknown_payload!(normalized, payload_fields)
+            normalized
+          end
+
+          def merge_unknown_payload!(normalized, payload_fields)
+            return if payload_fields.empty?
+
+            normalized[:payload] = if normalized.key?(:payload)
+                                     merge_payload_input(normalized.fetch(:payload), payload_fields)
+                                   else
+                                     payload_fields
+                                   end
+          end
+
+          def merge_payload_input(explicit_payload, unknown_payload)
+            if explicit_payload.is_a?(Hash)
+              Fields::FieldSet.merge(unknown_payload, explicit_payload)
+            else
+              Fields::FieldSet.merge(unknown_payload, Fields::FieldSet::VALUE_KEY => explicit_payload)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/records/console_formatter.rb

@@ -9,13 +9,13 @@ module Julewire
           Record.validate_normalized!(record)
 
           {
-            event: record[:event],
-            labels: record[:labels],
+            event: record.fetch(:event),
+            labels: record.fetch(:labels),
             message: DisplayMessage.call(record),
-            payload: record[:payload],
-            severity: record[:severity],
-            source: record[:source],
-            timestamp: record[:timestamp]
+            payload: record.fetch(:payload),
+            severity: record.fetch(:severity),
+            source: record.fetch(:source),
+            timestamp: record.fetch(:timestamp)
           }
         end
       end

data/lib/julewire/core/records/deconstruct.rb

@@ -9,7 +9,7 @@ module Julewire
           return to_h unless keys
 
           keys.each_with_object({}) do |key, selected|
-            selected[key] = Fields::FieldSet.deep_dup(@data[key]) if @data.key?(key)
+            selected[key] = Fields::FieldSet.deep_dup(fetch(key)) if key?(key)
           end
         end
       end

data/lib/julewire/core/records/display_message.rb

@@ -118,9 +118,7 @@ module Julewire
 
           def duration_text(value)
             text = format("%.3f", value.round(3))
-            text.delete_suffix!("0") while text.end_with?("0")
-            text.delete_suffix!(".")
-            text
+            text.sub(/(?:\.0+|(\.\d+?)0+)\z/, "\\1")
           end
 
           def job_queue(neutral)
@@ -153,7 +151,7 @@ module Julewire
           end
 
           def value_at(value, key)
-            Fields::Lookup.value(value, key)
+            Fields::Lookup.wire_value(value, key)
           end
 
           def blank?(value)