kitsune-kit 0.4.0 → 0.5.0

data/lib/kitsune/kit/operations/remote_script.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../errors"
+require_relative "../plan"
+
+module Kitsune
+  module Kit
+    module Operations
+      class RemoteScript
+        MARKER_DIRECTORY = "/var/lib/kitsune/state"
+
+        attr_reader :resource
+
+        def initialize(config:, transport_factory:, state_store:, resource:, script_path:, arguments: [],
+                       transport_roles: { apply: :deploy }, verification: {})
+          @config = config
+          @transport_factory = transport_factory
+          @state_store = state_store
+          @resource = resource
+          @script_path = script_path
+          @arguments = arguments.map(&:to_s).freeze
+          @transport_roles = transport_roles
+          @post_verify = verification[:callback]
+          @finalize_action = verification[:finalize_action]
+          @rollback_on_failure = verification.fetch(:rollback_on_failure, false)
+        end
+
+        def plan
+          return pending_change unless transport_factory.server&.public_ip
+
+          actual = remote_fingerprint
+          return unchanged_change if actual == fingerprint
+
+          Change.new(
+            resource: resource,
+            action: actual.empty? ? "create" : "update",
+            summary: actual.empty? ? "Configure #{resource}" : "Update #{resource}",
+            details: { fingerprint: fingerprint, actual_fingerprint: actual.empty? ? nil : actual }
+          )
+        rescue Errors::ConnectionError
+          pending_change
+        end
+
+        def apply(change)
+          return true unless change.changed?
+
+          remote = "/tmp/kitsune-#{safe_resource}-#{fingerprint[0, 12]}.sh"
+          applied = false
+          current_transport.with_session do
+            current_transport.upload(content: script, remote_path: remote, mode: "0700")
+            execute_script(remote, "apply")
+            applied = true
+            execute_script(remote, "verify")
+            @post_verify&.call
+            finalize(remote)
+            write_marker
+            record_state(change)
+            true
+          rescue StandardError => e
+            recover_verified_transition(remote, e) if applied && @rollback_on_failure
+            raise e
+          ensure
+            cleanup(remote)
+          end
+        end
+
+        def rollback
+          state = state_store.read(config.environment).dig("resources", resource)
+          return false unless state && state["managed"]
+
+          remote = "/tmp/kitsune-#{safe_resource}-rollback.sh"
+          rollback_transport.upload(content: script, remote_path: remote, mode: "0700")
+          execute_script(remote, "rollback", transport: rollback_transport)
+          rollback_transport.execute("sudo", arguments: ["rm", "-f", marker_path], timeout: 10)
+          state_store.update(config.environment) do |current|
+            current["resources"].delete(resource)
+            current["operations"] << { "resource" => resource, "action" => "rollback", "status" => "applied" }
+            current
+          end
+          true
+        ensure
+          cleanup(remote, transport: rollback_transport) if defined?(remote) && remote
+        end
+
+        private
+
+        attr_reader :config, :transport_factory, :state_store
+
+        def script = @script ||= File.read(@script_path)
+        def fingerprint = @fingerprint ||= Digest::SHA256.hexdigest([script, *@arguments].join("\0"))
+        def safe_resource = resource.tr(".", "-")
+        def marker_path = "#{MARKER_DIRECTORY}/#{safe_resource}.sha256"
+
+        def current_transport
+          @current_transport ||= transport_factory.public_send(@transport_roles.fetch(:apply, :deploy))
+        end
+
+        def rollback_transport
+          role = @transport_roles.fetch(:rollback) { @transport_roles.fetch(:apply, :deploy) }
+          @rollback_transport ||= transport_factory.public_send(role)
+        end
+
+        def remote_fingerprint
+          result = current_transport.execute("sudo", arguments: ["cat", marker_path], timeout: 10)
+          result.success? ? result.stdout.strip : ""
+        end
+
+        def execute_script(remote, action, transport: current_transport)
+          result = transport.execute(
+            "sudo",
+            arguments: ["bash", remote, action, *@arguments],
+            timeout: 300
+          )
+          return result if result.success?
+
+          raise Errors::RemoteCommandError.new(
+            "#{resource} #{action} failed with status #{result.exit_status}",
+            hint: "Review the remote command error and resume apply after correcting it.",
+            context: { stderr: result.stderr, stdout: result.stdout }
+          )
+        end
+
+        def finalize(remote)
+          return unless @finalize_action
+
+          execute_script(remote, @finalize_action)
+          execute_script(remote, "verify_final")
+          @post_verify&.call
+        end
+
+        def write_marker
+          directory = current_transport.execute(
+            "sudo", arguments: ["install", "-d", "-m", "0755", MARKER_DIRECTORY], timeout: 10
+          )
+          raise_remote_result!(directory, "create marker directory")
+          marker = current_transport.execute(
+            "sudo", arguments: ["tee", marker_path], stdin: "#{fingerprint}\n", timeout: 10
+          )
+          raise_remote_result!(marker, "write marker")
+          mode = current_transport.execute("sudo", arguments: ["chmod", "0644", marker_path], timeout: 10)
+          raise_remote_result!(mode, "secure marker")
+        end
+
+        def raise_remote_result!(result, action)
+          return if result.success?
+
+          raise Errors::RemoteCommandError.new("unable to #{action} for #{resource}",
+                                               context: { stderr: result.stderr })
+        end
+
+        def record_state(change)
+          state_store.update(config.environment) do |state|
+            state["resources"][resource] = {
+              "managed" => true,
+              "fingerprint" => fingerprint,
+              "action" => change.action
+            }
+            state["operations"] << { "resource" => resource, "action" => change.action, "status" => "applied" }
+            state
+          end
+        end
+
+        def pending_change
+          Change.new(
+            resource: resource,
+            action: "create",
+            summary: "Configure #{resource} after the server is ready",
+            details: { fingerprint: fingerprint, depends_on: "server" }
+          )
+        end
+
+        def unchanged_change
+          Change.new(
+            resource: resource,
+            action: "no_change",
+            summary: "#{resource} is configured",
+            details: { fingerprint: fingerprint }
+          )
+        end
+
+        def cleanup(remote, transport: current_transport)
+          transport.execute("rm", arguments: ["-f", remote], timeout: 10)
+        rescue StandardError
+          nil
+        end
+
+        def recover_verified_transition(remote, original_error)
+          execute_script(remote, "rollback")
+          marker = current_transport.execute("sudo", arguments: ["rm", "-f", marker_path], timeout: 10)
+          raise_remote_result!(marker, "remove marker during recovery")
+          state_store.update(config.environment) do |state|
+            if state["resources"].delete(resource)
+              state["operations"] << {
+                "resource" => resource, "action" => "recover", "status" => "applied"
+              }
+            end
+            state
+          end
+        rescue StandardError => e
+          raise Errors::VerificationError.new(
+            "#{resource} verification failed and the preserved SSH session could not restore it",
+            hint: "Keep the current terminal open and use provider-console access before retrying.",
+            context: {
+              original_error: error_name(original_error), recovery_error: error_name(e)
+            }
+          )
+        end
+
+        def error_name(error) = error.respond_to?(:code) ? error.code : error.class.name
+      end
+    end
+  end
+end

