kitsune-kit 0.4.0 → 0.5.0

data/lib/kitsune/kit/adapters/fake_provider.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "provider"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class FakeProvider < Provider
+        attr_reader :calls, :servers, :dns_records
+
+        def initialize(servers: [], dns_records: [], failures: {})
+          super()
+          @servers = servers.dup
+          @dns_records = dns_records.dup
+          @failures = failures
+          @calls = []
+        end
+
+        def validate_credentials!
+          record(:validate_credentials)
+          fail_if_requested!(:validate_credentials)
+          true
+        end
+
+        def validate_server_spec!(spec:)
+          record(:validate_server_spec, spec: spec)
+          fail_if_requested!(:validate_server_spec)
+          true
+        end
+
+        def find_server(name:, tags: [])
+          record(:find_server, name: name, tags: tags)
+          fail_if_requested!(:find_server)
+          @servers.find { |server| server.name == name && (tags.empty? || (tags - server.tags).empty?) }
+        end
+
+        def find_server_by_id(id:)
+          record(:find_server_by_id, id: id)
+          fail_if_requested!(:find_server_by_id)
+          @servers.find { |server| server.id.to_s == id.to_s }
+        end
+
+        def create_server(spec:)
+          record(:create_server, spec: spec)
+          fail_if_requested!(:create_server)
+          server = ServerRecord.new(
+            id: SecureRandom.uuid,
+            name: spec.fetch(:name),
+            status: "new",
+            public_ip: nil,
+            region: spec.fetch(:region),
+            size: spec.fetch(:size),
+            image: spec.fetch(:image),
+            tags: spec.fetch(:tags, [])
+          )
+          @servers << server
+          server
+        end
+
+        def wait_until_ready(id:, timeout:)
+          record(:wait_until_ready, id: id, timeout: timeout)
+          fail_if_requested!(:wait_until_ready)
+          server = @servers.find { |candidate| candidate.id == id }
+          raise KeyError, "server not found: #{id}" unless server
+
+          ready = server.with(status: "active", public_ip: server.public_ip || "203.0.113.10")
+          @servers[@servers.index(server)] = ready
+          ready
+        end
+
+        def delete_server(id:)
+          record(:delete_server, id: id)
+          fail_if_requested!(:delete_server)
+          !!@servers.reject! { |server| server.id == id }
+        end
+
+        def find_dns_record(zone:, name:, type:)
+          record(:find_dns_record, zone: zone, name: name, type: type)
+          @dns_records.find { |record| record.zone == zone && record.name == name && record.type == type }
+        end
+
+        def upsert_dns_record(record:)
+          record(:upsert_dns_record, record: record)
+          existing = find_dns_record(zone: record.zone, name: record.name, type: record.type)
+          saved = record.with(id: existing&.id || SecureRandom.uuid)
+          existing ? @dns_records[@dns_records.index(existing)] = saved : @dns_records << saved
+          saved
+        end
+
+        def delete_dns_record(id:, zone:)
+          record(:delete_dns_record, id: id, zone: zone)
+          !!@dns_records.reject! { |record| record.id == id && record.zone == zone }
+        end
+
+        private
+
+        def record(name, **arguments) = @calls << [name, arguments]
+
+        def fail_if_requested!(name)
+          failure = @failures[name]
+          raise failure if failure
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/fake_reporter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../reporters/reporter"
+
+module Kitsune
+  module Kit
+    module Adapters
+      # Deterministic event sink for exercising complete workflows without a terminal.
+      class FakeReporter < Reporters::Reporter
+        def initialize
+          super
+          @events = []
+          @mutex = Mutex.new
+        end
+
+        def handle(event)
+          @mutex.synchronize { @events << event }
+          event
+        end
+
+        def events = @mutex.synchronize { @events.dup }
+
+        def events_of(type)
+          @mutex.synchronize { @events.select { |event| event.type == type.to_s } }
+        end
+
+        def clear
+          @mutex.synchronize { @events.clear }
+          self
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/fake_secret_store.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require_relative "../secret_stores/store"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class FakeSecretStore < SecretStores::Store
+        attr_reader :fetches
+
+        def initialize(values = {})
+          super()
+          @values = values.transform_keys(&:to_s)
+          @fetches = []
+        end
+
+        def fetch(name, required: true)
+          key = name.to_s
+          @fetches << key
+          value = @values.fetch(key, "")
+          if required && value.empty?
+            raise Errors::ConfigurationError.new(
+              "required secret #{key} is not set", hint: "Provide #{key} through the configured secret store."
+            )
+          end
+          value
+        end
+
+        def configured?(name) = !@values.fetch(name.to_s, "").empty?
+        def set(name, value) = @values[name.to_s] = value.to_s
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/fake_state_store.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../errors"
+require_relative "../state_stores/store"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class FakeStateStore < StateStores::Store
+        SCHEMA_VERSION = 1
+
+        def initialize
+          super
+          @states = {}
+          @mutex = Mutex.new
+          @operation_mutexes = Hash.new { |hash, key| hash[key] = Mutex.new }
+        end
+
+        def read(environment)
+          name = safe_environment(environment)
+          @mutex.synchronize { copy(@states.fetch(name) { empty_state(name) }) }
+        end
+
+        def update(environment)
+          name = safe_environment(environment)
+          @mutex.synchronize do
+            updated = yield(copy(@states.fetch(name) { empty_state(name) }))
+            updated["updated_at"] = Time.now.utc.iso8601(6)
+            validate!(updated, name)
+            @states[name] = copy(updated)
+          end
+          read(name)
+        end
+
+        def write(environment, state) = update(environment) { state }
+
+        def delete(environment)
+          name = safe_environment(environment)
+          @mutex.synchronize { @states.delete(name) ? true : nil }
+        end
+
+        def with_execution_lock(environment)
+          name = safe_environment(environment)
+          lock = @mutex.synchronize { @operation_mutexes[name] }
+          unless lock.try_lock
+            raise Errors::UnsafeOperationError.new(
+              "another mutating operation is active for #{name}",
+              hint: "Wait for it to finish or stop it safely before retrying."
+            )
+          end
+          yield
+        ensure
+          lock&.unlock if lock&.owned?
+        end
+
+        private
+
+        def empty_state(environment)
+          {
+            "version" => SCHEMA_VERSION, "environment" => environment, "updated_at" => nil,
+            "resources" => {}, "operations" => [], "runs" => {}
+          }
+        end
+
+        def safe_environment(environment)
+          value = environment.to_s
+          return value if value.match?(/\A[a-zA-Z0-9_-]+\z/)
+
+          raise Errors::ConfigurationError, "environment name has an invalid format"
+        end
+
+        def validate!(state, environment)
+          raise Errors::ConfigurationError, "state must be an object" unless state.is_a?(Hash)
+          unless state["version"] == SCHEMA_VERSION
+            raise Errors::ConfigurationError,
+                  "unsupported state schema version #{state['version'].inspect}; expected #{SCHEMA_VERSION}"
+          end
+          raise Errors::ConfigurationError, "state environment mismatch" unless state["environment"] == environment
+          raise Errors::ConfigurationError, "state resources must be an object" unless state["resources"].is_a?(Hash)
+          raise Errors::ConfigurationError, "state operations must be an array" unless state["operations"].is_a?(Array)
+          raise Errors::ConfigurationError, "state runs must be an object" unless state["runs"].is_a?(Hash)
+
+          state
+        end
+
+        def copy(value) = Marshal.load(Marshal.dump(value))
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/fake_transport.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "transport"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class FakeTransport < Transport
+        attr_reader :calls, :uploads
+
+        def initialize(reachable: true, failures: {})
+          super()
+          @reachable = reachable
+          @failures = failures
+          @stubs = {}
+          @calls = []
+          @uploads = {}
+        end
+
+        def stub(command, arguments: [], stdout: "", stderr: "", exit_status: 0, duration_ms: 1)
+          @stubs[[command, arguments]] = CommandResult.new(
+            stdout: stdout,
+            stderr: stderr,
+            exit_status: exit_status,
+            duration_ms: duration_ms
+          )
+        end
+
+        def reachable?
+          @calls << [:reachable, {}]
+          raise @failures[:reachable] if @failures[:reachable]
+
+          @reachable
+        end
+
+        def execute(command, arguments: [], timeout: 30, stdin: nil)
+          @calls << [:execute, { command: command, arguments: arguments, timeout: timeout, stdin: stdin }]
+          raise @failures[:execute] if @failures[:execute]
+
+          @stubs.fetch([command, arguments]) do
+            status = command == "test" ? 1 : 0
+            CommandResult.new(stdout: "", stderr: "", exit_status: status, duration_ms: 1)
+          end
+        end
+
+        def upload(content:, remote_path:, mode: "0600")
+          @calls << [:upload, { remote_path: remote_path, mode: mode }]
+          raise @failures[:upload] if @failures[:upload]
+
+          @uploads[remote_path] = { content: content, mode: mode }
+          true
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/net_ssh_transport.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+require "base64"
+require "net/ssh"
+require "shellwords"
+require "timeout"
+require_relative "../errors"
+require_relative "transport"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class NetSshTransport < Transport
+        def initialize(host:, user:, port:, key_path:, known_hosts: nil, verify_host_key: :always,
+                       maximum_timeout: nil)
+          super()
+          @host = host
+          @user = user
+          @port = Integer(port)
+          @key_path = key_path
+          @known_hosts = known_hosts
+          @verify_host_key = verify_host_key
+          @maximum_timeout = maximum_timeout
+        end
+
+        def reachable?
+          with_connection { true }
+        rescue Errors::ConnectionError
+          false
+        end
+
+        def with_session
+          return yield if @persistent_session
+
+          open_connection do |ssh|
+            @persistent_session = ssh
+            yield
+          ensure
+            @persistent_session = nil
+          end
+        end
+
+        def execute(command, arguments: [], timeout: 30, stdin: nil)
+          validate_command!(command)
+          shell_command = ([command] + arguments.map { |argument| Shellwords.escape(argument.to_s) }).join(" ")
+          started_at = monotonic_time
+          stdout = +""
+          stderr = +""
+          exit_status = nil
+
+          effective_timeout = @maximum_timeout ? [timeout, @maximum_timeout].min : timeout
+          Timeout.timeout(effective_timeout) do
+            with_connection do |ssh|
+              ssh.open_channel do |channel|
+                channel.exec(shell_command) do |_exec_channel, success|
+                  raise Errors::RemoteCommandError, "remote command could not be started" unless success
+
+                  channel.send_data(stdin) if stdin
+                  channel.eof! if stdin
+                  channel.on_data { |_data_channel, data| stdout << data }
+                  channel.on_extended_data { |_data_channel, _type, data| stderr << data }
+                  channel.on_request("exit-status") { |_status_channel, data| exit_status = data.read_long }
+                end
+              end
+              ssh.loop
+            end
+          end
+
+          command_result(stdout, stderr, exit_status, started_at)
+        rescue Timeout::Error
+          raise Errors::TimeoutError.new("remote command timed out after #{effective_timeout || timeout} seconds",
+                                         context: { command: command })
+        end
+
+        def upload(content:, remote_path:, mode: "0600")
+          validate_remote_path!(remote_path)
+          validate_mode!(mode)
+          encoded = Base64.strict_encode64(content)
+          result = execute(
+            "sh",
+            arguments: ["-c", "base64 --decode > \"$1\" && chmod \"$2\" \"$1\"", "kitsune-upload", remote_path, mode],
+            stdin: encoded,
+            timeout: 30
+          )
+          raise_remote_failure!(result, "upload #{remote_path}") unless result.success?
+
+          true
+        end
+
+        private
+
+        def command_result(stdout, stderr, exit_status, started_at)
+          CommandResult.new(
+            stdout: stdout,
+            stderr: stderr,
+            exit_status: exit_status || 255,
+            duration_ms: ((monotonic_time - started_at) * 1000).round
+          )
+        end
+
+        def with_connection
+          return yield(@persistent_session) if @persistent_session
+
+          open_connection { |ssh| return yield(ssh) }
+        end
+
+        def open_connection
+          options = {
+            port: @port,
+            keys: [@key_path],
+            non_interactive: true,
+            timeout: @maximum_timeout ? [10, @maximum_timeout].min : 10,
+            verify_host_key: @verify_host_key
+          }
+          options[:user_known_hosts_file] = [@known_hosts] if @known_hosts
+          Net::SSH.start(@host, @user, **options) { |ssh| return yield(ssh) }
+        rescue Net::SSH::Exception, SystemCallError, SocketError => e
+          raise Errors::ConnectionError.new(
+            "SSH connection to #{@user}@#{@host}:#{@port} failed",
+            hint: "Verify the address, key, host fingerprint and firewall rules.",
+            context: { cause: e.class.name },
+            retryable: true
+          )
+        end
+
+        def validate_command!(command)
+          return if command.to_s.match?(%r{\A[\w./-]+\z})
+
+          raise Errors::ConfigurationError, "remote command has an invalid format"
+        end
+
+        def validate_remote_path!(path)
+          return if path.to_s.match?(%r{\A/[a-zA-Z0-9_./-]+\z}) && !path.to_s.include?("..")
+
+          raise Errors::ConfigurationError, "remote path has an invalid format"
+        end
+
+        def validate_mode!(mode)
+          return if mode.to_s.match?(/\A0[0-7]{3}\z/)
+
+          raise Errors::ConfigurationError, "file mode has an invalid format"
+        end
+
+        def raise_remote_failure!(result, operation)
+          raise Errors::RemoteCommandError.new(
+            "remote #{operation} failed with status #{result.exit_status}",
+            context: { stderr: result.stderr }
+          )
+        end
+
+        def monotonic_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/provider.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module Adapters
+      API_VERSION = 1
+
+      ServerRecord = Data.define(:id, :name, :status, :public_ip, :region, :size, :image, :tags) do
+        def to_h
+          members.to_h { |member| [member, public_send(member)] }
+        end
+      end
+
+      DnsRecord = Data.define(:id, :zone, :name, :type, :data, :ttl) do
+        def to_h
+          members.to_h { |member| [member, public_send(member)] }
+        end
+      end
+
+      class Provider
+        def validate_credentials! = raise NotImplementedError
+        def validate_server_spec!(spec:) = raise NotImplementedError
+        def find_server(name:, tags: []) = raise NotImplementedError
+        def find_server_by_id(id:) = raise NotImplementedError
+        def create_server(spec:) = raise NotImplementedError
+        def wait_until_ready(id:, timeout:) = raise NotImplementedError
+        def delete_server(id:) = raise NotImplementedError
+        def find_dns_record(zone:, name:, type:) = raise NotImplementedError
+        def upsert_dns_record(record:) = raise NotImplementedError
+        def delete_dns_record(id:, zone:) = raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/transport.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module Adapters
+      CommandResult = Data.define(:stdout, :stderr, :exit_status, :duration_ms) do
+        def success? = exit_status.zero?
+
+        def to_h
+          { stdout: stdout, stderr: stderr, exit_status: exit_status, duration_ms: duration_ms }
+        end
+      end
+
+      class Transport
+        def with_session = yield
+        def reachable? = raise NotImplementedError
+        def execute(command, arguments: [], timeout: 30, stdin: nil) = raise NotImplementedError
+        def upload(content:, remote_path:, mode: "0600") = raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/kitsune/kit/adapters/transport_factory.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../errors"
+require_relative "net_ssh_transport"
+require_relative "confirming_host_key_verifier"
+
+module Kitsune
+  module Kit
+    module Adapters
+      class TransportFactory
+        BOOTSTRAP_TIMEOUT = 120
+        BOOTSTRAP_RETRY_INTERVAL = 5
+
+        def initialize(config:, provider:, root: Dir.pwd, host_key_confirmation: nil, maximum_timeout: nil,
+                       sleeper: Kernel, monotonic_clock: nil, bootstrap_timeout: BOOTSTRAP_TIMEOUT)
+          if maximum_timeout && maximum_timeout <= 0
+            raise Errors::ConfigurationError, "timeout must be greater than zero"
+          end
+          raise Errors::ConfigurationError, "SSH bootstrap timeout must be greater than zero" if bootstrap_timeout <= 0
+
+          @config = config
+          @provider = provider
+          @known_hosts = File.expand_path(".kitsune/known_hosts", root)
+          @host_key_verifier = ConfirmingHostKeyVerifier.new(&host_key_confirmation)
+          @maximum_timeout = maximum_timeout
+          @bootstrap_timeout = [bootstrap_timeout, maximum_timeout].compact.min
+          @sleeper = sleeper
+          @monotonic_clock = monotonic_clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+        end
+
+        def server
+          @provider.find_server(name: @config.server.name, tags: @config.server.tags)
+        end
+
+        def for(user:)
+          current = server
+          unless current&.public_ip
+            raise Errors::ConnectionError.new(
+              "server is not ready for SSH",
+              hint: "Apply the server operation first, then resume."
+            )
+          end
+          FileUtils.mkdir_p(File.dirname(@known_hosts), mode: 0o700)
+          FileUtils.touch(@known_hosts)
+          File.chmod(0o600, @known_hosts)
+          NetSshTransport.new(
+            host: current.public_ip,
+            user: user,
+            port: @config.ssh.port,
+            key_path: @config.ssh.key_path,
+            known_hosts: @known_hosts,
+            verify_host_key: @host_key_verifier,
+            maximum_timeout: @maximum_timeout
+          )
+        end
+
+        def deploy = self.for(user: @config.ssh.user)
+        def root = self.for(user: "root")
+
+        def bootstrap
+          candidate = deploy
+          return candidate if candidate.reachable?
+
+          candidate = root
+          return candidate if candidate.reachable?
+
+          raise Errors::ConnectionError.new(
+            "neither #{@config.ssh.user} nor root can access the server",
+            hint: "Verify the SSH key and provider console before changing SSH policy."
+          )
+        end
+
+        def wait_for_bootstrap
+          deadline = monotonic_time + @bootstrap_timeout
+          loop do
+            return bootstrap
+          rescue Errors::ConnectionError
+            remaining = deadline - monotonic_time
+            break if remaining <= 0
+
+            @sleeper.sleep([BOOTSTRAP_RETRY_INTERVAL, remaining].min)
+          end
+
+          raise Errors::ConnectionError.new(
+            "SSH did not become reachable within #{@bootstrap_timeout} seconds",
+            hint: "Wait for Ubuntu to finish booting and verify that the uploaded public key matches ssh.key_path.",
+            context: { timeout: @bootstrap_timeout },
+            retryable: true
+          )
+        end
+
+        private
+
+        def monotonic_time = @monotonic_clock.call
+      end
+
+      class FakeTransportFactory
+        attr_reader :server_record
+
+        def initialize(transport:, server: nil, root_transport: nil, deploy_transport: nil)
+          @transport = transport
+          @root_transport = root_transport || transport
+          @deploy_transport = deploy_transport || transport
+          @server_record = server
+        end
+
+        def server = @server_record
+        def deploy = @deploy_transport
+        def root = @root_transport
+        def bootstrap = @deploy_transport.reachable? ? @deploy_transport : @root_transport
+        def wait_for_bootstrap = bootstrap
+      end
+    end
+  end
+end