fiber_audit 0.1.0 → 0.2.0

data/lib/fiber_audit/runtime/policy.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    Policy = Data.define(
+      :redaction,
+      :sampling_rate,
+      :max_events_per_second,
+      :max_events_per_session,
+      :max_record_bytes,
+      :max_session_bytes,
+      :fail_open
+    ) do
+      def initialize(**values)
+        unknown = values.keys - Policy::DEFAULTS.keys
+        raise RuntimeContractError, "unknown runtime policy field: #{unknown.first}" unless unknown.empty?
+
+        fields = Policy::DEFAULTS.merge(values)
+        redaction = normalize_redaction(fields[:redaction])
+        sampling_rate = normalize_sampling_rate(fields[:sampling_rate])
+        limits = Policy::LIMITS.to_h do |name, range|
+          [name, normalize_limit(fields[name], name, range)]
+        end
+        unless limits[:max_session_bytes] >= limits[:max_record_bytes]
+          raise RuntimeContractError, 'max_session_bytes must be >= max_record_bytes'
+        end
+        raise RuntimeContractError, 'fail_open must be a Boolean' unless [true, false].include?(fields[:fail_open])
+
+        super(
+          redaction: redaction,
+          sampling_rate: sampling_rate,
+          **limits,
+          fail_open: fields[:fail_open]
+        )
+      end
+
+      def sample?(draw:)
+        value = Validation.finite_number(draw, 'draw').to_f
+        raise RuntimeContractError, 'draw must be in 0.0...1.0' unless value >= 0.0 && value < 1.0
+
+        value < sampling_rate
+      end
+
+      def rate_allowed?(emitted_in_window:)
+        count_below_limit?(emitted_in_window, max_events_per_second, 'emitted_in_window')
+      end
+
+      def session_event_allowed?(emitted_events:)
+        count_below_limit?(emitted_events, max_events_per_session, 'emitted_events')
+      end
+
+      def record_size_allowed?(bytes:)
+        size_allowed?(bytes, max_record_bytes, 'bytes')
+      end
+
+      def session_bytes_allowed?(written_bytes:, next_record_bytes:)
+        written = Validation.integer(written_bytes, 'written_bytes')
+        following = Validation.integer(next_record_bytes, 'next_record_bytes')
+        written + following <= max_session_bytes
+      end
+
+      def fail_open?
+        fail_open
+      end
+
+      def strict_redaction?
+        redaction == :strict
+      end
+
+      private
+
+      def normalize_redaction(value)
+        normalized = value.is_a?(String) || value.is_a?(Symbol) ? value.to_sym : nil
+        return :strict if normalized == :strict
+
+        raise RuntimeContractError, 'redaction must be strict'
+      end
+
+      def normalize_sampling_rate(value)
+        rate = Validation.finite_number(value, 'sampling_rate').to_f
+        return rate if rate.between?(0.0, 1.0)
+
+        raise RuntimeContractError, 'sampling_rate must be between 0.0 and 1.0'
+      end
+
+      def normalize_limit(value, field, range)
+        unless value.is_a?(Integer) && range.cover?(value)
+          raise RuntimeContractError, "#{field} must be an Integer in #{range}"
+        end
+
+        value
+      end
+
+      def count_below_limit?(value, limit, field)
+        Validation.integer(value, field) < limit
+      end
+
+      def size_allowed?(value, limit, field)
+        Validation.integer(value, field) <= limit
+      end
+    end
+
+    Policy.const_set(:DEFAULTS, {
+      redaction: :strict,
+      sampling_rate: 0.1,
+      max_events_per_second: 100,
+      max_events_per_session: 10_000,
+      max_record_bytes: 16_384,
+      max_session_bytes: 10_485_760,
+      fail_open: true
+    }.freeze)
+    Policy.const_set(:LIMITS, {
+      max_events_per_second: 1..10_000,
+      max_events_per_session: 1..1_000_000,
+      max_record_bytes: 1_024..1_048_576,
+      max_session_bytes: 4_096..1_073_741_824
+    }.freeze)
+  end
+end

