igniter 0.5.0 → 0.5.2

data/lib/igniter/mesh/poller.rb

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

@@ -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

data/lib/igniter/mesh.rb

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

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

data/lib/igniter/metrics/prometheus_exporter.rb

@@ -1,104 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Metrics
-    # Formats a Collector snapshot into Prometheus text exposition format (0.0.4).
-    #
-    # https://prometheus.io/docs/instrumenting/exposition_formats/
-    #
-    # Usage:
-    #   exporter = PrometheusExporter.new(collector, store: store, registry: registry)
-    #   text = exporter.export          # → String in Prometheus text format
-    #   content_type = exporter.content_type
-    class PrometheusExporter
-      CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
-
-      COUNTER_META = {
-        "igniter_executions_total" =>
-          "Total contract executions completed",
-        "igniter_http_requests_total" =>
-          "Total HTTP requests received by igniter-server"
-      }.freeze
-
-      HISTOGRAM_META = {
-        "igniter_execution_duration_seconds" =>
-          "Contract execution duration in seconds",
-        "igniter_http_request_duration_seconds" =>
-          "HTTP request processing duration in seconds"
-      }.freeze
-
-      def initialize(collector, store:, registry:)
-        @collector = collector
-        @store     = store
-        @registry  = registry
-      end
-
-      def content_type
-        CONTENT_TYPE
-      end
-
-      def export # rubocop:disable Metrics/MethodLength
-        snap  = @collector.snapshot
-        lines = []
-
-        emit_counters(lines, snap.counters)
-        emit_histograms(lines, snap.histograms)
-        emit_pending_gauge(lines)
-
-        lines.join("\n") + "\n"
-      end
-
-      private
-
-      def emit_counters(lines, counters) # rubocop:disable Metrics/MethodLength
-        by_metric = counters.each_with_object(Hash.new { |h, k| h[k] = [] }) do |(key, val), memo|
-          name = key.split("{").first
-          memo[name] << [key, val]
-        end
-
-        by_metric.each do |name, entries|
-          lines << "# HELP #{name} #{COUNTER_META.fetch(name, name)}"
-          lines << "# TYPE #{name} counter"
-          entries.each { |key, val| lines << "#{key} #{val}" }
-          lines << ""
-        end
-      end
-
-      def emit_histograms(lines, histograms)
-        histograms.each do |name, by_label|
-          lines << "# HELP #{name} #{HISTOGRAM_META.fetch(name, name)}"
-          lines << "# TYPE #{name} histogram"
-          by_label.each_value { |entry| emit_histogram_entry(lines, name, entry) }
-          lines << ""
-        end
-      end
-
-      def emit_histogram_entry(lines, name, entry) # rubocop:disable Metrics/MethodLength
-        lstr = entry[:labels].map { |k, v| "#{k}=\"#{v}\"" }.join(",")
-        sep  = lstr.empty? ? "" : ","
-
-        Collector::HISTOGRAM_BUCKETS.each do |b|
-          le = b.to_s
-          lines << "#{name}_bucket{#{lstr}#{sep}le=\"#{le}\"} #{entry[:buckets][b]}"
-        end
-        lines << "#{name}_bucket{#{lstr}#{sep}le=\"+Inf\"} #{entry[:count]}"
-        lines << "#{name}_sum{#{lstr}} #{format("%.6f", entry[:sum])}"
-        lines << "#{name}_count{#{lstr}} #{entry[:count]}"
-      end
-
-      def emit_pending_gauge(lines) # rubocop:disable Metrics/MethodLength
-        lines << "# HELP igniter_pending_executions Currently pending executions in store"
-        lines << "# TYPE igniter_pending_executions gauge"
-
-        @registry.names.each do |name|
-          count = @store.list_pending(graph: name).size
-          lines << "igniter_pending_executions{graph=\"#{name}\"} #{count}"
-        rescue StandardError
-          lines << "igniter_pending_executions{graph=\"#{name}\"} 0"
-        end
-
-        lines << ""
-      end
-    end
-  end
-end

data/lib/igniter/metrics/snapshot.rb

@@ -1,8 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Metrics
-    # Immutable snapshot of collected metrics, safe to read from any thread.
-    Snapshot = Struct.new(:counters, :histograms, keyword_init: true)
-  end
-end

