julewire-core 1.0.0 → 1.1.0

data/lib/julewire/core/fields/field_stack.rb

@@ -4,8 +4,8 @@ module Julewire
   module Core
     module Fields
       # @api internal
-      # Immutable layers keep snapshots stable while each stack tracks only its
-      # current head and versioned read caches.
+      # Immutable layers keep snapshots stable while each stack tracks only the
+      # current head and snapshot cache.
       class FieldStack
         EMPTY_HASH = {}.freeze
         private_constant :EMPTY_HASH
@@ -13,15 +13,29 @@ module Julewire
         class Layer
           attr_reader :fields, :parent
 
-          def initialize(parent, fields, delete_paths: nil, clear_parent_deletes: true)
+          class << self
+            def fields(parent, fields, clear_parent_deletes: true)
+              clear_parent_fields = fields if clear_parent_deletes
+              new(
+                parent,
+                fields,
+                delete_paths: nil,
+                clear_parent_fields:
+              )
+            end
+
+            def delete_paths(parent, paths)
+              new(parent, nil, delete_paths: paths, clear_parent_fields: nil)
+            end
+
+            private :new
+          end
+
+          def initialize(parent, fields, delete_paths:, clear_parent_fields:)
             @parent = parent
             @fields = fields
             @delete_paths = delete_paths
-            @clear_parent_deletes = clear_parent_deletes
-            @active_delete_paths_computed = false
-            @active_delete_paths = nil
-            @snapshot = nil
-            @value_cache = nil
+            @clear_parent_fields = clear_parent_fields
           end
 
           def snapshot
@@ -29,81 +43,54 @@ module Julewire
           end
 
           def value_for(key)
-            return @value_cache[key] if @value_cache&.key?(key)
+            return @value_cache.fetch(key) if @value_cache&.key?(key)
 
             value = if delete_paths_for_key?(key)
                       FieldSet.value_for(snapshot, key, default: MISSING)
                     else
                       field_value = FieldSet.value_for(@fields, key, default: MISSING)
-                      field_value.equal?(MISSING) ? parent_value_for(key) : Fields::Internal.frozen_copy(field_value)
+                      field_value.equal?(MISSING) ? parent_value_for(key) : frozen_field_value(field_value)
                     end
             (@value_cache ||= {})[key] = value
           end
 
           def active_delete_paths
-            return @active_delete_paths if @active_delete_paths_computed
+            return @active_delete_paths if instance_variable_defined?(:@active_delete_paths)
 
             @active_delete_paths = build_active_delete_paths
-            @active_delete_paths_computed = true
-            @active_delete_paths
           end
 
           def snapshot_cached?
             !@snapshot.nil?
           end
 
-          def delete_paths_for_snapshot
-            @clear_parent_deletes ? @delete_paths : active_delete_paths
+          def merge_into(snapshot)
+            Internal.merge_owned!(snapshot, FieldSet.deep_dup_owned(@fields))
           end
 
           private
 
           def build_snapshot
-            return build_direct_snapshot unless @parent
-            return build_parent_snapshot if @parent.snapshot_cached?
-
-            snapshot = source_snapshot_base
-            source_chain.reverse_each do |source|
-              FieldSet.merge!(snapshot, source.fields)
-              paths = source.delete_paths_for_snapshot
-              Fields::Internal.apply_delete_paths!(snapshot, paths) if paths
-            end
-            Fields::Internal.frozen_copy(snapshot)
+            sources, base = source_layers_and_base
+            snapshot = base ? FieldSet.deep_dup_owned(base.snapshot) : {}
+            sources.reverse_each { it.merge_into(snapshot) }
+            paths = active_delete_paths
+            Internal.apply_delete_paths!(snapshot, paths) if paths
+            Internal.frozen_owned_copy(snapshot)
           end
 
-          def build_direct_snapshot
-            snapshot = FieldSet.merge!({}, @fields)
-            paths = delete_paths_for_snapshot
-            Fields::Internal.apply_delete_paths!(snapshot, paths) if paths
-            Fields::Internal.frozen_copy(snapshot)
+          def frozen_field_value(value)
+            Internal.frozen_owned_copy(value)
           end
 
-          def build_parent_snapshot
-            snapshot = FieldSet.merge(@parent.snapshot, @fields)
-            paths = delete_paths_for_snapshot
-            Fields::Internal.apply_delete_paths!(snapshot, paths) if paths
-            Fields::Internal.frozen_copy(snapshot)
-          end
+          def source_layers_and_base(source = self, seen_sources = [], sources = [])
+            return [sources, source] if source.nil? || source.snapshot_cached?
 
