julewire-core 1.0.0

data/lib/julewire/core/testing/contracts/runtime.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module Contracts
+        module Runtime
+          def assert_julewire_runtime_integration_contract(**options)
+            run_julewire_runtime_contract(options)
+          end
+
+          def assert_julewire_execution_boundary_contract(**options)
+            run_julewire_execution_boundary_contract(options)
+          end
+
+          def assert_julewire_failure_containment_contract(configure:, destination_name: :default, emit: nil)
+            Julewire.configure(&configure)
+
+            assert_nil((emit || default_failure_contract_emit).call)
+
+            health = Julewire.health
+            destination_health = health.dig(:pipeline, :destinations, destination_name.to_sym)
+
+            assert_equal :degraded, health.fetch(:status)
+            assert_kind_of Hash, destination_health
+
+            [health, destination_health]
+          end
+
+          def assert_julewire_record_source_contract(
+            records:,
+            event:,
+            source:,
+            **options
+          )
+            record = find_contract_record(records, options.fetch(:event_path, %w[event]), event)
+
+            assert_equal source.to_s, fetch_contract_path(record, options.fetch(:source_path, %w[source])).to_s
+            assert_contract_optional_source_field(record, options, :logger)
+            assert_contract_optional_source_field(record, options, :kind)
+
+            record
+          end
+
+          private
+
+          def assert_contract_optional_source_field(record, options, field)
+            expected = options[field]
+            return unless expected
+
+            path = options.fetch(:"#{field}_path", [field.to_s])
+            assert_equal expected.to_s, fetch_contract_path(record, path).to_s
+          end
+
+          def run_julewire_runtime_contract(options)
+            Julewire.configure(&options.fetch(:configure))
+            emit_runtime_contract_records
+
+            records = options.fetch(:records).call
+            point = find_contract_record(records, options.fetch(:event_path), point_event(options))
+            summary = find_contract_record(records, options.fetch(:event_path), summary_event(options))
+            health = Julewire.health
+
+            assert_runtime_contract_records(point, summary, health, options)
+            [point, summary, health]
+          end
+
+          def run_julewire_execution_boundary_contract(options)
+            Julewire.configure(&options.fetch(:configure))
+            options.fetch(:exercise).call(**execution_boundary_probe(options))
+            Julewire.flush
+
+            records = options.fetch(:records).call
+            point = find_contract_record(records, options.fetch(:event_path), point_event(options))
+            summary = find_contract_record(records, options.fetch(:event_path), summary_event(options))
+            health = Julewire.health
+
+            assert_runtime_contract_records(point, summary, health, options)
+            [point, summary, health]
+          end
+
+          def emit_runtime_contract_records
+            Julewire.with_execution(
+              type: :contract,
+              id: "contract-1",
+              summary_event: "contract.completed",
+              summary_source: "contract"
+            ) do
+              Julewire.context.add(request_id: "request-1")
+              Julewire.carry.add(http: { request_headers: { traceparent: contract_traceparent } })
+              Julewire.summary.add(total: 2)
+              Julewire.emit(event: point_event({}), source: "contract", message: "point", payload: { value: 1 })
+            end
+            Julewire.flush
+          end
+
+          def assert_runtime_contract_records(point, summary, health, options)
+            assert_equal "request-1", fetch_contract_path(point, options.fetch(:context_path) + [:request_id])
+            assert_equal 2, fetch_contract_path(summary, options.fetch(:summary_payload_path) + [:total])
+            assert_runtime_contract_carry(point, options[:carry_path]) if options[:carry_path]
+
+            assert health.dig(:pipeline, :configured)
+            assert_kind_of Hash, health.dig(:pipeline, :destinations, contract_destination_name(options))
+          end
+
+          def assert_runtime_contract_carry(point, carry_path)
+            path = carry_path + %i[http request_headers traceparent]
+
+            assert_equal contract_traceparent, fetch_contract_path(point, path)
+          end
+
+          def contract_destination_name(options)
+            options.fetch(:destination_name, :default).to_sym
+          end
+
+          def default_failure_contract_emit
+            lambda do
+              Julewire.emit(
+                event: "contract.failure",
+                source: "contract",
+                message: "failure probe",
+                payload: { token: "secret" }
+              )
+            end
+          end
+
+          def execution_boundary_probe(options)
+            {
+              add_summary: -> { Julewire.summary.add(total: 2) },
+              carry: { http: { request_headers: { traceparent: contract_traceparent } } },
+              context: { request_id: "request-1" },
+              emit_point: lambda do
+                Julewire.emit(event: point_event(options), source: "contract", message: "point", payload: { value: 1 })
+              end,
+              summary_event: summary_event(options),
+              traceparent: contract_traceparent
+            }
+          end
+
+          def point_event(options)
+            options.fetch(:point_event, "contract.point")
+          end
+
+          def summary_event(options)
+            options.fetch(:summary_event, "contract.completed")
+          end
+
+          def find_contract_record(records, event_path, event)
+            record = records.find { fetch_contract_path(it, event_path) == event }
+            return record if record
+
+            flunk("expected contract record #{event.inspect}, got #{records.inspect}")
+          end
+
+          def fetch_contract_path(value, path)
+            path.reduce(value) { |current, key| fetch_contract_key(current, key) }
+          end
+
+          def fetch_contract_key(value, key)
+            return value.fetch(key) if value.respond_to?(:key?) && value.key?(key)
+            return value.fetch(key.to_s) if value.respond_to?(:key?) && value.key?(key.to_s)
+            return fetch_symbol_contract_key(value, key) if key.respond_to?(:to_sym)
+
+            flunk("expected key #{key.inspect} in #{value.inspect}")
+          end
+
+          def fetch_symbol_contract_key(value, key)
+            return value.fetch(key.to_sym) if value.respond_to?(:key?) && value.key?(key.to_sym)
+
+            flunk("expected key #{key.inspect} in #{value.inspect}")
+          end
+
+          def contract_traceparent = "00-06796866738c859f2f19b7cfb3214824-000000000000004a-01"
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/contracts/wire.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module Contracts
+        module Wire
+          def assert_julewire_propagation_contract(key: Julewire::Core::Propagation::Carrier::DEFAULT_KEY)
+            carrier = {}
+            extracted = nil
+            restored = nil
+
+            Julewire.with_execution(type: :contract, id: "contract-1", emit_summary: false) do
+              Julewire.context.add(request_id: "request-1")
+              Julewire.carry.add(http: { request_headers: { traceparent: contract_traceparent } })
+
+              assert_same carrier, Julewire::Core::Propagation::Carrier.inject(carrier, key: key)
+
+              extracted = Julewire::Core::Propagation::Carrier.extract(carrier, key: key)
+              assert_equal "request-1", extracted.dig(:context, :request_id)
+              assert_equal contract_traceparent, extracted.dig(:carry, :http, :request_headers, :traceparent)
+              assert_equal "contract-1", extracted.dig(:execution, :id)
+
+              Julewire::Core::Propagation::Carrier.restore(carrier, key: key) do
+                restored = Julewire::Core::Propagation.capture_local
+              end
+            end
+
+            assert_equal "request-1", restored.dig(:context, :request_id)
+            assert_equal contract_traceparent, restored.dig(:carry, :http, :request_headers, :traceparent)
+            assert_equal "contract-1", restored.dig(:execution, :id)
+            assert_oversize_carrier_clears_stale_value!(key)
+
+            extracted
+          end
+
+          private
+
+          def assert_oversize_carrier_clears_stale_value!(key)
+            string_key = key.to_s
+            symbol_key = key.is_a?(String) ? key.to_sym : key
+            carrier = { string_key => "stale" }
+            carrier[symbol_key] = "stale" if symbol_key != string_key
+
+            result = Julewire::Core::Propagation::Carrier.inject(
+              carrier,
+              envelope: { context: { large: "x" * 64 } },
+              key: key,
+              max_bytes: 1
+            )
+
+            assert_nil result
+            refute carrier.key?(string_key)
+            refute carrier.key?(symbol_key) if symbol_key != string_key
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/contracts.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "contracts/component"
+require_relative "contracts/deadline_scheduler"
+require_relative "contracts/integration"
+require_relative "contracts/record_draft"
+require_relative "contracts/runtime"
+require_relative "contracts/wire"
+
+module Julewire
+  module Core
+    module Testing
+      # @api extension
+      module Contracts
+        include Component
+        include DeadlineScheduler
+        include Integration
+        include RecordDraft
+        include Runtime
+        include Wire
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/coverage.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      # @api extension
+      module Coverage
+        DEFAULT_MINIMUM_LINE = 96
+        DEFAULT_MINIMUM_BRANCH = 87
+
+        class << self
+          def start!(minimum_line: DEFAULT_MINIMUM_LINE, minimum_branch: DEFAULT_MINIMUM_BRANCH, filters: [])
+            return unless ENV["COVERAGE"]
+
+            require "simplecov"
+            require "simplecov-lcov"
+
+            configure_lcov_formatter
+            configure_formatters
+            start_simplecov(minimum_line: minimum_line, minimum_branch: minimum_branch, filters: filters)
+            nil
+          end
+
+          def configure_lcov_formatter
+            SimpleCov::Formatter::LcovFormatter.config do |config|
+              config.report_with_single_file = true
+              config.output_directory = "coverage/lcov"
+              config.lcov_file_name = "lcov.info"
+              config.single_report_path = "coverage/lcov/lcov.info"
+            end
+          end
+
+          def configure_formatters
+            SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new(
+              [
+                SimpleCov::Formatter::HTMLFormatter,
+                SimpleCov::Formatter::LcovFormatter
+              ]
+            )
+          end
+
+          def start_simplecov(minimum_line:, minimum_branch:, filters:)
+            SimpleCov.start do
+              enable_coverage :branch
+              minimum_coverage line: minimum_line, branch: minimum_branch if minimum_line || minimum_branch
+              track_files "lib/**/*.rb"
+              add_filter "/test/"
+              add_filter "/lib/julewire/core/testing/coverage.rb"
+              add_filter %r{/lib/julewire/[^/]+/version\.rb\z}
+              add_filter %r{/lib/julewire-[^/]+\.rb\z}
+              filters.each { add_filter(it) }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing/test_reports.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    module Testing
+      module TestReports
+        module CodecovJUnitReportMethods
+          def report
+            return super unless @single_file
+
+            puts "Writing XML reports to #{reports_path}"
+            File.write(filename_for("minitest"), testsuites_xml)
+          end
+
+          private
+
+          def testsuites_xml
+            suites = tests.group_by { test_class(it) }
+            result = analyze_suite(tests)
+            xml = Builder::XmlMarkup.new(indent: 2)
+            xml.instruct!
+            xml.testsuites(testsuite_result_attributes(result)) do
+              suites.each do |suite, suite_tests|
+                parse_xml_for(xml, suite, suite_tests)
+              end
+            end
+
+            xml.target!
+          end
+
+          def testsuite_result_attributes(result)
+            {
+              name: "minitest",
+              skipped: result[:skip_count],
+              failures: result[:fail_count],
+              errors: result[:error_count],
+              tests: result[:test_count],
+              assertions: result[:assertion_count],
+              time: result[:time]
+            }
+          end
+        end
+        private_constant :CodecovJUnitReportMethods
+
+        module_function
+
+        def start!(enabled: ENV.fetch("JULEWIRE_JUNIT", nil),
+                   reports_dir: ENV.fetch("JULEWIRE_JUNIT_DIR", "test/reports"))
+          return unless enabled
+
+          require "fileutils"
+          require "minitest/reporters"
+
+          FileUtils.mkdir_p(reports_dir)
+          junit = junit_reporter_class.new(
+            reports_dir,
+            true,
+            base_path: Dir.pwd,
+            include_timestamp: true,
+            single_file: true
+          )
+
+          Minitest::Reporters.use!(
+            [Minitest::Reporters::DefaultReporter.new, junit],
+            ENV,
+            Minitest.backtrace_filter
+          )
+        end
+
+        def junit_reporter_class
+          @junit_reporter_class ||= Class.new(Minitest::Reporters::JUnitReporter) do
+            include CodecovJUnitReportMethods
+          end
+        end
+      end
+    end
+  end
+end

