imap-backup 14.4.4 → 14.4.5

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

@@ -3,15 +3,11 @@ require "imap/backup/email/provider/base"
 module Imap; end
 
 module Imap::Backup
+  # Provides overrides when the IMAP provider is not known
   class Email::Provider::Unknown < Email::Provider::Base
     # We don't know how to guess the IMAP server
+    # @return [nil]
     def host
     end
-
-    def options
-      # rubocop:disable Naming/VariableNumber
-      {port: 993, ssl: {ssl_version: :TLSv1_2}}
-      # rubocop:enable Naming/VariableNumber
-    end
   end
 end

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

@@ -9,7 +9,12 @@ module Imap; end
 module Imap::Backup
   module Email; end
 
+  # Provides a class factory for email account providers
   class Email::Provider
+    # @param address [String] an email address
+    # @return [Email::Provider::Fastmail, Email::Provider::GMail, Email::Provider::AppleMail,
+    #   Email::Provider::Purelymail, Email::Provider::Unknown]
+    #   an instance supplying default values for the email's account set up
     def self.for_address(address)
       # rubocop:disable Lint/DuplicateBranch
       case

data/lib/imap/backup/file_mode.rb

@@ -1,11 +1,13 @@
 module Imap; end
 
 module Imap::Backup
+  # Accesses a file's access permissions
   class FileMode
     def initialize(filename:)
       @filename = filename
     end
 
+    # @return [Integer, nil] The user, group and "other" part of the file's "mode"
     def mode
       return nil if !File.exist?(filename)
 

data/lib/imap/backup/flag_refresher.rb

@@ -1,7 +1,9 @@
 module Imap; end
 
 module Imap::Backup
+  # Updates the flags on backed-up emails
   class FlagRefresher
+    # The number of messages to process at a time
     CHUNK_SIZE = 100
 
     def initialize(folder, serializer)
@@ -9,6 +11,8 @@ module Imap::Backup
       @serializer = serializer
     end
 
+    # Runs the update
+    # @return [void]
     def run
       uids = serializer.uids.clone
 

data/lib/imap/backup/local_only_message_deleter.rb

@@ -3,6 +3,7 @@ require "imap/backup/logger"
 module Imap; end
 
 module Imap::Backup
+  # Deletes locally backed-up emails that are no longer on the server
   class LocalOnlyMessageDeleter
     def initialize(folder, serializer)
       @folder = folder
@@ -12,6 +13,7 @@ module Imap::Backup
     # TODO: this method is very slow as it copies all messages.
     # A quicker method would only remove UIDs from the .imap file,
     # but that would require a garbage collection later.
+    # @return [void]
     def run
       local_only_uids = serializer.uids - folder.uids
       if local_only_uids.empty?

data/lib/imap/backup/logger.rb

@@ -7,13 +7,26 @@ require "imap/backup/text/sanitizer"
 module Imap; end
 
 module Imap::Backup
+  # Wraps the standard logger, providing configuration and sanitization
   class Logger
     include Singleton
 
+    # @return [Imap::Backup::Logger] the singleton instance of this class
     def self.logger
       Logger.instance.logger
     end
 
+    # @param options [Hash] command-line options
+    # @option options [Boolean] :quiet (false) if true, no output will be written
+    # @option options [Array<Boolean>] :verbose ([]) counts how many `--verbose`
+    #   parameters were passed (and, potentially subtracts the number of
+    #   `--no-verbose` parameters).
+    #   If the result is 0, does normal info-level logging,
+    #   If the result is 1, does debug logging,
+    #   If the result is 2, does debug logging and client-server debug logging.
+    #   This option is overridden by the `:verbose` option.
+    #
+    # @return [Hash] the options without the :quiet and :verbose keys
     def self.setup_logging(options = {})
       copy = options.clone
       quiet = copy.delete(:quiet)
@@ -35,6 +48,9 @@ module Imap::Backup
       copy
     end
 
+    # Wraps a block, filtering output to standard error,
+    # hidng passwords and outputs the results to standard out
+    # @return [void]
     def self.sanitize_stderr
       sanitizer = Text::Sanitizer.new($stdout)
       previous_stderr = $stderr
