igniter 0.5.0 → 0.5.1

data/lib/igniter/application.rb

@@ -1,174 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter/server"
-require_relative "application/app_config"
-require_relative "application/yml_loader"
-require_relative "application/autoloader"
-require_relative "application/scheduler"
-require_relative "application/generator"
-
-module Igniter
-  # Base class for Igniter applications.
-  #
-  # Provides a unified DSL for configuration, contract registration,
-  # scheduled jobs, and server startup — replacing the raw
-  # Igniter::Server.configure boilerplate.
-  #
-  # == Minimal example
-  #
-  #   require "igniter/application"
-  #
-  #   class MyApp < Igniter::Application
-  #     config_file "application.yml"        # optional YAML base config
-  #
-  #     configure do |c|
-  #       c.port  = 4567
-  #       c.store = Igniter::Runtime::Stores::MemoryStore.new
-  #     end
-  #
-  #     register "OrderContract", OrderContract
-  #
-  #     schedule :cleanup, every: "1h" do
-  #       puts "running cleanup..."
-  #     end
-  #   end
-  #
-  #   MyApp.start       # blocking built-in HTTP server
-  #   MyApp.rack_app    # Rack-compatible app (Puma / Unicorn)
-  #
-  # == YAML config (application.yml)
-  #
-  #   server:
-  #     port: 4567
-  #     host: "0.0.0.0"
-  #     log_format: json    # text (default) or json
-  #     drain_timeout: 30
-  #
-  # Values from the YAML file are applied first; the Ruby `configure` block
-  # runs afterwards and always wins.
-  class Application
-    class << self
-      # ─── DSL ─────────────────────────────────────────────────────────────────
-
-      # Path to an optional YAML configuration file.
-      # Loaded before the configure block — configure values override YAML.
-      def config_file(path)
-        @yml_path = path
-      end
-
-      # Configure the application. Block receives an AppConfig instance.
-      # May be called multiple times; blocks are applied in order.
-      def configure(&block)
-        @configure_blocks << block
-      end
-
-      # Declare a directory whose .rb files are eagerly required at startup
-      # (before contracts are registered).
-      def executors_path(path)
-        @executors_paths << path
-      end
-
-      # Declare a directory whose .rb files are eagerly required at startup.
-      def contracts_path(path)
-        @contracts_paths << path
-      end
-
-      # Declare a directory whose .rb files are eagerly required at startup
-      # (agents, supervisors, and other actor-system components).
-      def agents_path(path)
-        @agents_paths << path
-      end
-
-      # Register a contract class under a name for HTTP dispatch.
-      def register(name, contract_class)
-        @registered[name.to_s] = contract_class
-      end
-
-      # Define a recurring background job.
-      #
-      #   schedule :report, every: "1d", at: "09:00" do
-      #     DailyReportContract.new.resolve_all(...)
-      #   end
-      #
-      # Interval formats: Integer (seconds), "30s", "5m", "2h", "1d",
-      # or Hash { hours: 1, minutes: 30 }.
-      def schedule(name, every:, at: nil, &block)
-        @scheduled_jobs << { name: name, every: every, at: at, block: block }
-      end
-
-      # ─── Lifecycle ───────────────────────────────────────────────────────────
-
-      # Start the built-in HTTP server (blocking).
-      # Schedules background jobs and registers an at_exit cleanup.
-      def start
-        sc    = build!
-        sched = build_scheduler(sc)
-        sched&.start
-        at_exit { sched&.stop }
-        Igniter::Server::HttpServer.new(sc).start
-      end
-
-      # Return a Rack-compatible application (for Puma / Unicorn / etc.).
-      def rack_app
-        sc = build!
-        build_scheduler(sc)&.start
-        Igniter::Server::RackApp.new(sc)
-      end
-
-      # Expose the AppConfig (populated after the first build!).
-      def config = @app_config
-
-      # ─── Inheritance isolation ────────────────────────────────────────────────
-
-      def inherited(subclass)
-        super
-        subclass.instance_variable_set(:@yml_path,         nil)
-        subclass.instance_variable_set(:@configure_blocks, [])
-        subclass.instance_variable_set(:@executors_paths,  [])
-        subclass.instance_variable_set(:@contracts_paths,  [])
-        subclass.instance_variable_set(:@agents_paths,     [])
-        subclass.instance_variable_set(:@registered,       {})
-        subclass.instance_variable_set(:@scheduled_jobs,   [])
-        subclass.instance_variable_set(:@app_config,       AppConfig.new)
-        subclass.instance_variable_set(:@build_scheduler,  nil)
-      end
-
-      private
-
-      # Build and return a ready Server::Config.
-      def build!
-        cfg = @app_config
-        apply_yml!(cfg)
-        autoload_paths!
-        @configure_blocks.each { |b| b.call(cfg) }
-        sc = cfg.to_server_config
-        @registered.each { |name, klass| sc.register(name, klass) }
-        sc
-      end
-
-      def apply_yml!(cfg)
-        return unless @yml_path
-
-        yml = YmlLoader.load(@yml_path)
-        YmlLoader.apply(cfg, yml)
-      end
-
-      def autoload_paths!
-        loader = Autoloader.new(base_dir: Dir.pwd)
-        @executors_paths.each { |p| loader.load_path(p) }
-        @contracts_paths.each { |p| loader.load_path(p) }
-        @agents_paths.each    { |p| loader.load_path(p) }
-      end
-
-      def build_scheduler(server_config)
-        return nil if @scheduled_jobs.empty?
-
-        @build_scheduler ||= begin
-          sched = Scheduler.new(logger: server_config.logger)
-          @scheduled_jobs.each { |j| sched.add(j[:name], every: j[:every], at: j[:at], &j[:block]) }
-          sched
-        end
-      end
-    end
-  end
-end

