yobi 0.3.0 → 1.0.0

data/lib/yobi/repository/copy.rb

@@ -2,20 +2,18 @@
 
 module Yobi
   class Repository
-    # `restic copy`: replicates snapshots from another repository into
-    # this one. Already-copied snapshots are skipped automatically.
+    # +restic copy+: replicates snapshots from another repository into this
+    # one. Already-copied snapshots are skipped 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 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]
+    # +from_repo:+ is the source repository's URL, a Yobi::Repository (its
+    # own #url/#password are used automatically), or a +[:file, "..."]+
+    # tuple reading the URL from a file. +from_password:+ takes the same
+    # shape as #initialize's +password:+, and defaults to the source
+    # Repository's own password when +from_repo:+ is one.
+    #
+    # +snapshot_ids:+ names the snapshots to copy; all of them if empty.
+    # +hosts:+, +paths:+, and +tags:+ each accept a single value or an
+    # Array to filter by.
     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?

data/lib/yobi/repository/diff.rb

@@ -2,12 +2,9 @@
 
 module Yobi
   class Repository
-    # `restic diff`: compares two snapshots.
-    #
-    # @param from [String] snapshot ID
-    # @param to [String] snapshot ID
-    # @param metadata [Boolean] also report metadata-only changes (access mode, timestamps, ...)
-    # @return [Yobi::DiffOutcome]
+    # +restic diff+: compares two snapshots, +from:+ and +to:+ (both
+    # snapshot IDs). +metadata: true+ also reports metadata-only changes
+    # (access mode, timestamps, ...). Returns a Yobi::DiffOutcome.
     def diff(from:, to:, metadata: false)
       argv = build_argv("diff", from, to) do |a|
         a.flag(:metadata) if metadata
@@ -18,16 +15,7 @@ module Yobi
     end
   end
 
-  # 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
+  module DiffMessageWrapper # :nodoc:
     def self.call(raw)
       case raw["message_type"]
       when "change" then DiffChange.new(raw)
@@ -37,28 +25,26 @@ module Yobi
     end
   end
 
-  # The outcome of one {Yobi::Repository#diff} call.
+  # The outcome of one Yobi::Repository#diff call.
   class DiffOutcome
-    # @return [Yobi::ResticOutput]
+    # The Yobi::ResticOutput backing this outcome.
     attr_reader :output
 
-    # @private
-    def initialize(execution)
+    def initialize(execution) # :nodoc:
       @output = execution[:output]
     end
 
-    # @return [Yobi::DiffStatistics] Restic's own `"statistics"` fields
+    # The Yobi::DiffStatistics of Restic's own +"statistics"+ fields.
     def statistics
       @statistics ||= output.messages("statistics").first || DiffStatistics.new({})
     end
     alias_method :report, :statistics
 
-    # @return [Enumerable<Yobi::DiffChange>]
+    # Every Yobi::DiffChange from the run.
     def changes
       @changes ||= output.messages("change")
     end
 
-    # @return [void]
     def pretty_print(q)
       q.object_group(self) do
         q.breakable
@@ -67,109 +53,92 @@ module Yobi
     end
   end
 
-  # One `"change"` message from a diff run. `modifier` is Restic's own
-  # concatenation of single-character codes: `"+"` added, `"-"` removed,
-  # `"U"` metadata updated, `"M"` content modified, `"T"` type changed,
-  # `"?"` bitrot detected.
+  # One +"change"+ message from a diff run. #modifier is Restic's own
+  # 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"]
     end
 
-    # @return [String]
     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
 
-  # The `"statistics"` message from a diff run, the final result once the
-  # command finishes. Dispatched to {Yobi::DiffOutcome#statistics}.
+  # 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
 
-    # @return [String, nil]
     def target_snapshot
       self["target_snapshot"]
     end
 
-    # @return [Integer]
     def changed_files
       self["changed_files"] || 0
     end
 
-    # @return [Yobi::DiffStat]
+    # A Yobi::DiffStat of what was added.
     def added
       @added ||= DiffStat.new(self["added"] || {})
     end
 
-    # @return [Yobi::DiffStat]
+    # A Yobi::DiffStat of what was removed.
     def removed
       @removed ||= DiffStat.new(self["removed"] || {})
     end
   end
 
-  # The `"added"`/`"removed"` sub-object of a {Yobi::DiffStatistics} message.
+  # 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

data/lib/yobi/repository/dump.rb

