fiber_audit 0.1.0 → 0.2.1

data/lib/fiber_audit/runtime/lifecycle.rb

@@ -0,0 +1,343 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+require_relative 'clock'
+require_relative 'active_operations'
+require_relative 'environment'
+require_relative 'execution_context'
+require_relative 'rails_integration'
+require_relative 'jsonl/writer'
+require_relative 'recorder'
+require_relative 'redactor'
+require_relative 'probes/registry'
+require_relative 'scheduler_observer'
+require_relative 'session'
+require_relative 'watchdog'
+require_relative 'watchdog_policy'
+
+module FiberAudit
+  module Runtime
+    # rubocop:disable Metrics/ClassLength
+    class Lifecycle
+      attr_reader :settings, :owner_pid, :output_path, :recorder,
+                  :watchdog, :active_operations, :watchdog_policy,
+                  :redactor, :probe_registry, :execution_context_store,
+                  :rails_integration
+
+      def self.start(...)
+        new(...)
+      end
+
+      def initialize(
+        settings:,
+        watchdog_policy: nil,
+        probes_enabled: false,
+        clock: Clock.new,
+        session_id_source: SecureRandom.method(:uuid),
+        pid_source: Process.method(:pid),
+        writer_factory: JSONL::Writer.method(:open),
+        random: Sampler::RANDOM_SOURCE
+      )
+        validate_dependencies!(
+          settings, watchdog_policy, probes_enabled, clock,
+          session_id_source, pid_source, writer_factory, random
+        )
+        @settings = settings
+        @watchdog_policy = watchdog_policy
+        @probes_enabled = probes_enabled
+        @clock = clock
+        @session_id_source = session_id_source
+        @pid_source = pid_source
+        @writer_factory = writer_factory
+        @random = random
+        @owner_pid = current_pid
+        @state = :starting
+        @output_path = nil
+        @recorder = nil
+        @watchdog = nil
+        @scheduler_observer = nil
+        @active_operations = nil
+        @redactor = nil
+        @probe_registry = nil
+        @execution_context_store = nil
+        @rails_integration = nil
+        start_process_session!
+      rescue StandardError => e
+        startup_failure!(e)
+      end
+
+      def active?
+        @state == :active && recorder&.active?
+      end
+
+      def disabled?
+        @state == :disabled || recorder&.disabled?
+      end
+
+      def closed?
+        @state == :closed
+      end
+
+      def ensure_current_process!
+        pid = current_pid
+        return self if pid == owner_pid
+
+        abandon_inherited_runtime!
+        @owner_pid = pid
+        @output_path = nil
+        @recorder = nil
+        @watchdog = nil
+        @scheduler_observer = nil
+        @active_operations = nil
+        @redactor = nil
+        @probe_registry = nil
+        @execution_context_store = nil
+        @rails_integration = nil
+        @state = :starting
+        # Reset fiber-local context after fork
+        ExecutionContext.reset!
+        start_process_session!
+        self
+      rescue StandardError => e
+        process_failure!(e)
+      end
+
+      def shutdown(exception: nil)
+        ensure_current_process!
+        return @summary if closed?
+
+        runtime_error = stop_runtime_observers
+        status = runtime_error && exception.nil? ? :degraded : shutdown_status(exception)
+        @summary = recorder&.close(status: status)
+        @state = :closed
+        raise runtime_error if runtime_error && !settings.policy.fail_open?
+
+        @summary
+      rescue StandardError => e
+        @state = :closed
+        raise e unless settings.policy.fail_open?
+
+        nil
+      end
+
+      private
+
+      def validate_dependencies!(candidate_settings, watchdog, probes, candidate_clock, session_ids, pids, writers, random)
+        unless candidate_settings.is_a?(Environment::Settings)
+          raise RuntimeContractError, 'settings must be FiberAudit::Runtime::Environment::Settings'
+        end
+        unless watchdog.nil? || watchdog.is_a?(WatchdogPolicy)
+          raise RuntimeContractError, 'watchdog_policy must be a FiberAudit::Runtime::WatchdogPolicy or nil'
+        end
+        raise RuntimeContractError, 'probes_enabled must be a Boolean' unless [true, false].include?(probes)
+        raise RuntimeContractError, 'clock must be a FiberAudit::Runtime::Clock' unless candidate_clock.is_a?(Clock)
+
+        {
+          'session_id_source' => session_ids,
+          'pid_source' => pids,
+          'writer_factory' => writers,
+          'random source' => random
+        }.each do |name, source|
+          raise RuntimeContractError, "#{name} must respond to call" unless source.respond_to?(:call)
+        end
+      end
+
+      def start_process_session!
+        session_id = @session_id_source.call
+        started_at = @clock.wall_time
+        started_monotonic_ns = @clock.monotonic_ns
+        @output_path = build_output_path(session_id)
+        session = Session.new(
+          id: session_id,
+          started_at: started_at,
+          started_monotonic_ns: started_monotonic_ns,
+          policy: settings.policy
+        )
+        writer = @writer_factory.call(path: output_path, max_record_bytes: settings.policy.max_record_bytes)
+        @recorder = start_recorder(session, writer)
+        setup_runtime_observers! if recorder.active?
+        @state = recorder.active? ? :active : :disabled
+      end
+
+      def start_recorder(session, writer)
+        Recorder.start(session: session, writer: writer, clock: @clock, random: @random)
+      rescue StandardError
+        begin
+          writer.close
+        rescue StandardError
+          nil
+        end
+        raise
+      end
+
+      def setup_runtime_observers!
+        @active_operations = ActiveOperations.new(pid_source: @pid_source)
+        @redactor = Redactor.new(root: settings.project_root, policy: settings.policy)
+        @execution_context_store = ExecutionContext if @probes_enabled
+        setup_watchdog! if watchdog_policy
+        setup_rails_integration! if @probes_enabled
+        setup_probes! if @probes_enabled
+      rescue StandardError => e
+        unless e.instance_variable_defined?(:@fiber_audit_runtime_accounted)
+          recorder.internal_error!
+          e.instance_variable_set(:@fiber_audit_runtime_accounted, true)
+        end
+        deactivate_active_components!
+        close_failed_startup!(e)
+      end
+
+      def deactivate_active_components!
+        # Deactivate components in reverse order of setup
+        begin
+          Probes::Registry.deactivate(@probe_registry) if @probe_registry
+        rescue StandardError
+          nil
+        ensure
+          @probe_registry = nil
+        end
+        begin
+          RailsIntegration.deactivate(@rails_integration) if @rails_integration
+        rescue StandardError
+          nil
+        ensure
+          @rails_integration = nil
+        end
+        begin
+          if @scheduler_observer
+            SchedulerObserver.deactivate(@scheduler_observer)
+            @watchdog&.stop
+          end
+        rescue StandardError
+          nil
+        ensure
+          @scheduler_observer = nil
+          @watchdog = nil
+        end
+      end
+
+      def setup_rails_integration!
+        @rails_integration = RailsIntegration.activate(
+          context_store: @execution_context_store,
+          recorder: recorder
+        )
+      rescue StandardError
+        @rails_integration = nil
+        raise unless settings.policy.fail_open?
+      end
+
+      def setup_watchdog!
+        @watchdog = Watchdog.new(
+          policy: watchdog_policy,
+          recorder: recorder,
+          redactor: redactor,
+          active_operations: active_operations,
+          clock: @clock
+        )
+        @scheduler_observer = SchedulerObserver.activate(watchdog: watchdog) if watchdog.enabled?
+      end
+
+      def setup_probes!
+        base = Probes::Base.new(
+          recorder: recorder,
+          clock: @clock,
+          redactor: redactor,
+          active_operations: active_operations,
+          execution_context_store: @execution_context_store,
+          pid_source: @pid_source
+        )
+        @probe_registry = Probes::Registry.activate(base: base)
+      end
+
+      def close_failed_startup!(error)
+        @probe_registry = nil
+        return if settings.policy.fail_open?
+
+        begin
+          recorder.close(status: :degraded)
+        rescue StandardError
+          nil
+        end
+        raise error
+      end
+
+      def build_output_path(session_id)
+        unless session_id.is_a?(String) && session_id.match?(Validation::UUID)
+          raise RuntimeContractError, 'session ID source must return a canonical lowercase UUID'
+        end
+
+        filename = "fiber-audit-runtime-#{settings.launch_id}-#{owner_pid}-#{session_id}.jsonl"
+        File.join(settings.output_directory, filename).freeze
+      end
+
+      def abandon_inherited_runtime!
+        recorder&.writer&.close
+      ensure
+        @recorder = nil
+        @watchdog = nil
+        @scheduler_observer = nil
+        @active_operations = nil
+        @redactor = nil
+        @probe_registry = nil
+        @execution_context_store = nil
+        @rails_integration = nil
+      end
+
+      def stop_runtime_observers
+        error = nil
+        begin
+          RailsIntegration.deactivate(@rails_integration) if @rails_integration
+        rescue StandardError => e
+          error ||= e
+        ensure
+          @rails_integration = nil
+        end
+        begin
+          Probes::Registry.deactivate(probe_registry) if probe_registry
+        rescue StandardError => e
+          error ||= e
+        ensure
+          @probe_registry = nil
+        end
+        begin
+          SchedulerObserver.deactivate(@scheduler_observer) if @scheduler_observer
+          watchdog&.stop
+        rescue StandardError => e
+          error ||= e
+        ensure
+          @scheduler_observer = nil
+        end
+        recorder&.internal_error! if error
+        error
+      end
+
+      def startup_failure!(error)
+        raise error unless defined?(@settings) && settings.policy.fail_open?
+
+        @state = :disabled
+      end
+
+      def process_failure!(error)
+        raise error unless settings.policy.fail_open?
+
+        @state = :disabled
+        self
+      end
+
+      def current_pid
+        value = @pid_source.call
+        unless value.is_a?(Integer) && value.positive?
+          raise RuntimeContractError, 'pid source must return a positive Integer'
+        end
+
+        value
+      end
+
+      def shutdown_status(exception)
+        return :completed if exception.nil? || exception.is_a?(SystemExit)
+
+        :aborted
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/fiber_audit/runtime/limits.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative 'policy'
+require_relative 'session'
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    class Limits
+      WINDOW_NS = 1_000_000_000
+      MAX_COUNTER = 9_223_372_036_854_775_807
+      COUNTERS = SessionSummary::COUNTERS
+      DROP_REASONS = %i[
+        sampled_out rate_limited session_event_limited session_byte_limited oversize
+      ].freeze
+
+      attr_reader :policy, :started_monotonic_ns
+
+      def initialize(policy:, started_monotonic_ns:)
+        raise RuntimeContractError, 'policy must be a FiberAudit::Runtime::Policy' unless policy.is_a?(Policy)
+
+        @policy = policy
+        @started_monotonic_ns = Validation.integer(started_monotonic_ns, 'started_monotonic_ns')
+        @counters = COUNTERS.to_h { |name| [name, 0] }
+        @window_index = 0
+        @emitted_in_window = 0
+        @last_admission_ns = @started_monotonic_ns
+      end
+
+      def observe!
+        increment!(:events_observed)
+      end
+
+      def sampled_out!
+        increment!(:sampled_out)
+      end
+
+      def preflight_event(now_ns:)
+        now = normalize_admission_time(now_ns)
+        advance_window!(now)
+        return :session_event_limited unless policy.session_event_allowed?(emitted_events: @counters[:events_emitted])
+        return :rate_limited unless policy.rate_allowed?(emitted_in_window: @emitted_in_window)
+
+        nil
+      end
+
+      def drop!(reason)
+        raise RuntimeContractError, "unknown runtime drop reason: #{reason.inspect}" unless DROP_REASONS.include?(reason)
+
+        increment!(reason)
+      end
+
+      def emitted!(now_ns:)
+        now = normalize_admission_time(now_ns)
+        advance_window!(now)
+        increment!(:events_emitted)
+        increment_window!
+      end
+
+      def internal_error!(count: 1)
+        amount = Validation.integer(count, 'internal error count', minimum: 1)
+        increment!(:internal_errors, amount)
+      end
+
+      def counters
+        @counters.dup.freeze
+      end
+
+      private
+
+      def normalize_admission_time(value)
+        now = Validation.integer(value, 'admission monotonic time')
+        raise RuntimeContractError, 'admission monotonic time precedes the session' if now < @started_monotonic_ns
+        raise RuntimeSafetyError, 'monotonic clock moved backwards' if now < @last_admission_ns
+
+        @last_admission_ns = now
+      end
+
+      def advance_window!(now)
+        index = (now - started_monotonic_ns) / WINDOW_NS
+        return if index == @window_index
+
+        @window_index = index
+        @emitted_in_window = 0
+      end
+
+      def increment!(name, amount = 1)
+        following = @counters.fetch(name) + amount
+        raise RuntimeSafetyError, "runtime counter overflow: #{name}" if following > MAX_COUNTER
+
+        @counters[name] = following
+      end
+
+      def increment_window!
+        following = @emitted_in_window + 1
+        raise RuntimeSafetyError, 'runtime rate counter overflow' if following > MAX_COUNTER
+
+        @emitted_in_window = following
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/location.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    Location = Data.define(:path, :line, :column) do
+      def initialize(path:, line: nil, column: nil)
+        super(
+          path: normalize_path(path),
+          line: Validation.integer(line, 'line', minimum: 1, allow_nil: true),
+          column: Validation.integer(column, 'column', allow_nil: true)
+        )
+      end
+
+      private
+
+      def normalize_path(value)
+        path = Validation.string(value, 'path', max_bytes: Location::MAX_PATH_BYTES)
+        return path if Location::SENTINELS.include?(path)
+
+        normalized = path.tr('\\', '/')
+        raise RuntimeContractError, 'path must be project-relative' if absolute_path?(normalized)
+
+        clean = Pathname.new(normalized).cleanpath.to_s
+        if clean == '.' || clean == '..' || clean.start_with?('../')
+          raise RuntimeContractError, 'path must not escape the project root'
+        end
+
+        clean.freeze
+      rescue ArgumentError
+        raise RuntimeContractError, 'path is invalid'
+      end
+
+      def absolute_path?(path)
+        path.start_with?('/', '//') || path.match?(%r{\A[A-Za-z]:/})
+      end
+    end
+
+    Location.const_set(:SENTINELS, %w[[external] [redacted]].freeze)
+    Location.const_set(:MAX_PATH_BYTES, 1_024)
+  end
+end

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