fiber_audit 0.1.0 → 0.2.0

data/lib/fiber_audit/runtime/rails_integration.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+require_relative 'execution_context'
+
+module FiberAudit
+  module Runtime
+    # Process-local, idempotent Rails integration.
+    # Installs prepend hooks for Rails boundaries when detected.
+    # Becomes inert after deactivation or fork.
+    # Supports late-load rescanning for Rails components loaded after boot.
+    class RailsIntegration
+      attr_reader :owner_pid, :context_store, :recorder
+
+      def initialize(context_store:, recorder: nil)
+        @context_store = context_store
+        @recorder = recorder
+        @owner_pid = Process.pid
+        @active = true
+        @middleware_stack = nil
+        @require_hook_installed = false
+        @mutex = Mutex.new
+      end
+
+      def active_for_current_process?
+        @active && @owner_pid == Process.pid
+      end
+
+      def deactivate!
+        @active = false
+        self
+      end
+
+      def install!
+        return unless active_for_current_process?
+
+        @mutex.synchronize do
+          install_require_hook
+          install_controller_hook
+          install_job_hook
+          install_cable_hook
+          try_install_middleware_hook
+        end
+        self
+      rescue StandardError => e
+        handle_installation_failure(e)
+        self
+      end
+
+      def rescan!
+        return unless active_for_current_process?
+
+        @mutex.synchronize do
+          install_controller_hook
+          install_job_hook
+          install_cable_hook
+          try_install_middleware_hook
+        end
+        self
+      rescue StandardError => e
+        handle_installation_failure(e)
+        self
+      end
+
+      class << self
+        def activate(context_store: ExecutionContext, recorder: nil)
+          integration = new(context_store: context_store, recorder: recorder)
+          integration.install!
+          @current = integration
+          @current
+        rescue StandardError
+          @current = nil
+          raise
+        end
+
+        attr_reader :current
+
+        def deactivate(integration = nil)
+          target = integration || @current
+          return unless target
+
+          target.deactivate!
+          @current = nil if @current.equal?(target)
+        end
+
+        def rescan!
+          @current&.rescan! if @current&.active_for_current_process?
+        end
+
+        def rescan_after_require!
+          key = :fiber_audit_rails_require_rescan
+          thread = Thread.current
+          acquired = false
+          return if thread.thread_variable_get(key)
+
+          thread.thread_variable_set(key, true)
+          acquired = true
+          rescan!
+        ensure
+          thread&.thread_variable_set(key, false) if acquired
+        end
+      end
+
+      private
+
+      def handle_installation_failure(error)
+        unless error.instance_variable_defined?(:@fiber_audit_runtime_accounted)
+          recorder&.internal_error! unless recorder&.disabled?
+          error.instance_variable_set(:@fiber_audit_runtime_accounted, true)
+        end
+        raise error unless fail_open?
+      end
+
+      def fail_open?
+        return true unless recorder
+
+        recorder.session.policy.fail_open?
+      end
+
+      def account_internal_error
+        return unless recorder
+
+        recorder.internal_error! unless recorder.disabled?
+      end
+
+      def install_require_hook
+        return if @require_hook_installed
+
+        # Install narrow guarded require hook for late Rails loading
+        # Independent of probe registry
+        ::Kernel.prepend(RequireHook) unless ::Kernel.ancestors.include?(RequireHook)
+        @require_hook_installed = true
+      end
+
+      def install_controller_hook
+        return unless defined?(::ActionController::Metal)
+
+        ::ActionController::Metal.prepend(ControllerHook) unless ::ActionController::Metal.ancestors.include?(ControllerHook)
+      end
+
+      def install_job_hook
+        return unless defined?(::ActiveJob::Base)
+
+        ::ActiveJob::Base.prepend(JobHook) unless ::ActiveJob::Base.ancestors.include?(JobHook)
+      end
+
+      def install_cable_hook
+        return unless defined?(::ActionCable::Channel::Base)
+
+        ::ActionCable::Channel::Base.prepend(CableHook) unless ::ActionCable::Channel::Base.ancestors.include?(CableHook)
+      end
+
+      def try_install_middleware_hook
+        return unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+        stack = ::Rails.application.config.middleware
+        return if @middleware_stack.equal?(stack)
+
+        # Try to insert middleware into Rails stack. A replacement stack (for
+        # example after a Rails reload) is eligible for installation again.
+        begin
+          stack.use(Middleware)
+          @middleware_stack = stack
+        rescue StandardError => e
+          # Stack may be finalized - that's okay, middleware is optional
+          handle_installation_failure(e)
+        end
+      end
+
+      # Require hook for late Rails loading - independent of probe registry
+      # Narrow, guarded, behavior-preserving
+      module RequireHook
+        def require(path)
+          result = super
+          # Only rescan after a successful require that loaded a feature.
+          RailsIntegration.rescan_after_require! if result
+          result
+        end
+
+        private :require
+      end
+
+      # Prepend hooks - consult active integration before setting context
+      # Resilient to context store failures in fail-open mode
+      # Critical: must not catch application exceptions or invoke app twice
+      module ControllerHook
+        def process_action(...)
+          integration = RailsIntegration.current
+          return super unless integration&.active_for_current_process?
+
+          executed = false
+          begin
+            integration.context_store.with(:request) do
+              executed = true
+              super
+            end
+          rescue StandardError
+            raise if executed
+            # Context setup failed before application code ran
+            raise unless integration.send(:fail_open?)
+
+            integration.send(:account_internal_error)
+            super
+          end
+        end
+      end
+
+      module JobHook
+        def perform_now(...)
+          integration = RailsIntegration.current
+          return super unless integration&.active_for_current_process?
+
+          executed = false
+          begin
+            integration.context_store.with(:job) do
+              executed = true
+              super
+            end
+          rescue StandardError
+            raise if executed
+            # Context setup failed before application code ran
+            raise unless integration.send(:fail_open?)
+
+            integration.send(:account_internal_error)
+            super
+          end
+        end
+      end
+
+      module CableHook
+        def dispatch_action(...)
+          integration = RailsIntegration.current
+          return super unless integration&.active_for_current_process?
+
+          executed = false
+          begin
+            integration.context_store.with(:websocket) do
+              executed = true
+              super
+            end
+          rescue StandardError
+            raise if executed
+            # Context setup failed before application code ran
+            raise unless integration.send(:fail_open?)
+
+            integration.send(:account_internal_error)
+            super
+          end
+        end
+      end
+
+      # Rack middleware for :middleware context
+      class Middleware
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          integration = RailsIntegration.current
+          return @app.call(env) unless integration&.active_for_current_process?
+
+          executed = false
+          begin
+            integration.context_store.with(:middleware) do
+              executed = true
+              @app.call(env)
+            end
+          rescue StandardError
+            raise if executed
+            # Context setup failed before application code ran
+            raise unless integration.send(:fail_open?)
+
+            integration.send(:account_internal_error)
+            @app.call(env)
+          end
+        end
+      end
+    end
+  end
+end

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