igniter 0.4.3 → 0.5.0

data/lib/igniter/replication/replication_agent.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "../agent"
+
+module Igniter
+  module Replication
+    # Agent that handles :replicate messages to deploy Igniter to remote servers.
+    #
+    # In production, start via ReplicationAgent.start and send messages through
+    # the Ref. In tests, instantiate directly and call handle_message/1.
+    #
+    # Message payload keys:
+    #   host:                  [String]  (required) remote hostname or IP
+    #   user:                  [String]  (required) SSH username
+    #   key:                   [String]  path to SSH private key (optional)
+    #   port:                  [Integer] SSH port (default: 22)
+    #   env:                   [Hash]    environment variables for remote (default: {})
+    #   strategy:              [Symbol]  :git, :gem, or :tarball (default: :git)
+    #   target_path:           [String]  installation path on remote (default: /opt/igniter)
+    #   bootstrapper_options:  [Hash]    forwarded to the bootstrapper constructor
+    #
+    class ReplicationAgent < Igniter::Agent
+      MAX_REPLICAS = 10
+
+      initial_state events: []
+
+      # Class-level handler for the agent mailbox runtime.
+      # Instantiates a temporary agent to run the replication so that
+      # deliver/1 can be overridden in subclasses.
+      on :replicate do |state:, payload:, **|
+        agent = new
+        agent.send(:run_replicate, payload)
+        state
+      end
+
+      # Emit a named lifecycle event. Override or stub in tests.
+      #
+      # @param type    [Symbol] event name (e.g. :replication_started)
+      # @param payload [Hash]   associated data
+      def deliver(type, payload = {})
+        # Base implementation: no-op. Override in subclasses for real routing.
+      end
+
+      # Process a raw message hash synchronously (used in tests and internal tooling).
+      #
+      # @param message [Hash] must have :type key; optional :payload key
+      def handle_message(message)
+        type    = message.fetch(:type).to_sym
+        payload = message.fetch(:payload, {})
+        return unless type == :replicate
+
+        run_replicate(payload)
+      end
+
+      private
+
+      def run_replicate(payload) # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
+        host        = payload[:host]        || raise(ArgumentError, "host is required")
+        user        = payload[:user]        || raise(ArgumentError, "user is required")
+        key         = payload[:key]
+        port        = payload.fetch(:port, 22)
+        env         = payload.fetch(:env, {})
+        strategy    = payload.fetch(:strategy, :git).to_sym
+        target_path = payload.fetch(:target_path, "/opt/igniter")
+        bs_options  = payload.fetch(:bootstrapper_options, {})
+
+        session      = SSHSession.new(host: host, user: user, key: key, port: port)
+        bootstrapper = Replication.bootstrapper_for(strategy, **bs_options)
+        manifest     = Manifest.current
+
+        deliver(:replication_started, host: host, instance_id: manifest.instance_id)
+
+        bootstrapper.install(session: session, manifest: manifest,
+                             env: env, target_path: target_path)
+        bootstrapper.start(session: session, manifest: manifest, target_path: target_path)
+        verified = bootstrapper.verify(session: session, target_path: target_path)
+
+        deliver(:replication_completed,
+                host: host, instance_id: manifest.instance_id, verified: verified)
+      rescue SSHSession::SSHError => e
+        deliver(:replication_failed, host: host, error: e.message)
+      rescue ArgumentError => e
+        deliver(:replication_failed, host: payload[:host], error: e.message)
+      end
+    end
+  end
+end

