imap-backup 14.4.4 → 14.5.0

data/lib/imap/backup/account.rb

@@ -14,10 +14,9 @@ module Imap::Backup
     # The username of the account (usually the same as the email address)
     # @return [String]
     attr_reader :username
-    # The password of the Account
+    # @return [String] password of the Account
     attr_reader :password
-    # The path where backups will be saved
-    # @return [String]
+    # @return [String] the path where backups will be saved
     attr_reader :local_path
     # @overload folders
     #   The list of folders that have been configured for the Account
@@ -38,13 +37,11 @@ module Imap::Backup
     attr_reader :folder_blacklist
     # Should all emails be backed up progressively, or should emails
     # which are deleted from the server be deleted locally?
+    # @return [Boolean]
     attr_reader :mirror_mode
     # The address of the IMAP server
     # @return [String]
     attr_reader :server
-    # Extra options to be passed to the IMAP server when connecting
-    # @return [Hash, void]
-    attr_reader :connection_options
     # The name of the download strategy to adopt during backups
     # @return [String]
     attr_accessor :download_strategy
@@ -61,18 +58,17 @@ module Imap::Backup
     # mark messages as '\Seen' when accessed).
     # @return [Boolean]
     attr_reader :reset_seen_flags_after_fetch
-    # Tracks changes to the Account's attributes
-    attr_reader :changes
 
     def initialize(options)
       @username = options[:username]
       @password = options[:password]
       @local_path = options[:local_path]
       @folders = options[:folders]
-      @folder_blacklist = options[:folder_blacklist]
-      @mirror_mode = options[:mirror_mode]
+      @folder_blacklist = options[:folder_blacklist] || false
+      @mirror_mode = options[:mirror_mode] || false
       @server = options[:server]
-      @connection_options = options[:connection_options]
+      @connection_options = nil
+      @supplied_connection_options = options[:connection_options]
       @download_strategy = options[:download_strategy]
       @multi_fetch_size_orignal = options[:multi_fetch_size]
       @reset_seen_flags_after_fetch = options[:reset_seen_flags_after_fetch]
@@ -123,6 +119,7 @@ module Imap::Backup
     end
 
     # Resets the store of changes, indicating that the current state is the saved state
+    # @return [void]
     def clear_changes
       @changes = {}
     end
@@ -134,16 +131,12 @@ module Imap::Backup
       @marked_for_deletion = true
     end
 
-    # Indicates whether the account has been flagged for deletion during setup
-    #
-    # @return [Boolean]
+    # @return [Boolean] whether the account has been flagged for deletion during setup
     def marked_for_deletion?
       @marked_for_deletion
     end
 
-    # Returns all Account data for serialization
-    #
-    # @return [Hash]
+    # @return [Hash] all Account data for serialization
     def to_h
       h = {username: @username, password: @password}
       h[:local_path] = @local_path if @local_path
