kitsune-kit 0.4.0 → 0.5.0

data/lib/kitsune/kit/plan.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    class Change < Data.define(:resource, :action, :summary, :details, :destructive)
+      ACTIONS = %w[create update delete no_change].freeze
+
+      def initialize(resource:, action:, summary:, details: {}, destructive: false)
+        raise ArgumentError, "unknown action: #{action}" unless ACTIONS.include?(action.to_s)
+
+        super(
+          resource: resource.to_s,
+          action: action.to_s,
+          summary: summary.to_s,
+          details: details.freeze,
+          destructive: !!destructive
+        )
+      end
+
+      def changed? = action != "no_change"
+      def destructive? = destructive
+
+      def to_h
+        {
+          resource: resource,
+          action: action,
+          summary: summary,
+          details: details,
+          destructive: destructive
+        }
+      end
+
+      def self.from_h(value)
+        new(
+          resource: value.fetch("resource"),
+          action: value.fetch("action"),
+          summary: value.fetch("summary"),
+          details: value.fetch("details", {}),
+          destructive: value.fetch("destructive", false)
+        )
+      end
+    end
+
+    class Plan < Data.define(:environment, :changes)
+      def initialize(environment:, changes:)
+        super(environment: environment.to_s, changes: changes.freeze)
+      end
+
+      def changed? = changes.any?(&:changed?)
+      def destructive? = changes.any?(&:destructive)
+      def changed_count = changes.count(&:changed?)
+
+      def counts
+        changes.each_with_object(Hash.new(0)) { |change, total| total[change.action] += 1 }
+      end
+
+      def to_h
+        {
+          environment: environment,
+          changed: changed?,
+          destructive: destructive?,
+          counts: counts,
+          changes: changes.map(&:to_h)
+        }
+      end
+
+      def self.from_h(environment:, changes:)
+        new(environment: environment, changes: changes.map { |change| Change.from_h(change) })
+      end
+    end
+  end
+end

data/lib/kitsune/kit/reporters/human.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "reporter"
+
+module Kitsune
+  module Kit
+    module Reporters
+      class Human < Reporter
+        SYMBOLS = {
+          "run_started" => "START",
+          "plan_built" => "PLAN",
+          "operation_started" => "RUN",
+          "operation_progressed" => "PROGRESS",
+          "operation_succeeded" => "OK",
+          "operation_skipped" => "SKIP",
+          "operation_failed" => "FAIL",
+          "warning_emitted" => "WARN",
+          "run_finished" => "DONE"
+        }.freeze
+
+        def initialize(output: $stdout, error: $stderr, color: nil, quiet: false, verbose: false,
+                       secret_filter: SecretFilter.new)
+          super()
+          @output = output
+          @error = error
+          @color = color.nil? ? output.tty? && !ENV.key?("NO_COLOR") : color
+          @secret_filter = secret_filter
+          @quiet = quiet
+          @verbose = verbose
+        end
+
+        def handle(event)
+          return if @quiet && !%w[operation_failed warning_emitted run_finished].include?(event.type)
+
+          data = @secret_filter.filter(event.data)
+          stream = %w[operation_failed warning_emitted].include?(event.type) ? @error : @output
+          message = message_for(event.type, data)
+          stream.puts("#{label(event.type)} #{message}") if message
+        end
+
+        private
+
+        def label(type)
+          value = "[#{SYMBOLS.fetch(type, type.upcase)}]"
+          return value unless @color
+
+          code = case type
+                 when "operation_succeeded", "run_finished" then 32
+                 when "operation_failed" then 31
+                 when "warning_emitted" then 33
+                 else 36
+                 end
+          "\e[#{code}m#{value}\e[0m"
+        end
+
+        def message_for(type, data)
+          method = "message_#{type}"
+          send(method, data) if respond_to?(method, true)
+        end
+
+        def message_run_started(data) = "#{data[:command]} for #{data[:environment]}"
+        def message_plan_built(data) = "#{data[:changed_count]} change(s), #{data[:unchanged_count]} unchanged"
+
+        def message_operation_started(data)
+          progress = data[:index] && data[:total] ? "[#{data[:index]}/#{data[:total]}] " : ""
+          "#{progress}#{data[:summary]}"
+        end
+
+        def message_operation_succeeded(data)
+          duration = data[:duration_ms] ? " (#{data[:duration_ms]}ms)" : ""
+          "#{data[:summary]}#{duration}"
+        end
+
+        def message_operation_progressed(data)
+          "#{data[:summary]}: #{data[:percent]}%" if @verbose
+        end
+
+        def message_operation_failed(data) = "#{data[:summary]}: #{data[:message]}"
+
+        def message_operation_skipped(data)
+          "#{data[:summary]} (#{data[:reason]})" if @verbose
+        end
+
+        def message_warning_emitted(data) = data[:message]
+        def message_run_finished(data) = "#{data[:status]} in #{data[:duration_ms]}ms"
+      end
+    end
+  end
+end