data/lib/kitsune/kit/operations/service_backup.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Kitsune
+  module Kit
+    module Operations
+      class ServiceBackup
+        BACKUP_IMAGE = "alpine:3.20@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc"
+
+        def initialize(config:, type:, transport:, compose:, clock: -> { Time.now.utc })
+          @config = config
+          @type = type
+          @transport = transport
+          @compose = compose
+          @clock = clock
+        end
+
+        def call(state)
+          unless state&.fetch("installed", true)
+            raise Errors::UnsafeOperationError.new(
+              "#{type} is not installed",
+              hint: "Install and verify the service before creating a data backup."
+            )
+          end
+
+          directory = "/home/#{config.ssh.user}/.local/share/kitsune/backups/#{type}"
+          path = "#{directory}/#{type}-#{clock.call.strftime('%Y%m%dT%H%M%S')}.tar.gz"
+          create_directory(directory)
+          create_archive(directory, path, state.fetch("volume"))
+          path
+        end
+
+        private
+
+        attr_reader :config, :type, :transport, :compose, :clock
+
+        def create_directory(directory)
+          result = transport.execute("mkdir", arguments: ["-p", directory], timeout: 10)
+          raise_remote!(result, "create backup directory")
+        end
+
+        def create_archive(directory, path, volume)
+          paused = false
+          compose.call("pause")
+          paused = true
+          result = transport.execute(
+            "docker",
+            arguments: ["run", "--rm", "--volume", "#{volume}:/data:ro", "--volume", "#{directory}:/backup",
+                        BACKUP_IMAGE, "tar", "-czf", "/backup/#{File.basename(path)}", "-C", "/data", "."],
+            timeout: 600
+          )
+          raise_remote!(result, "back up service data")
+          result = transport.execute("chmod", arguments: ["0600", path], timeout: 10)
+          raise_remote!(result, "secure service backup")
+        ensure
+          compose.call("unpause") if paused
+        end
+
+        def raise_remote!(result, action)
+          return if result.success?
+
+          raise Errors::RemoteCommandError.new(
+            "unable to #{action} for #{type}",
+            context: { stderr: result.stderr, exit_status: result.exit_status }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/operations/service_files.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Kitsune
+  module Kit
+    module Operations
+      class ServiceFiles
+        def initialize(config:, type:, transport:, state_store:, resource:, fingerprint:)
+          @config = config
+          @type = type
+          @transport = transport
+          @state_store = state_store
+          @resource = resource
+          @fingerprint = fingerprint
+        end
+
+        def directory = "/home/#{config.ssh.user}/.local/share/kitsune/services/#{type}"
+        def compose_path = "#{directory}/compose.yml"
+        def env_path = "#{directory}/.env"
+        def backup_directory = "/var/lib/kitsune/backups/service-#{type}-#{fingerprint.call[0, 12]}"
+
+        def ensure_managed_or_absent!(actual_fingerprint)
+          return if managed?
+          return if actual_fingerprint.empty? && !exists?(compose_path) && !exists?(env_path)
+
+          raise Errors::UnsafeOperationError.new(
+            "refusing to replace unmanaged #{type} service files",
+            hint: "Restore the local state backup or move the existing files before applying again.",
+            context: { directory: directory }
+          )
+        end
+
+        def prepare_backup
+          result = transport.execute(
+            "sudo",
+            arguments: ["install", "-d", "-m", "0700", "-o", config.ssh.user, "-g", config.ssh.user,
+                        backup_directory],
+            timeout: 20
+          )
+          raise_remote!(result, "create service backup directory")
+          [compose_path, env_path].select { |path| exists?(path) }.tap do |paths|
+            paths.each { |path| copy(path, backup_directory) }
+          end
+        end
+
+        def restore_after_failure(backed_up_files)
+          if backed_up_files.empty?
+            transport.execute("rm", arguments: ["-f", compose_path, env_path], timeout: 20)
+          else
+            backed_up_files.each { |path| copy("#{backup_directory}/#{File.basename(path)}", File.dirname(path)) }
+          end
+        end
+
+        def restore_previous(previous, marker_path:)
+          if previous["backup_directory"]
+            restore_files(previous["backup_directory"], previous.fetch("backed_up_files", []))
+            restore_marker(marker_path, previous["previous_fingerprint"])
+            remove_backup(previous["backup_directory"])
+            true
+          else
+            transport.execute("rm", arguments: ["-rf", directory], timeout: 30)
+            transport.execute("sudo", arguments: ["rm", "-f", marker_path], timeout: 10)
+            false
+          end
+        end
+
+        def destroy(entry, marker_path:)
+          result = transport.execute("rm", arguments: ["-rf", directory], timeout: 30)
+          raise_remote!(result, "remove service files")
+          result = transport.execute("sudo", arguments: ["rm", "-f", marker_path], timeout: 10)
+          raise_remote!(result, "remove service marker")
+          backup_directories(entry).each { |backup| remove_backup(backup) }
+        end
+
+        private
+
+        attr_reader :config, :type, :transport, :state_store, :resource, :fingerprint
+
+        def managed? = !!state_store.read(config.environment).dig("resources", resource, "managed")
+        def exists?(path) = transport.execute("test", arguments: ["-e", path], timeout: 10).success?
+
+        def restore_files(directory, files)
+          files.each { |path| copy("#{directory}/#{File.basename(path)}", File.dirname(path)) }
+        end
+
+        def copy(source, destination)
+          result = transport.execute(
+            "cp", arguments: ["--preserve=mode,ownership", source, destination], timeout: 20
+          )
+          raise_remote!(result, "copy service files")
+        end
+
+        def restore_marker(path, value)
+          return transport.execute("sudo", arguments: ["rm", "-f", path], timeout: 10) unless value
+
+          result = transport.execute("sudo", arguments: ["tee", path], stdin: "#{value}\n", timeout: 10)
+          raise_remote!(result, "restore service marker")
+        end
+
+        def remove_backup(directory)
+          result = transport.execute("sudo", arguments: ["rm", "-rf", directory], timeout: 30)
+          raise_remote!(result, "remove restored service backup")
+        end
+
+        def backup_directories(entry)
+          current = entry
+          [].tap do |directories|
+            while current
+              directories << current["backup_directory"] if current["backup_directory"]
+              current = current["previous_state"]
+            end
+          end.uniq
+        end
+
+        def raise_remote!(result, action)
+          return if result.success?
+
+          raise Errors::RemoteCommandError.new(
+            "unable to #{action} for #{type}",
+            context: { stderr: result.stderr, exit_status: result.exit_status }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/operations/service_firewall.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+
+module Kitsune
+  module Kit
+    module Operations
+      class ServiceFirewall
+        attr_reader :owned_rules, :drop_owned
+
+        def initialize(config:, type:, service:, transport:, state_store:, resource:)
+          @config = config
+          @type = type
+          @service = service
+          @transport = transport
+          @state_store = state_store
+          @resource = resource
+          @owned_rules = []
+          @drop_owned = false
+        end
+
+        def reconcile(previous)
+          unless service.publish
+            remove_state(previous)
+            return
+          end
+
+          @transaction_added = []
+          @transaction_deleted = []
+          ensure_drop_rule(previous, tracked: true)
+          added = service.allowed_cidrs.reject { |cidr| rule_exists?(allow_rule(cidr)) }.each do |cidr|
+            add_tracked_rule(allow_rule(cidr))
+          end
+          retained = previous_rules_for_current_port(previous) & service.allowed_cidrs
+          @owned_rules = (retained + added).uniq
+          remove_stale(previous, tracked: true)
+        rescue StandardError => e
+          begin
+            rollback_transaction
+          rescue StandardError => recovery_error
+            raise Errors::VerificationError.new(
+              "Docker firewall reconciliation and recovery both failed",
+              hint: "Inspect DOCKER-USER rules marked by Kitsune Kit before retrying.",
+              context: {
+                original_error: error_name(e), recovery_error: error_name(recovery_error)
+              }
+            )
+          end
+          raise e
+        ensure
+          @transaction_added = nil
+          @transaction_deleted = nil
+        end
+
+        def remove
+          remove_state(managed_state)
+        end
+
+        def restore(previous)
+          return unless previous["published"]
+
+          port = previous.fetch("port")
+          ensure_rule(drop_rule(port: port))
+          previous.fetch("firewall_rules_added", []).each do |cidr|
+            ensure_rule(allow_rule(cidr, port: port))
+          end
+        end
+
+        def restore_after_failure(previous)
+          remove_state(
+            "published" => service.publish,
+            "port" => service.port,
+            "firewall_rules_added" => @owned_rules,
+            "firewall_drop_added" => @drop_owned
+          )
+          restore(previous || {})
+        end
+
+        private
+
+        attr_reader :config, :type, :service, :transport, :state_store, :resource
+
+        def ensure_drop_rule(previous, tracked: false)
+          existed = rule_exists?(drop_rule)
+          unless existed
+            tracked ? add_tracked_rule(drop_rule) : add_rule(drop_rule, position: 1)
+          end
+          previously_owned = previous&.fetch("published", false) && previous.fetch("port") == service.port &&
+                             previous["firewall_drop_added"]
+          @drop_owned = previously_owned || !existed
+        end
+
+        def remove_state(previous)
+          return unless previous&.fetch("published", false)
+
+          port = previous.fetch("port")
+          previous.fetch("firewall_rules_added", []).each { |cidr| delete_rule(allow_rule(cidr, port: port)) }
+          delete_rule(drop_rule(port: port)) if previous["firewall_drop_added"]
+        end
+
+        def remove_stale(previous, tracked: false)
+          return unless previous&.fetch("published", false)
+
+          previous_port = previous.fetch("port")
+          previous.fetch("firewall_rules_added", []).each do |cidr|
+            next if previous_port == service.port && service.allowed_cidrs.include?(cidr)
+
+            rule = allow_rule(cidr, port: previous_port)
+            tracked ? delete_tracked_rule(rule) : delete_rule(rule)
+          end
+          return unless previous["firewall_drop_added"] && previous_port != service.port
+
+          rule = drop_rule(port: previous_port)
+          tracked ? delete_tracked_rule(rule) : delete_rule(rule)
+        end
+
+        def previous_rules_for_current_port(previous)
+          return [] unless previous&.fetch("published", false) && previous.fetch("port") == service.port
+
+          previous.fetch("firewall_rules_added", [])
+        end
+
+        def allow_rule(cidr, port: service.port)
+          common_rule(port) + ["-s", cidr, "-m", "comment", "--comment", "kitsune:#{type}:allow", "-j", "ACCEPT"]
+        end
+
+        def drop_rule(port: service.port)
+          common_rule(port) + ["-m", "comment", "--comment", "kitsune:#{type}:drop", "-j", "DROP"]
+        end
+
+        def common_rule(port)
+          ["DOCKER-USER", "-p", "tcp", "-m", "conntrack", "--ctorigdstport", port.to_s,
+           "--ctdir", "ORIGINAL"]
+        end
+
+        def ensure_rule(rule)
+          add_rule(rule, position: 1) unless rule_exists?(rule)
+        end
+
+        def rule_exists?(rule)
+          transport.execute("sudo", arguments: ["iptables", "-C", *rule], timeout: 20).success?
+        end
+
+        def add_rule(rule, position:)
+          result = transport.execute(
+            "sudo",
+            arguments: ["iptables", "-I", rule.first, position.to_s, *rule.drop(1)],
+            timeout: 20
+          )
+          raise_remote!(result, "add Docker firewall rule")
+        end
+
+        def add_tracked_rule(rule)
+          add_rule(rule, position: 1)
+          @transaction_added << rule
+        end
+
+        def delete_rule(rule)
+          result = transport.execute("sudo", arguments: ["iptables", "-D", *rule], timeout: 20)
+          return false if result.exit_status == 1
+
+          raise_remote!(result, "remove Docker firewall rule") unless result.success?
+          true
+        end
+
+        def delete_tracked_rule(rule)
+          @transaction_deleted << rule if delete_rule(rule)
+        end
+
+        def rollback_transaction
+          Array(@transaction_added).reverse_each { |rule| delete_rule(rule) }
+          Array(@transaction_deleted).reverse_each { |rule| ensure_rule(rule) }
+        end
+
+        def error_name(error) = error.respond_to?(:code) ? error.code : error.class.name
+
+        def managed_state = state_store.read(config.environment).dig("resources", resource)
+
+        def raise_remote!(result, action)
+          return if result.success?
+
+          raise Errors::RemoteCommandError.new(
+            "unable to #{action} for #{type}",
+            context: { stderr: result.stderr, exit_status: result.exit_status }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/operations/service_state.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module Operations
+      class ServiceState
+        def initialize(state_store:, environment:, resource:)
+          @state_store = state_store
+          @environment = environment
+          @resource = resource
+        end
+
+        def current = state_store.read(environment).dig("resources", resource)
+        def managed? = !!current&.fetch("managed", false)
+
+        def record_apply(action, attributes)
+          update do |state|
+            previous = state["resources"][resource]
+            state["resources"][resource] = attributes.merge("previous_state" => previous)
+            operation(state, action)
+          end
+        end
+
+        def record_remove
+          update do |state|
+            state["resources"][resource]["installed"] = false
+            operation(state, "remove")
+          end
+        end
+
+        def record_rollback(previous)
+          update do |state|
+            prior = previous["previous_state"]
+            prior ? state["resources"][resource] = prior : state["resources"].delete(resource)
+            operation(state, "rollback")
+          end
+        end
+
+        def delete(action)
+          update do |state|
+            state["resources"].delete(resource)
+            operation(state, action)
+          end
+        end
+
+        private
+
+        attr_reader :state_store, :environment, :resource
+
+        def update(&) = state_store.update(environment, &)
+
+        def operation(state, action)
+          state["operations"] << { "resource" => resource, "action" => action, "status" => "applied" }
+          state
+        end
+      end
+    end
+  end
+end