imap-backup 14.4.1 → 14.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f83228485fa483834d66fa4fb2fd8dcfba3523100608136e8d82eb3c90765f40
-  data.tar.gz: d1c52e0743c7b2922e0c5e65c388446ef344f32a42887f0069f2070b5e0903bc
+  metadata.gz: 0cfc1578cd412445288e4fab78e6baa0f36b1d821c5ef6d534b72b1b2e647f97
+  data.tar.gz: ebe6162fd0370739a141c92861f7f623ff9e4b774e6d88952cfc04e0792a9826
 SHA512:
-  metadata.gz: 4a95165223801af4c9e72b7aa66b054caaad51300f229d105d6ca6d0636f8f3a500598eb184b7230c48e0c27492d1f14121660c96db1c515d89bf21a73fcaa89
-  data.tar.gz: 9c3b7fe3b38ab2819285406503d61651f3df175e3ce6702e2e274183d99a361a6e986e2afb75859ea74a788688fda05856ad869b62a736b2c996a1b2593a23f3
+  metadata.gz: a57023ad7181a137744866b84181d307485029b7f05e9b64d3a8ccc4735a3114a814006ef82cc8c9e8eac1ea9db1055be31a8f8ff48a385836b874b5b23494bb
+  data.tar.gz: ffb357707b5c42a1cea36da60d1c1b0ffc056d175c32760c9551259673331c1205d3365e62bf865b6ed0245042c069ba4b610cf66b4f53e59a57e97f46ef1cbc

data/bin/imap-backup

@@ -2,9 +2,9 @@
 
 $LOAD_PATH.unshift(File.expand_path("../lib/", __dir__))
 
-require "imap/backup/cli_coverage"
+require_relative "../spec/support/cli_coverage"
 
-Imap::Backup::CliCoverage.conditionally_activate
+CliCoverage.conditionally_activate
 
 require "imap/backup/cli"
 require "imap/backup/logger"

data/docs/api.md

