igniter 0.5.1 → 0.5.2

data/examples/saga.rb

@@ -1,110 +0,0 @@
-# frozen_string_literal: true
-
-# Saga Pattern — compensating transactions for Igniter contracts.
-#
-# When a step fails mid-execution, the saga system automatically runs
-# compensating actions for all previously completed steps in reverse order.
-#
-# Run: ruby examples/saga.rb
-
-$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
-require "igniter"
-require "igniter/extensions/saga"
-require "igniter/extensions/execution_report"
-
-# ── Contracts ─────────────────────────────────────────────────────────────────
-
-class OrderWorkflow < Igniter::Contract
-  define do
-    input :order_id, type: :string
-    input :amount,   type: :numeric
-
-    compute :reserve_stock, depends_on: :order_id do |order_id:|
-      puts "  [forward] reserve_stock for order #{order_id}"
-      { reservation_id: "rsv-#{order_id}" }
-    end
-
-    compute :charge_card, depends_on: %i[order_id amount reserve_stock] do |order_id:, amount:, **|
-      puts "  [forward] charge_card: $#{amount}"
-      raise "Card declined: amount $#{amount} exceeds limit" if amount > 500
-
-      { charge_id: "chg-#{order_id}", amount: amount }
-    end
-
-    compute :send_confirmation, depends_on: %i[reserve_stock charge_card] do |charge_card:, **|
-      puts "  [forward] send_confirmation for charge #{charge_card[:charge_id]}"
-      { sent: true }
-    end
-
-    output :reserve_stock
-    output :charge_card
-    output :send_confirmation
-  end
-
-  compensate :charge_card do |_inputs:, value:|
-    puts "  [compensate] refunding charge #{value[:charge_id]}"
-  end
-
-  compensate :reserve_stock do |_inputs:, value:|
-    puts "  [compensate] releasing reservation #{value[:reservation_id]}"
-  end
-end
-
-puts "=== Saga Demo ==="
-puts
-
-# ── 1. Successful saga ─────────────────────────────────────────────────────────
-
-puts "--- 1. Successful execution (amount=$100) ---"
-result_ok = OrderWorkflow.new(order_id: "ord-001", amount: 100.0).resolve_saga
-puts result_ok.explain
-puts
-
-# ── 2. Failed saga — compensations triggered ───────────────────────────────────
-
-puts "--- 2. Failed execution (amount=$999 — exceeds limit) ---"
-result_fail = OrderWorkflow.new(order_id: "ord-002", amount: 999.0).resolve_saga
-puts result_fail.explain
-puts
-
-# ── 3. Result query API ────────────────────────────────────────────────────────
-
-puts "--- 3. Result query API ---"
-puts "success?          = #{result_fail.success?}"
-puts "failed_node       = #{result_fail.failed_node.inspect}"
-puts "error             = #{result_fail.error.message}"
-puts "compensations_ran = #{result_fail.compensations.map(&:node_name).inspect}"
-puts "all compensations ok? #{result_fail.compensations.all?(&:success?)}"
-puts
-
-# ── 4. Execution report ────────────────────────────────────────────────────────
-
-puts "--- 4. execution_report (after failed saga) ---"
-failed_contract = OrderWorkflow.new(order_id: "ord-003", amount: 999.0)
-begin
-  failed_contract.resolve_all
-rescue Igniter::Error
-  nil
-end
-puts failed_contract.execution_report.explain
-puts
-
-# ── 5. Execution report on successful contract ────────────────────────────────
-
-puts "--- 5. execution_report (successful) ---"
-ok_contract = OrderWorkflow.new(order_id: "ord-004", amount: 50.0)
-ok_contract.resolve_all
-puts ok_contract.execution_report.explain
-puts
-
-# ── 6. to_h / structured output ───────────────────────────────────────────────
-
-puts "--- 6. result.to_h ---"
-h = result_fail.to_h
-puts "success:       #{h[:success]}"
-puts "failed_node:   #{h[:failed_node].inspect}"
-puts "error:         #{h[:error]}"
-puts "compensations: #{h[:compensations].map { |c| [c[:node], c[:success]] }.inspect}"
-puts
-
-puts "done=true"

data/lib/igniter/stack.rb

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "monorepo_packages"
-require "igniter/sdk"
-require "igniter/app/stack_pack"

data/packages/igniter-agents/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/packages/igniter-agents/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/packages/igniter-agents/lib/igniter/agent/ref.rb

@@ -1,87 +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
-        raise reply.payload[:error] if reply.payload[:error]
-
-        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/packages/igniter-agents/lib/igniter/agent/runner.rb

@@ -1,141 +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)
-      rescue Igniter::PendingDependencyError => e
-        send_error_reply(message, e)
-        return
-      else
-
-        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
-
-      def send_error_reply(message, error)
-        return unless message.reply_to
-
-        message.reply_to.push(
-          Message.new(type: :reply, payload: { error: error })
-        )
-      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/packages/igniter-agents/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/packages/igniter-agents/lib/igniter/agent.rb

@@ -1,161 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter/core/errors"
-require "igniter/core/runtime/agent_adapter"
-require_relative "registry"
-require_relative "agent/message"
-require_relative "agent/mailbox"
-require_relative "agent/state_holder"
-require_relative "agent/runner"
-require_relative "agent/ref"
-require_relative "runtime/registry_agent_adapter"
-
-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
-
-Igniter::Runtime.activate_agent_adapter! if Igniter::Runtime.agent_adapter.instance_of?(Igniter::Runtime::AgentAdapter)