kamal-backup 0.1.0.pre.1

data/lib/kamal_backup/config.rb

@@ -0,0 +1,273 @@
+require "fileutils"
+require "pathname"
+require "time"
+require "uri"
+require_relative "errors"
+
+module KamalBackup
+  class Config
+    DEFAULT_RETENTION = {
+      "RESTIC_KEEP_LAST" => "7",
+      "RESTIC_KEEP_DAILY" => "7",
+      "RESTIC_KEEP_WEEKLY" => "4",
+      "RESTIC_KEEP_MONTHLY" => "6",
+      "RESTIC_KEEP_YEARLY" => "2"
+    }.freeze
+
+    SUSPICIOUS_BACKUP_PATHS = %w[/ /var /etc /root /usr /bin /sbin /boot /dev /proc /sys /run].freeze
+
+    attr_reader :env
+
+    def initialize(env: ENV)
+      @env = env.to_h
+    end
+
+    def app_name
+      value("APP_NAME")
+    end
+
+    def app_name!
+      required!("APP_NAME")
+    end
+
+    def restic_repository
+      value("RESTIC_REPOSITORY")
+    end
+
+    def restic_password
+      value("RESTIC_PASSWORD")
+    end
+
+    def restic_init_if_missing?
+      truthy?("RESTIC_INIT_IF_MISSING")
+    end
+
+    def check_after_backup?
+      truthy?("RESTIC_CHECK_AFTER_BACKUP")
+    end
+
+    def forget_after_backup?
+      !falsey?("RESTIC_FORGET_AFTER_BACKUP")
+    end
+
+    def check_read_data_subset
+      value("RESTIC_CHECK_READ_DATA_SUBSET")
+    end
+
+    def allow_restore?
+      truthy?("KAMAL_BACKUP_ALLOW_RESTORE")
+    end
+
+    def allow_production_restore?
+      truthy?("KAMAL_BACKUP_ALLOW_PRODUCTION_RESTORE")
+    end
+
+    def allow_in_place_file_restore?
+      truthy?("KAMAL_BACKUP_ALLOW_IN_PLACE_FILE_RESTORE")
+    end
+
+    def allow_suspicious_backup_paths?
+      truthy?("KAMAL_BACKUP_ALLOW_SUSPICIOUS_PATHS")
+    end
+
+    def backup_schedule_seconds
+      integer("BACKUP_SCHEDULE_SECONDS", 86_400, minimum: 1)
+    end
+
+    def backup_start_delay_seconds
+      integer("BACKUP_START_DELAY_SECONDS", 0, minimum: 0)
+    end
+
+    def state_dir
+      value("KAMAL_BACKUP_STATE_DIR") || "/var/lib/kamal-backup"
+    end
+
+    def last_check_path
+      File.join(state_dir, "last_check.json")
+    end
+
+    def backup_paths
+      raw = value("BACKUP_PATHS").to_s
+      raw.split(/[\n:]+/).map(&:strip).reject(&:empty?)
+    end
+
+    def backup_path_label(path)
+      label = path.to_s.sub(%r{\A/+}, "").gsub(%r{[^A-Za-z0-9_.-]+}, "-")
+      label.empty? ? "root" : label
+    end
+
+    def database_adapter
+      explicit = value("DATABASE_ADAPTER")
+      return normalize_adapter(explicit) if explicit
+
+      url = value("DATABASE_URL")
+      if url
+        scheme = URI.parse(url).scheme rescue nil
+        detected = normalize_adapter(scheme)
+        return detected if detected
+      end
+
+      return "sqlite" if value("SQLITE_DATABASE_PATH")
+
+      nil
+    end
+
+    def retention
+      DEFAULT_RETENTION.each_with_object({}) do |(key, default), result|
+        result[key] = value(key) || default
+      end
+    end
+
+    def retention_args
+      retention.each_with_object([]) do |(key, raw), args|
+        next if raw.to_s.empty?
+
+        number = Integer(raw)
+        next if number <= 0
+
+        flag = "--#{key.sub("RESTIC_KEEP_", "keep-").downcase.tr("_", "-")}"
+        args.concat([flag, number.to_s])
+      rescue ArgumentError
+        raise ConfigurationError, "#{key} must be an integer"
+      end
+    end
+
+    def validate_for_restic!
+      app_name!
+      required!("RESTIC_REPOSITORY")
+      required!("RESTIC_PASSWORD")
+    end
+
+    def validate_for_backup!
+      validate_for_restic!
+      validate_database_backup!
+      validate_backup_paths!
+    end
+
+    def validate_database_backup!
+      case database_adapter
+      when "postgres"
+        unless value("DATABASE_URL") || value("PGDATABASE")
+          raise ConfigurationError, "PostgreSQL backup requires DATABASE_URL or PGDATABASE/libpq environment"
+        end
+      when "mysql"
+        unless value("DATABASE_URL") || value("MYSQL_DATABASE") || value("MARIADB_DATABASE")
+          raise ConfigurationError, "MySQL backup requires DATABASE_URL or MYSQL_DATABASE/MARIADB_DATABASE"
+        end
+      when "sqlite"
+        path = required!("SQLITE_DATABASE_PATH")
+        raise ConfigurationError, "SQLITE_DATABASE_PATH does not exist: #{path}" unless File.file?(path)
+      else
+        raise ConfigurationError, "DATABASE_ADAPTER is required or must be detectable from DATABASE_URL/SQLITE_DATABASE_PATH"
+      end
+    end
+
+    def validate_backup_paths!
+      paths = backup_paths
+      raise ConfigurationError, "BACKUP_PATHS must contain at least one path" if paths.empty?
+
+      paths.each do |path|
+        expanded = File.expand_path(path)
+        if SUSPICIOUS_BACKUP_PATHS.include?(expanded) && !allow_suspicious_backup_paths?
+          raise ConfigurationError, "refusing suspicious backup path #{expanded}; set KAMAL_BACKUP_ALLOW_SUSPICIOUS_PATHS=true to override"
+        end
+        raise ConfigurationError, "backup path does not exist: #{path}" unless File.exist?(path)
+      end
+    end
+
+    def validate_restore_allowed!
+      return if allow_restore?
+
+      raise ConfigurationError, "restore commands require KAMAL_BACKUP_ALLOW_RESTORE=true"
+    end
+
+    def validate_file_restore_target!(target)
+      raise ConfigurationError, "restore target cannot be empty" if target.to_s.strip.empty?
+
+      expanded_target = File.expand_path(target)
+      raise ConfigurationError, "refusing to restore files to /" if expanded_target == "/"
+
+      in_place = backup_paths.any? do |path|
+        expanded_path = File.expand_path(path)
+        expanded_target == expanded_path || expanded_path.start_with?(expanded_target + "/") || expanded_target.start_with?(expanded_path + "/")
+      end
+
+      if in_place && !allow_in_place_file_restore?
+        raise ConfigurationError, "refusing in-place file restore to #{expanded_target}; set KAMAL_BACKUP_ALLOW_IN_PLACE_FILE_RESTORE=true to override"
+      end
+
+      expanded_target
+    end
+
+    def validate_database_restore_target!(target)
+      raise ConfigurationError, "restore database target is required" if target.to_s.strip.empty?
+
+      if production_like_target?(target) && !allow_production_restore?
+        raise ConfigurationError, "refusing production-looking restore target #{target}; set KAMAL_BACKUP_ALLOW_PRODUCTION_RESTORE=true to override"
+      end
+    end
+
+    def production_like_target?(target)
+      target = target.to_s
+      source_targets = [
+        value("DATABASE_URL"),
+        value("SQLITE_DATABASE_PATH"),
+        value("PGDATABASE"),
+        value("MYSQL_DATABASE"),
+        value("MARIADB_DATABASE")
+      ].compact
+
+      return true if source_targets.include?(target)
+
+      lowered = target.downcase
+      lowered.include?("production") ||
+        lowered.match?(%r{(^|[/_.:-])prod([/_.:-]|$)}) ||
+        lowered.match?(%r{(^|[/_.:-])live([/_.:-]|$)})
+    end
+
+    def value(key)
+      raw = env[key]
+      return nil if raw.nil?
+
+      stripped = raw.to_s.strip
+      stripped.empty? ? nil : stripped
+    end
+
+    def required!(key)
+      value(key) || raise(ConfigurationError, "#{key} is required")
+    end
+
+    def truthy?(key)
+      %w[1 true yes y on].include?(value(key).to_s.downcase)
+    end
+
+    def falsey?(key)
+      %w[0 false no n off].include?(value(key).to_s.downcase)
+    end
+
+    private
+
+    def integer(key, default, minimum:)
+      raw = value(key)
+      number = raw ? Integer(raw) : default
+      raise ConfigurationError, "#{key} must be >= #{minimum}" if number < minimum
+
+      number
+    rescue ArgumentError
+      raise ConfigurationError, "#{key} must be an integer"
+    end
+
+    def normalize_adapter(value)
+      case value.to_s.downcase
+      when "postgres", "postgresql"
+        "postgres"
+      when "mysql", "mysql2", "mariadb"
+        "mysql"
+      when "sqlite", "sqlite3"
+        "sqlite"
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/kamal_backup/databases/base.rb

