imap-backup 16.4.0 → 16.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ec15a683d70eadabab4271afcd2231c723344e79dde55fadeea091056201fc8
-  data.tar.gz: 946f1074220df2af38c92a5ff7f5dda8bcdcef3dc20f48d9f2c8206e29a8cd6e
+  metadata.gz: f3ffe8d1bd32587d59e12a514b005d68175244e2cb73a9d138dd3a5d273c785f
+  data.tar.gz: 62d6364641799f1ce20466affc34052f8614a2a2d5633f53a05b4cac31a4e0f3
 SHA512:
-  metadata.gz: 7c33112eb20f168c453f0cc52e86497c7a44459afa718ac12ff1ca71cf990d9566514598aae25fc22117fb30478db649bb76a1aff697d40dabb788cc54fa1508
-  data.tar.gz: ea2dd0c673c603c71708ba550cbdf98c218c51b8ff076ba031d40a7ae33f80ff830ada659b7cc300e8511cc3da207665e6f2114c231e985a0b716e2844f7fe7a
+  metadata.gz: f4fdd4254948ef5dd7fba17e3683aa13bf84a19a77ffd935bad3f830355d4bf0d14ff48c731be2542ce56332ed8b4903b1b7971a16e7e947f4406ba4473b4a44
+  data.tar.gz: 4ca3ca9bb9eda64a9b8b9a6cc0889e5815f446e2a798f762f1d55e228928e99988c186bdaad4dfd7d033cd21667de7d906ea3cbd1f11d947dc77d68f4bbd1090

data/README.md

@@ -25,102 +25,13 @@ The {file:CHANGELOG.md CHANGELOG} has a history of the changes to the program.
 * Restartable - calculate start point based on already downloaded messages
 * Standalone - do not rely on an email client or MTA
 
-# Repository
+# Development
 
-After cloning the repo, run the following command to get
-better `git blame` output:
-
-```sh
-git config --local blame.ignoreRevsFile .git-blame-ignore-revs
-```
+See the [development documentation](/docs/development.md).
 
 # Testing
 
-## Feature Specs
-
-Specs under `specs/features` are integration specs.
-Some of these specs run against two local IMAP servers
-controlled by Podman (or Docker) Compose.
-
-Start them before running the test suite
-
-```sh
-$ podman-compose -f dev/compose.yml up -d
-```
-
-or, with Docker
-
-```sh
-$ docker-compose -f dev/compose.yml up -d
-```
-
-Then, run all specs
-
-```sh
-$ rspec
-```
-
-To exclude container-based tests
-
-```sh
-$ rspec --tag ~container
-```
-
-To run **just** the feature specs
-
-```sh
-rspec spec/features/**/*_spec.rb
-```
-
-## Full Test Run
-
-The full test run includes RSpec specs **and** Rubocop checks
-
-```sh
-rake
-```
-
-# Test Debugging
-
-The feature specs are run 'out of process' via the Aruba gem.
-In order to see debugging output from the process,
-use `last_command_started.output`.
-
-# Older Rubies
-
-A Containerfile is available to allow testing with all available Ruby versions,
-see the README in the `dev` directory.
-
-# Performance Specs
-
-```sh
-PERFORMANCE=1 rspec --order=defined
-```
-
-Beware: the performance spec (just backup for now) takes a very
-long time to run, approximately 24 hours!
-
-# Access Docker imap server
-
-```ruby
-require "net/imap"
-require_relative "spec/features/support/30_email_server_helpers"
-
-include EmailServerHelpers
-
-test_connection = test_server_connection_parameters
-
-test_imap = Net::IMAP.new(test_connection[:server], test_connection[:connection_options])
-test_imap.login(test_connection[:username], test_connection[:password])
-
-message = "From: #{test_connection[:username]}\nSubject: Some Subject\n\nHello!\n"
-response = test_imap.append("INBOX", message, nil, nil)
-
-test_imap.examine("INBOX")
-uids = test_imap.uid_search(["ALL"]).sort
-
-fetch_data_items = test_imap.uid_fetch(uids, ["BODY[]"])
-```
+See the [testing documentation](/docs/testing.md).
 
 # Contributing
 

data/docs/development.md

@@ -0,0 +1,8 @@
+# Repository
+
+After cloning the repo, run the following command to get
+better `git blame` output:
+
+```sh
+git config --local blame.ignoreRevsFile .git-blame-ignore-revs
+```

data/docs/testing.md