@@ -151,7 +144,7 @@ module Imap::Backup
       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[: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
@@ -180,25 +173,45 @@ module Imap::Backup
       update(:local_path, value)
     end
 
+    # @raise [RuntimeError] if the supplied value is not an Array
+    # @return [void]
     def folders=(value)
       raise "folders must be an Array" if !value.is_a?(Array)
 
       update(:folders, value)
     end
 
+    # @return [void]
     def folder_blacklist=(value)
       update(:folder_blacklist, value)
     end
 
+    # @return [void]
     def mirror_mode=(value)
       update(:mirror_mode, value)
     end
 
+    # @return [void]
     def server=(value)
       update(:server, value)
     end
 
+    # Extra options to be passed to the IMAP server when connecting
+    # @return [Hash, void]
+    def connection_options
+      @connection_options ||=
+        case @supplied_connection_options
+        when String
+          JSON.parse(@supplied_connection_options, symbolize_names: true)
+        else
+          @supplied_connection_options
+        end
+    end
+
+    # @return [void]
     def connection_options=(value)
+      # Ensure we've loaded the connection_options
+      connection_options
       parsed =
         if value == ""
           nil
@@ -232,12 +245,15 @@ module Imap::Backup
       update(:multi_fetch_size, parsed)
     end
 
+    # @return [void]
     def reset_seen_flags_after_fetch=(value)
       update(:reset_seen_flags_after_fetch, value)
     end
 
     private
 
+    attr_reader :changes
+
     def update(field, value)
       key = :"@#{field}"
       if changes[field]

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

@@ -10,6 +10,7 @@ module Imap; end
 module Imap::Backup
   class CLI < Thor; end
 
+  # Runs backups of configured accounts
   class CLI::Backup < Thor
     include Thor::Actions
     include CLI::Helpers
@@ -19,6 +20,8 @@ module Imap::Backup
       @options = options
     end
 
+    # @!method run
+    #   @return [void]
     no_commands do
       def run
         config = load_config(**options)

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

@@ -9,6 +9,7 @@ module Imap; end
 module Imap::Backup
   class CLI < Thor; end
 
+  # Implements a folder enumerator for backed-up accounts
   class CLI::FolderEnumerator
     def initialize(
       destination:,
@@ -26,6 +27,11 @@ module Imap::Backup
       @source_prefix = source_prefix
     end
 
+    # Enumerates backed-up folders
+    # When called without a block, returns an Enumerator
+    # @yieldparam serializer [Serializer] the folder's serializer
+    # @yieldparam folder [Account::Folder] the online folder
+    # @return [Enumerator, void]
     def each
       return enum_for(:each) if !block_given?
 

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

@@ -8,6 +8,7 @@ module Imap; end
 module Imap::Backup
   class CLI < Thor; end
 
+  # Provides helper methods for CLI classes
   module CLI::Helpers
     def self.included(base)
       base.class_eval do
@@ -73,6 +74,10 @@ module Imap::Backup
       end
     end
 
+    # Processes command-line parameters
+    # @return [Hash] the supplied command-line parameters with
+    #   with hyphens in keys replaced by underscores
+    #   and the keys converted to Symbols
     def options
       @symbolized_options ||= # rubocop:disable Naming/MemoizedInstanceVariableName
         begin
@@ -89,6 +94,9 @@ module Imap::Backup
         end
     end
 
+    # Loads the application configuration
+    # @raise [ConfigurationNotFound] if the configuration file does not exist
+    # @return [Configuration]
     def load_config(**options)
       path = options[:config]
       require_exists = options.key?(:require_exists) ? options[:require_exists] : true
@@ -102,6 +110,8 @@ module Imap::Backup
       Configuration.new(path: path)
     end
 
+    # @raise [RuntimeError] if the account does not exist
+    # @return [Account] the Account information for the email address
     def account(config, email)
       account = config.accounts.find { |a| a.username == email }
       raise "#{email} is not a configured account" if !account
@@ -109,6 +119,9 @@ module Imap::Backup
       account
     end
 
+    # @return [Array<Account>] If email addresses have been specified
+    #   returns the Account configurations for them.
+    #   If non have been specified, returns all account configurations
     def requested_accounts(config)
       emails = (options[:accounts] || "").split(",")
       if emails.any?

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

@@ -10,6 +10,7 @@ module Imap::Backup
   class CLI; end
   class CLI::Local < Thor; end
 
+  # Runs integrity check on local backups
   class CLI::Local::Check
     include CLI::Helpers
 
@@ -17,6 +18,8 @@ module Imap::Backup
       @options = options
     end
 
+    # Runs the check
+    # @return [void]
     def run
       results = requested_accounts(config).map do |account|
         serialized_folders = Account::SerializedFolders.new(account: account)

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

@@ -10,6 +10,7 @@ module Imap; end
 module Imap::Backup
   class CLI < Thor; end
 
+  # Implements the CLI functions relating to local storage
   class CLI::Local < Thor
     include Thor::Actions
     include CLI::Helpers
@@ -19,6 +20,8 @@ module Imap::Backup
     format_option
     quiet_option
     verbose_option
+    # Lists configured accounts
+    # @return [void]
     def accounts
       names = config.accounts.map(&:username)
       case options[:format]
@@ -44,6 +47,8 @@ module Imap::Backup
     format_option
     quiet_option
     verbose_option
+    # Runs integrity checks on backups
+    # @return [void]
     def check
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Check.new(non_logging_options).run
@@ -54,6 +59,8 @@ module Imap::Backup
     format_option
     quiet_option
     verbose_option
+    # Lists backed-up folders for an account
+    # @return [void]
     def folders(email)
       account = account(config, email)
 
@@ -63,7 +70,7 @@ module Imap::Backup
         list = serialized_folders.map { |_s, f| {name: f.name} }
         Kernel.puts list.to_json
       else
-        serialized_folders.each do |_s, f|
+        serialized_folders.each_value do |f|
           Kernel.puts %("#{f.name}")
         end
       end
@@ -74,6 +81,9 @@ module Imap::Backup
     format_option
     quiet_option
     verbose_option
+    # Lists backed-up emails for an account folder
+    # @raise [RuntimeError] if the folder does not exist
+    # @return [void]
     def list(email, folder_name)
       account = account(config, email)
 
@@ -101,6 +111,9 @@ module Imap::Backup
     format_option
     quiet_option
     verbose_option
+    # Shows the content of one or more backed-up email messages
+    # @raise [RuntimeError] if the folder does not exist
+    # @return [void]
     def show(email, folder_name, uids)
       account = account(config, email)
 

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

@@ -8,6 +8,7 @@ module Imap; end
 module Imap::Backup
   class CLI < Thor; end
 
+  # Implements the CLI functions relating to configured online accounts
   class CLI::Remote < Thor
     include Thor::Actions
     include CLI::Helpers
@@ -17,6 +18,8 @@ module Imap::Backup
     format_option
     quiet_option
     verbose_option
+    # Prints an account's folders
+    # @return [void]
     def folders(email)
       Imap::Backup::Logger.setup_logging options
       folder_names = folder_names(email)
@@ -36,6 +39,8 @@ module Imap::Backup
     format_option
     quiet_option
     verbose_option
+    # Prints an account's IMAP capabilities
+    # @return [void]
     def capabilities(email)
       Imap::Backup::Logger.setup_logging options
       config = load_config(**options)
@@ -55,6 +60,8 @@ module Imap::Backup
     format_option
     quiet_option
     verbose_option
+    # Prints an account's IMAP namespaces
+    # @return [void]
     def namespaces(email)
       Imap::Backup::Logger.setup_logging options
       config = load_config(**options)

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

@@ -8,6 +8,7 @@ module Imap; end
 module Imap::Backup
   class CLI < Thor; end
 
+  # Restores backups for one or more accounts
   class CLI::Restore < Thor
     include Thor::Actions
     include CLI::Helpers
@@ -18,6 +19,9 @@ module Imap::Backup
       @options = options
     end
 
+    # @!method run
+    #   @raise [RuntimeError] if no email is specified
+    #   @return [void]
     no_commands do
       def run
         config = load_config(**options)

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

@@ -8,6 +8,7 @@ module Imap; end
 module Imap::Backup
   class CLI < Thor; end
 
+  # Runs the menu-driven setup program
   class CLI::Setup < Thor
     include Thor::Actions
     include CLI::Helpers
@@ -17,6 +18,8 @@ module Imap::Backup
       @options = options
     end
 
+    # @!method run
+    #   @return [void]
     no_commands do
       def run
         config = load_config(**options, require_exists: false)

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

@@ -10,12 +10,15 @@ module Imap::Backup
   class CLI < Thor; end
   class CLI::Single < Thor; end
 
+  # Runs a backup without relying on existing configuration
   class CLI::Single::Backup
     def initialize(options)
       @options = options
       @password = nil
     end
 
+    # Runs the backup
+    # @return [void]
     def run
       process_options!
       account = Account.new(

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

@@ -9,6 +9,8 @@ module Imap; end
 module Imap::Backup
   class CLI < Thor; end
 
+  # Processes parameters to run a backup via command-line parameters
+  # (without using a configuration file)
   class CLI::Single < Thor
     include CLI::Helpers
 
@@ -170,6 +172,8 @@ module Imap::Backup
     )
     quiet_option
     verbose_option
+    # Launches the backup procedure
+    # @return [void]
     def backup
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       direct = Backup.new(non_logging_options)

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

@@ -4,6 +4,7 @@ require "imap/backup/serializer"
 module Imap; end
 
 module Imap::Backup
+  # Prints various statistics about an account and its backup
   class CLI::Stats < Thor
     include Thor::Actions
     include CLI::Helpers
@@ -14,6 +15,8 @@ module Imap::Backup
       @options = options
     end
 
+    # @!method run
+    #   @return [void]
     no_commands do
       def run
         case options[:format]

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

@@ -8,10 +8,12 @@ require "imap/backup/mirror"
 module Imap; end
 
 module Imap::Backup
+  # Implements migration and mirroring
   class CLI::Transfer < Thor
     include Thor::Actions
     include CLI::Helpers
 
+    # The possible vaues for the action parameter
     ACTIONS = %i(migrate mirror).freeze
 
     def initialize(action, source_email, destination_email, options)
@@ -29,6 +31,12 @@ module Imap::Backup
       @source_prefix = nil
     end
 
+    # @!method run
+    #   @raise [RuntimeError] if the indicated action is unknown,
+    #     or the source and destination accounts are the same,
+    #     or either of the accounts is not configured,
+    #     or incompatible namespace/delimter parameters have been supplied
+    #   @return [void]
     no_commands do
       def run
         raise "Unknown action '#{action}'" if !ACTIONS.include?(action)

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

@@ -13,6 +13,7 @@ module Imap; end
 module Imap::Backup
   class CLI < Thor; end
 
+  # Implements the CLI utility functions
   class CLI::Utils < Thor
     include Thor::Actions
     include CLI::Helpers
@@ -21,6 +22,9 @@ module Imap::Backup
     config_option
     quiet_option
     verbose_option
+    # Creates fake downloaded emails so that only the account's future emails
+    # will really get backed up
+    # @return [void]
     def ignore_history(email)
       Logger.setup_logging options
       config = load_config(**options)
@@ -59,6 +63,8 @@ module Imap::Backup
       banner: "the name of the Thunderbird profile to copy emails to",
       aliases: ["-p"]
     )
+    # Exports the account's emails to Thunderbird
+    # @return [void]
     def export_to_thunderbird(email)
       Imap::Backup::Logger.setup_logging options
       force = options.key?(:force) ? options[:force] : false
@@ -78,7 +84,7 @@ module Imap::Backup
 
       raise "No serialized folders were found for account '#{email}'" if serialized_folders.none?
 
-      serialized_folders.each do |serializer, _folder|
+      serialized_folders.each_key do |serializer|
         Thunderbird::MailboxExporter.new(
           email, serializer, profile, force: force
         ).run

data/lib/imap/backup/cli.rb

@@ -48,6 +48,7 @@ module Imap::Backup
 
     # Overrides {https://www.rubydoc.info/gems/thor/Thor%2FBase%2FClassMethods:start Thor's method}
     # to handle '--version' and rearrange parameters if 'help' is passed
+    # @return [void]
     def self.start(args)
       if args.include?("--version")
         new.version
@@ -87,6 +88,7 @@ module Imap::Backup
     refresh_option
     verbose_option
     # Runs account backups
+    # @return [void]
     def backup
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Backup.new(non_logging_options).run
@@ -148,6 +150,7 @@ module Imap::Backup
       aliases: ["-s"]
     )
     # Migrates emails from one account to another
