igniter 0.4.5 → 0.5.0

data/lib/igniter/replication/network_topology.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Replication
+    # Thread-safe in-memory registry of known nodes in the deployment network.
+    #
+    # Updated by ReflectiveReplicationAgent as nodes are spawned, heartbeat-ed,
+    # or removed. Can be shared across agent handler invocations via state.
+    #
+    # @example
+    #   topology = NetworkTopology.new
+    #   topology.register(node_id: "abc", host: "10.0.0.2", role: :worker)
+    #   topology.nodes(role: :worker)      # => [NodeEntry]
+    #   topology.needs_role?(:coordinator) # => true
+    class NetworkTopology
+      # Mutable record for a single live node (mutated only inside the Mutex).
+      NodeEntry = Struct.new(:node_id, :host, :role,
+                             :registered_at, :last_seen_at, :healthy,
+                             keyword_init: true)
+
+      def initialize
+        @nodes = {}
+        @mutex = Mutex.new
+      end
+
+      # Register or overwrite a node entry.
+      #
+      # @param node_id [String]
+      # @param host    [String]
+      # @param role    [Symbol, nil]
+      # @return [NodeEntry]
+      def register(node_id:, host:, role: nil)
+        now   = Time.now
+        entry = NodeEntry.new(
+          node_id:       node_id,
+          host:          host,
+          role:          role&.to_sym,
+          registered_at: now,
+          last_seen_at:  now,
+          healthy:       true
+        )
+        @mutex.synchronize { @nodes[node_id] = entry }
+        entry
+      end
+
+      # Update last_seen_at for a known node (heartbeat).
+      #
+      # @param node_id [String]
+      # @return [Boolean] true if the node was found
+      def touch(node_id:)
+        @mutex.synchronize do
+          entry = @nodes[node_id]
+          return false unless entry
+
+          entry.last_seen_at = Time.now
+          true
+        end
+      end
+
+      # Mark a node as unhealthy (e.g. SSH unreachable).
+      #
+      # @param node_id [String]
+      # @return [Boolean] true if the node was found
+      def mark_unhealthy(node_id:)
+        @mutex.synchronize do
+          entry = @nodes[node_id]
+          return false unless entry
+
+          entry.healthy = false
+          true
+        end
+      end
+
+      # Remove a node from the topology.
+      #
+      # @param node_id [String]
+      # @return [NodeEntry, nil] the removed entry, or nil if not found
+      def remove(node_id:)
+        @mutex.synchronize { @nodes.delete(node_id) }
+      end
+
+      # Return nodes, optionally filtered by role.
+      #
+      # @param role [Symbol, nil]
+      # @return [Array<NodeEntry>]
+      def nodes(role: nil)
+        @mutex.synchronize do
+          entries = @nodes.values.dup
+          role ? entries.select { |e| e.role == role.to_sym } : entries
+        end
+      end
+
+      # True when no healthy node with the given role exists.
+      #
+      # @param role [Symbol, String]
+      # @return [Boolean]
+      def needs_role?(role)
+        nodes(role: role).none?(&:healthy)
+      end
+
+      # Count of healthy nodes across all roles.
+      #
+      # @return [Integer]
+      def healthy_count
+        @mutex.synchronize { @nodes.values.count(&:healthy) }
+      end
+
+      # Total number of registered nodes.
+      #
+      # @return [Integer]
+      def size
+        @mutex.synchronize { @nodes.size }
+      end
+
+      # All registered node IDs.
+      #
+      # @return [Array<String>]
+      def node_ids
+        @mutex.synchronize { @nodes.keys.dup }
+      end
+    end
+  end
+end