@@ -0,0 +1,74 @@
+require_relative "../command"
+require_relative "../errors"
+
+module KamalBackup
+  module Databases
+    class Base
+      attr_reader :config, :redactor
+
+      def initialize(config, redactor:)
+        @config = config
+        @redactor = redactor
+      end
+
+      def backup(restic, timestamp)
+        restic.backup_command_output(
+          dump_command,
+          filename: database_filename(timestamp),
+          tags: backup_tags(timestamp)
+        )
+      end
+
+      def restore(restic, snapshot, filename)
+        validate_restore_target!
+        restic.dump_file_to_command(snapshot, filename, restore_command)
+      end
+
+      def database_filename(timestamp)
+        app = config.app_name.gsub(/[^A-Za-z0-9_.-]+/, "-")
+        "databases-#{app}-#{adapter_name}-#{timestamp}.#{dump_extension}"
+      end
+
+      def backup_tags(timestamp)
+        ["type:database", "adapter:#{adapter_name}", "run:#{timestamp}"]
+      end
+
+      def adapter_name
+        raise NotImplementedError
+      end
+
+      def dump_extension
+        raise NotImplementedError
+      end
+
+      def dump_command
+        raise NotImplementedError
+      end
+
+      def restore_command
+        raise NotImplementedError
+      end
+
+      def validate_restore_target!
+        config.validate_database_restore_target!(restore_target_identifier)
+      end
+
+      def restore_target_identifier
+        raise NotImplementedError
+      end
+
+      private
+
+      def value(key)
+        config.value(key)
+      end
+
+      def executable_available?(name)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+          path = File.join(dir, name)
+          File.executable?(path) && !File.directory?(path)
+        end
+      end
+    end
+  end
+end

