fiber_audit 0.1.0 → 0.2.1

data/lib/fiber_audit/runtime/watchdog_policy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'validation'
+
+module FiberAudit
+  module Runtime
+    WatchdogPolicy = Data.define(
+      :enabled,
+      :heartbeat_interval_ms,
+      :stall_threshold_ms,
+      :max_frames
+    ) do
+      def initialize(**values)
+        unknown = values.keys - WatchdogPolicy::DEFAULTS.keys
+        raise RuntimeContractError, "unknown watchdog policy field: #{unknown.first}" unless unknown.empty?
+
+        fields = WatchdogPolicy::DEFAULTS.merge(values)
+        raise RuntimeContractError, 'enabled must be a Boolean' unless [true, false].include?(fields[:enabled])
+
+        limits = WatchdogPolicy::LIMITS.to_h do |name, range|
+          value = fields.fetch(name)
+          unless value.is_a?(Integer) && range.cover?(value)
+            raise RuntimeContractError, "#{name} must be an Integer in #{range}"
+          end
+
+          [name, value]
+        end
+
+        super(enabled: fields[:enabled], **limits)
+      end
+
+      def enabled?
+        enabled
+      end
+
+      def heartbeat_interval_ns
+        heartbeat_interval_ms * WatchdogPolicy::NANOSECONDS_PER_MILLISECOND
+      end
+
+      def stall_threshold_ns
+        stall_threshold_ms * WatchdogPolicy::NANOSECONDS_PER_MILLISECOND
+      end
+
+      def stalled?(age_ns:)
+        age = Validation.integer(age_ns, 'heartbeat age')
+        age > stall_threshold_ns
+      end
+    end
+
+    WatchdogPolicy.const_set(:NANOSECONDS_PER_MILLISECOND, 1_000_000)
+    WatchdogPolicy.const_set(:DEFAULTS, {
+      enabled: true,
+      heartbeat_interval_ms: 25,
+      stall_threshold_ms: 100,
+      max_frames: 20
+    }.freeze)
+    WatchdogPolicy.const_set(:LIMITS, {
+      heartbeat_interval_ms: 1..60_000,
+      stall_threshold_ms: 1..600_000,
+      max_frames: 0..100
+    }.freeze)
+    WatchdogPolicy.const_set(:DISABLED, WatchdogPolicy.new(enabled: false))
+  end
+end

data/lib/fiber_audit/runtime.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'errors'
+require_relative 'operation_vocabulary'
+require_relative 'execution_context'
+require_relative 'runtime/validation'
+require_relative 'runtime/policy'
+require_relative 'runtime/watchdog_policy'
+require_relative 'runtime/location'
+require_relative 'runtime/event'
+require_relative 'runtime/session'
+require_relative 'runtime/redactor'
+require_relative 'runtime/clock'
+require_relative 'runtime/sampler'
+require_relative 'runtime/limits'
+require_relative 'runtime/jsonl/schema'
+require_relative 'runtime/jsonl/writer'
+require_relative 'runtime/recorder'
+require_relative 'runtime/execution_context'
+require_relative 'runtime/rails_integration'
+require_relative 'runtime/environment'
+require_relative 'runtime/active_operations'
+require_relative 'runtime/heartbeat'
+require_relative 'runtime/watchdog'
+require_relative 'runtime/scheduler_observer'
+require_relative 'runtime/probes/base'
+require_relative 'runtime/probes/subprocess'
+require_relative 'runtime/probes/thread_wait'
+require_relative 'runtime/probes/synchronization'
+require_relative 'runtime/probes/thread_state'
+require_relative 'runtime/probes/io_select'
+require_relative 'runtime/probes/socket'
+require_relative 'runtime/probes/http'
+require_relative 'runtime/probes/registry'
+require_relative 'runtime/lifecycle'
+require_relative 'runtime/supervisor'

data/lib/fiber_audit/static/rules/blocking_subprocess.rb

@@ -4,6 +4,7 @@ require_relative 'base'
 require_relative '../../findings/evidence'
 require_relative '../../correlation/fingerprint'
 require_relative '../../findings/finding'
+require_relative '../../operation_vocabulary'
 
 module FiberAudit
   module Static
@@ -14,14 +15,8 @@ module FiberAudit
         default_confidence :high
         description 'Blocking subprocess call in the fiber scheduler path'
 
-        TARGETS = {
-          'Kernel' => %i[system exec spawn].freeze,
-          'Open3' => %i[capture2 capture2e capture3 pipeline].freeze,
-          'IO' => %i[popen].freeze,
-          'Process' => %i[waitall detach].freeze
-        }.freeze
-
-        BARE_KERNEL_METHODS = %i[system exec spawn].freeze
+        TARGETS = OperationVocabulary::FA1001_TARGETS
+        BARE_KERNEL_METHODS = OperationVocabulary::FA1001_KERNEL_METHODS
 
         MESSAGE = 'Subprocess operation may block the thread running the fiber scheduler.'
         REMEDIATION = 'Move long-running subprocess work outside the request path, or verify scheduler behaviour under load.'

