yobi 0.1.0 → 0.2.0

data/lib/yobi/repository/diff.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
-require "delegate"
-
 module Yobi
   class Repository
     # `restic diff`: compares two snapshots.
@@ -15,51 +12,66 @@ module Yobi
       argv = build_argv("diff", from, to) do |a|
         a.flag(:metadata) if metadata
       end
-      execution = run_restic(argv)
-      DiffOutcome.new(execution[:exit_code], execution[:output])
+      output = Yobi::ResticOutput.new(transform: Yobi::DiffMessageWrapper)
+      execution = run_restic(argv, output: output)
+      DiffOutcome.new(execution)
     end
   end
 
-  # The outcome of one {Yobi::Repository#diff} call.
-  class DiffOutcome < Struct.new(:exit_code, :output)
-    # @return [Hash] Restic's own `"statistics"` fields (`"changed_files"`, `"added"`, `"removed"`, ...)
-    def report
-      @report ||= summary_hash
+  # Classifies a raw diff message Hash by its own message_type, wrapping
+  # it in the matching typed class. Used both as the {Yobi::ResticOutput}
+  # `transform:` for {Yobi::Repository#diff} and by {Yobi::DiffOutcome}'s
+  # own post-hoc accessors.
+  #
+  # @private
+  module DiffMessageWrapper
+    # @param raw [Hash]
+    # @return [Yobi::DiffChange, Yobi::DiffStatistics, Hash]
+    #   the raw Hash itself for a message_type this version of Yobi doesn't recognize
+    def self.call(raw)
+      case raw["message_type"]
+      when "change" then DiffChange.new(raw)
+      when "statistics" then DiffStatistics.new(raw)
+      else raw
+      end
     end
+  end
 
-    # @return [Enumerable<Yobi::DiffChange>]
-    def changes
-      @changes ||= DiffChanges.new(output)
-    end
+  # The outcome of one {Yobi::Repository#diff} call.
+  class DiffOutcome
+    # @return [Yobi::ResticOutput]
+    attr_reader :output
 
-    private
+    # @private
+    def initialize(execution)
+      @output = execution[:output]
+    end
 
-    def summary_hash
-      line = output.last_line
-      hash = line && JSON.parse(line)
-      if hash && hash["message_type"] == "statistics"
-        hash
-      else
-        find_summary || {}
-      end
+    # @return [Yobi::DiffStatistics] Restic's own `"statistics"` fields
+    def statistics
+      @statistics ||= output.messages("statistics").first || DiffStatistics.new({})
     end
+    alias_method :report, :statistics
 
-    def find_summary
-      output.each_line do |line|
-        next if line.strip.empty?
+    # @return [Enumerable<Yobi::DiffChange>]
+    def changes
+      @changes ||= output.messages("change")
+    end
 
-        hash = JSON.parse(line)
-        return hash if hash["message_type"] == "statistics"
+    # @return [void]
+    def pretty_print(q)
+      q.object_group(self) do
+        q.breakable
+        q.pp statistics
       end
-
-      nil
     end
   end
 
   # One `"change"` message from a diff run. `modifier` is Restic's own
-  # single-character code: `"+"` added, `"-"` removed, `"U"` metadata
-  # updated, `"M"` content modified, `"T"` type changed, `"?"` bitrot detected.
-  class DiffChange < SimpleDelegator
+  # concatenation of single-character codes: `"+"` added, `"-"` removed,
+  # `"U"` metadata updated, `"M"` content modified, `"T"` type changed,
+  # `"?"` bitrot detected.
+  class DiffChange < Yobi::FancyHash
     # @return [String]
     def path
       self["path"]
@@ -69,26 +81,97 @@ module Yobi
     def modifier
       self["modifier"]
     end