data/lib/julewire/core/testing.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    # @api extension
+    module Testing
+      # @api extension
+      class CaptureDestination
+        attr_reader :name, :records
+
+        def initialize(name: :capture, snapshot: true)
+          @name = name
+          @snapshot = snapshot
+          @records = []
+        end
+
+        def emit(record)
+          @records << (@snapshot ? record.to_h : record)
+          nil
+        end
+
+        def flush(*)
+          self
+        end
+
+        def close(*)
+          self
+        end
+
+        def health
+          { status: :ok, counts: { captured: @records.size } }
+        end
+
+        def clear
+          @records.clear
+          self
+        end
+      end
+
+      # @api extension
+      class NullOutput
+        attr_reader :writes
+
+        def initialize
+          @writes = []
+        end
+
+        def write(value)
+          @writes << value
+          value.bytesize
+        end
+
+        def flush = self
+
+        def close = self
+      end
+
+      class << self
+        def configure_capture_destination(runtime = Julewire, **)
+          destination = CaptureDestination.new(**)
+          runtime.configure do |config|
+            config.destinations.clear
+            config.destinations.add(destination)
+          end
+          destination
+        end
+
+        def capture(runtime = Julewire, **)
+          records = configure_capture_destination(runtime, **).records
+          yield records if block_given?
+          records
+        end
+
+        def unregister_destination(kind)
+          Core::Destinations.__send__(:unregister, kind)
+        end
+
+        def reset_shared_scheduler
+          Core::Scheduling::SharedScheduler.__send__(:reset_for_test!)
+        end
+
+        def with_overridden_singleton_method(receiver, method_name, replacement)
+          singleton_class = class << receiver; self; end
+          method_exists =
+            singleton_class.method_defined?(method_name) || singleton_class.private_method_defined?(method_name)
+          original = singleton_class.instance_method(method_name) if method_exists
+          verbose = $VERBOSE
+          $VERBOSE = nil
+          singleton_class.define_method(method_name, replacement)
+          yield
+        ensure
+          $VERBOSE = nil
+          if original
+            singleton_class.define_method(method_name, original)
+          elsif singleton_class&.method_defined?(method_name) || singleton_class&.private_method_defined?(method_name)
+            singleton_class.remove_method(method_name)
+          end
+          $VERBOSE = verbose
+        end
+
+        def nonblocking_queue_values(queue)
+          values = []
+          loop do
+            values << queue.pop(true)
+          rescue ThreadError
+            return values
+          end
+        end
+      end
+    end
+  end
+
+  Testing = Core::Testing unless const_defined?(:Testing, false)
+end
+
+require_relative "testing/chaos"
+require_relative "testing/chaos/catalog"
+require_relative "testing/chaos/core_runtime"
+require_relative "testing/chaos/destination"
+require_relative "testing/chaos/emitter"
+require_relative "testing/chaos/raising_output"
+require_relative "testing/contracts"

