yobi 0.3.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56739c72c75a1d5c856bbd619b781dd3986cf1b3c1447d4864edd19b9543d8d9
-  data.tar.gz: a5321fe628cab2f74011ce257a4eee380ed1fcb804456f8afa5482ac84c96b6f
+  metadata.gz: cea1c8c245d4ba7aec5a218441f19921606c7bdb5d2b1ddc9912c2d9519ba15e
+  data.tar.gz: 66bf1c1c5e4ce94706948db27352889b8af41e6967c0c00406c303515181f710
 SHA512:
-  metadata.gz: 9b2253d54dd64aa88658c7ddd53734a2edbcaf2623bb98258bc14d71d0d4a82bb3bcb447e6434bfb28505d2bfcd329988841d8f491ce7c3d1b13865b4a50b0f7
-  data.tar.gz: 7cd169b509d216a99b258180381c9caa9cd92837b822467781b01c3788cc37af4252d825b4de50a511b71a521a4e8d9bff8317a7f9c0da11b82847c6b65c2b8c
+  metadata.gz: 89d14f78cd56cfcd7e48e3d56b94a2f5159ac5de5877872797b106307730d0d8c98702fd897ac5572f72d294fede4726e59cecfeab942e1fc29c1e15fe4184f3
+  data.tar.gz: d2c8ae8d702cebc1186c0f117abb542d1e80e84d4dc5e0ccac7ced97b278cd0762c0b70dfe2db84d968529aa235f12fbfd34b07252aa140d6bc2841cab372221

data/.ruby-version

@@ -0,0 +1 @@
+4.0.5

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [1.1.0] - 2026-09-02
+
+### Added
+
+- `Repository#with_cancellation(token)` and `Yobi::Cancellation`: stop a long-running `#backup`/`#restore`/`#check`/`#prune`/`#forget`/`#copy` from another thread via `token.cancel!`, raising `Yobi::Cancelled` if Restic exited with code 130.
+
+## [1.0.0] - 2026-08-29
+
+### Changed
+
+- **Breaking:** minimum supported Restic bumped from 0.17.1 to 0.18.0. Restic 0.17.x completely ignored `--json` for `tag` and `check`, so those commands ran without error but returned empty `TagOutcome`/`CheckOutcome` objects. 0.18.0 is the first version emitting structured JSON for both. `Yobi::UnsupportedResticVersion` is now raised against any 0.17.x binary.
+
+### Added
+
+- `Restic#restic_path=` setter.
+- `Repository#url=`, `#password=`, and `#backend_credentials=` setters, validated on assignment with the same shapes `#initialize` accepts.
+
 ## [0.3.1] - 2026-08-10
 
 ### Fixed

data/README.md

@@ -1,6 +1,10 @@
 # Yobi
 
