imap-backup 16.0.0 → 16.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac22de1cd99aab34b9d478d2ad8727faf67bbac635cf6ef80335d27012328a29
-  data.tar.gz: 7b74833c6e1752c1a25a201d3e3f40a05f8b966bebe38796843ee4f133191aff
+  metadata.gz: 773e831319b208a930da663eae601d32236281104f4712960bfdb42dbc9d7794
+  data.tar.gz: 0da5b5f25c8e89022b387f08e5a5bee101284067fa6c5b9db7b35c95890e92da
 SHA512:
-  metadata.gz: b0147bfef559ef12c9f6b3e41eced66cade0de85fa418bafb81eed6cfa06bd6e751d818cb8d058768a8259e69526c2a90aa504389a188146722f66f2d2671b2c
-  data.tar.gz: 6b48724665aa1383094053164de511e2bcfd1b3bf2b32d28bf659740e96e1e5f32a9dc37af32ec6cb0fd23fb06bd863d567ca78135bac27bb2662d6b6b6f5118
+  metadata.gz: ccd49d19ec804c70c5aaaadcc40129ad8fcccf129c8de01c2c9e74cec0068bd2268fe6ea4e79f1d313539069e727891da9d0fc16e91a9e64c2301b00248204d8
+  data.tar.gz: 92553f44cf28d9c3a19b4cc3ff63fbd5a2dae59056663e9222ba0481ac6768d77f91c33e6d2aec652e451fbc1a5c9ae8f3933fcc2b9d601a5d3ce04865720af3

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

@@ -1,9 +1,7 @@
 require "socket"
 
-require "imap/backup/client/apple_mail"
 require "imap/backup/client/automatic_login_wrapper"
 require "imap/backup/client/default"
-require "imap/backup/email/provider"
 
 module Imap; end
 
@@ -14,39 +12,17 @@ module Imap::Backup
   class Account::ClientFactory
     def initialize(account:)
       @account = account
-      @provider = nil
-      @server = nil
     end
 
     # @return [Client::AutomaticLoginWrapper] a client for the account
     def run
-      options = provider_options
-      Logger.logger.debug(
-        "Creating IMAP instance: #{server}, options: #{options.inspect}"
-      )
-      client =
-        if provider.is_a?(Email::Provider::AppleMail)
-          Client::AppleMail.new(server, account, options)
-        else
-          Client::Default.new(server, account, options)
-        end
+      Logger.logger.debug("Creating IMAP instance")
+      client = Client::Default.new(account)
       Client::AutomaticLoginWrapper.new(client: client)
     end
 
     private
 
     attr_reader :account
-
-    def provider
-      @provider ||= Email::Provider.for_address(account.username)
-    end
-
-    def provider_options
-      provider.options.merge(account.connection_options || {})
-    end
-
-    def server
-      @server ||= account.server || provider.host
-    end
   end
 end

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

@@ -38,7 +38,6 @@ module Imap::Backup
       Logger.logger.debug "Folder '#{name}' exists"
       true
     rescue FolderNotFound
-      Logger.logger.debug "Folder '#{name}' does not exist"
       false
     end
 
@@ -189,9 +188,9 @@ module Imap::Backup
     def examine
       client.examine(utf7_encoded_name)
     rescue Net::IMAP::NoResponseError
-      Imap::Backup::Logger.logger.warn "Folder '#{name}' does not exist on server"
-      Imap::Backup::Logger.logger.warn caller.join("\n")
-      raise FolderNotFound, "Folder '#{name}' does not exist on server"
+      message = "Folder '#{name}' does not exist on server"
+      Imap::Backup::Logger.logger.warn message
+      raise FolderNotFound, message
     end
 
     def extract_uid(response)

data/lib/imap/backup/account.rb

@@ -44,7 +44,7 @@ module Imap::Backup
     # 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
+    # Should 'Seen' flags be cached before fetching emails and
     # rewritten to the server afterwards?
     #
     # Some IMAP providers, notably Apple Mail, set the '\Seen' flag
@@ -57,6 +57,12 @@ module Imap::Backup
     # mark messages as '\Seen' when accessed).
     # @return [Boolean]
     attr_reader :reset_seen_flags_after_fetch