@@ -45,10 +61,12 @@ module Imap::Backup
       $stderr = previous_stderr
     end
 
+    # @private
     def self.count(verbose)
       verbose.reduce(1) { |acc, v| acc + (v ? 1 : -1) }
     end
 
+    # @return [Logger] the configured Logger
     attr_reader :logger
 
     def initialize

data/lib/imap/backup/migrator.rb

@@ -3,6 +3,7 @@ require "imap/backup/logger"
 module Imap; end
 
 module Imap::Backup
+  # Copies a folder of backed-up emails to an online folder
   class Migrator
     def initialize(serializer, folder, reset: false)
       @folder = folder
@@ -10,6 +11,8 @@ module Imap::Backup
       @serializer = serializer
     end
 
+    # Runs the migration
+    # @return [void]
     def run
       count = serializer.uids.count
       folder.create

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

@@ -5,6 +5,7 @@ module Imap; end
 module Imap::Backup
   class Mirror; end
 
+  # Keeps track of the mapping between source and destination UIDs
   class Mirror::Map
     def initialize(pathname:, destination:)
       @pathname = pathname
@@ -16,6 +17,8 @@ module Imap::Backup
       @map = nil
     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
@@ -24,6 +27,8 @@ module Imap::Backup
       true
     end
 
+    # Sets, or resets to an empty state
+    # @return [void]
     def reset(source_uid_validity:, destination_uid_validity:)
       destination_store["source_uid_validity"] = source_uid_validity
       @source_uid_validity = nil
@@ -33,6 +38,11 @@ module Imap::Backup
       @map = nil
     end
 
+    # @param destination_uid [Integer] a message UID from the destination server
+    #
+    # @raise [RuntimeError] if the UID validity is not set
+    # @return [Integer, nil] the source UID that is equivalent to the given destination UID
+    #   or nil if it is not found
     def source_uid(destination_uid)
       if destination_store == {}
         raise "Assign UID validities with #reset before calling #source_uid"
@@ -41,6 +51,11 @@ module Imap::Backup
       map.key(destination_uid)
     end
 
+    # @param source_uid [Integer] a message UID from the source server
+    #
+    # @raise [RuntimeError] if the UID validity is not set
+    # @return [Integer, nil] the destination UID that is equivalent to the given source UID
+    #   or nil if it is not found
     def destination_uid(source_uid)
       if destination_store == {}
         raise "Assign UID validities with #reset before calling #destination_uid"
@@ -49,12 +64,18 @@ module Imap::Backup
       map[source_uid]
     end
 
+    # Creates a mapping between message UIDs on the source
+    # and destination servers
+    # @raise [RuntimeError] if the UID validity is not set
+    # @return [void]
     def map_uids(source:, destination:)
       raise "Assign UID validities with #reset before calling #map_uids" if destination_store == {}
 
       map[source] = destination
     end
 
+    # Saves the map to disk as JSON
+    # @return [void]
     def save
       File.write(pathname, store.to_json)
     end

data/lib/imap/backup/mirror.rb

@@ -3,12 +3,20 @@ require "imap/backup/mirror/map"
 module Imap; end
 
 module Imap::Backup
+  # Synchronises a folder between a source and destination
   class Mirror
     def initialize(serializer, folder)
       @serializer = serializer
       @folder = folder
     end
 
+    # If necessary, reates the destination folder,
+    # then deletes any messages in the destination folder
+    # that are not in the local store,
+    # sets existing messages' flas
+    # then appends any missing messages
+    # and saves the mapping file
+    # @return [void]
     def run
       ensure_destination_folder
       delete_destination_only_emails

data/lib/imap/backup/naming.rb

@@ -1,11 +1,17 @@
 module Imap; end
 
 module Imap::Backup
+  # Maps between server and file system folder names
+  # `/` is treated as an acceptable character
   class Naming
+    # The characters that cannot be used in file names
     INVALID_FILENAME_CHARACTERS = ":%;".freeze
