igniter 0.5.0 → 0.5.2

data/examples/mesh.rb

@@ -1,239 +0,0 @@
-# frozen_string_literal: true
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Igniter Mesh — Phase 1: Static Mesh
-#
-# This example demonstrates how to configure a static peer topology and use
-# the two new routing modes for remote: nodes:
-#
-#   capability: :sym   — auto-select an alive peer that advertises the capability;
-#                        if none are alive the node is deferred (:pending), and
-#                        resolution retries when inputs are updated.
-#
-#   pinned_to: "name"  — must call this exact peer; if it is down the node
-#                        fails with IncidentError signalling admin intervention.
-#
-# In production you would require "igniter/extensions/mesh" and configure real
-# peer URLs.  Here we stub the HTTP layer so the example runs without any
-# actual servers.
-# ─────────────────────────────────────────────────────────────────────────────
-
-require "igniter/extensions/mesh"
-require "json"
-
-# ── 1. Configure the mesh ────────────────────────────────────────────────────
-
-Igniter::Mesh.configure do |c|
-  c.peer_name          = "api-node"
-  c.local_capabilities = [:api]
-
-  # Declare the remote peers this node knows about.
-  c.add_peer "orders-node",
-             url: "http://orders.internal:4567",
-             capabilities: %i[orders inventory]
-
-  c.add_peer "audit-node",
-             url: "http://audit.internal:4567",
-             capabilities: %i[audit]
-end
-
-puts "Mesh configured with #{Igniter::Mesh.config.peers.size} peers:"
-Igniter::Mesh.config.peers.each do |p|
-  puts "  #{p.name} (#{p.url}) — capabilities: #{p.capabilities.join(", ")}"
-end
-puts
-
-# ── 2. Server configuration (what a peer advertises) ────────────────────────
-
-Igniter::Server.configure do |c|
-  c.peer_name         = "orders-node"
-  c.peer_capabilities = %i[orders inventory]
-  c.register "ProcessOrder", Class.new(Igniter::Contract) do
-    input :order_id
-    define do
-      compute :result, depends_on: :order_id do |order_id:|
-        { id: order_id, status: "processed" }
-      end
-    end
-    output :result, from: :result
-  end
-end
-
-puts "Server peer_name:    #{Igniter::Server.config.peer_name}"
-puts "Server capabilities: #{Igniter::Server.config.peer_capabilities.join(", ")}"
-puts
-
-# ── 3. Contract using capability: routing ───────────────────────────────────
-
-class OrderPipeline < Igniter::Contract
-  define do
-    input :order_id
-    # Route to any alive peer advertising :orders capability.
-    # If no peer is alive → node defers (:pending) until one comes up.
-    remote :order_result,
-           contract: "ProcessOrder",
-           capability: :orders,
-           inputs: { order_id: :order_id }
-    output :order_result
-  end
-end
-
-# ── 4. Contract using pinned_to: routing ────────────────────────────────────
-
-class AuditPipeline < Igniter::Contract
-  define do
-    input :event
-    # Always call the "audit-node" — if it is down, raise IncidentError.
-    # This is for critical side-effects that must not be load-balanced.
-    remote :audit_log,
-           contract: "WriteAudit",
-           pinned_to: "audit-node",
-           inputs: { event: :event }
-    output :audit_log
-  end
-end
-
-puts "OrderPipeline compiled:  #{OrderPipeline.compiled_graph.name}"
-puts "AuditPipeline compiled:  #{AuditPipeline.compiled_graph.name}"
-puts
-
-# ── 5. Stub HTTP layer and demonstrate capability routing ────────────────────
-
-# Simulate orders-node being alive.
-def stub_alive(_url, health_response: { "status" => "ok" })
-  client = Object.new
-
-  client.define_singleton_method(:health) { health_response }
-  client.define_singleton_method(:execute) do |_contract, inputs:|
-    { status: :succeeded, outputs: { result: { id: inputs[:order_id], status: "processed" } } }
-  end
-
-  # We cannot easily monkey-patch in a plain script, so we demonstrate
-  # the behaviour via inline contracts instead.
-  client
-end
-
-puts "=== Scenario A: capability routing — orders-node alive ==="
-
-Igniter::Mesh.reset!
-Igniter::Mesh.configure do |c|
-  c.add_peer "orders-node",
-             url: "http://orders.internal:4567",
-             capabilities: [:orders]
-end
-
-# Patch Client for demo purposes
-orders_client = Object.new
-orders_client.define_singleton_method(:health) { { "status" => "ok" } }
-orders_client.define_singleton_method(:execute) do |_contract, inputs:|
-  { status: :succeeded, outputs: { result: { id: inputs[:order_id], status: "processed" } } }
-end
-
-original_new = Igniter::Server::Client.method(:new)
-Igniter::Server::Client.define_singleton_method(:new) do |url, **opts|
-  url == "http://orders.internal:4567" ? orders_client : original_new.call(url, **opts)
-end
-
-contract = OrderPipeline.new(order_id: 42)
-begin
-  contract.resolve_all
-  puts "  order_result: #{contract.result.order_result.inspect}"
-rescue Igniter::Error => e
-  puts "  Error: #{e.message}"
-ensure
-  Igniter::Server::Client.define_singleton_method(:new, &original_new)
-  Igniter::Mesh.reset!
-end
-
-puts
-
-puts "=== Scenario B: capability routing — no alive peers (deferred) ==="
-
-Igniter::Mesh.reset!
-Igniter::Mesh.configure do |c|
-  c.add_peer "orders-node",
-             url: "http://orders.internal:4567",
-             capabilities: [:orders]
-end
-
-dead_client = Object.new
-dead_client.define_singleton_method(:health) do
-  raise Igniter::Server::Client::ConnectionError, "Connection refused"
-end
-
-Igniter::Server::Client.define_singleton_method(:new) do |url, **opts|
-  url == "http://orders.internal:4567" ? dead_client : original_new.call(url, **opts)
-end
-
-contract = OrderPipeline.new(order_id: 42)
-begin
-  contract.resolve_all
-rescue Igniter::Error
-  nil
-end
-
-order_state = contract.execution.cache.fetch(:order_result)
-puts "  order_result status: #{order_state&.status.inspect}   (expected :pending)"
-
-Igniter::Server::Client.define_singleton_method(:new, &original_new)
-Igniter::Mesh.reset!
-puts
-
-puts "=== Scenario C: pinned_to routing — audit-node down (incident) ==="
-
-Igniter::Mesh.reset!
-Igniter::Mesh.configure do |c|
-  c.add_peer "audit-node",
-             url: "http://audit.internal:4567",
-             capabilities: [:audit]
-end
-
-Igniter::Server::Client.define_singleton_method(:new) do |url, **opts|
-  url == "http://audit.internal:4567" ? dead_client : original_new.call(url, **opts)
-end
-
-audit_contract = AuditPipeline.new(event: "order.created")
-begin
-  audit_contract.resolve_all
-rescue Igniter::Error
-  nil
-end
-
-audit_state = audit_contract.execution.cache.fetch(:audit_log)
-puts "  audit_log status: #{audit_state&.status.inspect}   (expected :failed)"
-puts "  error class:      #{audit_state&.error&.class}"
-puts "  error message:    #{audit_state&.error&.message}"
-
-Igniter::Server::Client.define_singleton_method(:new, &original_new)
-Igniter::Mesh.reset!
-puts
-
-# ── 6. GET /v1/manifest demo ─────────────────────────────────────────────────
-
-puts "=== Server manifest endpoint ==="
-
-Igniter::Server.configure do |c|
-  c.peer_name         = "orders-node"
-  c.peer_capabilities = %i[orders inventory]
-end
-
-registry = Igniter::Server::Registry.new
-registry.register("ProcessOrder", Class.new(Igniter::Contract))
-
-handler = Igniter::Server::Handlers::ManifestHandler.new(
-  registry,
-  Igniter::Runtime::Stores::MemoryStore.new,
-  config: Igniter::Server.config
-)
-
-result = handler.call(params: {}, body: {})
-manifest = JSON.parse(result[:body])
-puts "  peer_name:    #{manifest["peer_name"]}"
-puts "  capabilities: #{manifest["capabilities"].join(", ")}"
-puts "  contracts:    #{manifest["contracts"].join(", ")}"
-puts "  url:          #{manifest["url"]}"
-puts
-
-Igniter::Server.reset!
-
-puts "Done."

