igniter 0.4.3 → 0.5.0

data/lib/igniter/mesh/config.rb

@@ -0,0 +1,45 @@
+# 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/discovery.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Mesh
+    # Orchestrates the full dynamic-discovery lifecycle:
+    #
+    #   1. Announce self to all seeds (POST /v1/mesh/peers).
+    #   2. Immediately poll all seeds for their known peer list (GET /v1/mesh/peers).
+    #   3. Start the background Poller to keep the registry up to date.
+    #
+    # On #stop:
+    #   1. Deannounce self from all seeds (DELETE /v1/mesh/peers/:name), best-effort.
+    #   2. Stop the background Poller.
+    class Discovery
+      def initialize(config)
+        @config    = config
+        @announcer = Announcer.new(config)
+        @poller    = Poller.new(config)
+      end
+
+      def start
+        @announcer.announce_all
+        @poller.poll_once
+        @poller.start
+        self
+      end
+
+      def stop
+        @announcer.deannounce_all
+        @poller.stop
+        self
+      end
+
+      def running?
+        @poller.running?
+      end
+    end
+  end
+end

data/lib/igniter/mesh/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Mesh
+    # Raised when a capability-routed remote node has no alive peers.
+    # Inherits from PendingDependencyError so the resolver transitions
+    # the node to :pending (same as await/distributed workflow nodes).
+    class DeferredCapabilityError < Igniter::PendingDependencyError
+      attr_reader :capability
+
+      def initialize(capability, deferred_result, message = nil)
+        @capability = capability
+        super(deferred_result, message || "No alive peer with capability :#{capability}")
+      end
+    end
+
+    # Raised when a pinned_to peer is unavailable.
+    # Inherits from ResolutionError so the resolver transitions the node
+    # to :failed and surfaces it as an operational incident requiring
+    # manual intervention.
+    class IncidentError < Igniter::ResolutionError
+      attr_reader :peer_name
+
+      def initialize(peer_name, message = nil, context: {})
+        @peer_name = peer_name
+        super(message || "Pinned peer '#{peer_name}' is unreachable — manual intervention required",
+              context: context)
+      end
+    end
+  end
+end

data/lib/igniter/mesh/gossip.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Mesh
+    # Executes a single peer-to-peer gossip round.
+    #
+    # Picks up to config.gossip_fanout random peers from the local PeerRegistry
+    # (excluding self), fetches their GET /v1/mesh/peers lists, and registers
+    # any newly discovered peers. This decentralises topology exchange: once seeds
+    # bootstrap the registry, peers continue spreading topology information among
+    # themselves even if seeds become unavailable.
+    #
+    # Errors from individual peers are swallowed — a dead peer must not abort
+    # the round for the remaining candidates.
+    class GossipRound
+      def initialize(config)
+        @config = config
+      end
+
+      def run
+        pick_candidates.each { |peer| exchange_with(peer) }
+      end
+
+      private
+
+      def pick_candidates
+        @config.peer_registry.all
+               .reject { |p| p.url == @config.local_url }
+               .sample(@config.gossip_fanout)
+      end
+
+      def exchange_with(peer) # rubocop:disable Metrics/AbcSize
+        peers = Igniter::Server::Client.new(peer.url, timeout: 5).list_peers
+        peers.each do |pd|
+          next if pd[:name].nil? || pd[:url].nil?
+          next if pd[:name] == @config.peer_name
+
+          @config.peer_registry.register(
+            Peer.new(name: pd[:name], url: pd[:url], capabilities: pd[:capabilities] || [])
+          )
+        end
+      rescue Igniter::Server::Client::ConnectionError
+        nil
+      end
+    end
+  end
+end

data/lib/igniter/mesh/peer.rb

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

