fiber_audit 0.1.0 → 0.2.1

data/lib/fiber_audit/runtime/environment.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+require 'pathname'
+require 'securerandom'
+require_relative 'policy'
+require_relative 'validation'
+require_relative 'watchdog_policy'
+
+module FiberAudit
+  module Runtime
+    # rubocop:disable Metrics/ModuleLength
+    module Environment
+      PROTOCOL_VERSION = 1
+      ACTIVATION_KEY = 'FIBER_AUDIT_RUNTIME_BOOT'
+      SETTINGS_KEY = 'FIBER_AUDIT_RUNTIME_SETTINGS'
+      FAILURE_MODE_KEY = 'FIBER_AUDIT_RUNTIME_FAILURE_MODE'
+      WATCHDOG_SETTINGS_KEY = 'FIBER_AUDIT_RUNTIME_WATCHDOG_SETTINGS'
+      PROBES_KEY = 'FIBER_AUDIT_RUNTIME_PROBES'
+      BOOT_REQUIRE = '-rfiber_audit/runtime/boot'
+      MAX_SETTINGS_BYTES = 16_384
+      MAX_WATCHDOG_SETTINGS_BYTES = 1_024
+      SETTINGS_KEYS = %w[protocol_version launch_id project_root output_directory policy].freeze
+      POLICY_KEYS = %w[
+        redaction sampling_rate max_events_per_second max_events_per_session
+        max_record_bytes max_session_bytes fail_open
+      ].freeze
+      WATCHDOG_KEYS = %w[
+        protocol_version enabled heartbeat_interval_ms stall_threshold_ms max_frames
+      ].freeze
+
+      Settings = Data.define(:protocol_version, :launch_id, :project_root, :output_directory, :policy) do
+        def initialize(protocol_version:, launch_id:, project_root:, output_directory:, policy:)
+          unless protocol_version == PROTOCOL_VERSION
+            raise RuntimeContractError, "runtime activation protocol must be #{PROTOCOL_VERSION}"
+          end
+          unless launch_id.is_a?(String) && launch_id.match?(Validation::UUID)
+            raise RuntimeContractError, 'runtime launch_id must be a canonical lowercase UUID'
+          end
+          unless policy.is_a?(Policy)
+            raise RuntimeContractError, 'runtime activation policy must be a FiberAudit::Runtime::Policy'
+          end
+
+          super(
+            protocol_version: protocol_version,
+            launch_id: launch_id.dup.freeze,
+            project_root: Environment.normalize_directory(project_root, 'project_root'),
+            output_directory: Environment.normalize_directory(output_directory, 'output_directory'),
+            policy: policy
+          )
+        end
+      end
+
+      module_function
+
+      def build(policy:, output_directory:, project_root:, launch_id: SecureRandom.uuid)
+        Settings.new(
+          protocol_version: PROTOCOL_VERSION,
+          launch_id: launch_id,
+          project_root: project_root,
+          output_directory: output_directory,
+          policy: policy
+        )
+      end
+
+      def dump(settings)
+        require_settings!(settings)
+        payload = {
+          'protocol_version' => settings.protocol_version,
+          'launch_id' => settings.launch_id,
+          'project_root' => settings.project_root,
+          'output_directory' => settings.output_directory,
+          'policy' => policy_payload(settings.policy)
+        }
+        encoded = JSON.generate(payload)
+        raise RuntimeSafetyError, 'runtime activation settings are too large' if encoded.bytesize > MAX_SETTINGS_BYTES
+
+        encoded.freeze
+      end
+
+      def load(environment = ENV)
+        return unless activated?(environment)
+
+        value = environment.fetch(SETTINGS_KEY) do
+          raise RuntimeContractError, "missing runtime activation variable: #{SETTINGS_KEY}"
+        end
+        unless value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_SETTINGS_BYTES
+          raise RuntimeContractError, 'runtime activation settings are invalid'
+        end
+
+        payload = JSON.parse(value)
+        require_exact_keys!(payload, SETTINGS_KEYS, 'runtime activation settings')
+        policy_values = payload.fetch('policy')
+        require_exact_keys!(policy_values, POLICY_KEYS, 'runtime activation policy')
+        settings = Settings.new(
+          protocol_version: payload.fetch('protocol_version'),
+          launch_id: payload.fetch('launch_id'),
+          project_root: payload.fetch('project_root'),
+          output_directory: payload.fetch('output_directory'),
+          policy: Policy.new(**symbolize_policy(policy_values))
+        )
+        validate_failure_mode!(environment, settings.policy)
+        settings
+      rescue JSON::ParserError, ArgumentError => e
+        raise RuntimeContractError, "invalid runtime activation settings: #{e.message}"
+      end
+
+      def dump_watchdog_policy(policy)
+        require_watchdog_policy!(policy)
+        payload = {
+          'protocol_version' => PROTOCOL_VERSION,
+          'enabled' => policy.enabled,
+          'heartbeat_interval_ms' => policy.heartbeat_interval_ms,
+          'stall_threshold_ms' => policy.stall_threshold_ms,
+          'max_frames' => policy.max_frames
+        }
+        encoded = JSON.generate(payload)
+        if encoded.bytesize > MAX_WATCHDOG_SETTINGS_BYTES
+          raise RuntimeSafetyError, 'runtime watchdog activation settings are too large'
+        end
+
+        encoded.freeze
+      end
+
+      def load_watchdog_policy(environment = ENV)
+        value = environment[WATCHDOG_SETTINGS_KEY]
+        return WatchdogPolicy::DISABLED if value.nil?
+        unless value.is_a?(String) && value.valid_encoding? && value.bytesize <= MAX_WATCHDOG_SETTINGS_BYTES
+          raise RuntimeContractError, 'runtime watchdog activation settings are invalid'
+        end
+
+        payload = JSON.parse(value)
+        require_exact_keys!(payload, WATCHDOG_KEYS, 'runtime watchdog activation settings')
+        unless payload.fetch('protocol_version') == PROTOCOL_VERSION
+          raise RuntimeContractError, "runtime watchdog activation protocol must be #{PROTOCOL_VERSION}"
+        end
+
+        WatchdogPolicy.new(
+          enabled: payload.fetch('enabled'),
+          heartbeat_interval_ms: payload.fetch('heartbeat_interval_ms'),
+          stall_threshold_ms: payload.fetch('stall_threshold_ms'),
+          max_frames: payload.fetch('max_frames')
+        )
+      rescue JSON::ParserError, ArgumentError => e
+        raise RuntimeContractError, "invalid runtime watchdog activation settings: #{e.message}"
+      end
+
+      def activated?(environment = ENV)
+        marker = environment[ACTIVATION_KEY]
+        return false if marker.nil?
+        return true if marker == '1'
+
+        raise RuntimeContractError, "#{ACTIVATION_KEY} must be 1"
+      end
+
+      def failure_mode(environment = ENV)
+        value = environment[FAILURE_MODE_KEY]
+        return :open if value.nil? || value == 'open'
+        return :closed if value == 'closed'
+
+        raise RuntimeContractError, "#{FAILURE_MODE_KEY} must be open or closed"
+      end
+
+      def probes_enabled?(environment = ENV)
+        value = environment[PROBES_KEY]
+        return false if value.nil?
+        return true if value == '1'
+
+        raise RuntimeContractError, "#{PROBES_KEY} must be 1 when present"
+      end
+
+      def child_environment(
+        settings:,
+        watchdog_policy: nil,
+        probes_enabled: false,
+        base_environment: ENV,
+        library_path: default_library_path
+      )
+        require_settings!(settings)
+        require_watchdog_policy!(watchdog_policy) if watchdog_policy
+        raise RuntimeContractError, 'probes_enabled must be a Boolean' unless [true, false].include?(probes_enabled)
+        raise RuntimeContractError, 'base_environment must be a Hash-like object' unless base_environment.respond_to?(:[])
+
+        environment = {
+          ACTIVATION_KEY => '1',
+          SETTINGS_KEY => dump(settings),
+          FAILURE_MODE_KEY => settings.policy.fail_open? ? 'open' : 'closed',
+          'RUBYOPT' => prepend_token(base_environment['RUBYOPT'], BOOT_REQUIRE, separator: ' '),
+          'RUBYLIB' => prepend_token(base_environment['RUBYLIB'], library_path, separator: File::PATH_SEPARATOR)
+        }
+        environment[WATCHDOG_SETTINGS_KEY] = dump_watchdog_policy(watchdog_policy) if watchdog_policy
+        environment[PROBES_KEY] = '1' if probes_enabled
+        environment.transform_values(&:freeze).freeze
+      end
+
+      def prepare_output_directory(path)
+        normalized = normalize_absolute_path(path, 'output directory')
+        if File.exist?(normalized)
+          raise RuntimeSafetyError, "runtime output is not a directory: #{normalized}" unless File.directory?(normalized)
+
+          return normalized
+        end
+
+        FileUtils.mkdir_p(normalized, mode: 0o700)
+        File.chmod(0o700, normalized)
+        normalized
+      rescue SystemCallError => e
+        raise RuntimeSafetyError, "cannot prepare runtime output directory: #{e.message}"
+      end
+
+      def normalize_directory(value, field)
+        normalized = normalize_absolute_path(value, field)
+        raise RuntimeContractError, "#{field} must be an existing directory" unless File.directory?(normalized)
+
+        normalized.freeze
+      end
+
+      def default_library_path
+        File.expand_path('../..', __dir__).freeze
+      end
+      private_class_method :default_library_path
+
+      def normalize_absolute_path(value, field)
+        text = Validation.string(value, field, max_bytes: 4_096)
+        path = Pathname.new(text)
+        raise RuntimeContractError, "#{field} must be absolute" unless path.absolute?
+
+        path.cleanpath.to_s.freeze
+      rescue ArgumentError
+        raise RuntimeContractError, "#{field} is invalid"
+      end
+      private_class_method :normalize_absolute_path
+
+      def prepend_token(existing, token, separator:)
+        current = existing.to_s
+        parts = current.split(separator)
+        return current.dup.freeze if parts.include?(token)
+
+        current.empty? ? token.dup.freeze : "#{token}#{separator}#{current}".freeze
+      end
+      private_class_method :prepend_token
+
+      def require_settings!(value)
+        return if value.is_a?(Settings)
+
+        raise RuntimeContractError, 'settings must be FiberAudit::Runtime::Environment::Settings'
+      end
+      private_class_method :require_settings!
+
+      def require_watchdog_policy!(value)
+        return if value.is_a?(WatchdogPolicy)
+
+        raise RuntimeContractError, 'watchdog_policy must be FiberAudit::Runtime::WatchdogPolicy'
+      end
+      private_class_method :require_watchdog_policy!
+
+      def require_exact_keys!(value, expected, path)
+        raise RuntimeContractError, "#{path} must be an object" unless value.is_a?(Hash)
+
+        unknown = value.keys - expected
+        missing = expected - value.keys
+        raise RuntimeContractError, "unknown key #{unknown.first.inspect} at #{path}" unless unknown.empty?
+        raise RuntimeContractError, "missing key #{missing.first.inspect} at #{path}" unless missing.empty?
+      end
+      private_class_method :require_exact_keys!
+
+      def policy_payload(policy)
+        policy.to_h.transform_values { |value| value.is_a?(Symbol) ? value.to_s : value }.transform_keys(&:to_s)
+      end
+      private_class_method :policy_payload
+
+      def symbolize_policy(values)
+        values.to_h { |key, value| [key.to_sym, value] }
+      end
+      private_class_method :symbolize_policy
+
+      def validate_failure_mode!(environment, policy)
+        expected = policy.fail_open? ? :open : :closed
+        actual = failure_mode(environment)
+        return if actual == expected
+
+        raise RuntimeContractError, 'runtime activation failure mode does not match policy'
+      end
+      private_class_method :validate_failure_mode!
+    end
+    # rubocop:enable Metrics/ModuleLength
+  end
+end

