yobi 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edd02fb1bbb985e22d5e32e8558b37f469809e9b5cdc079c6b4885e5ada5a775
-  data.tar.gz: 4d6a90b324596e6fc375a1338fdba1c70d84a6bf9504b15513614c87458bd7c0
+  metadata.gz: 56739c72c75a1d5c856bbd619b781dd3986cf1b3c1447d4864edd19b9543d8d9
+  data.tar.gz: a5321fe628cab2f74011ce257a4eee380ed1fcb804456f8afa5482ac84c96b6f
 SHA512:
-  metadata.gz: 9c11e446c74d42a68b7a34c61b4952451f0929d56114a6439ec6462f854019ea40d7844dd730371026a679f744a464600c997ce76b884de538a38ee879348efc
-  data.tar.gz: e3245e59a13c6b9f8712824406f0844106e1495a543ff68cf2ac11210835ef480109755acf2019ca5b10708d46436bc1e58f7e9e122f450ce3dd4f40395695fb
+  metadata.gz: 9b2253d54dd64aa88658c7ddd53734a2edbcaf2623bb98258bc14d71d0d4a82bb3bcb447e6434bfb28505d2bfcd329988841d8f491ce7c3d1b13865b4a50b0f7
+  data.tar.gz: 7cd169b509d216a99b258180381c9caa9cd92837b822467781b01c3788cc37af4252d825b4de50a511b71a521a4e8d9bff8317a7f9c0da11b82847c6b65c2b8c

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.3.1] - 2026-08-10
+
+### Fixed
+
+- `#forget`/`#init`/`#stats`/`#find`/`#snapshots`/`#key_list`/the `#cat_*` methods no longer raise a bare, uninformative `JSON::ParserError` when Restic exits with code 3 ("succeeded with warnings" - e.g. `#forget` failing to remove one or more snapshots) and mixes a plain-text diagnostic line into otherwise-JSON output. Raises `Yobi::ResticCommandFailed` instead, with the diagnostic still available in the error message.
+
+## [0.3.0] - 2026-08-03
+
+### Changed
+
+- **Breaking:** `#init`/`#copy`'s `from_repository_file:` kwarg removed - `from_repo:` is now polymorphic, additionally accepting a `[:file, "..."]` tuple to read the source repository's URL from a file, alongside the existing plain URL String/`Repository` instance shapes.
+- Invalid shapes for `password:`, `backend_credentials:`, `restic:`, `source:`/a `stdin_from_command` command, `new_password:`, `from_repo:`, and `from_password:` now raise `ArgumentError` with a message like `"invalid password shape"`, instead of a raw `NoMatchingPatternError`/`NoMatchingPatternKeyError`.
+- `Repository#initialize`'s `password:`/`backend_credentials:` shapes are now validated eagerly at construction (and `from_password:`/`from_repo:` eagerly in `#init`/`#copy`), instead of lazily on the first `#env`/`#inspect`/argv-building call.
+
 ## [0.2.0] - 2026-08-03
 
 ### Added

data/README.md

@@ -521,7 +521,7 @@ A shortcut for setting up a `#copy` destination: constructs a new `Repository` a
 mirror_repo.copy(from_repo: primary_repo, tags: "nightly")
 ```
 
-Replicates snapshots from another repository into this one. `from_repo:` accepts a plain URL String or a `Repository` instance. Given the latter, its own `#url`/`#password` are used automatically unless `from_password:` is given explicitly. Already-copied snapshots are skipped automatically on a repeat run. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#copy-instance_method) for the full list of options. Returns `true`.
+Replicates snapshots from another repository into this one. `from_repo:` accepts a plain URL String, a `[:file, "..."]` tuple reading the URL from a file, or a `Repository` instance. Given the latter, its own `#url`/`#password` are used automatically unless `from_password:` is given explicitly. Already-copied snapshots are skipped automatically on a repeat run. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#copy-instance_method) for the full list of options. Returns `true`.
 
 ## Mounting
 

data/lib/yobi/repository/backup.rb

@@ -83,6 +83,8 @@ 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
 
