yobi 0.1.0 → 0.3.0

data/lib/yobi/fancy_hash.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Yobi
+  # Base class for every wrapper around one raw Restic JSON object.
+  class FancyHash < Hash
+    # @private
+    def initialize(raw)
+      super()
+      replace(raw)
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{super}>"
+    end
+
+    # @return [void]
+    def pretty_print(q)
+      q.object_group(self) do
+        each do |key, value|
+          next if key == "message_type"
+
+          value = public_send(key) if self.class.method_defined?(key, false)
+          q.breakable
+          q.text "#{key}="
+          q.pp(value)
+        end
+      end
+    end
+  end
+end

data/lib/yobi/io_handle.rb

@@ -22,14 +22,11 @@ module Yobi
     # @return [Integer] the Restic process's pid
     attr_reader :pid
 
-    # @param io [IO]
-    # @param pid [Integer]
-    # @param output_file [File]
-    # @param argv [Array<String>]
-    def initialize(io, pid:, output_file:, argv:)
+    # @private
+    def initialize(io, pid:, output:, argv:)
       @io = io
       @pid = pid
-      @output_file = output_file
+      @output = output
       @argv = argv
       @closed = false
     end
@@ -39,6 +36,11 @@ module Yobi
       @closed
     end
 
+    # @return [String]
+    def inspect
+      "#<#{self.class} pid=#{pid} closed=#{closed?}>"
+    end
+
     # Reaps the Restic process and raises based on its exit code. Safe to
     # call more than once.
     #
@@ -49,7 +51,7 @@ module Yobi
       @closed = true
       @io.close unless @io.closed?
       _, status = Process.wait2(@pid)
-      Restic.dispatch(exit_code: status.exitstatus, output: Yobi::ResticOutput.new(@output_file), argv: @argv)
+      Restic.dispatch(exit_code: status.exitstatus, output: @output, argv: @argv)
     end
 
     # Yields binary-safe chunks of {#io} until EOF, then calls {#close}.

data/lib/yobi/{mount.rb → mount_handle.rb}

@@ -5,20 +5,16 @@ module Yobi
   # Restic has reported itself ready. The mounted filesystem itself is
   # browsed with ordinary file I/O at {#mountpoint}; this object only
   # manages the Restic process's lifetime.
-  class Mount
+  class MountHandle
     # @return [String] the path the repository is mounted at
     attr_reader :mountpoint
 
-    # @param wait_thr [Process::Waiter] as returned by `Open3.popen2e`
-    # @param mountpoint [String]
-    # @param output [IO]
-    # @param output_file [File]
-    # @param argv [Array<String>]
-    def initialize(wait_thr:, mountpoint:, output:, output_file:, argv:)
+    # @private
+    def initialize(wait_thr:, mountpoint:, pipe:, output:, argv:)
       @wait_thr = wait_thr
       @mountpoint = mountpoint
+      @pipe = pipe
       @output = output
-      @output_file = output_file
       @argv = argv
       @stopped = false
     end
@@ -33,6 +29,11 @@ module Yobi
       @stopped
     end
 
+    # @return [String]
+    def inspect
+      "#<#{self.class} pid=#{pid} mountpoint=#{mountpoint.inspect} stopped=#{stopped?}>"
+    end
+
     # Sends the Restic process SIGINT, waits for it to unmount and exit,
     # then raises based on its exit code. Safe to call more than once, and
     # safe to call after the mount has already been stopped externally
@@ -52,13 +53,13 @@ module Yobi
 
       drain_remaining_output
       status = @wait_thr.value
-      Restic.dispatch(exit_code: status.exitstatus, output: Yobi::ResticOutput.new(@output_file), argv: @argv)
+      Restic.dispatch(exit_code: status.exitstatus, output: @output, argv: @argv)
     end
 
     private
 
     def drain_remaining_output