@@ -0,0 +1,51 @@
+# 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/poller.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Mesh
+    # Background thread that periodically fetches the peer list from every seed
+    # and populates the local PeerRegistry with newly discovered peers.
+    #
+    # - Errors from individual seeds are swallowed (seed may be temporarily down).
+    # - Does not remove peers from the registry on failure — the health cache in
+    #   Router handles routing around dead peers without purging known topology.
+    # - Thread is non-daemon: call #stop explicitly on shutdown (Discovery does this).
+    class Poller
+      def initialize(config)
+        @config  = config
+        @running = false
+        @thread  = nil
+        @mutex   = Mutex.new
+      end
+
+      # Start the background polling thread. Idempotent.
+      def start
+        @mutex.synchronize do
+          return if @running
+
+          @running = true
+          @thread  = Thread.new { run_loop }
+          @thread.abort_on_exception = false
+        end
+      end
+
+      # Stop the background thread. Idempotent.
+      def stop
+        @mutex.synchronize do
+          @running = false
+          @thread&.kill
+          @thread = nil
+        end
+      end
+
+      def running?
+        @mutex.synchronize { @running }
+      end
+
+      # Fetch peers from all seeds, then run a gossip round with random registry
+      # peers (Phase 3). Synchronous — used at startup and inside the background loop.
+      def poll_once
+        @config.seeds.each { |url| fetch_peers_from(url) }
+        GossipRound.new(@config).run if @config.gossip_fanout.positive?
+      end
+
+      private
+
+      def run_loop
+        loop do
+          sleep(@config.discovery_interval)
+          break unless @running
+
+          poll_once
+        end
+      end
+
+      def fetch_peers_from(seed_url)
+        peers = Igniter::Server::Client.new(seed_url, timeout: 5).list_peers
+        peers.each do |pd|
+          next if pd[:name].nil? || pd[:url].nil?
+          next if pd[:name] == @config.peer_name
+
+          @config.peer_registry.register(
+            Peer.new(name: pd[:name], url: pd[:url], capabilities: pd[:capabilities] || [])
+          )
+        end
+      rescue Igniter::Server::Client::ConnectionError
+        nil
+      end
+    end
+  end
+end

data/lib/igniter/mesh/router.rb

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

data/lib/igniter/mesh.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "mesh/errors"
+require_relative "mesh/peer"
+require_relative "mesh/peer_registry"
+require_relative "mesh/config"
+require_relative "mesh/router"
+require_relative "mesh/announcer"
+require_relative "mesh/poller"
+require_relative "mesh/discovery"
+require_relative "mesh/gossip"
+
+module Igniter
+  # Mesh routing for remote: nodes.
+  #
+  # Phase 1 — Static Mesh:
+  #   Declare peer topology via add_peer. capability: and pinned_to: routing
+  #   modes select alive peers at resolution time.
+  #
+  # Phase 2 — Dynamic Discovery:
+  #   Configure seed URLs and call start_discovery!. The local node announces
+  #   itself to seeds and polls them for the current peer list in the background.
+  #
+  # Usage:
+  #
+  #   require "igniter/extensions/mesh"
+  #
+  #   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   # seconds (default)
+  #
+  #     # Static peers still work alongside dynamic discovery:
+  #     c.add_peer "legacy-node",
+  #                url: "http://legacy.internal:4567",
+  #                capabilities: [:billing]
+  #   end
+  #
+  #   Igniter::Mesh.start_discovery!   # announce + poll + background thread
+  #   # …
+  #   Igniter::Mesh.stop_discovery!    # deannounce + stop thread (on shutdown)
+  module Mesh
+    class << self
+      def config
+        @config ||= Config.new
+      end
+
+      def configure
+        yield config
+        self
+      end
+
+      def router
+        @router ||= Router.new(config)
+      end
+
+      # Start dynamic discovery: announce self to seeds, do an immediate poll,
+      # then begin background polling at config.discovery_interval.
+      def start_discovery!
+        discovery.start
+        self
+      end
+
+      # Stop dynamic discovery: deannounce self from seeds, stop background thread.
+      def stop_discovery!
+        @discovery&.stop
+        @discovery = nil
+        self
+      end
+
+      def discovery
+        @discovery ||= Discovery.new(config)
+      end
+
+      # Reset all singletons (config, router, discovery). Useful in tests.
+      def reset!
+        stop_discovery!
+        @config = nil
+        @router = nil
+      end
+    end
+  end
+end

