julewire-core 1.0.0

data/lib/julewire/core/serialization/text_encoder.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Julewire
+  module Core
+    module Serialization
+      # @api extension
+      class TextEncoder
+        SEVERITY_STYLES = {
+          "debug" => 36,
+          "info" => 32,
+          "warn" => 33,
+          "error" => 31,
+          "fatal" => 35,
+          "unknown" => 37
+        }.freeze
+        PUNK_SEVERITY_STYLES = {
+          "debug" => 36,
+          "info" => 92,
+          "warn" => 93,
+          "error" => 91,
+          "fatal" => 95,
+          "unknown" => 97
+        }.freeze
+        PUNK_SEVERITY_GLYPHS = {
+          "debug" => "..",
+          "info" => ">>",
+          "warn" => "!!",
+          "error" => "XX",
+          "fatal" => "##",
+          "unknown" => "??"
+        }.freeze
+        THEMES = %i[plain punk].freeze
+        DEFAULT_MAX_VALUE_BYTES = 160
+
+        class << self
+          def punk_glyph(severity)
+            PUNK_SEVERITY_GLYPHS.fetch(severity.to_s, PUNK_SEVERITY_GLYPHS.fetch("unknown"))
+          end
+        end
+
+        def initialize(max_value_bytes: DEFAULT_MAX_VALUE_BYTES, color: false, append_newline: true, theme: :plain)
+          @max_value_bytes = Validation.validate_integer_limit!(
+            max_value_bytes,
+            name: :max_value_bytes,
+            positive: true
+          )
+          @color = color
+          @line_suffix = append_newline ? "\n" : ""
+          @theme = validate_theme(theme)
+        end
+
+        def call(payload)
+          text = payload.is_a?(String) ? payload : line_for(payload)
+          "#{text}#{@line_suffix}"
+        end
+
+        private
+
+        def line_for(payload)
+          fields = [
+            timestamp(payload),
+            severity(payload),
+            label(payload, :event),
+            label(payload, :source),
+            message(payload),
+            compact_hash(:payload, value_at(payload, :payload)),
+            compact_hash(:labels, value_at(payload, :labels))
+          ].compact
+          fields.join(" ")
+        end
+
+        def validate_theme(theme)
+          Validation.validate_symbol_choice!(theme, name: "text encoder theme", choices: THEMES)
+        end
+
+        def timestamp(payload)
+          value = value_at(payload, :timestamp)
+          return if blank?(value)
+          # Console output is human-facing; JSON keeps nanosecond precision.
+          return value.iso8601(6) if value.respond_to?(:iso8601)
+
+          value.to_s
+        end
+
+        def severity(payload)
+          value = (value_at(payload, :severity) || :info).to_s
+          label = severity_label(value)
+          return label unless @color
+
+          code = severity_styles.fetch(value, 37)
+          "\e[#{code}m#{label}\e[0m"
+        end
+
+        def severity_label(value)
+          label = value.upcase.ljust(5)
+          return label unless @theme == :punk
+
+          glyph = self.class.punk_glyph(value)
+          "#{glyph} #{value.upcase} #{glyph}"
+        end
+
+        def severity_styles
+          @theme == :punk ? PUNK_SEVERITY_STYLES : SEVERITY_STYLES
+        end
+
+        def label(payload, key)
+          value = value_at(payload, key)
+          return if blank?(value)
+
+          "#{key}=#{value}"
+        end
+
+        def message(payload)
+          value = value_at(payload, :message)
+          return if blank?(value)
+
+          truncate(value.to_s)
+        end
+
+        def compact_hash(name, value)
+          return unless value.is_a?(Hash) && !value.empty?
+
+          "#{name}=#{truncate(JSON.generate(value, allow_nan: false))}"
+        rescue StandardError
+          "#{name}=#{truncate(value.inspect)}"
+        end
+
+        def truncate(value)
+          return value if value.bytesize <= @max_value_bytes
+
+          "#{value.byteslice(0, @max_value_bytes).scrub("?")}..."
+        end
+
+        def value_at(payload, key)
+          Fields::Lookup.value(payload, key)
+        end
+
+        def blank?(value)
+          Fields::Lookup.blank?(value)
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/serialization/value_copy.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Serialization
+      class ValueCopy
+        include ValueTraversal
+
+        CIRCULAR_REFERENCE = Core::CIRCULAR_REFERENCE
+        EMPTY_ARRAY = [].freeze
+        EMPTY_HASH = {}.freeze
+        POOL_KEY = :julewire_core_value_copy_pool
+        private_constant :EMPTY_ARRAY, :EMPTY_HASH, :POOL_KEY
+
+        class << self
+          def call(
+            value,
+            compact_empty: false,
+            freeze_values: false,
+            max_depth: Core::NORMALIZATION_MAX_DEPTH,
+            symbolize_keys: false
+          )
+            return copy_leaf(value, freeze_values: freeze_values) unless container?(value)
+
+            copy_with(
+              cached_copier(
+                compact_empty: compact_empty,
+                freeze_values: freeze_values,
+                max_depth: max_depth,
+                symbolize_keys: symbolize_keys
+              ),
+              value
+            )
+          end
+
+          def omitted_empty?(value)
+            value.nil? || (value.is_a?(Hash) && value.empty?) || (value.is_a?(Array) && value.empty?)
+          end
+
+          private
+
+          def container?(value) = value.is_a?(Hash) || value.is_a?(Array)
+
+          def cached_copier(compact_empty:, freeze_values:, max_depth:, symbolize_keys:)
+            # One copier per thread/options avoids per-record walker allocation.
+            pool = Thread.current.thread_variable_get(POOL_KEY)
+            unless pool
+              pool = {}
+              Thread.current.thread_variable_set(POOL_KEY, pool)
+            end
+
+            key = cache_key(
+              compact_empty: compact_empty,
+              freeze_values: freeze_values,
+              max_depth: max_depth,
+              symbolize_keys: symbolize_keys
+            )
+            pool[key] ||= new(
+              compact_empty: compact_empty,
+              freeze_values: freeze_values,
+              max_depth: max_depth,
+              symbolize_keys: symbolize_keys
+            )
+          end
+
+          def cache_key(compact_empty:, freeze_values:, max_depth:, symbolize_keys:)
+            depth_key = max_depth || -1
+            flags = 0
+            flags |= 1 if compact_empty
+            flags |= 2 if freeze_values
+            flags |= 4 if symbolize_keys
+            (depth_key << 3) | flags
+          end
+
+          def copy_with(copier, value)
+            return copier.call_reusable(value) unless copier.in_use?
+
+            new(
+              compact_empty: copier.compact_empty,
+              freeze_values: copier.freeze_values,
+              max_depth: copier.max_depth,
+              symbolize_keys: copier.symbolize_keys
+            ).call(value)
+          end
+
+          def copy_leaf(value, freeze_values:)
+            return copy_string(value, freeze_values: freeze_values) if value.is_a?(String)
+            return copy_time(value, freeze_values: freeze_values) if value.is_a?(Time)
+
+            value
+          end
+
+          def copy_string(value, freeze_values:)
+            copy = value.frozen? ? value : value.dup
+            freeze_values ? copy.freeze : copy
+          end
+
+          def copy_time(value, freeze_values:)
+            return value unless freeze_values
+            return value if value.frozen?
+
+            value.dup.freeze
+          end
+        end
+
+        attr_reader :compact_empty, :freeze_values, :max_depth, :symbolize_keys
+
+        def initialize(compact_empty:, freeze_values:, max_depth:, symbolize_keys:)
+          @compact_empty = compact_empty
+          @freeze_values = freeze_values
+          @max_depth = max_depth
+          @symbolize_keys = symbolize_keys
+          @in_use = false
+        end
+
+        def call(value)
+          traverse(value) { |root, depth| copy_value(root, depth) }
+        end
+
+        def call_reusable(value)
+          @in_use = true
+          call(value)
+        ensure
+          @in_use = false
+        end
+
+        def in_use? = @in_use
+
+        private
+
+        def copy_value(value, depth)
+          return copy_container(value, depth) if value.is_a?(Hash) || value.is_a?(Array)
+          return copy_string(value) if value.is_a?(String)
+          return copy_time(value) if value.is_a?(Time)
+
+          value
+        end
+
+        def copy_container(value, depth)
+          return copy_string(Serializer::MAX_DEPTH_VALUE) if depth_limited?(depth)
+          return frozen_empty_container(value) if @freeze_values && value.empty?
+
+          with_traversal_container(value, CIRCULAR_REFERENCE) do
+            value.is_a?(Hash) ? copy_hash(value, depth) : copy_array(value, depth)
+          end
+        end
+
+        def depth_limited?(depth)
+          @max_depth && depth >= @max_depth
+        end
+
+        def frozen_empty_container(value)
+          value.is_a?(Hash) ? EMPTY_HASH : EMPTY_ARRAY
+        end
+
+        def copy_hash(value, depth)
+          result = {}
+          value.each do |key, item|
+            next if @compact_empty && self.class.omitted_empty?(item)
+
+            copied = copy_value(item, depth + 1)
+            next if @compact_empty && self.class.omitted_empty?(copied)
+
+            result[copy_key(key)] = copied
+          end
+          freeze_container(result)
+        end
+
+        def copy_array(value, depth)
+          result = []
+          value.each do |item|
+            next if @compact_empty && self.class.omitted_empty?(item)
+
+            copied = copy_value(item, depth + 1)
+            next if @compact_empty && self.class.omitted_empty?(copied)
+
+            result << copied
+          end
+          freeze_container(result)
+        end
+
+        def copy_key(key)
+          return key.to_sym if @symbolize_keys && key.is_a?(String)
+          return copy_string(key) if key.is_a?(String)
+
+          key
+        end
+
+        def copy_string(value)
+          return value unless value.is_a?(String)
+
+          copy = value.frozen? ? value : value.dup
+          @freeze_values ? copy.freeze : copy
+        end
+
+        def copy_time(value)
+          return value unless @freeze_values
+          return value if value.frozen?
+
+          value.dup.freeze
+        end
+
+        def freeze_container(value)
+          @freeze_values ? value.freeze : value
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/serialization/value_traversal.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Serialization
+      module ValueTraversal
+        def traverse(value)
+          previous_seen = @traversal_seen
+          previous_first_seen = @traversal_first_seen
+          previous_second_seen = @traversal_second_seen
+          previous_third_seen = @traversal_third_seen
+          previous_fourth_seen = @traversal_fourth_seen
+          @traversal_seen = nil
+          @traversal_first_seen = nil
+          @traversal_second_seen = nil
+          @traversal_third_seen = nil
+          @traversal_fourth_seen = nil
+          yield(value, 0)
+        ensure
+          @traversal_seen = previous_seen
+          @traversal_first_seen = previous_first_seen
+          @traversal_second_seen = previous_second_seen
+          @traversal_third_seen = previous_third_seen
+          @traversal_fourth_seen = previous_fourth_seen
+        end
+
+        private
+
+        def with_traversal_container(value, circular_value)
+          added = false
+          seen = @traversal_seen
+          first_seen = @traversal_first_seen
+          second_seen = @traversal_second_seen
+          third_seen = @traversal_third_seen
+          fourth_seen = @traversal_fourth_seen
+          return circular_value if seen&.key?(value) || first_seen.equal?(value) || second_seen.equal?(value) ||
+                                   third_seen.equal?(value) || fourth_seen.equal?(value)
+
+          added = mark_traversal_container(value, seen, first_seen, second_seen, third_seen, fourth_seen)
+          yield
+        ensure
+          unmark_traversal_container(value, added)
+        end
+
+        def traversal_seen?(value)
+          @traversal_seen&.key?(value) || @traversal_first_seen.equal?(value) ||
+            @traversal_second_seen.equal?(value) || @traversal_third_seen.equal?(value) ||
+            @traversal_fourth_seen.equal?(value)
+        end
+
+        def with_marked_traversal_container(value)
+          added = mark_traversal_container(
+            value,
+            @traversal_seen,
+            @traversal_first_seen,
+            @traversal_second_seen,
+            @traversal_third_seen,
+            @traversal_fourth_seen
+          )
+          yield
+        ensure
+          unmark_traversal_container(value, added)
+        end
+
+        def mark_traversal_container(value, seen, first_seen, second_seen, third_seen, fourth_seen)
+          # Most records visit only a handful of live containers. Keep those in
+          # slots and allocate the identity hash only for genuinely deep walks.
+          if seen
+            seen[value] = true
+            :hash
+          elsif first_seen.nil?
+            mark_first_seen(value)
+          elsif second_seen.nil?
+            mark_second_seen(value)
+          elsif third_seen.nil?
+            mark_third_seen(value)
+          elsif fourth_seen.nil?
+            mark_fourth_seen(value)
+          else
+            promote_traversal_seen(value, first_seen, second_seen, third_seen, fourth_seen)
+          end
+        end
+
+        def unmark_traversal_container(value, added)
+          case added
+          when :hash
+            @traversal_seen.delete(value)
+          when :first, :second, :third, :fourth
+            unmark_traversal_slot(value, added)
+          end
+        end
+
+        def mark_first_seen(value)
+          @traversal_first_seen = value
+          :first
+        end
+
+        def mark_second_seen(value)
+          @traversal_second_seen = value
+          :second
+        end
+
+        def mark_third_seen(value)
+          @traversal_third_seen = value
+          :third
+        end
+
+        def mark_fourth_seen(value)
+          @traversal_fourth_seen = value
+          :fourth
+        end
+
+        def promote_traversal_seen(value, first_seen, second_seen, third_seen, fourth_seen)
+          @traversal_seen = {}.compare_by_identity
+          @traversal_seen[first_seen] = true
+          @traversal_seen[second_seen] = true
+          @traversal_seen[third_seen] = true
+          @traversal_seen[fourth_seen] = true
+          @traversal_seen[value] = true
+          clear_traversal_slots!
+          :hash
+        end
+
+        def unmark_traversal_slot(value, added)
+          return @traversal_seen.delete(value) if @traversal_seen
+
+          clear_traversal_slot(added)
+        end
+
+        def clear_traversal_slot(slot)
+          case slot
+          when :first then @traversal_first_seen = nil
+          when :second then @traversal_second_seen = nil
+          when :third then @traversal_third_seen = nil
+          when :fourth then @traversal_fourth_seen = nil
+          end
+        end
+
+        def clear_traversal_slots!
+          @traversal_first_seen = nil
+          @traversal_second_seen = nil
+          @traversal_third_seen = nil
+          @traversal_fourth_seen = nil
+        end
+      end
+
+      private_constant :ValueTraversal
+    end
+  end
+end