+
+    # @return [Boolean]
+    def added?
+      modifier.include?("+")
+    end
+
+    # @return [Boolean]
+    def removed?
+      modifier.include?("-")
+    end
+
+    # @return [Boolean]
+    def type_changed?
+      modifier.include?("T")
+    end
+
+    # @return [Boolean]
+    def modified?
+      modifier.include?("M")
+    end
+
+    # @return [Boolean]
+    def metadata_updated?
+      modifier.include?("U")
+    end
+
+    # @return [Boolean]
+    def bitrot?
+      modifier.include?("?")
+    end
   end
 
-  # Enumerable over every {Yobi::DiffChange} in a run.
-  class DiffChanges
-    include Enumerable
+  # The `"statistics"` message from a diff run, the final result once the
+  # command finishes. Dispatched to {Yobi::DiffOutcome#statistics}.
+  class DiffStatistics < Yobi::FancyHash
+    # @return [String, nil]
+    def source_snapshot
+      self["source_snapshot"]
+    end
 
-    # @param output [Yobi::ResticOutput]
-    def initialize(output)
-      @output = output
+    # @return [String, nil]
+    def target_snapshot
+      self["target_snapshot"]
     end
 
-    # @yieldparam change [Yobi::DiffChange]
-    # @return [Enumerator] if no block is given
-    def each
-      return enum_for(:each) unless block_given?
+    # @return [Integer]
+    def changed_files
+      self["changed_files"] || 0
+    end
 
-      @output.index["change"].each do |offset|
-        line = @output.read_line_at(offset)
-        yield DiffChange.new(JSON.parse(line))
-      end
+    # @return [Yobi::DiffStat]
+    def added
+      @added ||= DiffStat.new(self["added"] || {})
+    end
+
+    # @return [Yobi::DiffStat]
+    def removed
+      @removed ||= DiffStat.new(self["removed"] || {})
+    end
+  end
+
+  # The `"added"`/`"removed"` sub-object of a {Yobi::DiffStatistics} message.
+  class DiffStat < Yobi::FancyHash
+    # @return [Integer]
+    def files
+      self["files"] || 0
+    end
+
+    # @return [Integer]
+    def dirs
+      self["dirs"] || 0
+    end
+
+    # @return [Integer]
+    def others
+      self["others"] || 0
+    end
+
+    # @return [Integer]
+    def data_blobs
+      self["data_blobs"] || 0
+    end
+
+    # @return [Integer]
+    def tree_blobs
+      self["tree_blobs"] || 0
+    end
+
+    # @return [Integer]
+    def bytes
+      self["bytes"] || 0
     end
   end
 end

data/lib/yobi/repository/dump.rb

@@ -4,7 +4,7 @@ require "tempfile"
 
 module Yobi
   class Repository
-    # Valid `archive:` values for {#dump}, as both String and Symbol.
+    # @private
     ARCHIVE_TYPES = Set.new(%w[tar zip].flat_map { [_1, _1.to_sym] }).freeze
 
     # `restic dump`: extracts a file/folder from a snapshot. A single file's

data/lib/yobi/repository/find.rb

@@ -2,7 +2,6 @@
 
 require "json"
 require "time"
-require "delegate"
 
 module Yobi
   class Repository
@@ -24,7 +23,7 @@ module Yobi
     # @param show_pack_id [Boolean] include the pack ID each match is stored in
     # @param snapshot_ids [Array<String>, String] restrict to these snapshot ID(s)
     # @param tags [Array<String>, String] filter by tag(s)
-    # @return [Enumerable<Yobi::MatchesPerSnapshot>]
+    # @return [Array<Yobi::MatchesPerSnapshot>]
     def find(patterns:, blob: false, pack: false, tree: false, hosts: [], human_readable: false,
       ignore_case: false, long: false, newest: nil, oldest: nil, paths: [], reverse: false,
       show_pack_id: false, snapshot_ids: [], tags: [])
@@ -46,12 +45,12 @@ module Yobi
         a.end_of_options.append(patterns)
       end
       execution = run_restic(argv)
-      FindMatches.new(execution[:output])
+      JSON.parse(execution[:output].to_s).map { |raw| MatchesPerSnapshot.new(raw) }
     end
   end
 
   # One matched file/directory from a {Yobi::Repository#find} call.
