kamal-backup 0.1.0.pre.1

data/lib/kamal_backup/evidence.rb

@@ -0,0 +1,80 @@
+require "json"
+require "time"
+require_relative "command"
+require_relative "version"
+
+module KamalBackup
+  class Evidence
+    def initialize(config, restic:, redactor:)
+      @config = config
+      @restic = restic
+      @redactor = redactor
+    end
+
+    def to_h
+      {
+        app_name: @config.app_name,
+        generated_at: Time.now.utc.iso8601,
+        database_adapter: @config.database_adapter,
+        restic_repository: @redactor.redact_string(@config.restic_repository.to_s),
+        backup_paths: @config.backup_paths,
+        forget_after_backup: @config.forget_after_backup?,
+        retention: @config.retention,
+        latest_database_backup: latest_snapshot_summary(["type:database"]),
+        latest_file_backup: latest_snapshot_summary(["type:files"]),
+        last_restic_check: last_check,
+        image_version: ENV.fetch("KAMAL_BACKUP_IMAGE_VERSION", VERSION),
+        tool_versions: tool_versions
+      }
+    end
+
+    def to_json(*args)
+      JSON.pretty_generate(to_h, *args)
+    end
+
+    private
+
+    def latest_snapshot_summary(tags)
+      snapshot = @restic.latest_snapshot(tags: tags)
+      return nil unless snapshot
+
+      {
+        id: snapshot["short_id"] || snapshot["id"],
+        time: snapshot["time"],
+        tags: snapshot["tags"]
+      }
+    rescue Error => e
+      { error: @redactor.redact_string(e.message) }
+    end
+
+    def last_check
+      return nil unless File.file?(@config.last_check_path)
+
+      JSON.parse(File.read(@config.last_check_path))
+    rescue JSON::ParserError, SystemCallError => e
+      { error: @redactor.redact_string(e.message) }
+    end
+
+    def tool_versions
+      {
+        pg_dump: version_for(["pg_dump", "--version"]),
+        pg_restore: version_for(["pg_restore", "--version"]),
+        mysql_dump: version_for(["mariadb-dump", "--version"], ["mysqldump", "--version"]),
+        mysql_client: version_for(["mariadb", "--version"], ["mysql", "--version"]),
+        sqlite3: version_for(["sqlite3", "--version"]),
+        restic: version_for(["restic", "version"])
+      }
+    end
+
+    def version_for(*commands)
+      commands.each do |argv|
+        result = Command.capture(CommandSpec.new(argv: argv), redactor: @redactor)
+        output = result.stdout.empty? ? result.stderr : result.stdout
+        return @redactor.redact_string(output.strip)
+      rescue CommandError
+        next
+      end
+      "unavailable"
+    end
+  end
+end

data/lib/kamal_backup/redactor.rb