data/lib/igniter/replication/role_registry.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Replication
+    # Module-level registry of named NodeRoles.
+    #
+    # @example
+    #   RoleRegistry.define(:worker,
+    #     contracts:     ["ComputeContract"],
+    #     capabilities:  [:compute],
+    #     env_overrides: { "WORKER_POOL" => "4" }
+    #   )
+    #
+    #   role = RoleRegistry.fetch(:worker)
+    #   role.env_overrides  # => { "WORKER_POOL" => "4" }
+    module RoleRegistry
+      @roles = {}
+
+      class << self
+        # Define and register a new role.
+        #
+        # @param name          [Symbol, String]
+        # @param contracts     [Array<String>]
+        # @param capabilities  [Array<Symbol>]
+        # @param env_overrides [Hash]
+        # @param tags          [Array<Symbol>]
+        # @return [NodeRole]
+        def define(name, contracts: [], capabilities: [], env_overrides: {}, tags: [])
+          role = NodeRole.new(
+            name:          name,
+            contracts:     contracts,
+            capabilities:  capabilities,
+            env_overrides: env_overrides,
+            tags:          tags
+          )
+          @roles[role.name] = role
+        end
+
+        # Fetch a role by name.
+        #
+        # @param name [Symbol, String]
+        # @return [NodeRole]
+        # @raise [ArgumentError] if not registered
+        def fetch(name)
+          @roles.fetch(name.to_sym) do
+            raise ArgumentError,
+                  "Unknown role: #{name}. Available: #{@roles.keys.join(", ")}"
+          end
+        end
+
+        # Returns true if a role with the given name is registered.
+        #
+        # @param name [Symbol, String]
+        # @return [Boolean]
+        def registered?(name)
+          @roles.key?(name.to_sym)
+        end
+
+        # All registered roles (copy to prevent external mutation).
+        #
+        # @return [Hash{Symbol => NodeRole}]
+        def all
+          @roles.dup
+        end
+
+        # Remove all registrations. Useful in tests.
+        def reset!
+          @roles = {}
+        end
+      end
+    end
+  end
+end

data/lib/igniter/replication/ssh_session.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Igniter
+  module Replication
+    # Thin subprocess wrapper over the +ssh+ and +scp+ CLI tools.
+    #
+    # Provides exec/exec! for running remote commands and upload! for
+    # copying local files to the remote host. No external gems required.
+    class SSHSession
+      class SSHError < Igniter::Error; end
+
+      DEFAULT_CONNECT_TIMEOUT = 10
+
+      def initialize(host:, user:, key: nil, port: 22, connect_timeout: DEFAULT_CONNECT_TIMEOUT)
+        @host            = host
+        @user            = user
+        @key             = key
+        @port            = port
+        @connect_timeout = connect_timeout
+      end
+
+      # Run a command on the remote host. Raises SSHError on non-zero exit.
+      # Returns stdout string on success.
+      def exec!(command)
+        result = exec(command)
+        raise SSHError, "SSH command failed on #{@host}: #{command.inspect}\n#{result[:stderr]}" \
+          unless result[:success]
+
+        result[:stdout]
+      end
+
+      # Run a command on the remote host.
+      # Returns a Hash: { stdout:, stderr:, success:, exit_code: }
+      def exec(command)
+        stdout, stderr, status = Open3.capture3(*build_cmd(command))
+        { stdout: stdout, stderr: stderr, success: status.success?, exit_code: status.exitstatus }
+      end
+
+      # Upload a local file to the remote host via scp.
+      # Raises SSHError on failure.
+      def upload!(local_path, remote_path)
+        args = ["scp", *scp_opts, "-P", @port.to_s, local_path, "#{@user}@#{@host}:#{remote_path}"]
+        _, stderr, status = Open3.capture3(*args)
+        raise SSHError, "SCP upload failed to #{@host}: #{stderr}" unless status.success?
+      end
+
+      # Quick connectivity test. Returns true if the remote responds.
+      def test_connection
+        exec("echo ok")[:success]
+      end
+
+      private
+
+      def build_cmd(command)
+        ["ssh", *ssh_opts, "-p", @port.to_s, "#{@user}@#{@host}", command]
+      end
+
+      def ssh_opts
+        opts = [
+          "-o", "StrictHostKeyChecking=no",
+          "-o", "BatchMode=yes",
+          "-o", "ConnectTimeout=#{@connect_timeout}"
+        ]
+        opts += ["-i", @key] if @key
+        opts
+      end
+
+      def scp_opts
+        opts = ["-o", "StrictHostKeyChecking=no", "-B"]
+        opts += ["-i", @key] if @key
+        opts
+      end
+    end
+  end
+end