@@ -99,6 +101,8 @@ module Yobi
         Shellwords.split(value)
       in Array => values
         values.map(&:to_s)
+      else
+        raise ArgumentError, "invalid stdin_from_command command shape"
       end
     end
   end

data/lib/yobi/repository/cat.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
-
 module Yobi
   class Repository
     # `restic cat config`: the repository's own config document.
@@ -10,7 +8,7 @@ module Yobi
     # @raise [Yobi::RepositoryNotFound, Yobi::AuthenticationFailed]
     def cat_config
       execution = run_restic(build_argv("cat", "config"))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
     alias_method :config, :cat_config
 
@@ -21,7 +19,7 @@ module Yobi
     def cat_snapshot(id)
       id = id.id if id.is_a?(Yobi::Snapshot)
       execution = run_restic(build_argv("cat", "snapshot", id))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
 
     # `restic cat index ID`: one index file's own raw contents. IDs come
@@ -31,7 +29,7 @@ module Yobi
     # @return [Hash]
     def cat_index(id)
       execution = run_restic(build_argv("cat", "index", id))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
 
     # `restic cat key ID`: one key's own raw stored record.
@@ -41,7 +39,7 @@ module Yobi
     def cat_key(id)
       id = id.id if id.is_a?(Yobi::Key)
       execution = run_restic(build_argv("cat", "key", id))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
 
     # `restic cat tree snapshot:subfolder`: the raw tree object at a
@@ -58,7 +56,7 @@ module Yobi
         "#{snapshot_id}:#{subfolder}"
       end
       execution = run_restic(build_argv("cat", "tree", target))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     end
 
     # `restic cat pack ID`: one pack file's raw, still-encrypted bytes.
@@ -91,7 +89,7 @@ module Yobi
     # @return [Hash]
     def cat_masterkey_and_game_over_if_this_leaks
       execution = run_restic(build_argv("cat", "masterkey"))
-      JSON.parse(execution[:output].to_s)
+      parse_json_output(execution)
     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

data/lib/yobi/repository/find.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
 require "time"
 
 module Yobi
@@ -45,7 +44,7 @@ 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
 

data/lib/yobi/repository/forget.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
-
 module Yobi
   class Repository
     # `restic forget`: applies a retention policy, removing snapshots
@@ -69,7 +67,7 @@ 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) }
+      parse_json_output(execution).map { |raw| ForgetGroup.new(raw) }
     end
   end
 

data/lib/yobi/repository/init.rb

@@ -1,38 +1,37 @@
 # 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 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, nil] the source repository, or its URL
-    #   (given a `Repository`, its own `#url`/`#password` are used automatically)
-    # @param from_repository_file [String, nil]
+    # @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]
-    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
+    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?
+
+      if from_repo_value
+        from_password = from_repo_password(from_repo) if from_password.nil?
+        validate_from_password_shape!(from_password)
       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(from_repo_flag, from_repo_value) if from_repo_flag
         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))
+      Initialized.new(parse_json_output(execution))
     end
 
     # Constructs a new {Yobi::Repository} at `url`, already initialized with

data/lib/yobi/repository/key.rb

@@ -24,7 +24,7 @@ module Yobi
         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?
+          a.flag(flag_name, flag_value)
         end
         run_restic(argv)
       end
@@ -37,7 +37,7 @@ module Yobi
     # @return [Array<Yobi::Key>]
     def key_list
       execution = run_restic(build_argv("key", "list"))
-      JSON.parse(execution[:output].to_s).map { |raw| Key.new(raw) }
+      parse_json_output(execution).map { |raw| Key.new(raw) }
     end
     alias_method :keys, :key_list
 
@@ -55,7 +55,7 @@ module Yobi
         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?
+          a.flag(flag_name, flag_value)
         end
         run_restic(argv)
       end
@@ -88,6 +88,8 @@ module Yobi
         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 }
+      else
+        raise ArgumentError, "invalid new_password shape"
       end
     end
 

data/lib/yobi/repository/mount.rb

