fiber_audit 0.1.0 → 0.2.0

data/lib/fiber_audit/runtime/probes/registry.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'http'
+require_relative 'io_select'
+require_relative 'socket'
+require_relative 'subprocess'
+require_relative 'synchronization'
+require_relative 'thread_state'
+require_relative 'thread_wait'
+
+module FiberAudit
+  module Runtime
+    module Probes
+      # Process-local owner of idempotent probe installation and dispatch.
+      class Registry
+        PROBE_INSTALLERS = [
+          Subprocess,
+          ThreadWait,
+          Synchronization,
+          ThreadState,
+          IOSelect,
+          Socket,
+          HTTP
+        ].freeze
+
+        module RequireInstanceHook
+          def require(...)
+            result = super
+            Registry.rescan_current!
+            result
+          end
+
+          private :require
+        end
+
+        module RequireSingletonHook
+          def require(...)
+            result = super
+            Registry.rescan_current!
+            result
+          end
+        end
+
+        class << self
+          def activate(base:)
+            raise RuntimeContractError, 'base must be a Runtime::Probes::Base' unless base.is_a?(Base)
+
+            registry = new(base: base)
+            @current = registry
+            registry.install!
+            registry
+          rescue StandardError
+            registry&.deactivate
+            @current = nil if @current.equal?(registry)
+            raise
+          end
+
+          def observe(operation:, measurements: {}, emit_start: false, measurement_builder: nil, &application)
+            raise ArgumentError, 'probe observation requires a block' unless application
+
+            registry = current_for_observation
+            return application.call unless registry
+
+            registry.base.observe(
+              operation: operation,
+              measurements: measurements,
+              emit_start: emit_start,
+              measurement_builder: measurement_builder,
+              &application
+            )
+          end
+
+          def rescan_current!
+            current_for_observation&.scan!
+          end
+
+          def deactivate(registry)
+            @current = nil if @current.equal?(registry)
+            registry&.deactivate
+          end
+
+          def current
+            current_for_observation
+          end
+
+          private
+
+          def current_for_observation
+            registry = @current
+            return unless registry
+            return registry if registry.active_for_current_process?
+            return unless registry.stale_process?
+
+            FiberAudit::Runtime::Boot.current if defined?(FiberAudit::Runtime::Boot)
+            registry = @current
+            registry if registry&.active_for_current_process?
+          end
+        end
+
+        attr_reader :base, :owner_pid
+
+        def initialize(base:)
+          @base = base
+          @owner_pid = Process.pid
+          @mutex = Mutex.new
+          @active = true
+        end
+
+        def install!
+          scan!
+          self
+        end
+
+        def scan!
+          return self unless active_for_current_process?
+
+          base.with_guard do
+            @mutex.synchronize do
+              prepend_once(Kernel, RequireInstanceHook)
+              prepend_once(Kernel.singleton_class, RequireSingletonHook)
+              PROBE_INSTALLERS.each { |installer| installer.install!(self) }
+            end
+          end
+          self
+        rescue StandardError => e
+          base.instrumentation_failure(e)
+          self
+        end
+
+        def prepend_once(target, hook)
+          unless target.is_a?(Module) && hook.is_a?(Module)
+            raise RuntimeContractError, 'probe target and hook must be Modules'
+          end
+
+          target.prepend(hook) unless target.ancestors.include?(hook)
+          target
+        end
+
+        def deactivate
+          @active = false
+          base.deactivate
+          self
+        end
+
+        def active_for_current_process?
+          @active && owner_pid == Process.pid
+        end
+
+        def stale_process?
+          owner_pid != Process.pid
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/probes/socket.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require_relative '../../operation_vocabulary'
+
+module FiberAudit
+  module Runtime
+    module Probes
+      module Socket
+        MODULE_NAME = Module.instance_method(:name)
+        MODULE_COMPARE = Module.instance_method(:<=)
+        CONST_DEFINED = Module.instance_method(:const_defined?)
+        CONST_GET = Module.instance_method(:const_get)
+
+        module ConstructorHook
+          def new(...)
+            operation = Socket.operation_for(self)
+            return super unless operation
+
+            Registry.observe(operation: operation) { super }
+          end
+        end
+
+        module_function
+
+        def install!(registry)
+          return unless defined?(::BasicSocket)
+
+          registry.prepend_once(::BasicSocket.singleton_class, ConstructorHook)
+        end
+
+        def operation_for(klass)
+          name = MODULE_NAME.bind_call(klass)
+          return unless safe_constant_name?(name)
+          return unless exact_socket?(klass, name) || ip_socket_subclass?(klass)
+          return unless resolve_constant(name).equal?(klass)
+
+          "#{name}.new"
+        rescue StandardError
+          nil
+        end
+
+        def exact_socket?(klass, name)
+          return false unless OperationVocabulary::FA1006_EXACT.include?(name)
+
+          resolve_constant(name).equal?(klass)
+        end
+
+        def ip_socket_subclass?(klass)
+          return false unless defined?(::IPSocket)
+
+          MODULE_COMPARE.bind_call(klass, ::IPSocket) == true
+        end
+
+        def safe_constant_name?(name)
+          name.is_a?(String) && name.bytesize <= 240 &&
+            name.match?(/\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/)
+        end
+
+        def resolve_constant(name)
+          namespace = Object
+          name.split('::').each do |part|
+            unless CONST_DEFINED.bind_call(namespace, part, false)
+              namespace = nil
+              break
+            end
+
+            namespace = CONST_GET.bind_call(namespace, part, false)
+          end
+          namespace
+        rescue NameError, TypeError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/probes/subprocess.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  module Runtime
+    module Probes
+      module Subprocess
+        module KernelInstanceHook
+          def system(...)
+            Registry.observe(operation: 'Kernel.system') { super }
+          end
+
+          def exec(...)
+            Registry.observe(operation: 'Kernel.exec', emit_start: true) { super }
+          end
+
+          def spawn(...)
+            Registry.observe(operation: 'Kernel.spawn') { super }
+          end
+
+          private :system, :exec, :spawn
+        end
+
+        module KernelSingletonHook
+          def system(...)
+            Registry.observe(operation: 'Kernel.system') { super }
+          end
+
+          def exec(...)
+            Registry.observe(operation: 'Kernel.exec', emit_start: true) { super }
+          end
+
+          def spawn(...)
+            Registry.observe(operation: 'Kernel.spawn') { super }
+          end
+        end
+
+        module IOHook
+          def popen(...)
+            Registry.observe(operation: 'IO.popen') { super }
+          end
+        end
+
+        module ProcessHook
+          def waitall(...)
+            Registry.observe(operation: 'Process.waitall') { super }
+          end
+
+          def detach(...)
+            Registry.observe(operation: 'Process.detach') { super }
+          end
+        end
+
+        module Open3Hook
+          def capture2(...)
+            Registry.observe(operation: 'Open3.capture2') { super }
+          end
+
+          def capture2e(...)
+            Registry.observe(operation: 'Open3.capture2e') { super }
+          end
+
+          def capture3(...)
+            Registry.observe(operation: 'Open3.capture3') { super }
+          end
+
+          def pipeline(...)
+            Registry.observe(operation: 'Open3.pipeline') { super }
+          end
+        end
+
+        module_function
+
+        def install!(registry)
+          registry.prepend_once(Kernel, KernelInstanceHook)
+          registry.prepend_once(Kernel.singleton_class, KernelSingletonHook)
+          registry.prepend_once(IO.singleton_class, IOHook)
+          registry.prepend_once(Process.singleton_class, ProcessHook)
+          registry.prepend_once(Open3.singleton_class, Open3Hook) if defined?(Open3)
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/probes/synchronization.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  module Runtime
+    module Probes
+      module Synchronization
+        TRY_LOCK_MEASUREMENTS = lambda do |result|
+          acquired = result == true
+          { acquired: acquired, contention_observed: !acquired }
+        end
+
+        module MutexHook
+          def lock(...)
+            Registry.observe(operation: 'Mutex#lock') { super }
+          end
+
+          def synchronize(...)
+            Registry.observe(operation: 'Mutex#synchronize') { super }
+          end
+
+          def try_lock(...)
+            Registry.observe(
+              operation: 'Mutex#try_lock',
+              measurement_builder: TRY_LOCK_MEASUREMENTS
+            ) { super }
+          end
+        end
+
+        module ConditionVariableHook
+          def wait(...)
+            Registry.observe(operation: 'ConditionVariable#wait') { super }
+          end
+        end
+
+        module MonitorHook
+          def synchronize(...)
+            Registry.observe(operation: 'Monitor#synchronize') { super }
+          end
+        end
+
+        module MonitorMixinHook
+          def synchronize(...)
+            Registry.observe(operation: 'MonitorMixin#synchronize') { super }
+          end
+        end
+
+        module_function
+
+        def install!(registry)
+          registry.prepend_once(Mutex, MutexHook)
+          registry.prepend_once(ConditionVariable, ConditionVariableHook) if defined?(ConditionVariable)
+          registry.prepend_once(Monitor, MonitorHook) if defined?(Monitor)
+          registry.prepend_once(MonitorMixin, MonitorMixinHook) if defined?(MonitorMixin)
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/probes/thread_state.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  module Runtime
+    module Probes
+      module ThreadState
+        module Hook
+          def thread_variable_get(...)
+            Registry.observe(operation: 'Thread.thread_variable_get') { super }
+          end
+
+          def thread_variable_set(...)
+            Registry.observe(operation: 'Thread.thread_variable_set') { super }
+          end
+
+          def [](...)
+            return super unless equal?(Thread.current)
+
+            Registry.observe(operation: 'Thread.current.[]') { super }
+          end
+
+          def []=(...)
+            if equal?(Thread.current)
+              Registry.observe(operation: 'Thread.current.[]=') { super }
+            else
+              super
+            end
+          end
+        end
+
+        module_function
+
+        def install!(registry)
+          registry.prepend_once(Thread, Hook)
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/runtime/probes/thread_wait.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  module Runtime
+    module Probes
+      module ThreadWait
+        module Hook
+          def join(...)
+            Registry.observe(operation: 'Thread.join') { super }
+          end
+
+          def value(...)
+            Registry.observe(operation: 'Thread.value') { super }
+          end
+        end
+
+        module_function
+
+        def install!(registry)
+          registry.prepend_once(Thread, Hook)
+        end
+      end
+    end
+  end
+end