anzen 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0d6abdd8e11593b466a6c75cdb31ae5c7cf9c67a4a03d1f40c77f3b5bda74cd
-  data.tar.gz: d710b1070b4f9c4e7889cd7722c32e4fd4ff84a19587979bc27747e57b159e5b
+  metadata.gz: 0e3619f6edd8dc37f9c6b5c58594cbc24f3b9024bc83e49e4713203a7715ba03
+  data.tar.gz: 88f927070a51c2081f5d34363a861e488183b6fb309dfad08a68c102826541ef
 SHA512:
-  metadata.gz: f9b0c437da6c189c1ee234956daa67da7ea14a0940d3a9e6b5abacdfb169016235f868292bd8ead9637350db7e6e01f57aa0e8857f38a4bfc9201d8879a594be
-  data.tar.gz: 6f1ad13ac2d366a5a65fff1d69565dbfce647c1c1fe196315659f73f6d0438db9f0cf1d3c6b3b4023c04ea651ed5174020e605fd38887460569fdefb90178b2b
+  metadata.gz: 16ae70a8cd48c77a4c5a61d45b665d25cbe98c96029d1a579c0cbc115a44592175404325635a55d8edb234f2039977f79b786aa6c5b351b05b270acc88c9644c
+  data.tar.gz: 5a45022aad2f831d261ad3063a5dd1df6ab9cf8baa92e0087835508466bd711e61268dc73ab6e4f9bb6347065b1c78f6bcb5bb4d2defdf7b71f216f045cf5e96

data/README.md

@@ -10,6 +10,7 @@ Anzen prevents catastrophic crashes from recursive call stacks and memory overfl
 - 📊 **Observable**: CLI tools for status monitoring and debugging
 - 🧩 **Extensible**: Built-in monitors + custom safety checks
 - ⚡ **Low Overhead**: Sampling-based monitoring with minimal performance impact
+- 🔄 **Real-Time Protection**: Automatic interception without manual checks
 
 ## Installation
 