data/lib/igniter/consensus.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/integrations/agents"
-require_relative "consensus/errors"
-require_relative "consensus/state_machine"
-require_relative "consensus/node"
-require_relative "consensus/cluster"
-require_relative "consensus/executors"
-require_relative "consensus/read_query"
-
-module Igniter
-  # Consensus protocol primitives built on Igniter::Agent and Igniter::Contract.
-  #
-  # Provides a Raft-inspired cluster where:
-  # - +Igniter::Consensus::Node+  encapsulates the full Raft protocol as an Agent
-  # - +Igniter::Consensus::Cluster+ manages node lifecycle + high-level read/write
-  # - +Igniter::Consensus::StateMachine+ lets users define custom command reducers
-  # - +Igniter::Consensus::ReadQuery+ is a ready-made Contract for cluster reads
-  #
-  # == Minimal example
-  #
-  #   require "igniter/consensus"
-  #
-  #   cluster = Igniter::Consensus::Cluster.start(nodes: %i[n1 n2 n3 n4 n5])
-  #   cluster.wait_for_leader
-  #
-  #   cluster.write(key: :price, value: 99)   # default KV protocol
-  #   cluster.read(:price)                     # => 99
-  #
-  #   cluster.stop!
-  #
-  # == Custom state machine
-  #
-  #   class PriceStore < Igniter::Consensus::StateMachine
-  #     apply :set    do |state, cmd| state.merge(cmd[:key] => cmd[:value]) end
-  #     apply :delete do |state, cmd| state.reject { |k, _| k == cmd[:key] } end
-  #   end
-  #
-  #   cluster = Igniter::Consensus::Cluster.start(
-  #     nodes: %i[n1 n2 n3 n4 n5],
-  #     state_machine: PriceStore,
-  #   )
-  #   cluster.write(type: :set, key: :price, value: 99)
-  #
-  # == Contract integration
-  #
-  #   class PriceCheck < Igniter::Contract
-  #     define do
-  #       input :cluster
-  #       compute :leader, with: :cluster, call: Igniter::Consensus::FindLeader
-  #       compute :price,  with: [:leader], call: MyPriceReader
-  #       output :price
-  #     end
-  #   end
-  module Consensus
-  end
-end

data/lib/igniter/diagnostics.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "diagnostics/report"
-
-module Igniter
-  module Diagnostics
-  end
-end

