seigen_watchdog 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a2a0a72ac34884493eebe4d7e9fe04e845136f0498408d0fc70dba907d9d54d9
+  data.tar.gz: ebcd461562d6755b976697096b2aff15c884278ecf075e63f8f505099f1412c9
+SHA512:
+  metadata.gz: 3d4680614a457b4f74ce4958be27fe78b200a82e8f2cdb9b9207895e87fd49508ec982de39824c7702dba23a98448900b90f7dc569efde236b53a344334ccfe2
+  data.tar.gz: c64475ed1f9dc7b19bb9e581518798ed4b0b78bcb647f64b4defa44ddf6b3a7636a25f4d736f92ca49d4af538ccaf293327886c207df5f7cbe9cd162a02a3448

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,47 @@
+plugins:
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.3
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'spec/**/*.rb'
+    - 'lib/seigen_watchdog/monitor.rb'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Metrics/ClassLength:
+  Max: 200
+
+Metrics/ParameterLists:
+  CountKeywordArgs: false
+
+Layout/LeadingCommentSpace:
+  AllowRBSInlineAnnotation: true
+
+RSpec/NamedSubject:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/ExampleLength:
+  Enabled: false

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# 0.1.0
+- initial release with basic functionality:
+  - RSS memory limiter
+  - Execution time limiter
+  - Iteration count limiter
+  - Custom condition limiter
+  - Signal-based killer strategy
+  - Threadsafe background watchdog
+  - Configurable check interval
+  - Optional logging and exception handling
+# 0.2.0
+- store limiters as Hash, access specific limiter by it's name, for ex. `monitor.limiter(:rss)`
+- counter limiter all init, increment/decrement, and reset with specified value
+# 0.3.0
+- monitor prevents multiple kill calls (only calls `killer.kill!` once even if limiters continue to be exceeded)
+- added `killed?` method to check if killer was invoked
+- added `seconds_since_killed` method to track time elapsed since kill
+- `before_kill` callback now receives limiter name and limiter instance: `->(name, limiter)`
+- limiter keys are now standardized to Symbol type

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Denis Talakevich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,238 @@
+# SeigenWatchdog
+
+Seigen (制限 — “limit, restriction”).
+
+Monitors and gracefully terminates a Ruby application based on configurable memory usage, execution time, iteration count, or custom conditions. Threadsafe and easy to integrate.
+
+How it works:
+After setting up SeigenWatchdog with desired limiters and a killer strategy, it spawns a background thread that periodically checks the defined conditions. If any limiter exceeds its threshold, the specified killer strategy is invoked to terminate the application gracefully.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add seigen_watchdog
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install seigen_watchdog
+```
+
+## Requirements
+
+- Ruby >= 3.3.0
+- Dependencies:
+  - `get_process_mem` - for RSS memory monitoring
+  - `logger` - for optional debug logging
+
+## Usage
+
+```ruby
+require 'seigen_watchdog'
+
+SeigenWatchdog.start(
+ check_interval: 5, # seconds or nil for no periodic checks
+ killer: SeigenWatchdog::Killers::Signal.new(signal: 'INT'),
+ limiters: {
+    rss: SeigenWatchdog::Limiters::RSS.new(max_rss: 200 * 1024 * 1024), # 200 MB
+    time: SeigenWatchdog::Limiters::Time.new(max_duration: 24 * 60 * 60), # 24 hours
+    jobs: SeigenWatchdog::Limiters::Counter.new(max_count: 1_000_000), # 1 million iterations
+    custom: SeigenWatchdog::Limiters::Custom.new(checker: -> { SomeCondition.met? }) # custom condition
+ },
+ logger: Logger.new($stdout), # optional logger, logs DEBUG for each check, INFO when killer is invoked
+ on_exception: ->(e) { Sentry.capture_exception(e) }, # optional exception handler
+ before_kill: ->(name, limiter) { Prometheus::KillInstrument.send_metrics(name, limiter.class.name) } # optional callback before kill
+)
+
+# to increment particular count limiter
+SeigenWatchdog.monitor.limiter(:jobs).increment # increment by 1
+SeigenWatchdog.monitor.limiter(:jobs).increment(5) # increment by 5
+
+# to perform check manually (if check_interval is nil)
+SeigenWatchdog.monitor.check_once
+
+# to stop the watchdog
+SeigenWatchdog.stop
+
+# to check if watchdog is running
+SeigenWatchdog.started? # => true or false
+```
+
+## API Reference
+
+### Module Methods
+
+#### `SeigenWatchdog.start(check_interval:, killer:, limiters:, logger: nil, on_exception: nil, before_kill: nil)`
+Starts the watchdog monitor with the specified configuration.
+
+**Parameters:**
+- `check_interval` - Interval in seconds between checks, or `nil` for manual checks only
+- `killer` - Killer strategy instance (e.g., `SeigenWatchdog::Killers::Signal.new(signal: 'INT')`)
+- `limiters` - Hash of limiter instances (keys are limiter names, values are limiter instances)
+- `logger` - Optional logger instance for debug/info logging
+- `on_exception` - Optional callback proc for exception handling (receives exception as argument)
+- `before_kill` - Optional callback proc invoked before killing (receives limiter name and limiter instance as arguments)
+
+**Returns:** Monitor instance
+
+#### `SeigenWatchdog.stop`
+Stops the watchdog monitor and terminates the background thread.
+
+#### `SeigenWatchdog.started?`
+Returns `true` if the watchdog is currently running, `false` otherwise.
+
+#### `SeigenWatchdog.monitor`
+Returns the current monitor instance, or `nil` if not started.
+
+### Monitor Instance Methods
+
+#### `monitor.check_once`
+Performs a single manual check of all limiters. Useful when `check_interval` is `nil`.
+
+**Returns:** `true` if a limit was exceeded and killer was invoked, `false` otherwise.
+
+#### `monitor.limiter(name)`
+Returns a limiter instance by its name.
+
+**Parameters:**
+- `name` - Symbol or String name of the limiter
+
+**Returns:** Limiter instance
+
+**Raises:** `KeyError` if limiter with the given name doesn't exist
+
+#### `monitor.limiters`
+Returns a hash of all limiters. Modifications to the returned hash won't affect internal state, but limiter instances are shared.
+
+**Returns:** Hash of limiters (keys are names, values are limiter instances)
+
+#### `monitor.killed?`
+Returns whether the killer has been invoked.
+
+**Returns:** `true` if killer was invoked, `false` otherwise.
+
+#### `monitor.seconds_since_killed`
+Returns the number of seconds elapsed since the killer was invoked.
+
+**Returns:** Float representing seconds since kill, or `nil` if killer has not been invoked.
+
+#### `monitor.seconds_after_last_check`
+Returns the number of seconds elapsed since the last check was performed.
+
+**Returns:** Float representing seconds since last check, or `nil` if no check has been performed.
+
+### Limiters
+
+#### `SeigenWatchdog::Limiters::RSS.new(max_rss:)`
+Monitors RSS (Resident Set Size) memory usage.
+- `max_rss` - Maximum RSS in bytes
+
+#### `SeigenWatchdog::Limiters::Time.new(max_duration:)`
+Monitors execution time since limiter creation.
+- `max_duration` - Maximum duration in seconds
+
+#### `SeigenWatchdog::Limiters::Counter.new(max_count:, initial: 0)`
+Monitors iteration count with manual incrementing.
+- `max_count` - Maximum count before exceeding
+- `initial` - Initial counter value (default: 0)
+
+**Instance Methods:**
+- `increment(count = 1)` - Increments the counter by the specified amount (default: 1)
+- `decrement(count = 1)` - Decrements the counter by the specified amount (default: 1)
+- `reset(initial = 0)` - Resets the counter to the specified value (default: 0)
+
+**Usage:**
+```ruby
+# Access counter limiter via monitor
+counter = SeigenWatchdog.monitor.limiter(:jobs)
+counter.increment      # increment by 1
+counter.increment(5)   # increment by 5
+counter.decrement      # decrement by 1
+counter.decrement(3)   # decrement by 3
+counter.reset          # reset to 0
+counter.reset(10)      # reset to 10
+
+# Create counter with custom initial value
+SeigenWatchdog::Limiters::Counter.new(max_count: 100, initial: 50)
+# Counter starts at 50, will exceed at 100
+```
+
+#### `SeigenWatchdog::Limiters::Custom.new(checker:)`
+Custom condition limiter using a proc.
+- `checker` - Proc that returns `true` when limit is exceeded
+
+### Killers
+
+#### `SeigenWatchdog::Killers::Signal.new(signal:)`
+Terminates the process by sending a signal.
+- `signal` - Signal name as string or symbol (e.g., `'INT'`, `:TERM`)
+
+## Callbacks
+
+### `before_kill` Callback
+
+The `before_kill` callback is invoked immediately before the killer strategy is executed when a limiter exceeds its threshold. This allows you to perform cleanup operations, send metrics, or log information about which limit was exceeded.
+
+**Callback signature:**
+```ruby
+->(name, limiter) { ... }
+```
+
+**Arguments:**
+- `name` - Symbol representing the limiter name (e.g., `:rss`, `:time`, `:jobs`)
+- `limiter` - The limiter instance that exceeded its threshold
+
+**Example use cases:**
+```ruby
+# Send metrics to monitoring system
+before_kill: ->(name, limiter) {
+  Prometheus::KillInstrument.send_metrics(name, limiter.class.name)
+}
+
+# Log detailed information with limiter name
+before_kill: ->(name, limiter) {
+  Rails.logger.warn("Process killed due to #{name} (#{limiter.class.name}) limit exceeded")
+}
+
+# Send alert with limiter name
+before_kill: ->(name, limiter) {
+  Sentry.capture_message("Watchdog killing process: #{name}")
+}
+
+# Perform cleanup based on limiter type
+before_kill: ->(name, limiter) {
+  case limiter
+  when SeigenWatchdog::Limiters::RSS
+    Rails.logger.warn("Memory limit exceeded (#{name}): #{limiter.max_rss / 1024 / 1024} MB")
+  when SeigenWatchdog::Limiters::Time
+    Rails.logger.warn("Time limit exceeded (#{name}): #{limiter.max_duration} seconds")
+  end
+}
+```
+
+**Exception handling:**
+If the `before_kill` callback raises an exception, it will be handled by the `on_exception` callback (if provided) and the killer will still be invoked to ensure the process terminates as expected.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+
+Generate sig using the following command:
+
+```bash
+bundle exec rbs-inline --opt-out --output=sig lib
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/senid231/seigen_watchdog.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported Versions
+
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.x.x   | :white_check_mark: |
+
+## Reporting a Vulnerability
+
+Report vulnerability to issues