@@ -4,24 +4,23 @@ require "tempfile"
 
 module Yobi
   class Repository
-    # @private
-    ARCHIVE_TYPES = Set.new(%w[tar zip].flat_map { [_1, _1.to_sym] }).freeze
+    ARCHIVE_TYPES = Set.new(%w[tar zip].flat_map { [_1, _1.to_sym] }).freeze # :nodoc:
 
-    # `restic dump`: extracts a file/folder from a snapshot. A single file's
+    # +restic dump+: extracts a file/folder from a snapshot. A single file's
     # raw bytes are written as-is; a folder is written as a tar/zip archive.
-    # Give at most one of `target:` or a block.
+    # Give at most one of +target:+ or a block.
     #
-    # @param snapshot_id [String] also accepts Restic's own `"snapshotID:subfolder"` form directly
-    # @param file [String] path within the snapshot to extract; `"/"` dumps the whole snapshot
-    # @param target [String, nil] write straight to this file path instead of yielding a block
-    # @param archive [String, Symbol, nil] `"tar"` (default) or `"zip"`, when `file` is a folder
-    # @param hosts [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
-    # @param paths [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
-    # @param tags [Array<String>, String] only relevant when `snapshot_id` is `"latest"`
-    # @yieldparam io [IO]
-    # @return [true] if `target:` was given
-    # @return [Yobi::IOHandle] if no block is given
-    # @raise [ArgumentError] if given both `target:` and a block
+    # +snapshot_id:+ is a snapshot ID, or Restic's own
+    # +"snapshotID:subfolder"+ form. +file:+ is the path within the snapshot
+    # to extract; +"/"+ dumps the whole snapshot. +archive:+ is +"tar"+
+    # (default) or +"zip"+, and only applies when +file+ is a folder.
+    #
+    # +hosts:+, +paths:+ and +tags:+ are only relevant when +snapshot_id+
+    # is +"latest"+.
+    #
+    # With +target:+, writes straight to that file path and returns +true+.
+    # Without a block, returns a Yobi::IOHandle. Raises ArgumentError if
+    # given both +target:+ and a block.
     def dump(snapshot_id:, file:, target: nil, archive: nil, hosts: [], paths: [], tags: [], &block)
       raise ArgumentError, "give at most one of target: or a block, not both" if target && block
 

data/lib/yobi/repository/find.rb

@@ -1,29 +1,23 @@
 # frozen_string_literal: true
 
-require "json"
 require "time"
 
 module Yobi
   class Repository
-    # `restic find`: searches for files/directories across snapshots by
+    # +restic find+: searches for files/directories across snapshots by
     # name pattern.
     #
-    # @param patterns [Array<String>, String] glob patterns to match
-    # @param blob [Boolean] match blob IDs instead of file names
-    # @param pack [Boolean] match pack IDs instead of file names
-    # @param tree [Boolean] match tree IDs instead of file names
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param human_readable [Boolean] format sizes for humans
-    # @param ignore_case [Boolean] case-insensitive matching
-    # @param long [Boolean] include long listing format
-    # @param newest [String, nil] only consider snapshots at or before this time
-    # @param oldest [String, nil] only consider snapshots at or after this time
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param reverse [Boolean] reverse sort order
-    # @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 [Array<Yobi::MatchesPerSnapshot>]
+    # +patterns:+ accepts a single glob or an Array. +blob:+, +pack:+ and
+    # +tree:+ match blob/pack/tree IDs instead of file names.
+    #
+    # +hosts:+, +paths:+, +snapshot_ids:+, and +tags:+ each accept a single
+    # value or an Array to filter by. +newest:+ / +oldest:+ restrict the
+    # snapshot window.
+    #
+    # +ignore_case:+, +long:+, +human_readable:+, +reverse:+ and
+    # +show_pack_id:+ toggle formatting/matching options.
+    #
+    # Returns an Array of 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: [])
@@ -45,92 +39,77 @@ module Yobi
         a.end_of_options.append(patterns)
       end
       execution = run_restic(argv)
-      JSON.parse(execution[:output].to_s).map { |raw| MatchesPerSnapshot.new(raw) }
+      parse_json_output(execution).map { |raw| MatchesPerSnapshot.new(raw) }
     end
   end
 
-  # One matched file/directory from a {Yobi::Repository#find} call.
+  # One matched file/directory from a Yobi::Repository#find call.
   class FindMatch < Yobi::FancyHash
