igniter 0.5.0 → 0.5.2

data/lib/igniter/agent/mailbox.rb

@@ -1,96 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Agent
-    # Thread-safe bounded queue for passing Messages between threads.
-    #
-    # Overflow policies (applied when capacity is reached):
-    #   :block      — block the caller until space is available (default)
-    #   :drop_oldest — discard the oldest message and enqueue the new one
-    #   :drop_newest — discard the incoming message silently
-    #   :error      — raise Igniter::Agent::MailboxFullError
-    class Mailbox
-      DEFAULT_CAPACITY = 256
-
-      def initialize(capacity: DEFAULT_CAPACITY, overflow: :block)
-        @capacity = capacity
-        @overflow = overflow
-        @queue    = []
-        @mutex    = Mutex.new
-        @not_empty = ConditionVariable.new
-        @not_full  = ConditionVariable.new
-        @closed    = false
-      end
-
-      # Enqueue a message. Returns self (chainable).
-      def push(message) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength
-        @mutex.synchronize do
-          return self if @closed
-
-          if @queue.size >= @capacity
-            case @overflow
-            when :block
-              @not_full.wait(@mutex) while @queue.size >= @capacity && !@closed
-              return self if @closed
-            when :drop_oldest
-              @queue.shift
-            when :drop_newest
-              return self
-            when :error
-              raise MailboxFullError, "Mailbox full (capacity=#{@capacity})"
-            end
-          end
-
-          @queue << message
-          @not_empty.signal
-        end
-        self
-      end
-
-      # Dequeue the next message. Blocks until a message arrives or the mailbox
-      # is closed. Returns nil if closed and empty, or if +timeout+ expires.
-      def pop(timeout: nil) # rubocop:disable Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
-        @mutex.synchronize do
-          if timeout
-            deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
-            while @queue.empty? && !@closed
-              remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
-              return nil if remaining <= 0
-
-              @not_empty.wait(@mutex, remaining)
-            end
-          else
-            @not_empty.wait(@mutex) while @queue.empty? && !@closed
-          end
-
-          return nil if @queue.empty?
-
-          msg = @queue.shift
-          @not_full.signal
-          msg
-        end
-      end
-
-      # Close the mailbox. Blocked callers in +pop+ wake up and return nil.
-      def close
-        @mutex.synchronize do
-          @closed = true
-          @not_empty.broadcast
-          @not_full.broadcast
-        end
-      end
-
-      def closed?
-        @mutex.synchronize { @closed }
-      end
-
-      def size
-        @mutex.synchronize { @queue.size }
-      end
-
-      def empty?
-        @mutex.synchronize { @queue.empty? }
-      end
-    end
-  end
-end

data/lib/igniter/agent/message.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Agent
-    # Immutable message passed between agents through a Mailbox.
-    #
-    #   type     — Symbol identifying the message kind (e.g. :increment, :get)
-    #   payload  — frozen Hash of message data (default: {})
-    #   reply_to — one-shot Mailbox for sync request-reply (nil for async)
-    class Message
-      attr_reader :type, :payload, :reply_to
-
-      def initialize(type:, payload: {}, reply_to: nil)
-        @type     = type.to_sym
-        @payload  = (payload || {}).freeze
-        @reply_to = reply_to
-        freeze
-      end
-    end
-  end
-end

data/lib/igniter/agent/ref.rb

