yobi 0.3.1 → 1.1.0

data/lib/yobi/restic_output.rb

@@ -4,21 +4,11 @@ require "json"
 require "tempfile"
 
 module Yobi
-  # Wraps the tempfile a repository operation's stdout+stderr are both
-  # written to, with random access so a caller asking only for the last
-  # line (see {#last_line}) doesn't have to read the entire output.
-  #
-  # @private
-  class ResticOutput
-    # Default read window size, in bytes, for {#last_line}.
+  class ResticOutput # :nodoc:
     DEFAULT_TAIL_CHUNK_SIZE = 4096
 
-    # @return [File] a fresh, already-unlinked tempfile of its own
     attr_reader :file
 
-    # @param tail_chunk_size [Integer] read window size for {#last_line}
-    # @param transform [Proc, nil] used by {#write_and_parse} during a streaming run to transform
-    #   each message, and as {#messages}' default transform afterward, when no explicit one is given
     def initialize(tail_chunk_size: DEFAULT_TAIL_CHUNK_SIZE, transform: nil)
       @file = Tempfile.new("yobi-restic-output")
       @file.unlink
@@ -28,25 +18,15 @@ module Yobi
       @stderr_offsets = []
     end
 
-    # Byte offsets of every line, grouped by message_type. Built once and
-    # memoized.
-    #
-    # @return [Hash{String => Array<Integer>}]
     def index
       @index ||= build_index
     end
 
-    # @param offset [Integer] a byte offset, as recorded by {#index}
-    # @return [String] the line starting at that offset
     def read_line_at(offset)
       @file.seek(offset)
       @file.gets
     end
 
-    # The last non-blank line, found by seeking backward from the end of
-    # the file.
-    #
-    # @return [String, nil]
     def last_line
       size = @file.size
       return nil if size.zero?
@@ -66,8 +46,6 @@ module Yobi
       end
     end
 
-    # @yieldparam line [String]
-    # @return [Enumerator] if no block is given
     def each_line(&block)
       return enum_for(:each_line) unless block_given?
 
@@ -75,17 +53,6 @@ module Yobi
       @file.each_line(&block)
     end
 
-    # Every message recorded in {#index}, restricted to one +message_type+
-    # if given, in file order. Without an explicit transform block, uses
-    # the +transform:+ given to {#initialize} (if any); with neither, just
-    # yields/returns the raw parsed Hash. Whenever a transform (explicit
-    # or the stored one) applies, wraps the result in a {LazyList}
-    # instead of yielding.
-    #
-    # @param message_type [String, nil] every message, if omitted
-    # @yieldparam message [Hash] the raw parsed message, to transform
-    # @return [Yobi::ResticOutput::LazyList] if a transform block (or a stored transform) applies
-    # @return [Enumerator] of raw Hashes, otherwise
     def messages(message_type = nil, &transform)
       transform ||= @transform
       return raw_messages(message_type) unless transform
@@ -94,27 +61,12 @@ module Yobi
       LazyList.new(self, offsets, transform)
     end
 
-    # Every line known to have arrived on stderr rather than stdout during
-    # a streaming run (see {#write_and_parse}), in file order.
-    #
-    # @yieldparam line [String]
-    # @return [Enumerator] if no block is given
     def stderr_lines
       return enum_for(:stderr_lines) unless block_given?
 
       @stderr_offsets.each { |offset| yield read_line_at(offset) }
     end
 
-    # Called once per line read from a live streaming run's stdout/stderr.
-    # Writes it to the file, parses it, and - if it's a JSON message -
-    # indexes it by message_type and returns it transformed via the
-    # +transform:+ given to {#initialize} (or the raw parsed Hash, if none
-    # was given). A non-JSON line's offset is recorded in {#stderr_lines}
-    # instead, if +origin+ is +:stderr+; either way, returns nil.
-    #
-    # @param line [String]
-    # @param origin [:stdout, :stderr]
-    # @return [Object, nil]
     def write_and_parse(line, origin)
       offset = @file.pos
       @file.write(line)
@@ -134,13 +86,11 @@ module Yobi
       end
     end
 
-    # @return [String] the full captured output
     def to_s
       @file.rewind
       @file.read
     end
 
-    # @return [String]
     def inspect
       "#<#{self.class} #{@file.size} bytes>"
     end
@@ -179,32 +129,17 @@ module Yobi
       index
     end
 
-    # A lazily-transformed view over a set of {#index} offsets, printing
-    # like a plain Array (bounded to a preview, unlike one). Returned by
-    # {ResticOutput#messages} when given a transform block.
-    # #inspect/#pretty_print's preview is memoized, and #each reuses it
-    # rather than re-reading/re-transforming those same offsets again
-    # when the caller iterates the whole thing.
-    #
-    # @private
-    class LazyList
+    class LazyList # :nodoc:
       include Enumerable
 
-      # Items #inspect/#pretty_print show before truncating with "...".
-      # One louder than ActiveRecord::Relation#inspect's own preview size.
       INSPECT_PREVIEW_SIZE = 11
 
-      # @param output [Yobi::ResticOutput]
-      # @param offsets [Array<Integer>]
-      # @param transform [Proc] applied to each offset's raw parsed Hash
       def initialize(output, offsets, transform)
         @output = output
         @offsets = offsets
         @transform = transform
       end
 
-      # @yieldparam item [Object]
-      # @return [Enumerator] if no block is given
       def each
         return enum_for(:each) unless block_given?
 
@@ -212,23 +147,17 @@ module Yobi
         @offsets[preview.size..].each { |offset| yield transform_at(offset) }
       end
 
-      # The number of messages, known upfront from {#index} - unlike
-      # +Enumerable#count+, doesn't read/transform a single one to answer.
-      #
-      # @return [Integer]
       def size
         @offsets.size
       end
       alias_method :length, :size
 