+    # @return [void]
     def migrate(source_email, destination_email)
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Transfer.new(:migrate, source_email, destination_email, non_logging_options).run
@@ -208,6 +211,7 @@ module Imap::Backup
       aliases: ["-s"]
     )
     # Keeps one email account in line with another
+    # @return [void]
     def mirror(source_email, destination_email)
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Transfer.new(:mirror, source_email, destination_email, non_logging_options).run
@@ -226,6 +230,7 @@ module Imap::Backup
     quiet_option
     verbose_option
     # Restores backed up meails to an account
+    # @return [void]
     def restore(email = nil)
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Restore.new(email, non_logging_options).run
@@ -240,6 +245,7 @@ module Imap::Backup
     quiet_option
     verbose_option
     # Runs the menu-driven setup program
+    # @return [void]
     def setup
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       CLI::Setup.new(non_logging_options).run
@@ -264,6 +270,7 @@ module Imap::Backup
     quiet_option
     verbose_option
     # Prints various statistics about a configured account
+    # @return [void]
     def stats(email)
       non_logging_options = Imap::Backup::Logger.setup_logging(options)
       Stats.new(email, non_logging_options).run
@@ -274,6 +281,7 @@ module Imap::Backup
 
     desc "version", "Print the imap-backup version"
     # Prints the program version
