yobi 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4daa53c0b99656d99f3b81b808ad6940ad0fa6b8d202f0915b769721972a40a2
-  data.tar.gz: c1931310b0b9081099dedd3251cc304f01f8938ca0de13be82801289af1080db
+  metadata.gz: cea1c8c245d4ba7aec5a218441f19921606c7bdb5d2b1ddc9912c2d9519ba15e
+  data.tar.gz: 66bf1c1c5e4ce94706948db27352889b8af41e6967c0c00406c303515181f710
 SHA512:
-  metadata.gz: dbb9ae518fd0181e5c7cff763f74f113936cefa996eb2ab5bd741e5c61550b5a254cb6b795aadc67363cfdc064351aa2b77f830cb8f6dadde4372974dc1dffc5
-  data.tar.gz: 888067f9352c2a6bfe4493e7ea28770abc9df716c88ead2228b319ef7f07604884e977c1205e8726df61673ce0c79cf7f71d613296a6145d51af92ef72353ccf
+  metadata.gz: 89d14f78cd56cfcd7e48e3d56b94a2f5159ac5de5877872797b106307730d0d8c98702fd897ac5572f72d294fede4726e59cecfeab942e1fc29c1e15fe4184f3
+  data.tar.gz: d2c8ae8d702cebc1186c0f117abb542d1e80e84d4dc5e0ccac7ced97b278cd0762c0b70dfe2db84d968529aa235f12fbfd34b07252aa140d6bc2841cab372221

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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

data/README.md

@@ -220,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.
 
@@ -234,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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`
 
@@ -265,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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).
 
@@ -295,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 - the one option here that can destroy data outside the snapshot itself. See the [docs](https://rubydoc.info/gems/yobi/1.0.0/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.
 
@@ -319,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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")
@@ -339,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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`).
 
@@ -353,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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`
 
@@ -361,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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).
 
@@ -371,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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"`).
 
@@ -384,7 +385,7 @@ 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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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`, 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.).
 
@@ -396,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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).
 
@@ -410,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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.
 
@@ -420,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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`
 
@@ -430,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 - depends on a correct index, so run `#repair_index` first. See the [docs](https://rubydoc.info/gems/yobi/1.0.0/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`
 
@@ -446,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. `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.0.0/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`
 
@@ -471,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 [docs](https://rubydoc.info/gems/yobi/1.0.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.
+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
 
@@ -484,7 +485,7 @@ 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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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). On success, it also updates this same `Repository` instance's own `password:` to match, so it keeps working against the repository right afterward:
 
@@ -525,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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
 
@@ -548,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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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)
 