-      @output.each_line { |line| @output_file.write(line) }
+      @pipe.each_line { |line| @output.file.write(line) }
     rescue IOError, Errno::EBADF
       nil
     end

data/lib/yobi/repository/backup.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-require "json"
 require "time"
-require "delegate"
 require "shellwords"
 
 module Yobi
@@ -40,7 +38,7 @@ module Yobi
     # @param time [String, nil] timestamp to record instead of now
     # @param verbose [Boolean] stream a {Yobi::BackupVerboseStatus} per file to the block
     # @param with_atime [Boolean] also store files' access times
-    # @yieldparam message [Yobi::BackupStatus, Yobi::BackupError, Yobi::BackupVerboseStatus]
+    # @yieldparam message [Yobi::BackupStatus, Yobi::BackupError, Yobi::BackupVerboseStatus, Yobi::BackupSummary]
     # @return [Yobi::BackupOutcome]
     def backup(source:, excludes: [], exclude_files: [], exclude_if_present: [], exclude_larger_than: nil,
       files_from: [], files_from_raw: [], files_from_verbatim: [], iexcludes: [], iexclude_files: [],
@@ -85,109 +83,126 @@ module Yobi
           a.flag(:stdin_from_command)
           a.flag(:stdin_filename, filename)
           a.end_of_options.append(tokenize(command))
+        else
+          raise ArgumentError, "invalid source shape"
         end
       end
 
-      execution = if block
-        run_restic(argv) { |raw| dispatch_backup_message(raw, &block) }
-      else
-        run_restic(argv)
-      end
-      BackupOutcome.new(execution[:exit_code], execution[:output])
+      output = Yobi::ResticOutput.new(transform: Yobi::BackupMessageWrapper)
+      execution = run_restic(argv, output: output, &block)
+      BackupOutcome.new(execution)
     end
 
     private
 
-    def dispatch_backup_message(raw)
-      case raw["message_type"]
-      when "status"
-        yield Yobi::BackupStatus.new(raw)
-      when "error"
-        yield Yobi::BackupError.new(raw)
-      when "verbose_status"
-        yield Yobi::BackupVerboseStatus.new(raw)
-      end
-    end
-
     def tokenize(command)
       case command
       in String => value
         Shellwords.split(value)
       in Array => values
         values.map(&:to_s)
+      else
+        raise ArgumentError, "invalid stdin_from_command command shape"
+      end
+    end
+  end
+
+  # Classifies a raw backup message Hash by its own message_type, wrapping
+  # it in the matching typed class. Used both by {Yobi::Repository#backup}
+  # (as the {Yobi::ResticOutput} `transform:` for a live streaming run) and
+  # by {Yobi::BackupOutcome}'s own post-hoc accessors.
+  #
+  # @private
+  module BackupMessageWrapper
+    # @param raw [Hash]
+    # @return [Yobi::BackupStatus, Yobi::BackupError, Yobi::BackupVerboseStatus, Yobi::BackupSummary, 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 "status" then BackupStatus.new(raw)
+      when "error" then BackupError.new(raw)
+      when "verbose_status" then BackupVerboseStatus.new(raw)
+      when "summary" then BackupSummary.new(raw)
+      else raw
       end
     end
   end
 
   # The outcome of one {Yobi::Repository#backup} call.
-  class BackupOutcome < Struct.new(:exit_code, :output)
-    # Matches Restic's own log line format for stderr relayed from a
-    # `source: [:stdin_from_command, ...]` command's own subprocess.
+  class BackupOutcome
+    # @private
     COMMAND_OUTPUT_LINE_PATTERN = /\Asubprocess [^:]+: (.*)/
 
-    # @return [Boolean]
-    def success?
-      exit_code.zero?
-    end
+    # @return [Yobi::ResticOutput]
+    attr_reader :output
 
-    # @return [Boolean] true if the backup completed with some files skipped
-    def partial?
-      exit_code == 3
+    # @private
+    def initialize(execution)
+      @output = execution[:output]
     end
 
     # @return [Enumerable<Yobi::BackupError>]
     def errors
-      @errors ||= BackupErrors.new(output)
+      @errors ||= output.messages("error")
+    end
+
+    # Every message from the run, in file order, each wrapped in its own
+    # {Yobi::BackupStatus}/{Yobi::BackupError}/{Yobi::BackupVerboseStatus}/{Yobi::BackupSummary}.
+    #
+    # @return [Enumerable<Yobi::BackupStatus, Yobi::BackupError, Yobi::BackupVerboseStatus, Yobi::BackupSummary>]
+    def messages
+      @messages ||= output.messages
     end
 
     # The `source: [:stdin_from_command, ...]` subprocess's own stderr, if any, de-prefixed.
     #
-    # @return [Array<String>]
+    # @yieldparam line [String]
+    # @return [Enumerator] if no block is given
     def command_output
-      @command_output ||= output.each_line.filter_map do |line|
+      return enum_for(:command_output) unless block_given?
+
+      output.stderr_lines.each do |line|
         match = COMMAND_OUTPUT_LINE_PATTERN.match(line)
-        match[1] if match
+        yield match[1] if match
       end
     end
 
-    # @return [Hash] Restic's own `"summary"` fields, with `"backup_start"`/`"backup_end"` parsed into `Time`
-    def report
-      @report ||= begin
-        hash = summary_hash
-        hash.merge(
-          "backup_start" => (Time.parse(hash["backup_start"]) if hash["backup_start"]),
-          "backup_end" => (Time.parse(hash["backup_end"]) if hash["backup_end"])
-        )
-      end
+    # @return [Yobi::BackupSummary] Restic's own `"summary"` fields
+    def summary
+      @summary ||= output.messages("summary").first || BackupSummary.new({})
     end
-
-    private
-
-    def summary_hash
-      line = output.last_line
-      hash = line && JSON.parse(line)
-      if hash && hash["message_type"] == "summary"
-        hash
-      else
-        find_summary || {}
+    alias_method :report, :summary
+
+    # @return [void]
+    def pretty_print(q)
+      q.object_group(self) do
+        q.breakable
+        q.text("(has errors)") if errors.any?
+        q.breakable
+        q.pp summary
       end
     end
+  end
 
-    def find_summary
-      output.each_line do |line|
-        next if line.strip.empty?
-
-        hash = JSON.parse(line)
-        return hash if hash["message_type"] == "summary"
-      end
+  # The `"summary"` message from a backup run, the final result once the
+  # command finishes. Dispatched to {Yobi::Repository#backup}'s block, and
+  # also what {Yobi::BackupOutcome#summary} returns.
+  # https://restic.readthedocs.io/en/stable/075_scripting.html#summary
+  class BackupSummary < Yobi::FancyHash
+    # @return [Time, nil]
+    def backup_start
+      @backup_start ||= Time.parse(self["backup_start"]) if self["backup_start"]
+    end
 
-      nil
+    # @return [Time, nil]
+    def backup_end
+      @backup_end ||= Time.parse(self["backup_end"]) if self["backup_end"]
     end
   end
 
   # One `"status"` message from a live backup run.
   # https://restic.readthedocs.io/en/stable/075_scripting.html#status
-  class BackupStatus < SimpleDelegator
+  class BackupStatus < Yobi::FancyHash
     # @return [Float, nil]
     def percent_done
       self["percent_done"]
@@ -226,7 +241,7 @@ module Yobi
 
   # One `"error"` message from a backup run.
   # https://restic.readthedocs.io/en/stable/075_scripting.html#error
-  class BackupError < SimpleDelegator
+  class BackupError < Yobi::FancyHash
     # @return [String, nil]
     def message
       dig("error", "message")
@@ -243,30 +258,9 @@ module Yobi
     end
   end
 
-  # Enumerable over every {Yobi::BackupError} in a run.
-  class BackupErrors
-    include Enumerable
-
-    # @param output [Yobi::ResticOutput]
-    def initialize(output)
-      @output = output
-    end
-
-    # @yieldparam error [Yobi::BackupError]
-    # @return [Enumerator] if no block is given
-    def each
-      return enum_for(:each) unless block_given?
-
-      @output.index["error"].each do |offset|
-        line = @output.read_line_at(offset)
-        yield BackupError.new(JSON.parse(line))
-      end
-    end
-  end
-
   # One `"verbose_status"` message from a backup run, one per file. Only
   # emitted when `verbose: true` is passed to {Yobi::Repository#backup}.
-  class BackupVerboseStatus < SimpleDelegator
+  class BackupVerboseStatus < Yobi::FancyHash
     # @return [String]
     def action
       self["action"]

data/lib/yobi/repository/cat.rb

@@ -4,6 +4,16 @@ require "json"
 
 module Yobi
   class Repository
+    # `restic cat config`: the repository's own config document.
+    #
+    # @return [Hash]
+    # @raise [Yobi::RepositoryNotFound, Yobi::AuthenticationFailed]
+    def cat_config
+      execution = run_restic(build_argv("cat", "config"))
+      JSON.parse(execution[:output].to_s)
+    end
+    alias_method :config, :cat_config
+
     # `restic cat snapshot ID`: one snapshot's own raw stored record.
     #
     # @param id [String, Yobi::Snapshot]

data/lib/yobi/repository/check.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
-require "delegate"
-
 module Yobi
   class Repository
     # `restic check`: tests the repository for errors.
@@ -23,74 +20,93 @@ module Yobi
         a.repeat_flag(:tag, tags)
         a.flag(:with_cache) if with_cache
       end
-      execution = run_restic(argv)
-      CheckOutcome.new(execution[:exit_code], execution[:output])
+      output = Yobi::ResticOutput.new(transform: Yobi::CheckMessageWrapper)
+      execution = run_restic(argv, output: output)
+      CheckOutcome.new(execution)
     end
   end
 
-  # The outcome of one {Yobi::Repository#check} call.
-  class CheckOutcome < Struct.new(:exit_code, :output)
-    # @return [Hash] Restic's own `"summary"` fields (`"num_errors"`, `"broken_packs"`, ...)
-    def report
-      @report ||= summary_hash
+  # Classifies a raw check message Hash by its own message_type, wrapping
+  # it in the matching typed class. Used both as the {Yobi::ResticOutput}
+  # `transform:` for {Yobi::Repository#check} and by {Yobi::CheckOutcome}'s
+  # own post-hoc accessors.
+  #
+  # @private
+  module CheckMessageWrapper
+    # @param raw [Hash]
+    # @return [Yobi::CheckError, Yobi::CheckSummary, 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 "error" then CheckError.new(raw)
+      when "summary" then CheckSummary.new(raw)
+      else raw
+      end
     end
+  end
 
-    # @return [Enumerable<Yobi::CheckError>]
-    def errors
-      @errors ||= CheckErrors.new(output)
-    end
+  # The outcome of one {Yobi::Repository#check} call.
+  class CheckOutcome
+    # @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"] == "summary"
-        hash
-      else
-        find_summary || {}
-      end
+    # @return [Yobi::CheckSummary] Restic's own `"summary"` fields
+    def summary
+      @summary ||= output.messages("summary").first || CheckSummary.new({})
     end
+    alias_method :report, :summary
 
-    def find_summary
-      output.each_line do |line|
-        next if line.strip.empty?
+    # @return [Enumerable<Yobi::CheckError>]
+    def errors
+      @errors ||= output.messages("error")
+    end
 
-        hash = JSON.parse(line)
-        return hash if hash["message_type"] == "summary"
+    # @return [void]
+    def pretty_print(q)
+      q.object_group(self) do
+        q.breakable
+        q.text("(has errors)") if errors.any?
+        q.breakable
+        q.pp summary
       end
-
-      nil
     end
   end
 
   # One `"error"` message from a check run.
   # https://restic.readthedocs.io/en/stable/075_scripting.html#error
-  class CheckError < SimpleDelegator
+  class CheckError < Yobi::FancyHash
     # @return [String]
     def message
       self["message"]
     end
   end
 
-  # Enumerable over every {Yobi::CheckError} in a run.
-  class CheckErrors
-    include Enumerable
+  # The `"summary"` message from a check run, the final result once the
+  # command finishes. Dispatched to {Yobi::CheckOutcome#summary}.
+  class CheckSummary < Yobi::FancyHash
+    # @return [Integer]
+    def num_errors
+      self["num_errors"] || 0
+    end
 
-    # @param output [Yobi::ResticOutput]
-    def initialize(output)
-      @output = output
+    # @return [Array<String>] pack IDs needing `repair_packs`/`repair_snapshots`
+    def broken_packs
+      self["broken_packs"] || []
     end
 
-    # @yieldparam error [Yobi::CheckError]
-    # @return [Enumerator] if no block is given
-    def each
-      return enum_for(:each) unless block_given?
+    # @return [Boolean] whether to run {Yobi::Repository#repair_index}
+    def suggest_repair_index?
+      self["suggest_repair_index"]
+    end
 
-      @output.index["error"].each do |offset|
-        line = @output.read_line_at(offset)
-        yield CheckError.new(JSON.parse(line))
-      end
+    # @return [Boolean] whether to run {Yobi::Repository#prune}
+    def suggest_prune?
+      self["suggest_prune"]
     end
   end
 end

data/lib/yobi/repository/copy.rb

@@ -5,33 +5,31 @@ module Yobi
     # `restic copy`: replicates snapshots from another repository into
     # this one. Already-copied snapshots are skipped automatically.
     #
-    # @param from_repo [String, Yobi::Repository] the source repository, or its URL
-    #   (given a `Repository`, its own `#url`/`#password` are used automatically)
+    # @param from_repo [String, Yobi::Repository, Array] the source repository's
+    #   URL; a `Repository` instance (its own `#url`/`#password` are used
+    #   automatically); or a `[:file, "..."]` tuple reading the URL from a file
     # @param from_password [String, Array, Symbol, #call, nil] the source
     #   repository's password, same shape as {#initialize}'s `password:`
     # @param snapshot_ids [Array<String>, String] snapshots to copy; all of them if empty
     # @param from_key_hint [String, nil]
-    # @param from_repository_file [String, nil] read the source repository's URL from a file
     # @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 copy(from_repo:, from_password: nil, snapshot_ids: [], from_key_hint: nil,
-      from_repository_file: nil, hosts: [], paths: [], tags: [])
-      if from_repo.is_a?(Repository)
-        from_password = from_repo.password if from_password.nil?
-        from_repo = from_repo.url
-      end
+    def copy(from_repo:, from_password: nil, snapshot_ids: [], from_key_hint: nil, hosts: [], paths: [], tags: [])
+      from_repo_flag, from_repo_value = resolved_from_repo_flag(from_repo)
+      from_password = from_repo_password(from_repo) if from_password.nil?
+      validate_from_password_shape!(from_password)
 
       argv = build_argv("copy", snapshot_ids) do |a|
-        a.flag(:from_repo, from_repo)
+        a.flag(from_repo_flag, from_repo_value)
         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_repository_file, from_repository_file) unless from_repository_file.nil?
         a.repeat_flag(:host, hosts)
         a.repeat_flag(:path, paths)
         a.repeat_flag(:tag, tags)
       end
+
       run_restic(argv, extra_env: password_env(from_password, "RESTIC_FROM_PASSWORD"))
       true
     end