data/lib/fiber_audit/static/rules/direct_socket.rb

@@ -4,6 +4,7 @@ require_relative 'base'
 require_relative '../../findings/evidence'
 require_relative '../../correlation/fingerprint'
 require_relative '../../findings/finding'
+require_relative '../../operation_vocabulary'
 
 module FiberAudit
   module Static
@@ -19,9 +20,7 @@ module FiberAudit
         TITLE    = 'Direct socket creation'
         CATEGORY = :network
 
-        EXACT = %w[
-          TCPSocket TCPServer UDPSocket UNIXSocket UNIXServer Socket IPSocket
-        ].freeze
+        EXACT = OperationVocabulary::FA1006_EXACT
 
         MESSAGE = 'Direct socket use may bypass scheduler-aware networking ' \
                   'and block the scheduler thread.'

data/lib/fiber_audit/static/rules/io_select.rb

@@ -4,6 +4,7 @@ require_relative 'base'
 require_relative '../../findings/evidence'
 require_relative '../../correlation/fingerprint'
 require_relative '../../findings/finding'
+require_relative '../../operation_vocabulary'
 
 module FiberAudit
   module Static
@@ -22,10 +23,7 @@ module FiberAudit
         MESSAGE = 'IO.select may bypass scheduler-aware I/O and block the thread running the fiber scheduler.'
         REMEDIATION = 'Use scheduler-aware I/O APIs or allow the active Fiber scheduler to manage readiness.'
 
-        TARGETS = {
-          'IO' => :select,
-          'Kernel' => :select
-        }.freeze
+        TARGETS = OperationVocabulary::FA1005_TARGETS
 
         class << self
           def title = TITLE

data/lib/fiber_audit/static/rules/net_http_in_request.rb

@@ -4,6 +4,7 @@ require_relative 'base'
 require_relative '../../findings/evidence'
 require_relative '../../correlation/fingerprint'
 require_relative '../../findings/finding'
+require_relative '../../operation_vocabulary'
 
 module FiberAudit
   module Static
@@ -22,11 +23,8 @@ module FiberAudit
         MESSAGE = 'Synchronous HTTP activity in a request-like context may block the thread running the fiber scheduler.'
         REMEDIATION = 'Use a scheduler-aware HTTP client, or move outbound HTTP work outside the request path.'
 
-        NET_HTTP_METHODS = %i[get get_response start request].freeze
-        URI_METHODS = {
-          'URI' => :open,
-          'OpenURI' => :open_uri
-        }.freeze
+        NET_HTTP_METHODS = OperationVocabulary::FA1007_NET_HTTP_METHODS
+        URI_METHODS = OperationVocabulary::FA1007_URI_METHODS
         EMIT_CONTEXTS = %i[request middleware websocket callback].freeze
 
         def analyze(call_sites:)

data/lib/fiber_audit/static/rules/synchronization.rb

@@ -4,6 +4,7 @@ require_relative 'base'
 require_relative '../../findings/evidence'
 require_relative '../../correlation/fingerprint'
 require_relative '../../findings/finding'
+require_relative '../../operation_vocabulary'
 
 module FiberAudit
   module Static
@@ -16,12 +17,7 @@ module FiberAudit
 
         RULE_TITLE = 'Thread synchronization'
         RULE_CATEGORY = :synchronization
-        TARGETS = {
-          'Mutex' => %i[lock synchronize try_lock],
-          'ConditionVariable' => %i[wait],
-          'Monitor' => %i[synchronize],
-          'MonitorMixin' => %i[synchronize]
-        }.freeze
+        TARGETS = OperationVocabulary::FA1003_TARGETS
         TRY_LOCK_MSG = 'Mutex.try_lock is non-blocking but may indicate ' \
                        'thread-oriented synchronization in fiber-scheduled code.'
         NORMAL_MSG = 'Synchronization operation may block the thread running the fiber scheduler.'

data/lib/fiber_audit/static/rules/thread_current_state.rb

@@ -4,6 +4,7 @@ require_relative 'base'
 require_relative '../../findings/evidence'
 require_relative '../../correlation/fingerprint'
 require_relative '../../findings/finding'
+require_relative '../../operation_vocabulary'
 
 module FiberAudit
   module Static
@@ -20,8 +21,8 @@ module FiberAudit
         MESSAGE = 'Thread-local state may be shared across fibers and leak request-local data.'
         REMEDIATION = 'Use fiber-local or framework-provided request-local state instead of Thread thread variables.'
 
-        THREAD_VARIABLE_METHODS = %i[thread_variable_get thread_variable_set].freeze
-        INDEX_METHODS = %i[[] []=].freeze
+        THREAD_VARIABLE_METHODS = OperationVocabulary::FA1004_THREAD_VARIABLE_METHODS
+        INDEX_METHODS = OperationVocabulary::FA1004_INDEX_METHODS
 
         def analyze(call_sites:)
           findings = []