@@ -0,0 +1,93 @@
+# Setup
+
+Specs under `spec/features` are integration specs.
+Some of these specs run against two local IMAP servers
+controlled by Podman (or Docker) Compose.
+
+Start them before running the test suite
+
+```sh
+$ podman-compose -f dev/compose.yml up -d
+```
+
+or, with Docker
+
+```sh
+$ docker-compose -f dev/compose.yml up -d
+```
+
+# Invocations
+
+Run all specs
+
+```sh
+$ rake spec
+```
+
+Run **just** the unit specs
+
+```sh
+$ rake spec_unit
+```
+
+Run **just** the feature specs
+
+```sh
+$ rake spec_feature
+```
+
+To exclude the slow container-based tests
+
+```sh
+$ rake spec_non_container
+```
+
+## Full Test Run
+
+The full test run includes RSpec specs **and** Rubocop checks
+
+```sh
+rake test
+```
+
+# Debugging
+
+The feature specs are run 'out of process' via the Aruba gem.
+In order to see debugging output from the process,
+use `last_command_started.output`.
+
+# Older Rubies
+
+A Containerfile is available to allow testing with all available Ruby versions,
+see the README in the `dev` directory.
+
+# Performance Specs
+
+```sh
+PERFORMANCE=1 rspec --order=defined
+```
+
+Beware: the performance spec (just backup for now) takes a very
+long time to run, approximately 24 hours!
+
+# Access Docker imap server
+
+```ruby
+require "net/imap"
+require_relative "spec/features/support/30_email_server_helpers"
+
+include EmailServerHelpers
+
+test_connection = test_server_connection_parameters
+
+test_imap = Net::IMAP.new(test_connection[:server], test_connection[:connection_options])
+test_imap.login(test_connection[:username], test_connection[:password])
+
+message = "From: #{test_connection[:username]}\nSubject: Some Subject\n\nHello!\n"
+response = test_imap.append("INBOX", message, nil, nil)
+
+test_imap.examine("INBOX")
+uids = test_imap.uid_search(["ALL"]).sort
+
+fetch_data_items = test_imap.uid_fetch(uids, ["BODY[]"])
+```

data/lib/imap/backup/account/backup.rb

@@ -11,6 +11,8 @@ module Imap::Backup
 
   # Carries out the backup of the configured folders of the account
   class Account::Backup
+    # @param account [Account] the account to back up
+    # @param refresh [Boolean] true to refresh folder metadata even if mirror is disabled
     def initialize(account:, refresh: false)
       @account = account
       @refresh = refresh

data/lib/imap/backup/account/backup_folders.rb

@@ -9,6 +9,8 @@ module Imap::Backup
   class Account::BackupFolders
     include Enumerable
 
+    # @param client [Client::AutomaticLoginWrapper] the IMAP client that lists folders
+    # @param account [Account] the account whose folders are being backed up
     def initialize(client:, account:)
       @client = client
       @account = account

data/lib/imap/backup/account/client_factory.rb

@@ -10,6 +10,7 @@ module Imap::Backup
 
   # Returns an IMAP client set up for the supplied account
   class Account::ClientFactory
+    # @param account [Account] the account whose credentials configure the client
     def initialize(account:)
       @account = account
     end

data/lib/imap/backup/account/folder.rb

@@ -23,6 +23,8 @@ module Imap::Backup
     # @return [String] the name of the folder
     attr_reader :name
 
+    # @param client [Client::Default] the IMAP client used to talk to the server
+    # @param name [String] the UTF-7 encoded folder name
     def initialize(client, name)
       @client = client
       @name = name

data/lib/imap/backup/account/folder_backup.rb

@@ -12,6 +12,9 @@ module Imap::Backup
 
   # Implements backup for a single folder
   class Account::FolderBackup
+    # @param account [Account] the account that owns the folder
+    # @param folder [Account::Folder] the online folder being backed up
+    # @param refresh [Boolean] true to refresh metadata regardless of mirror mode
     def initialize(account:, folder:, refresh: false)
       @account = account
       @folder = folder

data/lib/imap/backup/account/folder_ensurer.rb

@@ -8,6 +8,7 @@ module Imap::Backup
 
   # Handles creation of directories for backup storage
   class Account::FolderEnsurer
+    # @param account [Account] the account to check
     def initialize(account:)
       @account = account
     end

data/lib/imap/backup/account/folder_mapper.rb

@@ -11,6 +11,12 @@ module Imap::Backup
 
   # Implements a folder enumerator for backed-up accounts
   class Account::FolderMapper
