yobi 0.1.0

data/lib/yobi/repository/key.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "delegate"
+
+module Yobi
+  class Repository
+    # `restic key add`: creates a new key (password) for this repository.
+    #
+    # @param host [String, nil] hostname to record on the new key
+    # @param user [String, nil] username to record on the new key
+    # @param new_insecure_no_password [Boolean] create the new key with an empty password
+    # @param new_password_file [String, nil] path to a file containing the new key's password
+    # @return [true]
+    def key_add(host: nil, user: nil, new_insecure_no_password: false, new_password_file: nil)
+      argv = build_argv("key", "add") do |a|
+        a.flag(:host, host) unless host.nil?
+        a.flag(:user, user) unless user.nil?
+        a.flag(:new_insecure_no_password) if new_insecure_no_password
+        a.flag(:new_password_file, new_password_file) unless new_password_file.nil?
+      end
+      run_restic(argv)
+      true
+    end
+    alias_method :add_key, :key_add
+
+    # `restic key list`: lists every key (password) associated with this repository.
+    #
+    # @return [Enumerable<Yobi::Key>]
+    def key_list
+      execution = run_restic(build_argv("key", "list"))
+      Keys.new(execution[:output])
+    end
+    alias_method :keys, :key_list
+
+    # `restic key passwd`: creates a new key for this repository and
+    # removes the key currently in use. Doesn't mutate this `Repository`
+    # instance's own `password:`. Build a new `Repository` with the
+    # rotated password to keep talking to this repository afterward.
+    #
+    # @param host [String, nil] hostname to record on the new key
+    # @param user [String, nil] username to record on the new key
+    # @param new_insecure_no_password [Boolean] set the new key's password to empty
+    # @param new_password_file [String, nil] path to a file containing the new key's password
+    # @return [true]
+    def key_passwd(host: nil, user: nil, new_insecure_no_password: false, new_password_file: nil)
+      argv = build_argv("key", "passwd") do |a|
+        a.flag(:host, host) unless host.nil?
+        a.flag(:user, user) unless user.nil?
+        a.flag(:new_insecure_no_password) if new_insecure_no_password
+        a.flag(:new_password_file, new_password_file) unless new_password_file.nil?
+      end
+      run_restic(argv)
+      true
+    end
+    alias_method :change_password, :key_passwd
+
+    # `restic key remove`: removes the given key ID from this repository.
+    # Restic refuses to remove the key currently being used to access the
+    # repository.
+    #
+    # @param id [String]
+    # @return [true]
+    def key_remove(id:)
+      run_restic(build_argv("key", "remove", id))
+      true
+    end
+    alias_method :remove_key, :key_remove
+  end
+
+  # One key (password) associated with the repository, from {Yobi::Repository#key_list}.
+  class Key < SimpleDelegator
+    # @return [String]
+    def id
+      self["id"]
+    end
+
+    # @return [String]
+    def user_name
+      self["userName"]
+    end
+
+    # @return [String]
+    def host_name
+      self["hostName"]
+    end
+
+    # @return [Boolean] whether this is the key currently in use
+    def current?
+      self["current"]
+    end
+
+    # @return [Time]
+    def created
+      @created ||= Time.parse(self["created"])
+    end
+  end
+
+  # Enumerable over every {Yobi::Key} in one {Yobi::Repository#key_list} call.
+  class Keys
+    include Enumerable
+
+    # @return [Yobi::ResticOutput]
+    attr_reader :output
+
+    # @param output [Yobi::ResticOutput]
+    def initialize(output)
+      @output = output
+    end
+
+    # @yieldparam key [Yobi::Key]
+    # @return [Enumerator] if no block is given
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      keys.each(&block)
+    end
+
+    private
+
+    def keys
+      @keys ||= JSON.parse(output.to_s).map { |raw| Yobi::Key.new(raw) }
+    end
+  end
+end