-      # @return [String]
       def inspect
         shown = preview.first(INSPECT_PREVIEW_SIZE).map(&:inspect).join(", ")
         shown += ", ..." if preview.size > INSPECT_PREVIEW_SIZE
         "[#{shown}]"
       end
 
-      # @return [void]
       def pretty_print(q)
         q.group(1, "[", "]") do
           q.seplist(preview.first(INSPECT_PREVIEW_SIZE)) { |item| q.pp item }
@@ -238,7 +167,6 @@ module Yobi
 
       private
 
-      # @return [Array<Object>]
       def preview
         @preview ||= @offsets.first(INSPECT_PREVIEW_SIZE + 1).map { |offset| transform_at(offset) }
       end

data/lib/yobi/snapshot.rb

@@ -3,120 +3,108 @@
 require "time"
 
 module Yobi
-  # One snapshot, as Restic reports it. Shared across {Yobi::Repository#snapshots},
-  # {Yobi::Repository#ls}, and {Yobi::Repository#forget}'s keep/remove entries.
+  # One snapshot, as Restic reports it. Shared across Yobi::Repository#snapshots,
+  # Yobi::Repository#ls, and Yobi::Repository#forget's keep/remove entries.
   class Snapshot < Yobi::FancyHash
-    # @return [String]
+    # Full snapshot ID (64-char hex).
     def id
       self["id"]
     end
 
-    # @return [String]
+    # First 8 chars of #id.
     def short_id
       self["short_id"]
     end
 
-    # @return [Time]
+    # When the snapshot was created.
     def time
       @time ||= Time.parse(self["time"])
     end
 
-    # @return [String]
+    # Hostname recorded on the snapshot.
     def host
       self["hostname"]
     end
 
-    # @return [Array<String>]
+    # Tags recorded on the snapshot.
     def tags
       @tags ||= self["tags"] || []
     end
 
-    # @return [Array<String>]
+    # Paths backed up in the snapshot.
     def paths
       self["paths"]
     end
 
-    # @return [String, nil]
+    # Parent snapshot's #id, if any.
     def parent_id
       self["parent"]
     end
 
-    # @return [Yobi::SnapshotSummary]
+    # A Yobi::SnapshotSummary of the snapshot's stats at creation time.
     def summary
       @summary ||= SnapshotSummary.new(self["summary"] || {})
     end
   end
 
-  # The `"summary"` field of a {Yobi::Snapshot}, the stats recorded when it
-  # was created.
-  # https://restic.readthedocs.io/en/stable/075_scripting.html#snapshotsummary-object
+  # The +"summary"+ field of a Yobi::Snapshot, the stats recorded when it
+  # was created. See
+  # https://restic.readthedocs.io/en/stable/075_scripting.html#snapshotsummary-object.
   class SnapshotSummary < Yobi::FancyHash
-    # @return [Time, nil]
+    # When the backup started.
     def backup_start
       @backup_start ||= Time.parse(self["backup_start"]) if self["backup_start"]
     end
 
-    # @return [Time, nil]
+    # When the backup finished.
     def backup_end
       @backup_end ||= Time.parse(self["backup_end"]) if self["backup_end"]
     end
 
-    # @return [Integer]
     def files_new
       self["files_new"] || 0
     end
 
-    # @return [Integer]
     def files_changed
       self["files_changed"] || 0
     end
 
-    # @return [Integer]
     def files_unmodified
       self["files_unmodified"] || 0
     end
 
-    # @return [Integer]
     def dirs_new
       self["dirs_new"] || 0
     end
 
-    # @return [Integer]
     def dirs_changed
       self["dirs_changed"] || 0
     end
 
-    # @return [Integer]
     def dirs_unmodified
       self["dirs_unmodified"] || 0
     end
 
-    # @return [Integer]
     def data_blobs
       self["data_blobs"] || 0
     end
 
-    # @return [Integer]
     def tree_blobs
       self["tree_blobs"] || 0
     end
 
-    # @return [Integer]
     def data_added
       self["data_added"] || 0
     end
 
-    # @return [Integer]
     def data_added_packed
       self["data_added_packed"] || 0
     end
 
-    # @return [Integer]
     def total_files_processed
       self["total_files_processed"] || 0
     end
 
-    # @return [Integer]
     def total_bytes_processed
       self["total_bytes_processed"] || 0
     end

data/lib/yobi/version.rb

@@ -3,6 +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
-  # @return [String]
-  VERSION = "0.3.1"
+  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
@@ -227,7 +254,7 @@ module Yobi
     MINIMUM_VERSION: Gem::Version
     ALLOWED_ENV_VARS: Set[String]
 
-    attr_reader restic_path: String
+    attr_accessor restic_path: String
     attr_accessor cache_dir: String?
     attr_accessor compression: String?
     attr_accessor pack_size: Integer?
@@ -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
 
@@ -287,9 +314,9 @@ module Yobi
   end
 
   class Repository
-    attr_reader url: String
-    attr_reader password: password
-    attr_reader backend_credentials: backend_credentials
+    attr_accessor url: String
+    attr_accessor password: password
+    attr_accessor backend_credentials: backend_credentials
 
     def initialize: (url: String, password: password, ?backend_credentials: backend_credentials, ?restic: restic_or_path) -> void
 
@@ -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: 0.3.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Zia Perdana
@@ -16,11 +16,14 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".ruby-version"
 - CHANGELOG.md
 - LICENSE.txt
 - 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
@@ -61,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/0.3.1
+  documentation_uri: https://rubydoc.info/gems/yobi/1.1.0
 rdoc_options: []
 require_paths:
 - lib