+    # The status of the account - controls backup and migration behavior
+    # "active" - the account is available for backup and migration,
+    # "archived" - the account is available for migration, but not backup,
+    # "offline" - the account is not available for backup or migration.
+    # @return [String] one of "active" (the default), "archived", or "offline"
+    attr_reader :status
 
     def initialize(options)
       check_options!(options)
@@ -72,6 +78,7 @@ module Imap::Backup
       @download_strategy = options[:download_strategy]
       @multi_fetch_size_orignal = options[:multi_fetch_size]
       @reset_seen_flags_after_fetch = options[:reset_seen_flags_after_fetch]
+      @status = options[:status] || DEFAULT_STATUS
       @client = nil
       @changes = {}
       @marked_for_deletion = false
@@ -122,7 +129,11 @@ module Imap::Backup
 
     # @return [Hash] all Account data for serialization
     def to_h
-      h = {username: @username, password: @password}
+      h = {
+        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
@@ -211,11 +222,7 @@ module Imap::Backup
     def multi_fetch_size
       @multi_fetch_size ||= begin
         int = @multi_fetch_size_orignal.to_i
-        if int.positive?
-          int
-        else
-          DEFAULT_MULTI_FETCH_SIZE
-        end
+        int.positive? ? int : DEFAULT_MULTI_FETCH_SIZE
       end
     end
 
@@ -234,6 +241,44 @@ module Imap::Backup
       update(:reset_seen_flags_after_fetch, value)
     end
 
+    # Sets the status attribute and marks it as modified, storing the original value
+    #
+    # @param value [String] one of "active", "archived", or "offline"
+    # @raise [ArgumentError] if the value is not a valid status
+    # @return [void]
+    def status=(value)
+      if !VALID_STATUSES.include?(value)
+        raise ArgumentError, "status must be one of: #{VALID_STATUSES.join(', ')}"
+      end
+
+      update(:status, value)
+    end
+
+    # @return [Boolean] true if the account is active
+    def active?
+      @status == "active"
+    end
+
+    # @return [Boolean] true if the account is archived
+    def archived?
+      @status == "archived"
+    end
+
+    # @return [Boolean] true if the account is offline
+    def offline?
+      @status == "offline"
+    end
+
+    # @return [Boolean] true if the account is available for backup operations
+    def available_for_backup?
+      active?
+    end
+
+    # @return [Boolean] true if the account is available for migration operations
+    def available_for_migration?
+      active? || archived?
+    end
+
     private
 
     attr_reader :changes
@@ -241,9 +286,11 @@ module Imap::Backup
     REQUIRED_ATTRIBUTES = %i[password username].freeze
     OPTIONAL_ATTRIBUTES = %i[
       connection_options download_strategy folders folder_blacklist local_path mirror_mode
-      multi_fetch_size reset_seen_flags_after_fetch server
+      multi_fetch_size reset_seen_flags_after_fetch server status
     ].freeze
     KNOWN_ATTRIBUTES = REQUIRED_ATTRIBUTES + OPTIONAL_ATTRIBUTES
+    VALID_STATUSES = %w[active archived offline].freeze
+    DEFAULT_STATUS = "active".freeze
 
     def check_options!(options)
       missing_required = REQUIRED_ATTRIBUTES - options.keys

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

@@ -28,6 +28,8 @@ module Imap::Backup
         config = load_config(**options)
         exit_code = nil
         accounts = requested_accounts(config)
+        # Filter to only include accounts available for backup
+        accounts = accounts.select(&:available_for_backup?)
         if accounts.none?
           Logger.logger.warn "No matching accounts found to backup"
           return

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

@@ -88,6 +88,16 @@ module Imap::Backup
       raise "Account '#{destination_email}' does not exist" if !destination_account
 
       raise "Account '#{source_email}' does not exist" if !source_account
+
+      if !source_account.available_for_migration?
+        raise "Account '#{source_email}' is not available for migration " \
+              "(status: #{source_account.status})"
+      end
+
+      return if destination_account.available_for_migration?
+
+      raise "Account '#{destination_email}' is not available for migration " \
+            "(status: #{destination_account.status})"
     end
 
     def choose_prefixes_and_delimiters!

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

@@ -1,6 +1,7 @@
 require "forwardable"
 require "net/imap"
 
+require "imap/backup/email/provider"
 require "imap/backup/logger"
 
 module Imap; end
@@ -17,10 +18,8 @@ module Imap::Backup
       responses uid_fetch uid_search uid_store
     )
 