data/lib/igniter/metrics.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-require "igniter"
-require "igniter/metrics/snapshot"
-require "igniter/metrics/collector"
-require "igniter/metrics/prometheus_exporter"
-
-module Igniter
-  # Metrics collection for Igniter contracts and igniter-server.
-  #
-  # The Collector subscribes to an Igniter::Events::Bus and maintains
-  # in-memory counters and histograms with zero external dependencies.
-  #
-  # Prometheus text format is exported via PrometheusExporter — usable
-  # directly in the /v1/metrics endpoint of igniter-server.
-  #
-  # Usage (standalone):
-  #   require "igniter/metrics"
-  #
-  #   collector = Igniter::Metrics::Collector.new
-  #   contract.execution.events.subscribe(collector)
-  #   contract.resolve_all
-  #
-  #   exporter = Igniter::Metrics::PrometheusExporter.new(
-  #     collector, store: store, registry: registry
-  #   )
-  #   puts exporter.export
-  #
-  # Usage (igniter-server — automatic when metrics_collector is set):
-  #   Igniter::Server.configure do |c|
-  #     c.metrics_collector = Igniter::Metrics::Collector.new
-  #   end
-  #
-  module Metrics
-    class MetricsError < Igniter::Error; end
-  end
-end

data/lib/igniter/model/aggregate_node.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Model
-    # Represents a maintained aggregate node in the computation graph.
-    #
-    # An AggregateNode computes an aggregate value over an incremental collection
-    # and updates it in O(change) time by processing only the diff (added/changed/removed
-    # items) rather than iterating over the entire collection on every resolve.
-    #
-    # Supported built-in operators: :count, :sum, :avg, :min, :max, :group_count.
-    # Custom aggregates can be defined with initial:, add:, and remove: lambdas.
-    #
-    # The aggregate node depends on exactly one upstream incremental collection node.
-    # The compiler validates this at definition time.
-    class AggregateNode < Node
-      attr_reader :source_collection, :operator
-
-      def initialize(id:, name:, source_collection:, operator:, # rubocop:disable Metrics/ParameterLists
-                     path: nil, metadata: {})
-        super(
-          id: id,
-          kind: :aggregate,
-          name: name,
-          path: path || name.to_s,
-          dependencies: [source_collection],
-          metadata: metadata
-        )
-        @source_collection = source_collection.to_sym
-        @operator = operator
-      end
-    end
-  end
-end

data/lib/igniter/model/await_node.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Model
-    class AwaitNode < Node
-      attr_reader :event_name
-
-      def initialize(id:, name:, event_name:, path: nil, metadata: {})
-        super(
-          id: id,
-          kind: :await,
-          name: name,
-          path: path || name.to_s,
-          dependencies: [],
-          metadata: metadata
-        )
-        @event_name = event_name.to_sym
-      end
-    end
-  end
-end

data/lib/igniter/model/branch_node.rb

@@ -1,46 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Model
-    class BranchNode < Node
-      attr_reader :selector_dependency, :cases, :default_contract, :input_mapping, :context_dependencies, :input_mapper
-
-      def initialize(id:, name:, selector_dependency:, cases:, default_contract:, input_mapping:, context_dependencies: [], input_mapper: nil, path: nil, metadata: {})
-        dependencies = ([selector_dependency] + input_mapping.values + context_dependencies).uniq
-
-        super(
-          id: id,
-          kind: :branch,
-          name: name,
-          path: (path || name),
-          dependencies: dependencies,
-          metadata: metadata
-        )
-
-        @selector_dependency = selector_dependency.to_sym
-        @cases = cases.map { |entry| normalize_case(entry) }.freeze
-        @default_contract = default_contract
-        @input_mapping = input_mapping.transform_keys(&:to_sym).transform_values(&:to_sym).freeze
-        @context_dependencies = Array(context_dependencies).map(&:to_sym).freeze
-        @input_mapper = input_mapper
-      end
-
-      def possible_contracts
-        (cases.map { |entry| entry[:contract] } + [default_contract]).uniq
-      end
-
-      def input_mapper?
-        !input_mapper.nil?
-      end
-
-      private
-
-      def normalize_case(entry)
-        {
-          match: entry.fetch(:match),
-          contract: entry.fetch(:contract)
-        }
-      end
-    end
-  end
-end

data/lib/igniter/model/collection_node.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module Igniter
-  module Model
-    class CollectionNode < Node
-      attr_reader :source_dependency, :contract_class, :key_name, :mode, :window, :context_dependencies, :input_mapper
-
-      def initialize(id:, name:, source_dependency:, contract_class:, key_name:, mode:, window: nil, context_dependencies: [], input_mapper: nil, path: nil, metadata: {})
-        super(
-          id: id,
-          kind: :collection,
-          name: name,
-          path: (path || name),
-          dependencies: [source_dependency, *context_dependencies],
-          metadata: metadata
-        )
-
-        @source_dependency = source_dependency.to_sym
-        @contract_class = contract_class
-        @key_name = key_name.to_sym
-        @mode = mode.to_sym
-        @window = window
-        @context_dependencies = Array(context_dependencies).map(&:to_sym)
-        @input_mapper = input_mapper
-      end
-
-      def input_mapper?
-        !input_mapper.nil?
-      end
-    end
-  end
-end