-          def source_snapshot_base
-            source = source_chain_base
-            source ? FieldSet.deep_dup(source.snapshot) : {}
-          end
-
-          def source_chain
-            sources = []
-            source = self
-            until source.nil? || source.snapshot_cached?
-              sources << source
-              source = source.parent
-            end
-            sources
-          end
+            raise Error, "field stack layer cycle" if seen_sources.include?(source)
 
-          def source_chain_base
-            source = self
-            source = source.parent until source.nil? || source.snapshot_cached?
-            source
+            seen_sources << source
+            sources << source
+            source_layers_and_base(source.parent, seen_sources, sources)
           end
 
           def parent_value_for(key)
@@ -118,16 +105,14 @@ module Julewire
 
           def build_active_delete_paths
             paths = @parent&.active_delete_paths
-            paths = clear_active_delete_paths(paths) if paths && @clear_parent_deletes && !@fields.empty?
+            paths = clear_active_delete_paths(paths) if paths
             paths = append_delete_paths(paths) if @delete_paths
-            return unless paths
-
-            paths.empty? ? nil : paths
+            paths
           end
 
           def clear_active_delete_paths(paths)
             paths = paths.dup
-            Fields::Internal.clear_delete_paths!(paths, @fields)
+            Internal.clear_delete_paths!(paths, @clear_parent_fields)
             paths
           end
 
@@ -137,51 +122,35 @@ module Julewire
         end
         private_constant :Layer
 
-        def initialize(fields = {}, delete_paths: false, source: nil)
+        def initialize(fields = nil, delete_paths: false, source: nil)
           @source = source
           @delete_paths_enabled = delete_paths
-          @version = 0
-          @snapshot_version = nil
-          @snapshot = nil
-          @value_cache = nil
-          add(fields) if fields.is_a?(Hash) && !fields.empty?
+          add(fields)
         end
 
         def snapshot
-          return @snapshot if @snapshot_version == @version
+          return @snapshot if @snapshot
 
           @snapshot = @source ? @source.snapshot : EMPTY_HASH
-          @snapshot_version = @version
-          @snapshot
         end
 
-        def fork
+        def branch
           self.class.new(delete_paths: @delete_paths_enabled, source: @source)
         end
 
         def value_for(key, default:)
-          cache = @value_cache
-          return cache[key] if cache&.key?(key)
-
-          if key.is_a?(String)
-            key = Fields::Internal.normalize_key(key)
-            cache = @value_cache
-            return cache[key] if cache&.key?(key)
-          end
-
+          key = Internal.normalize_key(key)
           value = source_value_for(key)
           return default if value.equal?(MISSING)
 
-          (@value_cache ||= {})[key] = value
+          value
         end
 
         def add(fields = nil, owned: false, **keyword_fields)
           fields = field_input(fields, keyword_fields, owned: owned)
-          return unless fields.is_a?(Hash)
           return if fields.empty?
 
-          fields = normalize_owned_keys(fields) if owned
-          @source = Layer.new(@source, fields, clear_parent_deletes: true)
+          @source = Layer.fields(@source, fields)
           invalidate_snapshot!
         end
 
@@ -189,16 +158,14 @@ module Julewire
           return if path.empty?
           return unless @delete_paths_enabled
 
-          @source = Layer.new(@source, {}, delete_paths: [path], clear_parent_deletes: false)
+          @source = Layer.delete_paths(@source, [path])
           invalidate_snapshot!
         end
 
         def with(fields = nil, owned: false, **keyword_fields, &)
           fields = field_input(fields, keyword_fields, owned: owned)
-          return yield unless fields.is_a?(Hash)
           return yield if fields.empty?
 
-          fields = normalize_owned_keys(fields) if owned
           with_layer(fields, &)
         end
 
@@ -207,28 +174,25 @@ module Julewire
 
           return yield unless @delete_paths_enabled
 
-          with_layer({}, delete_paths: [path], &)
+          with_delete_layer([path], &)
         end
 
         private
 
         def field_input(fields, keyword_fields, owned:)
           if owned
-            return fields if keyword_fields.empty?
-            return keyword_fields if fields.nil?
-            return fields.merge(keyword_fields) if fields.is_a?(Hash)
+            fields = keyword_fields if fields.nil?
+            Serialization::DeepFreeze.validate_symbol_hash(fields)
 
-            return keyword_fields
+            return fields.merge(keyword_fields)
           end
 
-          return FieldSet.deep_symbolize_keys(fields) if keyword_fields.empty?
-
           FieldSet.coerce(fields, keyword_fields)
         end
 