data/lib/seigen_watchdog/killers/base.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module SeigenWatchdog
+  module Killers
+    # Base class for all killers
+    class Base
+      # @rbs return: void
+      def kill!
+        raise NotImplementedError, "#{self.class} must implement #kill!"
+      end
+    end
+  end
+end

data/lib/seigen_watchdog/killers/signal.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SeigenWatchdog
+  module Killers
+    # Killer that sends a signal to the current process
+    class Signal < Base
+      # @rbs @signal: String
+
+      attr_reader :signal #: String
+
+      # @rbs signal: String | Symbol
+      # @rbs return: void
+      def initialize(signal:)
+        super()
+        @signal = signal.to_s
+      end
+
+      # Sends the signal to the current process
+      # @rbs return: void
+      def kill!
+        Process.kill(@signal, Process.pid)
+      end
+    end
+  end
+end

data/lib/seigen_watchdog/limiters/base.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SeigenWatchdog
+  module Limiters
+    # Base class for all limiters
+    class Base
+      # @rbs return: bool
+      def exceeded?
+        raise NotImplementedError, "#{self.class} must implement #exceeded?"
+      end
+
+      # Called when the limiter is started (when monitor initializes)
+      # @rbs return: void
+      def started; end
+
+      # Called when the limiter is stopped (when monitor stops)
+      # @rbs return: void
+      def stopped; end
+    end
+  end
+end