data/lib/yobi/repository/list.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Yobi
+  class Repository
+    # `restic list`: lists every object ID of the given type in this
+    # repository. Restic ignores `--json` for this command; each line is a
+    # bare ID, except for `:blobs`, where each line is `"data <id>"` or `"tree <id>"`.
+    #
+    # @param type [Symbol, String] `:blobs`, `:packs`, `:index`, `:snapshots`, `:keys`, or `:locks`
+    # @return [Array<String>]
+    def list(type)
+      argv = build_argv("list", type)
+      execution = run_restic(argv)
+      execution[:output].to_s.each_line.map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/yobi/repository/ls.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "delegate"
+
+module Yobi
+  class Repository
+    # `restic ls`: lists a snapshot's files/directories.
+    #
+    # @param snapshot_id [String] also accepts `"latest"`
+    # @param dirs [Array<String>, String] restrict to these directories within the snapshot
+    # @param hosts [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
+    # @param human_readable [Boolean] format sizes for humans
+    # @param long [Boolean] include long listing format
+    # @param paths [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
+    # @param recursive [Boolean] recurse into subdirectories
+    # @param reverse [Boolean] reverse sort order
+    # @param sort [String, nil] sort key, e.g. `"size"`
+    # @param tags [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
+    # @return [Yobi::LsOutcome]
+    def ls(snapshot_id:, dirs: [], hosts: [], human_readable: false, long: false, paths: [],
+      recursive: false, reverse: false, sort: nil, tags: [])
+      argv = build_argv("ls", snapshot_id) do |a|
+        a.repeat_flag(:host, hosts)
+        a.flag(:human_readable) if human_readable
+        a.flag(:long) if long
+        a.repeat_flag(:path, paths)
+        a.flag(:recursive) if recursive
+        a.flag(:reverse) if reverse
+        a.flag(:sort, sort) unless sort.nil?
+        a.repeat_flag(:tag, tags)
+        a.end_of_options.append(dirs)
+      end
+      execution = run_restic(argv)
+      LsOutcome.new(execution[:exit_code], execution[:output])
+    end
+  end
+
+  # The outcome of one {Yobi::Repository#ls} call.
+  class LsOutcome < Struct.new(:exit_code, :output)
+    # @return [Yobi::Snapshot] the resolved snapshot, useful when `snapshot_id:` was `"latest"`
+    def snapshot
+      @snapshot ||= Yobi::Snapshot.new(JSON.parse(snapshot_line))
+    end
+
+    # @return [Enumerable<Yobi::LsEntry>]
+    def entries
+      @entries ||= LsEntries.new(output)
+    end
+
+    private
+
+    def snapshot_line
+      offset = output.index["snapshot"].first
+      output.read_line_at(offset)
+    end
+  end
+
+  # One file/directory entry from a {Yobi::Repository#ls} call.
+  class LsEntry < SimpleDelegator
+    # @return [String]
+    def name
+      self["name"]
+    end
+
+    # @return [String]
+    def type
+      self["type"]
+    end
+
+    # @return [String]
+    def path
+      self["path"]
+    end
+
+    # @return [Integer]
+    def size
+      self["size"]
+    end
+
+    # @return [String]
+    def permissions
+      self["permissions"]
+    end
+
+    # @return [Integer]
+    def uid
+      self["uid"]
+    end
+
+    # @return [Integer]
+    def gid
+      self["gid"]
+    end
+
+    # @return [Integer]
+    def inode
+      self["inode"]
+    end
+
+    # @return [Time]
+    def mtime
+      @mtime ||= Time.parse(self["mtime"])
+    end
+
+    # @return [Time]
+    def atime
+      @atime ||= Time.parse(self["atime"])
+    end
+
+    # @return [Time]
+    def ctime
+      @ctime ||= Time.parse(self["ctime"])
+    end
+  end
+
+  # Enumerable over every {Yobi::LsEntry} in a run.
+  class LsEntries
+    include Enumerable
+
+    # @param output [Yobi::ResticOutput]
+    def initialize(output)
+      @output = output
+    end
+
+    # @yieldparam entry [Yobi::LsEntry]
+    # @return [Enumerator] if no block is given
+    def each
+      return enum_for(:each) unless block_given?
+
+      @output.index["node"].each do |offset|
+        line = @output.read_line_at(offset)
+        yield LsEntry.new(JSON.parse(line))
+      end
+    end
+  end
+end

data/lib/yobi/repository/migrate.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Yobi
+  class Repository
+    # `restic migrate`: checks which migrations can be applied to this
+    # repository, or applies the given ones. Restic ignores `--json` for
+    # this command, so there's no programmatic way to discover which
+    # migrations are available. Run `restic migrate` directly for that.
+    #
+    # @param names [Array<String>, String] migration names to apply; only lists available ones if empty
+    # @param force [Boolean] reapply a migration already marked as applied
+    # @return [true]
+    def migrate(names: [], force: false)
+      argv = build_argv("migrate", names) do |a|
+        a.flag(:force) if force
+      end
+      run_restic(argv)
+      true
+    end
+  end
+end