-        def with_layer(fields, delete_paths: nil)
+        def with_layer(fields)
           previous_source = @source
-          @source = Layer.new(previous_source, fields, delete_paths: delete_paths, clear_parent_deletes: false)
+          @source = Layer.fields(previous_source, fields, clear_parent_deletes: false)
           invalidate_snapshot!
           begin
             yield
@@ -238,30 +202,26 @@ module Julewire
           end
         end
 
-        def normalize_owned_keys(fields)
-          return fields unless fields.any? { |key, _value| key.is_a?(String) }
-
-          fields.to_h { |key, value| [Fields::Internal.normalize_key(key), value] }
+        def with_delete_layer(delete_paths)
+          previous_source = @source
+          @source = Layer.delete_paths(previous_source, delete_paths)
+          invalidate_snapshot!
+          begin
+            yield
+          ensure
+            @source = previous_source
+            invalidate_snapshot!
+          end
         end
 
         def source_value_for(key)
           return MISSING unless @source
 
-          unless @source.parent
-            # Single-layer hits avoid Layer's delete-path/cache bookkeeping.
-            field_value = FieldSet.value_for(@source.fields, key, default: MISSING)
-            return Fields::Internal.frozen_copy(field_value) unless field_value.equal?(MISSING)
-          end
-
-          value = @source.value_for(key)
-          value.equal?(MISSING) ? MISSING : value
+          @source.value_for(key)
         end
 
         def invalidate_snapshot!
-          @version += 1
           @snapshot = nil
-          @snapshot_version = nil
-          @value_cache = nil
         end
       end
     end

data/lib/julewire/core/fields/internal/deletion.rb

@@ -11,12 +11,10 @@ module Julewire
               return target if normalized_path.empty?
 
               deep_delete_path!(target, normalized_path)
-              target
             end
 
             def apply_delete_paths!(target, paths)
               paths.each { delete_path!(target, it) }
-              target
             end
 
             def clear_delete_paths!(paths, fields)
@@ -27,7 +25,7 @@ module Julewire
             end
 
             def normalize_path(path)
-              Array(path).flatten.filter_map { Internal.normalize_key(it) }
+              Array(path).flatten.map { Internal.normalize_key(it) }
             end
 
             private
@@ -37,7 +35,7 @@ module Julewire
 
               fields.flat_map do |key, value|
                 path = prefix + [Internal.normalize_key(key)]
-                nested = value.is_a?(Hash) ? field_paths(value, path) : []
+                nested = field_paths(value, path)
                 nested.empty? ? [path] : nested
               end
             end
@@ -53,12 +51,11 @@ module Julewire
               key = path.first
               if path.one?
                 Internal.delete_key!(target, key)
-                return
+              else
+                child = FieldSet.value_for(target, key)
+                deep_delete_path!(child, path.drop(1))
+                Internal.delete_key!(target, key) if child.is_a?(Hash) && child.empty?
               end
-
-              child = FieldSet.value_for(target, key)
-              deep_delete_path!(child, path.drop(1))
-              Internal.delete_key!(target, key) if child.is_a?(Hash) && child.empty?
             end
           end
         end

data/lib/julewire/core/fields/internal.rb

@@ -4,13 +4,16 @@ module Julewire
   module Core
     module Fields
       module Internal
-        EMPTY_ARRAY = [].freeze
-        EMPTY_HASH = {}.freeze
-        private_constant :EMPTY_ARRAY, :EMPTY_HASH
+        FIELD_KEY_ERROR = "field keys must be String or Symbol"
+        RECORD_STRING_KEY_ERROR = "record must not use string keys"
+        RECORD_SYMBOL_KEY_ERROR = "record keys must be Symbols"
 
         class << self
           def normalize_key(key)
-            key.is_a?(String) ? key.to_sym : key
+            return key.to_sym if key.is_a?(String)
+            return key if key.instance_of?(Symbol)
+
+            raise TypeError, FIELD_KEY_ERROR
           end
 
           def delete_key!(target, key)
@@ -18,16 +21,19 @@ module Julewire
           end
 
           def frozen_copy(value)
-            return EMPTY_HASH if value.is_a?(Hash) && value.empty?
-            return EMPTY_ARRAY if value.is_a?(Array) && value.empty?
-
-            Serialization::ValueCopy.call(value, freeze_values: true)
+            frozen_copy_with(value, preserve_truncation_metadata: false)
           end
 
-          def deep_merge(left, right)
-            deep_merge!(FieldSet.deep_symbolize_keys(left), right)
+          def frozen_owned_copy(value)
+            frozen_copy_with(value, preserve_truncation_metadata: true)
           end
 