data/lib/seigen_watchdog/limiters/counter.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SeigenWatchdog
+  module Limiters
+    # Limiter based on iteration count
+    class Counter < Base
+      # @rbs @max_count: Integer
+      # @rbs @count: Integer
+      # @rbs @mutex: Thread::Mutex
+
+      attr_reader :max_count #: Integer
+
+      # @rbs max_count: Integer
+      # @rbs initial: Integer
+      # @rbs return: void
+      def initialize(max_count:, initial: 0)
+        super()
+        @max_count = max_count
+        @count = initial
+        @mutex = Mutex.new
+      end
+
+      # Increments the counter by the specified amount
+      # @rbs count: Integer
+      # @rbs return: void
+      def increment(count = 1)
+        @mutex.synchronize { @count += count }
+      end
+
+      # Decrements the counter by the specified amount
+      # @rbs count: Integer
+      # @rbs return: void
+      def decrement(count = 1)
+        @mutex.synchronize { @count -= count }
+      end
+
+      # Resets the counter to the specified initial value
+      # @rbs initial: Integer
+      # @rbs return: void
+      def reset(initial = 0)
+        @mutex.synchronize { @count = initial }
+      end
+
+      # @rbs return: bool
+      def exceeded?
+        @mutex.synchronize { @count >= @max_count }
+      end
+    end
+  end
+end