data/lib/julewire/core/testing/chaos/catalog.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module Chaos
+        class Catalog
+          Entry = Data.define(:kind, :name, :exercise)
+          KINDS = %i[processor formatter encoder destination subscriber listener].freeze
+
+          attr_reader :entries
+
+          class << self
+            def build
+              catalog = new
+              yield catalog if block_given?
+              catalog
+            end
+
+            def assert_contract(test_context, catalog:, errors:)
+              entries = catalog.entries
+              raise ArgumentError, "chaos catalog must have entries" if entries.empty?
+
+              entries.each do |entry|
+                assert_entry(test_context, entry, errors)
+              end
+              nil
+            end
+
+            private
+
+            def assert_entry(test_context, entry, errors)
+              Chaos.assert_contained(
+                test_context,
+                errors: errors,
+                description: "#{entry.kind} #{entry.name}"
+              ) do |error|
+                entry.exercise.call(error)
+              end
+            end
+          end
+
+          def initialize
+            @entries = []
+          end
+
+          def processor(name, &) = register(:processor, name, &)
+
+          def formatter(name, &) = register(:formatter, name, &)
+
+          def encoder(name, &) = register(:encoder, name, &)
+
+          def destination(name, &) = register(:destination, name, &)
+
+          def subscriber(name, &) = register(:subscriber, name, &)
+
+          def listener(name, &) = register(:listener, name, &)
+
+          private
+
+          def register(kind, name, &exercise)
+            raise ArgumentError, "unknown chaos component kind #{kind.inspect}" unless KINDS.include?(kind)
+            raise ArgumentError, "chaos component exercise block required" unless exercise
+
+            @entries << Entry.new(kind, Core.normalize_name(name), exercise)
+            self
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/chaos/core_runtime.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module Chaos
+        module CoreRuntime
+          SCENARIOS = %i[
+            destination_processor
+            drop_callback
+            encoder
+            failure_callback
+            formatter
+            lifecycle_after_fork
+            lifecycle_flush
+            output
+            pipeline_processor
+          ].freeze
+
+          private_constant :SCENARIOS
+
+          class << self
+            def assert_contract(test_context, runtime:, reset:, errors:)
+              SCENARIOS.each do |scenario|
+                errors.each do |error|
+                  assert_scenario(test_context, runtime, reset, scenario, error)
+                end
+              end
+              nil
+            end
+
+            private
+
+            def assert_scenario(test_context, runtime, reset, scenario, error)
+              reset.call
+              send(:"exercise_#{scenario}", runtime, error)
+            rescue StandardError => e
+              test_context.flunk(
+                "expected core #{scenario} failure to be contained, " \
+                "#{error.class} leaked #{e.class}: #{e.message}"
+              )
+            ensure
+              reset.call
+            end
+
+            def exercise_destination_processor(runtime, error)
+              configure_destination(runtime, processors: [Chaos.raiser(error)])
+              runtime.emit("chaos")
+            end
+
+            def exercise_drop_callback(runtime, error)
+              trigger = RuntimeError.new("julewire chaos formatter trigger")
+              configure_destination(runtime, formatter: Chaos.raiser(trigger), on_drop: Chaos.raiser(error))
+              runtime.emit("chaos")
+            end
+
+            def exercise_encoder(runtime, error)
+              configure_destination(runtime, encoder: Chaos.raiser(error))
+              runtime.emit("chaos")
+            end
+
+            def exercise_failure_callback(runtime, error)
+              trigger = RuntimeError.new("julewire chaos output trigger")
+              configure_destination(
+                runtime,
+                output: RaisingOutput.new(trigger, failures: %i[write]),
+                runtime_on_failure: Chaos.raiser(error)
+              )
+              runtime.emit("chaos")
+            end
+
+            def exercise_formatter(runtime, error)
+              configure_destination(runtime, formatter: Chaos.raiser(error))
+              runtime.emit("chaos")
+            end
+
+            def exercise_lifecycle_after_fork(runtime, error)
+              configure_destination(runtime, output: RaisingOutput.new(error, failures: %i[after_fork]))
+              runtime.after_fork!
+            end
+
+            def exercise_lifecycle_flush(runtime, error)
+              configure_destination(runtime, output: RaisingOutput.new(error, failures: %i[flush]))
+              runtime.flush
+            end
+
+            def exercise_output(runtime, error)
+              configure_destination(runtime, output: RaisingOutput.new(error, failures: %i[write]))
+              runtime.emit("chaos")
+            end
+
+            def exercise_pipeline_processor(runtime, error)
+              runtime.configure do |config|
+                config.destinations.use(:default, output: NullOutput.new)
+                config.processors.use(Chaos.raiser(error))
+              end
+              runtime.emit("chaos")
+            end
+
+            def configure_destination(runtime, output: NullOutput.new, formatter: nil, encoder: nil,
+                                      on_drop: nil, processors: nil, runtime_on_failure: nil)
+              runtime.configure do |config|
+                config.on_failure = runtime_on_failure if runtime_on_failure
+                config.destinations.clear
+                config.destinations.use(
+                  :default,
+                  encoder: encoder || Julewire::Core::Serialization::JsonEncoder.new,
+                  formatter: formatter || Julewire::Core::Records::Formatter.new,
+                  on_drop: on_drop,
+                  output: output,
+                  processors: processors || []
+                )
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end