+          def apply_delete_paths!(target, paths) = Deletion.apply_delete_paths!(target, paths)
+
+          def clear_delete_paths!(paths, fields) = Deletion.clear_delete_paths!(paths, fields)
+
+          def normalize_path(path) = Deletion.normalize_path(path)
+
           def deep_merge!(target, fields)
             merge_values!(target, fields) do |value, existing|
               if existing.is_a?(Hash) && value.is_a?(Hash)
@@ -39,7 +45,7 @@ module Julewire
           end
 
           def deep_merge_owned!(target, fields)
-            merge_values!(target, fields) do |value, existing|
+            merge_owned_values!(target, fields) do |value, existing|
               if existing.is_a?(Hash) && value.is_a?(Hash)
                 deep_merge_owned!(existing, value)
               else
@@ -49,26 +55,19 @@ module Julewire
           end
 
           def merge_owned!(target, fields)
-            merge_values!(target, fields) { |value, _existing| value }
+            merge_owned_values!(target, fields) { |value, _existing| value }
           end
 
-          def frozen_deep_symbolize_keys(value)
-            return EMPTY_HASH if value.is_a?(Hash) && value.empty?
-            return EMPTY_ARRAY if value.is_a?(Array) && value.empty?
+          private
 
-            Serialization::ValueCopy.call(value, freeze_values: true, symbolize_keys: true)
+          def frozen_copy_with(value, preserve_truncation_metadata:)
+            Serialization::ValueCopy.call(
+              value,
+              freeze_values: true,
+              preserve_truncation_metadata: preserve_truncation_metadata
+            )
           end
 
-          def delete_path!(target, path) = Deletion.delete_path!(target, path)
-
-          def apply_delete_paths!(target, paths) = Deletion.apply_delete_paths!(target, paths)
-
-          def clear_delete_paths!(paths, fields) = Deletion.clear_delete_paths!(paths, fields)
-
-          def normalize_path(path) = Deletion.normalize_path(path)
-
-          private
-
           def merge_values!(target, fields)
             return target unless fields.is_a?(Hash)
 
@@ -80,6 +79,16 @@ module Julewire
 
             target
           end
+
+          def merge_owned_values!(target, fields)
+            return target unless fields.is_a?(Hash)
+
+            fields.each do |key, value|
+              target[key] = yield value, target[key]
+            end
+
+            target
+          end
         end
       end
     end

data/lib/julewire/core/fields/lookup.rb

@@ -8,25 +8,21 @@ module Julewire
           def value(source, key)
             return unless source.respond_to?(:[])
 
-            direct = source[key]
-            return direct unless direct.nil?
-
-            alternate_key(source, key)
+            source[key]
           rescue StandardError
             nil
           end
 
-          def blank?(value)
-            value.nil? || (value.respond_to?(:empty?) && value.empty?)
+          # Decoded wire records have String keys, while in-process records use
+          # Symbols. Keep this conversion at presentation boundaries instead of
+          # making ordinary core lookups tolerant.
+          def wire_value(source, key)
+            result = value(source, key)
+            result.nil? ? value(source, key.to_s) : result
           end
 
-          private
-
-          def alternate_key(source, key)
-            case key
-            when Symbol then source[key.name]
-            when String then source[key.to_sym]
-            end
+          def blank?(value)
+            value.nil? || (value.respond_to?(:empty?) && value.empty?)
           end
         end
       end

data/lib/julewire/core/fields/section_proxy.rb

@@ -34,7 +34,7 @@ module Julewire
 
         def to_h = section_hash
 
-        def [](key) = nil_if_missing(section_value(key, default: MISSING))
+        def [](key) = call_store(:value, key, default: nil)
 
         private
 
@@ -51,10 +51,6 @@ module Julewire
           yield coerce_fields(fields, keyword_fields)
         end
 
-        def nil_if_missing(value)
-          value.equal?(MISSING) ? nil : value
-        end
-
         def add_section(fields)
           call_store(:add, fields)
         end
@@ -67,10 +63,6 @@ module Julewire
           call_store(:hash)
         end
 
-        def section_value(key, default:)
-          call_store(:value, key, default: default)
-        end
-
         def call_store(action, ...)
           @store.public_send(store_method(action), ...)
         end

data/lib/julewire/core/fields/stack_set.rb

@@ -4,13 +4,12 @@ module Julewire
   module Core
     module Fields
       class StackSet
-        EMPTY_HASH = {}.freeze
-        private_constant :EMPTY_HASH
-
         class << self