data/lib/fiber_audit/static/rules/thread_join.rb

@@ -4,6 +4,7 @@ require_relative 'base'
 require_relative '../../findings/evidence'
 require_relative '../../correlation/fingerprint'
 require_relative '../../findings/finding'
+require_relative '../../operation_vocabulary'
 
 module FiberAudit
   module Static
@@ -30,8 +31,8 @@ module FiberAudit
         MESSAGE  = 'Waiting for a thread may block the thread running the fiber scheduler.'
         REMEDIATION = 'Replace thread waits with scheduler-aware coordination, ' \
                       'or move the work outside the fiber-scheduled path.'
-        TARGET_METHODS  = %i[join value].freeze
-        CANONICAL_OPS   = %w[Thread.join Thread.value].freeze
+        TARGET_METHODS  = OperationVocabulary::FA1002_METHODS
+        CANONICAL_OPS   = OperationVocabulary::FA1002_OPERATIONS
         DIRECT_CLASS_SOURCE = 'Thread'
 
         def analyze(call_sites:)

data/lib/fiber_audit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FiberAudit
-  VERSION = '0.1.0'
+  VERSION = '0.2.1'
 end

data/lib/fiber_audit.rb

@@ -9,6 +9,7 @@ require_relative 'fiber_audit/findings/evidence'
 require_relative 'fiber_audit/correlation/fingerprint'
 require_relative 'fiber_audit/findings/finding'
 require_relative 'fiber_audit/findings/collection'
+require_relative 'fiber_audit/runtime'
 require_relative 'fiber_audit/configuration'
 require_relative 'fiber_audit/suppressions/parser'
 require_relative 'fiber_audit/suppressions/store'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiber_audit
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - FiberAudit Contributors
@@ -43,7 +43,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".fiber-audit.example.yml"
+- ARCHITECTURE.md
 - CHANGELOG.md
+- LICENSE
 - README.md
 - bin/fiber-audit
 - lib/fiber_audit.rb
@@ -59,11 +61,45 @@ files:
 - lib/fiber_audit/findings/finding.rb
 - lib/fiber_audit/findings/location.rb
 - lib/fiber_audit/findings/severity.rb
+- lib/fiber_audit/operation_vocabulary.rb
 - lib/fiber_audit/project.rb
 - lib/fiber_audit/reporters/base.rb
 - lib/fiber_audit/reporters/json.rb
 - lib/fiber_audit/reporters/schema.rb
 - lib/fiber_audit/reporters/text.rb
+- lib/fiber_audit/runtime.rb
+- lib/fiber_audit/runtime/active_operations.rb
+- lib/fiber_audit/runtime/boot.rb
+- lib/fiber_audit/runtime/clock.rb
+- lib/fiber_audit/runtime/environment.rb
+- lib/fiber_audit/runtime/event.rb
+- lib/fiber_audit/runtime/execution_context.rb
+- lib/fiber_audit/runtime/heartbeat.rb
+- lib/fiber_audit/runtime/jsonl/schema.rb
+- lib/fiber_audit/runtime/jsonl/writer.rb
+- lib/fiber_audit/runtime/lifecycle.rb
+- lib/fiber_audit/runtime/limits.rb
+- lib/fiber_audit/runtime/location.rb
+- lib/fiber_audit/runtime/policy.rb
+- lib/fiber_audit/runtime/probes/base.rb
+- lib/fiber_audit/runtime/probes/http.rb
+- lib/fiber_audit/runtime/probes/io_select.rb
+- lib/fiber_audit/runtime/probes/registry.rb
+- lib/fiber_audit/runtime/probes/socket.rb
+- lib/fiber_audit/runtime/probes/subprocess.rb
+- lib/fiber_audit/runtime/probes/synchronization.rb
+- lib/fiber_audit/runtime/probes/thread_state.rb
+- lib/fiber_audit/runtime/probes/thread_wait.rb
+- lib/fiber_audit/runtime/rails_integration.rb
+- lib/fiber_audit/runtime/recorder.rb
+- lib/fiber_audit/runtime/redactor.rb
+- lib/fiber_audit/runtime/sampler.rb
+- lib/fiber_audit/runtime/scheduler_observer.rb
+- lib/fiber_audit/runtime/session.rb
+- lib/fiber_audit/runtime/supervisor.rb
+- lib/fiber_audit/runtime/validation.rb
+- lib/fiber_audit/runtime/watchdog.rb
+- lib/fiber_audit/runtime/watchdog_policy.rb
 - lib/fiber_audit/static/call_site.rb
 - lib/fiber_audit/static/call_site_extractor.rb
 - lib/fiber_audit/static/execution_context_resolver.rb
@@ -104,5 +140,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Static fiber-scheduler compatibility auditor for Ruby and Rails applications
+summary: Static and observational runtime fiber-scheduler auditor for Ruby and Rails
 test_files: []