data/lib/kitsune/kit/reporters/json.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "reporter"
+
+module Kitsune
+  module Kit
+    module Reporters
+      class Json < Reporter
+        attr_reader :events
+
+        def initialize(output: $stdout, secret_filter: SecretFilter.new)
+          super()
+          @output = output
+          @secret_filter = secret_filter
+          @events = []
+        end
+
+        def handle(event)
+          @events << @secret_filter.filter(event.to_h)
+        end
+
+        def flush(result: nil, command: nil, environment: nil)
+          started = event("run_started", reverse: true)
+          finished = event("run_finished", reverse: true)
+          payload = {
+            schema_version: 1,
+            command: command || started&.dig(:data, :command),
+            environment: environment || started&.dig(:data, :environment),
+            run_id: started&.dig(:run_id) || result&.metadata&.dig(:run_id),
+            status: (result&.status || status_from_events).to_s,
+            duration_ms: finished&.dig(:data, :duration_ms),
+            result: @secret_filter.filter(serialize(result&.value)),
+            warnings: @secret_filter.filter(result&.warnings || []),
+            events: @events
+          }
+          @output.puts(::JSON.generate(payload))
+          payload
+        end
+
+        private
+
+        def event(type, reverse: false)
+          source = reverse ? @events.reverse_each : @events.each
+          source.find { |item| item[:type] == type }
+        end
+
+        def status_from_events
+          @events.reverse_each do |event|
+            return event.dig(:data, :status) if event[:type] == "run_finished"
+          end
+          "unknown"
+        end
+
+        def serialize(value)
+          return value.map { |item| serialize(item) } if value.is_a?(Array)
+          return value.to_h { |key, item| [key, serialize(item)] } if value.is_a?(Hash)
+          return serialize(value.to_h) if value.respond_to?(:to_h)
+
+          value
+        end
+      end
+    end
+  end
+end

data/lib/kitsune/kit/reporters/reporter.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    module Reporters
+      class Reporter
+        def handle(event) = raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/kitsune/kit/result.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Kitsune
+  module Kit
+    class Result < Data.define(:status, :value, :warnings, :metadata)
+      STATUSES = %i[success failure cancelled].freeze
+
+      def initialize(status:, value: nil, warnings: [], metadata: {})
+        raise ArgumentError, "unknown status: #{status}" unless STATUSES.include?(status.to_sym)
+
+        super(
+          status: status.to_sym,
+          value: value,
+          warnings: warnings.freeze,
+          metadata: metadata.freeze
+        )
+      end
+
+      def success? = status == :success
+      def failure? = status == :failure
+      def cancelled? = status == :cancelled
+
+      def self.success(value = nil, warnings: [], metadata: {})
+        new(status: :success, value: value, warnings: warnings, metadata: metadata)
+      end
+    end
+  end
+end