data/lib/yobi/repository/mount.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "open3"
+require "tempfile"
+
+module Yobi
+  class Repository
+    # `restic mount`: serves this repository as a read-only FUSE
+    # filesystem at `mountpoint`, which must already exist.
+    #
+    # Without a block, returns a {Yobi::Mount} once Restic reports itself
+    # ready; call `#stop` yourself once done. With one, yields the `Mount`
+    # and stops it automatically once the block returns or raises.
+    #
+    # @param mountpoint [String] must already exist
+    # @param hosts [Array<String>, String] restrict which snapshots appear under `snapshots/`
+    # @param paths [Array<String>, String] restrict which snapshots appear under `snapshots/`
+    # @param tags [Array<String>, String] restrict which snapshots appear under `snapshots/`
+    # @param allow_other [Boolean] allow other users to access the mount
+    # @param no_default_permissions [Boolean] don't check file permissions
+    # @param owner_root [Boolean] mount files as owned by root
+    # @param path_templates [Array<String>, String] directory naming scheme(s) under `snapshots/`
+    # @param time_template [String, nil] directory naming scheme for time-based paths
+    # @param ready_timeout [Numeric] seconds to wait for Restic's readiness message before raising
+    # @yieldparam mount [Yobi::Mount]
+    # @return [Yobi::Mount] if no block is given
+    # @return [Object] the block's own return value, otherwise
+    # @raise [Yobi::MountTimeout]
+    def mount(mountpoint:, hosts: [], paths: [], tags: [], allow_other: false,
+      no_default_permissions: false, owner_root: false, path_templates: [], time_template: nil,
+      ready_timeout: 10)
+      argv = build_argv("mount") do |a|
+        a.flag(:allow_other) if allow_other
+        a.repeat_flag(:host, hosts)
+        a.flag(:no_default_permissions) if no_default_permissions
+        a.flag(:owner_root) if owner_root
+        a.repeat_flag(:path, paths)
+        a.repeat_flag(:path_template, path_templates)
+        a.repeat_flag(:tag, tags)
+        a.flag(:time_template, time_template) unless time_template.nil?
+        a.end_of_options.append(mountpoint)
+      end
+
+      mount = run_restic_mount(argv, mountpoint: mountpoint.to_s, ready_timeout: ready_timeout)
+      return mount unless block_given?
+
+      begin
+        yield mount
+      ensure
+        mount.stop
+      end
+    end
+
+    private
+
+    def run_restic_mount(argv, mountpoint:, ready_timeout:)
+      @restic.run_mount(argv, mountpoint: mountpoint, extra_env: env, ready_timeout: ready_timeout)
+    end
+  end
+
+  class Restic
+    # Restic's own stdout line signaling a mount is ready to serve.
+    READY_LINE = "Now serving the repository at"
+
+    # For {Yobi::Repository#mount}. Spawns Restic and waits for its
+    # readiness line (or `ready_timeout:` seconds, or Restic exiting on
+    # its own) before returning.
+    #
+    # @param argv [Array<String>]
+    # @param mountpoint [String]
+    # @param extra_env [Hash{String => String}]
+    # @param ready_timeout [Numeric]
+    # @return [Yobi::Mount]
+    # @raise [Yobi::MountTimeout]
+    def run_mount(argv, mountpoint:, extra_env: {}, ready_timeout: 10)
+      ensure_minimum_version!
+      file = Tempfile.new("yobi-restic-output")
+      file.unlink
+
+      stdin, output, wait_thr = Open3.popen2e(env.merge(extra_env), restic_path, *argv)
+      stdin.close
+
+      case wait_for_ready(output, file, mountpoint, ready_timeout)
+      when :ready
+        Yobi::Mount.new(wait_thr: wait_thr, mountpoint: mountpoint, output: output, output_file: file, argv: argv)
+      when :timeout
+        Process.kill("INT", wait_thr.pid)
+        wait_thr.value
+        raise Yobi::MountTimeout.new(argv: argv, timeout: ready_timeout)
+      when :exited
+        status = wait_thr.value
+        self.class.dispatch(exit_code: status.exitstatus, output: Yobi::ResticOutput.new(file), argv: argv)
+      end
+    rescue Errno::ENOENT
+      file&.close
+      raise Yobi::ResticNotFound.new(restic_path: restic_path, argv: argv)
+    end
+
+    private
+
+    def wait_for_ready(output, file, mountpoint, timeout)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+
+      loop do
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        return :timeout if remaining <= 0
+        return :timeout if IO.select([output], nil, nil, remaining).nil?
+
+        line = output.gets
+        return :exited if line.nil?
+
+        file.write(line)
+        return (wait_for_mountpoint(mountpoint, deadline) ? :ready : :timeout) if line.include?(READY_LINE)
+      end
+    end
+
+    def wait_for_mountpoint(mountpoint, deadline)
+      until Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+        begin
+          return true unless Dir.empty?(mountpoint)
+        rescue Errno::ENOENT, Errno::ENOTCONN, Errno::ENXIO, Errno::EIO
+          nil
+        end
+        sleep 0.005
+      end
+      false
+    end
+  end
+end