-          def inherit_from(source, inherit_attributes: true)
-            stacks = Bags.stack_sections.to_h do |section|
-              [section, inherited_stack(source, section, inherit_section?(section, inherit_attributes))]
+          def inherit_from(source, inherit_attributes:)
+            stacks = Bags.stack_sections.each_with_object({}) do |section, inherited|
+              next unless inherit_section?(section, inherit_attributes)
+
+              inherited[section] = source.stack(section).branch
             end
             new(**stacks)
           end
@@ -20,16 +19,12 @@ module Julewire
           def inherit_section?(section, inherit_attributes)
             inherit_attributes || !%i[attributes neutral].include?(section)
           end
-
-          def inherited_stack(source, section, inherit)
-            inherit ? source.stack(section).fork : FieldStack.new
-          end
         end
 
         def initialize(**sections)
           @stacks = Bags.stack_sections.to_h do |section|
-            [section, field_stack(sections.fetch(section, EMPTY_HASH), section)]
-          end.freeze
+            [section, field_stack(sections.fetch(section, nil), section)]
+          end
         end
 
         def stack(section)
@@ -48,8 +43,8 @@ module Julewire
           stack(section).delete(path)
         end
 
-        def with(section, fields, owned: false, &)
-          stack(section).with(fields, owned: owned, &)
+        def with(section, fields = nil, owned: false, **keyword_fields, &)
+          stack(section).with(fields, owned: owned, **keyword_fields, &)
         end
 
         def without(section, path, &)

data/lib/julewire/core/fields/static_labels.rb

@@ -19,7 +19,7 @@ module Julewire
         end
 
         def remove(key)
-          Fields::Internal.delete_key!(@fields, key)
+          Internal.delete_key!(@fields, key)
           self
         end
 

data/lib/julewire/core/integration/configurable.rb

@@ -28,7 +28,7 @@ module Julewire
         end
 
         def reset!
-          @config = build_config
+          @config = nil
         end
 
         private
@@ -38,9 +38,10 @@ module Julewire
         end
 
         def validate_config!(configuration)
-          return if configuration.is_a?(configuration_class)
+          klass = configuration_class
+          return if configuration.is_a?(klass)
 
-          raise TypeError, "expected #{configuration_class.name}"
+          raise TypeError, "expected #{klass}"
         end
 
         def configuration_class

data/lib/julewire/core/integration/destination_health.rb

@@ -5,11 +5,11 @@ module Julewire
     module Integration
       # @api integration_spi
       class DestinationHealth
-        def initialize(counter_keys:, failure_counter: :failures)
+        def initialize(counter_keys:, callback_failure_counter: nil, failure_counter: :failures)
           @failure_counter = failure_counter
           @state = Diagnostics::Health.new(
+            callback_failure_counter: callback_failure_counter,
             counter_keys: counter_keys,
-            failure_counter: failure_counter,
             track_failures: failure_counter == :failures
           )
         end
@@ -19,23 +19,44 @@ module Julewire
         end
 
         def record_failure(error, counter: @failure_counter, **metadata)
-          @state.record_failure(error, counter: counter, degrade: false, **metadata)
+          @state.record_failure(error, counter: counter, **metadata)
         end
 
         def record_loss(reason:, counter: reason, **metadata)
-          @state.record_loss(reason: reason, counter: counter, degrade: false, **metadata)
+          @state.record_loss(reason: reason, counter: counter, **metadata)
         end
 
-        def clear_degraded! = @state.clear_failures!
+        def record_callback_failure(callback_failure)
+          @state.record_callback_failure(callback_failure)
+        end
+
+        def degradation_marker = @state.degradation_marker
+
+        def clear_degradation_if_unchanged(marker) = @state.clear_degradation_if_unchanged(marker)
+
+        def recover_if_successful
+          marker = degradation_marker
+          result = yield
+          clear_degradation_if_unchanged(marker) unless result == false
+          result
+        end
+
+        def clear_failures! = @state.clear_failures!
 
-        def degraded? = @state.degraded?(status_from: :failure_or_loss)
+        def degraded? = @state.degraded?
+
+        def last_callback_failure = @state.last_callback_failure
 
         def last_loss = @state.last_loss
 
         def last_failure = @state.last_failure
 
         def snapshot(status: nil, **fields)
-          @state.snapshot(status: status, status_from: :failure_or_loss, include_loss: true, **fields)
+          snapshot = @state.snapshot(status: status, include_loss: true, **fields)
+          callback_failure = last_callback_failure
+          return snapshot unless callback_failure
+
+          snapshot.merge(last_callback_failure: callback_failure).freeze
         end
       end
     end