data/lib/kamal_backup/databases/mysql.rb

@@ -0,0 +1,109 @@
+require "uri"
+require_relative "base"
+
+module KamalBackup
+  module Databases
+    class Mysql < Base
+      def adapter_name
+        "mysql"
+      end
+
+      def dump_extension
+        "sql"
+      end
+
+      def dump_command
+        connection = backup_connection
+        argv = [
+          dump_binary,
+          "--single-transaction",
+          "--quick",
+          "--routines",
+          "--triggers",
+          "--events"
+        ] + connection_args(connection)
+        argv << connection.fetch(:database)
+        CommandSpec.new(argv: argv, env: password_env(connection))
+      end
+
+      def restore_command
+        connection = restore_connection
+        argv = [client_binary] + connection_args(connection)
+        argv << connection.fetch(:database)
+        CommandSpec.new(argv: argv, env: password_env(connection))
+      end
+
+      def restore_target_identifier
+        connection = restore_connection
+        [connection[:host], connection[:database]].compact.join("/")
+      end
+
+      private
+
+      def dump_binary
+        value("MYSQL_DUMP_BIN") || (executable_available?("mariadb-dump") ? "mariadb-dump" : "mysqldump")
+      end
+
+      def client_binary
+        value("MYSQL_CLIENT_BIN") || (executable_available?("mariadb") ? "mariadb" : "mysql")
+      end
+
+      def backup_connection
+        if value("DATABASE_URL")
+          parse_url(value("DATABASE_URL"))
+        else
+          connection_from_env("")
+        end
+      end
+
+      def restore_connection
+        if value("RESTORE_DATABASE_URL")
+          parse_url(value("RESTORE_DATABASE_URL"))
+        else
+          connection_from_env("RESTORE_")
+        end
+      end
+
+      def connection_from_env(prefix)
+        database = value("#{prefix}MYSQL_DATABASE") || value("#{prefix}MARIADB_DATABASE")
+        raise ConfigurationError, "#{prefix}MYSQL_DATABASE or #{prefix}MARIADB_DATABASE is required" unless database
+
+        {
+          host: value("#{prefix}MYSQL_HOST") || value("#{prefix}MARIADB_HOST"),
+          port: value("#{prefix}MYSQL_PORT") || value("#{prefix}MARIADB_PORT"),
+          user: value("#{prefix}MYSQL_USER") || value("#{prefix}MARIADB_USER"),
+          password: value("#{prefix}MYSQL_PWD") || value("#{prefix}MYSQL_PASSWORD") || value("#{prefix}MARIADB_PASSWORD"),
+          database: database
+        }
+      end
+
+      def parse_url(url)
+        uri = URI.parse(url)
+        database = uri.path.to_s.sub(%r{\A/}, "")
+        raise ConfigurationError, "database name is missing in #{uri.scheme} DATABASE_URL" if database.empty?
+
+        {
+          host: uri.host,
+          port: uri.port,
+          user: uri.user ? URI.decode_www_form_component(uri.user) : nil,
+          password: uri.password ? URI.decode_www_form_component(uri.password) : nil,
+          database: URI.decode_www_form_component(database)
+        }
+      rescue URI::InvalidURIError => e
+        raise ConfigurationError, "invalid database URL: #{e.message}"
+      end
+
+      def connection_args(connection)
+        args = []
+        args.concat(["--host", connection[:host]]) if connection[:host]
+        args.concat(["--port", connection[:port].to_s]) if connection[:port]
+        args.concat(["--user", connection[:user]]) if connection[:user]
+        args
+      end
+
+      def password_env(connection)
+        connection[:password] ? { "MYSQL_PWD" => connection[:password] } : {}
+      end
+    end
+  end
+end