data/lib/igniter/extensions/introspection/plan_formatter.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Extensions
-    module Introspection
-      class PlanFormatter
-        def self.to_text(execution, output_names = nil)
-          new(execution, output_names).to_text
-        end
-
-        def initialize(execution, output_names = nil)
-          @execution = execution
-          @plan = execution.plan(output_names)
-        end
-
-        def to_text
-          lines = []
-          lines << "Plan #{@execution.compiled_graph.name}"
-          lines << "Targets: #{format_list(@plan[:targets])}"
-          lines << "Ready: #{format_list(@plan[:ready])}"
-          lines << "Blocked: #{format_list(@plan[:blocked])}"
-          lines << "Nodes:"
-
-          @plan[:nodes].each_value do |entry|
-            lines << format_node(entry)
-          end
-
-          lines.join("\n")
-        end
-
-        private
-
-        def format_node(entry)
-          line = "- #{entry[:kind]} #{entry[:path]} status=#{entry[:status]}"
-          line += " ready=true" if entry[:ready]
-          line += " blocked=true" if entry[:blocked]
-          line += " waiting_on=#{format_list(entry[:waiting_on])}" if entry[:waiting_on].any?
-
-          dependency_summary = entry[:dependencies].map do |dependency|
-            "#{dependency[:name]}(#{dependency[:status]})"
-          end
-          line += " deps=#{dependency_summary.join(',')}" if dependency_summary.any?
-          line
-        end
-
-        def format_list(values)
-          array = Array(values)
-          return "none" if array.empty?
-
-          array.join(",")
-        end
-      end
-    end
-  end
-end

data/lib/igniter/extensions/invariants.rb

@@ -1,116 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/invariant"
-
-module Igniter
-  module Extensions
-    # Patches Igniter::Contract with:
-    #   - Class method: invariant(name) { |output:, **| condition }
-    #   - Instance method: check_invariants → Array<InvariantViolation>
-    #   - Automatic post-execution check in resolve_all (raises InvariantError)
-    #
-    # Invariant blocks receive ONLY the contract's declared output values as
-    # keyword args — the stable public interface, independent of internal nodes.
-    # Use ** to absorb outputs you don't need.
-    #
-    # @example
-    #   class PricingContract < Igniter::Contract
-    #     define do
-    #       input  :price
-    #       input  :quantity
-    #       compute :total, depends_on: %i[price quantity] do |price:, quantity:|
-    #         price * quantity
-    #       end
-    #       output :total
-    #     end
-    #
-    #     invariant(:total_non_negative) { |total:, **| total >= 0 }
-    #   end
-    #
-    # This module is applied globally via:
-    #   Igniter::Contract.include(Igniter::Extensions::Invariants)
-    #
-    module Invariants
-      def self.included(base)
-        base.extend(ClassMethods)
-        base.prepend(InstanceMethods)
-      end
-
-      # ── Class-level DSL ──────────────────────────────────────────────────────
-
-      module ClassMethods
-        # Declare a condition that must always hold after successful execution.
-        #
-        # The block receives the contract's declared output values as keyword
-        # arguments; use ** to absorb outputs you don't care about. Return a
-        # truthy value to indicate the invariant holds, falsy to indicate
-        # a violation.
-        #
-        # @example
-        #   invariant(:positive_total) { |total:, **| total >= 0 }
-        #
-        # @param name [Symbol]
-        def invariant(name, &block)
-          @_invariants ||= {}
-          @_invariants[name.to_sym] = Igniter::Invariant.new(name, &block)
-        end
-
-        # @return [Hash{Symbol => Igniter::Invariant}]
-        def invariants
-          @_invariants || {}
-        end
-      end
-
-      # ── Instance override + new public method ───────────────────────────────
-
-      module InstanceMethods
-        # Intercepts resolve_all to run invariant checks after execution.
-        # Uses a thread-local flag so that property testing can disable the
-        # automatic raise and collect violations as data instead.
-        def resolve_all(...)
-          result = super
-          validate_invariants! unless Thread.current[:igniter_skip_invariants]
-          result
-        end
-
-        # Run all invariants without raising. Returns violations as data.
-        # Safe to call at any time after execution.
-        #
-        # @return [Array<Igniter::InvariantViolation>]
-        def check_invariants
-          return [] if self.class.invariants.empty?
-
-          resolved = collect_output_values
-          self.class.invariants.values.filter_map { |inv| inv.check(resolved) }
-        end
-
-        private
-
-        def validate_invariants!
-          violations = check_invariants
-          return if violations.empty?
-
-          names = violations.map { |v| ":#{v.name}" }.join(", ")
-          raise Igniter::InvariantError.new(
-            "#{violations.size} invariant(s) violated: #{names}",
-            violations: violations,
-            context: { contract: self.class.name }
-          )
-        end
-
-        # Collect all declared output values from the resolved cache.
-        # Keyed by output name (not source node name).
-        def collect_output_values
-          cache = execution.cache
-          execution.compiled_graph.outputs.each_with_object({}) do |output_node, acc|
-            state = cache.fetch(output_node.source_root)
-            acc[output_node.name] = state.value if state&.succeeded?
-          end
-        end
-      end
-    end
-  end
-end
-
-Igniter::Contract.include(Igniter::Extensions::Invariants)