data/lib/seigen_watchdog/limiters/custom.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module SeigenWatchdog
+  module Limiters
+    # Limiter based on a custom checker lambda
+    class Custom < Base
+      # @rbs @checker: Proc | #call
+      # @rbs checker: Proc | #call
+      # @rbs return: void
+      def initialize(checker:)
+        super()
+        @checker = checker
+      end
+
+      # @rbs return: bool
+      def exceeded?
+        @checker.call
+      end
+    end
+  end
+end

data/lib/seigen_watchdog/limiters/rss.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'get_process_mem'
+
+module SeigenWatchdog
+  module Limiters
+    # Limiter based on RSS memory usage
+    class RSS < Base
+      # @rbs @max_rss: Integer
+      # @rbs @mem: GetProcessMem
+
+      attr_reader :max_rss #: Integer
+
+      # @rbs max_rss: Integer
+      # @rbs return: void
+      def initialize(max_rss:)
+        super()
+        @max_rss = max_rss
+        @mem = GetProcessMem.new
+      end
+
+      # @rbs return: bool
+      def exceeded?
+        @mem.bytes >= @max_rss
+      end
+    end
+  end
+end

data/lib/seigen_watchdog/limiters/time.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module SeigenWatchdog
+  module Limiters
+    # Limiter based on execution time
+    class Time < Base
+      # @rbs @max_duration: Numeric
+      # @rbs @start_time: Float?
+
+      attr_reader :start_time #: Float?
+      attr_reader :max_duration #: Numeric
+
+      # @rbs max_duration: Numeric
+      # @rbs return: void
+      def initialize(max_duration:)
+        super()
+        @max_duration = max_duration
+        @start_time = nil
+      end
+
+      # Called when monitor starts - records the start time
+      # @rbs return: void
+      def started
+        @start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      # @rbs return: bool
+      def exceeded?
+        elapsed_time >= @max_duration
+      end
+
+      private
+
+      # @rbs return: Float
+      def elapsed_time
+        return 0.0 if @start_time.nil?
+
+        Process.clock_gettime(Process::CLOCK_MONOTONIC) - @start_time
+      end
+    end
+  end
+end