-  class FindMatch < SimpleDelegator
+  class FindMatch < Yobi::FancyHash
     # @return [String]
     def path
       self["path"]
@@ -114,11 +113,17 @@ module Yobi
   end
 
   # One snapshot's worth of matches from a {Yobi::Repository#find} call.
-  class MatchesPerSnapshot < SimpleDelegator
-    # @return [Hash]
+  class MatchesPerSnapshot < Yobi::FancyHash
+    # Restic's own `find --json` output only gives the snapshot's ID here,
+    # not a full record - unlike every other place in this API where
+    # "snapshot" means a {Yobi::Snapshot}. Call {Yobi::Repository#snapshots}
+    # yourself if you need the full record.
+    #
+    # @return [String]
     def snapshot
       self["snapshot"]
     end
+    alias_method :snapshot_id, :snapshot
 
     # @return [Integer]
     def hits
@@ -130,31 +135,4 @@ module Yobi
       @matches ||= (self["matches"] || []).map { |raw| Yobi::FindMatch.new(raw) }
     end
   end
-
-  # Enumerable over every {Yobi::MatchesPerSnapshot} in one {Yobi::Repository#find} call.
-  class FindMatches
-    include Enumerable
-
-    # @return [Yobi::ResticOutput]
-    attr_reader :output
-
-    # @param output [Yobi::ResticOutput]
-    def initialize(output)
-      @output = output
-    end
-
-    # @yieldparam matches [Yobi::MatchesPerSnapshot]
-    # @return [Enumerator] if no block is given
-    def each(&block)
-      return enum_for(:each) unless block_given?
-
-      matches_per_snapshot.each(&block)
-    end
-
-    private
-
-    def matches_per_snapshot
-      @matches_per_snapshot ||= JSON.parse(output.to_s).map { |raw| Yobi::MatchesPerSnapshot.new(raw) }
-    end
-  end
 end

data/lib/yobi/repository/forget.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "json"
-require "delegate"
 
 module Yobi
   class Repository
@@ -34,7 +33,7 @@ module Yobi
     # @param repack_cacheable_only [Boolean] passed through to the implied prune
     # @param repack_uncompressed [Boolean] passed through to the implied prune
     # @param repack_smaller_than [String, nil] passed through to the implied prune