+    # @param account [Account] the account whose local folders are being iterated
+    # @param destination [Account] the destination account
+    # @param destination_delimiter [String] the delimiter to use for destination folder names
+    # @param destination_prefix [String] a prefix applied to destination folder names
+    # @param source_delimiter [String] the delimiter used in the source account
+    # @param source_prefix [String] a prefix applied to source folder names
     def initialize(
       account:,
       destination:,

data/lib/imap/backup/account/local_only_folder_deleter.rb

@@ -10,6 +10,7 @@ module Imap::Backup
   # This is used in mirror mode, where local copies are only kept as long as they
   # exist on the server.
   class Account::LocalOnlyFolderDeleter
+    # @param account [Account] the account whose serialized folders are being pruned
     def initialize(account:)
       @account = account
     end

data/lib/imap/backup/account/locker.rb

@@ -9,6 +9,7 @@ module Imap::Backup
   class Account::Locker
     attr_reader :account
 
+    # @param account [Account] the account whose backup must be locked
     def initialize(account:)
       @account = account
     end
@@ -27,7 +28,11 @@ module Imap::Backup
         Account::FolderEnsurer.new(account: account).run
       end
 
-      lockfile.with_lock do
+      begin
+        lockfile.with_lock do
+          block.call
+        end
+      rescue Lockfile::ProcessStartTimeUnavailableError
         block.call
       end
     end

data/lib/imap/backup/account/restore.rb

@@ -9,6 +9,9 @@ module Imap::Backup
 
   # Restores all backed up folders to the server
   class Account::Restore
+    # @param account [Account] the account whose backups will be restored
+    # @param delimiter [String] the destination folder delimiter
+    # @param prefix [String] a prefix applied to restored folder names
     def initialize(account:, delimiter: "/", prefix: "")
       @account = account
       @destination_delimiter = delimiter

data/lib/imap/backup/account/serialized_folders.rb

@@ -13,6 +13,7 @@ module Imap::Backup
   class Account::SerializedFolders
     include Enumerable
 
+    # @param account [Account] the account whose serialized folders are iterated
     def initialize(account:)
       @account = account
     end

data/lib/imap/backup/account.rb

@@ -65,6 +65,25 @@ module Imap::Backup
     # @return [String] one of "active" (the default), "archived", or "offline"
     attr_reader :status
 
+    # @param options [Hash] Account attributes
+    # @option opts [String] :username the username of the account (usually the same as the email
+    #   address)
+    # @option opts [String] :password the password of the account
+    # @option opts [String] :local_path the path where backups will be saved
+    # @option opts [Array<String>] :folders (nil) the list of folders that have been configured for
+    #   the Account
+    # @option opts [Boolean] :folder_blacklist (false) whether the folders attribute is a blacklist
+    # @option opts [Boolean] :mirror_mode (false) whether to run in mirror mode
+    # @option opts [String] :server the address of the IMAP server
+    # @option opts [Hash] :connection_options (nil) additional connection options for the IMAP
+    #   server
+    # @option opts [String] :download_strategy (nil) the name of the download strategy to adopt
+    #   during backups
+    # @option opts [Integer] :multi_fetch_size (nil) the number of emails to fetch from the IMAP
+    #   server at a time
+    # @option opts [Boolean] :reset_seen_flags_after_fetch (false) whether to reset seen flags after
+    #   fetching messages
+    # @option opts [String] :status ("active") the status of the account
     def initialize(options)
       check_options!(options)
       @username = options[:username]
@@ -131,19 +150,19 @@ module Imap::Backup
     # @return [Hash] all Account data for serialization
     def to_h
       h = {
-        username: @username,
-        password: @password,
+        username: username,
+        password: password,
         status: status
       }
-      h[:local_path] = @local_path if @local_path
-      h[:folders] = @folders if @folders
-      h[:folder_blacklist] = true if @folder_blacklist
-      h[:mirror_mode] = true if @mirror_mode
-      h[:server] = @server if @server
-      h[:connection_options] = @connection_options if connection_options
+      h[:local_path] = local_path if local_path
+      h[:folders] = folders if folders
+      h[:folder_blacklist] = true if folder_blacklist
+      h[:mirror_mode] = true if mirror_mode
+      h[:server] = server if server
+      h[:connection_options] = connection_options if connection_options
       h[:multi_fetch_size] = multi_fetch_size
-      if @reset_seen_flags_after_fetch
-        h[:reset_seen_flags_after_fetch] = @reset_seen_flags_after_fetch
+      if reset_seen_flags_after_fetch
+        h[:reset_seen_flags_after_fetch] = reset_seen_flags_after_fetch
       end
       h
     end
@@ -216,12 +235,11 @@ module Imap::Backup
     def connection_options=(value)
       # Ensure we've loaded the connection_options
       connection_options
-      parsed =
-        if value == ""
-          nil
-        else
-          JSON.parse(value, symbolize_names: true)
-        end
+      parsed = if value == ""
+                 nil
+               else
+                 JSON.parse(value, symbolize_names: true)
+               end
       update(:connection_options, parsed)
     end
 

data/lib/imap/backup/cli/backup.rb

@@ -15,6 +15,10 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
+    # @option opts [Boolean] :refresh (false) whether to force refresh of folder metadata
     def initialize(options)
       super([])
       @options = options

data/lib/imap/backup/cli/local/check.rb

@@ -14,6 +14,11 @@ module Imap::Backup
   class CLI::Local::Check
     include CLI::Helpers
 
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
+    # @option opts [Boolean] :delete_corrupt (false) whether to delete corrupt folders
+    # @option opts [String] :format ("text") the output format, either "text" or "json"
     def initialize(options)
       @options = options
     end

data/lib/imap/backup/cli/options.rb

@@ -70,6 +70,7 @@ module Imap::Backup
       }
     ].freeze
 