data/lib/seigen_watchdog/monitor.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module SeigenWatchdog
+  # Monitor class that checks limiters and invokes the killer when needed
+  class Monitor
+    # @rbs @check_interval: Numeric?
+    # @rbs @killer: Killers::Base
+    # @rbs @limiters: Hash[Symbol, Limiters::Base]
+    # @rbs @logger: Logger?
+    # @rbs @on_exception: Proc?
+    # @rbs @before_kill: Proc?
+    # @rbs @checks: Integer
+    # @rbs @last_check_time: Float? | nil
+    # @rbs @time_killed: Float? | nil
+    # @rbs @thread: Thread? | nil
+    # @rbs @running: bool
+    # @rbs @mutex: Thread::Mutex
+
+    # @rbs!
+    #   attr_reader checks: Integer
+    attr_reader :checks
+
+    # Interval in seconds between checks, nil to disable background thread
+    # @rbs check_interval: Numeric?
+    # The killer to invoke when a limit is exceeded
+    # @rbs killer: Killers::Base
+    # Hash of limiters to check
+    # @rbs limiters: Hash[Symbol, Limiters::Base]
+    # Optional logger for debugging
+    # @rbs logger: Logger?
+    # Optional callback when an exception occurs
+    # @rbs on_exception: Proc?
+    # Optional callback invoked before killing, receives exceeded limiter
+    # @rbs before_kill: Proc?
+    # @rbs return: void
+    def initialize(check_interval:, killer:, limiters:, logger: nil, on_exception: nil, before_kill: nil)
+      @check_interval = check_interval
+      @killer = killer
+      @limiters = limiters.transform_keys(&:to_sym)
+      @logger = logger
+      @on_exception = on_exception
+      @before_kill = before_kill
+      @checks = 0
+      @last_check_time = nil
+      @time_killed = nil
+      @thread = nil
+      @running = false
+      @mutex = Mutex.new
+
+      # Call started on all limiters to initialize their state
+      @limiters.each_value(&:started)
+
+      if @check_interval
+        log_info('Monitor started with background thread')
+        start_background_thread
+      else
+        log_info('Monitor initialized without background thread; manual checks required')
+      end
+    end
+
+    # Performs a single check of all limiters
+    # Returns true if any limiter exceeded and killer was invoked
+    # @rbs return: bool
+    def check_once
+      increment_checks
+      log_debug("Performing check ##{@checks}")
+
+      name, limiter = @limiters.find { |_k, v| v.exceeded? }
+      if limiter
+        if killed?
+          log_debug("Limit exceeded but killer already invoked #{seconds_since_killed} seconds ago")
+        else
+          log_info("Limit exceeded: #{name}, invoking killer")
+          perform_kill(name, limiter)
+        end
+        true
+      else
+        log_debug('All limiters within bounds')
+        false
+      end
+    rescue StandardError => e
+      handle_exception(e)
+      false
+    end
+
+    # Returns the number of seconds since the last check
+    # Seconds since last check, or nil if no check has been performed
+    # @rbs return: Float?
+    def seconds_after_last_check
+      return nil if @last_check_time.nil?
+
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - @last_check_time
+    end
+
+    # Returns true if the killer has been invoked
+    # @rbs return: bool
+    def killed?
+      !@time_killed.nil?
+    end
+
+    # Returns the number of seconds since the killer was invoked
+    # Seconds since killer was invoked, or nil if killer has not been invoked
+    # @rbs return: Float?
+    def seconds_since_killed
+      return nil if @time_killed.nil?
+
+      Process.clock_gettime(Process::CLOCK_MONOTONIC) - @time_killed
+    end
+
+    # Stops the background thread if running
+    # @rbs return: void
+    def stop
+      if @thread
+        @mutex.synchronize { @running = false }
+        @thread.join(5) # Wait up to 5 seconds for thread to finish
+        @thread = nil
+        log_debug('Monitor stopped')
+      end
+
+      # Call stopped on all limiters to clean up their state
+      @limiters.each_value(&:stopped)
+    end
+
+    # Checks if the background thread is running
+    # Returns true if the background thread is running
+    # @rbs return: bool
+    def running?
+      @running && @thread&.alive?
+    end
+
+    # Returns a limiter by name
+    # @rbs name: Symbol | String
+    # @rbs return: Limiters::Base
+    def limiter(name)
+      @limiters.fetch(name.to_sym)
+    end
+
+    # Returns a hash of all limiters
+    # Returns a new hash with the same keys and values
+    # Modifications to the hash won't affect internal state, but limiter instances are shared
+    # @rbs return: Hash[Symbol | String, Limiters::Base]
+    def limiters
+      @limiters.to_h { |k, v| [k, v] }
+    end
+
+    private
+
+    # @rbs name: Symbol
+    # @rbs limiter: Limiters::Base
+    # @rbs return: void
+    def perform_kill(name, limiter)
+      run_before_kill(name, limiter)
+      @killer.kill!
+      @time_killed = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # @rbs name: Symbol
+    # @rbs limiter: Limiters::Base
+    # @rbs return: void
+    def run_before_kill(name, limiter)
+      @before_kill&.call(name, limiter)
+    rescue StandardError => e
+      handle_exception(e)
+    end
+
+    # @rbs return: void
+    def increment_checks
+      @mutex.synchronize do
+        @checks += 1
+        @last_check_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+
+    # @rbs return: void
+    def start_background_thread
+      @running = true
+      @thread = Thread.new { background_loop }
+      @thread.abort_on_exception = false
+    end
+
+    # @rbs return: void
+    def background_loop
+      while @running
+        check_once
+        sleep(@check_interval) if @running
+      end
+    rescue StandardError => e
+      handle_exception(e)
+    end
+
+    # @rbs exception: StandardError
+    # @rbs return: void
+    def handle_exception(exception)
+      log_error("Exception in monitor: #{exception.class}: #{exception.message}")
+      @on_exception&.call(exception)
+    end
+
+    # @rbs message: String
+    # @rbs return: void
+    def log_debug(message)
+      @logger&.debug { "SeigenWatchdog: #{message}" }
+    end
+
+    # @rbs message: String
+    # @rbs return: void
+    def log_info(message)
+      @logger&.info("SeigenWatchdog: #{message}")
+    end
+
+    # @rbs message: String
+    # @rbs return: void
+    def log_error(message)
+      @logger&.error("SeigenWatchdog: #{message}")
+    end
+  end
+end

data/lib/seigen_watchdog/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SeigenWatchdog
+  VERSION = '0.3.0' #: String
+end