@@ -0,0 +1,20 @@
+# @title Index
+# imap-backup API Documentation
+
+![Version](https://img.shields.io/gem/v/imap-backup?label=Version&logo=rubygems)
+[![Build Status](https://github.com/joeyates/imap-backup/actions/workflows/main.yml/badge.svg)][CI Status]
+![Coverage](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/joeyates/b54fe758bfb405c04bef72dad293d707/raw/coverage.json)
+![License](https://img.shields.io/github/license/joeyates/imap-backup?color=brightgreen&label=License)
+[![Stars](https://img.shields.io/github/stars/joeyates/imap-backup?style=social)][GitHub Stars]
+
+[CI Status]: https://github.com/joeyates/imap-backup/actions/workflows/main.yml
+[GitHub Stars]: https://github.com/joeyates/imap-backup/stargazers "GitHub Stars"
+
+This is the developer documentation for imap-backup's **code**.
+
+Usage documentation is on [GitHub](https://github.com/joeyates/imap-backup).
+
+You can get an overview of the program's structure from the
+{file:ARCHITECTURE.md ARCHITECTURE} file.
+
+The {file:CHANGELOG.md CHANGELOG} has a history of the changes to the program.

data/docs/development.md

@@ -17,8 +17,9 @@ git config --local blame.ignoreRevsFile .git-blame-ignore-revs
 
 ## Feature Specs
 
-Specs under `specs/features` are integration specs run against
-two local IMAP servers controlled by Podman (or Docker) Compose.
+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
 
@@ -32,20 +33,30 @@ or, with Podman
 $ podman-compose -f dev/compose.yml up -d
 ```
 
+Then, run all specs
+
 ```sh
-$ rake
+$ rspec
 ```
 
-To exclude container-based tests:
+To exclude container-based tests
 
 ```sh
-rake no-docker
+$ rspec --tag ~docker
 ```
 
-or
+To run **just** the feature specs
 
 ```sh
-$ rspec --tag ~docker
+rspec spec/features/**/*_spec.rb
+```
+
+## Full Test Run
+
+The full test run includes RSpec specs **and** Runbocop checks
+
+```sh
+rake
 ```
 
 # Older Rubies

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

@@ -8,10 +8,8 @@ module Imap; end
 module Imap::Backup
   class Account; end
 
+  # Carries out the backup of the configured folders of the account
   class Account::Backup
-    attr_reader :account
-    attr_reader :refresh
-
     def initialize(account:, refresh: false)
       @account = account
       @refresh = refresh
@@ -35,5 +33,10 @@ module Imap::Backup
         Account::FolderBackup.new(account: account, folder: folder, refresh: refresh).run
       end
     end
+
+    private
+
+    attr_reader :account
+    attr_reader :refresh
   end
 end

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

@@ -5,12 +5,10 @@ module Imap; end
 module Imap::Backup
   class Account; end
 
+  # Iterates over the account folders that are to be backed up
   class Account::BackupFolders
     include Enumerable
 
-    attr_reader :account
-    attr_reader :client
-
     def initialize(client:, account:)
       @client = client
       @account = account
@@ -46,5 +44,10 @@ module Imap::Backup
         block.call(folder)
       end
     end
+
+    private
+
+    attr_reader :account
+    attr_reader :client
   end
 end

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

@@ -10,9 +10,8 @@ module Imap; end
 module Imap::Backup
   class Account; end
 
+  # Returns an IMAP client set up for the supplied account
   class Account::ClientFactory
-    attr_reader :account
-
     def initialize(account:)
       @account = account
       @provider = nil
@@ -35,6 +34,8 @@ module Imap::Backup
 
     private
 
+    attr_reader :account
+
     def provider
       @provider ||= Email::Provider.for_address(account.username)
     end

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

@@ -10,19 +10,13 @@ module Imap; end
 module Imap::Backup
   class Account; end
 
-  class FolderNotFound < StandardError; end
-
+  # Handles access to a folder on an IMAP server
   class Account::Folder
+    class FolderNotFound < StandardError; end
+
     extend Forwardable
     include RetryOnError
 
-    BODY_ATTRIBUTE = "BODY[]".freeze
-    UID_FETCH_RETRY_CLASSES = [::EOFError, ::Errno::ECONNRESET, ::IOError].freeze
-    APPEND_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
-    CREATE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
-    EXAMINE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
-    PERMITTED_FLAGS = %i(Answered Draft Flagged Seen).freeze
-
     attr_reader :client
     attr_reader :name
 
@@ -156,6 +150,13 @@ module Imap::Backup
 
     private
 
+    BODY_ATTRIBUTE = "BODY[]".freeze
+    UID_FETCH_RETRY_CLASSES = [::EOFError, ::Errno::ECONNRESET, ::IOError].freeze
+    APPEND_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
+    CREATE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
+    EXAMINE_RETRY_CLASSES = [::Net::IMAP::BadResponseError].freeze
+    PERMITTED_FLAGS = %i(Answered Draft Flagged Seen).freeze
+
     def examine
       client.examine(utf7_encoded_name)
     rescue Net::IMAP::NoResponseError

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

@@ -10,11 +10,8 @@ module Imap; end
 module Imap::Backup
   class Account; end
 
+  # Runs a backup for a single account folder
   class Account::FolderBackup
-    attr_reader :account
-    attr_reader :folder
-    attr_reader :refresh
-
     def initialize(account:, folder:, refresh: false)
       @account = account
       @folder = folder
@@ -38,6 +35,10 @@ module Imap::Backup
 
     private
 
+    attr_reader :account
+    attr_reader :folder
+    attr_reader :refresh
+
     def folder_ok?
       begin
         return false if !folder.exist?

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

@@ -6,9 +6,8 @@ module Imap; end
 module Imap::Backup
   class Account; end
 
+  # Handles creation of directories for backup storage
   class Account::FolderEnsurer
-    attr_reader :account
-
     def initialize(account:)
       @account = account
     end
@@ -22,5 +21,9 @@ module Imap::Backup
         permissions: Serializer::Directory::DIRECTORY_PERMISSIONS
       ).run
     end
+
+    private
+
+    attr_reader :account
   end
 end

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

@@ -6,10 +6,10 @@ module Imap; end
 module Imap::Backup
   class Account; end
 
-  # Deletes serialized folders that are not configured to be backed up
+  # Deletes serialized folders that are not configured to be backed up.
+  # This is used in mirror mode, where local copies are only kept as long as they
+  # exist on the server.
   class Account::LocalOnlyFolderDeleter
-    attr_reader :account
-
     def initialize(account:)
       @account = account
     end
@@ -24,5 +24,9 @@ module Imap::Backup
         serializer.delete if !wanted.include?(serializer.folder)
       end
     end
+
+    private
+
+    attr_reader :account
   end
 end

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

@@ -6,9 +6,8 @@ module Imap; end
 module Imap::Backup
   class Account; end
 
+  # Restores all backed up folders to the server
   class Account::Restore
-    attr_reader :account
-
     def initialize(account:)
       @account = account
     end
@@ -19,5 +18,9 @@ module Imap::Backup
         Uploader.new(folder, serializer).run
       end
     end
+
+    private
+
+    attr_reader :account
   end
 end

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

@@ -9,11 +9,10 @@ module Imap; end
 module Imap::Backup
   class Account; end
 
+  # Enumerates over the folders that are backed up to an account
   class Account::SerializedFolders
     include Enumerable
 
-    attr_reader :account
-
     def initialize(account:)
       @account = account
     end
@@ -31,6 +30,8 @@ module Imap::Backup
 
     private
 
+    attr_reader :account
+
     def base
       @base ||= Pathname.new(account.local_path)
     end

data/lib/imap/backup/account.rb

@@ -6,19 +6,62 @@ require "imap/backup/account/restore"
 module Imap; end
 
 module Imap::Backup
+  # Contains the attributes relating to an email account.
   class Account
+    # By default, the backup process fetches one email at a time
     DEFAULT_MULTI_FETCH_SIZE = 1
 
+    # The username of the account (usually the same as the email address)
+    # @return [String]
     attr_reader :username
+    # The password of the Account
     attr_reader :password
+    # The path where backups will be saved
+    # @return [String]
     attr_reader :local_path
+    # @overload folders
+    #   The list of folders that have been configured for the Account
+    #   @see #folder_blacklist how this list is interpreted.
+    #   @return [Array<String>, void]
+    # @overload folders=(value)
+    #   Sets the folders attribute and marks it as modified, storing the original value
+    #   @param value [Array<String>] a list of folders
+    #   @return [void]
     attr_reader :folders
+    # Indicates whether the configured folders are a whitelist or a blacklist.
+    # When true, any folders attribute will be taken as a list of folders to
+    # skip when running backups.
+    # When false, the folders attribute is used as the list of folders to backup.
+    # If no folders are configured, all folders on the server are backed up
+    # irrespective of the folder_blacklist setting
+    # @return [Boolean]
     attr_reader :folder_blacklist
+    # Should all emails be backed up progressively, or should emails
+    # which are deleted from the server be deleted locally?
     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
+    # Should 'Seen' flags be cached before fetchiong emails and
+    # rewritten to the server afterwards?
+    #
+    # Some IMAP providers, notably Apple Mail, set the '\Seen' flag
+    # on emails when they are fetched. By setting `:reset_seen_flags_after_fetch`,
+    # a workaround is activated which checks which emails are 'unseen' before
+    # and after the fetch, and removes the '\Seen' flag from those which have changed.
+    # As this check is susceptible to 'race conditions', i.e. when a different
+    # client sets the '\Seen' flag while imap-backup is fetching, it is best
+    # to only use it when required (i.e. for IMAP providers which always
+    # 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)
@@ -38,23 +81,39 @@ module Imap::Backup
       @marked_for_deletion = false
     end
 
+    # Initializes a client for the account's IMAP server
+    #
+    # @return [Account::Client::Default] the client
     def client
       @client ||= Account::ClientFactory.new(account: self).run
     end
 
+    # Returns the namespaces configured for the account on the IMAP server
+    #
+    # @return [Array<String>] the namespaces
     def namespaces
       client.namespace
     end
 
+    # Returns the capabilites of the IMAP server
+    #
+    # @return [Array<String>] the capabilities
     def capabilities
       client.capability
     end
 
+    # Restore the local backup to the server
+    #
+    # @return [void]
     def restore
       restore = Account::Restore.new(account: self)
       restore.run
     end
 
+    # Indicates whether the account has been configured, and is ready
+    # to be used
+    #
+    # @return [Boolean]
     def valid?
       username && password ? true : false
     end
@@ -63,18 +122,28 @@ module Imap::Backup
       changes.any?
     end
 
+    # Resets the store of changes, indicating that the current state is the saved state
     def clear_changes
       @changes = {}
     end
 
+    # Sets a flag indicating the Account should be excluded from the next save operation
+    #
+    # @return [void]
     def mark_for_deletion
       @marked_for_deletion = true
     end
 
+    # Indicates whether the account has been flagged for deletion during setup
+    #
+    # @return [Boolean]
     def marked_for_deletion?
       @marked_for_deletion
     end
 
+    # Returns all Account data for serialization
+    #
+    # @return [Hash]
     def to_h
       h = {username: @username, password: @password}
       h[:local_path] = @local_path if @local_path
@@ -90,14 +159,23 @@ module Imap::Backup
       h
     end
 
+    # Sets the username attribute and marks it as modified, storing the original value
+    #
+    # @return [void]
     def username=(value)
       update(:username, value)
     end
 
+    # Sets the password attribute and marks it as modified, storing the original value
+    #
+    # @return [void]
     def password=(value)
       update(:password, value)
     end
 
+    # Sets the local_path attribute and marks it as modified, storing the original value
+    #
+    # @return [void]
     def local_path=(value)
       update(:local_path, value)
     end
@@ -130,6 +208,9 @@ module Imap::Backup
       update(:connection_options, parsed)
     end
 
+    # The number of emails to fetch from the IMAP server at a time
+    #
+    # @return [Integer]
     def multi_fetch_size
       @multi_fetch_size ||= begin
         int = @multi_fetch_size_orignal.to_i
@@ -141,6 +222,10 @@ module Imap::Backup
       end
     end
 
+    # Sets the multi_fetch_size attribute and marks it as modified, storing the original value.
+    # If the supplied value is not a positive integer, uses {DEFAULT_MULTI_FETCH_SIZE}
+    #
+    # @return [void]
     def multi_fetch_size=(value)
       parsed = value.to_i
       parsed = DEFAULT_MULTI_FETCH_SIZE if !parsed.positive?

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

@@ -14,8 +14,6 @@ module Imap::Backup
     include Thor::Actions
     include CLI::Helpers
 
-    attr_reader :options
-
     def initialize(options)
       super([])
       @options = options
@@ -44,18 +42,22 @@ module Imap::Backup
         end
         exit(exit_code) if exit_code
       end
+    end
 
-      def refresh
-        options.key?(:refresh) ? !!options[:refresh] : false
-      end
+    private
 
-      def choose_exit_code(exception)
-        case exception
-        when Net::IMAP::NoResponseError, Errno::ECONNREFUSED
-          111
-        else
-          1
-        end
+    attr_reader :options
+
+    def refresh
+      options.key?(:refresh) ? !!options[:refresh] : false
+    end
+
+    def choose_exit_code(exception)
+      case exception
+      when Net::IMAP::NoResponseError, Errno::ECONNREFUSED
+        111
+      else
+        1
       end
     end
   end

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

@@ -10,11 +10,6 @@ module Imap::Backup
   class CLI < Thor; end
 
   class CLI::FolderEnumerator
-    attr_reader :destination
-    attr_reader :destination_delimiter
-    attr_reader :source
-    attr_reader :source_delimiter
-
     def initialize(
       destination:,
       source:,
@@ -45,6 +40,11 @@ module Imap::Backup
 
     private
 
+    attr_reader :destination
+    attr_reader :destination_delimiter
+    attr_reader :source
+    attr_reader :source_delimiter
+
     def destination_prefix_clipped
       @destination_prefix_clipped ||=
         if @destination_prefix.end_with?(destination_delimiter)

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

@@ -13,8 +13,6 @@ module Imap::Backup
   class CLI::Local::Check
     include CLI::Helpers
 
-    attr_reader :options
-
     def initialize(options)
       @options = options
     end
@@ -48,6 +46,10 @@ module Imap::Backup
       end
     end
 
+    private
+
+    attr_reader :options
+
     def print_check_results_as_json(results)
       Kernel.puts results.to_json
     end