-    def initialize(server, account, options)
+    def initialize(account)
       @account = account
-      @options = options
-      @server = server
       @state = nil
     end
 
@@ -32,7 +31,10 @@ module Imap::Backup
 
       return [] if mailbox_lists.nil?
 
-      mailbox_lists.map { |ml| extract_name(ml) }
+      ignored_tags = provider.folder_ignore_tags
+      mailbox_lists.
+        select { |ml| ml.attr & ignored_tags == [] }.
+        map { |ml| extract_name(ml) }
     end
 
     # Logs in to the account on the IMAP server
@@ -83,8 +85,6 @@ module Imap::Backup
     private
 
     attr_reader :account
-    attr_reader :options
-    attr_reader :server
     attr_accessor :state
 
     def imap
@@ -100,17 +100,36 @@ module Imap::Backup
       account.password.gsub(/./, "x")
     end
 
+    def provider
+      @provider ||= Email::Provider.for_address(account.username)
+    end
+
+    def options
+      @options ||= provider.options.merge(account.connection_options || {})
+    end
+
+    def server
+      @server ||= account.server || provider.host
+    end
+
     # 6.3.8. LIST Command
     # An empty ("" string) mailbox name argument is a special request to
     # return the hierarchy delimiter and the root name of the name given
     # in the reference.
     def provider_root
-      @provider_root ||= begin
-        Logger.logger.debug "Fetching provider root"
-        root_info = imap.list("", "")[0]
-        Logger.logger.debug "Provider root is '#{root_info.name}'"
-        root_info.name
-      end
+      @provider_root ||=
+        if provider.root
+          Logger.logger.debug "Using fixed provider root '#{provider.root}'"
+          provider.root
+        else
+          Logger.logger.debug "Fetching provider root"
+          result = imap.list("", "")
+          raise "IMAP server did not return root folder for #{account.username}" if result.empty?
+
+          root_info = result[0]
+          Logger.logger.debug "Provider root is '#{root_info.name}'"
+          root_info.name
+        end
     end
   end
 end

data/lib/imap/backup/downloader.rb

@@ -13,13 +13,15 @@ module Imap::Backup
       @serializer = serializer
       @multi_fetch_size = multi_fetch_size
       @reset_seen_flags_after_fetch = reset_seen_flags_after_fetch
+      @folder_uids = nil
+      @serializer_uids = nil
       @uids = nil
     end
 
     # Runs the downloader
     # @return [void]
     def run
-      debug("#{serializer_uids.count} already messages already downloaded")
+      debug("#{serializer_uids.count} messages already downloaded")
       debug("#{folder_uids.count} messages on server")
       local_only_count = (serializer_uids - folder_uids).count
       if local_only_count.positive?
@@ -33,15 +35,7 @@ module Imap::Backup
 
       info("#{uids.count} new messages")
 
-      uids.each_slice(multi_fetch_size).with_index do |block, i|
-        multifetch_failed = download_block(block, i)
-        raise MultiFetchFailedError if multifetch_failed
-      end
-    rescue MultiFetchFailedError
-      @count = nil
-      @multi_fetch_size = 1
-      @uids = nil
-      retry
+      download
     rescue Net::IMAP::ByeResponseError
       folder.client.reconnect
       retry
@@ -54,6 +48,21 @@ module Imap::Backup
     attr_reader :multi_fetch_size
     attr_reader :reset_seen_flags_after_fetch
 
+    def download
+      block_count = (uids.count / multi_fetch_size.to_f).ceil
+      uids.each_slice(multi_fetch_size).with_index do |block, i|
+        debug("Downloading #{block.count} messages (block #{i + 1}/#{block_count})")
+        multifetch_failed = download_block(block, i)
+        raise MultiFetchFailedError if multifetch_failed
+      end
+    rescue MultiFetchFailedError
+      @multi_fetch_size = 1
+      @uids = nil
+      @folder_uids = nil
+      @serializer_uids = nil
+      retry
+    end
+
     def download_block(block, index)
       uids_and_bodies =
         if reset_seen_flags_after_fetch

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

