julewire-core 1.0.0

data/lib/julewire/core/execution/view.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Execution
+      # @api public
+      # Read-only view returned by Julewire.current_execution.
+      class View
+        attr_reader :finished_at, :id, :lineage, :started_at, :type
+
+        def initialize(scope)
+          @scope = scope
+          @id = scope.id
+          @type = scope.type
+          @started_at = scope.started_at
+          @finished_at = scope.finished_at
+          @parent_scope = scope.parent
+          @lineage = scope.lineage
+          @parent = nil
+          @execution_hash = nil
+          @context_hash = nil
+          @carry_hash = nil
+          @neutral_hash = nil
+          @attributes_hash = nil
+          @labels_hash = nil
+          @summary_hash = nil
+          @metrics_hash = nil
+        end
+
+        def parent
+          return unless @parent_scope
+
+          @parent ||= self.class.new(@parent_scope)
+        end
+
+        def execution_hash = Fields::FieldSet.deep_dup(@execution_hash ||= @scope.frozen_execution_hash)
+
+        def context_hash = Fields::FieldSet.deep_dup(@context_hash ||= @scope.context_hash)
+
+        def carry_hash = Fields::FieldSet.deep_dup(@carry_hash ||= @scope.carry_hash)
+
+        def neutral_hash = Fields::FieldSet.deep_dup(@neutral_hash ||= @scope.neutral_hash)
+
+        def attributes_hash = Fields::FieldSet.deep_dup(@attributes_hash ||= @scope.attributes_hash)
+
+        def labels_hash = Fields::FieldSet.deep_dup(@labels_hash ||= @scope.frozen_labels_hash)
+
+        def summary_hash = Fields::FieldSet.deep_dup(@summary_hash ||= @scope.summary_hash)
+
+        def metrics_hash = Fields::FieldSet.deep_dup(@metrics_hash ||= @scope.metrics_hash)
+
+        def finished? = !finished_at.nil?
+      end
+    end
+  end
+end