@@ -90,7 +90,7 @@ module Yobi
         self.class.dispatch(exit_code: status.exitstatus, output: output, argv: argv)
       end
     rescue Errno::ENOENT
-      output&.file&.close
+      output.file.close
       raise Yobi::ResticNotFound.new(restic_path: restic_path, argv: argv)
     end
 

data/lib/yobi/repository/snapshots.rb

@@ -23,7 +23,7 @@ module Yobi
         a.flag(:latest, latest) unless latest.nil?
       end
       execution = run_restic(argv)
-      JSON.parse(execution[:output].to_s).map { |raw| Snapshot.new(raw) }
+      parse_json_output(execution).map { |raw| Snapshot.new(raw) }
     end
   end
 end

data/lib/yobi/repository/stats.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "json"
-
 module Yobi
   class Repository
     # @private
@@ -29,7 +27,7 @@ module Yobi
         a.repeat_flag(:tag, tags)
       end
       execution = run_restic(argv)
-      RepositoryStats.new(JSON.parse(execution[:output].to_s))
+      RepositoryStats.new(parse_json_output(execution))
     end
   end
 

data/lib/yobi/repository.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "uri"
 
 module Yobi
@@ -23,9 +24,10 @@ module Yobi
     #   responding to `#call` returning such a Hash
     # @param restic [Yobi::Restic, String, nil] a `Restic` instance to share,
     #   a bare Restic binary path, or `nil` to create a default one
-    # @raise [ArgumentError] if `password:` is `nil`
+    # @raise [ArgumentError] if `password:` is `nil`, or if `password:`/`backend_credentials:`/`restic:` is an invalid shape
     def initialize(url:, password:, backend_credentials: {}, restic: nil)
-      raise ArgumentError, "password: is required (use :insecure_no_password if the repository truly has none)" if password.nil?
+      validate_password_shape!(password)
+      validate_backend_credentials_shape!(backend_credentials)
 
       @url, @extracted_rest_credentials = extract_rest_credentials(url)
       @password = password
@@ -61,6 +63,21 @@ module Yobi
       builder.to_a
     end
 
+    # Parses a command's captured output as JSON. If parsing fails, raises
+    # {Yobi::ResticCommandFailed} when `execution[:exit_code]` is `3`
+    # (Restic reported a problem alongside otherwise-JSON output), or
+    # re-raises the original +JSON::ParserError+ when it's `0`.
+    #
+    # @param execution [Hash] `{exit_code:, output:, argv:}`
+    # @return [Object] the parsed JSON
+    # @raise [Yobi::ResticCommandFailed] if parsing fails and `exit_code` is `3`
+    def parse_json_output(execution)
+      JSON.parse(execution[:output].to_s)
+    rescue JSON::ParserError
+      raise if execution[:exit_code].zero?
+      raise Yobi::ResticCommandFailed, execution
+    end
+
     def resolved_password
       password_env(password)
     end
@@ -119,6 +136,51 @@ module Yobi
       end
     end
 
+    def from_repo_password(from_repo)
+      from_repo.password if from_repo.is_a?(Repository)
+    end
+
+    def resolved_from_repo_flag(from_repo)
+      case from_repo
+      in Repository
+        [:from_repo, from_repo.url]
+      in String
+        [:from_repo, from_repo]
+      in [:file, String => path]
+        [:from_repository_file, path]
+      else
+        raise ArgumentError, "invalid from_repo shape"
+      end
+    end
+
+    def validate_password_shape!(value, name: "password")
+      case value
+      in nil
+        raise ArgumentError, "#{name}: is required (use :insecure_no_password if there truly is none)"
+      in :insecure_no_password | String | [:command, String] | [:file, String]
+        true
+      in callable if callable.respond_to?(:call)
+        true
+      else
+        raise ArgumentError, "invalid #{name} shape"
+      end
+    end
+
+    def validate_from_password_shape!(value)
+      validate_password_shape!(value, name: "from_password")
+    end
+
+    def validate_backend_credentials_shape!(value)
+      case value
+      in Hash
+        true
+      in callable if callable.respond_to?(:call)
+        true
+      else
+        raise ArgumentError, "invalid backend_credentials shape"
+      end
+    end
+
     def extract_rest_credentials(url)
       return [url, {}] unless url.start_with?("rest:")
 