data/lib/igniter/extensions/mesh.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-# Igniter Mesh — Phase 1 (Static) + Phase 2 (Dynamic Discovery)
-#
-# Extends the remote: DSL with capability-based and pinned routing modes, and
-# enables dynamic peer discovery so that the peer topology can be maintained
-# without static add_peer declarations.
-#
-# Usage:
-#   require "igniter/extensions/mesh"
-#
-#   # Phase 1 — static topology (still works):
-#   Igniter::Mesh.configure do |c|
-#     c.add_peer "orders-node",
-#                url: "http://orders.internal:4567",
-#                capabilities: [:orders, :inventory]
-#   end
-#
-#   # Phase 2 — dynamic discovery:
-#   Igniter::Mesh.configure do |c|
-#     c.peer_name          = "api-node"
-#     c.local_url          = "http://api.internal:4567"
-#     c.local_capabilities = [:api]
-#     c.seeds              = %w[http://orders.internal:4567 http://audit.internal:4567]
-#     c.discovery_interval = 30
-#   end
-#   Igniter::Mesh.start_discovery!
-#
-require "igniter"
-require "igniter/server"
-require "igniter/mesh"

data/lib/igniter/integrations/agents.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-# Actor system for Igniter — stateful message-driven agents with supervision.
-#
-# Usage:
-#   require "igniter/integrations/agents"
-#
-# Provides:
-#   Igniter::Agent      — base class for stateful actors
-#   Igniter::Supervisor — supervises and restarts child agents
-#   Igniter::Registry   — thread-safe name → Ref lookup
-#   Igniter::StreamLoop — continuous contract-in-a-tick-loop
-#
-
-require_relative "../agent"
-require_relative "../supervisor"
-require_relative "../registry"
-require_relative "../stream_loop"

data/lib/igniter/mesh/config.rb

@@ -1,45 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Configuration for the local mesh node: registered peers and local identity.
-    class Config
-      attr_accessor :peer_name, :local_capabilities, :seeds, :discovery_interval,
-                    :auto_announce, :local_url, :gossip_fanout
-      attr_reader   :peers, :peer_registry
-
-      def initialize
-        @peer_name          = nil
-        @local_capabilities = []
-        @peers              = []
-        @peer_registry      = PeerRegistry.new
-        @seeds              = []
-        @discovery_interval = 30
-        @auto_announce      = true
-        @local_url          = nil
-        @gossip_fanout      = 3
-      end
-
-      # Register a remote peer by name.
-      #
-      #   Igniter::Mesh.configure do |c|
-      #     c.add_peer "orders-node", url: "http://orders.internal:4567",
-      #                               capabilities: [:orders, :inventory]
-      #   end
-      def add_peer(name, url:, capabilities: [])
-        @peers << Peer.new(name: name, url: url, capabilities: capabilities)
-        self
-      end
-
-      # All static peers that advertise a given capability.
-      def peers_with_capability(capability)
-        @peers.select { |p| p.capable?(capability) }
-      end
-
-      # Find a static peer by its registered name. Returns nil if not found.
-      def peer_named(name)
-        @peers.find { |p| p.name == name.to_s }
-      end
-    end
-  end
-end

data/lib/igniter/mesh/peer.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Immutable value object representing a peer in the static mesh.
-    class Peer
-      attr_reader :name, :url, :capabilities
-
-      def initialize(name:, url:, capabilities: [])
-        @name         = name.to_s.freeze
-        @url          = url.to_s.chomp("/").freeze
-        @capabilities = Array(capabilities).map(&:to_sym).freeze
-        freeze
-      end
-
-      def capable?(capability)
-        @capabilities.include?(capability.to_sym)
-      end
-    end
-  end
-end