+    # @return [void]
     def version
       Kernel.puts "imap-backup #{Imap::Backup::VERSION}"
     end

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

@@ -3,9 +3,11 @@ require "imap/backup/client/default"
 module Imap; end
 
 module Imap::Backup
+  # Overrides default IMAP client behaviour for Apple Mail accounts
   class Client::AppleMail < Client::Default
     # With Apple Mails's IMAP, passing "/" to list
     # results in an empty list
+    # @return [String] the value to use when requesting the list of account folders
     def provider_root
       ""
     end

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

@@ -5,19 +5,24 @@ module Imap; end
 module Imap::Backup
   module Client; end
 
+  # Transparently wraps a client instance, while delaying login until it becomes necessary
   class Client::AutomaticLoginWrapper
     include RetryOnError
 
+    # @private
     LOGIN_RETRY_CLASSES = [::EOFError, ::Errno::ECONNRESET, ::SocketError].freeze
 
+    # @return [Client]
     attr_reader :client
-    attr_reader :login_called
 
     def initialize(client:)
       @client = client
       @login_called = false
     end
 
+    # Proxies calls to the client.
+    # Before the first call does login
+    # @return the return value of the client method called
     def method_missing(method_name, *arguments, &block)
       if login_called
         client.send(method_name, *arguments, &block)