data/lib/fiber_audit/runtime/probes/base.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require_relative '../active_operations'
+require_relative '../clock'
+require_relative '../event'
+require_relative '../execution_context'
+require_relative '../rails_integration'
+require_relative '../recorder'
+require_relative '../redactor'
+
+module FiberAudit
+  module Runtime
+    module Probes
+      # Shared behavior-preserving observation boundary for targeted wrappers.
+      # rubocop:disable Metrics/ClassLength
+      class Base
+        SOURCE = :targeted_probe
+        MAX_CALLSITE_FRAMES = 32
+        INTERNAL_PATH = File.expand_path('../..', __dir__).freeze
+        ORIGINAL_MUTEX_SYNCHRONIZE = Mutex.instance_method(:synchronize)
+
+        Observation = Data.define(
+          :operation,
+          :started_monotonic_ns,
+          :location,
+          :handle,
+          :thread_id,
+          :fiber_id,
+          :measurements,
+          :execution_context
+        )
+
+        attr_reader :recorder, :clock, :redactor, :active_operations, :owner_pid, :execution_context_store
+
+        def initialize(recorder:, clock:, redactor:, active_operations:, execution_context_store: nil,
+                       pid_source: Process.method(:pid))
+          validate_dependencies!(recorder, clock, redactor, active_operations, execution_context_store, pid_source)
+          @recorder = recorder
+          @clock = clock
+          @redactor = redactor
+          @active_operations = active_operations
+          @execution_context_store = execution_context_store
+          @pid_source = pid_source
+          @owner_pid = current_pid
+          @active = true
+        end
+
+        def observe(operation:, measurements: {}, emit_start: false, measurement_builder: nil)
+          return yield unless active_for_current_process?
+          return yield if guarded?
+
+          observation = begin
+            prepare_observation(operation, measurements)
+          rescue StandardError => e
+            instrumentation_failure(e)
+          end
+          return yield unless observation
+
+          with_guard { emit_start_observation(observation) } if emit_start
+          completed = false
+          result = nil
+          begin
+            result = yield
+            completed = true
+            result
+          ensure
+            finalize_observation(observation, completed: completed, result: result, measurement_builder: measurement_builder)
+          end
+        end
+
+        def with_guard
+          self.class.enter_guard
+          yield
+        ensure
+          self.class.exit_guard
+        end
+
+        def deactivate
+          @active = false
+          self
+        end
+
+        def active_for_current_process?
+          @active && owner_pid == current_pid
+        rescue StandardError
+          false
+        end
+
+        def fail_open?
+          recorder.session.policy.fail_open?
+        end
+
+        def instrumentation_failure(error)
+          account_internal_error
+          raise error unless fail_open?
+
+          nil
+        end
+
+        private
+
+        def validate_dependencies!(candidate_recorder, candidate_clock, candidate_redactor, operations, context_store, pids)
+          raise RuntimeContractError, 'recorder must be a Runtime::Recorder' unless candidate_recorder.is_a?(Recorder)
+          raise RuntimeContractError, 'clock must be a Runtime::Clock' unless candidate_clock.is_a?(Clock)
+          raise RuntimeContractError, 'redactor must be a Runtime::Redactor' unless candidate_redactor.is_a?(Redactor)
+          unless operations.is_a?(ActiveOperations)
+            raise RuntimeContractError, 'active_operations must be Runtime::ActiveOperations'
+          end
+          if context_store && !context_store.respond_to?(:current)
+            raise RuntimeContractError, 'execution_context_store must respond to current'
+          end
+          raise RuntimeContractError, 'pid_source must respond to call' unless pids.respond_to?(:call)
+        end
+
+        def prepare_observation(operation, measurements)
+          # The block keeps all preparation under one recursion guard.
+          # rubocop:disable Metrics/BlockLength
+          with_guard do
+            canonical_operation = Validation.operation(operation)
+            normalized_measurements = normalize_measurements(measurements)
+            started_ns = clock.monotonic_ns
+            location = project_callsite
+            next unless location
+
+            thread = Thread.current
+            fiber = Fiber.current
+            captured_context = capture_execution_context
+            handle = active_operations.register(
+              operation: canonical_operation,
+              monotonic_ns: started_ns,
+              location: location,
+              execution_context: captured_context,
+              thread: thread,
+              fiber: fiber
+            )
+            Observation.new(
+              operation: canonical_operation,
+              started_monotonic_ns: started_ns,
+              location: location,
+              handle: handle,
+              thread_id: thread.object_id,
+              fiber_id: fiber.object_id,
+              measurements: normalized_measurements,
+              execution_context: captured_context
+            )
+          end
+          # rubocop:enable Metrics/BlockLength
+        end
+
+        def capture_execution_context
+          return Context::UNKNOWN unless execution_context_store
+
+          execution_context_store.current
+        rescue StandardError
+          Context::UNKNOWN
+        end
+
+        def emit_start_observation(observation)
+          emit_observation(:operation_started, observation, monotonic_ns: observation.started_monotonic_ns)
+        rescue StandardError => e
+          with_guard { active_operations.finish(observation.handle) } if observation.handle && !fail_open?
+          instrumentation_failure(e)
+        end
+
+        def finalize_observation(observation, completed:, result:, measurement_builder:)
+          error = nil
+          begin
+            if active_for_current_process?
+              with_guard do
+                ended_ns = clock.monotonic_ns
+                if ended_ns < observation.started_monotonic_ns
+                  raise RuntimeSafetyError, 'probe monotonic clock moved backwards'
+                end
+
+                measurements = completed_measurements(observation, completed, result, measurement_builder)
+                emit_observation(
+                  completed ? :operation_completed : :operation_aborted,
+                  observation,
+                  monotonic_ns: ended_ns,
+                  duration_ns: ended_ns - observation.started_monotonic_ns,
+                  measurements: measurements
+                )
+              end
+            end
+          rescue StandardError => e
+            error = e
+          ensure
+            begin
+              with_guard { active_operations.finish(observation.handle) } if observation.handle
+            rescue StandardError => e
+              error ||= e
+            end
+          end
+
+          return unless error
+
+          account_internal_error
+          raise error if completed && !fail_open?
+        end
+
+        def completed_measurements(observation, completed, result, builder)
+          values = observation.measurements.dup
+          if completed && builder
+            generated = builder.call(result)
+            raise RuntimeContractError, 'measurement_builder must return a Hash' unless generated.is_a?(Hash)
+
+            values.merge!(generated)
+          end
+          values[:operation_sequence] = observation.handle&.sequence
+          values
+        end
+
+        def emit_observation(kind, observation, monotonic_ns:, duration_ns: nil, measurements: nil)
+          values = measurements || observation.measurements.merge(operation_sequence: observation.handle&.sequence)
+          recorder.record do
+            Event.new(
+              kind: kind,
+              source: SOURCE,
+              occurred_at: clock.wall_time,
+              monotonic_ns: monotonic_ns,
+              duration_ns: duration_ns,
+              operation: observation.operation,
+              location: observation.location,
+              execution_context: observation.execution_context,
+              thread_id: observation.thread_id,
+              fiber_id: observation.fiber_id,
+              measurements: values
+            )
+          end
+        end
+
+        def normalize_measurements(value)
+          raise RuntimeContractError, 'probe measurements must be a Hash' unless value.is_a?(Hash)
+
+          value.dup.freeze
+        end
+
+        def project_callsite
+          caller_locations(0, MAX_CALLSITE_FRAMES)&.each do |frame|
+            paths = frame_paths(frame)
+            next if paths.any? { |path| internal_path?(path) }
+
+            return paths.filter_map { |path| safe_location(frame, path) }.first
+          rescue StandardError
+            return nil
+          end
+          nil
+        end
+
+        def frame_paths(frame)
+          candidates = [frame.absolute_path, frame.path].compact.filter_map do |path|
+            next unless path.is_a?(String) && !path.start_with?('-', '<')
+
+            File.absolute_path?(path) ? File.expand_path(path) : File.expand_path(path, redactor.root)
+          end
+          candidates.uniq
+        end
+
+        def internal_path?(path)
+          path == INTERNAL_PATH || path.start_with?("#{INTERNAL_PATH}#{File::SEPARATOR}")
+        end
+
+        def safe_location(frame, path)
+          location = redactor.location(path: path, line: frame.lineno, column: nil)
+          return if Location::SENTINELS.include?(location.path)
+
+          location
+        end
+
+        class << self
+          def guarded?
+            state = guard_state
+            key = guard_key
+            ORIGINAL_MUTEX_SYNCHRONIZE.bind_call(state.fetch(:mutex)) do
+              state.fetch(:depths).fetch(key, 0).positive?
+            end
+          end
+
+          def enter_guard
+            state = guard_state
+            key = guard_key
+            ORIGINAL_MUTEX_SYNCHRONIZE.bind_call(state.fetch(:mutex)) do
+              depths = state.fetch(:depths)
+              depths[key] = depths.fetch(key, 0) + 1
+            end
+          end
+
+          def exit_guard
+            state = guard_state
+            key = guard_key
+            ORIGINAL_MUTEX_SYNCHRONIZE.bind_call(state.fetch(:mutex)) do
+              depths = state.fetch(:depths)
+              depth = depths.fetch(key, 1) - 1
+              depth.positive? ? depths[key] = depth : depths.delete(key)
+            end
+          end
+
+          private
+
+          def guard_state
+            pid = Process.pid
+            return @guard_state if @guard_pid == pid && @guard_state
+
+            @guard_pid = pid
+            @guard_state = { mutex: Mutex.new, depths: {} }
+          end
+
+          def guard_key
+            [Thread.current.object_id, Fiber.current.object_id]
+          end
+        end
+
+        def guarded?
+          self.class.guarded?
+        end
+
+        def account_internal_error
+          with_guard { recorder.internal_error! unless recorder.disabled? }
+        rescue StandardError
+          nil
+        end
+
+        def current_pid
+          value = @pid_source.call
+          return value if value.is_a?(Integer) && value.positive?
+
+          raise RuntimeContractError, 'pid_source must return a positive Integer'
+        end
+      end
+      # rubocop:enable Metrics/ClassLength
+    end
+  end
+end