-    # @return [Enumerable<Yobi::ForgetGroup>]
+    # @return [Array<Yobi::ForgetGroup>]
     def forget(keep_last: nil, keep_hourly: nil, keep_daily: nil, keep_weekly: nil, keep_monthly: nil,
       keep_yearly: nil, keep_within: nil, keep_within_hourly: nil, keep_within_daily: nil,
       keep_within_weekly: nil, keep_within_monthly: nil, keep_within_yearly: nil, keep_tags: [],
@@ -70,54 +69,13 @@ module Yobi
         a.flag(:repack_smaller_than, repack_smaller_than) unless repack_smaller_than.nil?
       end
       execution = run_restic(argv)
-      ForgetGroups.new(execution[:exit_code], execution[:output])
-    end
-  end
-
-  # The outcome of one {Yobi::Repository#forget} call.
-  class ForgetGroups
-    include Enumerable
-
-    # @return [Integer]
-    attr_reader :exit_code
-    # @return [Yobi::ResticOutput]
-    attr_reader :output
-
-    # @param exit_code [Integer]
-    # @param output [Yobi::ResticOutput]
-    def initialize(exit_code, output)
-      @exit_code = exit_code
-      @output = output
-    end
-
-    # @yieldparam group [Yobi::ForgetGroup]
-    # @return [Enumerator] if no block is given
-    def each(&block)
-      return enum_for(:each) unless block_given?
-
-      groups.each(&block)
-    end
-
-    # @return [Boolean]
-    def success?
-      exit_code.zero?
-    end
-
-    # @return [Boolean]
-    def partial?
-      exit_code == 3
-    end
-
-    private
-
-    def groups
-      @groups ||= JSON.parse(output.to_s).map { |raw| Yobi::ForgetGroup.new(raw) }
+      JSON.parse(execution[:output].to_s).map { |raw| ForgetGroup.new(raw) }
     end
   end
 
   # One grouping Restic's forget policy was evaluated against (by default,
   # grouped by host+paths).
-  class ForgetGroup < SimpleDelegator
+  class ForgetGroup < Yobi::FancyHash
     # @return [String]
     def host
       self["host"]
@@ -143,14 +101,14 @@ module Yobi
       @remove ||= (self["remove"] || []).map { |entry| Yobi::Snapshot.new(entry) }
     end
 
-    # @return [Array<Yobi::ForgetReason>] one per kept snapshot, explaining which policy rule(s) kept it
+    # @return [Array<Yobi::KeepReason>] one per kept snapshot, explaining which policy rule(s) kept it
     def reasons
-      @reasons ||= (self["reasons"] || []).map { |entry| Yobi::ForgetReason.new(entry) }
+      @reasons ||= (self["reasons"] || []).map { |entry| Yobi::KeepReason.new(entry) }
     end
   end
 
   # Why one snapshot survived a {Yobi::Repository#forget} run.
-  class ForgetReason < SimpleDelegator
+  class KeepReason < Yobi::FancyHash
     # @return [Yobi::Snapshot]
     def snapshot
       @snapshot ||= Yobi::Snapshot.new(self["snapshot"])

data/lib/yobi/repository/init.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Yobi
+  class Repository
+    # `restic init`: creates the repository at {#url}.
+    #
+    # @param copy_chunker_params [Boolean] copy chunker parameters from `from_repo:`/`from_repository_file:`
+    # @param from_key_hint [String, nil]
+    # @param from_password [String, Array, Symbol, #call, nil] the source
+    #   repository's password (when copying chunker params from one), same
+    #   shape as {#initialize}'s `password:`
+    # @param from_repo [String, Yobi::Repository, nil] the source repository, or its URL
+    #   (given a `Repository`, its own `#url`/`#password` are used automatically)
+    # @param from_repository_file [String, nil]
+    # @param repository_version [String, nil]
+    # @return [Yobi::Initialized]
+    def init(copy_chunker_params: false, from_key_hint: nil, from_password: nil, from_repo: nil,
+      from_repository_file: nil, repository_version: nil)
+      if from_repo.is_a?(Repository)
+        from_password = from_repo.password if from_password.nil?
+        from_repo = from_repo.url
+      end
+
+      argv = build_argv("init") do |a|
+        a.flag(:copy_chunker_params) if copy_chunker_params
+        a.flag(:from_insecure_no_password) if from_password == :insecure_no_password
+        a.flag(:from_key_hint, from_key_hint) unless from_key_hint.nil?
+        a.flag(:from_repo, from_repo) unless from_repo.nil?
+        a.flag(:from_repository_file, from_repository_file) unless from_repository_file.nil?
+        a.flag(:repository_version, repository_version) unless repository_version.nil?
+      end
+      execution = run_restic(argv, extra_env: password_env(from_password, "RESTIC_FROM_PASSWORD"))
+      Initialized.new(JSON.parse(execution[:output].to_s))
+    end
+
+    # Constructs a new {Yobi::Repository} at `url`, already initialized with
+    # chunker parameters copied from this one (`{#init}(copy_chunker_params:
+    # true, from_repo: self)`), so a later {#copy} between the two can
+    # deduplicate. A one-time setup call, not an ongoing sync: nothing keeps
+    # the two repositories in sync afterward, and this doesn't mutate this
+    # `Repository` instance or copy any snapshots itself.
+    #
+    # @param url [String] the new repository's location
+    # @param password [String, Array, Symbol, #call] the new repository's own password
+    # @param backend_credentials [Hash{String => String}, #call] the new repository's own backend credentials
+    # @param restic [Yobi::Restic, String, nil] a `Restic` instance to share, defaults to this repository's own
+    # @param repository_version [String, nil]
+    # @return [Yobi::Repository] the newly initialized mirror
+    def init_mirror(url:, password:, backend_credentials: {}, restic: @restic, repository_version: nil)
+      Repository.new(url: url, password: password, backend_credentials: backend_credentials, restic: restic).tap do |mirror|
+        mirror.init(copy_chunker_params: true, from_repo: self, repository_version: repository_version)
+      end
+    end
+  end
+
+  # The `"initialized"` message from an {Yobi::Repository#init} run.
+  class Initialized < Yobi::FancyHash
+    # @return [String] ID of the created repository
+    def id
+      self["id"]
+    end
+
+    # @return [String] URL of the repository
+    def repository
+      self["repository"]
+    end
+  end
+end

data/lib/yobi/repository/key.rb

@@ -2,7 +2,7 @@
 
 require "json"
 require "time"
-require "delegate"
+require "tempfile"
 
 module Yobi
   class Repository
@@ -10,48 +10,56 @@ module Yobi
     #
     # @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
+    # @param new_password [String, Array, Symbol, #call] the new key's password,
+    #   accepting the same shapes as {#initialize}'s `password:` minus `[:command, ...]`: a
+    #   literal String; a `[:file, "..."]` tuple, resolved natively by Restic
+    #   itself; `:insecure_no_password`; or anything responding to `#call`. A
+    #   literal String or callable is written to a briefly-lived,
+    #   0600-permissioned tempfile, since Restic itself only accepts a new
+    #   password by file or interactive prompt, unlike the repository's own
+    #   `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?
+    def key_add(new_password:, host: nil, user: nil)
+      with_new_password_flag(new_password) do |flag_name, flag_value|
+        argv = build_argv("key", "add") do |a|
+          a.flag(:host, host) unless host.nil?
+          a.flag(:user, user) unless user.nil?
+          a.flag(flag_name, flag_value) unless flag_name.nil?
+        end
+        run_restic(argv)
       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>]