data/lib/kamal_backup/databases/postgres.rb

@@ -0,0 +1,125 @@
+require "uri"
+require_relative "base"
+
+module KamalBackup
+  module Databases
+    class Postgres < Base
+      SOURCE_ENV_KEYS = %w[
+        PGHOST
+        PGPORT
+        PGUSER
+        PGPASSWORD
+        PGDATABASE
+        PGSSLMODE
+        PGSSLROOTCERT
+        PGSSLCERT
+        PGSSLKEY
+        PGCONNECT_TIMEOUT
+        PGSERVICE
+        PGPASSFILE
+      ].freeze
+
+      RESTORE_ENV_MAP = {
+        "RESTORE_PGHOST" => "PGHOST",
+        "RESTORE_PGPORT" => "PGPORT",
+        "RESTORE_PGUSER" => "PGUSER",
+        "RESTORE_PGPASSWORD" => "PGPASSWORD",
+        "RESTORE_PGDATABASE" => "PGDATABASE",
+        "RESTORE_PGSSLMODE" => "PGSSLMODE"
+      }.freeze
+
+      def adapter_name
+        "postgres"
+      end
+
+      def dump_extension
+        "pgdump"
+      end
+
+      def dump_command
+        argv = %w[pg_dump --format=custom --no-owner --no-privileges]
+        CommandSpec.new(argv: argv, env: backup_env)
+      end
+
+      def restore_command
+        connection = restore_connection
+        database = connection.fetch("PGDATABASE")
+
+        argv = %w[pg_restore --clean --if-exists --no-owner --no-privileges --dbname]
+        argv << database
+        CommandSpec.new(argv: argv, env: connection)
+      end
+
+      def restore_target_identifier
+        value("RESTORE_DATABASE_URL") || value("RESTORE_PGDATABASE")
+      end
+
+      private
+
+      def backup_env
+        if value("DATABASE_URL")
+          connection_from_url(value("DATABASE_URL"), "DATABASE_URL")
+        else
+          prefixed_env("", SOURCE_ENV_KEYS)
+        end
+      end
+
+      def restore_connection
+        if value("RESTORE_DATABASE_URL")
+          connection_from_url(value("RESTORE_DATABASE_URL"), "RESTORE_DATABASE_URL")
+        else
+          connection = restore_env
+          raise ConfigurationError, "RESTORE_DATABASE_URL or RESTORE_PGDATABASE is required for PostgreSQL restore" unless connection["PGDATABASE"]
+
+          connection
+        end
+      end
+
+      def restore_env
+        RESTORE_ENV_MAP.each_with_object({}) do |(source, target), env|
+          env[target] = value(source) if value(source)
+        end
+      end
+
+      def prefixed_env(prefix, keys)
+        keys.each_with_object({}) do |key, env|
+          env[key] = value("#{prefix}#{key}") if value("#{prefix}#{key}")
+        end
+      end
+
+      def connection_from_url(url, name)
+        uri = URI.parse(url)
+        unless %w[postgres postgresql].include?(uri.scheme)
+          raise ConfigurationError, "#{name} must use postgres:// or postgresql://"
+        end
+
+        database = URI.decode_www_form_component(uri.path.to_s.sub(%r{\A/}, ""))
+        raise ConfigurationError, "database name is missing in #{name}" if database.empty?
+
+        env = {
+          "PGHOST" => uri.host,
+          "PGPORT" => uri.port&.to_s,
+          "PGUSER" => uri.user ? URI.decode_www_form_component(uri.user) : nil,
+          "PGPASSWORD" => uri.password ? URI.decode_www_form_component(uri.password) : nil,
+          "PGDATABASE" => database
+        }.compact
+
+        query = URI.decode_www_form(uri.query.to_s).to_h
+        {
+          "sslmode" => "PGSSLMODE",
+          "sslrootcert" => "PGSSLROOTCERT",
+          "sslcert" => "PGSSLCERT",
+          "sslkey" => "PGSSLKEY",
+          "connect_timeout" => "PGCONNECT_TIMEOUT"
+        }.each do |source, target|
+          env[target] = query[source] if query[source]
+        end
+
+        env
+      rescue URI::InvalidURIError => e
+        raise ConfigurationError, "invalid #{name}: #{e.message}"
+      end
+
+    end
+  end
+end