data/lib/fiber_audit/runtime/event.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative '../execution_context'
+require_relative 'location'
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    Event = Data.define(
+      :kind,
+      :source,
+      :occurred_at,
+      :monotonic_ns,
+      :duration_ns,
+      :operation,
+      :location,
+      :execution_context,
+      :thread_id,
+      :fiber_id,
+      :measurements
+    ) do
+      def initialize(
+        kind:,
+        source:,
+        occurred_at:,
+        monotonic_ns:,
+        duration_ns: nil,
+        operation: nil,
+        location: nil,
+        execution_context: :unknown,
+        thread_id: nil,
+        fiber_id: nil,
+        measurements: {}
+      )
+        super(
+          kind: Validation.identifier(kind, 'kind'),
+          source: Validation.identifier(source, 'source'),
+          occurred_at: Validation.utc_time(occurred_at, 'occurred_at'),
+          monotonic_ns: Validation.integer(monotonic_ns, 'monotonic_ns'),
+          duration_ns: Validation.integer(duration_ns, 'duration_ns', allow_nil: true),
+          operation: Validation.operation(operation, allow_nil: true),
+          location: normalize_location(location),
+          execution_context: normalize_context(execution_context),
+          thread_id: Validation.integer(thread_id, 'thread_id', allow_nil: true),
+          fiber_id: Validation.integer(fiber_id, 'fiber_id', allow_nil: true),
+          measurements: normalize_measurements(measurements)
+        )
+      end
+
+      private
+
+      def normalize_location(value)
+        return value if value.nil? || value.is_a?(Location)
+
+        raise RuntimeContractError, 'location must be a FiberAudit::Runtime::Location or nil'
+      end
+
+      def normalize_context(value)
+        normalized = value.is_a?(String) || value.is_a?(Symbol) ? value.to_sym : nil
+        return normalized if Context::ALL.include?(normalized)
+
+        raise RuntimeContractError, "execution_context is invalid: #{value.inspect}"
+      end
+
+      def normalize_measurements(value)
+        raise RuntimeContractError, 'measurements must be a Hash' unless value.is_a?(Hash)
+        if value.size > Event::MAX_MEASUREMENTS
+          raise RuntimeContractError, "measurements must contain at most #{Event::MAX_MEASUREMENTS} entries"
+        end
+
+        value.each_with_object({}) do |(key, measurement), normalized|
+          name = Validation.identifier(key, 'measurement key').to_s.freeze
+          raise RuntimeContractError, "duplicate normalized measurement key: #{name}" if normalized.key?(name)
+          unless measurement.nil? || measurement == true || measurement == false ||
+                 (measurement.is_a?(Numeric) && measurement.finite?)
+            raise RuntimeContractError, "measurement #{name} must be a finite number, Boolean, or nil"
+          end
+
+          normalized[name] = measurement
+        end.freeze
+      end
+    end
+
+    Event.const_set(:MAX_MEASUREMENTS, 32)
+  end
+end