@@ -27,12 +32,15 @@ module Imap::Backup
       end
     end
 
+    # @return [Boolean] whether the client responds to the method
     def respond_to_missing?(method_name, _include_private = false)
       client.respond_to?(method_name)
     end
 
     private
 
+    attr_reader :login_called
+
     def do_first_login
       retry_on_error(errors: LOGIN_RETRY_CLASSES) do
         client.login

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

@@ -8,6 +8,8 @@ module Imap; end
 module Imap::Backup
   module Client; end
 
+  # Wraps a Net::IMAP instance
+  # Tracks the latest folder selection in order to avoid repeated calls
   class Client::Default
     extend Forwardable
     def_delegators :imap, *%i(
@@ -22,6 +24,7 @@ module Imap::Backup
       @state = nil
     end
 
+    # @return [Array<String>] the account folders
     def list
       root = provider_root
       mailbox_lists = imap.list(root, "*")
@@ -31,36 +34,44 @@ module Imap::Backup
       mailbox_lists.map { |ml| extract_name(ml) }
     end
 
+    # Logs in to the account on the IMAP server
+    # @return [void]
     def login
       Logger.logger.debug "Logging in: #{account.username}/#{masked_password}"
       imap.login(account.username, account.password)
       Logger.logger.debug "Login complete"
     end
 
+    # Logs out and back in to the server
+    # @return [void]
     def reconnect
       disconnect
       login
     end
 
+    # @return [String] the account username
     def username
       account.username
     end
 
-    # Track mailbox selection during delegation to Net::IMAP instance
-
+    # Disconects from the server
+    # @return [void]
     def disconnect
       imap.disconnect
       self.state = nil
     end
 
+    # Prepares read-only access to a folder
+    # @return [void]
     def examine(mailbox)
       return if state == [:examine, mailbox]
 
-      result = imap.examine(mailbox)
+      imap.examine(mailbox)
       self.state = [:examine, mailbox]
-      result
     end
 
+    # Prepares read-write access to a folder
+    # @return [void]
     def select(mailbox)
       return if state == [:select, mailbox]