+    # A regular expression that captures each disallowed character
     INVALID_FILENAME_CHARACTER_MATCH = /([#{INVALID_FILENAME_CHARACTERS}])/.freeze
 
-    # `*_path` functions treat `/` as an acceptable character
+    # @param name [String] a folder name
+    # @return [String] the supplied string iwth disallowed characters replaced
+    #   by their hexadecimal representation
     def self.to_local_path(name)
       name.gsub(INVALID_FILENAME_CHARACTER_MATCH) do |character|
         hex =
@@ -16,6 +22,9 @@ module Imap::Backup
       end
     end
 
+    # @param name [String] a serialized folder name
+    # @return the supplied string with hexadecimal codes ('%xx') replaced with
+    #   the characters they represent
     def self.from_local_path(name)
       name.gsub(/%(.*?);/) do
         ::Regexp.last_match(1).

data/lib/imap/backup/retry_on_error.rb

@@ -3,7 +3,16 @@ require "imap/backup/logger"
 module Imap; end
 
 module Imap::Backup
+  # Provides a mechanism for retrying blocks of code which often throw errors
   module RetryOnError
+    # Calls the supplied block,
+    # traps the given types of errors
+    # retrying up to a given number of times
+    # @param errors [Array<Exception>] the exceptions to trap
+    # @param limit [Integer] the maximum number of retries
+    # @param on_error [Proc] a block to call when an error occurs
+    # @raise any error ocurring more than `limit` times
+    # @return the result of any successful completion of the block
     def retry_on_error(errors:, limit: 10, on_error: nil)
       tries ||= 1
       yield

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

@@ -7,6 +7,9 @@ module Imap::Backup
 
   # Appends messages to the local store
   class Serializer::Appender
+    # @param folder [String] the name of the folder
+    # @param imap [Serializer::Imap] the metadata serializer for the folder
+    # @param mbox [Serializer::Mbox] the folder's mailbox
     def initialize(folder:, imap:, mbox:)
       @folder = folder
       @imap = imap
@@ -15,6 +18,12 @@ module Imap::Backup
 
     # Adds a message to the metadata file and the mailbox.
     # Wraps any errors with information about the message that caused them.
+    # @raise [RuntimeError] if the UID validity is not set
+    #   or when an error occurs during serialization
+    # @param uid [Integer] the message's UID
+    # @param message [String] the on-disk version of the message
+    # @param flags [Array[Symbol]] the message's flags
+    # @return [void]
     def append(uid:, message:, flags:)
       raise "Can't add messages without uid_validity" if !imap.uid_validity
 

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

@@ -8,11 +8,13 @@ require "imap/backup/serializer/transaction"
 module Imap; end
 
 module Imap::Backup
+  # Wraps the Serializer, delaying metadata appends
   class Serializer::DelayedMetadataSerializer
     extend Forwardable
 
     def_delegator :serializer, :uids
 
+    # @param serializer [Serializer] the serializer for a folder
     def initialize(serializer:)
       @serializer = serializer
       @tsx = nil
@@ -20,7 +22,9 @@ module Imap::Backup
 
     # Initializes the metadata and mailbox transactions, then calls the supplied block.
     # Once the block has finished, commits changes to metadata
+    # @param block [block] the block that is wrapped by the transaction
     #
+    # @raise any error ocurring during the commit phase
     # @return [void]
     def transaction(&block)
       tsx.fail_in_transaction!(:transaction, message: "nested transactions are not supported")

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

@@ -18,6 +18,7 @@ module Imap::Backup
 
     # Creates the directory and any missing parent directories,
     # ensuring the desired permissions.
+    # @return [void]
     def run
       parts = path.split("/")
       return if parts.empty?

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

@@ -12,6 +12,7 @@ module Imap::Backup
     # The version number to store in the metadata file
     CURRENT_VERSION = 3
 
+    # @return [String] The path of the imap metadata file, without the '.imap' extension
     attr_reader :folder_path
 
     # @param folder_path [String] The path of the imap metadata file, without the '.imap' extension
@@ -24,6 +25,10 @@ module Imap::Backup
       @tsx = nil
     end
 
+    # Opens a transaction
+    # @param block [block] the block that is wrapped by the transaction
+    # @raise any exception ocurring in the block
+    # @return [void]
     def transaction(&block)
       tsx.fail_in_transaction!(:transaction, message: "nested transactions are not supported")
 
@@ -41,6 +46,8 @@ module Imap::Backup
       # rubocop:enable Lint/RescueException
     end
 
+    # Discards stored changes to the data
+    # @return [void]
     def rollback
       tsx.fail_outside_transaction!(:rollback)
 
@@ -50,6 +57,7 @@ module Imap::Backup
       tsx.clear
     end
 
+    # @return [String] The full path name of the metadata file
     def pathname
       "#{folder_path}.imap"
     end
@@ -66,6 +74,11 @@ module Imap::Backup
       true
     end
 
+    # Append message metadata
+    # @param uid [Integer] the message's UID
+    # @param length [Integer] the length of the message (as stored on disk)
+    # @param flags [Array[Symbol]] the message's flags
+    # @return [void]
     def append(uid, length, flags: [])
       offset =
         if messages.empty?
@@ -82,10 +95,16 @@ module Imap::Backup
       save
     end
 
+    # Get message metadata
+    # @param uid [Integer] a message UID
+    # @return [Serializer::Message]
     def get(uid)
       messages.find { |m| m.uid == uid }
     end
 
+    # Deletes the metadata file
+    # and discards stored attributes
+    # @return [void]
     def delete
       return if !exist?
 
@@ -96,6 +115,10 @@ module Imap::Backup
       @version = nil
     end
 
+    # Renames the metadata file, if it exists,
+    # otherwise, simply stores the new name
+    # @param new_path [String] the new path (without extension)
+    # @return [void]
     def rename(new_path)
       if exist?
         old_pathname = pathname
@@ -106,28 +129,36 @@ module Imap::Backup
       end
     end
 
+    # @return [Integer] the UID validity for the folder
     def uid_validity
       ensure_loaded
       @uid_validity
     end
 
+    # Sets the folder's UID validity and saves the metadata file
+    # @param value [Integer] the new UID validity
+    # @return [void]
     def uid_validity=(value)
       ensure_loaded
       @uid_validity = value
       save
     end
 
-    # Make private
+    # @return [Array<Hash>]
     def messages
       ensure_loaded
       @messages
     end
 
-    # Deprecated
+    # @return [Array<Integer>] The uids of all messages
     def uids
       messages.map(&:uid)
     end
 
+    # Update a message's metadata, replacing its UID
+    # @param old [Integer] the existing message UID
+    # @param new [Integer] the new UID to apply to the message
+    # @return [void]
     def update_uid(old, new)
       index = messages.find_index { |m| m.uid == old }
       return if index.nil?
@@ -136,11 +167,16 @@ module Imap::Backup
       save
     end
 
+    # @return [String] The format version for the metadata file
     def version
       ensure_loaded
       @version
     end
 
+    # Saves the file,
+    # except in a transaction when it does nothing
+    # @raise [RuntimeError] if UID validity has not been set
+    # @return [void]
     def save
       return if tsx.in_transaction?
 

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

@@ -3,6 +3,7 @@ module Imap; end
 module Imap::Backup
   class Serializer; end
 
+  # An error indicating the folder is not serialized correctly
   class Serializer::FolderIntegrityError < StandardError; end
 
   # Checks that both the mailbox and its associated metadata file match

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

@@ -3,14 +3,21 @@ require "imap/backup/serializer/transaction"
 module Imap; end
 
 module Imap::Backup
+  # Stores messages
   class Serializer::Mbox
+    # @return [String] The path of the mailbox file, without the '.mbox' extension
     attr_reader :folder_path
 
+    # @param folder_path [String] The path of the mailbox file, without the '.mbox' extension
     def initialize(folder_path)
       @folder_path = folder_path
       @tsx = nil
     end
 
+    # Starts a transaction
+    # @param block [block] the block that is wrapped by the transaction
+    # @raise re-raises errors which occur in the block
+    # @return [void]
     def transaction(&block)
       tsx.fail_in_transaction!(:transaction, message: "nested transactions are not supported")
 
@@ -26,6 +33,8 @@ module Imap::Backup
       end
     end
 
+    # Returns to the pre-transaction state
+    # @return [void]
     def rollback
       tsx.fail_outside_transaction!(:rollback)
 
@@ -36,12 +45,19 @@ module Imap::Backup
       exist?
     end
 
+    # Serializes a message
+    # @param message [String] the message text
+    # @return [void]
     def append(message)
       File.open(pathname, "ab") do |file|
         file.write message
       end
     end
 
+    # Reads a message from disk
+    # @param offset [Integer] the start of the message inside the mailbox file
+    # @param length [Integer] the length of the message (as stored on disk)
+    # @return [String] the message
     def read(offset, length)
       File.open(pathname, "rb") do |f|
         f.seek offset
@@ -49,6 +65,8 @@ module Imap::Backup
       end
     end
 
+    # Deletes the mailbox
+    # @return [void]
     def delete
       return if !exist?
 
@@ -59,16 +77,22 @@ module Imap::Backup
       File.exist?(pathname)
     end
 
+    # @return [Integer] The lsize of the disk file
     def length
       return nil if !exist?
 
       File.stat(pathname).size
     end
 
+    # @return [String] The full path name of the mailbox
     def pathname
       "#{folder_path}.mbox"
     end
 
+    # Renames the mailbox, if it exists,
+    # otherwise, simply stores the new name
+    # @param new_path [String] the new path (without extension)
+    # @return [void]
     def rename(new_path)
       if exist?
         old_pathname = pathname
@@ -79,6 +103,8 @@ module Imap::Backup
       end
     end
 
+    # Sets the mailbox file's updated time to the current time
+    # @return [void]
     def touch
       File.open(pathname, "a") {}
     end

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

@@ -5,10 +5,15 @@ require "imap/backup/email/mboxrd/message"
 module Imap; end
 
 module Imap::Backup
+  # Represents a stored message
   class Serializer::Message
+    # @return [Array[Symbol]] the message's flags
     attr_accessor :flags
+    # @return [Integer] the length of the message (as stored on disk)
     attr_reader :length
+    # @return [Integer] the start of the message inside the mailbox file
     attr_reader :offset
+    # @return [Integer] the message's UID
     attr_accessor :uid
 
     extend Forwardable
@@ -16,6 +21,11 @@ module Imap::Backup
     def_delegator :message, :supplied_body, :body
     def_delegators :message, :imap_body, :date, :subject
 
+    # @param uid [Integer] the message's UID
+    # @param offset [Integer] the start of the message inside the mailbox file
+    # @param length [Integer] the length of the message (as stored on disk)
+    # @param mbox [Serializer::Mbox] the mailbox containing the message
+    # @param flags [Array[Symbol]] the message's flags
     def initialize(uid:, offset:, length:, mbox:, flags: [])
       @uid = uid
       @offset = offset
@@ -24,6 +34,7 @@ module Imap::Backup
       @flags = flags.map(&:to_sym)
     end
 
+    # @return [Hash] the message metadata
     def to_h
       {
         uid: uid,
@@ -33,6 +44,8 @@ module Imap::Backup
       }
     end
 
+    # Reads the message text and returns the original form
+    # @return [String] the message
     def message
       @message =
         begin

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

@@ -1,13 +1,17 @@
 module Imap; end
 
 module Imap::Backup
+  # Enumerates over a list of stores messages
   class Serializer::MessageEnumerator
-    attr_reader :imap
-
+    # @param imap [Serializer::Imap] the metadata serializer for the folder
     def initialize(imap:)
       @imap = imap
     end
 
+    # Enumerates over the messages
+    # @param uids [Array<Integer>] the message UIDs of the messages to iterate over
+    # @yieldparam message [Serializer::Message]
+    # @return [void]
     def run(uids:)
       uids.each do |uid_maybe_string|
         uid = uid_maybe_string.to_i
@@ -18,5 +22,9 @@ module Imap::Backup
         yield message
       end
     end
+
+    private
+
+    attr_reader :imap
   end
 end

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

@@ -3,12 +3,18 @@ require "imap/backup/file_mode"
 module Imap; end
 
 module Imap::Backup
+  # Ensures a file has the desired permissions
   class Serializer::PermissionChecker
+    # @param filename [String] the file name
+    # @param limit [Integer] the maximum permission that should be set
     def initialize(filename:, limit:)
       @filename = filename
       @limit = limit
     end
 
+    # Runs the check
+    # @raise [RuntimeError] if the permissions are incorrect
+    # @return [void]
     def run
       actual = FileMode.new(filename: filename).mode
       return nil if actual.nil?