+    # @param base [Thor] the command class receiving the options
     def initialize(base:)
       @base = base
     end

data/lib/imap/backup/cli/restore.rb

@@ -14,6 +14,13 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
+    # @param email [String, nil] optional email address identifying the account to restore
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
+    # @option opts [Array<String>] :accounts (nil) the accounts to restore
+    # @option opts [String] :delimiter ("/") the destination folder delimiter
+    # @option opts [String] :prefix ("") a prefix applied to restored folder names
     def initialize(email = nil, options)
       super([])
       @email = email
@@ -30,9 +37,6 @@ module Imap::Backup
         when email && !options.key?(:accounts)
           account = account(config, email)
           restore(account, **restore_options)
-        when !email && !options.key?(:accounts)
-          Logger.logger.info "Calling restore without an EMAIL parameter is deprecated"
-          config.accounts.each { |a| restore(a) }
         when email && options.key?(:accounts)
           raise "Missing EMAIL parameter"
         when !email && options.key?(:accounts)
@@ -41,6 +45,9 @@ module Imap::Backup
             "please pass a single EMAIL parameter"
           )
           requested_accounts(config).each { |a| restore(a) }
+        else
+          Logger.logger.info "Calling restore without an EMAIL parameter is deprecated"
+          config.accounts.each { |a| restore(a) }
         end
       end
     end

data/lib/imap/backup/cli/setup.rb

@@ -13,6 +13,9 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
     def initialize(options)
       super([])
       @options = options

data/lib/imap/backup/cli/single/backup.rb

@@ -12,6 +12,26 @@ module Imap::Backup
 
   # Runs a backup without relying on existing configuration
   class CLI::Single::Backup
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
+    # @option opts [String] :email the email address identifying the account to backup
+    # @option opts [String] :password (nil) the password for the account
+    # @option opts [String] :password_environment_variable (nil) the name of an environment variable
+    #   containing the password
+    # @option opts [String] :password_file (nil) the path to a file containing the password
+    # @option opts [String] :server the IMAP server address
+    # @option opts [String] :download_strategy (nil) the download strategy to use, either "delay"
+    #   or "direct"
+    # @option opts [Boolean] :folder_blacklist (false) whether to treat folder list as a blacklist
+    # @option opts [Array<String>] :folder ([]) the folders to backup
+    # @option opts [String] :path (nil) the local path to store the backup
+    # @option opts [Boolean] :mirror (false) whether to run in mirror mode
+    # @option opts [Integer] :multi_fetch_size (nil) the number of messages to fetch in a single
+    #   operation
+    # @option opts [Boolean] :refresh (false) whether to force refresh of folder metadata
+    # @option opts [Boolean] :reset_seen_flags_after_fetch (false) whether to reset seen flags
+    #   after fetching messages
     def initialize(options)
       @options = options
       @password = nil

data/lib/imap/backup/cli/stats.rb

@@ -1,14 +1,24 @@
+require "thor"
+
 require "imap/backup/account/backup_folders"
+require "imap/backup/cli/helpers"
 require "imap/backup/serializer"
 
 module Imap; end
 
 module Imap::Backup