@@ -1,86 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Agent
-    # External handle to a running agent.
-    #
-    # Callers interact with agents exclusively through Ref — they never touch
-    # the Mailbox, StateHolder, or Thread directly. This allows the Supervisor
-    # to swap out internals on restart without invalidating existing Ref objects.
-    class Ref
-      def initialize(thread:, mailbox:, state_holder:)
-        @thread        = thread
-        @mailbox       = mailbox
-        @state_holder  = state_holder
-        @mutex         = Mutex.new
-      end
-
-      # Asynchronous fire-and-forget. Returns self.
-      def send(type, payload = {})
-        mailbox.push(Message.new(type: type.to_sym, payload: payload))
-        self
-      end
-
-      # Synchronous request-reply. Blocks until the handler responds or timeout
-      # elapses. Raises Igniter::Agent::TimeoutError on timeout.
-      def call(type, payload = {}, timeout: 5)
-        reply_box = Mailbox.new(capacity: 1, overflow: :drop_newest)
-        mailbox.push(Message.new(type: type.to_sym, payload: payload, reply_to: reply_box))
-        reply = reply_box.pop(timeout: timeout)
-        raise TimeoutError, "Agent did not reply within #{timeout}s" unless reply
-
-        reply.payload[:value]
-      end
-
-      # Request graceful shutdown. Closes the mailbox so the runner exits after
-      # processing any in-flight message. Blocks until the thread finishes.
-      def stop(timeout: 5)
-        mailbox.close
-        thread&.join(timeout)
-        self
-      end
-
-      # Forcefully terminate the agent thread.
-      def kill
-        thread&.kill
-        mailbox.close
-        self
-      end
-
-      def alive?
-        thread&.alive? || false
-      end
-
-      # Read the current state snapshot without blocking the agent.
-      def state
-        state_holder.get
-      end
-
-      # Supervisor-internal: swap out internals when the agent restarts.
-      # Callers keep the same Ref object; the new thread/mailbox/state_holder
-      # are transparently injected.
-      def rebind(thread:, mailbox:, state_holder:)
-        @mutex.synchronize do
-          @thread        = thread
-          @mailbox       = mailbox
-          @state_holder  = state_holder
-        end
-        self
-      end
-
-      private
-
-      def thread
-        @mutex.synchronize { @thread }
-      end
-
-      def mailbox
-        @mutex.synchronize { @mailbox }
-      end
-
-      def state_holder
-        @mutex.synchronize { @state_holder }
-      end
-    end
-  end
-end

data/lib/igniter/agent/runner.rb

@@ -1,129 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Agent
-    # Runs an agent's message loop in a dedicated Ruby Thread.
-    #
-    # Responsibilities:
-    #   - Pop messages from the Mailbox and dispatch to registered handlers
-    #   - Fire scheduled timers when their interval elapses
-    #   - Apply handler return-value semantics to StateHolder
-    #   - Invoke the on_crash callback when the thread dies unexpectedly
-    #   - Fire lifecycle hooks (after_start, after_crash, after_stop)
-    #
-    # Handler return-value semantics:
-    #   Hash  → replace agent state with the returned hash
-    #   :stop → close the mailbox and exit the loop cleanly
-    #   nil   → leave state unchanged (no reply sent to sync caller)
-    #   other → leave state unchanged; if message has reply_to, send value as reply
-    class Runner
-      def initialize(agent_class:, mailbox:, state_holder:, on_crash: nil)
-        @agent_class   = agent_class
-        @mailbox       = mailbox
-        @state_holder  = state_holder
-        @on_crash      = on_crash
-        @thread        = nil
-        @timers        = build_timers
-      end
-
-      # Start the message loop in a background thread. Returns the Thread.
-      def start
-        @thread = Thread.new { run_loop }
-        @thread.abort_on_exception = false
-        @thread
-      end
-
-      attr_reader :thread
-
-      private
-
-      def run_loop # rubocop:disable Metrics/MethodLength
-        fire_hooks(:start)
-        loop do
-          delay   = nearest_timer_delay
-          message = @mailbox.pop(timeout: delay)
-          fire_due_timers
-          break if message.nil? && @mailbox.closed?
-
-          dispatch(message) if message
-        end
-      rescue StandardError => e
-        @on_crash&.call(e)
-        fire_hooks(:crash, error: e)
-      ensure
-        fire_hooks(:stop)
-      end
-
-      def dispatch(message) # rubocop:disable Metrics/MethodLength
-        handler = @agent_class.handlers[message.type]
-
-        unless handler
-          # Unknown message type — send nil reply if caller is waiting
-          send_reply(message, nil)
-          return
-        end
-
-        state  = @state_holder.get
-        result = handler.call(state: state, payload: message.payload)
-
-        case result
-        when Hash
-          @state_holder.set(result)
-          send_reply(message, nil)
-        when :stop
-          send_reply(message, nil)
-          @mailbox.close
-        when nil
-          send_reply(message, nil)
-        else
-          # Non-state return value — treat as sync reply payload
-          send_reply(message, result)
-        end
-      end
-
-      def send_reply(message, value)
-        return unless message.reply_to
-
-        message.reply_to.push(
-          Message.new(type: :reply, payload: { value: value })
-        )
-      end
-
-      # Returns seconds until the next timer fires, or nil if no timers.
-      def nearest_timer_delay
-        return nil if @timers.empty?
-
-        now      = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        next_at  = @timers.map { |t| t[:next_at] }.min
-        [next_at - now, 0].max
-      end
-
-      def fire_due_timers
-        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        @timers.each do |timer|
-          next if timer[:next_at] > now
-
-          state  = @state_holder.get
-          result = timer[:handler].call(state: state)
-          @state_holder.set(result) if result.is_a?(Hash)
-          timer[:next_at] = now + timer[:interval]
-        end
-      end
-
-      def build_timers
-        now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-        @agent_class.timers.map do |t|
-          t.merge(next_at: now + t[:interval])
-        end
-      end
-
-      def fire_hooks(type, **args)
-        @agent_class.hooks[type]&.each do |hook|
-          hook.call(**args)
-        rescue StandardError
-          nil # hooks must not crash the runner
-        end
-      end
-    end
-  end
-end

