julewire-core 1.0.0

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Serialization
+      class DeepCompactEmpty
+        include ValueTraversal
+
+        class << self
+          def call(value)
+            ValueCopy.call(value, compact_empty: true)
+          end
+
+          def compact_owned!(value)
+            new.compact_owned!(value)
+          end
+
+          def omitted?(value)
+            ValueCopy.omitted_empty?(value)
+          end
+        end
+
+        def compact_owned!(value)
+          traverse(value) { |root, _depth| compact_value!(root) }
+        end
+
+        private
+
+        def compact_value!(value)
+          return compact_hash!(value) if value.is_a?(Hash)
+          return compact_array!(value) if value.is_a?(Array)
+
+          value
+        end
+
+        def compact_hash!(value)
+          with_traversal_container(value, value) do
+            value.each do |key, item|
+              compacted = compact_value!(item)
+              if self.class.omitted?(compacted)
+                value.delete(key)
+              elsif !compacted.equal?(item)
+                value[key] = compacted
+              end
+            end
+            value
+          end
+        end
+
+        def compact_array!(value)
+          with_traversal_container(value, value) do
+            index = 0
+            value.each do |item|
+              compacted = compact_value!(item)
+              next if self.class.omitted?(compacted)
+
+              value[index] = compacted
+              index += 1
+            end
+            value.slice!(index, value.length - index) if index < value.length
+            value
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Serialization
+      class DeepFreeze
+        include ValueTraversal
+
+        class << self
+          def call(value, max_depth: Core::NORMALIZATION_MAX_DEPTH, trust_frozen: false)
+            new(max_depth, trust_frozen: trust_frozen).call(value)
+          end
+        end
+
+        def initialize(max_depth, trust_frozen:)
+          @max_depth = max_depth
+          @trust_frozen = trust_frozen
+        end
+
+        def call(value)
+          traverse(value) { |root, depth| freeze_value(root, depth) }
+        end
+
+        private
+
+        def freeze_value(value, depth)
+          return value.freeze if value.is_a?(String)
+          return value if @trust_frozen && value.frozen?
+          return freeze_container(value, depth) if value.is_a?(Hash) || value.is_a?(Array)
+
+          value
+        end
+
+        def freeze_container(value, depth)
+          return Serializer::MAX_DEPTH_VALUE.freeze if depth_limited?(depth)
+
+          with_traversal_container(value, value) do
+            value.is_a?(Hash) ? freeze_hash(value, depth) : freeze_array(value, depth)
+          end
+        end
+
+        def depth_limited?(depth)
+          @max_depth && depth >= @max_depth
+        end
+
+        def freeze_hash(value, depth)
+          value.each { |key, item| freeze_child(value, key, item, depth) }
+          value.freeze
+        end
+
+        def freeze_array(value, depth)
+          value.each_index { freeze_child(value, it, value[it], depth) }
+          value.freeze
+        end
+
+        def freeze_child(value, key, item, depth)
+          frozen = freeze_value(item, depth + 1)
+          value[key] = frozen unless value.frozen? || frozen.equal?(item)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Serialization
+      module EncodingSanitizer
+        class << self
+          def call(value)
+            raise TypeError, "value must be a String" unless value.is_a?(String)
+
+            return value if valid_utf8?(value) || valid_ascii_only?(value)
+            return value.scrub("?") if utf8?(value)
+
+            encode_utf8(value)
+          rescue EncodingError
+            encode_utf8(value.b.force_encoding(Encoding::UTF_8))
+          end
+
+          private
+
+          def valid_utf8?(value)
+            utf8?(value) && value.valid_encoding?
+          end
+
+          def valid_ascii_only?(value)
+            value.ascii_only? && value.valid_encoding?
+          end
+
+          def utf8?(value)
+            value.encoding == Encoding::UTF_8
+          end
+
+          def encode_utf8(value)
+            value.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Serialization
+      class ExceptionShape
+        include ValueTraversal
+
+        DEFAULT_MAX_CAUSE_DEPTH = 5
+
+        class << self
+          def call(error, max_backtrace_lines: Core::MAX_BACKTRACE_LINES, max_cause_depth: DEFAULT_MAX_CAUSE_DEPTH)
+            new(
+              max_backtrace_lines: max_backtrace_lines,
+              max_cause_depth: max_cause_depth
+            ).call(error)
+          end
+        end
+
+        def initialize(max_backtrace_lines:, max_cause_depth:)
+          @backtrace_limiter = BacktraceLimiter.new(max_backtrace_lines: max_backtrace_lines)
+          @include_backtraces = max_backtrace_lines.positive?
+          @max_cause_depth = Validation.validate_integer_limit!(max_cause_depth, name: :max_cause_depth)
+        end
+
+        def call(error)
+          traverse(error) { |root, depth| shape_exception(root, depth) }
+        end
+
+        private
+
+        def shape_exception(error, depth)
+          return error unless error.is_a?(Exception)
+
+          with_traversal_container(error, Core::CIRCULAR_REFERENCE) do
+            exception_hash(error, depth)
+          end
+        end
+
+        def exception_hash(error, depth)
+          {
+            class: class_name(error),
+            message: error_message(error)
+          }.tap do |result|
+            if @include_backtraces
+              lines = backtrace(error)
+              result[:backtrace] = lines if lines
+            end
+
+            cause = exception_cause(error)
+            next unless cause
+
+            if depth >= @max_cause_depth
+              result[:cause_truncated] = true
+            else
+              result[:cause] = shape_exception(cause, depth + 1)
+            end
+          end
+        end
+
+        def class_name(error)
+          error.class.name || error.class.to_s
+        rescue StandardError
+          "Exception"
+        end
+
+        def error_message(error)
+          message = error.message
+          message.is_a?(String) ? message.dup : message.to_s
+        rescue StandardError
+          "[Unavailable]"
+        end
+
+        def backtrace(error)
+          @backtrace_limiter.call(backtrace: Core::Fields::FieldSet.deep_dup(error.backtrace))[:backtrace]
+        rescue StandardError
+          nil
+        end
+
+        def exception_cause(error)
+          error.cause
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Julewire
+  module Core
+    module Serialization
+      # @api extension
+      class JsonEncoder
+        def initialize(
+          max_depth: Serializer::DEFAULT_MAX_DEPTH,
+          max_string_bytes: Serializer::DEFAULT_MAX_STRING_BYTES,
+          max_array_items: Serializer::DEFAULT_MAX_ARRAY_ITEMS,
+          max_hash_keys: Serializer::DEFAULT_MAX_HASH_KEYS,
+          compact_empty: true,
+          max_backtrace_lines: Core::MAX_BACKTRACE_LINES,
+          append_newline: true
+        )
+          @max_depth = max_depth
+          @max_string_bytes = max_string_bytes
+          @max_array_items = max_array_items
+          @max_hash_keys = max_hash_keys
+          @compact_empty = compact_empty
+          @max_backtrace_lines = max_backtrace_lines
+          @line_suffix = append_newline ? "\n" : ""
+          @serializer_key = [
+            @max_depth,
+            @max_string_bytes,
+            @max_array_items,
+            @max_hash_keys,
+            @compact_empty,
+            @max_backtrace_lines
+          ].freeze
+        end
+
+        def call(payload)
+          JSON.generate(serialized_payload(payload), allow_nan: false).tap do |json|
+            json << @line_suffix
+          end
+        end
+
+        private
+
+        def serialized_payload(payload)
+          serializer = cached_serializer
+          return build_serializer.serialize(payload) if serializer.in_use?
+
+          serializer.serialize(payload)
+        end
+
+        def cached_serializer
+          SerializerPool.serializer(:julewire_core_json_encoder_serializers, @serializer_key) { build_serializer }
+        end
+
+        def build_serializer
+          Serializer.new(
+            max_depth: @max_depth,
+            max_string_bytes: @max_string_bytes,
+            max_array_items: @max_array_items,
+            max_hash_keys: @max_hash_keys,
+            compact_empty: @compact_empty,
+            max_backtrace_lines: @max_backtrace_lines,
+            copy_strings: false
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module Julewire
+  module Core
+    module Serialization
+      class Serializer < BoundedTraversal
+        MAX_DEPTH_VALUE = BoundedTraversal::MAX_DEPTH_VALUE
+        OBJECT_VALUE = "[Object]"
+        NAN_VALUE = "NaN"
+        INFINITY_VALUE = "Infinity"
+        NEGATIVE_INFINITY_VALUE = "-Infinity"
+        TRUNCATED_SUFFIX = BoundedTraversal::TRUNCATED_SUFFIX
+        TRUNCATION_METADATA_KEY = BoundedTraversal::TRUNCATION_METADATA_KEY
+        DEFAULT_MAX_DEPTH = BoundedTraversal::DEFAULT_MAX_DEPTH
+        DEFAULT_MAX_STRING_BYTES = BoundedTraversal::DEFAULT_MAX_STRING_BYTES
+        DEFAULT_MAX_ARRAY_ITEMS = BoundedTraversal::DEFAULT_MAX_ARRAY_ITEMS
+        DEFAULT_MAX_HASH_KEYS = BoundedTraversal::DEFAULT_MAX_HASH_KEYS
+        MAX_KEY_BYTES = DEFAULT_MAX_STRING_BYTES
+
+        class << self
+          def call(
+            value,
+            max_depth: DEFAULT_MAX_DEPTH,
+            max_string_bytes: DEFAULT_MAX_STRING_BYTES,
+            max_array_items: DEFAULT_MAX_ARRAY_ITEMS,
+            max_hash_keys: DEFAULT_MAX_HASH_KEYS,
+            compact_empty: false,
+            max_backtrace_lines: Core::MAX_BACKTRACE_LINES
+          )
+            new(
+              max_depth: max_depth,
+              max_string_bytes: max_string_bytes,
+              max_array_items: max_array_items,
+              max_hash_keys: max_hash_keys,
+              compact_empty: compact_empty,
+              max_backtrace_lines: max_backtrace_lines
+            ).serialize(value)
+          end
+        end
+
+        def initialize(
+          max_depth: DEFAULT_MAX_DEPTH,
+          max_string_bytes: DEFAULT_MAX_STRING_BYTES,
+          max_array_items: DEFAULT_MAX_ARRAY_ITEMS,
+          max_hash_keys: DEFAULT_MAX_HASH_KEYS,
+          compact_empty: false,
+          max_backtrace_lines: Core::MAX_BACKTRACE_LINES,
+          copy_strings: true
+        )
+          super(
+            max_array_items: max_array_items,
+            max_depth: max_depth,
+            max_depth_value: MAX_DEPTH_VALUE,
+            max_hash_keys: max_hash_keys,
+            max_string_bytes: max_string_bytes,
+            truncation_key: TRUNCATION_METADATA_KEY
+          )
+          @max_backtrace_lines = Validation.validate_integer_limit!(
+            max_backtrace_lines,
+            name: :max_backtrace_lines
+          )
+          @compact_empty = compact_empty
+          @copy_strings = copy_strings
+        end
+
+        def serialize(value)
+          @in_use = true
+          walk(record_data(value))
+        ensure
+          @in_use = false
+        end
+
+        def in_use? = @in_use
+
+        private
+
+        def scalar_value(value, depth, _key, _path)
+          return serialize_exception(value, depth) if value.is_a?(Exception)
+
+          case value
+          when nil, true, false
+            clear_truncated(value)
+          when Numeric
+            serialize_numeric(value)
+          when Symbol
+            clear_truncated(value.to_s)
+          when String
+            serialize_string(value)
+          when Time, DateTime, Date
+            serialize_temporal(value)
+          else
+            return serialize_iso8601_temporal(value) if zone_temporal?(value)
+
+            serialize_object(value)
+          end
+        rescue StandardError => e
+          clear_truncated(unserializable_marker(e))
+        end
+
+        def serialize_exception(error, depth)
+          shape = ExceptionShape.call(error, max_backtrace_lines: @max_backtrace_lines)
+          walk_value(shape, depth + 1, nil, nil)
+        end
+
+        def hash_like?(value)
+          value.is_a?(Hash) || value.is_a?(Records::PublicProjection)
+        end
+
+        def record_data(value)
+          return value.serializable_data if value.is_a?(Records::Record)
+
+          value
+        end
+
+        def serialize_numeric(value)
+          return serialize_float(value) if value.is_a?(Float)
+          return clear_truncated(value) if value.is_a?(Integer)
+          return serialize_string(value.to_s("F")) if defined?(BigDecimal) && value.is_a?(BigDecimal)
+
+          serialize_string(EncodingSanitizer.call(value.to_s))
+        end
+
+        def serialize_float(value)
+          return clear_truncated(value) if value.finite?
+          return clear_truncated(NAN_VALUE) if value.nan?
+
+          clear_truncated(value.positive? ? INFINITY_VALUE : NEGATIVE_INFINITY_VALUE)
+        end
+
+        def serialize_temporal(value)
+          return clear_truncated(value.getutc.iso8601(9)) if value.is_a?(Time)
+          return clear_truncated(value.iso8601(9)) if value.is_a?(DateTime)
+
+          clear_truncated(value.iso8601)
+        end
+
+        def serialize_iso8601_temporal(value)
+          temporal = value.respond_to?(:utc) ? value.utc : value
+          clear_truncated(EncodingSanitizer.call(temporal.iso8601(9)))
+        end
+
+        def zone_temporal?(value)
+          value.respond_to?(:iso8601) && value.respond_to?(:time_zone)
+        rescue StandardError
+          false
+        end
+
+        def omitted_value?(value) = DeepCompactEmpty.omitted?(value)
+
+        def raw_omitted_value?(value) = DeepCompactEmpty.omitted?(value)
+
+        def key_value(key) = serialize_key(key)
+
+        def error_value(error) = clear_truncated(unserializable_marker(error))
+
+        def serialize_key(key)
+          case key
+          when String
+            serialize_key_string(key)
+          when Symbol
+            serialize_symbol_key(key)
+          when nil, true, false, Numeric
+            serialize_key_string(key.to_s)
+          else
+            serialize_key_string(object_marker(key))
+          end
+        end
+
+        def serialize_symbol_key(key)
+          name = key.name
+          return serialize_trusted_key_string(name) if safe_trusted_key_name?(name)
+
+          serialize_key_string(name)
+        end
+
+        def safe_trusted_key_name?(value)
+          value.ascii_only? || (value.encoding == Encoding::UTF_8 && value.valid_encoding?)
+        end
+
+        def serialize_key_string(value)
+          string = EncodingSanitizer.call(value)
+          return clear_truncated(copy_string(string)) if string.bytesize <= MAX_KEY_BYTES
+
+          mark_truncated("#{string.byteslice(0, MAX_KEY_BYTES).scrub("?")}#{TRUNCATED_SUFFIX}")
+        end
+
+        def serialize_trusted_key_string(value)
+          return clear_truncated(value) if value.bytesize <= MAX_KEY_BYTES
+
+          mark_truncated("#{value.byteslice(0, MAX_KEY_BYTES).scrub("?")}#{TRUNCATED_SUFFIX}")
+        end
+
+        def serialize_object(value)
+          clear_truncated(object_marker(value))
+        end
+
+        def object_marker(value)
+          class_name = value.class.name
+          return OBJECT_VALUE if class_name.nil? || class_name.empty?
+
+          "[Object: #{EncodingSanitizer.call(class_name)}]"
+        end
+
+        def unserializable_marker(error)
+          class_name = error.class.name
+          return "[Unserializable]" if class_name.nil? || class_name.empty?
+
+          "[Unserializable: #{EncodingSanitizer.call(class_name)}]"
+        end
+
+        def serialize_string(value)
+          string = EncodingSanitizer.call(value)
+          return clear_truncated(copy_string(string)) if string.bytesize <= @max_string_bytes
+
+          mark_truncated("#{string.byteslice(0, @max_string_bytes).scrub("?")}#{TRUNCATED_SUFFIX}")
+        end
+
+        def copy_string(value)
+          value.frozen? || !@copy_strings ? value : value.dup
+        end
+
+        def record_hash_truncation(fields, _raw_key, key, key_truncated, child_truncated)
+          return fields unless key_truncated || child_truncated
+
+          append_truncation_field(fields, key)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Serialization
+      module SerializerPool
+        class << self
+          def serializer(pool_key, serializer_key)
+            # Serializers carry traversal state, so pooled instances stay thread-local.
+            pool = Thread.current.thread_variable_get(pool_key)
+            unless pool
+              pool = {}
+              Thread.current.thread_variable_set(pool_key, pool)
+            end
+            pool[serializer_key] ||= yield
+          end
+        end
+      end
+    end
+  end
+end