@@ -558,7 +559,7 @@ 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 [docs](https://rubydoc.info/gems/yobi/1.0.0/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
 
@@ -574,7 +575,7 @@ restic = Yobi::Restic.new(
 
 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`.
 
-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.0.0/Yobi/Restic).
+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
 
@@ -589,6 +590,47 @@ Both use the same settings. Changing `restic.limit_upload` later affects every r
 
 `--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
+```
+
+What an interrupted run leaves behind:
+
+- `#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
 
 Both `Repository#inspect` and `Restic#inspect` redact sensitive values, so a stray `pp`/`puts`/log call never prints a credential in plaintext:

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

data/lib/yobi/cancellation.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Yobi
+  # A cancellation token for a long-running Restic run.
+  #
+  # Pass one to Yobi::Repository#with_cancellation, then call #cancel! from
+  # another thread to stop whichever long-running method (#backup,
+  # #restore, #check, #prune, #forget, #copy) is running on the repository
+  # it returns:
+  #
+  #   token = Yobi::Cancellation.new
+  #   Thread.new { token.cancel! if user_clicked_cancel }
+  #   repo.with_cancellation(token).backup(source: "/data")
+  #   # => raises Yobi::Cancelled
+  #
+  # #cancel! sends the Restic process SIGINT rather than SIGKILL, so Restic
+  # removes its own repository lock on the way out and no +restic unlock+ is
+  # needed afterwards. An interrupted +backup+ writes no snapshot; data it had
+  # already uploaded is generally left unreferenced until the next +prune+
+  # rather than being reused, so cancelling does discard in-progress work.
+  #
+  # Safe to call #cancel! before the run starts (the run then raises without
+  # spawning Restic at all), after it has finished (a no-op), and from any
+  # thread. A token tracks one run at a time and is not reusable once
+  # cancelled.
+  class Cancellation
+    # The signal sent to Restic by #cancel! unless overridden.
+    DEFAULT_SIGNAL = "INT"
+
+    def initialize
+      @mutex = Mutex.new
+      @cancelled = false
+      @signal = DEFAULT_SIGNAL
+      @pid = nil
+    end
+
+    # True once #cancel! has been called.
+    def cancelled?
+      @mutex.synchronize { @cancelled }
+    end
+
+    # Requests cancellation, signalling the attached Restic process if one is
+    # currently running. Returns true the first time, false if this token was
+    # already cancelled. Idempotent and thread-safe.
+    #
+    # +signal:+ overrides the signal sent; the SIGINT default is what lets
+    # Restic clean up its lock, so override it only when you have a reason to.
+    def cancel!(signal: DEFAULT_SIGNAL)
+      pid = nil
+      @mutex.synchronize do
+        return false if @cancelled
+
+        @cancelled = true
+        @signal = signal
+        pid = @pid
+      end
+      signal_pid(pid, signal)
+      true
+    end
+
+    # Attaches a freshly spawned Restic process. If #cancel! already landed
+    # before the spawn, the process is signalled immediately. Called by
+    # Yobi::Restic; not part of the public API.
+    def attach(pid) # :nodoc:
+      cancelled, signal = @mutex.synchronize do
+        @pid = pid
+        [@cancelled, @signal]
+      end
+      signal_pid(pid, signal) if cancelled
+    end
+
+    # Detaches the current process once it has been reaped, so a later
+    # #cancel! can't signal a recycled PID. Called by Yobi::Restic; not part
+    # of the public API.
+    def detach # :nodoc:
+      @mutex.synchronize { @pid = nil }
+    end
+
+    def inspect
+      "#<#{self.class} cancelled=#{cancelled?}>"
+    end
+
+    private
+
+    # Errno::ESRCH means Restic already exited between the cancel and the
+    # signal, which is exactly the outcome cancelling wanted.
+    def signal_pid(pid, signal)
+      return if pid.nil?
+
+      begin
+        Process.kill(signal, pid)
+      rescue Errno::ESRCH
+        nil
+      end
+    end
+  end
+end

data/lib/yobi/errors.rb

@@ -41,6 +41,33 @@ module Yobi
     end
   end
 
+  # Raised when a run was stopped through a Yobi::Cancellation token.
+  #
+  # Distinct from Yobi::ResticExecutionError and its subclasses: the run did
+  # not fail, the caller stopped it on purpose. Rescue this to record a
+  # cancellation without treating it as a backup failure.
+  class Cancelled < Error
+    # The raw +{exit_code:, output:, argv:}+ result. +exit_code:+ and
+    # +output:+ are +nil+ when the token was already cancelled before
+    # Restic was spawned at all.
+    attr_reader :execution
+
+    def initialize(execution) # :nodoc:
+      @execution = execution
+      super("Restic run was cancelled")
+    end
+
+    # The argv of the run that was cancelled.
+    def argv
+      execution[:argv]
+    end
+
+    # True when the token was cancelled before Restic even started.
+    def before_start?
+      execution[:exit_code].nil?
+    end
+  end
+
   # Raised when the Restic binary itself can't be found or executed.
   class ResticNotFound < Error
     attr_reader :restic_path, :argv

data/lib/yobi/repository.rb

@@ -73,10 +73,28 @@ module Yobi
       "#<#{self.class} url=#{url.inspect} password=#{redacted_password.inspect} backend_credentials=#{redacted_backend_credentials.inspect}>"
     end
 
+    # Returns a Yobi::CancellableProxy wrapping this repository, exposing
+    # only its long-running methods (#backup, #restore, #check, #prune,
+    # #forget, #copy) with +token+ threaded through them, so #cancel! can
+    # stop whichever one is called:
+    #
+    #   token = Yobi::Cancellation.new
+    #   Thread.new { token.cancel! if user_clicked_cancel }
+    #   repo.with_cancellation(token).backup(source: "/data")
+    def with_cancellation(token)
+      CancellableProxy.new(self, token)
+    end
+
     private
 
+    # Set for the duration of one call by a Yobi::CancellableProxy, on the
+    # calling thread only.
+    def cancellation
+      Thread.current[:yobi_cancellation]
+    end
+
     def run_restic(argv, extra_env: {}, output: nil, &block)
-      @restic.run(argv, extra_env: env.merge(extra_env), output: output, &block)
+      @restic.run(argv, extra_env: env.merge(extra_env), output: output, cancellation: cancellation, &block)
     end
 
     def build_argv(*base)

data/lib/yobi/restic.rb

@@ -169,14 +169,22 @@ module Yobi
     #
     # Returns +{exit_code:, output:, argv:}+ on exit code 0 or 3.
     # Raises Yobi::RepositoryNotFound, Yobi::RepositoryLocked,
-    # Yobi::AuthenticationFailed, or Yobi::ResticCommandFailed otherwise.
-    def run(argv, extra_env: {}, skip_version_check: false, output: nil, &block) # :nodoc:
+    # Yobi::AuthenticationFailed, Yobi::Cancelled (exit code 130, e.g. from
+    # a Yobi::Cancellation token's #cancel!), or Yobi::ResticCommandFailed
+    # otherwise.
+    def run(argv, extra_env: {}, skip_version_check: false, output: nil, cancellation: nil, &block) # :nodoc:
       ensure_minimum_version! unless skip_version_check
+      raise Yobi::Cancelled.new({exit_code: nil, output: nil, argv: argv}) if cancellation&.cancelled?
+
+      # Only forwarded when a token was actually supplied, so the common
+      # short metadata commands keep their original call shape.
+      cancel_kwarg = cancellation ? {cancellation: cancellation} : {}
       execution = if output || block
-        execute_with_streaming(argv, extra_env, output: output, &block)
+        execute_with_streaming(argv, extra_env, output: output, **cancel_kwarg, &block)
       else
-        execute(argv, extra_env)
+        execute(argv, extra_env, **cancel_kwarg)
       end
+
       self.class.dispatch(execution)
     end
 
@@ -192,6 +200,8 @@ module Yobi
         raise Yobi::RepositoryLocked, execution
       when 12
         raise Yobi::AuthenticationFailed, execution
+      when 130
+        raise Yobi::Cancelled, execution
       else
         raise Yobi::ResticCommandFailed, execution
       end
@@ -281,21 +291,25 @@ module Yobi
       end
     end
 
-    def execute(argv, extra_env)
+    def execute(argv, extra_env, cancellation: nil)
       output = Yobi::ResticOutput.new
       pid = Process.spawn(env.merge(extra_env), restic_path, *argv, out: output.file, err: output.file)
+      cancellation&.attach(pid)
       _, status = Process.wait2(pid)
       {exit_code: status.exitstatus, output: output, argv: argv}
     rescue Errno::ENOENT
       output.file.close
       raise Yobi::ResticNotFound.new(restic_path: restic_path, argv: argv)
+    ensure
+      cancellation&.detach
     end
 
-    def execute_with_streaming(argv, extra_env, output: nil)
+    def execute_with_streaming(argv, extra_env, output: nil, cancellation: nil)
       output ||= Yobi::ResticOutput.new
 
       Open3.popen3(env.merge(extra_env), restic_path, *argv) do |stdin, stdout, stderr, wait_thr|
         stdin.close
+        cancellation&.attach(wait_thr.pid)
         readers = {stdout => :stdout, stderr => :stderr}
 
         until readers.empty?
@@ -317,6 +331,8 @@ module Yobi
     rescue Errno::ENOENT
       output.file.close
       raise Yobi::ResticNotFound.new(restic_path: restic_path, argv: argv)
+    ensure
+      cancellation&.detach
     end
   end
 

data/lib/yobi/version.rb

@@ -3,5 +3,5 @@
 # A Ruby library for the Restic backup program, wrapping the `restic` CLI in
 # plain Ruby objects instead of shelling out to flags and raw JSON by hand.
 module Yobi
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/yobi.rb

@@ -2,6 +2,7 @@
 
 require_relative "yobi/version"
 require_relative "yobi/fancy_hash"
+require_relative "yobi/cancellation"
 require_relative "yobi/errors"
 require_relative "yobi/argv_builder"
 require_relative "yobi/restic_output"
@@ -10,5 +11,6 @@ require_relative "yobi/mount_handle"
 require_relative "yobi/restic"
 require_relative "yobi/snapshot"
 require_relative "yobi/repository"
+require_relative "yobi/cancellable_proxy"
 
 Dir[File.join(__dir__, "yobi", "repository", "*.rb")].sort.each { |file| require_relative file }

data/sig/yobi.rbs

@@ -31,6 +31,32 @@ module Yobi
     def initialize: (installed_version: String, minimum_version: String) -> void
   end
 
+  class Cancellation
+    DEFAULT_SIGNAL: String
+
+    def initialize: () -> void
+
+    def cancelled?: () -> bool
+
+    def cancel!: (?signal: String) -> bool
+
+    def attach: (Integer pid) -> void
+
+    def detach: () -> void
+
+    def inspect: () -> String
+  end
+
+  class Cancelled < Error
+    attr_reader execution: cancelled_execution
+
+    def initialize: (cancelled_execution execution) -> void
+
+    def argv: () -> Array[String]
+
+    def before_start?: () -> bool
+  end
+
   class ResticNotFound < Error
     attr_reader restic_path: String
     attr_reader argv: Array[String]
@@ -39,6 +65,7 @@ module Yobi
   end
 
   type execution = { exit_code: Integer, output: ResticOutput, argv: Array[String] }
+  type cancelled_execution = { exit_code: Integer?, output: ResticOutput?, argv: Array[String] }
 
   class ResticExecutionError < Error
     attr_reader execution: execution
@@ -264,7 +291,7 @@ module Yobi
 
     def cache: (?cleanup: bool, ?max_age: String?, ?no_size: bool) -> true
 
-    def run: (Array[String] argv, ?extra_env: Hash[String, String], ?skip_version_check: bool, ?output: ResticOutput?) ?{ (untyped message) -> void } -> execution
+    def run: (Array[String] argv, ?extra_env: Hash[String, String], ?skip_version_check: bool, ?output: ResticOutput?, ?cancellation: Cancellation?) ?{ (untyped message) -> void } -> execution
 
     def self.dispatch: (execution execution) -> execution
 
@@ -305,6 +332,8 @@ module Yobi
 
     alias config cat_config
 
+    def with_cancellation: (Cancellation token) -> CancellableProxy
+
     def backup: (source: String | [:stdin_from_command, String | Array[String]] | [:stdin_from_command, String | Array[String], String],
       ?excludes: Array[String] | String, ?exclude_files: Array[String] | String,
       ?exclude_if_present: Array[String] | String, ?exclude_larger_than: String?,
@@ -418,7 +447,8 @@ module Yobi
       ?include_files: Array[String] | String, ?include_xattrs: Array[String] | String,
       ?paths: Array[String] | String, ?tags: Array[String] | String, ?delete: bool, ?dry_run: bool,
       ?overwrite: String | Symbol | nil, ?ownership_by_name: bool, ?sparse: bool, ?verbose: bool,
-      ?verify: bool) ?{ (RestoreStatus | RestoreVerboseStatus message) -> void } -> RestoreOutcome
+      ?verify: bool)
+      ?{ (RestoreStatus | RestoreVerboseStatus message) -> void } -> RestoreOutcome
 
     def rewrite: (?snapshot_ids: Array[String] | String, ?hosts: Array[String] | String,
       ?tags: Array[String] | String, ?paths: Array[String] | String, ?excludes: Array[String] | String,
@@ -441,6 +471,53 @@ module Yobi
     def unlock: (?remove_all: bool) -> true
   end
 
+  class CancellableProxy
+    def initialize: (Repository repository, Cancellation token) -> void
+
+    def backup: (source: String | [:stdin_from_command, String | Array[String]] | [:stdin_from_command, String | Array[String], String],
+      ?excludes: Array[String] | String, ?exclude_files: Array[String] | String,
+      ?exclude_if_present: Array[String] | String, ?exclude_larger_than: String?,
+      ?files_from: Array[String] | String, ?files_from_raw: Array[String] | String,
+      ?files_from_verbatim: Array[String] | String, ?iexcludes: Array[String] | String,
+      ?iexclude_files: Array[String] | String, ?tags: Array[String] | String, ?dry_run: bool,
+      ?exclude_caches: bool, ?exclude_cloud_files: bool, ?force: bool, ?group_by: String?,
+      ?host: String?, ?ignore_ctime: bool, ?ignore_inode: bool, ?no_scan: bool,
+      ?one_file_system: bool, ?parent: String?, ?read_concurrency: Integer?,
+      ?skip_if_unchanged: bool, ?time: String?, ?verbose: bool, ?with_atime: bool)
+      ?{ (BackupStatus | BackupError | BackupVerboseStatus | BackupSummary message) -> void } -> BackupOutcome
+
+    def restore: (snapshot_id: String, target: String, ?excludes: Array[String] | String,
+      ?exclude_files: Array[String] | String, ?exclude_xattrs: Array[String] | String,
+      ?hosts: Array[String] | String, ?iexcludes: Array[String] | String,
+      ?iexclude_files: Array[String] | String, ?iincludes: Array[String] | String,
+      ?iinclude_files: Array[String] | String, ?includes: Array[String] | String,
+      ?include_files: Array[String] | String, ?include_xattrs: Array[String] | String,
+      ?paths: Array[String] | String, ?tags: Array[String] | String, ?delete: bool, ?dry_run: bool,
+      ?overwrite: String | Symbol | nil, ?ownership_by_name: bool, ?sparse: bool, ?verbose: bool,
+      ?verify: bool)
+      ?{ (RestoreStatus | RestoreVerboseStatus message) -> void } -> RestoreOutcome
+
+    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 prune: (?dry_run: bool, ?max_repack_size: String?, ?max_unused: String?,
+      ?repack_cacheable_only: bool, ?repack_smaller_than: String?, ?repack_uncompressed: bool,
+      ?unsafe_recover_no_free_space: String?) -> true
+
+    def forget: (?keep_last: Integer?, ?keep_hourly: Integer?, ?keep_daily: Integer?, ?keep_weekly: Integer?,
+      ?keep_monthly: Integer?, ?keep_yearly: Integer?, ?keep_within: String?, ?keep_within_hourly: String?,
+      ?keep_within_daily: String?, ?keep_within_weekly: String?, ?keep_within_monthly: String?,
+      ?keep_within_yearly: String?, ?keep_tags: Array[String] | String, ?hosts: Array[String] | String,
+      ?tags: Array[String] | String, ?paths: Array[String] | String, ?compact: bool, ?group_by: String?,
+      ?dry_run: bool, ?prune: bool, ?unsafe_allow_remove_all: bool, ?max_unused: String?,
+      ?max_repack_size: String?, ?repack_cacheable_only: bool, ?repack_uncompressed: bool,
+      ?repack_smaller_than: String?) -> Array[ForgetGroup]
+
+    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
+  end
+
   module BackupMessageWrapper
     def self.call: (Hash[String, untyped] raw) -> (BackupStatus | BackupError | BackupVerboseStatus | BackupSummary | Hash[String, untyped])
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yobi
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Zia Perdana
@@ -22,6 +22,8 @@ files:
 - README.md
 - lib/yobi.rb
 - lib/yobi/argv_builder.rb
+- lib/yobi/cancellable_proxy.rb
+- lib/yobi/cancellation.rb
 - lib/yobi/errors.rb
 - lib/yobi/fancy_hash.rb
 - lib/yobi/io_handle.rb
@@ -62,7 +64,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/1.0.0
+  documentation_uri: https://rubydoc.info/gems/yobi/1.1.0
 rdoc_options: []
 require_paths:
 - lib