fiber_audit 0.1.0 → 0.2.1

data/lib/fiber_audit/runtime/supervisor.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module FiberAudit
+  module Runtime
+    class Supervisor
+      SIGNALS = %w[INT TERM HUP QUIT].select { |name| Signal.list.key?(name) }.freeze
+
+      class SystemAdapter
+        def spawn(environment, command, cwd)
+          executable = command.fetch(0)
+          Process.spawn(
+            environment,
+            [executable, executable],
+            *command.drop(1),
+            chdir: cwd,
+            pgroup: true
+          )
+        end
+
+        def wait2(pid)
+          Process.wait2(pid)
+        end
+
+        def trap(signal, handler = nil, &)
+          Signal.trap(signal, handler, &)
+        end
+
+        def kill(signal, pid)
+          Process.kill(signal, pid)
+        end
+      end
+
+      def initialize(command:, environment:, cwd:, adapter: SystemAdapter.new)
+        validate_command!(command)
+        raise RuntimeContractError, 'child environment must be a Hash' unless environment.is_a?(Hash)
+        raise RuntimeContractError, 'runtime cwd must be an existing directory' unless File.directory?(cwd)
+
+        @command = command.map { |argument| argument.dup.freeze }.freeze
+        @environment = environment.transform_values { |value| value&.dup&.freeze }.freeze
+        @cwd = File.expand_path(cwd).freeze
+        @adapter = adapter
+        @child_pid = nil
+      end
+
+      def run
+        handlers = {}
+        begin
+          # Install traps only after spawn so POSIX-spawned children cannot inherit
+          # FiberAudit's forwarding handlers and accidentally ignore termination.
+          @child_pid = @adapter.spawn(@environment, @command, @cwd)
+          install_handlers(handlers)
+          _pid, status = wait_for_child
+          status_code(status)
+        ensure
+          restore_handlers(handlers)
+          @child_pid = nil
+        end
+      end
+
+      private
+
+      def validate_command!(command)
+        unless command.is_a?(Array) && !command.empty? && command.all?(String)
+          raise RuntimeContractError, 'runtime command must be a nonempty Array of Strings'
+        end
+
+        command.each_with_index do |argument, index|
+          next if argument.valid_encoding? && !argument.include?("\0") && (index.positive? || !argument.empty?)
+
+          raise RuntimeContractError, 'runtime command contains an invalid argument'
+        end
+      end
+
+      def install_handlers(handlers)
+        SIGNALS.each do |signal|
+          handlers[signal] = @adapter.trap(signal) { receive_signal(signal) }
+        end
+      end
+
+      def restore_handlers(handlers)
+        handlers.each { |signal, previous| @adapter.trap(signal, previous) }
+      end
+
+      def receive_signal(signal)
+        forward_signal(signal) if @child_pid
+      end
+
+      def forward_signal(signal)
+        @adapter.kill(signal, -@child_pid)
+      rescue Errno::ESRCH, Errno::EINVAL, NotImplementedError
+        begin
+          @adapter.kill(signal, @child_pid)
+        rescue Errno::ESRCH, Errno::EINVAL, NotImplementedError
+          nil
+        end
+      end
+
+      def wait_for_child
+        @adapter.wait2(@child_pid)
+      rescue Errno::EINTR
+        retry
+      end
+
+      def status_code(status)
+        return status.exitstatus if status.exited?
+        return 128 + status.termsig if status.signaled?
+
+        raise RuntimeSafetyError, 'wrapped command ended without an exit status'
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/validation.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module FiberAudit
+  module Runtime
+    module Validation
+      IDENTIFIER = /\A[a-z][a-z0-9_]*\z/
+      UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/
+      CONTROL = /[[:cntrl:]]/
+      OPERATION = /\A(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*(?:[.#](?:[a-zA-Z_][a-zA-Z0-9_]*[!?=]?|\[\]=?))\z/
+      SPECIAL_OPERATIONS = %w[Thread.current.[] Thread.current.[]=].freeze
+
+      module_function
+
+      def identifier(value, field, max_bytes: 64)
+        normalized = value.is_a?(String) || value.is_a?(Symbol) ? value.to_s : nil
+        unless normalized&.match?(IDENTIFIER) && normalized.bytesize <= max_bytes
+          raise RuntimeContractError, "#{field} must be a snake-case identifier"
+        end
+
+        normalized.to_sym
+      end
+
+      def string(value, field, max_bytes:, allow_nil: false)
+        return if value.nil? && allow_nil
+        unless value.is_a?(String) && value.valid_encoding? && !value.empty? &&
+               value.bytesize <= max_bytes && !value.match?(CONTROL)
+          raise RuntimeContractError, "#{field} must be a non-empty UTF-8 String without control characters"
+        end
+
+        value.dup.freeze
+      end
+
+      def operation(value, allow_nil: false)
+        return if value.nil? && allow_nil
+
+        normalized = string(value, 'operation', max_bytes: 256)
+        unless normalized == '[redacted]' || SPECIAL_OPERATIONS.include?(normalized) || normalized.match?(OPERATION)
+          raise RuntimeContractError, 'operation must be canonical or redacted'
+        end
+
+        normalized
+      end
+
+      def integer(value, field, minimum: 0, allow_nil: false)
+        return if value.nil? && allow_nil
+        unless value.is_a?(Integer) && value >= minimum
+          raise RuntimeContractError, "#{field} must be an Integer >= #{minimum}"
+        end
+
+        value
+      end
+
+      def finite_number(value, field)
+        raise RuntimeContractError, "#{field} must be a finite number" unless value.is_a?(Numeric) && value.finite?
+
+        value
+      end
+
+      def utc_time(value, field)
+        raise RuntimeContractError, "#{field} must be a Time" unless value.is_a?(Time)
+
+        value.getutc.freeze
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/watchdog.rb

@@ -0,0 +1,479 @@
+# frozen_string_literal: true
+
+require_relative 'active_operations'
+require_relative 'clock'
+require_relative 'event'
+require_relative 'heartbeat'
+require_relative 'recorder'
+require_relative 'redactor'
+require_relative 'watchdog_policy'
+
+module FiberAudit
+  module Runtime
+    # Monitors scheduler-owned heartbeat fibers from one dedicated process thread.
+    # rubocop:disable Metrics/ClassLength
+    class Watchdog
+      SOURCE = :scheduler_watchdog
+      STOP_TIMEOUT_SECONDS = 1
+
+      Stall = Data.define(:sequence, :progress_sequence, :began_monotonic_ns)
+      Channel = Struct.new(:thread, :heartbeat, :active, :unsupported, :stall, keyword_init: true)
+
+      attr_reader :policy, :recorder, :active_operations
+
+      def initialize(
+        policy:,
+        recorder:,
+        redactor:,
+        active_operations:,
+        clock: Clock.new,
+        thread_factory: ->(&block) { Thread.new(&block) }
+      )
+        validate_dependencies!(policy, recorder, redactor, active_operations, clock, thread_factory)
+        @policy = policy
+        @recorder = recorder
+        @redactor = redactor
+        @active_operations = active_operations
+        @clock = clock
+        @thread_factory = thread_factory
+        @mutex = Mutex.new
+        @wait_mutex = Mutex.new
+        @condition = ConditionVariable.new
+        @channels = {}.compare_by_identity
+        @stall_sequence = 0
+        @unsupported_seen = false
+        @monitor_thread = nil
+        @stopping = false
+        @stopped = false
+        emit_state(policy.enabled? ? :watchdog_absent : :watchdog_disabled)
+      end
+
+      def enabled?
+        policy.enabled?
+      end
+
+      def fail_open?
+        recorder.session.policy.fail_open?
+      end
+
+      def state
+        return :disabled unless enabled?
+
+        @mutex.synchronize do
+          return :active if @channels.values.any?(&:active)
+          return :unsupported if @unsupported_seen || @channels.values.any?(&:unsupported)
+
+          :absent
+        end
+      end
+
+      def scheduler_installed(
+        thread: Thread.current,
+        schedule: Fiber.method(:schedule),
+        sleeper: Kernel.method(:sleep)
+      )
+        return self unless enabled?
+        raise RuntimeContractError, 'scheduler thread must be a Thread' unless thread.is_a?(Thread)
+
+        heartbeat = Heartbeat.new(
+          clock: @clock,
+          interval_ns: policy.heartbeat_interval_ns,
+          owner_thread: thread,
+          on_tick: method(:heartbeat_ticked),
+          on_error: method(:heartbeat_failed)
+        )
+        previous = @mutex.synchronize do
+          prior = @channels[thread]
+          @channels[thread] = Channel.new(
+            thread: thread,
+            heartbeat: heartbeat,
+            active: false,
+            unsupported: false,
+            stall: nil
+          )
+          prior
+        end
+        previous&.heartbeat&.request_stop
+        heartbeat.start(schedule: schedule, sleeper: sleeper)
+        self
+      rescue StandardError => e
+        channel_failure(thread, e)
+        raise e unless fail_open?
+
+        self
+      end
+
+      def scheduler_unsupported(thread: Thread.current)
+        return self unless enabled?
+
+        channel_failure(thread, nil)
+        self
+      end
+
+      def scheduler_closing(thread: Thread.current)
+        return self unless enabled?
+
+        now_ns = safe_monotonic_ns
+        @mutex.synchronize do
+          channel = @channels.delete(thread)
+          next unless channel
+
+          channel.heartbeat.request_stop
+          complete_stall(channel, now_ns: now_ns, resumed: false) if channel.stall
+          unless channel.active || channel.unsupported
+            @unsupported_seen = true
+            emit_state(:watchdog_unsupported, thread: thread)
+          end
+        end
+        wake_monitor
+        self
+      rescue StandardError => e
+        handle_failure(e)
+        raise e unless fail_open?
+
+        self
+      end
+
+      def poll(now_ns: nil)
+        return state unless enabled?
+
+        observed_now = now_ns.nil? ? @clock.monotonic_ns : Validation.integer(now_ns, 'watchdog poll time')
+        @mutex.synchronize do
+          @channels.each_value { |channel| poll_channel(channel, observed_now) if channel.active }
+        end
+        state
+      rescue StandardError => e
+        handle_failure(e)
+        raise e unless fail_open?
+
+        :unsupported
+      end
+
+      def stop
+        return self if @stopped
+
+        @wait_mutex.synchronize do
+          @stopping = true
+          @condition.broadcast
+        end
+        now_ns = safe_monotonic_ns
+        @mutex.synchronize do
+          @channels.each_value do |channel|
+            channel.heartbeat.request_stop
+            complete_stall(channel, now_ns: now_ns, resumed: false) if channel.stall
+            if !channel.active && !channel.unsupported
+              @unsupported_seen = true
+              emit_state(:watchdog_unsupported, thread: channel.thread)
+            end
+          end
+          @channels.clear
+        end
+        stop_monitor_thread
+        @stopped = true
+        self
+      rescue StandardError => e
+        handle_failure(e)
+        @stopped = true
+        raise e unless fail_open?
+
+        self
+      end
+
+      private
+
+      def validate_dependencies!(watchdog_policy, candidate_recorder, redactor, operations, clock, threads)
+        unless watchdog_policy.is_a?(WatchdogPolicy)
+          raise RuntimeContractError, 'policy must be a FiberAudit::Runtime::WatchdogPolicy'
+        end
+        unless candidate_recorder.is_a?(Recorder)
+          raise RuntimeContractError, 'recorder must be a FiberAudit::Runtime::Recorder'
+        end
+        raise RuntimeContractError, 'redactor must be a FiberAudit::Runtime::Redactor' unless redactor.is_a?(Redactor)
+        unless operations.is_a?(ActiveOperations)
+          raise RuntimeContractError, 'active_operations must be FiberAudit::Runtime::ActiveOperations'
+        end
+        raise RuntimeContractError, 'clock must be a FiberAudit::Runtime::Clock' unless clock.is_a?(Clock)
+        raise RuntimeContractError, 'thread_factory must respond to call' unless threads.respond_to?(:call)
+      end
+
+      def heartbeat_ticked(heartbeat)
+        activate = false
+        @mutex.synchronize do
+          channel = @channels[heartbeat.owner_thread]
+          return unless channel&.heartbeat.equal?(heartbeat)
+
+          unless channel.active
+            channel.active = true
+            activate = true
+          end
+        end
+        if activate
+          snapshot = heartbeat.snapshot
+          emit_state(
+            :watchdog_active,
+            thread: heartbeat.owner_thread,
+            fiber_id: snapshot.fiber_id,
+            measurements: policy_measurements
+          )
+          start_monitor_thread
+        end
+        wake_monitor
+      rescue StandardError => e
+        heartbeat_failed(heartbeat, e)
+      end
+
+      def heartbeat_failed(heartbeat, error)
+        channel_failure(heartbeat.owner_thread, error)
+        raise error unless fail_open?
+      end
+
+      def channel_failure(thread, error)
+        already_unsupported = false
+        @mutex.synchronize do
+          entry = @channels[thread]
+          if entry
+            already_unsupported = entry.unsupported
+            entry.heartbeat.request_stop
+            entry.unsupported = true
+            entry.active = false
+          else
+            already_unsupported = @unsupported_seen
+          end
+          @unsupported_seen = true
+        end
+        account_internal_error if error
+        emit_state(:watchdog_unsupported, thread: thread) unless already_unsupported
+      end
+
+      def poll_channel(channel, now_ns)
+        snapshot = channel.heartbeat.snapshot
+        return unless snapshot.started && snapshot.last_progress_ns
+        raise RuntimeSafetyError, 'watchdog monotonic clock moved backwards' if now_ns < snapshot.last_progress_ns
+
+        if channel.stall
+          complete_stall(channel, now_ns: now_ns, resumed: true) if snapshot.sequence > channel.stall.progress_sequence
+          return
+        end
+
+        age_ns = now_ns - snapshot.last_progress_ns
+        start_stall(channel, snapshot, age_ns, now_ns) if policy.stalled?(age_ns: age_ns)
+      end
+
+      def start_stall(channel, snapshot, age_ns, now_ns)
+        @stall_sequence += 1
+        channel.stall = Stall.new(
+          sequence: @stall_sequence,
+          progress_sequence: snapshot.sequence,
+          began_monotonic_ns: snapshot.last_progress_ns
+        )
+        operations = active_operations.snapshot(thread_id: snapshot.thread_id)
+        frames = safe_frames(channel.thread)
+        measurements = {
+          stall_sequence: @stall_sequence,
+          progress_sequence: snapshot.sequence,
+          observed_age_ns: age_ns,
+          stall_threshold_ns: policy.stall_threshold_ns,
+          heartbeat_interval_ns: policy.heartbeat_interval_ns,
+          frame_count: frames.size,
+          active_operation_count: operations.size,
+          active_operation_first_sequence: operations.first&.sequence,
+          active_operation_last_sequence: operations.last&.sequence
+        }
+        emit_event(
+          kind: :scheduler_stall_started,
+          monotonic_ns: now_ns,
+          thread_id: snapshot.thread_id,
+          fiber_id: snapshot.fiber_id,
+          measurements: measurements
+        )
+        frames.each_with_index do |location, index|
+          emit_event(
+            kind: :scheduler_stall_frame,
+            monotonic_ns: now_ns,
+            location: location,
+            thread_id: snapshot.thread_id,
+            fiber_id: snapshot.fiber_id,
+            measurements: { stall_sequence: @stall_sequence, frame_index: index }
+          )
+        end
+      end
+
+      def complete_stall(channel, now_ns:, resumed:)
+        stall = channel.stall
+        return unless stall
+
+        snapshot = channel.heartbeat.snapshot
+        duration = [now_ns - stall.began_monotonic_ns, 0].max
+        emit_event(
+          kind: :scheduler_stall_completed,
+          monotonic_ns: now_ns,
+          duration_ns: duration,
+          thread_id: snapshot.thread_id,
+          fiber_id: snapshot.fiber_id,
+          measurements: {
+            stall_sequence: stall.sequence,
+            progress_sequence: snapshot.sequence,
+            resumed: resumed
+          }
+        )
+        channel.stall = nil
+      end
+
+      def safe_frames(thread)
+        return [] if policy.max_frames.zero?
+
+        frames = thread.backtrace_locations(0, policy.max_frames) || []
+        frames.first(policy.max_frames).filter_map do |frame|
+          location = safe_frame_location(frame)
+          location unless location.nil? || Location::SENTINELS.include?(location.path)
+        rescue StandardError
+          nil
+        end.freeze
+      rescue StandardError => e
+        account_internal_error
+        raise e unless fail_open?
+
+        [].freeze
+      end
+
+      def safe_frame_location(frame)
+        path = frame.absolute_path
+        unless path
+          relative = frame.path
+          return unless relative.is_a?(String) && !relative.start_with?('-', '<')
+
+          path = File.join(@redactor.root, relative)
+        end
+        @redactor.location(path: path, line: frame.lineno, column: nil)
+      end
+
+      def emit_state(kind, thread: nil, fiber_id: nil, measurements: {})
+        state_measurements = measurements.empty? ? policy_measurements : measurements
+        emit_event(
+          kind: kind,
+          monotonic_ns: @clock.monotonic_ns,
+          thread_id: thread&.object_id,
+          fiber_id: fiber_id,
+          measurements: state_measurements
+        )
+      end
+
+      def emit_event(kind:, monotonic_ns:, duration_ns: nil, location: nil, thread_id: nil, fiber_id: nil, measurements: {})
+        recorder.record_control do
+          Event.new(
+            kind: kind,
+            source: SOURCE,
+            occurred_at: @clock.wall_time,
+            monotonic_ns: monotonic_ns,
+            duration_ns: duration_ns,
+            location: location,
+            execution_context: :unknown,
+            thread_id: thread_id,
+            fiber_id: fiber_id,
+            measurements: measurements
+          )
+        end
+      rescue StandardError => e
+        account_internal_error unless recorder.disabled?
+        raise e unless fail_open?
+
+        :internal_error
+      end
+
+      def policy_measurements
+        {
+          heartbeat_interval_ns: policy.heartbeat_interval_ns,
+          stall_threshold_ns: policy.stall_threshold_ns,
+          max_frames: policy.max_frames
+        }
+      end
+
+      def start_monitor_thread
+        @wait_mutex.synchronize do
+          return if @monitor_thread || @stopping
+
+          @monitor_thread = @thread_factory.call { monitor_loop }
+          raise RuntimeContractError, 'thread_factory must return a Thread' unless @monitor_thread.is_a?(Thread)
+
+          @monitor_thread.report_on_exception = false
+          @monitor_thread.abort_on_exception = !fail_open?
+          @monitor_thread.name = 'fiber-audit-watchdog' if @monitor_thread.respond_to?(:name=)
+        end
+      end
+
+      def monitor_loop
+        loop do
+          should_stop = @wait_mutex.synchronize do
+            @condition.wait(@wait_mutex, policy.heartbeat_interval_ms.fdiv(1_000)) unless @stopping
+            @stopping
+          end
+          break if should_stop
+
+          poll
+        end
+      rescue StandardError => e
+        handle_failure(e)
+        raise e unless fail_open?
+      end
+
+      def wake_monitor
+        @wait_mutex.synchronize { @condition.broadcast }
+      end
+
+      def stop_monitor_thread
+        thread = @monitor_thread
+        return unless thread && thread != Thread.current
+
+        return if thread.join(STOP_TIMEOUT_SECONDS)
+
+        account_internal_error
+        thread.kill
+        thread.join
+      ensure
+        @monitor_thread = nil
+      end
+
+      def handle_failure(error)
+        first_failure = false
+        failed_thread = nil
+        unless @mutex.owned?
+          @mutex.synchronize do
+            first_failure = !@unsupported_seen
+            @unsupported_seen = true
+            @channels.each_value do |channel|
+              failed_thread ||= channel.thread
+              channel.heartbeat.request_stop
+              channel.active = false
+              channel.unsupported = true
+            end
+          end
+        end
+        if first_failure
+          account_internal_error
+          begin
+            emit_state(:watchdog_unsupported, thread: failed_thread)
+          rescue StandardError
+            nil
+          end
+        end
+        error
+      end
+
+      def account_internal_error
+        recorder.internal_error!
+      rescue StandardError
+        nil
+      end
+
+      def safe_monotonic_ns
+        @clock.monotonic_ns
+      rescue StandardError => e
+        account_internal_error
+        raise e unless fail_open?
+
+        recorder.session.started_monotonic_ns
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end