+  class CLI < Thor; end
+
   # Prints various statistics about an account and its backup
   class CLI::Stats < Thor
     include Thor::Actions
     include CLI::Helpers
 
+    # @param email [String] the email address identifying the account to inspect
+    # @param options [Hash] CLI options controlling output
+    # @option opts [String] :config (nil) the path to the configuration file
+    # @option opts [String] :erb_configuration (nil) the path to the ERB configuration file
+    # @option opts [String] :format ("text") the output format, either "text" or "json"
     def initialize(email, options)
       super([])
       @email = email

data/lib/imap/backup/cli/transfer.rb

@@ -16,6 +16,9 @@ module Imap::Backup
     # The possible values for the action parameter
     ACTIONS = %i(copy migrate mirror).freeze
 
+    # @param action [Symbol] one of ACTIONS describing the transfer mode
+    # @param source_email [String] the email of the source account
+    # @param destination_email [String] the email of the destination account
     def initialize(action, source_email, destination_email, options)
       @action = action
       @source_email = source_email

data/lib/imap/backup/client/automatic_login_wrapper.rb

@@ -15,6 +15,7 @@ module Imap::Backup
     # @return [Client]
     attr_reader :client
 
+    # @param client [Client::Default] the client to wrap and lazily log in
     def initialize(client:)
       @client = client
       @login_called = false

data/lib/imap/backup/client/default.rb

@@ -19,6 +19,7 @@ module Imap::Backup
       responses uid_fetch uid_search uid_store
     )
 
+    # @param account [Account] the account whose server is accessed
     def initialize(account)
       @account = account
       @state = nil

data/lib/imap/backup/configuration.rb

@@ -32,6 +32,7 @@ module Imap::Backup
       File.exist?(path || default_pathname)
     end
 
+    # @param path [String, nil] optional path to the configuration file
     def initialize(path: nil)
       @pathname = path || self.class.default_pathname
       @download_strategy = nil

data/lib/imap/backup/downloader.rb

@@ -8,6 +8,10 @@ module Imap::Backup
     # @private
     class MultiFetchFailedError < StandardError; end
 
+    # @param folder [Account::Folder] the remote folder to download from
+    # @param serializer [Serializer] the local serializer that stores messages
+    # @param multi_fetch_size [Integer] how many messages to fetch per batch
+    # @param reset_seen_flags_after_fetch [Boolean] true to restore unseen flags after fetch
     def initialize(folder, serializer, multi_fetch_size: 1, reset_seen_flags_after_fetch: false)
       @folder = folder
       @serializer = serializer

data/lib/imap/backup/email/mboxrd/message.rb

@@ -35,6 +35,7 @@ module Imap::Backup
       # @return [String] the original message body
       attr_reader :supplied_body
 
+      # @param supplied_body [String] the original RFC 2822 message text
       def initialize(supplied_body)
         @supplied_body = supplied_body.clone
       end

data/lib/imap/backup/file_mode.rb

@@ -3,6 +3,7 @@ module Imap; end
 module Imap::Backup
   # Accesses a file's access permissions
   class FileMode
+    # @param filename [String] the file whose permissions will be checked
     def initialize(filename:)
       @filename = filename
     end

data/lib/imap/backup/flag_refresher.rb

@@ -6,6 +6,8 @@ module Imap::Backup
     # The number of messages to process at a time
     CHUNK_SIZE = 100
 
+    # @param folder [Account::Folder] the remote folder whose flags are refreshed
+    # @param serializer [Serializer] the local serializer providing stored UIDs
     def initialize(folder, serializer)
       @folder = folder
       @serializer = serializer

data/lib/imap/backup/local_only_message_deleter.rb

@@ -5,6 +5,8 @@ module Imap; end
 module Imap::Backup
   # Deletes locally backed-up emails that are no longer on the server
   class LocalOnlyMessageDeleter
+    # @param folder [Account::Folder] the remote folder used to detect missing UIDs
+    # @param serializer [Serializer] the local serializer that may contain stale messages
     def initialize(folder, serializer)
       @folder = folder
       @serializer = serializer

data/lib/imap/backup/lockfile.rb

@@ -7,6 +7,7 @@ module Imap::Backup
   class Lockfile
     # An error that is thrown if a lockfile already exists
     class LockfileExistsError < StandardError; end
+    class ProcessStartTimeUnavailableError < StandardError; end
 
     attr_reader :path
 