+    # @return [Array<Yobi::Key>]
     def key_list
       execution = run_restic(build_argv("key", "list"))
-      Keys.new(execution[:output])
+      JSON.parse(execution[:output].to_s).map { |raw| Key.new(raw) }
     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.
+    # removes the key currently in use. On success, also updates this
+    # `Repository` instance's own `password:` to `new_password:`, so it
+    # keeps working against this same 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
+    # @param new_password [String, Array, Symbol, #call] see {#key_add}
     # @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?
+    def key_passwd(new_password:, host: nil, user: nil)
+      with_new_password_flag(new_password) do |flag_name, flag_value|
+        argv = build_argv("key", "passwd") do |a|
+          a.flag(:host, host) unless host.nil?
+          a.flag(:user, user) unless user.nil?
+          a.flag(flag_name, flag_value) unless flag_name.nil?
+        end
+        run_restic(argv)
       end
-      run_restic(argv)
+      @password = new_password
       true
     end
     alias_method :change_password, :key_passwd
@@ -67,10 +75,36 @@ module Yobi
       true
     end
     alias_method :remove_key, :key_remove
+
+    private
+
+    def with_new_password_flag(new_password)
+      case new_password
+      in :insecure_no_password
+        yield :new_insecure_no_password, nil
+      in [:file, String => path]
+        yield :new_password_file, path
+      in String => literal
+        with_temp_password_file(literal) { |path| yield :new_password_file, path }
+      in callable if callable.respond_to?(:call)
+        with_temp_password_file(callable.call.to_s) { |path| yield :new_password_file, path }
+      end
+    end
+
+    def with_temp_password_file(password)
+      file = Tempfile.new("yobi-new-password")
+      file.chmod(0o600)
+      file.write(password)
+      file.flush
+      yield file.path
+    ensure
+      file&.close
+      file&.unlink
+    end
   end
 
   # One key (password) associated with the repository, from {Yobi::Repository#key_list}.
-  class Key < SimpleDelegator
+  class Key < Yobi::FancyHash
     # @return [String]
     def id
       self["id"]
@@ -96,31 +130,4 @@ module Yobi
       @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