igniter 0.4.5 → 0.5.0

data/examples/mesh.rb

@@ -0,0 +1,239 @@
+# 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

@@ -0,0 +1,267 @@
+# 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

@@ -0,0 +1,162 @@
+# 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."

data/examples/ringcentral_routing.rb

@@ -123,7 +123,7 @@ class CallConnectedContract < Igniter::Contract
       calls.successes.values.map { |item| item.result.summary }
     end
 
-    aggregate :routing_summary, with: %i[calls call_summaries extension_id telephony_status has_calls] do |calls:, call_summaries:, extension_id:, telephony_status:, has_calls:|
+    compute :routing_summary, with: %i[calls call_summaries extension_id telephony_status has_calls] do |calls:, call_summaries:, extension_id:, telephony_status:, has_calls:|
       has_calls
       {
         extension_id: extension_id,