data/lib/fiber_audit/runtime/execution_context.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative '../execution_context'
+
+module FiberAudit
+  module Runtime
+    # Fiber-local execution context stack.
+    # Uses fiber instance variables for isolation without Thread#[] visibility.
+    # PID-aware to handle fork correctly.
+    module ExecutionContext
+      MAX_DEPTH = 32
+      IVAR_KEY = :@__fiber_audit_execution_context__
+      IVAR_PID_KEY = :@__fiber_audit_execution_context_pid__
+
+      class << self
+        def current
+          state = current_state
+          return Context::UNKNOWN unless state
+
+          state[:stack].last || Context::UNKNOWN
+        end
+
+        def with(context)
+          normalized = validate_context(context)
+          state = ensure_state
+          return yield if state[:stack].size >= MAX_DEPTH
+
+          state[:stack].push(normalized)
+          begin
+            yield
+          ensure
+            state[:stack].pop
+          end
+        end
+
+        def reset!
+          fiber = Fiber.current
+          fiber.remove_instance_variable(IVAR_KEY) if fiber.instance_variable_defined?(IVAR_KEY)
+          fiber.remove_instance_variable(IVAR_PID_KEY) if fiber.instance_variable_defined?(IVAR_PID_KEY)
+        end
+
+        def after_fork!
+          reset!
+        end
+
+        private
+
+        def current_state
+          fiber = Fiber.current
+          return nil unless fiber.instance_variable_defined?(IVAR_KEY)
+
+          pid = fiber.instance_variable_defined?(IVAR_PID_KEY) ? fiber.instance_variable_get(IVAR_PID_KEY) : nil
+          return nil unless pid == Process.pid
+
+          { stack: fiber.instance_variable_get(IVAR_KEY), pid: pid }
+        end
+
+        def ensure_state
+          fiber = Fiber.current
+          pid = Process.pid
+
+          if fiber.instance_variable_defined?(IVAR_KEY)
+            stored_pid = fiber.instance_variable_defined?(IVAR_PID_KEY) ? fiber.instance_variable_get(IVAR_PID_KEY) : nil
+            return { stack: fiber.instance_variable_get(IVAR_KEY), pid: pid } if stored_pid == pid
+
+            # PID mismatch - reset
+            reset!
+          end
+
+          stack = []
+          fiber.instance_variable_set(IVAR_KEY, stack)
+          fiber.instance_variable_set(IVAR_PID_KEY, pid)
+          { stack: stack, pid: pid }
+        end
+
+        def validate_context(value)
+          unless value.is_a?(Symbol) || value.is_a?(String)
+            raise RuntimeContractError, 'execution_context must be a Symbol or String'
+          end
+
+          normalized = value.is_a?(Symbol) ? value : value.to_sym
+          return normalized if Context::ALL.include?(normalized)
+
+          raise RuntimeContractError, 'execution_context is invalid'
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/heartbeat.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative 'clock'
+
+module FiberAudit
+  module Runtime
+    # Scheduler-owned progress fiber observed by the watchdog thread.
+    class Heartbeat
+      Snapshot = Data.define(:sequence, :last_progress_ns, :thread_id, :fiber_id, :started, :stop_requested)
+
+      attr_reader :owner_thread
+
+      def initialize(
+        interval_ns:,
+        clock: Clock.new,
+        owner_thread: Thread.current,
+        on_tick: ->(_heartbeat) {},
+        on_error: ->(_heartbeat, _error) {}
+      )
+        raise RuntimeContractError, 'clock must be a FiberAudit::Runtime::Clock' unless clock.is_a?(Clock)
+        unless interval_ns.is_a?(Integer) && interval_ns.positive?
+          raise RuntimeContractError, 'interval_ns must be a positive Integer'
+        end
+        raise RuntimeContractError, 'owner_thread must be a Thread' unless owner_thread.is_a?(Thread)
+        raise RuntimeContractError, 'on_tick must respond to call' unless on_tick.respond_to?(:call)
+        raise RuntimeContractError, 'on_error must respond to call' unless on_error.respond_to?(:call)
+
+        @clock = clock
+        @interval_ns = interval_ns
+        @owner_thread = owner_thread
+        @on_tick = on_tick
+        @on_error = on_error
+        @mutex = Mutex.new
+        @sequence = 0
+        @last_progress_ns = nil
+        @fiber_id = nil
+        @started = false
+        @start_requested = false
+        @stop_requested = false
+      end
+
+      def start(schedule: Fiber.method(:schedule), sleeper: Kernel.method(:sleep))
+        raise RuntimeContractError, 'schedule must respond to call' unless schedule.respond_to?(:call)
+        raise RuntimeContractError, 'sleeper must respond to call' unless sleeper.respond_to?(:call)
+
+        @mutex.synchronize do
+          return self if @start_requested
+
+          @start_requested = true
+        end
+        schedule.call { run(sleeper) }
+        self
+      rescue StandardError
+        @mutex.synchronize { @start_requested = false }
+        raise
+      end
+
+      def tick
+        now_ns = @clock.monotonic_ns
+        @mutex.synchronize do
+          @sequence += 1
+          @last_progress_ns = now_ns
+          @fiber_id ||= Fiber.current.object_id
+          @started = true
+        end
+        @on_tick.call(self)
+        self
+      end
+
+      def request_stop
+        @mutex.synchronize { @stop_requested = true }
+        self
+      end
+
+      def snapshot
+        @mutex.synchronize do
+          Snapshot.new(
+            sequence: @sequence,
+            last_progress_ns: @last_progress_ns,
+            thread_id: owner_thread.object_id,
+            fiber_id: @fiber_id,
+            started: @started,
+            stop_requested: @stop_requested
+          )
+        end
+      end
+
+      def started?
+        @mutex.synchronize { @started }
+      end
+
+      def stop_requested?
+        @mutex.synchronize { @stop_requested }
+      end
+
+      private
+
+      def run(sleeper)
+        tick
+        loop do
+          break if stop_requested?
+
+          sleeper.call(@interval_ns.fdiv(1_000_000_000))
+          break if stop_requested?
+
+          tick
+        end
+      rescue StandardError => e
+        @on_error.call(self, e)
+      end
+    end
+  end
+end