data/lib/seigen_watchdog.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative 'seigen_watchdog/version'
+
+# Monitoring and watchdog module for Ruby applications
+module SeigenWatchdog
+  # @rbs self.@monitor: Monitor?
+
+  class Error < StandardError; end
+
+  class << self
+    attr_reader :monitor #: Monitor?
+
+    # Starts the SeigenWatchdog monitor
+    # @rbs check_interval: Numeric?
+    # @rbs killer: Killers::Base
+    # @rbs limiters: Hash[Symbol | String, Limiters::Base]
+    # @rbs logger: Logger?
+    # @rbs on_exception: Proc?
+    # @rbs before_kill: Proc?
+    # @rbs return: Monitor
+    def start(check_interval:, killer:, limiters:, logger: nil, on_exception: nil, before_kill: nil)
+      stop if started?
+
+      @monitor = Monitor.new(
+        check_interval: check_interval,
+        killer: killer,
+        limiters: limiters,
+        logger: logger,
+        on_exception: on_exception,
+        before_kill: before_kill
+      )
+    end
+
+    # Stops the SeigenWatchdog monitor
+    # @rbs return: void
+    def stop
+      return unless @monitor
+
+      @monitor.stop
+      @monitor = nil
+    end
+
+    # Checks if the monitor has been started
+    # Returns true if the monitor is started
+    # @rbs return: bool
+    def started?
+      !@monitor.nil?
+    end
+  end
+end
+
+require_relative 'seigen_watchdog/limiters/base'
+require_relative 'seigen_watchdog/limiters/rss'
+require_relative 'seigen_watchdog/limiters/time'
+require_relative 'seigen_watchdog/limiters/counter'
+require_relative 'seigen_watchdog/limiters/custom'
+require_relative 'seigen_watchdog/killers/base'
+require_relative 'seigen_watchdog/killers/signal'
+require_relative 'seigen_watchdog/monitor'

data/sig/seigen_watchdog/killers/base.rbs

@@ -0,0 +1,11 @@
+# Generated from lib/seigen_watchdog/killers/base.rb with RBS::Inline
+
+module SeigenWatchdog
+  module Killers
+    # Base class for all killers
+    class Base
+      # @rbs return: void
+      def kill!: () -> void
+    end
+  end
+end

data/sig/seigen_watchdog/killers/signal.rbs

@@ -0,0 +1,20 @@
+# Generated from lib/seigen_watchdog/killers/signal.rb with RBS::Inline
+
+module SeigenWatchdog
+  module Killers
+    # Killer that sends a signal to the current process
+    class Signal < Base
+      @signal: String
+
+      attr_reader signal: String
+
+      # @rbs signal: String | Symbol
+      # @rbs return: void
+      def initialize: (signal: String | Symbol) -> void
+
+      # Sends the signal to the current process
+      # @rbs return: void
+      def kill!: () -> void
+    end
+  end
+end

data/sig/seigen_watchdog/limiters/base.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/seigen_watchdog/limiters/base.rb with RBS::Inline
+
+module SeigenWatchdog
+  module Limiters
+    # Base class for all limiters
+    class Base
+      # @rbs return: bool
+      def exceeded?: () -> bool
+
+      # Called when the limiter is started (when monitor initializes)
+      # @rbs return: void
+      def started: () -> void
+
+      # Called when the limiter is stopped (when monitor stops)
+      # @rbs return: void
+      def stopped: () -> void
+    end
+  end
+end

data/sig/seigen_watchdog/limiters/counter.rbs

@@ -0,0 +1,39 @@
+# Generated from lib/seigen_watchdog/limiters/counter.rb with RBS::Inline
+
+module SeigenWatchdog
+  module Limiters
+    # Limiter based on iteration count
+    class Counter < Base
+      @max_count: Integer
+
+      @count: Integer
+
+      @mutex: Thread::Mutex
+
+      attr_reader max_count: Integer
+
+      # @rbs max_count: Integer
+      # @rbs initial: Integer
+      # @rbs return: void
+      def initialize: (max_count: Integer, ?initial: Integer) -> void
+
+      # Increments the counter by the specified amount
+      # @rbs count: Integer
+      # @rbs return: void
+      def increment: (?Integer count) -> void
+
+      # Decrements the counter by the specified amount
+      # @rbs count: Integer
+      # @rbs return: void
+      def decrement: (?Integer count) -> void
+
+      # Resets the counter to the specified initial value
+      # @rbs initial: Integer
+      # @rbs return: void
+      def reset: (?Integer initial) -> void
+
+      # @rbs return: bool
+      def exceeded?: () -> bool
+    end
+  end
+end

data/sig/seigen_watchdog/limiters/custom.rbs

