julewire-core 1.0.0

data/lib/julewire/core/processing/sampling.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Processing
+      # @api extension
+      module Sampling
+        HASH_SPACE = 1 << 64
+        FNV_OFFSET = 14_695_981_039_346_656_037
+        FNV_PRIME = 1_099_511_628_211
+        HASH_MASK = HASH_SPACE - 1
+        MIX_ONE = 0xff51afd7ed558ccd
+        MIX_TWO = 0xc4ceb9fe1a85ec53
+        private_constant :FNV_OFFSET, :FNV_PRIME, :HASH_MASK, :HASH_SPACE, :MIX_ONE, :MIX_TWO
+
+        class << self
+          def head(rate:, key: nil)
+            Head.new(rate: rate, key: key)
+          end
+
+          def keep?(rate:, key:)
+            threshold = threshold_for(rate)
+            return false if key.nil?
+
+            stable_hash(key) < threshold
+          end
+
+          def threshold_for(rate)
+            raise ArgumentError, "rate must be a finite Numeric between 0 and 1" unless valid_rate?(rate)
+
+            (rate * HASH_SPACE).floor
+          end
+
+          def stable_hash(value)
+            hash = key_string(value).each_byte.reduce(FNV_OFFSET) do |hash, byte|
+              ((hash ^ byte) * FNV_PRIME) & HASH_MASK
+            end
+            mix_hash(hash)
+          end
+
+          private
+
+          def valid_rate?(rate)
+            rate.between?(0, 1)
+          rescue StandardError
+            false
+          end
+
+          def mix_hash(hash)
+            hash ^= hash >> 33
+            hash = (hash * MIX_ONE) & HASH_MASK
+            hash ^= hash >> 33
+            hash = (hash * MIX_TWO) & HASH_MASK
+            hash ^ (hash >> 33)
+          end
+
+          def key_string(value)
+            case value
+            when String then value
+            when Symbol then value.name
+            else value.inspect
+            end
+          end
+        end
+
+        class Head
+          def initialize(rate:, key:)
+            @threshold = Sampling.threshold_for(rate)
+            @key = key
+            Validation.validate_callable!(key, name: :key, allow_nil: true)
+          end
+
+          def call(draft)
+            return :drop if @threshold.zero?
+
+            value = key_for(draft)
+            return :drop if value.nil?
+            return if @threshold == HASH_SPACE
+
+            Sampling.stable_hash(value) < @threshold ? nil : :drop
+          end
+
+          private
+
+          def key_for(draft)
+            @key ? @key.call(draft) : default_key(draft)
+          end
+
+          def default_key(draft)
+            root_id(draft) ||
+              field_value(draft[:execution], :id) ||
+              field_value(draft[:context], :request_id) ||
+              [draft[:source], draft[:event], draft[:message]].join("\0")
+          end
+
+          def root_id(draft)
+            field_value(draft.lineage.root_reference, :id) if draft.respond_to?(:lineage)
+          end
+
+          def field_value(hash, key)
+            return unless hash.is_a?(Hash)
+
+            Fields::FieldSet.value_for(hash, key)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/processing.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Processing
+      @factories = {}
+
+      class << self
+        def register(kind, &factory)
+          raise ArgumentError, "processor factory block required" unless factory
+
+          @factories[normalize_kind(kind)] = factory
+          nil
+        end
+
+        def build(kind, ...)
+          factory = factory_for(kind)
+          raise ArgumentError, "unknown processor kind #{kind.inspect}" unless factory
+
+          factory.call(...)
+        end
+
+        def factory_for(kind)
+          @factories[normalize_kind(kind)]
+        end
+
+        private
+
+        def normalize_kind(kind)
+          raise ArgumentError, "processor kind is required" if kind.nil?
+          raise ArgumentError, "processor kind must respond to #to_sym" unless kind.respond_to?(:to_sym)
+
+          name = kind.to_sym
+          raise ArgumentError, "processor kind cannot be empty" if name.name.empty?
+
+          name
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/propagation/carrier.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Julewire
+  module Core
+    module Propagation
+      # @api public
+      module Carrier
+        DEFAULT_KEY = "julewire"
+        DEFAULT_ENVELOPE = Core.sentinel(:default_envelope)
+        private_constant :DEFAULT_ENVELOPE
+
+        class << self
+          def encode(envelope: DEFAULT_ENVELOPE, max_bytes: nil)
+            Validation.validate_byte_limit!(max_bytes, name: :max_bytes)
+
+            encoded = JSON.generate(serialized_envelope(envelope), allow_nan: false)
+            return if max_bytes && encoded.bytesize > max_bytes
+
+            encoded
+          end
+
+          def inject(carrier = {}, envelope: DEFAULT_ENVELOPE, key: DEFAULT_KEY, max_bytes: nil)
+            validate_carrier!(carrier)
+            encoded = encode(envelope: envelope, max_bytes: max_bytes)
+            clear_carrier_key!(carrier, key) unless encoded
+            return unless encoded
+
+            carrier[key.to_s] = encoded
+            carrier
+          end
+
+          def extract(carrier, key: DEFAULT_KEY)
+            value = carrier_value(carrier, key)
+            return {} unless value
+
+            parsed = JSON.parse(value.to_s)
+            parsed.is_a?(Hash) ? Fields::FieldSet.deep_symbolize_keys(parsed) : {}
+          rescue StandardError
+            {}
+          end
+
+          def restore(carrier, key: DEFAULT_KEY, link_executions: false, &)
+            Propagation.restore(extract(carrier, key: key), link_executions: link_executions, &)
+          end
+
+          def serialized_envelope(envelope)
+            return Propagation.capture if envelope.equal?(DEFAULT_ENVELOPE)
+
+            Serialization::Serializer.call(envelope)
+          end
+
+          private
+
+          def carrier_value(carrier, key)
+            return unless carrier.respond_to?(:[])
+
+            carrier[key.to_s] || carrier[Fields::Internal.normalize_key(key)]
+          end
+
+          def validate_carrier!(carrier)
+            return if carrier.respond_to?(:[]=)
+
+            raise ArgumentError, "carrier must support []="
+          end
+
+          def clear_carrier_key!(carrier, key)
+            string_key = key.to_s
+            symbol_key = Fields::Internal.normalize_key(key)
+            if carrier.respond_to?(:delete)
+              begin
+                carrier.delete(string_key)
+                carrier.delete(symbol_key)
+              rescue StandardError
+                clear_carrier_key_by_assignment(carrier, string_key, symbol_key)
+              end
+            else
+              clear_carrier_key_by_assignment(carrier, string_key, symbol_key)
+            end
+          end
+
+          def clear_carrier_key_by_assignment(carrier, string_key, symbol_key)
+            carrier[string_key] = nil
+            carrier[symbol_key] = nil
+          rescue StandardError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/propagation.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    # @api public
+    module Propagation
+      FIELD_SECTIONS = (Fields::Bags.propagation_sections - [:execution]).freeze
+      private_constant :FIELD_SECTIONS
+
+      class << self
+        def capture
+          capture_with { Serialization::Serializer.call(it) }
+        end
+
+        def capture_local
+          capture_with { Fields::FieldSet.deep_dup(it) }
+        end
+
+        def restore(envelope, link_executions: false, &)
+          raise ArgumentError, "block required" unless block_given?
+
+          sections = FIELD_SECTIONS.to_h { |section| [section, hash_value(envelope, section)] }
+          execution = hash_value(envelope, :execution)
+          ContextStore.current.with_propagation(
+            **sections,
+            execution: execution,
+            link_executions: link_executions,
+            &
+          )
+        end
+
+        private
+
+        def capture_with
+          store = ContextStore.current
+          scope = store.current_scope_or_snapshot
+          envelope = FIELD_SECTIONS.to_h { |section| [section, yield(store.public_send(:"#{section}_hash"))] }
+          execution = scope ? scope.execution_hash : {}
+          envelope[:execution] = yield(execution) unless execution.empty?
+          envelope
+        end
+
+        def hash_value(hash, key)
+          value = Fields::FieldSet.value_for(hash, key)
+          value.is_a?(Hash) ? value : {}
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/records/console_formatter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Records
+      # @api extension
+      class ConsoleFormatter
+        def call(record)
+          Record.validate_normalized!(record)
+
+          {
+            event: record[:event],
+            labels: record[:labels],
+            message: DisplayMessage.call(record),
+            payload: record[:payload],
+            severity: record[:severity],
+            source: record[:source],
+            timestamp: record[:timestamp]
+          }
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/records/deconstruct.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Records
+      module Deconstruct
+        # Host record classes expose their immutable field hash through @data.
+        def deconstruct_keys(keys)
+          return to_h unless keys
+
+          keys.each_with_object({}) do |key, selected|
+            selected[key] = Fields::FieldSet.deep_dup(@data[key]) if @data.key?(key)
+          end
+        end
+      end
+      private_constant :Deconstruct
+    end
+  end
+end