data/examples/mesh_discovery.rb

@@ -1,267 +0,0 @@
-# frozen_string_literal: true
-
-# Igniter Mesh — Phase 2: Dynamic Discovery
-#
-# Demonstrates how peers self-register at startup and how the local node
-# discovers topology without a static add_peer list.
-#
-# This example uses in-process stubs so no real HTTP servers are needed.
-
-require_relative "../lib/igniter/extensions/mesh"
-
-# ─── Shared contract ──────────────────────────────────────────────────────────
-class ProcessOrder < Igniter::Contract
-  define do
-    input :order_id
-    compute :status, depends_on: :order_id do |order_id:|
-      order_id > 0 ? "accepted" : "rejected"
-    end
-    output :status
-  end
-end
-
-# ─── Stub HTTP layer ──────────────────────────────────────────────────────────
-# In production each peer is a separate igniter-server process. Here we stub
-# the HTTP client so the example runs inline.
-
-module ClientStubs
-  PEERS = {
-    "http://orders-node-1:4567" => {
-      peer_name:    "orders-node-1",
-      capabilities: %i[orders inventory],
-      contracts:    ["ProcessOrder"],
-      alive:        true
-    },
-    "http://orders-node-2:4567" => {
-      peer_name:    "orders-node-2",
-      capabilities: %i[orders],
-      contracts:    ["ProcessOrder"],
-      alive:        true
-    },
-    "http://audit-node:4567" => {
-      peer_name:    "audit-node",
-      capabilities: %i[audit],
-      contracts:    ["WriteAudit"],
-      alive:        false  # <-- offline
-    },
-    "http://seed:4567" => {
-      peer_name:    "seed",
-      capabilities: [],
-      contracts:    [],
-      alive:        true,
-      # What the seed returns for GET /v1/mesh/peers:
-      known_peers: [
-        { name: "orders-node-1", url: "http://orders-node-1:4567", capabilities: ["orders", "inventory"] },
-        { name: "orders-node-2", url: "http://orders-node-2:4567", capabilities: ["orders"] },
-        { name: "audit-node",    url: "http://audit-node:4567",    capabilities: ["audit"] }
-      ]
-    }
-  }.freeze
-
-  def self.install!
-    Igniter::Server::Client.class_eval do
-      alias_method :real_health,        :health
-      alias_method :real_manifest,      :manifest
-      alias_method :real_list_peers,    :list_peers
-      alias_method :real_register_peer, :register_peer
-
-      def health
-        info = ClientStubs::PEERS[@base_url]
-        raise Igniter::Server::Client::ConnectionError, "offline" unless info && info[:alive]
-
-        { "status" => "ok" }
-      end
-
-      def manifest
-        info = ClientStubs::PEERS[@base_url] || {}
-        { peer_name: info[:peer_name], capabilities: info[:capabilities] || [],
-          contracts: info[:contracts] || [], url: @base_url }
-      end
-
-      def list_peers
-        info = ClientStubs::PEERS[@base_url] || {}
-        (info[:known_peers] || []).map do |p|
-          { name: p[:name], url: p[:url], capabilities: Array(p[:capabilities]).map(&:to_sym) }
-        end
-      end
-
-      def register_peer(name:, url:, capabilities: [])
-        puts "  [seed] registered peer: #{name} @ #{url} caps=#{capabilities}"
-        { "registered" => true }
-      end
-    end
-  end
-
-  def self.uninstall!
-    Igniter::Server::Client.class_eval do
-      alias_method :health,        :real_health
-      alias_method :manifest,      :real_manifest
-      alias_method :list_peers,    :real_list_peers
-      alias_method :register_peer, :real_register_peer
-    end
-  end
-end
-
-ClientStubs.install!
-
-# ─── Stub execute path ────────────────────────────────────────────────────────
-Igniter::Server::Client.class_eval do
-  alias_method :real_execute, :execute
-  def execute(contract_name, inputs: {})
-    order_id = inputs[:order_id] || inputs["order_id"] || 0
-    contract = ProcessOrder.new(order_id: order_id)
-    contract.resolve_all
-    { status: :succeeded, execution_id: "stub-#{order_id}",
-      outputs: { status: contract.result.status }, waiting_for: [], error: nil }
-  end
-end
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Scenario 1 — Dynamic topology discovery at startup
-# ─────────────────────────────────────────────────────────────────────────────
-puts "=" * 60
-puts "Scenario 1: Dynamic discovery from seed"
-puts "=" * 60
-
-Igniter::Mesh.configure do |c|
-  c.peer_name          = "api-node"
-  c.local_url          = "http://api-node:4567"
-  c.local_capabilities = %i[api]
-  c.seeds              = %w[http://seed:4567]
-  c.discovery_interval = 60
-end
-
-puts "\nBefore start_discovery!:"
-puts "  Dynamic peers: #{Igniter::Mesh.config.peer_registry.size}"
-
-Igniter::Mesh.start_discovery!
-
-puts "\nAfter start_discovery!:"
-puts "  Dynamic peers: #{Igniter::Mesh.config.peer_registry.size}"
-Igniter::Mesh.config.peer_registry.all.each do |p|
-  puts "  - #{p.name} @ #{p.url} caps=#{p.capabilities}"
-end
-puts
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Scenario 2 — Capability routing over discovered peers
-# ─────────────────────────────────────────────────────────────────────────────
-puts "=" * 60
-puts "Scenario 2: Capability routing to discovered peers"
-puts "=" * 60
-
-class OrderPipeline < Igniter::Contract
-  define do
-    input :order_id
-
-    remote :order_result,
-           contract:   "ProcessOrder",
-           capability: :orders,
-           inputs:     { order_id: :order_id }
-
-    output :order_result
-  end
-end
-
-results = [101, 102, 103].map do |id|
-  contract = OrderPipeline.new(order_id: id)
-  contract.resolve_all
-  status = contract.result.order_result[:status]
-  puts "  order_id=#{id} → status=#{status}"
-  status
-end
-
-puts "\nAll orders accepted: #{results.all? { |r| r == "accepted" }}"
-puts
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Scenario 3 — New peer joins mid-run (simulated via direct registration)
-# ─────────────────────────────────────────────────────────────────────────────
-puts "=" * 60
-puts "Scenario 3: New peer joins the mesh mid-run"
-puts "=" * 60
-
-# Simulate a new billing-node announcing itself via POST /v1/mesh/peers
-# In production this is done by the new peer calling start_discovery!
-new_peer = Igniter::Mesh::Peer.new(
-  name:         "billing-node",
-  url:          "http://billing-node:4567",
-  capabilities: %i[billing]
-)
-Igniter::Mesh.config.peer_registry.register(new_peer)
-
-puts "  Registered billing-node into local registry"
-puts "  Peers with :billing capability: #{Igniter::Mesh.config.peer_registry.peers_with_capability(:billing).map(&:name)}"
-puts
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Scenario 4 — Deferred when discovered peer is offline
-# ─────────────────────────────────────────────────────────────────────────────
-puts "=" * 60
-puts "Scenario 4: Capability routing → :pending when peer offline"
-puts "=" * 60
-
-class AuditPipeline < Igniter::Contract
-  define do
-    input :event
-
-    remote :audit_log,
-           contract:   "WriteAudit",
-           capability: :audit,
-           inputs:     { event: :event }
-
-    output :audit_log
-  end
-end
-
-contract = AuditPipeline.new(event: "order_placed")
-begin
-  contract.resolve_all
-rescue Igniter::Error
-  nil
-end
-
-cache = contract.execution.cache
-audit_state = cache.values.find { |s| s.node.name == :audit_log }
-puts "  audit_log node status: #{audit_state&.status || :unknown}"
-puts "  (audit-node is offline → capability routing defers → :pending)"
-puts
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Scenario 5 — Static + dynamic peers merged
-# ─────────────────────────────────────────────────────────────────────────────
-puts "=" * 60
-puts "Scenario 5: Static add_peer + dynamic discovery merged"
-puts "=" * 60
-
-Igniter::Mesh.stop_discovery!
-Igniter::Mesh.reset!
-
-Igniter::Mesh.configure do |c|
-  c.peer_name = "api-node"
-  c.local_url = "http://api-node:4567"
-  c.seeds     = %w[http://seed:4567]
-  c.discovery_interval = 60
-  # Static peer declared manually:
-  c.add_peer "legacy-node", url: "http://legacy:4567", capabilities: %i[billing]
-end
-
-Igniter::Mesh.start_discovery!
-
-static_names  = Igniter::Mesh.config.peers.map(&:name)
-dynamic_names = Igniter::Mesh.config.peer_registry.all.map(&:name)
-
-puts "  Static peers:  #{static_names}"
-puts "  Dynamic peers: #{dynamic_names}"
-puts "  Combined (via router):"
-all_orders = Igniter::Mesh.router.instance_eval { all_capable_peers(:orders) }.map(&:name)
-puts "    :orders capable peers: #{all_orders}"
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Cleanup
-# ─────────────────────────────────────────────────────────────────────────────
-Igniter::Mesh.stop_discovery!
-Igniter::Mesh.reset!
-ClientStubs.uninstall!
-
-puts "\nDone."

data/examples/mesh_gossip.rb

@@ -1,162 +0,0 @@
-# frozen_string_literal: true
-
-# Igniter Mesh — Phase 3: Gossip Protocol
-#
-# Demonstrates how peer topology spreads through gossip even when seeds
-# are unavailable. Three nodes form a mesh: A knows B, C only knows A.
-# After one gossip round C discovers B — without ever contacting a seed.
-#
-# This example uses in-process stubs so no real HTTP servers are needed.
-
-require_relative "../lib/igniter/extensions/mesh"
-
-# ─── Shared contract ──────────────────────────────────────────────────────────
-class CheckInventory < Igniter::Contract
-  define do
-    input :sku
-    compute :available, depends_on: :sku do |sku:|
-      sku.start_with?("VALID") ? true : false
-    end
-    output :available
-  end
-end
-
-# ─── Node registries (in-memory representation of three separate processes) ───
-#
-# node_a: knows B (via seed bootstrap)
-# node_b: fresh node with inventory capability
-# node_c: knows A (via seed bootstrap), does NOT know B yet
-#
-# After node_c gossips with node_a → it will learn about node_b.
-
-NODE_A = {
-  name: "node-a", url: "http://node-a:4567",
-  capabilities: %w[orders],
-  peers: [
-    { name: "node-b", url: "http://node-b:4567", capabilities: ["inventory"] }
-  ]
-}.freeze
-
-NODE_B = {
-  name: "node-b", url: "http://node-b:4567",
-  capabilities: %w[inventory],
-  peers: []
-}.freeze
-
-NODE_C = {
-  name: "node-c", url: "http://node-c:4567",
-  capabilities: %w[api],
-  peers: [
-    { name: "node-a", url: "http://node-a:4567", capabilities: ["orders"] }
-  ]
-}.freeze
-
-# ─── Stub HTTP layer ──────────────────────────────────────────────────────────
-# Stubs GET /v1/mesh/peers (list_peers) for each node URL.
-# No health checks or execute stubs needed for this scenario.
-
-PEER_DB = {
-  NODE_A[:url] => NODE_A,
-  NODE_B[:url] => NODE_B,
-  NODE_C[:url] => NODE_C
-}.freeze
-
-Igniter::Server::Client.class_eval do
-  alias_method :real_list_peers_gossip, :list_peers
-
-  def list_peers
-    info = PEER_DB[@base_url] || {}
-    (info[:peers] || []).map do |p|
-      { name: p[:name], url: p[:url], capabilities: Array(p[:capabilities]).map(&:to_sym) }
-    end
-  end
-end
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Scenario 1 — Baseline: C's registry before gossip
-# ─────────────────────────────────────────────────────────────────────────────
-puts "=" * 60
-puts "Scenario 1: C's registry before gossip"
-puts "=" * 60
-
-Igniter::Mesh.configure do |c|
-  c.peer_name          = NODE_C[:name]
-  c.local_url          = NODE_C[:url]
-  c.local_capabilities = NODE_C[:capabilities].map(&:to_sym)
-  c.gossip_fanout      = 3
-  c.discovery_interval = 60
-  c.seeds              = []   # no seeds — gossip only
-end
-
-# C initially knows A (as if bootstrapped from a seed earlier)
-Igniter::Mesh.config.peer_registry.register(
-  Igniter::Mesh::Peer.new(name: NODE_A[:name], url: NODE_A[:url], capabilities: NODE_A[:capabilities].map(&:to_sym))
-)
-
-puts "\nC's registry before gossip:"
-Igniter::Mesh.config.peer_registry.all.each do |p|
-  puts "  - #{p.name} @ #{p.url} caps=#{p.capabilities}"
-end
-
-knows_b_before = !Igniter::Mesh.config.peer_registry.peer_named("node-b").nil?
-puts "  C knows node-b? #{knows_b_before}"
-puts
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Scenario 2 — Gossip round: C contacts A, learns about B
-# ─────────────────────────────────────────────────────────────────────────────
-puts "=" * 60
-puts "Scenario 2: C runs one gossip round → discovers B via A"
-puts "=" * 60
-
-Igniter::Mesh::GossipRound.new(Igniter::Mesh.config).run
-
-puts "\nC's registry after gossip:"
-Igniter::Mesh.config.peer_registry.all.each do |p|
-  puts "  - #{p.name} @ #{p.url} caps=#{p.capabilities}"
-end
-
-knows_b_after = !Igniter::Mesh.config.peer_registry.peer_named("node-b").nil?
-puts "\n  C knows node-b? #{knows_b_after}"
-puts "  Convergence achieved without seed: #{knows_b_after}"
-puts
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Scenario 3 — gossip_fanout = 0 disables gossip
-# ─────────────────────────────────────────────────────────────────────────────
-puts "=" * 60
-puts "Scenario 3: gossip_fanout = 0 disables the gossip round"
-puts "=" * 60
-
-Igniter::Mesh.reset!
-
-Igniter::Mesh.configure do |c|
-  c.peer_name          = NODE_C[:name]
-  c.local_url          = NODE_C[:url]
-  c.gossip_fanout      = 0   # disabled
-  c.discovery_interval = 60
-  c.seeds              = []
-end
-
-# Seed registry with A
-Igniter::Mesh.config.peer_registry.register(
-  Igniter::Mesh::Peer.new(name: NODE_A[:name], url: NODE_A[:url], capabilities: NODE_A[:capabilities].map(&:to_sym))
-)
-
-before_size = Igniter::Mesh.config.peer_registry.size
-Igniter::Mesh::Poller.new(Igniter::Mesh.config).poll_once  # no seeds → no seed fetch; gossip disabled
-after_size  = Igniter::Mesh.config.peer_registry.size
-
-puts "  gossip_fanout = 0 → registry size unchanged: #{before_size} → #{after_size}"
-puts
-
-# ─────────────────────────────────────────────────────────────────────────────
-# Cleanup
-# ─────────────────────────────────────────────────────────────────────────────
-Igniter::Mesh.reset!
-
-Igniter::Server::Client.class_eval do
-  alias_method :list_peers, :real_list_peers_gossip
-end
-
-puts "Done."