julewire-core 1.0.0

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      class SummaryProxy
+        def initialize(store)
+          @store = store
+        end
+
+        def add(fields = nil, **keyword_fields)
+          current_scope.add_summary(summary_fields(fields, keyword_fields), owned: true)
+          self
+        end
+
+        def add_attributes(fields = nil, **keyword_fields)
+          current_scope.add_summary_attributes(summary_fields(fields, keyword_fields), owned: true)
+          self
+        end
+
+        def increment_attribute(*path, by: 1)
+          current_scope.increment_summary_attribute(path, by: by)
+          self
+        end
+
+        def increment(key, by: 1)
+          current_scope.increment_summary(key, by: by)
+          self
+        end
+
+        def measure(key, &)
+          raise ArgumentError, "block required" unless block_given?
+
+          current_scope.measure_summary(key, &)
+        end
+
+        def measure_start(key)
+          current_scope.measure_summary_start(key)
+        end
+
+        def append(key, value)
+          current_scope.append_summary(key, value)
+          self
+        end
+
+        def active?
+          @store.current_scope?
+        end
+
+        private
+
+        def current_scope
+          @store.current_scope || raise(Execution::NoCurrentError, "summary data requires a current execution scope")
+        end
+
+        def summary_fields(fields, keyword_fields)
+          FieldSet.coerce(fields, keyword_fields, invalid: :wrap)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      module Configurable
+        def configurable_with(&configuration_class)
+          raise ArgumentError, "configuration class block required" unless configuration_class
+
+          @julewire_configuration_class = configuration_class
+        end
+
+        def config
+          @config ||= build_config
+        end
+
+        def config=(configuration)
+          validate_config!(configuration)
+          @config = configuration
+        end
+
+        def configure
+          raise ArgumentError, "#{name}.configure requires a block" unless block_given?
+
+          yield config
+          config
+        end
+
+        def reset!
+          @config = build_config
+        end
+
+        private
+
+        def build_config
+          configuration_class.new
+        end
+
+        def validate_config!(configuration)
+          return if configuration.is_a?(configuration_class)
+
+          raise TypeError, "expected #{configuration_class.name}"
+        end
+
+        def configuration_class
+          @julewire_configuration_class.call
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      class DestinationHealth
+        def initialize(counter_keys:, failure_counter: :failures)
+          @failure_counter = failure_counter
+          @state = Diagnostics::Health.new(
+            counter_keys: counter_keys,
+            failure_counter: failure_counter,
+            track_failures: failure_counter == :failures
+          )
+        end
+
+        def increment(key, by: 1)
+          @state.increment(key, by: by)
+        end
+
+        def record_failure(error, counter: @failure_counter, **metadata)
+          @state.record_failure(error, counter: counter, degrade: false, **metadata)
+        end
+
+        def record_loss(reason:, counter: reason, **metadata)
+          @state.record_loss(reason: reason, counter: counter, degrade: false, **metadata)
+        end
+
+        def clear_degraded! = @state.clear_failures!
+
+        def degraded? = @state.degraded?(status_from: :failure_or_loss)
+
+        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)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      module EventSubscriber
+        class << self
+          def included(base)
+            base.extend(ClassMethods)
+          end
+        end
+
+        module ClassMethods
+          def event_subscriber(integration_health:, configuration_class:, component: :event_subscriber)
+            event_subscriber_options[:component] = component
+            event_subscriber_options[:configuration_class] = configuration_class
+            event_subscriber_options[:integration_health] = integration_health
+          end
+
+          def default_configuration
+            event_subscriber_options.fetch(:configuration_class).new
+          end
+
+          def event_subscriber_component
+            event_subscriber_options.fetch(:component)
+          end
+
+          def event_subscriber_health
+            event_subscriber_options.fetch(:integration_health)
+          end
+
+          private
+
+          def event_subscriber_options
+            @event_subscriber_options ||= {}
+          end
+        end
+
+        def initialize(configuration = self.class.default_configuration)
+          self.configuration = configuration
+        end
+
+        def configuration=(configuration)
+          @configuration = configuration
+          after_configuration_change
+        end
+
+        def emit(event)
+          self.class.event_subscriber_health.with_failure_health(
+            action: :emit,
+            component: self.class.event_subscriber_component
+          ) { emit_event(event) }
+        end
+
+        private
+
+        def after_configuration_change = nil
+      end
+    end
+  end
+end

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

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      module Facade
+        class << self
+          def emit(record = Core::UNSET, enforce_level: true, **fields)
+            record = Core.emit_input(record, fields)
+            runtime = RuntimeLocator.current
+            if runtime.respond_to?(:emit_integration)
+              runtime.emit_integration(record, enforce_level: enforce_level)
+            elsif enforce_level
+              runtime.emit(record)
+            else
+              runtime.emit_without_level(record)
+            end
+            nil
+          end
+
+          def with_execution(type:, **, &)
+            raise ArgumentError, "block required" unless block_given?
+
+            integration_write_section!(:execution)
+            RuntimeLocator.current.with_execution(type: type, owned: true, **, &)
+          end
+
+          def with_attributes(fields, &)
+            with_fields(:attributes, fields, &)
+          end
+
+          def with_neutral(fields, &)
+            with_fields(:neutral, fields, &)
+          end
+
+          def with_carry(fields, &)
+            with_fields(:carry, fields, &)
+          end
+
+          def with_context(fields, &)
+            with_fields(:context, fields, &)
+          end
+
+          def add_context(fields)
+            add_fields(:context, fields)
+          end
+
+          def add_attributes(fields)
+            add_fields(:attributes, fields)
+          end
+
+          def add_neutral(fields)
+            add_fields(:neutral, fields)
+          end
+
+          def add_carry(fields)
+            add_fields(:carry, fields)
+          end
+
+          def add_summary_attributes(fields)
+            add_summary_fields(fields, :add_summary_attributes)
+          end
+
+          def add_summary_neutral(fields)
+            add_summary_fields(fields, :add_summary_neutral)
+          end
+
+          def summary_active?
+            current_scope?
+          end
+
+          def increment_summary_attribute(*path, by: 1)
+            scope = ContextStore.current.current_scope
+            return unless scope
+
+            scope.increment_summary_attribute(path, by: by)
+            nil
+          end
+
+          private
+
+          def current_scope?
+            ContextStore.current.current_scope?
+          end
+
+          def with_fields(section, fields, &)
+            raise ArgumentError, "block required" unless block_given?
+
+            integration_write_section!(section)
+            case section
+            when :attributes then ContextStore.current.with_attributes(fields, owned: true, &)
+            when :carry then ContextStore.current.with_carry(fields, owned: true, &)
+            when :context then ContextStore.current.with_context(fields, owned: true, &)
+            when :neutral then ContextStore.current.with_neutral(fields, owned: true, &)
+            end
+          end
+
+          def add_fields(section, fields)
+            integration_write_section!(section)
+            case section
+            when :attributes then ContextStore.current.add_attributes(fields, owned: true)
+            when :carry then ContextStore.current.add_carry(fields, owned: true)
+            when :context then ContextStore.current.add_context(fields, owned: true)
+            when :neutral then ContextStore.current.add_neutral(fields, owned: true)
+            end
+            nil
+          end
+
+          def integration_write_section!(section)
+            # Keep the failure path close to the table it protects; new field
+            # bags should not become integration-writable by accident.
+            return if Fields::Bags.integration_write_sections.include?(section)
+
+            raise ArgumentError, "integration cannot write #{section}"
+          end
+
+          def add_summary_fields(fields, writer)
+            integration_write_section!(:summary)
+            scope = ContextStore.current.current_scope
+            return unless scope && fields.is_a?(Hash)
+
+            fields = Serialization::DeepCompactEmpty.compact_owned!(fields)
+            scope.public_send(writer, fields, owned: true) unless fields.empty?
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      module ForkHooks
+        Entry = Data.define(:integration, :component, :callback)
+        private_constant :Entry
+
+        @mutex = Mutex.new
+        @entries = {}
+
+        class << self
+          def register(integration, component:, &callback)
+            raise ArgumentError, "block required" unless callback
+
+            name = integration_name(integration)
+            component = component.to_sym
+            register_entry(name, component, callback)
+          end
+
+          def run
+            snapshot = mutex.synchronize { entries.values }
+            snapshot.each { run_entry(it) }
+            nil
+          end
+
+          def after_fork!
+            @mutex = Mutex.new
+            nil
+          end
+
+          def reset!
+            mutex.synchronize { entries.clear }
+            nil
+          end
+
+          private
+
+          attr_reader :entries, :mutex
+
+          def register_entry(name, component, callback)
+            mutex.synchronize do
+              entries[[name, component]] = Entry.new(name, component, callback)
+            end
+            nil
+          rescue StandardError => e
+            Diagnostics::ProcessIntegrationHealth.record_failure(
+              name,
+              e,
+              action: :register_after_fork,
+              component: component
+            )
+            nil
+          end
+
+          def run_entry(entry)
+            entry.callback.call
+          rescue StandardError => e
+            Diagnostics::ProcessIntegrationHealth.record_failure(
+              entry.integration,
+              e,
+              action: :after_fork,
+              component: entry.component
+            )
+            nil
+          end
+
+          def integration_name(value)
+            name = value.to_s
+            raise ArgumentError, "integration name is required" if name.empty?
+
+            name.to_sym
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      module Health
+        class << self
+          def record_failure(integration, error, runtime: nil, **metadata)
+            if runtime
+              runtime.record_integration_failure(integration, error, **metadata)
+            else
+              Diagnostics::ProcessIntegrationHealth.record_failure(integration, error, **metadata)
+            end
+            nil
+          end
+
+          def record_success(integration, runtime: nil, **)
+            if runtime
+              runtime.record_integration_success(integration)
+            else
+              Diagnostics::ProcessIntegrationHealth.record_success(integration)
+            end
+            nil
+          end
+
+          def with_failure_health(integration, component:, action:, runtime: nil, **metadata)
+            yield.tap { record_success(integration, runtime: runtime) }
+          rescue StandardError => e
+            record_failure(integration, e, runtime: runtime, component: component, action: action, **metadata)
+            nil
+          end
+
+          def scoped(integration, runtime: nil)
+            Scoped.new(integration, runtime: runtime)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      class IvarState
+        def initialize(marker)
+          @marker = marker
+        end
+
+        def fetch(owner)
+          return unless owner.respond_to?(:instance_variable_get)
+
+          owner.instance_variable_get(@marker)
+        rescue StandardError
+          nil
+        end
+
+        def store(owner, value)
+          return value unless owner.respond_to?(:instance_variable_set)
+
+          owner.instance_variable_set(@marker, value)
+          value
+        rescue StandardError
+          value
+        end
+
+        def fetch_or_store(owner)
+          existing = fetch(owner)
+          return existing if existing
+
+          store(owner, yield)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      module Lifecycle
+        class << self
+          def require_optional(path)
+            require path
+          rescue LoadError
+            nil
+          end
+
+          def register_after_fork(integration, component:, &)
+            ForkHooks.register(integration, component: component, &)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      class Scoped
+        def initialize(integration, runtime: nil)
+          @integration = integration
+          @runtime = runtime
+        end
+
+        def record_failure(error, **metadata)
+          Health.record_failure(@integration, error, runtime: @runtime, **metadata)
+        end
+
+        def record_success(*, **)
+          Health.record_success(@integration, runtime: @runtime)
+        end
+
+        def with_failure_health(component:, action:, **metadata, &)
+          Health.with_failure_health(
+            @integration,
+            component: component,
+            action: action,
+            runtime: @runtime,
+            **metadata,
+            &
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      module Settings
+        class << self
+          def included(base)
+            base.extend(ClassMethods)
+          end
+        end
+
+        module ClassMethods
+          def setting(name, default: nil, predicate: false, validate: nil, &block)
+            settings_defaults[name] = block || proc { default }
+            settings_validators[name] = validate if validate
+            ivar = :"@#{name}"
+
+            define_method(name) { instance_variable_get(ivar) }
+            define_method(:"#{name}=") do |value|
+              instance_variable_set(ivar, validate_setting(name, value))
+            end
+
+            define_method(:"#{name}?") { !!public_send(name) } if predicate
+          end
+
+          def byte_limit
+            proc { |value, name| Core::Validation.validate_byte_limit!(value, name: name) }
+          end
+
+          def integer_limit(positive: false)
+            proc { |value, name| Core::Validation.validate_integer_limit!(value, name: name, positive: positive) }
+          end
+
+          def settings_defaults
+            @settings_defaults ||= {}
+          end
+
+          def settings_validators
+            @settings_validators ||= {}
+          end
+        end
+
+        def initialize
+          initialize_settings
+        end
+
+        def validate!
+          validate_settings!
+          self
+        end
+
+        private
+
+        def initialize_settings
+          self.class.settings_defaults.each do |name, default|
+            public_send(:"#{name}=", setting_default(default))
+          end
+        end
+
+        def setting_default(default)
+          Core::Fields::FieldSet.deep_dup(instance_exec(&default))
+        end
+
+        def validate_settings!
+          self.class.settings_defaults.each_key do |name|
+            public_send(:"#{name}=", public_send(name))
+          end
+        end
+
+        def validate_setting(name, value)
+          validator = self.class.settings_validators[name]
+          return value unless validator
+
+          result = call_setting_validator(validator, name, value)
+          result.nil? ? value : result
+        end
+
+        def call_setting_validator(validator, name, value)
+          case validator
+          when Symbol
+            validator_method = method(validator)
+            validator_method.arity == 1 ? validator_method.call(value) : validator_method.call(value, name)
+          else
+            validator.arity == 1 ? instance_exec(value, &validator) : instance_exec(value, name, &validator)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Integration
+      # @api integration_spi
+      module SubscriberInstall
+        def subscriber = @subscription&.subscriber
+
+        def installed? = !subscriber.nil?
+
+        def reset!
+          @subscription&.reset
+          @subscription = nil
+        end
+
+        private
+
+        def update_subscription(configuration)
+          @subscription&.update(configuration)
+        end
+
+        def store_subscription(subscriber, unsubscribe: nil)
+          @subscription = Subscription.new(subscriber, unsubscribe: unsubscribe)
+          subscriber
+        end
+
+        def install_subscriber(configuration, enabled:)
+          return reset! unless enabled
+          return update_subscription(configuration) if installed?
+
+          subscriber = new(configuration)
+          unsubscribe = yield subscriber
+          store_subscription(subscriber, unsubscribe: unsubscribe)
+        end
+      end
+    end
+  end
+end