data/lib/julewire/core/validation.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    # @api integration_spi
+    module Validation
+      class << self
+        def validate_byte_limit!(value, name:)
+          return if value.nil?
+
+          validate_integer_limit!(value, name: name, positive: true)
+        rescue ArgumentError
+          raise ArgumentError, "#{name} must be nil or a positive Integer"
+        end
+
+        def validate_non_negative_integer!(value, name:)
+          validate_integer_limit!(value, name: name)
+        end
+
+        def validate_integer_limit!(value, name:, positive: false)
+          return value if value.is_a?(Integer) && valid_integer_limit?(value, positive: positive)
+
+          qualifier = positive ? "positive" : "non-negative"
+          raise ArgumentError, "#{name} must be a #{qualifier} Integer"
+        end
+
+        def validate_callable!(value, name:, allow_nil: false)
+          return if allow_nil && value.nil?
+          return if value.respond_to?(:call)
+
+          raise ArgumentError, "#{name} must respond to #call"
+        end
+
+        def validate_options!(options, allowed_keys, name:)
+          unknown_options = options.keys - allowed_keys
+          return if unknown_options.empty?
+
+          raise ArgumentError, "unknown #{name} options: #{unknown_options.join(", ")}"
+        end
+
+        def validate_symbol_choice!(value, name:, choices:)
+          choice = value.to_sym if value.respond_to?(:to_sym)
+          return choice if choices.include?(choice)
+
+          raise ArgumentError, "#{name} must be one of: #{choices.join(", ")}"
+        end
+
+        def validate_timeout!(timeout, name:)
+          return if timeout.nil?
+          return if valid_numeric_timeout?(timeout)
+
+          raise ArgumentError, "#{name} must be nil or a non-negative finite Numeric"
+        end
+
+        def valid_numeric_timeout?(timeout)
+          timeout.is_a?(Numeric) && timeout.finite? && timeout >= 0
+        rescue StandardError
+          false
+        end
+
+        def valid_integer_limit?(value, positive:)
+          positive ? value.positive? : value >= 0
+        end
+
+        private :valid_integer_limit?, :valid_numeric_timeout?
+      end
+    end
+  end
+end