data/lib/kitsune/kit/run_journal.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "errors"
+
+module Kitsune
+  module Kit
+    class RunJournal
+      RESUMABLE_STATUSES = %w[running failure cancelled].freeze
+
+      def initialize(state_store:, environment:, run_id:, clock: -> { Time.now.utc })
+        @state_store = state_store
+        @environment = environment
+        @run_id = run_id
+        @clock = clock
+      end
+
+      def start(changes:, resumed_from: nil)
+        update_run do |run|
+          run.merge!(
+            "status" => "running",
+            "started_at" => timestamp,
+            "finished_at" => nil,
+            "resumed_from" => resumed_from,
+            "changes" => normalize(changes),
+            "steps" => {}
+          )
+        end
+      end
+
+      def record_step(resource, status, error: nil)
+        update_run do |run|
+          run["steps"] ||= {}
+          run["steps"][resource] = {
+            "status" => status,
+            "error" => error,
+            "updated_at" => timestamp
+          }
+        end
+      end
+
+      def finish(status, error: nil)
+        update_run do |run|
+          run["status"] = status
+          run["error"] = error
+          run["finished_at"] = timestamp
+        end
+      end
+
+      def resumable(requested_id = nil)
+        runs = state_store.read(environment)["runs"]
+        selected_id = requested_id || runs.keys.reverse.find { |id| resumable_status?(runs.fetch(id)) }
+        raise no_resumable_run_error unless selected_id
+
+        run = runs[selected_id]
+        raise Errors::ConfigurationError, "run not found: #{selected_id}" unless run
+
+        validate_resumable!(selected_id, run)
+        [selected_id, run]
+      end
+
+      private
+
+      attr_reader :state_store, :environment, :run_id, :clock
+
+      def update_run
+        return unless state_store
+
+        state_store.update(environment) do |state|
+          run = state["runs"][run_id] ||= {}
+          yield(run)
+          state
+        end
+      end
+
+      def validate_resumable!(selected_id, run)
+        unless resumable_status?(run)
+          raise Errors::ConfigurationError.new(
+            "run #{selected_id} cannot be resumed because its status is #{run['status']}",
+            hint: "Resume a failed, cancelled, or interrupted run."
+          )
+        end
+        return if run["changes"].is_a?(Array) && run["steps"].is_a?(Hash)
+
+        raise Errors::ConfigurationError, "run #{selected_id} does not contain a resumable plan"
+      end
+
+      def resumable_status?(run) = RESUMABLE_STATUSES.include?(run["status"])
+
+      def no_resumable_run_error
+        Errors::ConfigurationError.new(
+          "there is no run available to resume",
+          hint: "Run `kit apply` first or provide the ID of a failed run."
+        )
+      end
+
+      def timestamp = clock.call.iso8601(6)
+      def normalize(value) = JSON.parse(JSON.generate(value))
+    end
+  end
+end

data/lib/kitsune/kit/run_logger.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "pathname"
+
+module Kitsune
+  module Kit
+    class RunLogger
+      MAX_FILES = 20
+
+      attr_reader :path
+
+      def initialize(root:, run_id:, secret_filter: SecretFilter.new, clock: Clock.new)
+        directory = Pathname(root).expand_path.join(".kitsune/logs")
+        FileUtils.mkdir_p(directory, mode: 0o700)
+        @path = directory.join("#{clock.now.strftime('%Y%m%dT%H%M%S')}-#{run_id}.jsonl")
+        @secret_filter = secret_filter
+        FileUtils.touch(@path)
+        File.chmod(0o600, @path)
+        rotate(directory)
+      end
+
+      def handle(event)
+        File.open(path, "a", 0o600) do |file|
+          file.puts(JSON.generate(@secret_filter.filter(event.to_h)))
+        end
+      end
+
+      private
+
+      def rotate(directory)
+        directory.glob("*.jsonl").sort_by(&:mtime).reverse.drop(MAX_FILES).each(&:delete)
+      end
+    end
+  end
+end