data/lib/igniter/replication.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "replication/manifest"
+require_relative "replication/ssh_session"
+require_relative "replication/bootstrapper"
+require_relative "replication/bootstrappers/git"
+require_relative "replication/bootstrappers/gem"
+require_relative "replication/bootstrappers/tarball"
+require_relative "replication/replication_agent"
+require_relative "replication/node_role"
+require_relative "replication/role_registry"
+require_relative "replication/network_topology"
+require_relative "replication/expansion_plan"
+require_relative "replication/expansion_planner"
+require_relative "replication/reflective_replication_agent"
+
+module Igniter
+  # Self-replication capability: deploy a running Igniter instance to a
+  # remote server via SSH using one of three deployment strategies.
+  #
+  # Usage:
+  #   require "igniter/replication"
+  #   ref = Igniter::Replication::ReplicationAgent.start
+  #   ref.send(:replicate,
+  #     host:     "10.0.0.2",
+  #     user:     "deploy",
+  #     strategy: :git,
+  #     bootstrapper_options: { repo_url: "https://github.com/org/app" }
+  #   )
+  #
+  module Replication
+    ReplicationError = Class.new(Igniter::Error)
+
+    BOOTSTRAPPERS = {
+      git: Bootstrappers::Git,
+      gem: Bootstrappers::Gem,
+      tarball: Bootstrappers::Tarball
+    }.freeze
+
+    # Instantiate the bootstrapper for the given strategy.
+    #
+    # @param strategy [Symbol] one of :git, :gem, :tarball
+    # @param options  [Hash]   forwarded to the bootstrapper constructor
+    # @return [Bootstrapper]
+    # @raise [ArgumentError] for unknown strategies
+    def self.bootstrapper_for(strategy, **options)
+      klass = BOOTSTRAPPERS.fetch(strategy.to_sym) do
+        raise ArgumentError,
+              "Unknown bootstrapper: #{strategy}. Available: #{BOOTSTRAPPERS.keys.join(", ")}"
+      end
+      klass.new(**options)
+    end
+  end
+end

data/lib/igniter/runtime/cache.rb

@@ -13,24 +13,27 @@ module Igniter
         @mutex.synchronize { @states[node_name.to_sym] }
       end
 
-      def write(state)
+      def write(state) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         @mutex.synchronize do
           current = @states[state.node.name]
           version = state.version || (current&.running? ? current.version : next_version(current))
+          value_version = compute_value_version(state, current)
           @states[state.node.name] = NodeState.new(
             node: state.node,
             status: state.status,
             value: state.value,
             error: state.error,
             version: version,
+            value_version: value_version,
             resolved_at: state.resolved_at,
-            invalidated_by: state.invalidated_by
+            invalidated_by: state.invalidated_by,
+            dep_snapshot: state.dep_snapshot
           )
           @condition.broadcast
         end
       end
 
-      def begin_resolution(node)
+      def begin_resolution(node) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         @mutex.synchronize do
           loop do
             current = @states[node.name]
@@ -43,8 +46,10 @@ module Igniter
                 value: current&.value,
                 error: current&.error,
                 version: next_version(current),
+                value_version: current&.value_version,
                 resolved_at: current&.resolved_at || Time.now.utc,
-                invalidated_by: nil
+                invalidated_by: nil,
+                dep_snapshot: current&.dep_snapshot
               )
               return [:started, @states[node.name]]
             end
@@ -54,7 +59,7 @@ module Igniter
         end
       end
 
-      def stale!(node, invalidated_by:)
+      def stale!(node, invalidated_by:) # rubocop:disable Metrics/MethodLength
         @mutex.synchronize do
           current = @states[node.name]
           return unless current
@@ -65,8 +70,10 @@ module Igniter
             value: current.value,
             error: current.error,
             version: current.version + 1,
+            value_version: current.value_version,
             resolved_at: current.resolved_at,
-            invalidated_by: invalidated_by
+            invalidated_by: invalidated_by,
+            dep_snapshot: current.dep_snapshot
           )
           @condition.broadcast
         end
@@ -92,6 +99,28 @@ module Igniter
       def next_version(current)
         current ? current.version + 1 : 1
       end
+
+      # value_version only increments when the actual value changes.
+      # When state.value_version is set explicitly (backdating from resolver), use it.
+      # For :succeeded states, compare the new value against the old value:
+      #   - same value → preserve value_version
+      #   - different (or first time) → increment
+      # For all other statuses (failed, pending, etc.) → no value_version.
+      def compute_value_version(state, current)
+        return state.value_version if state.value_version
+
+        return nil unless state.status == :succeeded
+
+        base_vv = current&.value_version || 0
+        # When current is :running, current.value holds the pre-stale value for comparison.
+        old_value = current&.value
+
+        if base_vv.positive? && old_value == state.value
+          base_vv
+        else
+          base_vv + 1
+        end
+      end
     end
   end
 end

data/lib/igniter/runtime/execution.rb

@@ -59,6 +59,24 @@ module Igniter
         self
       end
 