data/lib/julewire/core/records/display_message.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Records
+      class DisplayMessage
+        class << self
+          def call(record)
+            error = value_at(record, :error)
+            metrics = value_at(record, :metrics)
+            neutral = value_at(record, :neutral)
+
+            explicit_message(record) || neutral_message(neutral, error, metrics) || error_summary(error)
+          end
+
+          def error_summary(error)
+            error = hash_error(error)
+
+            error_class = value_at(error, :class)
+            error_message = value_at(error, :message)
+            error_class = nil if blank?(error_class)
+            error_message = nil if blank?(error_message)
+            return unless error_class || error_message
+            return error_message.to_s unless error_class
+            return error_class.to_s unless error_message
+
+            "#{error_class}: #{error_message}"
+          end
+
+          private
+
+          def explicit_message(record)
+            message = value_at(record, :message)
+            message unless blank?(message)
+          end
+
+          def neutral_message(neutral, error, metrics)
+            http_message(neutral, error, metrics) ||
+              job_message(neutral, error, metrics) ||
+              messaging_message(neutral, error, metrics) ||
+              source_location_message(neutral)
+          end
+
+          def http_message(neutral, error, metrics)
+            method = neutral_value(neutral, Fields::AttributeKeys::HTTP_REQUEST_METHOD)
+            path = neutral_value(neutral, Fields::AttributeKeys::URL_PATH) ||
+                   neutral_value(neutral, Fields::AttributeKeys::URL_FULL)
+            status = neutral_value(neutral, Fields::AttributeKeys::HTTP_RESPONSE_STATUS_CODE)
+            return if blank?(method) || blank?(path) || blank?(status)
+
+            message = "#{method} #{path} -> #{status}"
+            append_part(message, error_class(error))
+            append_part(message, duration(metrics))
+          end
+
+          def job_message(neutral, error, metrics)
+            system = neutral_value(neutral, Fields::AttributeKeys::JOB_SYSTEM)
+            name = neutral_value(neutral, Fields::AttributeKeys::JOB_NAME)
+            id = neutral_value(neutral, Fields::AttributeKeys::JOB_ID)
+            status = neutral_value(neutral, Fields::AttributeKeys::JOB_STATUS)
+            return if blank?(system) && blank?(name) && blank?(id)
+
+            message = phrase(system || "job", name || id)
+            append_part(message, key_value("queue", job_queue(neutral)))
+            append_part(message, status_phrase(status, error, metrics))
+          end
+
+          def messaging_message(neutral, error, metrics)
+            system = neutral_value(neutral, Fields::AttributeKeys::MESSAGING_SYSTEM)
+            operation = neutral_value(neutral, Fields::AttributeKeys::MESSAGING_OPERATION_NAME)
+            destination = neutral_value(neutral, Fields::AttributeKeys::MESSAGING_DESTINATION_NAME)
+            return if blank?(system) && blank?(operation) && blank?(destination)
+
+            message = phrase(system || "messaging", operation)
+            append_part(message, destination)
+            append_part(message, key_value(
+                                   "partition",
+                                   neutral_value(neutral, Fields::AttributeKeys::MESSAGING_DESTINATION_PARTITION_ID)
+                                 ))
+            append_part(message, key_value("offset", neutral_value(neutral, Fields::AttributeKeys::MESSAGING_KAFKA_OFFSET)))
+            append_part(message, key_value(
+                                   "messages",
+                                   neutral_value(neutral, Fields::AttributeKeys::MESSAGING_BATCH_MESSAGE_COUNT)
+                                 ))
+            append_part(message, error_class(error))
+            append_part(message, duration(metrics))
+          end
+
+          def source_location_message(neutral)
+            file = neutral_value(neutral, Fields::AttributeKeys::CODE_FILE_PATH)
+            return if blank?(file)
+
+            line = neutral_value(neutral, Fields::AttributeKeys::CODE_LINE_NUMBER)
+            function = neutral_value(neutral, Fields::AttributeKeys::CODE_FUNCTION_NAME)
+            message = line ? "#{file}:#{line}" : file.to_s.dup
+            append_part(message, function)
+          end
+
+          def status_phrase(status, error, metrics)
+            message = append_part(nil, status)
+            message = append_part(message, error_class(error))
+            message = append_part(message, duration(metrics))
+            return unless message
+
+            "-> #{message}"
+          end
+
+          def error_class(error)
+            value_at(hash_error(error), :class)
+          end
+
+          def duration(metrics)
+            duration_ms = value_at(metrics, :duration_ms)
+            "in #{duration_text(Float(duration_ms))}ms"
+          rescue ArgumentError, TypeError
+            nil
+          end
+
+          def duration_text(value)
+            text = format("%.3f", value.round(3))
+            text.delete_suffix!("0") while text.end_with?("0")
+            text.delete_suffix!(".")
+            text
+          end
+
+          def job_queue(neutral)
+            neutral_value(neutral, Fields::AttributeKeys::JOB_QUEUE_NAME)
+          end
+
+          def hash_error(error)
+            error if error.is_a?(Hash)
+          end
+
+          def neutral_value(neutral, key)
+            value_at(neutral, key)
+          end
+
+          def key_value(name, value)
+            "#{name}=#{value}" unless blank?(value)
+          end
+
+          def phrase(first, second)
+            message = first.to_s.dup
+            append_part(message, second)
+          end
+
+          def append_part(message, part)
+            return message if blank?(part)
+
+            return part.to_s.dup unless message
+
+            message << " " << part.to_s
+          end
+
+          def value_at(value, key)
+            Fields::Lookup.value(value, key)
+          end
+
+          def blank?(value)
+            Fields::Lookup.blank?(value)
+          end
+        end
+      end
+    end
+  end
+end