-    # @return [String]
     def path
       self["path"]
     end
 
-    # @return [String]
     def type
       self["type"]
     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 [String]
     def user
       self["user"]
     end
 
-    # @return [String]
     def group
       self["group"]
     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
 
-  # One snapshot's worth of matches from a {Yobi::Repository#find} call.
+  # One snapshot's worth of matches from a Yobi::Repository#find call.
   class MatchesPerSnapshot < Yobi::FancyHash
-    # Restic's own `find --json` output only gives the snapshot's ID here,
+    # 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}
+    # "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
       self["hits"]
     end
 
-    # @return [Array<Yobi::FindMatch>]
+    # An Array of Yobi::FindMatch objects for this snapshot.
     def matches
       @matches ||= (self["matches"] || []).map { |raw| Yobi::FindMatch.new(raw) }
     end

data/lib/yobi/repository/forget.rb

@@ -1,39 +1,31 @@
 # frozen_string_literal: true
 
-require "json"
-
 module Yobi
   class Repository
-    # `restic forget`: applies a retention policy, removing snapshots
-    # that don't match any `keep_*` rule.
+    # +restic forget+: applies a retention policy, removing snapshots that
+    # don't match any +keep_*+ rule.
+    #
+    # +keep_last:+ always keeps that many of the most recent snapshots.
+    # +keep_hourly:+, +keep_daily:+, +keep_weekly:+, +keep_monthly:+, and
+    # +keep_yearly:+ each keep that many of the most recent per period.
+    # +keep_within:+ keeps all snapshots within a given duration (e.g.
+    # +"30d"+); the +keep_within_hourly:+ ... +keep_within_yearly:+ variants
+    # apply the same duration within their respective periods.
+    # +keep_tags:+ always keeps snapshots carrying any of the listed tags.
+    #
+    # +hosts:+, +tags:+, and +paths:+ each accept a single value or an
+    # Array to filter by.
+    #
+    # +compact:+ compacts the printed policy summary. +group_by:+ (e.g.
+    # +"host,paths"+) picks the grouping used to apply the policy.
+    # +dry_run:+ reports what would happen without doing it.
+    # +unsafe_allow_remove_all:+ allows removing every snapshot.
+    #
+    # +prune: true+ also reclaims disk space. +max_unused:+, +max_repack_size:+,
+    # +repack_cacheable_only:+, +repack_uncompressed:+ and
+    # +repack_smaller_than:+ are passed through to that implied prune.
     #
-    # @param keep_last [Integer, nil] always keep this many of the most recent snapshots
-    # @param keep_hourly [Integer, nil]
-    # @param keep_daily [Integer, nil]
-    # @param keep_weekly [Integer, nil]
-    # @param keep_monthly [Integer, nil]
-    # @param keep_yearly [Integer, nil]
-    # @param keep_within [String, nil] keep all snapshots within this duration, e.g. `"30d"`
-    # @param keep_within_hourly [String, nil]
-    # @param keep_within_daily [String, nil]
-    # @param keep_within_weekly [String, nil]
-    # @param keep_within_monthly [String, nil]
-    # @param keep_within_yearly [String, nil]
-    # @param keep_tags [Array<String>, String] always keep snapshots carrying any of these tags
-    # @param hosts [Array<String>, String] filter by hostname(s)
-    # @param tags [Array<String>, String] filter by tag(s)
-    # @param paths [Array<String>, String] filter by originally backed-up path(s)
-    # @param compact [Boolean] compact the printed policy summary
-    # @param group_by [String, nil] grouping used to apply the policy, e.g. `"host,paths"`
-    # @param dry_run [Boolean] report what would happen without doing it
-    # @param prune [Boolean] also reclaim disk space (equivalent to `restic forget --prune`)
-    # @param unsafe_allow_remove_all [Boolean] allow removing every snapshot
-    # @param max_unused [String, nil] passed through to the implied prune, e.g. `"10%"`
-    # @param max_repack_size [String, nil] passed through to the implied prune
-    # @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 [Array<Yobi::ForgetGroup>]
+    # Returns an Array of 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: [],
@@ -69,52 +61,54 @@ module Yobi
         a.flag(:repack_smaller_than, repack_smaller_than) unless repack_smaller_than.nil?
       end
       execution = run_restic(argv)