data/lib/julewire/core/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Julewire
+  module Core
+    VERSION = "1.0.0"
+  end
+end

data/lib/julewire/core.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+module Julewire
+  # Each gem extends the shared Julewire namespace.
+  loader = Zeitwerk::Loader.for_gem_extension(self)
+  loader.inflector.inflect("cli" => "CLI")
+  loader.ignore("#{__dir__}/core/testing.rb", "#{__dir__}/core/testing")
+  loader.setup
+
+  module Core
+    DEFAULT_MAX_RECORD_BYTES = 1_048_576
+    MAX_BACKTRACE_LINES = 20
+    NORMALIZATION_MAX_DEPTH = 128
+    CIRCULAR_REFERENCE = "[Circular]"
+
+    class << self
+      def sentinel(name) = Sentinel.new(name)
+
+      def normalize_name(value, name: :name)
+        case value
+        when String
+          raise ArgumentError, "#{name} must not be empty" if value.empty?
+
+          value.to_sym
+        when Symbol
+          raise ArgumentError, "#{name} must not be empty" if value.name.empty?
+
+          value
+        else
+          raise ArgumentError, "#{name} must be a String or Symbol"
+        end
+      end
+
+      def deep_compact_empty(value)
+        Serialization::DeepCompactEmpty.call(value)
+      end
+
+      def emit_input(input, fields)
+        return fields if input.equal?(UNSET)
+        return input if fields.empty?
+        return input.merge(fields) if input.is_a?(Hash)
+
+        { message: input.to_s }.merge(fields)
+      end
+    end
+
+    UNSET = sentinel(:unset)
+    MISSING = sentinel(:missing)
+    private_constant :MISSING
+  end
+
+  extend Core::FacadeMethods
+
+  Core::RuntimeLocator.current = Core::Runtime.new
+  Core.singleton_class.class_eval do
+    define_method(:loader) { loader }
+    private :loader
+  end
+
+  ConsoleFormatter = Core::Records::ConsoleFormatter
+  JsonEncoder = Core::Serialization::JsonEncoder
+  Match = Core::Processing::Match
+  Record = Core::Records::Record
+  RecordDraft = Core::Records::Draft
+  RecordFormatter = Core::Records::Formatter
+  Sampling = Core::Processing::Sampling
+  Serializer = Core::Serialization::Serializer
+  Tail = Core::Diagnostics::Tail
+  TailSampling = Core::Destinations::TailSampling
+  TextEncoder = Core::Serialization::TextEncoder
+
+  Core::Processing.register(:sampling) do |rate:, key: nil|
+    Core::Processing::Sampling.head(rate: rate, key: key)
+  end
+  Core::Destinations.register(:tail_sampling) do |name:, **options|
+    Core::Destinations::TailSampling.new(name: name, **options)
+  end
+end

data/lib/julewire/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Julewire
+  class Error < StandardError; end
+end

data/lib/julewire-core.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "julewire/core"