fiber_audit 0.1.0 → 0.2.0

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

data/lib/fiber_audit/runtime/supervisor.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module FiberAudit
+  module Runtime
+    class Supervisor
+      SIGNALS = %w[INT TERM HUP QUIT].select { |name| Signal.list.key?(name) }.freeze
+
+      class SystemAdapter
+        def spawn(environment, command, cwd)
+          executable = command.fetch(0)
+          Process.spawn(
+            environment,
+            [executable, executable],
+            *command.drop(1),
+            chdir: cwd,
+            pgroup: true
+          )
+        end
+
+        def wait2(pid)
+          Process.wait2(pid)
+        end
+
+        def trap(signal, handler = nil, &)
+          Signal.trap(signal, handler, &)
+        end
+
+        def kill(signal, pid)
+          Process.kill(signal, pid)
+        end
+      end
+
+      def initialize(command:, environment:, cwd:, adapter: SystemAdapter.new)
+        validate_command!(command)
+        raise RuntimeContractError, 'child environment must be a Hash' unless environment.is_a?(Hash)
+        raise RuntimeContractError, 'runtime cwd must be an existing directory' unless File.directory?(cwd)
+
+        @command = command.map { |argument| argument.dup.freeze }.freeze
+        @environment = environment.transform_values { |value| value&.dup&.freeze }.freeze
+        @cwd = File.expand_path(cwd).freeze
+        @adapter = adapter
+        @child_pid = nil
+      end
+
+      def run
+        handlers = {}
+        begin
+          # Install traps only after spawn so POSIX-spawned children cannot inherit
+          # FiberAudit's forwarding handlers and accidentally ignore termination.
+          @child_pid = @adapter.spawn(@environment, @command, @cwd)
+          install_handlers(handlers)
+          _pid, status = wait_for_child
+          status_code(status)
+        ensure
+          restore_handlers(handlers)
+          @child_pid = nil
+        end
+      end
+
+      private
+
+      def validate_command!(command)
+        unless command.is_a?(Array) && !command.empty? && command.all?(String)
+          raise RuntimeContractError, 'runtime command must be a nonempty Array of Strings'
+        end
+
+        command.each_with_index do |argument, index|
+          next if argument.valid_encoding? && !argument.include?("\0") && (index.positive? || !argument.empty?)
+
+          raise RuntimeContractError, 'runtime command contains an invalid argument'
+        end
+      end
+
+      def install_handlers(handlers)
+        SIGNALS.each do |signal|
+          handlers[signal] = @adapter.trap(signal) { receive_signal(signal) }
+        end
+      end
+
+      def restore_handlers(handlers)
+        handlers.each { |signal, previous| @adapter.trap(signal, previous) }
+      end
+
+      def receive_signal(signal)
+        forward_signal(signal) if @child_pid
+      end
+
+      def forward_signal(signal)
+        @adapter.kill(signal, -@child_pid)
+      rescue Errno::ESRCH, Errno::EINVAL, NotImplementedError
+        begin
+          @adapter.kill(signal, @child_pid)
+        rescue Errno::ESRCH, Errno::EINVAL, NotImplementedError
+          nil
+        end
+      end
+
+      def wait_for_child
+        @adapter.wait2(@child_pid)
+      rescue Errno::EINTR
+        retry
+      end
+
+      def status_code(status)
+        return status.exitstatus if status.exited?
+        return 128 + status.termsig if status.signaled?
+
+        raise RuntimeSafetyError, 'wrapped command ended without an exit status'
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/validation.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module FiberAudit
+  module Runtime
+    module Validation
+      IDENTIFIER = /\A[a-z][a-z0-9_]*\z/
+      UUID = /\A[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/
+      CONTROL = /[[:cntrl:]]/
+      OPERATION = /\A(?:::)?[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*(?:[.#](?:[a-zA-Z_][a-zA-Z0-9_]*[!?=]?|\[\]=?))\z/
+      SPECIAL_OPERATIONS = %w[Thread.current.[] Thread.current.[]=].freeze
+
+      module_function
+
+      def identifier(value, field, max_bytes: 64)
+        normalized = value.is_a?(String) || value.is_a?(Symbol) ? value.to_s : nil
+        unless normalized&.match?(IDENTIFIER) && normalized.bytesize <= max_bytes
+          raise RuntimeContractError, "#{field} must be a snake-case identifier"
+        end
+
+        normalized.to_sym
+      end
+
+      def string(value, field, max_bytes:, allow_nil: false)
+        return if value.nil? && allow_nil
+        unless value.is_a?(String) && value.valid_encoding? && !value.empty? &&
+               value.bytesize <= max_bytes && !value.match?(CONTROL)
+          raise RuntimeContractError, "#{field} must be a non-empty UTF-8 String without control characters"
+        end
+
+        value.dup.freeze
+      end
+
+      def operation(value, allow_nil: false)
+        return if value.nil? && allow_nil
+
+        normalized = string(value, 'operation', max_bytes: 256)
+        unless normalized == '[redacted]' || SPECIAL_OPERATIONS.include?(normalized) || normalized.match?(OPERATION)
+          raise RuntimeContractError, 'operation must be canonical or redacted'
+        end
+
+        normalized
+      end
+
+      def integer(value, field, minimum: 0, allow_nil: false)
+        return if value.nil? && allow_nil
+        unless value.is_a?(Integer) && value >= minimum
+          raise RuntimeContractError, "#{field} must be an Integer >= #{minimum}"
+        end
+
+        value
+      end
+
+      def finite_number(value, field)
+        raise RuntimeContractError, "#{field} must be a finite number" unless value.is_a?(Numeric) && value.finite?
+
+        value
+      end
+
+      def utc_time(value, field)
+        raise RuntimeContractError, "#{field} must be a Time" unless value.is_a?(Time)
+
+        value.getutc.freeze
+      end
+    end
+  end
+end