@@ -53,7 +54,9 @@ module Imap::Backup
 
       return true if proc_table_entry.nil?
 
-      proc_table_entry.starttime != starttime
+      other_starttime = starttime(proc_table_entry)
+
+      other_starttime != starttime
     end
 
     private
@@ -62,9 +65,11 @@ module Imap::Backup
       pid = Process.pid
       proc_table_entry = Sys::ProcTable.ps(pid: pid)
 
-      raise "Unable to get process info for PID #{pid}" if proc_table_entry.nil?
+      if proc_table_entry.nil?
+        raise ProcessStartTimeUnavailableError, "Unable to get process info for PID #{pid}"
+      end
 
-      starttime = proc_table_entry.starttime
+      starttime = starttime(proc_table_entry)
 
       data = {
         pid: pid,
@@ -74,5 +79,16 @@ module Imap::Backup
       json_data = JSON.generate(data)
       File.write(path, json_data)
     end
+
+    def starttime(proc_table_entry)
+      case
+      when proc_table_entry.respond_to?(:starttime)
+        proc_table_entry.starttime
+      when proc_table_entry.respond_to?(:start_tvsec)
+        proc_table_entry.start_tvsec
+      else
+        raise ProcessStartTimeUnavailableError, "Proctable entry structure unknown"
+      end
+    end
   end
 end

data/lib/imap/backup/logger.rb

@@ -49,7 +49,7 @@ module Imap::Backup
     end
 
     # Wraps a block, filtering output to standard error,
-    # hidng passwords and outputs the results to standard out
+    # hiding passwords, and outputs the results to standard out
     # @return [void]
     def self.sanitize_stderr(&block)
       sanitizer = Text::Sanitizer.new($stdout)

data/lib/imap/backup/migrator.rb

@@ -5,6 +5,9 @@ module Imap; end
 module Imap::Backup
   # Copies a folder of backed-up emails to an online folder
   class Migrator
+    # @param serializer [Serializer] the local folder to migrate
+    # @param folder [Account::Folder] the destination folder on the server
+    # @param reset [Boolean] true to clear the destination before uploading
     def initialize(serializer, folder, reset: false)
       @folder = folder
       @reset = reset

data/lib/imap/backup/mirror/map.rb

@@ -7,6 +7,8 @@ module Imap::Backup
 
   # Keeps track of the mapping between source and destination UIDs
   class Mirror::Map
+    # @param pathname [String] the path to the on-disk UID map
+    # @param destination [String] the destination account identifier
     def initialize(pathname:, destination:)
       @pathname = pathname
       @destination = destination
@@ -18,7 +20,6 @@ module Imap::Backup
     end
 
     # @return [Boolean] whether the supplied values match the existing
-    #  UID validity values
     def check_uid_validities(source:, destination:)
       store
       return false if source != source_uid_validity

data/lib/imap/backup/mirror.rb

@@ -5,6 +5,9 @@ module Imap; end
 module Imap::Backup
   # Synchronises a folder between a source and destination
   class Mirror
+    # @param serializer [Serializer] the source of backed-up messages
+    # @param folder [Account::Folder] the destination folder to mirror into
+    # @param reset [Boolean] true to delete destination-only messages first
     def initialize(serializer, folder, reset: false)
       @serializer = serializer
       @folder = folder

data/lib/imap/backup/serializer/message.rb

@@ -12,7 +12,7 @@ module Imap::Backup
     # @return [Array[Symbol]] the message's flags
     attr_accessor :flags
     # @return [Integer] the length of the message (as stored on disk)
-    attr_reader :length
+    attr_accessor :length
     # @return [Integer] the start of the message inside the mailbox file
     attr_reader :offset
     # @return [Integer] the message's UID

data/lib/imap/backup/version.rb

@@ -6,7 +6,7 @@ module Imap::Backup
   # @private
   MINOR    = 4
   # @private
-  REVISION = 0
+  REVISION = 1
   # @private
   PRE      = nil
   # The application version

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 16.4.0
+  version: 16.4.1
 platform: ruby
 authors:
 - Joe Yates
@@ -175,8 +175,10 @@ files:
 - README.md
 - bin/imap-backup
 - docs/delimiters-and-prefixes.md
+- docs/development.md
 - docs/documentation.md
 - docs/performance.md
+- docs/testing.md
 - imap-backup.gemspec
 - lib/imap/backup/account.rb
 - lib/imap/backup/account/backup.rb
@@ -277,7 +279,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Backup GMail (or other IMAP) accounts to disk
 test_files: []