@@ -139,6 +201,8 @@ module Yobi
         restic_or_restic_path
       in String | nil
         Yobi::Restic.new(restic_or_restic_path)
+      else
+        raise ArgumentError, "invalid restic shape"
       end
     end
   end

data/lib/yobi/restic.rb

@@ -262,7 +262,7 @@ module Yobi
       self.class.dispatch(exit_code: status.exitstatus, output: output, argv: argv)
       result
     rescue Errno::ENOENT
-      output&.file&.close
+      output.file.close
       raise Yobi::ResticNotFound.new(restic_path: restic_path, argv: argv)
     end
 
@@ -324,7 +324,7 @@ module Yobi
       _, status = Process.wait2(pid)
       {exit_code: status.exitstatus, output: output, argv: argv}
     rescue Errno::ENOENT
-      output&.file&.close
+      output.file.close
       raise Yobi::ResticNotFound.new(restic_path: restic_path, argv: argv)
     end
 
@@ -352,7 +352,7 @@ module Yobi
         {exit_code: wait_thr.value.exitstatus, output: output, argv: argv}
       end
     rescue Errno::ENOENT
-      output&.file&.close
+      output.file.close
       raise Yobi::ResticNotFound.new(restic_path: restic_path, argv: argv)
     end
   end

data/lib/yobi/version.rb

@@ -4,5 +4,5 @@
 # plain Ruby objects instead of shelling out to flags and raw JSON by hand.
 module Yobi
   # @return [String]
-  VERSION = "0.2.0"
+  VERSION = "0.3.1"
 end

data/sig/yobi.rbs

@@ -221,6 +221,7 @@ module Yobi
   type new_password = String | [:file, String] | :insecure_no_password | (^() -> String)
   type backend_credentials = Hash[String, String] | (^() -> Hash[String, String])
   type restic_or_path = Restic | String | nil
+  type from_repo = String | Repository | [:file, String]
 
   class Restic
     MINIMUM_VERSION: Gem::Version
@@ -295,7 +296,7 @@ module Yobi
     def env: () -> Hash[String, String]
 
     def init: (?copy_chunker_params: bool, ?from_key_hint: String?, ?from_password: from_password,
-      ?from_repo: String | Repository | nil, ?from_repository_file: String?, ?repository_version: String?) -> Initialized
+      ?from_repo: from_repo?, ?repository_version: String?) -> Initialized
 
     def init_mirror: (url: String, password: password, ?backend_credentials: backend_credentials,
       ?restic: restic_or_path, ?repository_version: String?) -> Repository
@@ -335,8 +336,8 @@ module Yobi
     def check: (?hosts: Array[String] | String, ?paths: Array[String] | String, ?read_data: bool,
       ?read_data_subset: String?, ?tags: Array[String] | String, ?with_cache: bool) -> CheckOutcome
 
-    def copy: (from_repo: String | Repository, ?from_password: from_password, ?snapshot_ids: Array[String] | String,
-      ?from_key_hint: String?, ?from_repository_file: String?, ?hosts: Array[String] | String,
+    def copy: (from_repo: from_repo, ?from_password: from_password, ?snapshot_ids: Array[String] | String,
+      ?from_key_hint: String?, ?hosts: Array[String] | String,
       ?paths: Array[String] | String, ?tags: Array[String] | String) -> true
 
     def diff: (from: String, to: String, ?metadata: bool) -> DiffOutcome

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yobi
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Zia Perdana
@@ -61,7 +61,7 @@ metadata:
   homepage_uri: https://codeberg.org/ukazap/yobi
   source_code_uri: https://codeberg.org/ukazap/yobi
   changelog_uri: https://codeberg.org/ukazap/yobi/src/branch/main/CHANGELOG.md
-  documentation_uri: https://rubydoc.info/gems/yobi
+  documentation_uri: https://rubydoc.info/gems/yobi/0.3.1
 rdoc_options: []
 require_paths:
 - lib