fiber_audit 0.1.0 → 0.2.1

data/lib/fiber_audit/runtime/recorder.rb

@@ -0,0 +1,333 @@
+# frozen_string_literal: true
+
+require_relative 'clock'
+require_relative 'event'
+require_relative 'jsonl/writer'
+require_relative 'limits'
+require_relative 'sampler'
+require_relative 'session'
+
+module FiberAudit
+  module Runtime
+    # Thread-safe coordinator for one bounded append-only runtime session.
+    # rubocop:disable Metrics/ClassLength
+    class Recorder
+      RESULTS = %i[
+        emitted sampled_out rate_limited session_event_limited session_byte_limited
+        oversize internal_error inactive
+      ].freeze
+      MAX_COUNTER = Limits::MAX_COUNTER
+      OUTCOME_COUNTERS = 6
+
+      attr_reader :session, :writer
+
+      def self.start(...)
+        new(...)
+      end
+
+      def initialize(session:, writer:, clock: Clock.new, random: Sampler::RANDOM_SOURCE)
+        validate_dependencies!(session, writer, clock, random)
+        @session = session
+        @writer = writer
+        @clock = clock
+        @mutex = Mutex.new
+        @state = :starting
+        @sequence = 1
+        @in_flight = 0
+        @start_written = false
+        @summary = nil
+        @limits = Limits.new(policy: session.policy, started_monotonic_ns: session.started_monotonic_ns)
+        @sampler = Sampler.new(policy: session.policy, random: random)
+        @end_reserve_bytes = end_reserve_bytes
+        start_session!
+      rescue StandardError => e
+        startup_failure!(e)
+      end
+
+      def record(&factory)
+        record_observation(sample: true, factory: factory)
+      end
+
+      # Control evidence is never sampled, but still consumes every configured
+      # rate, count, record-size, and session-size budget.
+      def record_control(&factory)
+        record_observation(sample: false, factory: factory)
+      end
+
+      # Accounts an instrumentation failure without retaining exception data.
+      def internal_error!
+        @mutex.synchronize do
+          return false if @state == :closed
+
+          @limits.internal_error!
+          true
+        end
+      end
+
+      def close(status: :completed)
+        requested_status = normalize_status(status)
+        @mutex.synchronize do
+          return @summary if @summary
+
+          @state = :closing
+          @limits.internal_error!(count: @in_flight) if @in_flight.positive?
+          ended_at, ended_monotonic_ns, clock_error = closing_times
+          errors = [clock_error].compact
+          summary = build_summary(requested_status, ended_at, ended_monotonic_ns)
+          errors.concat(write_end_record(summary))
+          errors.concat(close_writer)
+          summary = build_summary(requested_status, ended_at, ended_monotonic_ns) unless errors.empty?
+          @summary = summary
+          @state = :closed
+          raise errors.first if errors.any? && !session.policy.fail_open?
+
+          @summary
+        end
+      end
+
+      def active?
+        state?(:active)
+      end
+
+      def disabled?
+        state?(:disabled)
+      end
+
+      def closed?
+        state?(:closed)
+      end
+
+      def summary
+        @mutex.synchronize { @summary }
+      end
+
+      private
+
+      def validate_dependencies!(candidate_session, candidate_writer, candidate_clock, candidate_random)
+        raise RuntimeContractError, 'session must be a FiberAudit::Runtime::Session' unless candidate_session.is_a?(Session)
+        unless candidate_writer.is_a?(JSONL::Writer)
+          raise RuntimeContractError, 'writer must be a FiberAudit::Runtime::JSONL::Writer'
+        end
+        raise RuntimeContractError, 'clock must be a FiberAudit::Runtime::Clock' unless candidate_clock.is_a?(Clock)
+        raise RuntimeContractError, 'random source must respond to call' unless candidate_random.respond_to?(:call)
+      end
+
+      def start_session!
+        raise RuntimeSafetyError, 'runtime JSONL writer is not empty' unless writer.bytes_written.zero?
+        if session.started_monotonic_ns > MAX_COUNTER
+          raise RuntimeSafetyError, 'session monotonic start exceeds signed 64-bit range'
+        end
+
+        line = writer.prepare(JSONL::Schema.start_record(session))
+        required = line.bytesize + @end_reserve_bytes
+        unless session.policy.session_bytes_allowed?(written_bytes: 0, next_record_bytes: required)
+          raise RuntimeSafetyError, 'runtime session limit cannot contain start and end records'
+        end
+
+        writer.write_line(line)
+        @start_written = true
+        @state = :active
+      end
+
+      def startup_failure!(error)
+        raise error unless defined?(@session) && session.policy.fail_open?
+
+        @limits&.internal_error!
+        @state = :disabled
+      end
+
+      def record_observation(sample:, factory:)
+        raise ArgumentError, 'record requires an event factory block' unless factory
+
+        decision = begin_observation(sample: sample)
+        return decision unless decision == :selected
+
+        completed = false
+        begin
+          event = factory.call
+          completed = true
+        ensure
+          release_failed_factory unless completed
+        end
+        finish_observation(event)
+      end
+
+      def begin_observation(sample:)
+        @mutex.synchronize do
+          return :inactive unless @state == :active
+
+          @limits.observe!
+          if sample && !@sampler.sample?
+            @limits.drop!(:sampled_out)
+            return :sampled_out
+          end
+
+          @in_flight += 1
+          :selected
+        rescue StandardError => e
+          handle_internal_error!(e)
+        end
+      end
+
+      def finish_observation(event)
+        @mutex.synchronize do
+          @in_flight -= 1
+          return finish_inactive_observation unless @state == :active
+
+          emit_or_drop(event)
+        rescue StandardError => e
+          handle_internal_error!(e)
+        ensure
+          if writer.failed? && @state == :active
+            @limits.internal_error!
+            @state = :disabled
+          end
+        end
+      end
+
+      def finish_inactive_observation
+        @limits.internal_error! if @state == :disabled
+        :inactive
+      end
+
+      def emit_or_drop(event)
+        raise RuntimeContractError, 'event factory must return a FiberAudit::Runtime::Event' unless event.is_a?(Event)
+
+        now_ns = @clock.monotonic_ns
+        reason = @limits.preflight_event(now_ns: now_ns)
+        return account_preflight_drop(reason) if reason
+
+        line = prepare_event(event)
+        return :oversize unless line
+
+        unless event_bytes_allowed?(line)
+          @limits.drop!(:session_byte_limited)
+          return :session_byte_limited
+        end
+
+        writer.write_line(line)
+        @limits.emitted!(now_ns: now_ns)
+        @sequence += 1
+        :emitted
+      end
+
+      def account_preflight_drop(reason)
+        @limits.drop!(reason)
+        reason
+      end
+
+      def prepare_event(event)
+        record = JSONL::Schema.event_record(session_id: session.id, sequence: @sequence, event: event)
+        writer.prepare(record)
+      rescue RuntimeSafetyError
+        @limits.drop!(:oversize)
+        nil
+      end
+
+      def event_bytes_allowed?(line)
+        required = line.bytesize + @end_reserve_bytes
+        session.policy.session_bytes_allowed?(
+          written_bytes: writer.bytes_written,
+          next_record_bytes: required
+        )
+      end
+
+      def release_failed_factory
+        @mutex.synchronize do
+          @in_flight -= 1
+          @limits.internal_error! if @state == :disabled
+        end
+      end
+
+      def handle_internal_error!(error)
+        @limits.internal_error!
+        @state = :disabled
+        raise error unless session.policy.fail_open?
+
+        :internal_error
+      end
+
+      def closing_times
+        [@clock.wall_time, @clock.monotonic_ns, nil]
+      rescue StandardError => e
+        @limits.internal_error!
+        [session.started_at, session.started_monotonic_ns, e]
+      end
+
+      def write_end_record(summary)
+        return [] unless @start_written && writer.active?
+
+        record = JSONL::Schema.end_record(session_id: session.id, sequence: @sequence, summary: summary)
+        line = writer.prepare(record)
+        if line.bytesize > @end_reserve_bytes
+          raise RuntimeSafetyError, 'runtime session end record exceeded its reserved bytes'
+        end
+        unless session.policy.session_bytes_allowed?(written_bytes: writer.bytes_written, next_record_bytes: line.bytesize)
+          raise RuntimeSafetyError, 'runtime session end record exceeded the session byte limit'
+        end
+
+        writer.write_line(line)
+        []
+      rescue StandardError => e
+        @limits.internal_error!
+        [e]
+      end
+
+      def close_writer
+        writer.close
+        []
+      rescue StandardError => e
+        @limits.internal_error!
+        [e]
+      end
+
+      def build_summary(requested_status, ended_at, ended_monotonic_ns)
+        status = summary_status(requested_status)
+        SessionSummary.new(
+          ended_at: ended_at,
+          ended_monotonic_ns: ended_monotonic_ns,
+          status: status,
+          **@limits.counters
+        )
+      end
+
+      def summary_status(requested)
+        return :aborted if requested == :aborted
+        return :degraded if requested == :degraded || @limits.counters[:internal_errors].positive?
+
+        :completed
+      end
+
+      def normalize_status(value)
+        normalized = value.is_a?(String) || value.is_a?(Symbol) ? value.to_sym : nil
+        return normalized if SessionSummary::STATUSES.include?(normalized)
+
+        raise RuntimeContractError, "status must be one of: #{SessionSummary::STATUSES.join(', ')}"
+      end
+
+      def end_reserve_bytes
+        outcome = MAX_COUNTER / OUTCOME_COUNTERS
+        summary = SessionSummary.new(
+          ended_at: session.started_at,
+          ended_monotonic_ns: MAX_COUNTER,
+          status: :completed,
+          events_observed: outcome * OUTCOME_COUNTERS,
+          events_emitted: outcome,
+          sampled_out: outcome,
+          rate_limited: outcome,
+          session_event_limited: outcome,
+          session_byte_limited: outcome,
+          oversize: outcome,
+          internal_errors: MAX_COUNTER
+        )
+        record = JSONL::Schema.end_record(session_id: session.id, sequence: MAX_COUNTER, summary: summary)
+        writer.prepare(record).bytesize
+      end
+
+      def state?(expected)
+        @mutex.synchronize { @state == expected }
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end