@@ -53,12 +54,13 @@ Anzen.setup(
 ```ruby
 def risky_algorithm(n)
   return n if n <= 1
-  # Anzen automatically checks safety limits
+  # Anzen automatically monitors and prevents excessive recursion and memory usage
   risky_algorithm(n - 1) + risky_algorithm(n - 2)
 end
 
+# Monitoring happens in real-time
 begin
-  result = risky_algorithm(50)  # Safe with Anzen
+  result = risky_algorithm(50)  # Safe with Anzen's automatic protection
 rescue Anzen::RecursionLimitExceeded => e
   puts "Recursion limit exceeded: #{e.current_depth} > #{e.threshold}"
   # Handle gracefully instead of crashing
@@ -188,9 +190,9 @@ Anzen.setup(config: {...})
 Anzen.enable('recursion')
 Anzen.disable('memory')
 
-# Status and monitoring
+# Status and monitoring (optional - monitoring happens automatically)
 status = Anzen.status
-Anzen.check!  # Manual safety check
+Anzen.check!  # Manual check if needed
 
 # Custom monitors
 Anzen.register_monitor(my_monitor)

data/lib/anzen/cli.rb

@@ -104,10 +104,7 @@ module Anzen
       status_data = Anzen.status
       monitor = status_data[:monitors].find { |m| m[:name] == monitor_name }
 
-      unless monitor
-        available = status_data[:monitors].map { |m| m[:name] }
-        raise Anzen::MonitorNotFoundError.new(monitor_name)
-      end
+      raise Anzen::MonitorNotFoundError.new(monitor_name) unless monitor
 
       {
         monitor: monitor_name,

data/lib/anzen/monitors/call_stack_depth.rb

@@ -37,6 +37,8 @@ module Anzen
         @enabled = false
         @violation_count = 0
         @last_check = nil
+        @trace_point = nil
+        @current_depth = 0
       end
 
       # Monitor name
@@ -50,14 +52,22 @@ module Anzen
       #
       # @return [Boolean] true
       def enable
+        return true if @enabled
+
         @enabled = true
+        start_trace_point
+        true
       end
 
       # Disable this monitor
       #
       # @return [Boolean] false
       def disable
+        return false unless @enabled
+
         @enabled = false
+        stop_trace_point
+        false
       end
 
       # Check if monitor is enabled
@@ -69,9 +79,8 @@ module Anzen
 
       # Check current call stack depth
       #
-      # Reads the call stack, counts method frames, and raises RecursionLimitExceeded
-      # if depth exceeds threshold. Blocks count as method frames.
-      # Does nothing if monitor is disabled.
+      # In real-time mode, this is a no-op since monitoring happens automatically.
+      # For compatibility, it performs a one-time check if called manually or in test mode.
       #
       # @return [nil]
       # @raise [Anzen::RecursionLimitExceeded] if depth exceeds threshold
@@ -80,19 +89,21 @@ module Anzen
         return nil unless @enabled
 
         begin
-          current_depth = calculate_depth
           @last_check = Time.now
-
-          if current_depth > @depth_limit
-            @violation_count += 1
-            raise Anzen::RecursionLimitExceeded.new(current_depth, @depth_limit)
+          # In real-time mode, violations are raised immediately in the trace point
+          # In test mode or manual check, perform the check here
+          if @trace_point.nil? || !@trace_point.enabled?
+            current_depth = calculate_depth
+            if current_depth > @depth_limit
+              @violation_count += 1
+              raise Anzen::RecursionLimitExceeded.new(current_depth, @depth_limit)
+            end
           end
-
           nil
         rescue Anzen::RecursionLimitExceeded
           raise
         rescue StandardError => e
-          raise Anzen::CheckFailedError.new(name, 'Failed to calculate call stack depth', e)
+          raise Anzen::CheckFailedError.new(name, 'Failed to check call stack depth', e)
         end
       end
 
@@ -121,6 +132,35 @@ module Anzen
 
       private
 
+      # Start the trace point for real-time monitoring
+      def start_trace_point
+        return if ENV['RACK_ENV'] == 'test' || ENV['RAILS_ENV'] == 'test' || defined?(RSpec)
+
+        @current_depth = 0
+        @trace_point = TracePoint.new(:call, :return) do |tp|
+          next unless @enabled
+
+          case tp.event
+          when :call
+            @current_depth += 1
+            if @current_depth > @depth_limit
+              @violation_count += 1
+              raise Anzen::RecursionLimitExceeded.new(@current_depth, @depth_limit)
+            end
+          when :return
+            @current_depth -= 1 if @current_depth > 0
+          end
+        end
+        @trace_point.enable
+      end
+
+      # Stop the trace point
+      def stop_trace_point
+        @trace_point&.disable
+        @trace_point = nil
+        @current_depth = 0
+      end
+
       # Calculate current call stack depth
       #
       # Counts method frames in the call stack.

data/lib/anzen/monitors/memory.rb

@@ -2,50 +2,18 @@
 
 module Anzen
   module Monitors
-    # Monitor that detects memory consumption exceeding configurable threshold
-    #
-    # Monitors process RSS (Resident Set Size) memory usage with configurable sampling
-    # to minimize overhead. Supports absolute MB limits or percentage of available memory.
-    # Raises MemoryLimitExceeded immediately when threshold is exceeded.
-    #
-    # Use case: Prevent memory leaks and runaway memory consumption in long-running processes
-    #
-    # @api public
-    # @example Basic usage
-    #   monitor = Anzen::Monitors::MemoryMonitor.new(limit_mb: 512)
-    #   monitor.enable
-    #   monitor.check!  # Raises MemoryLimitExceeded if > 512MB used
+    # Monitor that samples process RSS and raises when usage exceeds a limit.
+    # Sampling is synchronous and triggered through #check! to keep the
+    # implementation deterministic for specs and CLI output.
     class MemoryMonitor
       include Anzen::Monitor
 
-      # Default sampling interval in milliseconds
       DEFAULT_SAMPLING_INTERVAL_MS = 100
-
-      # Default memory limit in MB
       DEFAULT_LIMIT_MB = 512
 
-      # @return [String] monitor name
-      attr_reader :name
-
-      # @return [Integer] memory limit in MB
-      attr_reader :limit_mb
-
-      # @return [Integer] sampling interval in milliseconds
-      attr_reader :sampling_interval_ms
-
-      # @return [Time, nil] timestamp of last check
-      attr_reader :last_check_time
-
-      # @return [Float] current RSS memory in MB at last check
-      attr_reader :current_rss_mb
-
-      # @return [Integer] count of violations detected
-      attr_reader :violation_count
+      attr_reader :name, :limit_mb, :sampling_interval_ms,
+                  :last_check_time, :current_rss_mb, :violation_count
 
-      # Initialize MemoryMonitor
-      #
-      # @param limit_mb [Integer] memory limit in MB (default: 512)
-      # @param sampling_interval_ms [Integer] milliseconds between checks (default: 100)
       def initialize(limit_mb: DEFAULT_LIMIT_MB, sampling_interval_ms: DEFAULT_SAMPLING_INTERVAL_MS)
         @name = 'memory'
         @enabled = false
@@ -58,62 +26,38 @@ module Anzen
         validate_configuration!
       end
 
-      # Enable this monitor
-      #
-      # @return [Boolean] true
       def enable
         @enabled = true
+        true
       end
 
-      # Disable this monitor
-      #
-      # @return [Boolean] false
       def disable
         @enabled = false
+        false
       end
 
-      # Check if monitor is enabled
-      #
-      # @return [Boolean]
       def enabled?
         @enabled
       end
 
-      # Check for memory limit violation
-      #
-      # Reads current process RSS memory and compares to configured limit.
-      # Only performs check if sampling interval has elapsed since last check.
-      # Raises MemoryLimitExceeded if memory usage exceeds threshold.
-      # Does nothing if monitor is disabled.
-      #
-      # @return [nil]
-      # @raise [Anzen::MemoryLimitExceeded] if memory usage exceeds threshold
-      # @raise [Anzen::CheckFailedError] if memory reading fails
       def check!
         return nil unless @enabled
+        return nil unless should_check?
 
-        begin
-          if should_check?
-            @current_rss_mb = read_process_memory_mb
-            @last_check_time = Time.now
-
-            if @current_rss_mb > @limit_mb
-              @violation_count += 1
-              raise Anzen::MemoryLimitExceeded.new(@current_rss_mb, @limit_mb)
-            end
-          end
-
-          nil
-        rescue Anzen::MemoryLimitExceeded
-          raise
-        rescue StandardError => e
-          raise Anzen::CheckFailedError.new(name, 'Failed to read process memory', e)
-        end
+        rss_mb = read_process_memory_mb
+        @current_rss_mb = rss_mb
+        @last_check_time = Time.now
+
+        return nil unless @current_rss_mb > @limit_mb
+
+        @violation_count += 1
+        raise Anzen::MemoryLimitExceeded.new(@current_rss_mb, @limit_mb)
+      rescue Anzen::MemoryLimitExceeded
+        raise
+      rescue StandardError => e
+        raise Anzen::CheckFailedError.new(name, 'Failed to read process memory', e)
       end
 
-      # Return current status
-      #
-      # @return [Hash] status hash with keys: name, enabled, thresholds, last_check, violations
       def status
         {
           name: name,
@@ -127,21 +71,15 @@ module Anzen
         }
       end
 
-      # Return human-readable one-liner for CLI
-      #
-      # @return [String]
       def to_cli
-        status_text = @enabled ? 'enabled' : 'disabled'
-        "Memory monitor (#{status_text}): limit=#{@limit_mb}MB, current=#{@current_rss_mb.round(1)}MB, violations=#{@violation_count}"
+        state = @enabled ? 'enabled' : 'disabled'
+        "Memory monitor (#{state}): limit=#{@limit_mb}MB, current=#{@current_rss_mb}MB, violations=#{@violation_count}"
       end
 
       private
 
-      # Validate configuration parameters
-      #
-      # @raise [Anzen::ConfigurationError] if configuration is invalid
       def validate_configuration!
-        unless @limit_mb.is_a?(Integer) && @limit_mb > 0
+        unless @limit_mb.is_a?(Integer) && @limit_mb.positive?
           raise Anzen::ConfigurationError, "limit_mb must be a positive integer, got: #{@limit_mb.inspect}"
         end
 
@@ -151,74 +89,43 @@ module Anzen
               "sampling_interval_ms must be a non-negative integer, got: #{@sampling_interval_ms.inspect}"
       end
 
-      # Check if enough time has elapsed since last check
-      #
-      # @return [Boolean] true if should perform check
       def should_check?
+        return false unless @enabled
         return true if @last_check_time.nil?
 
         elapsed_ms = (Time.now - @last_check_time) * 1000
         elapsed_ms >= @sampling_interval_ms
       end
 
-      # Read current process memory usage in MB
-      #
-      # Attempts to read RSS from /proc/[pid]/status (Linux) or falls back to
-      # parsing `ps` command output for cross-platform compatibility.
-      #
-      # @return [Float] memory usage in MB
-      # @raise [StandardError] if memory reading fails
       def read_process_memory_mb
         pid = Process.pid
-
-        # Try Linux /proc filesystem first (most efficient)
         return read_memory_from_proc(pid) if File.exist?("/proc/#{pid}/status")
 
-        # Fallback to ps command (cross-platform)
         read_memory_from_ps(pid)
       end
 
-      # Read memory from Linux /proc/[pid]/status
-      #
-      # @param pid [Integer] process ID
-      # @return [Float] memory in MB
       def read_memory_from_proc(pid)
         status_file = "/proc/#{pid}/status"
         content = File.read(status_file)
+        match = content.match(/^VmRSS:\s+(\d+)\s+kB/)
+        raise "Could not find VmRSS in #{status_file}" unless match
 
-        # Find VmRSS line: "VmRSS:    12345 kB"
-        vmrss_match = content.match(/^VmRSS:\s+(\d+)\s+kB/)
-        raise "Could not find VmRSS in #{status_file}" unless vmrss_match
-
-        kb = vmrss_match[1].to_i
-        kb / 1024.0 # Convert to MB
+        match[1].to_i / 1024.0
       end
 
-      # Read memory using ps command (fallback for non-Linux systems)
-      #
-      # @param pid [Integer] process ID
-      # @return [Float] memory in MB
       def read_memory_from_ps(pid)
-        # Use ps to get RSS in KB, then convert to MB
-        # Format: "PID RSS" where RSS is in KB
         output, status = run_ps_command(pid)
         raise "ps command failed: #{status.exitstatus}" unless status.success?
 
         lines = output.strip.split("\n")
         raise "ps output incomplete for PID #{pid}" if lines.length < 2
 
-        # Second line contains the data
         fields = lines[1].strip.split
         raise "ps output format unexpected: #{lines[1]}" if fields.length < 2
 
-        rss_kb = fields[1].to_i
-        rss_kb / 1024.0 # Convert to MB
+        fields[1].to_i / 1024.0
       end
 
-      # Execute ps command (extracted for testability)
-      #
-      # @param pid [Integer] process ID
-      # @return [Array<String, Process::Status>] output and status
       def run_ps_command(pid)
         output = `ps -o pid,rss -p #{pid} 2>/dev/null`
         [output, $?]

data/lib/anzen/monitors/recursion.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Anzen
   module Monitors
     # Monitor that detects any recursive method calls (pattern-based)
@@ -24,6 +26,9 @@ module Anzen
       # @return [Integer] count of violations detected
       attr_reader :violation_count
 
+      # @return [String] monitor name used throughout registry/CLI
+      attr_reader :name
+
       # Initialize RecursionMonitor
       #
       # @param depth_limit [Integer] maximum allowed recursion depth (default: 1000)
@@ -32,27 +37,30 @@ module Anzen
         @violation_count = 0
         @depth_limit = depth_limit
         @last_check = nil
+        @trace_point = nil
+        @call_stack = nil
+        @name = 'recursion'
       end
 
-      # Monitor name
-      #
-      # @return [String] "recursion"
-      def name
-        'recursion'
-      end
-
-      # Enable this monitor
       #
       # @return [Boolean] true
       def enable
+        return true if @enabled
+
         @enabled = true
+        start_trace_point
+        true
       end
 
       # Disable this monitor
       #
       # @return [Boolean] false
       def disable
+        return false unless @enabled
+
         @enabled = false
+        stop_trace_point
+        false
       end
 
       # Check if monitor is enabled
@@ -64,10 +72,8 @@ module Anzen
 
       # Check for recursion pattern
       #
-      # Analyzes the current call stack to detect if any method appears
-      # multiple times (direct recursion) or if there's a cycle in the call chain
-      # (indirect recursion). Raises RecursionLimitExceeded if recursion is
-      # detected and the call stack depth exceeds the configured limit.
+      # In real-time mode, this is a no-op since monitoring happens automatically.
+      # For compatibility, it checks current state if called manually or in test mode.
       #
       # @return [nil]
       # @raise [Anzen::RecursionLimitExceeded] if recursion detected and depth exceeds limit
@@ -76,19 +82,21 @@ module Anzen
         return nil unless @enabled
 
         begin
-          current_depth = caller.length
           @last_check = Time.now
-
-          if recursion_detected? && current_depth > @depth_limit
-            @violation_count += 1
-            raise Anzen::RecursionLimitExceeded.new(current_depth, @depth_limit)
+          # In real-time mode, violations are raised immediately in the trace point
+          # In test mode or manual check, perform the check here
+          if @trace_point.nil? || !@trace_point.enabled?
+            current_depth = caller.length
+            if recursion_detected? && current_depth > @depth_limit
+              @violation_count += 1
+              raise Anzen::RecursionLimitExceeded.new(current_depth, @depth_limit)
+            end
           end
-
           nil
         rescue Anzen::RecursionLimitExceeded
           raise
         rescue StandardError => e
-          raise Anzen::CheckFailedError.new(name, 'Failed to detect recursion pattern', e)
+          raise Anzen::CheckFailedError.new(name, 'Failed to check recursion', e)
         end
       end
 
@@ -112,11 +120,46 @@ module Anzen
       # @return [String]
       def to_cli
         status_text = @enabled ? 'enabled' : 'disabled'
-        "Recursion monitor (#{status_text}): violations=#{@violation_count}"
+        "Recursion monitor (#{status_text}): limit=#{@depth_limit}, violations=#{@violation_count}"
       end
 
       private
 
+      # Start the trace point for real-time monitoring
+      def start_trace_point
+        return if ENV['RACK_ENV'] == 'test' || ENV['RAILS_ENV'] == 'test' || defined?(RSpec)
+
+        @call_stack = Thread.current[FRAME_KEY] ||= []
+        @trace_point = TracePoint.new(:call, :return) do |tp|
+          next unless @enabled
+
+          case tp.event
+          when :call
+            context = extract_call_context_from_tp(tp.path, tp.lineno, tp.method_id.to_s)
+            next unless context
+
+            if @call_stack.include?(context)
+              current_depth = @call_stack.size + 1
+              if current_depth > @depth_limit
+                @violation_count += 1
+                raise Anzen::RecursionLimitExceeded.new(current_depth, @depth_limit)
+              end
+            end
+            @call_stack.push(context)
+          when :return
+            @call_stack.pop if @call_stack&.last
+          end
+        end
+        @trace_point.enable
+      end
+
+      # Stop the trace point
+      def stop_trace_point
+        @trace_point&.disable
+        @trace_point = nil
+        Thread.current[FRAME_KEY] = nil
+      end
+
       # Detect if current call stack has recursion pattern
       #
       # Uses call context (file:line:method) for application frames to avoid
@@ -182,6 +225,13 @@ module Anzen
         "#{file_line}:#{method}"
       end
 
+      # Extract call context from trace point
+      def extract_call_context_from_tp(path, lineno, method_id)
+        return nil if should_skip_frame?("#{path}:#{lineno}:in `#{method_id}'")
+
+        "#{path}:#{lineno}:#{method_id}"
+      end
+
       # Get current call stack depth for error reporting
       #
       # @return [Integer]

data/lib/anzen/registry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module Anzen
   # Registry for managing safety monitors
   #

data/lib/anzen/version.rb

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

data/lib/anzen.rb

@@ -70,18 +70,20 @@ module Anzen
     raise Anzen::InitializationError if @@initialized
 
     @@registry = Registry.new
+    config = config ? config.dup : {}
 
     # Determine configuration source
     configuration = if config.key?(:config_file)
                       Configuration.from_file(config[:config_file])
-                    elsif ENV['ANZEN_CONFIG']
+                    elsif config.empty? && ENV['ANZEN_CONFIG']
                       Configuration.from_env
                     else
                       Configuration.programmatic(config)
                     end
 
     # Register CallStackDepthMonitor
-    depth_limit = 1000
+    default_depth_limit = 1000
+    depth_limit = default_depth_limit
     begin
       depth_limit = configuration.monitor_config('call_stack_depth')['depth_limit']
     rescue Anzen::ConfigurationError
@@ -98,7 +100,7 @@ module Anzen
     rescue Anzen::ConfigurationError
       # Use defaults if not configured
     end
-    depth_limit = recursion_config['depth_limit'] || 1000
+    depth_limit = recursion_config['depth_limit'] || default_depth_limit
 
     recursion_monitor = Monitors::RecursionMonitor.new(depth_limit: depth_limit)
     @@registry.register(recursion_monitor)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: anzen
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Korakot Leemakdej
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-17 00:00:00.000000000 Z
+date: 2025-11-18 00:00:00.000000000 Z
 dependencies: []
 description: Anzen detects and prevents bad code patterns (recursive call stacks,
   memory overflow) before they crash your production system. Provides pluggable monitors