data/lib/kamal_backup/databases/sqlite.rb

@@ -0,0 +1,73 @@
+require "fileutils"
+require "tempfile"
+require_relative "base"
+
+module KamalBackup
+  module Databases
+    class Sqlite < Base
+      def adapter_name
+        "sqlite"
+      end
+
+      def dump_extension
+        "sqlite3"
+      end
+
+      def backup(restic, timestamp)
+        source = sqlite_source
+        Tempfile.create(["kamal-backup-", ".sqlite3"]) do |tempfile|
+          tempfile.close
+          Command.capture(
+            CommandSpec.new(argv: ["sqlite3", source, ".backup #{sqlite_literal(tempfile.path)}"]),
+            redactor: redactor
+          )
+          restic.backup_file_content(
+            tempfile.path,
+            filename: database_filename(timestamp),
+            tags: backup_tags(timestamp)
+          )
+        end
+      end
+
+      def restore(restic, snapshot, filename)
+        validate_restore_target!
+        restic.dump_file_to_path(snapshot, filename, restore_target)
+      end
+
+      def dump_command
+        raise NotImplementedError, "SQLite backup uses .backup into a temporary file"
+      end
+
+      def restore_command
+        raise NotImplementedError, "SQLite restore writes the database file directly"
+      end
+
+      def restore_target_identifier
+        restore_target
+      end
+
+      private
+
+      def sqlite_source
+        config.required!("SQLITE_DATABASE_PATH")
+      end
+
+      def restore_target
+        config.required!("RESTORE_SQLITE_DATABASE_PATH")
+      end
+
+      def validate_restore_target!
+        source = File.expand_path(sqlite_source)
+        target = File.expand_path(restore_target)
+        if source == target && !config.allow_in_place_file_restore?
+          raise ConfigurationError, "refusing in-place SQLite restore to #{target}; set KAMAL_BACKUP_ALLOW_IN_PLACE_FILE_RESTORE=true to override"
+        end
+        super
+      end
+
+      def sqlite_literal(value)
+        "'#{value.to_s.gsub("'", "''")}'"
+      end
+    end
+  end
+end

data/lib/kamal_backup/errors.rb

@@ -0,0 +1,16 @@
+module KamalBackup
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class CommandError < Error
+    attr_reader :command, :status, :stdout, :stderr
+
+    def initialize(message, command:, status: nil, stdout: "", stderr: "")
+      super(message)
+      @command = command
+      @status = status
+      @stdout = stdout.to_s
+      @stderr = stderr.to_s
+    end
+  end
+end