data/lib/igniter/replication/node_role.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Igniter
+  module Replication
+    # Immutable description of a specialised role a differentiated node can assume.
+    #
+    # When a node replicates with differentiation it carries a NodeRole that
+    # shapes its remote configuration: which contracts to activate, which env
+    # vars to inject, and which capability tags to advertise in the mesh.
+    #
+    # @example
+    #   role = NodeRole.new(
+    #     name:          :worker,
+    #     contracts:     ["ComputeContract"],
+    #     capabilities:  [:compute],
+    #     env_overrides: { "WORKER_POOL" => "8" },
+    #     tags:          [:cpu_heavy]
+    #   )
+    class NodeRole
+      attr_reader :name, :contracts, :capabilities, :env_overrides, :tags
+
+      def initialize(name:, contracts: [], capabilities: [], env_overrides: {}, tags: [])
+        @name          = name.to_sym
+        @contracts     = Array(contracts).map(&:to_s).freeze
+        @capabilities  = Array(capabilities).map(&:to_sym).freeze
+        @env_overrides = Hash(env_overrides).transform_keys(&:to_s).freeze
+        @tags          = Array(tags).map(&:to_sym).freeze
+        freeze
+      end
+
+      def to_h
+        {
+          name:          @name,
+          contracts:     @contracts,
+          capabilities:  @capabilities,
+          env_overrides: @env_overrides,
+          tags:          @tags
+        }
+      end
+    end
+  end
+end