data/lib/kitsune/kit/scripts/docker.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+action="${1:?action is required}"
+user="${2:?user is required}"
+backup_dir="/var/lib/kitsune/backups/docker"
+keyring="/etc/apt/keyrings/docker.asc"
+repository="/etc/apt/sources.list.d/docker.sources"
+packages=(docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin)
+prerequisites=(ca-certificates curl)
+conflicting_packages=(docker.io docker-compose docker-compose-v2 podman-docker containerd runc)
+
+refuse_conflicting_packages() {
+  local installed=()
+  local package
+  for package in "${conflicting_packages[@]}"; do
+    if dpkg-query -W -f='${Status}' "${package}" 2>/dev/null | grep -q "ok installed"; then
+      installed+=("${package}")
+    fi
+  done
+  if (( ${#installed[@]} > 0 )); then
+    printf 'conflicting Docker packages are installed: %s\n' "${installed[*]}" >&2
+    echo "Remove or migrate them explicitly before Kitsune Kit installs Docker CE." >&2
+    exit 3
+  fi
+}
+
+snapshot() {
+  [[ -f "${backup_dir}/snapshot-complete" ]] && return
+  : > "${backup_dir}/packages-before"
+  for package in "${prerequisites[@]}" "${packages[@]}"; do
+    if dpkg-query -W -f='${Status}' "${package}" 2>/dev/null | grep -q "ok installed"; then
+      printf '%s\n' "${package}" >> "${backup_dir}/packages-before"
+    fi
+  done
+  systemctl is-enabled --quiet docker && touch "${backup_dir}/enabled-before"
+  systemctl is-active --quiet docker && touch "${backup_dir}/active-before"
+  touch "${backup_dir}/snapshot-complete"
+}
+
+apply() {
+  refuse_conflicting_packages
+  install -d -m 0700 "${backup_dir}"
+  snapshot
+  apt-get update
+  DEBIAN_FRONTEND=noninteractive apt-get install --yes "${prerequisites[@]}"
+  install -d -m 0755 /etc/apt/keyrings
+  if [[ ! -f "${keyring}" ]]; then
+    temporary_key="$(mktemp)"
+    trap 'rm -f "${temporary_key}"' EXIT
+    curl --fail --silent --show-error --location \
+      https://download.docker.com/linux/ubuntu/gpg --output "${temporary_key}"
+    test -s "${temporary_key}"
+    install -o root -g root -m 0644 "${temporary_key}" "${keyring}"
+    rm -f "${temporary_key}"
+    trap - EXIT
+    touch "${backup_dir}/key-created"
+  fi
+  if [[ ! -f "${repository}" ]]; then
+    codename="$(sed -n 's/^UBUNTU_CODENAME=//p' /etc/os-release | tr -d '\"')"
+    if [[ -z "${codename}" ]]; then
+      codename="$(sed -n 's/^VERSION_CODENAME=//p' /etc/os-release | tr -d '\"')"
+    fi
+    [[ -n "${codename}" ]] || { echo "cannot determine Ubuntu codename" >&2; exit 1; }
+    temporary_repository="$(mktemp)"
+    trap 'rm -f "${temporary_repository}"' EXIT
+    cat > "${temporary_repository}" <<EOF
+Types: deb
+URIs: https://download.docker.com/linux/ubuntu
+Suites: ${codename}
+Components: stable
+Signed-By: ${keyring}
+EOF
+    install -o root -g root -m 0644 "${temporary_repository}" "${repository}"
+    rm -f "${temporary_repository}"
+    trap - EXIT
+    touch "${backup_dir}/repository-created"
+  fi
+  apt-get update
+  DEBIAN_FRONTEND=noninteractive apt-get install --yes "${packages[@]}"
+  systemctl enable --now docker
+  if ! id -nG "${user}" | tr ' ' '\n' | grep -Fxq docker; then
+    usermod -aG docker "${user}"
+    touch "${backup_dir}/group-added"
+  fi
+  if ! docker network inspect kitsune-private >/dev/null 2>&1; then
+    docker network create --driver bridge kitsune-private >/dev/null
+    touch "${backup_dir}/network-created"
+  fi
+}
+
+verify() {
+  systemctl is-active --quiet docker
+  docker version >/dev/null
+  docker compose version >/dev/null
+  id -nG "${user}" | tr ' ' '\n' | grep -Fxq docker
+  docker network inspect kitsune-private >/dev/null
+}
+
+rollback() {
+  if [[ -f "${backup_dir}/group-added" ]]; then
+    gpasswd -d "${user}" docker || true
+  fi
+  if [[ -f "${backup_dir}/network-created" ]]; then
+    docker network rm kitsune-private || true
+  fi
+  for package in "${packages[@]}"; do
+    if ! grep -Fxq "${package}" "${backup_dir}/packages-before" 2>/dev/null; then
+      apt-get remove --yes "${package}" || true
+    fi
+  done
+  for package in "${prerequisites[@]}"; do
+    if ! grep -Fxq "${package}" "${backup_dir}/packages-before" 2>/dev/null; then
+      apt-get remove --yes "${package}" || true
+    fi
+  done
+  if [[ -f "${backup_dir}/enabled-before" ]]; then
+    systemctl enable docker || true
+  else
+    systemctl disable docker || true
+  fi
+  if [[ -f "${backup_dir}/active-before" ]]; then
+    systemctl start docker || true
+  else
+    systemctl stop docker || true
+  fi
+  [[ -f "${backup_dir}/repository-created" ]] && rm -f "${repository}"
+  [[ -f "${backup_dir}/key-created" ]] && rm -f "${keyring}"
+  rm -rf "${backup_dir}"
+}
+
+case "${action}" in
+  apply) apply ;;
+  verify) verify ;;
+  rollback) rollback ;;
+  *) echo "unknown action: ${action}" >&2; exit 2 ;;
+esac