data/lib/julewire/core/facade_methods.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module FacadeMethods
+      def runtime(name = :default)
+        Core::RuntimeRegistry.fetch(name, current: Core::RuntimeLocator.current)
+      end
+
+      def config = runtime.config
+
+      def configure(&) = runtime.configure(&)
+
+      def context = runtime.context
+
+      def attributes = runtime.attributes
+
+      def carry = runtime.carry
+
+      def current_execution = runtime.current_execution
+
+      def current_execution? = runtime.current_execution?
+
+      def emit(record = Core::UNSET, **fields, &)
+        runtime.emit(record, **fields, &)
+      end
+
+      def debug(record = Core::UNSET, **fields, &)
+        emit_with_severity(:debug, record, fields, &)
+      end
+
+      def info(record = Core::UNSET, **fields, &)
+        emit_with_severity(:info, record, fields, &)
+      end
+
+      def warn(record = Core::UNSET, **fields, &)
+        emit_with_severity(:warn, record, fields, &)
+      end
+
+      def error(record = Core::UNSET, **fields, &)
+        emit_with_severity(:error, record, fields, &)
+      end
+
+      def fatal(record = Core::UNSET, **fields, &)
+        emit_with_severity(:fatal, record, fields, &)
+      end
+
+      def unknown(record = Core::UNSET, **fields, &)
+        emit_with_severity(:unknown, record, fields, &)
+      end
+
+      def flush(timeout: Core::UNSET)
+        runtime.flush(timeout: timeout)
+      end
+
+      def health = runtime.health
+
+      def measure(key, &)
+        summary.measure(key, &)
+      end
+
+      def measure_start(key) = summary.measure_start(key)
+
+      def doctor(name = :default)
+        Core::Diagnostics::Doctor.call(runtime(name))
+      end
+
+      def tail(name = :default, **)
+        Core::Diagnostics::Tail.attach!(runtime(name), **)
+      end
+
+      def observe_self!(name = :default, **)
+        Core::Diagnostics::MetaObserver.attach!(name, **)
+      end
+
+      def dev!(name = :default, output: $stdout, color: Core::UNSET, chaos: false, banner: chaos, tail: true)
+        color = output.respond_to?(:tty?) ? output.tty? : true if color.equal?(Core::UNSET)
+        punk!(name, output: output, color: color, chaos: chaos, banner: banner)
+        return unless tail
+
+        tail_options = tail == true ? {} : tail
+        raise ArgumentError, "tail must be true, false, or an options Hash" unless tail_options.is_a?(Hash)
+
+        Core::Diagnostics::Tail.attach!(runtime(name), **tail_options)
+      end
+
+      def punk!(name = :default, output: $stdout, color: true, chaos: false, banner: chaos)
+        output.write(punk_banner) if banner
+        output = punk_chaos_output(output, chaos) if chaos
+
+        runtime(name).configure do |config|
+          config.destinations.clear
+          config.destinations.use(
+            :default,
+            formatter: ConsoleFormatter.new,
+            encoder: TextEncoder.new(color: color, theme: :punk),
+            output: output
+          )
+        end
+      end
+
+      def fiber(**, &)
+        raise ArgumentError, "block required" unless block_given?
+
+        envelope = Core::Propagation.capture_local
+        Fiber.new(**) do |*args|
+          with_cleared_configure_guard do
+            Core::Propagation.restore(envelope) { yield(*args) }
+          end
+        end
+      end
+
+      def labels = runtime.labels
+
+      def after_fork! = runtime.after_fork!
+
+      def reset! = runtime.reset!
+
+      def close(timeout: Core::UNSET)
+        runtime.close(timeout: timeout)
+      end
+
+      def summary = runtime.summary
+
+      def start_execution(type:, **)
+        runtime.start_execution(type: type, **)
+      end
+
+      def thread(*, &)
+        raise ArgumentError, "block required" unless block_given?
+
+        envelope = Core::Propagation.capture_local
+        Thread.new(*) do |*thread_args|
+          with_cleared_configure_guard do
+            Core::Propagation.restore(envelope) { yield(*thread_args) }
+          end
+        end
+      end
+
+      def with_execution(type:, **, &)
+        runtime.with_execution(type: type, **, &)
+      end
+
+      private
+
+      def punk_banner
+        "!!JULEWIRE PUNK!! chaos containment armed\n"
+      end
+
+      def punk_chaos_output(output, chaos)
+        options = chaos.is_a?(Hash) ? chaos : {}
+        Core::Destinations::ChaosOutput.new(output, **options)
+      end
+
+      def emit_with_severity(severity, record, fields, &)
+        if record.equal?(Core::UNSET)
+          fields.delete("severity")
+          fields[:severity] = severity
+          runtime.emit(fields, &)
+        elsif !block_given? && !record.is_a?(Hash)
+          # Scalar eager logs stay allocation-light; lazy inputs need the wrapper
+          # so block-built records can still receive the eager severity.
+          input = fields.empty? ? { message: record.to_s } : Core.emit_input(record, fields)
+          input.delete("severity")
+          input[:severity] = severity
+          runtime.emit(input)
+        else
+          runtime.emit(Core::Records::LazyEmitInput.with_severity(severity, Core.emit_input(record, fields)), &)
+        end
+      end
+
+      def with_cleared_configure_guard
+        previous_guard = Fiber[Core::Runtime::CONFIGURE_GUARD_KEY]
+        Fiber[Core::Runtime::CONFIGURE_GUARD_KEY] = nil
+        yield
+      ensure
+        Fiber[Core::Runtime::CONFIGURE_GUARD_KEY] = previous_guard
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+# shareable_constant_value: literal
+
+module Julewire
+  module Core
+    module Fields
+      # @api integration_spi
+      module AttributeKeys
+        HTTP_REQUEST_METHOD = :"http.request.method"
+        HTTP_RESPONSE_BODY_SIZE = :"http.response.body.size"
+        HTTP_RESPONSE_STATUS_CODE = :"http.response.status_code"
+        URL_FULL = :"url.full"
+        URL_PATH = :"url.path"
+        USER_AGENT_ORIGINAL = :"user_agent.original"
+        CLIENT_ADDRESS = :"client.address"
+
+        CODE_FILE_PATH = :"code.file.path"
+        CODE_FUNCTION_NAME = :"code.function.name"
+        CODE_LINE_NUMBER = :"code.line.number"
+
+        MESSAGING_BATCH_MESSAGE_COUNT = :"messaging.batch.message_count"
+        MESSAGING_CONSUMER_GROUP_NAME = :"messaging.consumer.group.name"
+        MESSAGING_DESTINATION_NAME = :"messaging.destination.name"
+        MESSAGING_DESTINATION_PARTITION_ID = :"messaging.destination.partition.id"
+        MESSAGING_KAFKA_MESSAGE_KEY = :"messaging.kafka.message.key"
+        MESSAGING_KAFKA_OFFSET = :"messaging.kafka.offset"
+        MESSAGING_OPERATION_NAME = :"messaging.operation.name"
+        MESSAGING_OPERATION_TYPE = :"messaging.operation.type"
+        MESSAGING_SYSTEM = :"messaging.system"
+
+        JOB_ENQUEUED_AT = :"job.enqueued_at"
+        JOB_EXECUTION_COUNT = :"job.execution_count"
+        JOB_ID = :"job.id"
+        JOB_NAME = :"job.name"
+        JOB_PRIORITY = :"job.priority"
+        JOB_PROVIDER_ID = :"job.provider_id"
+        JOB_QUEUE_NAME = :"job.queue.name"
+        JOB_SCHEDULED_AT = :"job.scheduled_at"
+        JOB_STATUS = :"job.status"
+        JOB_SYSTEM = :"job.system"
+
+        class << self
+          def fields(fields)
+            return {} unless fields.is_a?(Hash)
+
+            fields.compact
+          end
+
+          def from(neutral) = neutral.is_a?(Hash) ? neutral : {}
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      class AttributesProxy < SectionProxy
+        def initialize(store) = super(store, :attributes)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      # @api extension
+      module Bags
+        Definition = Data.define(
+          :name,
+          :record_hash,
+          :transform_container,
+          :app_write,
+          :integration_write,
+          :propagate,
+          :emit_by_default,
+          :delete_paths,
+          :stack
+        )
+        RECORD_SCALAR_KEYS = %i[
+          timestamp
+          severity
+          kind
+          event
+          message
+          logger
+          source
+        ].freeze
+
+        class << self
+          private
+
+          def define(name, **capabilities)
+            Definition.new(
+              name: name,
+              record_hash: true,
+              transform_container: true,
+              app_write: false,
+              integration_write: false,
+              propagate: false,
+              emit_by_default: true,
+              delete_paths: false,
+              stack: false,
+              **capabilities
+            )
+          end
+        end
+
+        DEFINITIONS = {
+          execution: define(:execution, integration_write: true, propagate: true),
+          context: define(
+            :context,
+            app_write: true,
+            integration_write: true,
+            propagate: true,
+            stack: true
+          ),
+          carry: define(
+            :carry,
+            app_write: true,
+            integration_write: true,
+            propagate: true,
+            emit_by_default: false,
+            delete_paths: true,
+            stack: true
+          ),
+          neutral: define(:neutral, integration_write: true, emit_by_default: false, stack: true),
+          attributes: define(
+            :attributes,
+            app_write: true,
+            integration_write: true,
+            stack: true
+          ),
+          labels: define(:labels),
+          payload: define(:payload),
+          metrics: define(:metrics),
+          error: define(:error, record_hash: false),
+          summary: define(
+            :summary,
+            record_hash: false,
+            transform_container: false,
+            integration_write: true,
+            emit_by_default: false
+          )
+        }.freeze
+        private_constant :Definition, :DEFINITIONS, :RECORD_SCALAR_KEYS
+
+        class << self
+          def definition(name) = DEFINITIONS.fetch(name)
+
+          def record_scalar_keys = RECORD_SCALAR_KEYS
+
+          def record_hash_sections = select_names(:record_hash)
+
+          def required_record_keys = (record_scalar_keys + record_hash_sections + %i[error]).freeze
+
+          def transform_container_sections = select_names(:transform_container)
+
+          def hidden_output_sections
+            DEFINITIONS.filter_map do |name, definition|
+              name if definition.record_hash && !definition.emit_by_default
+            end.freeze
+          end
+
+          def app_write_sections = select_names(:app_write)
+
+          def integration_write_sections = select_names(:integration_write)
+
+          def propagation_sections = select_names(:propagate)
+
+          def stack_sections = select_names(:stack)
+
+          def delete_paths?(name) = definition(name).delete_paths
+
+          private
+
+          def select_names(attribute)
+            DEFINITIONS.filter_map { |name, definition| name if definition.public_send(attribute) }.freeze
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      class CarryProxy < SectionProxy
+        def initialize(store) = super(store, :carry)
+
+        def delete(*path)
+          @store.delete_carry(path)
+          self
+        end
+
+        def without(*path, &)
+          raise ArgumentError, "block required" unless block_given?
+
+          @store.without_carry(path, &)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      class ContextProxy < SectionProxy
+        def initialize(store) = super(store, :context)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Fields
+      # @api integration_spi
+      module FieldSet
+        VALUE_KEY = :value
+
+        class << self
+          # Public ingress accepts String or Symbol keys. Core stores Symbol keys
+          # after normalization so extension contracts stay simple.
+          def coerce(fields = nil, keyword_fields = {}, invalid: :ignore)
+            coerced = {}
+            coerce_fields!(coerced, fields, invalid: invalid) unless fields.nil?
+            merge!(coerced, keyword_fields) unless keyword_fields.empty?
+            coerced
+          end
+
+          def merge(left, right)
+            merge!(deep_symbolize_keys(left), right)
+          end
+
+          def merge!(target, fields)
+            return target unless fields.is_a?(Hash)
+
+            fields.each do |key, value|
+              target[Fields::Internal.normalize_key(key)] = copy_field_value(value)
+            end
+
+            target
+          end
+
+          def deep_dup(value)
+            return {} if value.is_a?(Hash) && value.empty?
+            return [] if value.is_a?(Array) && value.empty?
+
+            Serialization::ValueCopy.call(value)
+          end
+
+          def deep_symbolize_keys(value)
+            return {} if value.is_a?(Hash) && value.empty?
+            return [] if value.is_a?(Array) && value.empty?
+
+            Serialization::ValueCopy.call(value, symbolize_keys: true)
+          end
+
+          def frozen_copy(value)
+            Fields::Internal.frozen_copy(value)
+          end
+
+          def value_for(hash, key, default: nil)
+            return default unless hash.is_a?(Hash)
+
+            normalized = key.is_a?(String) ? Fields::Internal.normalize_key(key) : key
+            return hash[normalized] if hash.key?(normalized)
+
+            default
+          end
+
+          private
+
+          def coerce_fields!(target, fields, invalid:)
+            if fields.is_a?(Hash)
+              merge!(target, fields)
+            elsif invalid == :wrap
+              target[VALUE_KEY] = deep_dup(fields)
+            elsif invalid == :raise
+              raise ArgumentError, "fields must be a Hash"
+            end
+          end
+
+          def copy_field_value(value) = deep_symbolize_keys(value)
+        end
+      end
+    end
+  end
+end