data/lib/igniter/agent/state_holder.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  class Agent
-    # Mutex-guarded wrapper around an agent's current state hash.
-    # The state is always stored as a frozen Hash so callers can read it
-    # without holding the lock.
-    class StateHolder
-      def initialize(initial_state)
-        @state = initial_state.freeze
-        @mutex = Mutex.new
-      end
-
-      def get
-        @mutex.synchronize { @state }
-      end
-
-      def set(new_state)
-        @mutex.synchronize { @state = new_state.freeze }
-      end
-    end
-  end
-end

data/lib/igniter/agent.rb

@@ -1,155 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "agent/message"
-require_relative "agent/mailbox"
-require_relative "agent/state_holder"
-require_relative "agent/runner"
-require_relative "agent/ref"
-
-module Igniter
-  # Base class for stateful, message-driven actors.
-  #
-  # Subclass Agent and use the class-level DSL to declare:
-  #   - `initial_state`  — default state hash for new instances
-  #   - `on`             — handler for a named message type
-  #   - `schedule`       — recurring timer handler
-  #   - `mailbox_size`   — queue capacity (default: 256)
-  #   - `mailbox_overflow` — policy when queue is full (:block/:drop_oldest/
-  #                          :drop_newest/:error, default: :block)
-  #   - `after_start`    — hook called when the agent thread begins
-  #   - `after_crash`    — hook called with the error when the thread crashes
-  #   - `after_stop`     — hook called when the agent thread exits
-  #
-  # Handler return-value semantics:
-  #   Hash  → new state (replaces current state)
-  #   :stop → shut down the agent cleanly
-  #   nil   → unchanged state
-  #   other → unchanged state; sent as reply to sync `call()` callers
-  #
-  # Example:
-  #
-  #   class CounterAgent < Igniter::Agent
-  #     initial_state counter: 0
-  #
-  #     on :increment do |state:, payload:, **|
-  #       state.merge(counter: state[:counter] + payload.fetch(:by, 1))
-  #     end
-  #
-  #     on :count do |state:, **|
-  #       state[:counter]   # returned as sync reply
-  #     end
-  #   end
-  #
-  #   ref = CounterAgent.start
-  #   ref.send(:increment, by: 5)
-  #   ref.call(:count)  # => 5
-  #   ref.stop
-  #
-  class Agent
-    # ── Custom error types ────────────────────────────────────────────────────
-
-    class MailboxFullError < Igniter::Error; end
-    class TimeoutError     < Igniter::Error; end
-
-    # ── Class-level defaults ──────────────────────────────────────────────────
-
-    @handlers         = {}
-    @timers           = []
-    @default_state    = {}
-    @mailbox_capacity = Mailbox::DEFAULT_CAPACITY
-    @mailbox_overflow = :block
-    @hooks            = { start: [], crash: [], stop: [] }
-
-    class << self
-      attr_reader :handlers, :timers, :mailbox_capacity, :hooks
-
-      # ── Inheritance ─────────────────────────────────────────────────────────
-
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@handlers,         {})
-        subclass.instance_variable_set(:@timers,           [])
-        subclass.instance_variable_set(:@default_state,    {})
-        subclass.instance_variable_set(:@mailbox_capacity, Mailbox::DEFAULT_CAPACITY)
-        subclass.instance_variable_set(:@mailbox_overflow, :block)
-        subclass.instance_variable_set(:@hooks,            { start: [], crash: [], stop: [] })
-      end
-
-      # ── DSL ─────────────────────────────────────────────────────────────────
-
-      # Set the initial state hash. Pass a plain Hash or a block returning one.
-      def initial_state(hash = nil, &block)
-        if block
-          @default_state_proc = block
-        else
-          @default_state = (hash || {}).freeze
-        end
-      end
-
-      # Return the resolved default state (evaluated fresh when a block was given).
-      def default_state
-        @default_state_proc ? @default_state_proc.call : @default_state
-      end
-
-      # Register a handler for messages of the given +type+.
-      def on(type, &handler)
-        @handlers[type.to_sym] = handler
-      end
-
-      # Register a recurring timer. The handler is called every +every+ seconds.
-      # Returning a Hash from the handler updates state; nil leaves it unchanged.
-      def schedule(name, every:, &handler)
-        @timers << { name: name.to_sym, interval: every.to_f, handler: handler }
-      end
-
-      # Maximum number of messages in the mailbox before overflow policy applies.
-      def mailbox_size(capacity)
-        @mailbox_capacity = capacity
-      end
-
-      # Overflow policy when the mailbox is full.
-      # One of: :block (default), :drop_oldest, :drop_newest, :error
-      def mailbox_overflow(policy)
-        @mailbox_overflow = policy
-      end
-
-      def after_start(&hook)
-        @hooks[:start] << hook
-      end
-
-      def after_crash(&hook)
-        @hooks[:crash] << hook
-      end
-
-      def after_stop(&hook)
-        @hooks[:stop] << hook
-      end
-
-      # ── Factory ─────────────────────────────────────────────────────────────
-
-      # Start the agent and return a Ref. The agent runs in a background Thread.
-      #
-      # Options:
-      #   initial_state:  Hash — override class-level default state
-      #   on_crash:       callable(error) — supervisor crash hook
-      #   name:           Symbol/String — register in Igniter::Registry under this name
-      #
-      def start(initial_state: nil, on_crash: nil, name: nil) # rubocop:disable Metrics/MethodLength
-        state_holder = StateHolder.new(initial_state || default_state)
-        mailbox      = Mailbox.new(capacity: mailbox_capacity, overflow: @mailbox_overflow)
-        runner       = Runner.new(
-          agent_class: self,
-          mailbox: mailbox,
-          state_holder: state_holder,
-          on_crash: on_crash
-        )
-        thread = runner.start
-        ref    = Ref.new(thread: thread, mailbox: mailbox, state_holder: state_holder)
-
-        Igniter::Registry.register!(name, ref) if name
-
-        ref
-      end
-    end
-  end
-end