@@ -0,0 +1,16 @@
+# Generated from lib/seigen_watchdog/limiters/custom.rb with RBS::Inline
+
+module SeigenWatchdog
+  module Limiters
+    # Limiter based on a custom checker lambda
+    class Custom < Base
+      # @rbs @checker: Proc | #call
+      # @rbs checker: Proc | #call
+      # @rbs return: void
+      def initialize: (checker: untyped) -> void
+
+      # @rbs return: bool
+      def exceeded?: () -> bool
+    end
+  end
+end

data/sig/seigen_watchdog/limiters/rss.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/seigen_watchdog/limiters/rss.rb with RBS::Inline
+
+module SeigenWatchdog
+  module Limiters
+    # Limiter based on RSS memory usage
+    class RSS < Base
+      @max_rss: Integer
+
+      @mem: GetProcessMem
+
+      attr_reader max_rss: Integer
+
+      # @rbs max_rss: Integer
+      # @rbs return: void
+      def initialize: (max_rss: Integer) -> void
+
+      # @rbs return: bool
+      def exceeded?: () -> bool
+    end
+  end
+end

data/sig/seigen_watchdog/limiters/time.rbs

@@ -0,0 +1,32 @@
+# Generated from lib/seigen_watchdog/limiters/time.rb with RBS::Inline
+
+module SeigenWatchdog
+  module Limiters
+    # Limiter based on execution time
+    class Time < Base
+      @max_duration: Numeric
+
+      @start_time: Float?
+
+      attr_reader start_time: Float?
+
+      attr_reader max_duration: Numeric
+
+      # @rbs max_duration: Numeric
+      # @rbs return: void
+      def initialize: (max_duration: Numeric) -> void
+
+      # Called when monitor starts - records the start time
+      # @rbs return: void
+      def started: () -> void
+
+      # @rbs return: bool
+      def exceeded?: () -> bool
+
+      private
+
+      # @rbs return: Float
+      def elapsed_time: () -> Float
+    end
+  end
+end

data/sig/seigen_watchdog/monitor.rbs

@@ -0,0 +1,125 @@
+# Generated from lib/seigen_watchdog/monitor.rb with RBS::Inline
+
+module SeigenWatchdog
+  # Monitor class that checks limiters and invokes the killer when needed
+  class Monitor
+    @mutex: Thread::Mutex
+
+    @running: bool
+
+    @thread: Thread? | nil
+
+    @time_killed: Float? | nil
+
+    @last_check_time: Float? | nil
+
+    @checks: Integer
+
+    @before_kill: Proc?
+
+    @on_exception: Proc?
+
+    @logger: Logger?
+
+    @limiters: Hash[Symbol, Limiters::Base]
+
+    @killer: Killers::Base
+
+    @check_interval: Numeric?
+
+    # @rbs!
+    #   attr_reader checks: Integer
+    attr_reader checks: untyped
+
+    # Interval in seconds between checks, nil to disable background thread
+    # @rbs check_interval: Numeric?
+    # The killer to invoke when a limit is exceeded
+    # @rbs killer: Killers::Base
+    # Hash of limiters to check
+    # @rbs limiters: Hash[Symbol, Limiters::Base]
+    # Optional logger for debugging
+    # @rbs logger: Logger?
+    # Optional callback when an exception occurs
+    # @rbs on_exception: Proc?
+    # Optional callback invoked before killing, receives exceeded limiter
+    # @rbs before_kill: Proc?
+    # @rbs return: void
+    def initialize: (check_interval: Numeric?, killer: Killers::Base, limiters: Hash[Symbol, Limiters::Base], ?logger: Logger?, ?on_exception: Proc?, ?before_kill: Proc?) -> void
+
+    # Performs a single check of all limiters
+    # Returns true if any limiter exceeded and killer was invoked
+    # @rbs return: bool
+    def check_once: () -> bool
+
+    # Returns the number of seconds since the last check
+    # Seconds since last check, or nil if no check has been performed
+    # @rbs return: Float?
+    def seconds_after_last_check: () -> Float?
+
+    # Returns true if the killer has been invoked
+    # @rbs return: bool
+    def killed?: () -> bool
+
+    # Returns the number of seconds since the killer was invoked
+    # Seconds since killer was invoked, or nil if killer has not been invoked
+    # @rbs return: Float?
+    def seconds_since_killed: () -> Float?
+
+    # Stops the background thread if running
+    # @rbs return: void
+    def stop: () -> void
+
+    # Checks if the background thread is running
+    # Returns true if the background thread is running
+    # @rbs return: bool
+    def running?: () -> bool
+
+    # Returns a limiter by name
+    # @rbs name: Symbol | String
+    # @rbs return: Limiters::Base
+    def limiter: (Symbol | String name) -> Limiters::Base
+
+    # Returns a hash of all limiters
+    # Returns a new hash with the same keys and values
+    # Modifications to the hash won't affect internal state, but limiter instances are shared
+    # @rbs return: Hash[Symbol | String, Limiters::Base]
+    def limiters: () -> Hash[Symbol | String, Limiters::Base]
+
+    private
+
+    # @rbs name: Symbol
+    # @rbs limiter: Limiters::Base
+    # @rbs return: void
+    def perform_kill: (Symbol name, Limiters::Base limiter) -> void
+
+    # @rbs name: Symbol
+    # @rbs limiter: Limiters::Base
+    # @rbs return: void
+    def run_before_kill: (Symbol name, Limiters::Base limiter) -> void
+
+    # @rbs return: void
+    def increment_checks: () -> void
+
+    # @rbs return: void
+    def start_background_thread: () -> void
+
+    # @rbs return: void
+    def background_loop: () -> void
+
+    # @rbs exception: StandardError
+    # @rbs return: void
+    def handle_exception: (StandardError exception) -> void
+
+    # @rbs message: String
+    # @rbs return: void
+    def log_debug: (String message) -> void
+
+    # @rbs message: String
+    # @rbs return: void
+    def log_info: (String message) -> void
+
+    # @rbs message: String
+    # @rbs return: void
+    def log_error: (String message) -> void
+  end
+end