data/lib/igniter/replication/reflective_replication_agent.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "replication_agent"
+require_relative "network_topology"
+require_relative "expansion_plan"
+require_relative "expansion_planner"
+require_relative "role_registry"
+
+module Igniter
+  module Replication
+    # ReplicationAgent extended with episodic memory, self-reflection, and
+    # topology-aware network expansion.
+    #
+    # == Additional message types
+    #
+    #   :assess_network  — run ExpansionPlanner; execute replicate_role/retire_node actions
+    #   :reflect         — run a ReflectionCycle over recent episodes; store summary in state
+    #   :register_node   — register a remote node in the local NetworkTopology
+    #   :node_heartbeat  — update last_seen_at for a known node
+    #   :signal_scale    — emit a :scale_signal episode (e.g. from load monitors)
+    #
+    # == State keys (in addition to inherited :events)
+    #
+    #   :topology        — NetworkTopology instance (created lazily on first access)
+    #   :host_pool       — Array<String> of candidate hosts
+    #   :required_roles  — Array<Symbol> of roles that must always be present
+    #   :last_plan       — Hash from the most recent ExpansionPlan
+    #   :last_reflection — String summary from the most recent reflection cycle
+    #
+    # == Memory
+    #
+    # Call +enable_class_memory+ in the class body to activate episodic memory.
+    # Memory is class-level (shared across handler invocations on this class).
+    #
+    # == Auto-assessment
+    #
+    # Call +auto_assess(every: N)+ to schedule periodic topology assessment.
+    #
+    # @example
+    #   RoleRegistry.define(:worker, env_overrides: { "POOL" => "4" })
+    #
+    #   class MyAgent < ReflectiveReplicationAgent
+    #     enable_class_memory
+    #     auto_assess every: 60
+    #   end
+    #
+    #   ref = MyAgent.start(initial_state: {
+    #     topology:       NetworkTopology.new,
+    #     required_roles: [:worker],
+    #     host_pool:      ["10.0.0.2", "10.0.0.3"]
+    #   })
+    #   ref.call(:assess_network)
+    class ReflectiveReplicationAgent < ReplicationAgent
+      initial_state topology: nil, host_pool: [], required_roles: [],
+                    last_plan: nil, last_reflection: nil
+
+      # ── Class-level memory ─────────────────────────────────────────────────────
+
+      class << self
+        # Activate episodic memory for this class.
+        #
+        # @param store [Memory::Store, nil] backing store; defaults to global default
+        # @return [void]
+        def enable_class_memory(store: nil)
+          require "igniter/memory"
+          @class_memory_store   = store || Igniter::Memory.default_store
+          @class_memory_enabled = true
+        end
+
+        # Returns true when class-level memory has been activated.
+        #
+        # @return [Boolean]
+        def class_memory_enabled?
+          @class_memory_enabled || false
+        end
+
+        # Returns the AgentMemory facade bound to this class, or nil when disabled.
+        #
+        # @return [Memory::AgentMemory, nil]
+        def class_memory
+          return nil unless class_memory_enabled?
+
+          @class_memory ||= Igniter::Memory::AgentMemory.new(
+            store:    @class_memory_store,
+            agent_id: name.to_s
+          )
+        end
+
+        # Reset class-level memory state. Intended for use in tests.
+        #
+        # @return [void]
+        def reset_class_memory!
+          @class_memory         = nil
+          @class_memory_store   = nil
+          @class_memory_enabled = false
+        end
+
+        # Register a recurring topology assessment.
+        #
+        # @param every [Numeric] interval in seconds
+        # @return [void]
+        def auto_assess(every:)
+          schedule(:auto_assessment, every: every) do |state:|
+            agent = new
+            agent.send(:run_assess_network, state, {})
+          end
+        end
+      end
+
+      # ── deliver: intercept lifecycle events into memory ────────────────────────
+
+      # Override the no-op deliver from ReplicationAgent to record events.
+      # Subclasses can call +super+ and then add their own routing.
+      #
+      # @param type    [Symbol]
+      # @param payload [Hash]
+      def deliver(type, payload = {})
+        self.class.class_memory&.record(
+          type:       :replication_event,
+          content:    "#{type}: #{payload.inspect}",
+          outcome:    type == :replication_failed ? "failure" : "success",
+          importance: 0.6
+        )
+      end
+
+      # ── Handlers ───────────────────────────────────────────────────────────────
+
+      # Re-define :replicate (parent's handler is cleared by Agent.inherited).
+      on :replicate do |state:, payload:, **|
+        agent = new
+        agent.send(:run_replicate, payload)
+        state
+      end
+
+      on :assess_network do |state:, payload:, **|
+        agent = new
+        agent.send(:run_assess_network, state, payload)
+      end
+
+      on :reflect do |state:, payload:, **|
+        next state unless class_memory_enabled?
+
+        rec = class_memory.reflect
+        class_memory.record(
+          type:       :reflection,
+          content:    rec.summary,
+          outcome:    "success",
+          importance: 0.8
+        )
+        state.merge(last_reflection: rec.summary)
+      end
+
+      on :register_node do |state:, payload:, **|
+        topology = state[:topology] || NetworkTopology.new
+        topology.register(
+          node_id: payload.fetch(:node_id),
+          host:    payload.fetch(:host),
+          role:    payload[:role]
+        )
+        state.merge(topology: topology)
+      end
+
+      on :node_heartbeat do |state:, payload:, **|
+        state[:topology]&.touch(node_id: payload.fetch(:node_id))
+        state
+      end
+
+      on :signal_scale do |state:, payload:, **|
+        role = payload.fetch(:role)
+        class_memory&.record(
+          type:    :scale_signal,
+          content: "scale_out:#{role}",
+          outcome: nil
+        )
+        state
+      end
+
+      private
+
+      # Assess the network topology and execute the resulting plan.
+      # Returns the updated state hash.
+      #
+      # @param state   [Hash]
+      # @param payload [Hash]
+      # @return [Hash]
+      def run_assess_network(state, payload)
+        topology = state[:topology] || NetworkTopology.new
+        planner  = ExpansionPlanner.new(
+          topology:       topology,
+          memory:         self.class.class_memory,
+          required_roles: Array(payload[:required_roles] || state[:required_roles]),
+          host_pool:      Array(payload[:host_pool]      || state[:host_pool])
+        )
+
+        plan = planner.plan
+
+        plan.actions.each do |action|
+          case action[:action]
+          when :replicate_role
+            run_replicate_role(action, topology)
+          when :retire_node
+            topology.remove(node_id: action[:node_id])
+            deliver(:node_retired, node_id: action[:node_id], host: action[:host])
+          end
+        end
+
+        self.class.class_memory&.record(
+          type:    :assessment,
+          content: plan.rationale.to_s,
+          outcome: "success"
+        )
+
+        state.merge(topology: topology, last_plan: plan.to_h)
+      end
+
+      # Execute a :replicate_role action: call run_replicate + register in topology.
+      #
+      # @param action   [Hash]
+      # @param topology [NetworkTopology]
+      def run_replicate_role(action, topology)
+        role_obj = RoleRegistry.registered?(action[:role]) ? RoleRegistry.fetch(action[:role]) : nil
+        env      = role_obj&.env_overrides || {}
+
+        run_replicate(
+          host:                 action.fetch(:host),
+          user:                 action.fetch(:user, "deploy"),
+          strategy:             action.fetch(:strategy, :git),
+          env:                  env,
+          bootstrapper_options: action.fetch(:bootstrapper_options, {})
+        )
+
+        topology.register(node_id: SecureRandom.uuid, host: action[:host], role: action[:role])
+        deliver(:role_replicated, host: action[:host], role: action[:role])
+      end
+    end
+  end
+end

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