+      # Returns the DiffState for an incremental collection node (created on first access).
+      # Persists across update_inputs calls for the lifetime of this Execution.
+      def diff_state_for(node_name)
+        @diff_states ||= {}
+        @diff_states[node_name.to_sym] ||= Igniter::Dataflow::DiffState.new
+      end
+
+
+      # Returns the AggregateState for an aggregate node (created on first access).
+      # Persists across update_inputs calls for the lifetime of this Execution.
+      def aggregate_state_for(node_name)
+        @aggregate_states ||= {}
+        @aggregate_states[node_name.to_sym] ||= begin
+          node = compiled_graph.fetch_node(node_name)
+          Igniter::Dataflow::AggregateState.new(node.operator)
+        end
+      end
+
       def resume(node_name, value:)
         node = compiled_graph.fetch_node(node_name)
         current = cache.fetch(node.name)
@@ -251,10 +269,12 @@ module Igniter
           memo[node_name] = {
             status: state.status,
             version: state.version,
+            value_version: state.value_version,
             resolved_at: state.resolved_at&.iso8601,
             invalidated_by: state.invalidated_by,
             value: serialize_state_value(state.value),
-            error: serialize_state_error(state.error)
+            error: serialize_state_error(state.error),
+            dep_snapshot: state.dep_snapshot
           }
         end
       end
@@ -262,14 +282,18 @@ module Igniter
       def deserialize_states(snapshot_states)
         snapshot_states.each_with_object({}) do |(node_name, state_data), memo|
           node = compiled_graph.fetch_node(node_name)
+          raw_dep_snapshot = state_data[:dep_snapshot] || state_data["dep_snapshot"]
+          dep_snapshot = raw_dep_snapshot&.transform_keys(&:to_sym)
           memo[node.name] = NodeState.new(
             node: node,
             status: (state_data[:status] || state_data["status"]).to_sym,
             value: deserialize_state_value(node, state_data[:value] || state_data["value"]),
             error: deserialize_state_error(state_data[:error] || state_data["error"]),
             version: state_data[:version] || state_data["version"],
+            value_version: state_data[:value_version] || state_data["value_version"],
             resolved_at: deserialize_time(state_data[:resolved_at] || state_data["resolved_at"]),
-            invalidated_by: (state_data[:invalidated_by] || state_data["invalidated_by"])&.to_sym
+            invalidated_by: (state_data[:invalidated_by] || state_data["invalidated_by"])&.to_sym,
+            dep_snapshot: dep_snapshot
           )
         end
       end

data/lib/igniter/runtime/input_validator.rb

@@ -64,7 +64,8 @@ module Igniter
           next if inputs.key?(node.name)
           next unless node.default?
 
-          inputs[node.name] = node.default
+          d = node.default
+          inputs[node.name] = d.respond_to?(:call) ? d.call : d
         end
       end
 
@@ -77,7 +78,10 @@ module Igniter
       end
 
       def missing_value!(input_node)
-        return input_node.default if input_node.default?
+        if input_node.default?
+          d = input_node.default
+          return d.respond_to?(:call) ? d.call : d
+        end
         return nil unless input_node.required?
 
         raise input_error(input_node, "Missing required input: #{input_node.name}")

data/lib/igniter/runtime/node_state.rb

@@ -3,16 +3,20 @@
 module Igniter
   module Runtime
     class NodeState
-      attr_reader :node, :status, :value, :error, :version, :resolved_at, :invalidated_by
+      attr_reader :node, :status, :value, :error, :version, :value_version,
+                  :resolved_at, :invalidated_by, :dep_snapshot
 
-      def initialize(node:, status:, value: nil, error: nil, version: nil, resolved_at: Time.now.utc, invalidated_by: nil)
+      def initialize(node:, status:, value: nil, error: nil, version: nil, value_version: nil, # rubocop:disable Metrics/ParameterLists
+                     resolved_at: Time.now.utc, invalidated_by: nil, dep_snapshot: nil)
         @node = node
         @status = status
         @value = value
         @error = error
         @version = version
+        @value_version = value_version
         @resolved_at = resolved_at
         @invalidated_by = invalidated_by
+        @dep_snapshot = dep_snapshot
       end
 
       def stale?
@@ -40,6 +44,7 @@ module Igniter
           node_name: node.name,
           status: status,
           version: version,
+          value_version: value_version,
           resolved_at: resolved_at,
           invalidated_by: invalidated_by,
           value: value,