data/sig/seigen_watchdog/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/seigen_watchdog/version.rb with RBS::Inline
+
+module SeigenWatchdog
+  VERSION: String
+end

data/sig/seigen_watchdog.rbs

@@ -0,0 +1,30 @@
+# Generated from lib/seigen_watchdog.rb with RBS::Inline
+
+# Monitoring and watchdog module for Ruby applications
+module SeigenWatchdog
+  self.@monitor: Monitor?
+
+  class Error < StandardError
+  end
+
+  attr_reader monitor: Monitor?
+
+  # Starts the SeigenWatchdog monitor
+  # @rbs check_interval: Numeric?
+  # @rbs killer: Killers::Base
+  # @rbs limiters: Hash[Symbol | String, Limiters::Base]
+  # @rbs logger: Logger?
+  # @rbs on_exception: Proc?
+  # @rbs before_kill: Proc?
+  # @rbs return: Monitor
+  def self.start: (check_interval: Numeric?, killer: Killers::Base, limiters: Hash[Symbol | String, Limiters::Base], ?logger: Logger?, ?on_exception: Proc?, ?before_kill: Proc?) -> Monitor
+
+  # Stops the SeigenWatchdog monitor
+  # @rbs return: void
+  def self.stop: () -> void
+
+  # Checks if the monitor has been started
+  # Returns true if the monitor is started
+  # @rbs return: bool
+  def self.started?: () -> bool
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: seigen_watchdog
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- Denis Talakevich
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-11-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: get_process_mem
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+description: Monitors and gracefully terminates a Ruby application based on configurable
+  memory usage,execution time, iteration count, or custom conditions
+email:
+- senid231@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- SECURITY.md
+- lib/seigen_watchdog.rb
+- lib/seigen_watchdog/killers/base.rb
+- lib/seigen_watchdog/killers/signal.rb
+- lib/seigen_watchdog/limiters/base.rb
+- lib/seigen_watchdog/limiters/counter.rb
+- lib/seigen_watchdog/limiters/custom.rb
+- lib/seigen_watchdog/limiters/rss.rb
+- lib/seigen_watchdog/limiters/time.rb
+- lib/seigen_watchdog/monitor.rb
+- lib/seigen_watchdog/version.rb
+- sig/seigen_watchdog.rbs
+- sig/seigen_watchdog/killers/base.rbs
+- sig/seigen_watchdog/killers/signal.rbs
+- sig/seigen_watchdog/limiters/base.rbs
+- sig/seigen_watchdog/limiters/counter.rbs
+- sig/seigen_watchdog/limiters/custom.rbs
+- sig/seigen_watchdog/limiters/rss.rbs
+- sig/seigen_watchdog/limiters/time.rbs
+- sig/seigen_watchdog/monitor.rbs
+- sig/seigen_watchdog/version.rbs
+homepage: https://github.com/senid231/seigen_watchdog
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/senid231/seigen_watchdog
+  source_code_uri: https://github.com/senid231/seigen_watchdog
+  changelog_uri: https://github.com/senid231/seigen_watchdog/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Monitors and gracefully terminates a Ruby application based on configurable
+  memory usage,execution time, iteration count, or custom conditions
+test_files: []