-      JSON.parse(execution[:output].to_s).map { |raw| ForgetGroup.new(raw) }
+      # Permissive because `restic forget` can surround its JSON summary
+      # with non-JSON lines (prune chatter on <= 0.18.1, or a
+      # "Remove(...) failed" line on partial-removal). See
+      # #parse_json_output_permissively for the full rundown.
+      parse_json_output_permissively(execution).map { |raw| ForgetGroup.new(raw) }
     end
   end
 
   # One grouping Restic's forget policy was evaluated against (by default,
   # grouped by host+paths).
   class ForgetGroup < Yobi::FancyHash
-    # @return [String]
     def host
       self["host"]
     end
 
-    # @return [Array<String>]
     def tags
       @tags ||= self["tags"] || []
     end
 
-    # @return [Array<String>]
     def paths
       self["paths"]
     end
 
-    # @return [Array<Yobi::Snapshot>]
+    # Yobi::Snapshot instances kept by the policy.
     def keep
       @keep ||= (self["keep"] || []).map { |entry| Yobi::Snapshot.new(entry) }
     end
 
-    # @return [Array<Yobi::Snapshot>]
+    # Yobi::Snapshot instances removed by the policy.
     def remove
       @remove ||= (self["remove"] || []).map { |entry| Yobi::Snapshot.new(entry) }
     end
 
-    # @return [Array<Yobi::KeepReason>] one per kept snapshot, explaining which policy rule(s) kept it
+    # One Yobi::KeepReason per kept snapshot, explaining which policy
+    # rule(s) kept it.
     def reasons
       @reasons ||= (self["reasons"] || []).map { |entry| Yobi::KeepReason.new(entry) }
     end
   end
 
-  # Why one snapshot survived a {Yobi::Repository#forget} run.
+  # Why one snapshot survived a Yobi::Repository#forget run.
   class KeepReason < Yobi::FancyHash
-    # @return [Yobi::Snapshot]
+    # The Yobi::Snapshot that was kept.
     def snapshot
       @snapshot ||= Yobi::Snapshot.new(self["snapshot"])
     end
 
-    # @return [Array<String>] Restic's own human-readable rule-match strings, e.g. `"last snapshot"`
+    # Restic's own human-readable rule-match strings, e.g. +"last snapshot"+.
     def matches
       @matches ||= self["matches"] || []
     end

data/lib/yobi/repository/init.rb

@@ -1,21 +1,18 @@
 # frozen_string_literal: true
 
-require "json"
-
 module Yobi
   class Repository
-    # `restic init`: creates the repository at {#url}.
+    # +restic init+: creates the repository at #url.
+    #
+    # +copy_chunker_params: true+ copies chunker parameters from +from_repo:+
+    # (so a later #copy between the two can deduplicate). +from_repo:+ is
+    # the source repository's URL, a Yobi::Repository (its own #url/#password
+    # are used automatically), or a +[:file, "..."]+ tuple reading the URL
+    # from a file. +from_password:+ takes the same shape as #initialize's
+    # +password:+, and defaults to the source Repository's own password
+    # when +from_repo:+ is one.
     #
-    # @param copy_chunker_params [Boolean] copy chunker parameters from `from_repo:`
-    # @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, Array, nil] 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 repository_version [String, nil]
-    # @return [Yobi::Initialized]
+    # Returns a Yobi::Initialized.
     def init(copy_chunker_params: false, from_key_hint: nil, from_password: nil, from_repo: nil, repository_version: nil)
       from_repo_flag, from_repo_value = resolved_from_repo_flag(from_repo) unless from_repo.nil?
 
@@ -33,22 +30,18 @@ module Yobi
       end
 
       execution = run_restic(argv, extra_env: password_env(from_password, "RESTIC_FROM_PASSWORD"))
-      Initialized.new(JSON.parse(execution[:output].to_s))
+      Initialized.new(parse_json_output(execution))
     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
+    # 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.
+    # 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
+    # +url:+, +password:+, and +backend_credentials:+ take the same shapes
+    # as #initialize. +restic:+ defaults to this repository's own.
     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)
@@ -56,14 +49,14 @@ module Yobi
     end
   end
 
-  # The `"initialized"` message from an {Yobi::Repository#init} run.
+  # The +"initialized"+ message from a Yobi::Repository#init run.
   class Initialized < Yobi::FancyHash
-    # @return [String] ID of the created repository
+    # ID of the created repository.
     def id
       self["id"]
     end
 
-    # @return [String] URL of the repository
+    # URL of the repository.
     def repository
       self["repository"]
     end