data/lib/igniter/mesh/peer_registry.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Thread-safe registry for dynamically discovered peers.
-    #
-    # Stores peers indexed by name so that registering the same peer twice
-    # (e.g. from two different seeds) is idempotent and the latest wins.
-    class PeerRegistry
-      def initialize
-        @peers = {}
-        @mutex = Mutex.new
-      end
-
-      # Register (or update) a peer. Thread-safe.
-      def register(peer)
-        @mutex.synchronize { @peers[peer.name] = peer }
-      end
-
-      # Remove a peer by name. No-op if not registered.
-      def unregister(name)
-        @mutex.synchronize { @peers.delete(name.to_s) }
-      end
-
-      # All currently registered peers (snapshot).
-      def all
-        @mutex.synchronize { @peers.values.dup }
-      end
-
-      # Peers that advertise a given capability.
-      def peers_with_capability(capability)
-        all.select { |p| p.capable?(capability) }
-      end
-
-      # Find a peer by name. Returns nil if not found.
-      def peer_named(name)
-        @mutex.synchronize { @peers[name.to_s] }
-      end
-
-      # Remove all registered peers. Useful in tests.
-      def clear
-        @mutex.synchronize { @peers.clear }
-      end
-
-      # Number of registered peers.
-      def size
-        @mutex.synchronize { @peers.size }
-      end
-    end
-  end
-end

data/lib/igniter/mesh/router.rb

@@ -1,109 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Mesh
-    # Thread-safe capability router with a short-lived health cache.
-    #
-    # Resolves the URL to call for a given routing mode:
-    #   - :capability  → round-robin among alive peers that advertise the capability;
-    #                    raises DeferredCapabilityError when no alive peer is found.
-    #   - :pinned      → asserts the named peer is alive and returns its URL;
-    #                    raises IncidentError when the peer is unknown or unreachable.
-    #
-    # Peer pool = static peers (Config#peers) + dynamic peers (Config#peer_registry).
-    # Static peers take precedence when a name appears in both sets.
-    class Router
-      HEALTH_CACHE_TTL = 5 # seconds
-
-      def initialize(config)
-        @config       = config
-        @health_cache = {}
-        @mutex        = Mutex.new
-        @round_robin  = Hash.new(0)
-      end
-
-      # Find an alive peer advertising +capability+.
-      # Returns the peer URL. Raises DeferredCapabilityError when none are alive.
-      def find_peer_for(capability, deferred_result)
-        candidates = all_capable_peers(capability).select { |p| alive?(p) }
-
-        raise DeferredCapabilityError.new(capability, deferred_result) if candidates.empty?
-
-        url_for_round_robin(capability, candidates)
-      end
-
-      # Resolve the URL of a pinned peer by name.
-      # Raises IncidentError if the peer is unknown or unreachable.
-      def resolve_pinned(peer_name)
-        peer = find_named_peer(peer_name)
-
-        unless peer
-          raise IncidentError.new(
-            peer_name,
-            "Pinned peer '#{peer_name}' is not registered in Igniter::Mesh"
-          )
-        end
-
-        raise IncidentError, peer_name unless alive?(peer)
-
-        peer.url
-      end
-
-      # Expire a peer's cached health status (e.g., after a successful or failed request).
-      def invalidate_health!(url)
-        @mutex.synchronize { @health_cache.delete(url) }
-      end
-
-      private
-
-      # Combined static + dynamic peer pool for capability lookup.
-      # Static peers take precedence over same-named dynamic peers.
-      def all_capable_peers(capability)
-        merge_peers(
-          @config.peers_with_capability(capability),
-          @config.peer_registry.peers_with_capability(capability)
-        )
-      end
-
-      # Lookup peer by name across static and dynamic pools.
-      def find_named_peer(name)
-        @config.peer_named(name) || @config.peer_registry.peer_named(name)
-      end
-
-      # Merge static and dynamic peer lists; static names win on collision.
-      def merge_peers(static, dynamic)
-        seen = static.each_with_object({}) { |p, h| h[p.name] = true }
-        static + dynamic.reject { |p| seen[p.name] }
-      end
-
-      def url_for_round_robin(capability, candidates)
-        idx = @mutex.synchronize do
-          i = @round_robin[capability] % candidates.size
-          @round_robin[capability] = i + 1
-          i
-        end
-        candidates[idx].url
-      end
-
-      def alive?(peer) # rubocop:disable Metrics/MethodLength
-        @mutex.synchronize do
-          entry = @health_cache[peer.url]
-          return entry[:alive] if entry && (Time.now.utc - entry[:checked_at]) < HEALTH_CACHE_TTL
-        end
-
-        alive = begin
-          Igniter::Server::Client.new(peer.url, timeout: 3).health
-          true
-        rescue Igniter::Server::Client::ConnectionError
-          false
-        end
-
-        @mutex.synchronize do
-          @health_cache[peer.url] = { alive: alive, checked_at: Time.now.utc }
-        end
-
-        alive
-      end
-    end
-  end
-end