data/lib/fiber_audit/runtime/redactor.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require_relative 'location'
+require_relative 'policy'
+
+module FiberAudit
+  module Runtime
+    class Redactor
+      REDACTED = '[redacted]'
+      EXTERNAL = '[external]'
+      WINDOWS_ABSOLUTE = %r{\A[A-Za-z]:/}
+
+      attr_reader :root, :policy
+
+      def initialize(root:, policy: Policy.new)
+        raise RuntimeContractError, 'policy must be a FiberAudit::Runtime::Policy' unless policy.is_a?(Policy)
+
+        safe_root = Validation.string(root, 'root', max_bytes: 4_096)
+        @root = canonical_root(safe_root).freeze
+        @policy = policy
+        freeze
+      rescue ArgumentError
+        raise RuntimeContractError, 'root is invalid'
+      end
+
+      def location(path:, line: nil, column: nil)
+        Location.new(path: redact_path(path), line: line, column: column)
+      rescue RuntimeContractError
+        Location.new(path: REDACTED, line: nil, column: nil)
+      end
+
+      def operation(value)
+        return if value.nil?
+
+        text = value.is_a?(String) || value.is_a?(Symbol) ? value.to_s : nil
+        return REDACTED unless text&.valid_encoding? && text.bytesize <= 256
+        return REDACTED if text.match?(Validation::CONTROL)
+        return REDACTED unless text.match?(Validation::OPERATION)
+
+        text.dup.freeze
+      end
+
+      private
+
+      def canonical_root(value)
+        normalized = value.tr('\\', '/')
+        return Pathname.new(normalized).cleanpath.to_s if windows_absolute?(normalized)
+
+        Pathname.new(normalized).expand_path.cleanpath.to_s.tr('\\', '/')
+      end
+
+      def redact_path(value)
+        return REDACTED unless value.is_a?(String) && value.valid_encoding? && !value.empty?
+        return REDACTED if value.bytesize > Location::MAX_PATH_BYTES || value.match?(Validation::CONTROL)
+
+        normalized = value.tr('\\', '/')
+        return absolute_path(normalized) if windows_absolute?(normalized)
+
+        path = Pathname.new(normalized)
+        return relative_path(path) unless path.absolute?
+
+        absolute_path(path.expand_path.cleanpath.to_s.tr('\\', '/'))
+      rescue ArgumentError
+        REDACTED
+      end
+
+      def absolute_path(path)
+        clean = Pathname.new(path).cleanpath.to_s.tr('\\', '/')
+        return EXTERNAL unless inside_root?(clean)
+
+        clean[(root.length + 1)..]
+      end
+
+      def relative_path(path)
+        clean = path.cleanpath
+        value = clean.to_s
+        return EXTERNAL if value == '..' || value.start_with?('../')
+        return REDACTED if value == '.'
+
+        value
+      end
+
+      def inside_root?(path)
+        candidate, boundary = comparable_paths(path)
+        candidate.start_with?("#{boundary}/")
+      end
+
+      def comparable_paths(path)
+        if windows_absolute?(path) && windows_absolute?(root)
+          [path.downcase, root.downcase]
+        else
+          [path, root]
+        end
+      end
+
+      def windows_absolute?(path)
+        path.match?(WINDOWS_ABSOLUTE)
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/sampler.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative 'policy'
+
+module FiberAudit
+  module Runtime
+    class Sampler
+      RANDOM_SOURCE = -> { Random.rand }.freeze
+
+      attr_reader :policy
+
+      def initialize(policy:, random: RANDOM_SOURCE)
+        raise RuntimeContractError, 'policy must be a FiberAudit::Runtime::Policy' unless policy.is_a?(Policy)
+        raise RuntimeContractError, 'random source must respond to call' unless random.respond_to?(:call)
+
+        @policy = policy
+        @random = random
+        freeze
+      end
+
+      def sample?
+        policy.sample?(draw: @random.call)
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/scheduler_observer.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require_relative 'watchdog'
+
+module FiberAudit
+  module Runtime
+    # Explicit-runtime-only hooks for schedulers installed after RUBYOPT boot.
+    class SchedulerObserver
+      module FiberHook
+        # Ruby's scheduler API fixes this writer-like method name.
+        # rubocop:disable Naming/AccessorMethodName
+        def set_scheduler(scheduler)
+          FiberAudit::Runtime::SchedulerObserver.scheduler_replacing(thread: Thread.current) if Fiber.scheduler
+          result = super
+          if scheduler
+            FiberAudit::Runtime::SchedulerObserver.scheduler_installed(
+              scheduler: scheduler,
+              thread: Thread.current
+            )
+          end
+          result
+        end
+        # rubocop:enable Naming/AccessorMethodName
+      end
+
+      module SchedulerCloseHook
+        def close(...)
+          FiberAudit::Runtime::SchedulerObserver.scheduler_closing(thread: Thread.current)
+          super
+        end
+      end
+
+      class << self
+        def activate(watchdog:)
+          raise RuntimeContractError, 'watchdog must be a FiberAudit::Runtime::Watchdog' unless watchdog.is_a?(Watchdog)
+
+          install_fiber_hook!
+          observer = new(watchdog: watchdog)
+          @current = observer
+          observer.attach_existing!
+          observer
+        end
+
+        def scheduler_replacing(thread:)
+          current_for_process&.scheduler_closing(thread: thread)
+        end
+
+        def scheduler_installed(scheduler:, thread:)
+          observer = current_for_process
+          return unless observer
+
+          observer.scheduler_installed(scheduler: scheduler, thread: thread)
+        end
+
+        def scheduler_closing(thread:)
+          current_for_process&.scheduler_closing(thread: thread)
+        end
+
+        def deactivate(observer)
+          @current = nil if @current.equal?(observer)
+          observer.deactivate
+        end
+
+        private
+
+        def current_for_process
+          observer = @current
+          return observer if observer&.active_for_current_process?
+
+          nil
+        end
+
+        def install_fiber_hook!
+          singleton = Fiber.singleton_class
+          singleton.prepend(FiberHook) unless singleton.ancestors.include?(FiberHook)
+        end
+      end
+
+      attr_reader :watchdog, :owner_pid
+
+      def initialize(watchdog:)
+        @watchdog = watchdog
+        @owner_pid = Process.pid
+        @active = true
+      end
+
+      def active_for_current_process?
+        @active && owner_pid == Process.pid
+      end
+
+      def attach_existing!
+        scheduler = Fiber.scheduler
+        scheduler_installed(scheduler: scheduler, thread: Thread.current) if scheduler
+        self
+      end
+
+      def scheduler_installed(scheduler:, thread:)
+        return self unless active_for_current_process? && watchdog.enabled?
+
+        install_close_hook!(scheduler)
+        watchdog.scheduler_installed(thread: thread)
+        self
+      rescue StandardError
+        watchdog.scheduler_unsupported(thread: thread)
+        raise unless watchdog.fail_open?
+
+        self
+      end
+
+      def scheduler_closing(thread:)
+        watchdog.scheduler_closing(thread: thread) if active_for_current_process?
+        self
+      end
+
+      def deactivate
+        @active = false
+        self
+      end
+
+      private
+
+      def install_close_hook!(scheduler)
+        singleton = scheduler.singleton_class
+        singleton.prepend(SchedulerCloseHook) unless singleton.ancestors.include?(SchedulerCloseHook)
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/session.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative '../version'
+require_relative 'policy'
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    Session = Data.define(
+      :id,
+      :started_at,
+      :started_monotonic_ns,
+      :policy,
+      :tool_version,
+      :ruby_version
+    ) do
+      def initialize(
+        id:,
+        started_at:,
+        started_monotonic_ns:,
+        policy: Policy.new,
+        tool_version: FiberAudit::VERSION,
+        ruby_version: RUBY_VERSION
+      )
+        super(
+          id: normalize_id(id),
+          started_at: Validation.utc_time(started_at, 'started_at'),
+          started_monotonic_ns: Validation.integer(started_monotonic_ns, 'started_monotonic_ns'),
+          policy: normalize_policy(policy),
+          tool_version: Validation.string(tool_version, 'tool_version', max_bytes: 64),
+          ruby_version: Validation.string(ruby_version, 'ruby_version', max_bytes: 64)
+        )
+      end
+
+      private
+
+      def normalize_id(value)
+        unless value.is_a?(String) && value.match?(Validation::UUID)
+          raise RuntimeContractError, 'id must be a canonical lowercase UUID'
+        end
+
+        value.dup.freeze
+      end
+
+      def normalize_policy(value)
+        return value if value.is_a?(Policy)
+
+        raise RuntimeContractError, 'policy must be a FiberAudit::Runtime::Policy'
+      end
+    end
+
+    SessionSummary = Data.define(
+      :ended_at,
+      :ended_monotonic_ns,
+      :status,
+      :events_observed,
+      :events_emitted,
+      :sampled_out,
+      :rate_limited,
+      :session_event_limited,
+      :session_byte_limited,
+      :oversize,
+      :internal_errors
+    ) do
+      def initialize(ended_at:, ended_monotonic_ns:, status:, **counters)
+        unknown = counters.keys - SessionSummary::COUNTERS
+        missing = SessionSummary::COUNTERS - counters.keys
+        raise RuntimeContractError, "unknown session summary field: #{unknown.first}" unless unknown.empty?
+        raise RuntimeContractError, "missing session summary field: #{missing.first}" unless missing.empty?
+
+        normalized_status = status.is_a?(String) || status.is_a?(Symbol) ? status.to_sym : nil
+        unless SessionSummary::STATUSES.include?(normalized_status)
+          raise RuntimeContractError, "status must be one of: #{SessionSummary::STATUSES.join(', ')}"
+        end
+
+        normalized_counters = counters.to_h do |name, value|
+          [name, Validation.integer(value, name.to_s)]
+        end
+        accounted = %i[
+          events_emitted
+          sampled_out
+          rate_limited
+          session_event_limited
+          session_byte_limited
+          oversize
+        ].sum { |name| normalized_counters.fetch(name) }
+        if accounted > normalized_counters.fetch(:events_observed)
+          raise RuntimeContractError, 'event accounting exceeds events_observed'
+        end
+
+        super(
+          ended_at: Validation.utc_time(ended_at, 'ended_at'),
+          ended_monotonic_ns: Validation.integer(ended_monotonic_ns, 'ended_monotonic_ns'),
+          status: normalized_status,
+          **normalized_counters
+        )
+      end
+    end
+
+    SessionSummary.const_set(:STATUSES, %i[completed degraded aborted].freeze)
+    SessionSummary.const_set(:COUNTERS, %i[
+      events_observed
+      events_emitted
+      sampled_out
+      rate_limited
+      session_event_limited
+      session_byte_limited
+      oversize
+      internal_errors
+    ].freeze)
+  end
+end