fiber_audit 0.1.0 → 0.2.0

data/lib/fiber_audit/runtime/jsonl/writer.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative '../../errors'
+require_relative '../validation'
+require_relative 'schema'
+
+module FiberAudit
+  module Runtime
+    module JSONL
+      class Writer
+        attr_reader :bytes_written, :max_record_bytes
+
+        def self.open(path:, max_record_bytes:)
+          safe_path = Validation.string(path, 'runtime output path', max_bytes: 4_096)
+          # The returned Writer deliberately owns this descriptor until #close.
+          io = File.open(safe_path, File::WRONLY | File::CREAT | File::EXCL, 0o600) # rubocop:disable Style/FileOpen
+          io.binmode
+          io.sync = true
+          new(io: io, max_record_bytes: max_record_bytes, owns_io: true)
+        rescue StandardError
+          io&.close
+          raise
+        end
+
+        def initialize(io:, max_record_bytes:, owns_io: false)
+          raise RuntimeContractError, 'io must respond to write' unless io.respond_to?(:write)
+          unless max_record_bytes.is_a?(Integer) && max_record_bytes.positive?
+            raise RuntimeContractError, 'max_record_bytes must be a positive Integer'
+          end
+          raise RuntimeContractError, 'owns_io must be a Boolean' unless [true, false].include?(owns_io)
+
+          @io = io
+          @max_record_bytes = max_record_bytes
+          @owns_io = owns_io
+          @bytes_written = 0
+          @state = :active
+        end
+
+        def prepare(record)
+          ensure_active!
+          Schema.dump(record, max_record_bytes: max_record_bytes)
+        end
+
+        def write(record)
+          write_line(prepare(record))
+        end
+
+        def write_line(line)
+          ensure_active!
+          validate_line!(line)
+          completed = false
+          begin
+            write_all(line)
+            @io.flush if @io.respond_to?(:flush)
+            completed = true
+          ensure
+            @state = :failed unless completed
+          end
+          line.bytesize
+        end
+
+        def active?
+          @state == :active
+        end
+
+        def failed?
+          @state == :failed
+        end
+
+        def closed?
+          @state == :closed
+        end
+
+        def close
+          return if closed?
+
+          completed = false
+          begin
+            @io.close if @owns_io && @io.respond_to?(:close) && !@io.closed?
+            completed = true
+          ensure
+            @state = :failed unless completed
+          end
+          @state = :closed unless failed?
+          nil
+        end
+
+        private
+
+        def write_all(line)
+          offset = 0
+          while offset < line.bytesize
+            written = @io.write(line.byteslice(offset, line.bytesize - offset))
+            validate_write_result!(written, line.bytesize - offset)
+            offset += written
+            @bytes_written += written
+          end
+        end
+
+        def ensure_active!
+          raise RuntimeSafetyError, "runtime JSONL writer is #{@state}" unless active?
+        end
+
+        def validate_line!(line)
+          valid = line.is_a?(String) && line.valid_encoding? && line.end_with?("\n") && line.count("\n") == 1
+          raise RuntimeContractError, 'runtime JSONL line must be one valid complete line' unless valid
+          return unless line.bytesize > max_record_bytes
+
+          raise RuntimeSafetyError,
+                "runtime JSONL record is #{line.bytesize} bytes; limit is #{max_record_bytes}"
+        end
+
+        def validate_write_result!(written, remaining)
+          return if written.is_a?(Integer) && written.positive? && written <= remaining
+
+          @state = :failed
+          raise RuntimeSafetyError, "runtime JSONL write returned invalid byte count: #{written.inspect}"
+        end
+      end
+    end
+  end
+end

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