imap-backup 14.4.4 → 14.4.5

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)
 
@@ -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

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]
 

data/lib/imap/backup/configuration.rb

@@ -9,15 +9,21 @@ require "imap/backup/serializer/permission_checker"
 module Imap; end
 
 module Imap::Backup
+  # Handles the application's configuration file
   class Configuration
+    # The default directory of the configuration file
     CONFIGURATION_DIRECTORY = File.expand_path("~/.imap-backup")
+    # The default download strategy key
     DEFAULT_STRATEGY = "delay_metadata".freeze
+    # The available download strategies
     DOWNLOAD_STRATEGIES = [
       {key: "direct", description: "write straight to disk"},
       {key: DEFAULT_STRATEGY, description: "delay writing metadata"}
     ].freeze
+    # The current file version
     VERSION = "2.2".freeze
 
+    # @return [String] the default configuration file path
     def self.default_pathname
       File.join(CONFIGURATION_DIRECTORY, "config.json")
     end
@@ -33,10 +39,13 @@ module Imap::Backup
       @download_strategy_modified = false
     end
 
+    # @return [String] the directory containing the configuration file
     def path
       File.dirname(pathname)
     end
 
+    # Saves the configuration file in JSON format
+    # @return [void]
     def save
       ensure_loaded!
       FileUtils.mkdir_p(path) if !File.directory?(path)
@@ -53,6 +62,7 @@ module Imap::Backup
       @data = nil
     end
 
+    # @return [Array<Account>] the configured accounts
     def accounts
       @accounts ||= begin
         ensure_loaded!
@@ -63,12 +73,15 @@ module Imap::Backup
       end
     end
 
+    # @return [String] the cofigured download strategy
     def download_strategy
       ensure_loaded!
 
       @download_strategy
     end
 
+    # @param value [String] the new strategy
+    # @return [void]
     def download_strategy=(value)
       raise "Unknown strategy '#{value}'" if !DOWNLOAD_STRATEGIES.find { |s| s[:key] == value }
 

data/lib/imap/backup/configuration_not_found.rb

@@ -1,5 +1,6 @@
 module Imap; end
 
 module Imap::Backup
+  # Thrown when no configuration file is found
   class ConfigurationNotFound < StandardError; end
 end

data/lib/imap/backup/downloader.rb

@@ -3,7 +3,9 @@ require "net/imap"
 module Imap; end
 
 module Imap::Backup
+  # Downloads as yet undownloaded emails from an account's server
   class Downloader
+    # @private
     class MultiFetchFailedError < StandardError; end
 
     def initialize(folder, serializer, multi_fetch_size: 1, reset_seen_flags_after_fetch: false)
@@ -14,6 +16,8 @@ module Imap::Backup
       @uids = nil
     end
 
+    # Runs the downloader
+    # @return [void]
     def run
       info("#{uids.count} new messages") if uids.any?
 

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

@@ -6,7 +6,13 @@ module Imap::Backup
   module Email; end
 
   module Email::Mboxrd
+    # Handles serialization and deserialization of messages
     class Message
+      # @param serialized [String] an email message
+      #
+      # @return [String] The message without the initial 'From ' line
+      #   and with one level of '>' quoting removed from other lines
+      #   that start with 'From'
       def self.clean_serialized(serialized)
         cleaned = serialized.gsub(/^>(>*From)/, "\\1")
         # Serialized messages in this format *should* start with a line
@@ -19,32 +25,40 @@ module Imap::Backup
         cleaned
       end
 
+      # @param serialized [String] the on-disk version of the message
+      #
+      # @return [Message] the original message
       def self.from_serialized(serialized)
         new(clean_serialized(serialized))
       end
 
+      # @return [String] the original message body
       attr_reader :supplied_body
 
       def initialize(supplied_body)
         @supplied_body = supplied_body.clone
       end
 
+      # @return [String] the message with an initial 'From ADDRESS' line
       def to_serialized
         from_line = "From #{from}\n"
         body = mboxrd_body.dup.force_encoding(Encoding::UTF_8)
         from_line + body
       end
 
+      # @return [Date, nil] the date of the message
       def date
         parsed.date
       rescue StandardError
         nil
       end
 
+      # @return [String] the message's subject line
       def subject
         parsed.subject
       end
 
+      # @return [String] the original message ready for transmission to an IMAP server
       def imap_body
         supplied_body.gsub(/(?<!\r)\n/, "\r\n")
       end

data/lib/imap/backup/email/provider/apple_mail.rb

@@ -3,7 +3,9 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides for Apple mail accounts
   class Email::Provider::AppleMail < Email::Provider::Base
+    # @return [String] the Apple Mail IMAP server host name
     def host
       "imap.mail.me.com"
     end

data/lib/imap/backup/email/provider/base.rb

@@ -4,7 +4,9 @@ module Imap::Backup
   module Email; end
   class Email::Provider; end
 
+  # Supplies defaults for email provider behaviour
   class Email::Provider::Base
+    # @return [Hash] defaults for the Net::IMAP connection
     def options
       # rubocop:disable Naming/VariableNumber
       {port: 993, ssl: {ssl_version: :TLSv1_2}}

data/lib/imap/backup/email/provider/fastmail.rb

@@ -3,7 +3,9 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides for Fastmail accounts
   class Email::Provider::Fastmail < Email::Provider::Base
+    # @return [String] the Fastmail IMAP server host name
     def host
       "imap.fastmail.com"
     end

data/lib/imap/backup/email/provider/gmail.rb

@@ -3,7 +3,9 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides for GMail accounts
   class Email::Provider::GMail < Email::Provider::Base
+    # @return [String] the GMail IMAP server host name
     def host
       "imap.gmail.com"
     end

data/lib/imap/backup/email/provider/purelymail.rb

@@ -3,7 +3,9 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides for Purelymail accounts
   class Email::Provider::Purelymail < Email::Provider::Base
+    # @return [String] The Purelymail IMAP server host name
     def host
       "mailserver.purelymail.com"
     end