data/lib/fiber_audit/runtime/probes/http.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  module Runtime
+    module Probes
+      module HTTP
+        HTTP_SCHEME = /\Ahttps?:/i
+
+        module NetHTTPClassHook
+          def get(...)
+            Registry.observe(operation: 'Net::HTTP.get') { super }
+          end
+
+          def get_response(...)
+            Registry.observe(operation: 'Net::HTTP.get_response') { super }
+          end
+
+          def start(...)
+            Registry.observe(operation: 'Net::HTTP.start') { super }
+          end
+        end
+
+        module NetHTTPClassRequestHook
+          def request(...)
+            Registry.observe(operation: 'Net::HTTP.request') { super }
+          end
+        end
+
+        module NetHTTPInstanceHook
+          def start(...)
+            Registry.observe(operation: 'Net::HTTP.start') { super }
+          end
+
+          def request(...)
+            Registry.observe(operation: 'Net::HTTP.request') { super }
+          end
+        end
+
+        module URIHook
+          def open(*arguments, **, &)
+            return super unless HTTP.http_target?(arguments.first)
+
+            Registry.observe(operation: 'URI.open') { super }
+          end
+        end
+
+        module OpenURIHook
+          def open_uri(*arguments, **, &)
+            return super unless HTTP.http_target?(arguments.first)
+
+            Registry.observe(operation: 'OpenURI.open_uri') { super }
+          end
+        end
+
+        module_function
+
+        def install!(registry)
+          if defined?(Net::HTTP)
+            registry.prepend_once(Net::HTTP.singleton_class, NetHTTPClassHook)
+            registry.prepend_once(Net::HTTP, NetHTTPInstanceHook)
+            registry.prepend_once(Net::HTTP.singleton_class, NetHTTPClassRequestHook) if Net::HTTP.respond_to?(:request)
+          end
+          registry.prepend_once(URI.singleton_class, URIHook) if defined?(URI) && URI.respond_to?(:open)
+          return unless defined?(OpenURI) && OpenURI.respond_to?(:open_uri)
+
+          registry.prepend_once(OpenURI.singleton_class, OpenURIHook)
+        end
+
+        def http_target?(value)
+          return value.match?(HTTP_SCHEME) if value.instance_of?(String) && value.valid_encoding?
+          return false unless defined?(URI::HTTP)
+
+          value.instance_of?(URI::HTTP) || (defined?(URI::HTTPS) && value.instance_of?(URI::HTTPS))
+        rescue StandardError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/probes/io_select.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  module Runtime
+    module Probes
+      module IOSelect
+        module_function
+
+        def timeout_measurement(arguments)
+          { timeout_present: arguments.length >= 4 && !arguments[3].nil? }
+        end
+
+        module IOHook
+          def select(*arguments, &)
+            Registry.observe(
+              operation: 'IO.select',
+              measurements: IOSelect.timeout_measurement(arguments)
+            ) { super }
+          end
+        end
+
+        module KernelInstanceHook
+          def select(*arguments, &)
+            Registry.observe(
+              operation: 'Kernel.select',
+              measurements: IOSelect.timeout_measurement(arguments)
+            ) { super }
+          end
+
+          private :select
+        end
+
+        module KernelSingletonHook
+          def select(*arguments, &)
+            Registry.observe(
+              operation: 'Kernel.select',
+              measurements: IOSelect.timeout_measurement(arguments)
+            ) { super }
+          end
+        end
+
+        def install!(registry)
+          registry.prepend_once(IO.singleton_class, IOHook)
+          registry.prepend_once(Kernel, KernelInstanceHook)
+          registry.prepend_once(Kernel.singleton_class, KernelSingletonHook)
+        end
+      end
+    end
+  end
+end