data/lib/igniter/metrics/collector.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Metrics
+    # Thread-safe event subscriber that collects execution-level metrics.
+    #
+    # Subscribes to an Igniter::Events::Bus (via the Events::Bus#subscribe interface)
+    # and maintains in-memory counters and histograms for:
+    #   - Total executions (by graph, by status)
+    #   - Execution duration histogram (by graph)
+    #   - HTTP request counts and durations (recorded directly by the server)
+    #
+    # All state is protected by a Mutex. Snapshot returns a frozen copy
+    # safe to read outside the lock.
+    class Collector
+      HISTOGRAM_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0].freeze
+
+      def initialize
+        @mutex = Mutex.new
+        @counters   = Hash.new(0)  # String(metric{labels}) → Integer
+        @histograms = {}           # String(metric_name) → Hash(label_key → histogram_entry)
+        @exec_start = {}           # execution_id → Time (for duration tracking)
+        @exec_graph = {}           # execution_id → graph_name
+      end
+
+      # Called by Events::Bus for every event emitted during an execution.
+      def call(event) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+        case event.type
+        when :execution_started   then on_execution_started(event)
+        when :execution_finished  then on_execution_finished(event, "succeeded")
+        when :execution_failed    then on_execution_finished(event, "failed")
+        end
+      end
+
+      # Record an HTTP request (called directly by the server/router).
+      def record_http(method:, path:, status:, duration:)
+        @mutex.synchronize do
+          inc("igniter_http_requests_total",
+              method: method, path: normalized_path(path), status: status.to_s)
+          observe_locked("igniter_http_request_duration_seconds", duration,
+                         method: method, path: normalized_path(path))
+        end
+      end
+
+      # Snapshot returns frozen copies of counters and histograms.
+      def snapshot
+        @mutex.synchronize do
+          Snapshot.new(
+            counters: @counters.dup.freeze,
+            histograms: deep_freeze(@histograms)
+          )
+        end
+      end
+
+      private
+
+      def on_execution_started(event)
+        @mutex.synchronize do
+          @exec_start[event.execution_id] = event.timestamp
+          @exec_graph[event.execution_id] = event.payload[:graph].to_s
+        end
+      end
+
+      def on_execution_finished(event, status)
+        @mutex.synchronize do
+          graph      = @exec_graph.delete(event.execution_id) || event.payload[:graph].to_s
+          started_at = @exec_start.delete(event.execution_id)
+
+          inc("igniter_executions_total", graph: graph, status: status)
+
+          if started_at
+            duration = event.timestamp - started_at
+            observe_locked("igniter_execution_duration_seconds", duration, graph: graph)
+          end
+        end
+      end
+
+      def inc(name, labels)
+        @counters[metric_key(name, labels)] += 1
+      end
+
+      def observe_locked(name, value, labels)
+        lkey = label_key(labels)
+        @histograms[name] ||= {}
+        entry = @histograms[name][lkey] ||= new_histogram_entry(labels)
+        HISTOGRAM_BUCKETS.each { |b| entry[:buckets][b] += 1 if value <= b }
+        entry[:sum] += value
+        entry[:count] += 1
+      end
+
+      def new_histogram_entry(labels)
+        { labels: labels, buckets: Hash.new(0), sum: 0.0, count: 0 }
+      end
+
+      def metric_key(name, labels)
+        "#{name}#{label_selector(labels)}"
+      end
+
+      def label_key(labels)
+        label_selector(labels)
+      end
+
+      def label_selector(labels)
+        return "" if labels.empty?
+
+        pairs = labels.map { |k, v| "#{k}=\"#{v}\"" }.join(",")
+        "{#{pairs}}"
+      end
+
+      def normalized_path(path)
+        # Collapse dynamic path segments to avoid high-cardinality labels
+        path.to_s
+            .gsub(%r{/v1/contracts/[^/]+/}, "/v1/contracts/:name/")
+            .gsub(%r{/v1/executions/[^/]+}, "/v1/executions/:id")
+      end
+
+      def deep_freeze(hash)
+        hash.each_with_object({}) do |(name, by_label), memo|
+          memo[name] = by_label.each_with_object({}) do |(lkey, entry), inner|
+            inner[lkey] = {
+              labels: entry[:labels].dup.freeze,
+              buckets: entry[:buckets].dup.freeze,
+              sum: entry[:sum],
+              count: entry[:count]
+            }.freeze
+          end.freeze
+        end.freeze
+      end
+    end
+  end
+end