data/lib/igniter/agents/ai/alert_agent.rb

@@ -1,111 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "../proactive_agent"
-
-module Igniter
-  module Agents
-    # Threshold-based alerting agent.
-    #
-    # AlertAgent extends ProactiveAgent with an opinionated DSL for declaring
-    # numeric thresholds.  A single +monitor+ / +threshold+ pair registers both
-    # the watcher and the trigger automatically.
-    #
-    # @example
-    #   class ApiAlerts < Igniter::Agents::AlertAgent
-    #     intent "Alert when API error rate or latency spikes"
-    #     scan_interval 15.0
-    #
-    #     monitor :error_rate,  source: -> { Metrics.error_rate }
-    #     monitor :p99_latency, source: -> { Metrics.p99 }
-    #
-    #     threshold :error_rate,  above: 0.05
-    #     threshold :p99_latency, above: 500
-    #   end
-    #
-    #   ref    = ApiAlerts.start
-    #   alerts = ref.call(:alerts)   # => Array<AlertRecord>
-    class AlertAgent < ProactiveAgent
-      # Immutable record created when a threshold is breached.
-      AlertRecord = Struct.new(:metric, :value, :kind, :threshold,
-                               :fired_at, keyword_init: true)
-
-      proactive_initial_state alerts: [], silenced: false
-
-      class << self
-        # Register a polling source for a named metric.
-        # Usually called before +threshold+ for the same metric name.
-        #
-        # @param metric [Symbol, String]
-        # @param source [#call]  — zero-argument callable returning a Numeric
-        def monitor(metric, source:)
-          watch(metric.to_sym, poll: source)
-        end
-
-        # Declare a threshold for a watched metric.
-        # Automatically registers a trigger that fires when the condition is met.
-        #
-        # @param metric [Symbol, String]
-        # @param above  [Numeric, nil]  — breach if value > above
-        # @param below  [Numeric, nil]  — breach if value < below
-        def threshold(metric, above: nil, below: nil)
-          name = metric.to_sym
-
-          trigger(:"threshold_#{name}",
-            condition: ->(ctx) {
-              val = ctx[name]
-              return false if val.nil?
-
-              (above && val.to_f > above.to_f) ||
-                (below && val.to_f < below.to_f)
-            },
-            action: ->(state:, context:) {
-              next state if state[:silenced]
-
-              val  = context[name]
-              kind = above && val.to_f > above.to_f ? :above : :below
-              rec  = AlertRecord.new(
-                metric:    name,
-                value:     val,
-                kind:      kind,
-                threshold: kind == :above ? above : below,
-                fired_at:  Time.now
-              )
-              state.merge(alerts: (state[:alerts] + [rec]).last(200))
-            }
-          )
-        end
-      end
-
-      # ── Inheritance ────────────────────────────────────────────────────────
-      # Re-inject AlertAgent-specific handlers into every subclass so that
-      # anonymous test classes (Class.new(AlertAgent)) also have them.
-      def self.inherited(subclass)
-        super  # ProactiveAgent.inherited → resets @handlers, injects proactive ones
-        inject_alert_handlers!(subclass)
-      end
-
-      private_class_method def self.inject_alert_handlers!(klass)
-        klass.on(:silence)      { |state:, **| state.merge(silenced: true)  }
-        klass.on(:unsilence)    { |state:, **| state.merge(silenced: false) }
-        klass.on(:alerts)       { |state:, **| state.fetch(:alerts, []).dup }
-        klass.on(:clear_alerts) { |state:, **| state.merge(alerts: []) }
-      end
-
-      # Suppress alert creation (scans and condition checks still run).
-      on :silence   do |state:, **| state.merge(silenced: true)  end
-      on :unsilence do |state:, **| state.merge(silenced: false) end
-
-      # Sync query — all recorded AlertRecord objects.
-      #
-      # @return [Array<AlertRecord>]
-      on :alerts do |state:, **|
-        state.fetch(:alerts, []).dup
-      end
-
-      # Clear alert history.
-      on :clear_alerts do |state:, **|
-        state.merge(alerts: [])
-      end
-    end
-  end
-end