-Yobi is a Ruby interface for the [Restic](https://restic.net/) backup program.
+[![Gem Version](https://badge.fury.io/rb/yobi.svg)](https://badge.fury.io/rb/yobi)
+
+A Ruby interface for the [Restic](https://restic.net/) backup program.
+
+Tested against Restic 0.18.0, 0.18.1, 0.19.0, 0.19.1.
 
 ## Installation
 
@@ -30,7 +34,7 @@ restic version
 
 ### Minimum supported version
 
-Yobi requires Restic **0.17.1** or newer. This isn't arbitrary: `Yobi::Restic`'s exit-code-based error dispatch (mapping Restic's own exit codes to `Yobi::RepositoryNotFound`/`RepositoryLocked`/`AuthenticationFailed`) depends on a convention that's only guaranteed since that version. An older Restic could reuse those same exit codes for different failures, so rather than risk silently misclassifying an error, Yobi checks the installed version before running any real command and raises `Yobi::UnsupportedResticVersion` if it's too old:
+Yobi requires Restic **0.18.0** or newer. Its typed errors (`Yobi::RepositoryNotFound`, `RepositoryLocked`, `AuthenticationFailed`) rely on stable exit codes, and its `#tag`/`#check` outcomes rely on structured `--json` output that older restic didn't emit for those commands. Yobi checks the installed version before running any real command and raises `Yobi::UnsupportedResticVersion` if it's too old:
 
 ```ruby
 begin
@@ -40,7 +44,7 @@ rescue Yobi::UnsupportedResticVersion => e
 end
 ```
 
-See ["Minimum-version enforcement, in detail"](#minimum-version-enforcement-in-detail) below for the mechanics. If you'd rather fail fast at application startup instead of on the first backup attempt, call it explicitly:
+If you'd rather fail fast at application startup instead of on the first backup attempt, call it explicitly:
 
 ```ruby
 RESTIC = Yobi::Restic.new
@@ -216,6 +220,7 @@ The full hierarchy, all under `Yobi::Error < StandardError`:
 - `Yobi::RepositoryNotFound`, `Yobi::RepositoryLocked`, `Yobi::AuthenticationFailed`: Restic's own typed exit codes (10/11/12).
 - `Yobi::ResticCommandFailed`: any other non-zero exit, for a failure that doesn't fit one of the above.
 - `Yobi::MountTimeout`: `#mount` didn't report itself ready within its timeout.
+- `Yobi::Cancelled`: the run was stopped through a `Yobi::Cancellation` token (see ["Cancelling a running command"](#cancelling-a-running-command) below).
 
 Every method below lives on `Yobi::Repository` unless noted otherwise.
 
@@ -230,7 +235,7 @@ repo.init
 # => #<Yobi::Initialized id="..." repository="...">
 ```
 
-`copy_chunker_params:` copies chunker parameters from another repository (`from_repo:`/`from_password:`/etc.), so a later `#copy` between the two can deduplicate - see `#init_mirror` under ["Across repositories"](#across-repositories) for a shortcut that sets this up in one call. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#init-instance_method) for the full list of options. Returns an `Initialized` (`#id`/`#repository`).
+`copy_chunker_params:` copies chunker parameters from another repository (`from_repo:`/`from_password:`/etc.), so a later `#copy` between the two can deduplicate - see `#init_mirror` under ["Across repositories"](#across-repositories) for a shortcut that sets this up in one call. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#init-instance_method) for the full list of options. Returns an `Initialized` (`#id`/`#repository`).
 
 ### `#cat_config`
 
@@ -261,7 +266,7 @@ outcome.summary["data_added"]
 
 `source:` is either a path String, or a `[:stdin_from_command, command]`/`[:stdin_from_command, command, filename]` tuple: Restic spawns and executes `command` itself, capturing its stdout as the backup content (see ["Database dumps via `stdin_from_command`"](#database-dumps-via-stdin_from_command) below for a `pg_dump` example). `command` can be a String (tokenized with `Shellwords.split`, so quoted arguments survive) or an Array of already-discrete arguments (used as-is; needed when an argument itself contains a literal space, which `Shellwords` would otherwise split incorrectly).
 
-`host:` records a hostname on the *new* snapshot - a single value, since this is metadata being written, not a filter, unlike every `hosts:` elsewhere in this API. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#backup-instance_method) for the full list of options (filtering, retention, timing, and more).
+`host:` records a hostname on the *new* snapshot - a single value, since this is metadata being written, not a filter, unlike every `hosts:` elsewhere in this API. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#backup-instance_method) for the full list of options (filtering, retention, timing, and more).
 
 Returns a `BackupOutcome`: `#summary` (aliased `#report`; a `BackupSummary`, Restic's own summary fields plus `#backup_start`/`#backup_end` parsed into `Time`), `#errors` (lazy Enumerable of `BackupError` - empty unless some files were skipped, e.g. permission errors; a full failure raises before an outcome exists at all, see ["Error handling"](#error-handling) below), `#command_output` (the `source: [:stdin_from_command, ...]` subprocess's own stderr, de-prefixed, if any).
 
@@ -291,7 +296,7 @@ outcome.summary["snapshot_id"]
 repo.restore(snapshot_id: "latest", target: "/tmp/restore")
 ```
 
-`snapshot_id:` accepts `"latest"` or a real ID; `target:` is the destination directory. `delete:` removes files in `target:` not present in the snapshot - worth knowing about since it's the one option here that can destroy data outside the snapshot itself. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#restore-instance_method) for the full list of options (filtering, `overwrite:` behavior, and more).
+`snapshot_id:` accepts `"latest"` or a real ID; `target:` is the destination directory. `delete:` removes files in `target:` not present in the snapshot - the one option here that can destroy data outside the snapshot itself. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#restore-instance_method) for the full list of options (filtering, `overwrite:` behavior, and more).
 
 Returns a `RestoreOutcome`: `#summary` (aliased `#report`; Restic's own summary fields as a plain `Hash`) - restore has no exit code 3, so any item-level failure is a hard error that raises before an outcome exists.
 
@@ -315,7 +320,7 @@ repo.dump(snapshot_id: "latest", file: "/var/www", target: "/tmp/www.tar")
 repo.dump(snapshot_id: "latest", file: "/var/www", target: "/tmp/www.zip", archive: "zip")
 ```
 
-Give at most one of `target:` or a block. Without either, returns a `Yobi::IOHandle` instead. `hosts:`/`paths:`/`tags:` filters are also available when `snapshot_id:` is `"latest"` - see the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#dump-instance_method) for the full list of options.
+Give at most one of `target:` or a block. Without either, returns a `Yobi::IOHandle` instead. `hosts:`/`paths:`/`tags:` filters are also available when `snapshot_id:` is `"latest"` - see the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#dump-instance_method) for the full list of options.
 
 ```ruby
 handle = repo.dump(snapshot_id: "latest", file: "/var/www")
@@ -335,7 +340,7 @@ outcome.statistics.changed_files
 outcome.changes.each { |change| puts "#{change.modifier} #{change.path}" }
 ```
 
-`metadata: true` also reports metadata-only changes (permissions, timestamps) alongside content changes. `change.modifier` is Restic's own concatenation of single-character codes: `+` added, `-` removed, `U` metadata updated, `M` content modified, `T` type changed, `?` bitrot detected. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#diff-instance_method) for the full list of options.
+`metadata: true` also reports metadata-only changes (permissions, timestamps) alongside content changes. `change.modifier` is Restic's own concatenation of single-character codes: `+` added, `-` removed, `U` metadata updated, `M` content modified, `T` type changed, `?` bitrot detected. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#diff-instance_method) for the full list of options.
 
 Returns a `DiffOutcome`: `#statistics` (aliased `#report`; a `DiffStatistics` with `#changed_files` plus `#added`/`#removed` `DiffStat` breakdowns) and lazy `#changes` (Enumerable of `DiffChange`, with predicates like `#modified?`/`#added?` alongside the raw `#modifier`).
 
@@ -349,7 +354,7 @@ repo.snapshots(tags: ["daily"], hosts: "web-1").each do |snapshot|
 end
 ```
 
-Returns an Enumerable of `Snapshot` (`#id`, `#short_id`, `#time`, `#host`, `#tags`, `#paths`, `#parent_id`, `#summary` - a `SnapshotSummary` with the same stats fields `#backup`'s own summary has). `group_by:`/`latest:` group and limit results, e.g. `latest: 1` per group for "the most recent backup of each host." See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#snapshots-instance_method) for the full list of options.
+Returns an Enumerable of `Snapshot` (`#id`, `#short_id`, `#time`, `#host`, `#tags`, `#paths`, `#parent_id`, `#summary` - a `SnapshotSummary` with the same stats fields `#backup`'s own summary has). `group_by:`/`latest:` group and limit results, e.g. `latest: 1` per group for "the most recent backup of each host." See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#snapshots-instance_method) for the full list of options.
 
 ### `#tag`
 
@@ -357,7 +362,7 @@ Returns an Enumerable of `Snapshot` (`#id`, `#short_id`, `#time`, `#host`, `#tag
 repo.tag(snapshot_ids: snapshot.id, add: "verified")
 ```
 
-`add:`/`remove:`/`set:` (mutually exclusive with `add:`/`remove:` in Restic itself) modify tags on snapshots matched by `snapshot_ids:` (or by `hosts:`/`paths:`/`tags:` filters when no explicit IDs are given). Since tags are part of a snapshot's content-addressed identity, tagging produces a *new* snapshot ID for every snapshot touched. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#tag-instance_method) for the full list of options.
+`add:`/`remove:`/`set:` (mutually exclusive with `add:`/`remove:` in Restic itself) modify tags on snapshots matched by `snapshot_ids:` (or by `hosts:`/`paths:`/`tags:` filters when no explicit IDs are given). Since tags are part of a snapshot's content-addressed identity, tagging produces a *new* snapshot ID for every snapshot touched. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#tag-instance_method) for the full list of options.
 
 Returns a `TagOutcome`: `#summary` (aliased `#report`; a `TagSummary` - just `#changed_snapshots`) and lazy `#changes` (Enumerable of `TagChange`, the old-ID/new-ID pairs).
 
@@ -367,7 +372,7 @@ Returns a `TagOutcome`: `#summary` (aliased `#report`; a `TagSummary` - just `#c
 repo.forget(keep_daily: 7, keep_weekly: 4, keep_monthly: 12, prune: true)
 ```
 
-Applies a retention policy, removing snapshots that don't match any `keep_*` rule (counts like `keep_daily:`, or durations like `keep_within:`). `prune: true` also reclaims the disk space the forgotten snapshots held (equivalent to a separate `#prune` call afterward). See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#forget-instance_method) for the full list of options.
+Applies a retention policy, removing snapshots that don't match any `keep_*` rule (counts like `keep_daily:`, or durations like `keep_within:`). `prune: true` also reclaims the disk space the forgotten snapshots held (equivalent to a separate `#prune` call afterward). See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#forget-instance_method) for the full list of options.
 
 Returns an Enumerable of `ForgetGroup` (Restic evaluates the policy per group, by default grouped by host+paths). Each exposes `#keep`/`#remove` (Arrays of `Snapshot`) and `#reasons` (an Array of `KeepReason` explaining which rule kept each surviving snapshot, e.g. `"daily snapshot"`).
 
@@ -380,9 +385,9 @@ repo.find(patterns: "*.pem").each do |matches|
 end
 ```
 
-Searches for files/directories by name pattern across snapshots. `blob:`/`pack:`/`tree:` switch to matching object IDs instead, for low-level troubleshooting. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#find-instance_method) for the full list of options.
+Searches for files/directories by name pattern across snapshots. `blob:`/`pack:`/`tree:` switch to matching object IDs instead, for low-level troubleshooting. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#find-instance_method) for the full list of options.
 
-Returns an Enumerable of `MatchesPerSnapshot` (Restic's own docs describe find's output as "organized by snapshot," not a flat list). Each has `#snapshot`/`#snapshot_id` (just the matched snapshot's ID as a String - unlike elsewhere in this API, Restic's own `find` output doesn't include the full record), `#hits`, and `#matches` (an Array of `FindMatch`, with the usual file metadata: `#path`, `#size`, `#mtime`, etc.).
+Returns an Enumerable of `MatchesPerSnapshot`, one per snapshot with matches. Each has `#snapshot`/`#snapshot_id` (just the matched snapshot's ID as a String - unlike elsewhere in this API, Restic's own `find` output doesn't include the full record), `#hits`, and `#matches` (an Array of `FindMatch`, with the usual file metadata: `#path`, `#size`, `#mtime`, etc.).
 
 ### `#ls`
 
@@ -392,7 +397,7 @@ outcome.snapshot.short_id
 outcome.nodes.each { |node| puts node.path }
 ```
 
-Lists a snapshot's files/directories. `recursive:` descends into subdirectories. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#ls-instance_method) for the full list of options.
+Lists a snapshot's files/directories. `recursive:` descends into subdirectories. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#ls-instance_method) for the full list of options.
 
 Returns an `LsOutcome`: `#snapshot` (the resolved `Snapshot`, useful to see what `"latest"` actually resolved to) and lazy `#nodes` (aliased `#entries`; Enumerable of `Node` - Restic's own term for a file/directory entry).
 
@@ -406,7 +411,7 @@ outcome.summary.num_errors
 outcome.errors.each { |error| puts error.message }
 ```
 
-Verifies repository integrity. `read_data:` also reads and verifies every pack file's actual contents, not just structure (slow, thorough); `read_data_subset:` does a partial version of the same (e.g. `"5%"`, or `"1/20"` for a fifth each day in rotation). See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#check-instance_method) for the full list of options.
+Verifies repository integrity. `read_data:` also reads and verifies every pack file's actual contents, not just structure (slow, thorough); `read_data_subset:` does a partial version of the same (e.g. `"5%"`, or `"1/20"` for a fifth each day in rotation). See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#check-instance_method) for the full list of options.
 
 Returns a `CheckOutcome`: `#summary` (aliased `#report`; a `CheckSummary` covering the error count and what to run next - repair or prune) and `#errors` (lazy Enumerable of `CheckError`) for problems found.
 
@@ -416,7 +421,7 @@ Returns a `CheckOutcome`: `#summary` (aliased `#report`; a `CheckSummary` coveri
 repo.prune(max_unused: "5%")
 ```
 
-Removes data no longer referenced by any snapshot. `dry_run:` reports what would happen without doing it; `max_unused:` targets a maximum acceptable unused-space ratio after pruning. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#prune-instance_method) for the full list of options. Returns `true`.
+Removes data no longer referenced by any snapshot. `dry_run:` reports what would happen without doing it; `max_unused:` targets a maximum acceptable unused-space ratio after pruning. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#prune-instance_method) for the full list of options. Returns `true`.
 
 ### `#repair_index`, `#repair_packs`, `#repair_snapshots`
 
@@ -426,7 +431,7 @@ repo.repair_packs(ids: damaged_pack_ids)
 repo.repair_snapshots(snapshot_ids: affected_ids, forget: true)
 ```
 
-`#repair_index` rebuilds the index from the pack files present (the modern successor to Restic's now-deprecated `rebuild-index`). `#repair_packs` extracts intact blobs from damaged pack files and drops the rest. Restic also writes a backup copy of each given pack (named `pack-<id>`) into the *calling process's own current working directory* first, with no flag to disable this; be aware of where your process runs from before calling it. `#repair_snapshots` regenerates snapshots with damaged content removed. This is real data loss for whatever gets removed, so prefer a fresh `#backup` where the source data is still available, and run `#repair_index` first since this depends on a correct index. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#repair_snapshots-instance_method) for the full list of options.
+`#repair_index` rebuilds the index from the pack files present (the modern successor to Restic's now-deprecated `rebuild-index`). `#repair_packs` extracts intact blobs from damaged pack files and drops the rest. Restic also writes a backup copy of each given pack (named `pack-<id>`) into the *calling process's own current working directory* first, with no flag to disable this; be aware of where your process runs from before calling it. `#repair_snapshots` regenerates snapshots with damaged content removed - depends on a correct index, so run `#repair_index` first. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#repair_snapshots-instance_method) for the full list of options.
 
 ### `#recover`
 
@@ -434,7 +439,7 @@ repo.repair_snapshots(snapshot_ids: affected_ids, forget: true)
 repo.recover
 ```
 
-Builds a new snapshot from any data present in the repository but not referenced by an existing snapshot (e.g. after an accidental `#forget`). Call `#snapshots` afterward to see whether anything was actually recovered. Restic reports "nothing to do" as plain text with no structured way to tell the two cases apart.
+Builds a new snapshot from any data present in the repository but not referenced by an existing snapshot (e.g. after an accidental `#forget`). Call `#snapshots` afterward to see whether anything was actually recovered.
 
 ### `#rewrite`
 
@@ -442,7 +447,7 @@ Builds a new snapshot from any data present in the repository but not referenced
 repo.rewrite(snapshot_ids: old.id, excludes: "*.log", new_time: Time.now.iso8601)
 ```
 
-Creates new snapshots from existing ones with filters applied or metadata changed. With no `snapshot_ids:`/`hosts:`/`tags:`/`paths:` given, rewrites every snapshot in the repository - Restic's own default, not something Yobi adds. `dry_run:` reports what would happen without doing it. `forget: false` (the default) tags the new snapshots `"rewrite"` and keeps the originals; `forget: true` removes the originals instead (their data isn't reclaimed until a later `#prune`). See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#rewrite-instance_method) for the full list of options.
+Creates new snapshots from existing ones with filters applied or metadata changed. With no `snapshot_ids:`/`hosts:`/`tags:`/`paths:` given, rewrites every snapshot in the repository. `dry_run:` reports what would happen without doing it. `forget: false` (the default) tags the new snapshots `"rewrite"` and keeps the originals; `forget: true` removes the originals instead (their data isn't reclaimed until a later `#prune`). See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#rewrite-instance_method) for the full list of options.
 
 ### `#migrate`
 
@@ -467,7 +472,7 @@ repo.stats(mode: "raw-data")
 # => #<Yobi::RepositoryStats total_size=... total_file_count=... snapshots_count=...>
 ```
 
-Repository size/file-count statistics. `mode:` picks the counting strategy, as a String or Symbol: `"restore-size"`/`:restore_size` (default), `"files-by-contents"`/`:files_by_contents`, `"blobs-per-file"`/`:blobs_per_file`, `"raw-data"`/`:raw_data` (actual on-disk size, accounting for deduplication). Anything else raises `ArgumentError`. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#stats-instance_method) for more. Returns a `RepositoryStats` covering size, file/blob counts, and (for a repository using compression) how much space it's saving.
+Repository size/file-count statistics. `mode:` picks the counting strategy, as a String or Symbol: `"restore-size"`/`:restore_size` (default), `"files-by-contents"`/`:files_by_contents`, `"blobs-per-file"`/`:blobs_per_file`, `"raw-data"`/`:raw_data` (actual on-disk size, accounting for deduplication). Anything else raises `ArgumentError`. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#stats-instance_method) for more. Returns a `RepositoryStats` covering size, file/blob counts, and (for a repository using compression) how much space it's saving.
 
 ## Key management
 
@@ -480,9 +485,9 @@ repo.key_remove(id: old_key.id)
 
 `#key_add`/`#key_list`/`#key_passwd`/`#key_remove` (aliased `#add_key`/`#keys`/`#change_password`/`#remove_key`) manage passwords. Every key here is a different way to unlock the same underlying master key, not a separate encryption key of its own (see ["Low-level (`cat`) and object listing"](#low-level-cat-and-object-listing) below's note on `#cat_masterkey_and_game_over_if_this_leaks`).
 
-`#key_add`/`#key_passwd` share the same kwargs: `new_password:` is required, accepting the same shapes as `#initialize`'s `password:` minus `[:command, ...]`: a literal String; a `[:file, "..."]` tuple, resolved natively by Restic; `:insecure_no_password`; or anything responding to `#call`. Restic itself only accepts a new password by file, unlike the repository's own `password:`, so a literal String or callable is written to a briefly-lived, 0600-permissioned tempfile by Yobi first. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#key_add-instance_method) for the full list of options.
+`#key_add`/`#key_passwd` share the same kwargs: `new_password:` is required, accepting the same shapes as `#initialize`'s `password:` minus `[:command, ...]`: a literal String; a `[:file, "..."]` tuple, resolved natively by Restic; `:insecure_no_password`; or anything responding to `#call`. Restic itself only accepts a new password by file, unlike the repository's own `password:`, so a literal String or callable is written to a briefly-lived, 0600-permissioned tempfile by Yobi first. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#key_add-instance_method) for the full list of options.
 
-`#key_passwd` rotates the *password*, not the underlying master key itself (see the note on `#cat_masterkey_and_game_over_if_this_leaks` below if that distinction matters for your threat model). On success, it also updates this same `Repository` instance's own `password:` to match, so it keeps working against the repository right afterward:
+`#key_passwd` rotates the *password*, not the underlying master key itself (see the note on `#cat_masterkey_and_game_over_if_this_leaks` below). On success, it also updates this same `Repository` instance's own `password:` to match, so it keeps working against the repository right afterward:
 
 ```ruby
 repo.key_passwd(new_password: "new-password-value")
@@ -503,7 +508,7 @@ repo.list(:packs)                     # => Array of pack IDs
 
 `#cat_snapshot`/`#cat_index`/`#cat_key`/`#cat_tree` return a repository object's raw stored record as a Hash, lower-level than `#snapshots`/`#key_list`, which wrap entries in `Snapshot`/`Key` instead. `#cat_snapshot`/`#cat_key`/`#cat_tree` each accept either a bare ID String or the corresponding wrapper object (`Snapshot`/`Key`/`Snapshot`) directly; `#cat_index` only takes a bare ID String, since index entries have no wrapper class of their own. `#cat_pack`/`#cat_blob` are raw-bytes commands with the same block/`IOHandle` shape as `#dump`. `#list(type)` enumerates every object ID of a given type (`:blobs`/`:packs`/`:index`/`:snapshots`/`:keys`/`:locks`) as plain strings. Restic ignores `--json` for this command, so these come back exactly as Restic prints them.
 
-`#cat_masterkey_and_game_over_if_this_leaks` returns the repository's actual encryption/MAC key material: not a redacted reference, the real thing. There is no operation that rotates this key; every password change made afterward protects nothing already backed up if this value ever leaks. Treat the return value with more care than you'd give `password:` itself: unlike a password, this can't be rotated away after a leak.
+`#cat_masterkey_and_game_over_if_this_leaks` returns the repository's actual encryption/MAC key material: not a redacted reference, the real thing. There is no operation that rotates this key; a leak means every past snapshot in the repository stays decryptable forever, no password change fixes that.
 
 ## Across repositories
 
@@ -521,7 +526,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, 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`.
+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 [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#copy-instance_method) for the full list of options. Returns `true`.
 
 ## Mounting
 
@@ -544,7 +549,7 @@ ensure
 end
 ```
 
-`#stop` is safe to call more than once, and `MountHandle#pid`/`MountHandle#stop` are safe even if something *else* already triggered the unmount externally (`kill -INT <pid>`, or the OS's own `umount`/`fusermount` directly). `hosts:`/`paths:`/`tags:` restrict which snapshots appear under the mount's own `snapshots/` directory. `ready_timeout:` (default 10 seconds) bounds how long `#mount` waits for Restic's own readiness message before raising `Yobi::MountTimeout`. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Repository#mount-instance_method) for the full list of options.
+`#stop` is safe to call more than once, and `MountHandle#pid`/`MountHandle#stop` are safe even if something *else* already triggered the unmount externally (`kill -INT <pid>`, or the OS's own `umount`/`fusermount` directly). `hosts:`/`paths:`/`tags:` restrict which snapshots appear under the mount's own `snapshots/` directory. `ready_timeout:` (default 10 seconds) bounds how long `#mount` waits for Restic's own readiness message before raising `Yobi::MountTimeout`. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Repository#mount-instance_method) for the full list of options.
 
 ## Restic-level (not scoped to a repository)
 
@@ -554,11 +559,11 @@ restic.version.version # => "0.19.1"
 restic.cache(cleanup: true)
 ```
 
-`#version` and `#cache` are the two Restic subcommands that don't touch a repository at all, so they live on `Yobi::Restic` rather than `Repository`. `#version` returns a `Yobi::ResticVersion` (`#version`, `#go_version`, `#go_os`, `#go_arch`); if the installed binary is old enough to ignore `--json` for this command entirely, Yobi falls back to parsing its plain-text output for the version number instead of raising a JSON parse error. `#cache` lists (or, with `cleanup: true`, cleans) local cache directories, returning `true`. See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Restic#cache-instance_method) for its remaining options.
+`#version` and `#cache` are the two Restic subcommands that don't touch a repository at all, so they live on `Yobi::Restic` rather than `Repository`. `#version` returns a `Yobi::ResticVersion` (`#version`, `#go_version`, `#go_os`, `#go_arch`); if the installed binary is old enough to ignore `--json` for this command entirely, Yobi falls back to parsing its plain-text output for the version number instead of raising a JSON parse error. `#cache` lists (or, with `cleanup: true`, cleans) local cache directories, returning `true`. See the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Restic#cache-instance_method) for its remaining options.
 
 ## Global `Restic` settings
 
-Settings that apply regardless of which repository is being operated on live on `Yobi::Restic`, not `Repository`:
+`Yobi::Restic` holds settings that apply to every command, regardless of repository:
 
 ```ruby
 restic = Yobi::Restic.new(
@@ -568,14 +573,9 @@ restic = Yobi::Restic.new(
 )
 ```
 
-Two genuinely different kinds, both exposed as plain `attr_accessor`s:
-
-- **Env-var-backed** (e.g. `cache_dir:`, `compression:`, `pack_size:`): `Restic#env` computes the corresponding `RESTIC_*` vars fresh from the current accessor values on every call. Mutating one after construction is picked up by the very next command.
-- **CLI-flag-only, no env var equivalent** (e.g. `limit_upload:`, `no_lock:`, `options:` - Restic's own `--option`/`-o`, an escape hatch for backend-specific tuning like `s3.connections=10`).
+Some map to `RESTIC_*` env vars (`cache_dir:`, `compression:`, `pack_size:`). Others are CLI flags with no env equivalent (`limit_upload:`, `no_lock:`, `options:`, etc.). `options:` maps to Restic's `-o` for backend tuning like `s3.connections=10`.
 
-See the [YARD docs](https://rubydoc.info/gems/yobi/Yobi/Restic) for the full list of settings.
-
-"Picked up by the very next command" assumes calls happen one at a time. If you mutate one of these accessors on a `Restic` shared across threads while another thread has a command already in flight on it, which value that in-flight command actually uses is a race with no ordering guarantee, though not a crash: each accessor read/write is still atomic, so you won't get a corrupted argv, just an unpredictable choice between the old and new value.
+Every setting is an `attr_accessor`. Change one and the next command sees the new value. Full list in the [docs](https://rubydoc.info/gems/yobi/1.1.0/Yobi/Restic).
 
 ### Sharing a `Restic` across repositories
 
@@ -586,11 +586,50 @@ customer_a = Yobi::Repository.new(url: "s3:.../customer-a", password: "...", res
 customer_b = Yobi::Repository.new(url: "s3:.../customer-b", password: "...", restic: restic)
 ```
 
-Both repositories now use the same `limit_upload:` value, and changing `restic.limit_upload` later affects every repository built from it. This isn't a shared, pooled cap: Restic applies `--limit-upload` per invocation, so two backups running concurrently through this same `restic` are each independently capped at 5000, not splitting one combined 5000 between them. Useful when one process backs up many repositories under one operational policy, without repeating the same settings on every `Repository.new` call.
+Both use the same settings. Changing `restic.limit_upload` later affects every repository built from it.
+
+`--limit-upload` is per-invocation. Two backups running concurrently through the same `restic` are each capped at 5000. They don't share one 5000 budget.
+
+## Cancelling a running command
+
+Call `Repository#with_cancellation(token)` before `#backup`, `#restore`, `#check`, `#prune`, `#forget`, or `#copy`, then `token.cancel!` from another thread to stop it:
+
+```ruby
+token = Yobi::Cancellation.new
+
+worker = Thread.new do
+  repo.with_cancellation(token).backup(source: "/Users/zia/Documents")
+rescue Yobi::Cancelled
+  # the user stopped it; not a backup failure
+end
+
+token.cancel!   # => true
+worker.join
+```
+
+`#cancel!` sends **SIGINT**, not SIGKILL - Restic removes its own repository lock on the way out, so no `#unlock` is needed. Override with `cancel!(signal: "TERM")` only if you have a reason to.
+
+Restic exits with its own documented code 130 when killed by a signal; Yobi raises `Yobi::Cancelled` for that instead of `Yobi::ResticCommandFailed`.
+
+Safe at any point, from any thread; `#cancel!` is idempotent, returning `true` the first time and `false` after. Cancelling before the command starts means Restic never spawns; `Yobi::Cancelled#before_start?` tells the two cases apart:
+
+```ruby
+begin
+  repo.with_cancellation(token).backup(source: "/data")
+rescue Yobi::Cancelled => error
+  error.before_start?          # => true if Restic never ran
+  error.execution[:exit_code]  # => nil in that case, otherwise the real exit code
+end
+```
 
-### Minimum-version enforcement, in detail
+What an interrupted run leaves behind:
 
-`Yobi::Restic#run`/`#run_dump`/`#run_mount` all call `#ensure_minimum_version!` before executing a real command. It's memoized per `Restic` instance. The check runs once, not on every call, since the binary on disk isn't expected to change mid-process. See ["Minimum supported version"](#minimum-supported-version) above for what triggers it and why 0.17.1 specifically.
+- `#backup`: no snapshot is written; data already uploaded is generally left *unreferenced* rather than reused by the next run, and orphaned packs are only reclaimed by a later `#prune`.
+- `#restore`: the target directory may be left partially written (some files complete, others missing).
+- `#check`: read-only, nothing is written; safe to cancel at any point.
+- `#prune`: Restic's repacking is designed to be crash-safe, but repacking done so far may not be reused (the next `#prune` can end up starting over).
+- `#forget`: some snapshots may already be removed while the rest are intact, re-run to finish.
+- `#copy`: snapshots already copied should stay in the destination and be skipped on a re-run.
 
 ## Redaction
 
@@ -601,7 +640,7 @@ repo.inspect
 # => #<Yobi::Repository url="s3:..." password="[FILTERED]" backend_credentials={"AWS_ACCESS_KEY_ID"=>"[FILTERED]", "AWS_SECRET_ACCESS_KEY"=>"[FILTERED]"}>
 ```
 
-A literal or command/file-sourced `password:` shows as `"[FILTERED]"`; anything callable shows as `"[RESOLVER]"` **without ever being called**. Printing a `Repository` never triggers a real secret-store lookup as a side effect. `:insecure_no_password` shows plainly, since it's an explicit "there is no secret" declaration, not a value that could leak anything. `backend_credentials:` keys not in Restic's own documented list of non-identity operational env vars (`Yobi::Restic::ALLOWED_ENV_VARS`) are filtered the same way; the allowed ones (`RESTIC_CACHE_DIR`, `AWS_DEFAULT_REGION`, and similar non-secret operational vars) stay visible.
+A literal or command/file-sourced `password:` shows as `"[FILTERED]"`; anything callable shows as `"[RESOLVER]"` **without ever being called**. `:insecure_no_password` shows plainly, since it's an explicit "there is no secret" declaration, not a value that could leak anything. `backend_credentials:` keys not in Restic's own documented list of non-identity operational env vars (`Yobi::Restic::ALLOWED_ENV_VARS`) are filtered the same way; the allowed ones (`RESTIC_CACHE_DIR`, `AWS_DEFAULT_REGION`, and similar non-secret operational vars) stay visible.
 
 `#env` itself is never redacted. It's the method that actually builds what gets passed to `Process.spawn`, so it has to return the real values. Only `#inspect` (the thing a stray debug print might accidentally call) filters.
 
@@ -636,7 +675,7 @@ repo.forget(
 )
 ```
 
-A non-empty `outcome.errors` (exit code 3) means some files were skipped but the snapshot was still created (often fine to continue past, e.g. permission-denied on a handful of files); a full failure raises before `outcome` even exists via the usual `Yobi::ResticCommandFailed`/`Yobi::RepositoryLocked`/etc. hierarchy, so wrap the whole thing in the usual `rescue` if you want to alert on that separately (see ["Graceful lock-contention handling"](#graceful-lock-contention-handling) below).
+A non-empty `outcome.errors` (exit code 3) means some files were skipped but the snapshot was still created - often fine to continue past. A full failure raises `Yobi::ResticCommandFailed`/`Yobi::RepositoryLocked`/etc. before `outcome` exists at all; handle those with a `rescue` around the block (see ["Graceful lock-contention handling"](#graceful-lock-contention-handling)).
 
 ### Restore workflows
 
@@ -704,7 +743,7 @@ password: -> {
 }
 ```
 
-If the resolver itself is slow or rate-limited (a network round-trip per Restic invocation adds up over many commands), add your own caching inside the lambda; how long the result stays valid is entirely your call.
+If the resolver itself is slow or rate-limited (a network round-trip per Restic invocation adds up over many commands), add your own caching inside the lambda.
 
 ### Database dumps via `stdin_from_command`
 
@@ -717,7 +756,7 @@ repo.backup(
 )
 ```
 
-The third element (`"mydb.sql"`) names the resulting virtual file inside the snapshot. Omit it to fall back to Restic's own `"stdin"` default. If the command needs an argument containing a literal space (a password with a space in it, an unusual path), pass it as an Array of already-discrete arguments instead of a single String, since `Shellwords`-splitting a string would otherwise break it apart incorrectly. There's no shell involved either way (Restic execs the tokenized argv directly), but if any part of the String form is ever built from untrusted input rather than a hardcoded command like above, `Shellwords.split` will still tokenize whatever that input contains, letting it inject extra arguments into what gets executed. Use the Array form with untrusted values kept to their own discrete elements instead.
+The third element (`"mydb.sql"`) names the resulting virtual file inside the snapshot. Omit it for Restic's own `"stdin"` default. Use the Array form (`["mysqldump", "-u", user, db]`) when any argument contains spaces, or when any part comes from untrusted input - the String form is tokenized with `Shellwords.split`, which will split spaces inside an argument and, on untrusted input, let it inject extra arguments.
 
 ```ruby
 repo.backup(source: [:stdin_from_command, ["mysqldump", "-u", "backup", "my app db"]])
@@ -772,7 +811,7 @@ Customer.find_each do |customer|
 end
 ```
 
-Running commands concurrently through a shared `Repository`/`Restic` is safe (see ["Global `Restic` settings"](#global-restic-settings) above for the one caveat, mutating `restic`'s tuning accessors from another thread while backups are in flight), so backing up many repositories doesn't have to run strictly one at a time. A `Thread.new` per customer would spawn an unbounded number of concurrent `restic` subprocesses, and Ruby silently drops an unhandled exception from a thread that's never joined, so a single customer's failure could vanish instead of getting logged. A small fixed-size worker pool avoids both:
+To run backups concurrently, use a bounded worker pool. It caps how many `restic` subprocesses run at once and catches per-customer errors that would otherwise disappear with the thread:
 
 ```ruby
 queue = Queue.new
@@ -836,7 +875,7 @@ end
 with_retry { repo.backup(source: source_path) }
 ```
 
-For a one-off manual fix instead of retrying, `repo.unlock` removes stale locks left by a process that crashed without cleaning up after itself, but don't call it reflexively inside a retry loop that might be racing a *legitimately still-running* second process; that would double-run the backup.
+For a one-off manual fix, `repo.unlock` removes stale locks left by a process that crashed without cleaning up. Don't put it inside the retry loop above - a lock might belong to a live second process, not a dead one.
 
 ## Non-goals
 
@@ -855,7 +894,7 @@ After checking out the repo, run `bin/setup` to install dependencies.
 - `bin/test`: both, in parallel.
 - `bin/standardrb`: lint.
 - `bin/console`: an interactive prompt with the gem loaded.
-- `bin/docs`: serves YARD docs at http://localhost:8808, reparsing on every request.
+- `bin/docs`: regenerates RDoc into `./doc` and opens the index in the default browser.
 
 See `MAINTAINERS.md` for what to keep in sync as the API changes, and the release checklist.
 

data/lib/yobi/argv_builder.rb

@@ -1,17 +1,8 @@
 # frozen_string_literal: true
 
 module Yobi
-  # Builds a Restic command's argv incrementally. Not an Array subclass:
-  # only the methods below are available; {#to_a} hands back the plain
-  # Array once building is done.
-  #
-  # @private
-  class ArgvBuilder
-    # Maps a flag name Symbol to its "--dashed-string" form, e.g.
-    # `:read_data_subset` to `"--read-data-subset"`.
+  class ArgvBuilder # :nodoc:
     FLAGS = Hash.new { |flags, name| flags[name] = "--#{name.to_s.tr("_", "-")}" }
-
-    # Maps a short flag name Symbol to its "-name" form, e.g. `:vv` to `"-vv"`.
     SHORT_FLAGS = Hash.new { |flags, name| flags[name] = "-#{name}" }
 
     def initialize
@@ -19,21 +10,14 @@ module Yobi
       @end_of_options_called = false
     end
 
-    # @return [Array<String>] the argv built so far
     def to_a
       @argv
     end
 
-    # @return [String]
     def inspect
       "#<#{self.class} #{@argv.inspect}>"
     end
 
-    # Appends one or more bare positional values. `nil` is dropped; an
-    # Enumerable is flattened in; everything else is converted with `#to_s`.
-    #
-    # @param values [Array<Object>]
-    # @return [self]
     def append(*values)
       values.each do |v|
         case v
@@ -49,41 +33,23 @@ module Yobi
       self
     end
 
-    # Appends a flag, plus its value when one is given.
-    #
-    # @param name [Symbol] flag name, looked up in {FLAGS}
-    # @param value [Object, nil] the flag's value; omit for a boolean flag
-    # @return [self]
     def flag(name, value = nil)
       @argv << FLAGS[name]
       @argv << value.to_s unless value.nil?
       self
     end
 
-    # Appends a repeatable flag once per value, e.g. `--host a --host b`.
-    #
-    # @param name [Symbol] flag name, looked up in {FLAGS}
-    # @param values [Array<Object>, Object, nil]
-    # @return [self]
     def repeat_flag(name, values)
       name = FLAGS[name]
       array_of_strings(values).each { |value| @argv << name << value }
       self
     end
 
-    # Appends a short flag, e.g. `short_flag(:vv)` for `-vv`.
-    #
-    # @param name [Symbol] flag name, looked up in {SHORT_FLAGS}
-    # @return [self]
     def short_flag(name)
       @argv << SHORT_FLAGS[name]
       self
     end
 
-    # Appends Restic's `--` end-of-options marker.
-    #
-    # @return [self]
-    # @raise [RuntimeError] if called more than once on the same builder
     def end_of_options
       raise "end_of_options already called - Restic only honors the first \"--\"" if @end_of_options_called
 

data/lib/yobi/cancellable_proxy.rb

@@ -0,0 +1,48 @@
+module Yobi
+  # Returned by Repository#with_cancellation. Exposes only the six
+  # long-running methods a Yobi::Cancellation token can stop; every other
+  # Repository method (#snapshots, #mount, #init, ...) is unreachable here.
+  #
+  # +token+ reaches the repository via a thread-local, set only for the
+  # duration of each call and only on the calling thread.
+  class CancellableProxy
+    def initialize(repository, token)
+      @repository = repository
+      @token = token
+    end
+
+    def backup(...)
+      with_token { @repository.backup(...) }
+    end
+
+    def restore(...)
+      with_token { @repository.restore(...) }
+    end
+
+    def check(...)
+      with_token { @repository.check(...) }
+    end
+
+    def prune(...)
+      with_token { @repository.prune(...) }
+    end
+
+    def forget(...)
+      with_token { @repository.forget(...) }
+    end
+
+    def copy(...)
+      with_token { @repository.copy(...) }
+    end
+
+    private
+
+    def with_token
+      previous = Thread.current[:yobi_cancellation]
+      Thread.current[:yobi_cancellation] = @token
+      yield
+    ensure
+      Thread.current[:yobi_cancellation] = previous
+    end
+  end
+end