@@ -0,0 +1,53 @@
+require "uri"
+
+module KamalBackup
+  class Redactor
+    SECRET_KEY_PATTERN = /(pass|password|secret|token|key|credential|authorization)/i
+    REDACTED = "[REDACTED]"
+
+    def initialize(secret_values: [], env: ENV)
+      @secret_values = Array(secret_values).compact.map(&:to_s).reject { |value| value.empty? || value.length < 4 }
+      @env = env
+    end
+
+    def redact_hash(hash)
+      hash.each_with_object({}) do |(key, value), result|
+        result[key] = redact_value(key, value)
+      end
+    end
+
+    def redact_value(key, value)
+      return nil if value.nil?
+      return REDACTED if key.to_s.match?(SECRET_KEY_PATTERN)
+
+      redact_string(value.to_s)
+    end
+
+    def redact_string(value)
+      redacted = redact_url_credentials(value.to_s)
+      known_secret_values.each do |secret|
+        redacted = redacted.gsub(secret, REDACTED)
+      end
+      redacted
+    end
+
+    private
+
+    def known_secret_values
+      @known_secret_values ||= begin
+        env_secrets = @env.each_with_object([]) do |(key, value), values|
+          values << value.to_s if key.to_s.match?(SECRET_KEY_PATTERN)
+        end
+        (@secret_values + env_secrets).compact.uniq.reject { |value| value.empty? || value.length < 4 }
+      end
+    end
+
+    def redact_url_credentials(value)
+      value.gsub(%r{(://)([^/\s:@]+)(?::([^/\s@]*))?@}) do
+        "#{$1}#{REDACTED}@"
+      end.gsub(/([?&](?:password|token|secret|key|access_key_id|secret_access_key)=)[^&\s]+/i) do
+        "#{$1}#{REDACTED}"
+      end
+    end
+  end
+end

data/lib/kamal_backup/restic.rb

@@ -0,0 +1,239 @@
+require "fileutils"
+require "json"
+require "open3"
+require "time"
+require_relative "command"
+
+module KamalBackup
+  class Restic
+    attr_reader :config, :redactor
+
+    def initialize(config, redactor:)
+      @config = config
+      @redactor = redactor
+    end
+
+    def ensure_repository!
+      run(%w[snapshots --json])
+    rescue CommandError => e
+      raise e unless config.restic_init_if_missing?
+
+      log("restic repository not ready, running restic init")
+      run(%w[init])
+    end
+
+    def backup_command_output(command, filename:, tags:)
+      restic_command = CommandSpec.new(argv: ["restic", "backup", "--stdin", "--stdin-filename", filename] + tag_args(common_tags + tags))
+      log("backing up stream as #{filename}")
+      pipe_commands(command, restic_command, producer_label: "dump", consumer_label: "restic backup")
+    end
+
+    def backup_file_content(path, filename:, tags:)
+      command = CommandSpec.new(argv: ["restic", "backup", "--stdin", "--stdin-filename", filename] + tag_args(common_tags + tags))
+      log("backing up file content as #{filename}")
+
+      File.open(path, "rb") do |file|
+        Open3.popen3(command.env, *command.argv) do |stdin, stdout, stderr, wait_thread|
+          stdout_reader = Thread.new { stdout.read }
+          stderr_reader = Thread.new { stderr.read }
+          IO.copy_stream(file, stdin)
+          stdin.close
+          out = stdout_reader.value
+          err = stderr_reader.value
+          status = wait_thread.value
+          raise_command_error(command, status, out, err) unless status.success?
+
+          CommandResult.new(stdout: out, stderr: err, status: status.exitstatus)
+        end
+      end
+    rescue Errno::ENOENT => e
+      raise CommandError.new("command not found: #{command.argv.first}", command: command, status: 127, stderr: e.message)
+    end
+
+    def backup_paths(paths, tags:)
+      paths = Array(paths).compact.map(&:to_s).reject(&:empty?)
+      return if paths.empty?
+
+      path_tags = paths.map { |path| "path:#{config.backup_path_label(path)}" }
+      log("backing up #{paths.size} file path(s): #{paths.join(", ")}")
+      run(["backup"] + paths + tag_args(common_tags + tags + path_tags))
+    end
+
+    def backup_path(path, tags:)
+      backup_paths([path], tags: tags)
+    end
+
+    def forget_after_success!
+      args = ["forget", "--prune"] + config.retention_args + tag_args(common_tags)
+      log("running restic forget/prune with retention policy")
+      run(args)
+    end
+
+    def check!
+      args = %w[check]
+      args.concat(["--read-data-subset", config.check_read_data_subset]) if config.check_read_data_subset
+      started_at = Time.now.utc
+      result = run(args)
+      write_last_check(status: "ok", started_at: started_at, finished_at: Time.now.utc, output: result.stdout)
+      result
+    rescue CommandError => e
+      write_last_check(status: "failed", started_at: started_at || Time.now.utc, finished_at: Time.now.utc, error: e.message)
+      raise
+    end
+
+    def snapshots(tags: common_tags)
+      run(["snapshots"] + tag_args(tags))
+    end
+
+    def snapshots_json(tags: common_tags)
+      output = run(["snapshots", "--json"] + tag_args(tags)).stdout
+      snapshots = JSON.parse(output)
+      required_tags = tags.compact
+      snapshots.select do |snapshot|
+        snapshot_tags = Array(snapshot["tags"])
+        required_tags.all? { |tag| snapshot_tags.include?(tag) }
+      end
+    end
+
+    def latest_snapshot(tags:)
+      snapshots = snapshots_json(tags: common_tags + tags)
+      snapshots.max_by { |snapshot| Time.parse(snapshot.fetch("time")) }
+    rescue JSON::ParserError
+      nil
+    end
+
+    def ls_json(snapshot)
+      output = run(["ls", "--json", snapshot]).stdout
+      output.lines.filter_map do |line|
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    def database_file(snapshot, adapter)
+      legacy_prefix = "databases/#{config.app_name}/#{adapter}/"
+      flat_prefix = "databases-#{config.app_name.gsub(/[^A-Za-z0-9_.-]+/, "-")}-#{adapter}-"
+      ls_json(snapshot).find do |entry|
+        next false unless entry["type"] == "file"
+
+        normalized = entry["path"].to_s.sub(%r{\A/+}, "")
+        normalized.start_with?(legacy_prefix) || File.basename(normalized).start_with?(flat_prefix)
+      end&.fetch("path")
+    end
+
+    def dump_file_to_command(snapshot, filename, command)
+      restic_command = CommandSpec.new(argv: ["restic", "dump", snapshot, filename])
+      pipe_commands(restic_command, command, producer_label: "restic dump", consumer_label: command.argv.first)
+    end
+
+    def dump_file_to_path(snapshot, filename, target_path)
+      command = CommandSpec.new(argv: ["restic", "dump", snapshot, filename])
+      target_path = File.expand_path(target_path)
+      FileUtils.mkdir_p(File.dirname(target_path))
+      temp_path = "#{target_path}.kamal-backup-#{$$}.tmp"
+
+      Open3.popen3(command.env, *command.argv) do |stdin, stdout, stderr, wait_thread|
+        stdin.close
+        stderr_reader = Thread.new { stderr.read }
+        File.open(temp_path, "wb") { |file| IO.copy_stream(stdout, file) }
+        err = stderr_reader.value
+        status = wait_thread.value
+        raise_command_error(command, status, "", err) unless status.success?
+      end
+      File.rename(temp_path, target_path)
+      target_path
+    rescue Errno::ENOENT => e
+      FileUtils.rm_f(temp_path) if temp_path
+      raise CommandError.new("command not found: #{command.argv.first}", command: command, status: 127, stderr: e.message)
+    rescue StandardError
+      FileUtils.rm_f(temp_path) if temp_path
+      raise
+    end
+
+    def restore_snapshot(snapshot, target)
+      log("restoring file snapshot #{snapshot} to #{target}")
+      run(["restore", snapshot, "--target", target])
+    end
+
+    def run(args)
+      Command.capture(CommandSpec.new(argv: ["restic"] + args), redactor: redactor)
+    end
+
+    def common_tags
+      ["kamal-backup", "app:#{config.app_name}"]
+    end
+
+    private
+
+    def tag_args(tags)
+      tags.compact.each_with_object([]) { |tag, args| args.concat(["--tag", tag]) }
+    end
+
+    def pipe_commands(producer, consumer, producer_label:, consumer_label:)
+      Open3.popen3(producer.env, *producer.argv) do |producer_stdin, producer_stdout, producer_stderr, producer_wait|
+        producer_stdin.close
+
+        Open3.popen3(consumer.env, *consumer.argv) do |consumer_stdin, consumer_stdout, consumer_stderr, consumer_wait|
+          producer_err_reader = Thread.new { producer_stderr.read }
+          consumer_out_reader = Thread.new { consumer_stdout.read }
+          consumer_err_reader = Thread.new { consumer_stderr.read }
+
+          copy_error = nil
+          copy_thread = Thread.new do
+            IO.copy_stream(producer_stdout, consumer_stdin)
+          rescue StandardError => e
+            copy_error = e
+          ensure
+            consumer_stdin.close unless consumer_stdin.closed?
+          end
+
+          copy_thread.join
+          producer_status = producer_wait.value
+          consumer_status = consumer_wait.value
+
+          producer_err = producer_err_reader.value
+          consumer_out = consumer_out_reader.value
+          consumer_err = consumer_err_reader.value
+
+          if copy_error
+            raise CommandError.new(
+              "failed to pipe #{producer_label} to #{consumer_label}: #{copy_error.message}",
+              command: consumer,
+              stderr: copy_error.message
+            )
+          end
+
+          raise_command_error(producer, producer_status, "", producer_err) unless producer_status.success?
+          raise_command_error(consumer, consumer_status, consumer_out, consumer_err) unless consumer_status.success?
+
+          CommandResult.new(stdout: consumer_out, stderr: consumer_err, status: consumer_status.exitstatus)
+        end
+      end
+    rescue Errno::ENOENT => e
+      command = e.message.include?(producer.argv.first) ? producer : consumer
+      raise CommandError.new("command not found: #{command.argv.first}", command: command, status: 127, stderr: e.message)
+    end
+
+    def raise_command_error(command, status, stdout, stderr)
+      raise CommandError.new(
+        "command failed (#{status.exitstatus}): #{command.display(redactor)}\n#{redactor.redact_string(stderr)}",
+        command: command,
+        status: status.exitstatus,
+        stdout: redactor.redact_string(stdout),
+        stderr: redactor.redact_string(stderr)
+      )
+    end
+
+    def write_last_check(payload)
+      FileUtils.mkdir_p(config.state_dir)
+      File.write(config.last_check_path, JSON.pretty_generate(payload.transform_values { |value| value.respond_to?(:iso8601) ? value.iso8601 : redactor.redact_string(value.to_s) }))
+    rescue SystemCallError
+      nil
+    end
+
+    def log(message)
+      $stdout.puts("[kamal-backup] #{redactor.redact_string(message)}")
+    end
+  end
+end

data/lib/kamal_backup/scheduler.rb

@@ -0,0 +1,50 @@
+require "time"
+
+module KamalBackup
+  class Scheduler
+    def initialize(config, &backup_block)
+      @config = config
+      @backup_block = backup_block
+      @stop = false
+    end
+
+    def run
+      install_signal_handlers
+      sleep_interruptibly(@config.backup_start_delay_seconds)
+
+      until @stop
+        started_at = Time.now.utc
+        log("backup started at #{started_at.iso8601}")
+        begin
+          @backup_block.call
+          log("backup completed at #{Time.now.utc.iso8601}")
+        rescue StandardError => e
+          warn("[kamal-backup] backup failed at #{Time.now.utc.iso8601}: #{e.class}: #{e.message}")
+        end
+
+        sleep_interruptibly(@config.backup_schedule_seconds)
+      end
+
+      log("scheduler stopped at #{Time.now.utc.iso8601}")
+    end
+
+    private
+
+    def install_signal_handlers
+      %w[TERM INT].each do |signal|
+        Signal.trap(signal) { @stop = true }
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    def sleep_interruptibly(seconds)
+      deadline = Time.now + seconds
+      sleep([deadline - Time.now, 1].min) while !@stop && Time.now < deadline
+    end
+
+    def log(message)
+      $stdout.puts("[kamal-backup] #{message}")
+    end
+  end
+end

data/lib/kamal_backup/version.rb

@@ -0,0 +1,3 @@
+module KamalBackup
+  VERSION = "0.1.0.pre.1"
+end

data/lib/kamal_backup.rb

@@ -0,0 +1,13 @@
+require_relative "kamal_backup/version"
+require_relative "kamal_backup/errors"
+require_relative "kamal_backup/command"
+require_relative "kamal_backup/redactor"
+require_relative "kamal_backup/config"
+require_relative "kamal_backup/restic"
+require_relative "kamal_backup/evidence"
+require_relative "kamal_backup/scheduler"
+require_relative "kamal_backup/databases/base"
+require_relative "kamal_backup/databases/postgres"
+require_relative "kamal_backup/databases/mysql"
+require_relative "kamal_backup/databases/sqlite"
+require_relative "kamal_backup/cli"

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: kamal-backup
+version: !ruby/object:Gem::Version
+  version: 0.1.0.pre.1
+platform: ruby
+authors:
+- Carmine Paolino
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-04-22 00:00:00.000000000 Z
+dependencies: []
+description: A small CLI and Docker image for encrypted, verifiable Kamal accessory
+  backups using restic.
+email:
+- carmine@paolino.me
+executables:
+- kamal-backup
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- exe/kamal-backup
+- lib/kamal_backup.rb
+- lib/kamal_backup/cli.rb
+- lib/kamal_backup/command.rb
+- lib/kamal_backup/config.rb
+- lib/kamal_backup/databases/base.rb
+- lib/kamal_backup/databases/mysql.rb
+- lib/kamal_backup/databases/postgres.rb
+- lib/kamal_backup/databases/sqlite.rb
+- lib/kamal_backup/errors.rb
+- lib/kamal_backup/evidence.rb
+- lib/kamal_backup/redactor.rb
+- lib/kamal_backup/restic.rb
+- lib/kamal_backup/scheduler.rb
+- lib/kamal_backup/version.rb
+homepage: https://kamal-backup.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://kamal-backup.dev
+  source_code_uri: https://github.com/crmne/kamal-backup
+  changelog_uri: https://github.com/crmne/kamal-backup/releases
+  bug_tracker_uri: https://github.com/crmne/kamal-backup/issues
+  funding_uri: https://github.com/sponsors/crmne
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Kamal-first restic backups for databases and mounted application files.
+test_files: []