data/lib/yobi/repository/prune.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Yobi
+  class Repository
+    # `restic prune`: removes data no longer referenced by any snapshot.
+    #
+    # @param dry_run [Boolean] report what would happen without doing it
+    # @param max_repack_size [String, nil] limit the amount of data repacked in this run
+    # @param max_unused [String, nil] target maximum unused space after pruning, e.g. `"10%"`
+    # @param repack_cacheable_only [Boolean] only repack packs that are cached locally
+    # @param repack_smaller_than [String, nil] also repack packs smaller than this size
+    # @param repack_uncompressed [Boolean] repack packs not yet using compression
+    # @param unsafe_recover_no_free_space [String, nil] proceed even without enough free space, at the given risk acknowledgement
+    # @return [true]
+    def prune(dry_run: false, max_repack_size: nil, max_unused: nil, repack_cacheable_only: false,
+      repack_smaller_than: nil, repack_uncompressed: false, unsafe_recover_no_free_space: nil)
+      argv = build_argv("prune") do |a|
+        a.flag(:dry_run) if dry_run
+        a.flag(:max_repack_size, max_repack_size) unless max_repack_size.nil?
+        a.flag(:max_unused, max_unused) unless max_unused.nil?
+        a.flag(:repack_cacheable_only) if repack_cacheable_only
+        a.flag(:repack_smaller_than, repack_smaller_than) unless repack_smaller_than.nil?
+        a.flag(:repack_uncompressed) if repack_uncompressed
+        a.flag(:unsafe_recover_no_free_space, unsafe_recover_no_free_space) unless unsafe_recover_no_free_space.nil?
+      end
+      run_restic(argv)
+      true
+    end
+  end
+end

data/lib/yobi/repository/recover.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Yobi
+  class Repository
+    # `restic recover`: builds a new snapshot from any data found in this
+    # repository that isn't referenced by an existing snapshot (e.g. after
+    # an accidental {#forget}). Call {#snapshots} afterward to find the
+    # recovered snapshot, if any was created.
+    #
+    # @return [true]
+    def recover
+      run_restic(build_argv("recover"))
+      true
+    end
+  end
+end

data/lib/yobi/repository/repair.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Yobi
+  class Repository
+    # `restic repair index`: creates a new index based on the pack files
+    # present in this repository. Successor to the deprecated
+    # `rebuild-index` command.
+    #
+    # @param read_all_packs [Boolean] read every pack file fully instead of just headers
+    # @return [true]
+    def repair_index(read_all_packs: false)
+      argv = build_argv("repair", "index") do |a|
+        a.flag(:read_all_packs) if read_all_packs
+      end
+      run_restic(argv)
+      true
+    end
+
+    # `restic repair packs`: extracts intact blobs from the given pack
+    # files, rebuilds the index to drop the damaged packs, and removes
+    # them from the repository. Restic also writes a backup copy of each
+    # given pack file (named `pack-<id>`) into the calling process's
+    # current working directory before removing it. There's no flag to
+    # disable this.
+    #
+    # @param ids [Array<String>, String] pack IDs
+    # @return [true]
+    def repair_packs(ids:)
+      argv = build_argv("repair", "packs", ids)
+      run_restic(argv)
+      true
+    end
+
+    # `restic repair snapshots`: scans the given snapshots and generates
+    # new ones with damaged directories/file contents removed. This
+    # causes data loss for the content actually removed; prefer a fresh
+    # {Yobi::Repository#backup} where the source data is still available.
+    # Depends on a correct index. Call {#repair_index} first.
+    #
+    # @param snapshot_ids [Array<String>, String] snapshots to repair; all of them if empty
+    # @param dry_run [Boolean] report what would happen without doing it
+    # @param forget [Boolean] remove the original damaged snapshots after repairing
+    # @param hosts [Array<String>, String] filter by hostname(s)
+    # @param paths [Array<String>, String] filter by originally backed-up path(s)
+    # @param tags [Array<String>, String] filter by tag(s)
+    # @return [true]
+    def repair_snapshots(snapshot_ids: [], dry_run: false, forget: false, hosts: [], paths: [], tags: [])
+      argv = build_argv("repair", "snapshots", snapshot_ids) do |a|
+        a.flag(:dry_run) if dry_run
+        a.flag(:forget) if forget
+        a.repeat_flag(:host, hosts)
+        a.repeat_flag(:path, paths)
+        a.repeat_flag(:tag, tags)
+      end
+      run_restic(argv)
+      true
+    end
+  end
+end