@@ -10,6 +10,11 @@ module Imap::Backup
       "imap.mail.me.com"
     end
 
+    # With Apple Mails's IMAP, passing "/" to list results in an empty list
+    def root
+      ""
+    end
+
     def sets_seen_flags_on_fetch?
       true
     end

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

@@ -6,11 +6,22 @@ module Imap::Backup
 
   # Supplies defaults for email provider behaviour
   class Email::Provider::Base
+    # @return [Array<Symbol>] tags to ignore when listing folders
+    def folder_ignore_tags
+      []
+    end
+
     # @return [Hash] defaults for the Net::IMAP connection
     def options
       {port: 993, ssl: {min_version: OpenSSL::SSL::TLS1_2_VERSION}}
     end
 
+    # By default, we query the server for this value.
+    # It is only fixed for Apple Mail accounts.
+    # @return [String, nil] any fixed value to use when requesting the list of account folders
+    def root
+    end
+
     def sets_seen_flags_on_fetch?
       false
     end

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

@@ -5,6 +5,11 @@ module Imap; end
 module Imap::Backup
   # Provides overrides for GMail accounts
   class Email::Provider::GMail < Email::Provider::Base
+    # https://imap-use.u.washington.narkive.com/RYMsOHTN/imap-protocol-status-on-a-noselect-mailbox
+    def folder_ignore_tags
+      [:Noselect]
+    end
+
     # @return [String] the GMail IMAP server host name
     def host
       "imap.gmail.com"

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

@@ -30,7 +30,8 @@ module Imap::Backup
         path,
         folders,
         multi_fetch,
-        reset_seen_flags_after_fetch
+        reset_seen_flags_after_fetch,
+        status_row
       ].compact
 
       menu.header = <<~HEADER.chomp
@@ -127,6 +128,12 @@ module Imap::Backup
       ["changes to unread flags will be reset during download"]
     end
 
+    def status_row
+      return nil if account.status == "active"
+
+      ["status", account.status]
+    end
+
     def format_rows(rows)
       largest_label, _value = rows.max_by do |(label, value)|
         if value

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

@@ -56,6 +56,7 @@ module Imap::Backup
         choose_folders menu
         modify_multi_fetch_size menu
         toggle_reset_seen_flags_after_fetch menu
+        rotate_status menu
         delete_account menu
         menu.choice("(q) return to main menu") { throw :done }
         menu.hidden("quit") { throw :done }
@@ -151,6 +152,19 @@ module Imap::Backup
       end
     end
 
+    def rotate_status(menu)
+      current_status = account.status
+      statuses = %w[active archived offline]
+      current_index = statuses.index(current_status) || 0
+      next_index = (current_index + 1) % statuses.length
+      next_status = statuses[next_index]
+
+      menu_item = "change status (currently: #{current_status} -> #{next_status})"
+      menu.choice(menu_item) do
+        account.status = next_status
+      end
+    end
+
     def test_connection(menu)
       menu.choice("test connection") do
         result = Setup::ConnectionTester.new(account).test

data/lib/imap/backup/version.rb

@@ -4,7 +4,7 @@ module Imap::Backup
   # @private
   MAJOR    = 16
   # @private
-  MINOR    = 0
+  MINOR    = 2
   # @private
   REVISION = 0
   # @private

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 16.0.0
+  version: 16.2.0
 platform: ruby
 authors:
 - Joe Yates
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-26 00:00:00.000000000 Z
+date: 2025-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -192,7 +192,6 @@ files:
 - lib/imap/backup/cli/stats.rb
 - lib/imap/backup/cli/transfer.rb
 - lib/imap/backup/cli/utils.rb
-- lib/imap/backup/client/apple_mail.rb
 - lib/imap/backup/client/automatic_login_wrapper.rb
 - lib/imap/backup/client/default.rb
 - lib/imap/backup/configuration.rb

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

@@ -1,15 +0,0 @@
-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
-  end
-end