imap-backup 4.0.0 → 4.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85e081f686a106384d27ffc91cb21965832edd629da671261bda69b668776d5e
-  data.tar.gz: 8253587491a279e76ebed2268a66b60d9aab4f517cdafadb8c9494e7c3f3648b
+  metadata.gz: 69ed28d85dda7c3d30cd6c8d4a9888e9f477eedd6f8ff08741fcc7d27cf087f8
+  data.tar.gz: 1a99e7143052a1d0b1b2d58381c5f9da0db2b1e0e3882c24e56036cebead043f
 SHA512:
-  metadata.gz: e2b3806cedfe124c286477f50690781c4593db1f3b12d53281c666d3d5771f9a42aa4cc24851fb88f9205a2f11a8e299c74a331a606de1aab056e56b753e3cf1
-  data.tar.gz: fc96edce37dd33793d04da272f2aea087ad7a16aa409726c83d6cf453bd386e3673a75b8d4e0eee90f352fc1e9168d611865dd87f79c05ff0cf132278bf59df3
+  metadata.gz: deb80ed5d629c81253574d96a7da0dcc6382eb6d5216c1f317b8083ca0f4dac80a3188cbc0b7f46ffbc01229dad9ab913858649558ca7b3a29bf7b81395bcce3
+  data.tar.gz: 2e6b2b8d2c67c6bc1e3ff5dcbb91c4eec92d0edb87ff33ad6e8a360b6635895c72cc7eb4cc68a7ff24bcfbad5a3533bda0a916e3c4d0c40ee67de70a010d4b2b

data/README.md

@@ -16,10 +16,6 @@
 [Rubygem]: http://rubygems.org/gems/imap-backup "Ruby gem at rubygems.org"
 [Continuous Integration]: https://circleci.com/gh/joeyates/imap-backup "Build status by CirceCI"
 
-# GMail
-
-To use imap-backup with GMail, you will need to enable 'App passwords' on your account.
-
 # Installation
 
 ```shell
@@ -51,6 +47,10 @@ Run:
 $ imap-backup setup
 ```
 
+## GMail
+
+To use imap-backup with GMail, you will need to enable 'App passwords' on your account.
+
 ## Folders
 
 By default, all folders are backed-up. You can override this by choosing
@@ -134,7 +134,15 @@ in the configuration file.
 
 The directory ~/.imap-backup, the configuration file and all backup
 directories have their access permissions set to only allow access
-by your user.
+by your user. This is not done on Windows - see below.
+
+## Windows
+
+Due to the complexity of managing permissions on Windows,
+directory and file access permissions are not set explicity.
+
+A pull request that implements permissions management on Windows
+would be welcome!
 
 # Run Backup
 
@@ -178,6 +186,7 @@ If you have problems:
   "debug": true
 }
 ```
+
 # Restore
 
 All missing messages are pushed to the IMAP server.
@@ -206,48 +215,7 @@ $ imap-backup status
 * Restartable - calculate start point based on already downloaded messages
 * Standalone - do not rely on an email client or MTA
 
-# Similar Software
-
-* https://github.com/OfflineIMAP/offlineimap
-
-# Testing
-
-## Integration Tests
-
-Integration tests (feature specs) are run against a Docker image
-(antespi/docker-imap-devel:latest).
-
-In one shell, run the Docker image:
-
-```sh
-$ docker run \
-  --env MAIL_ADDRESS=address@example.org \
-  --env MAIL_PASS=pass \
-  --env MAILNAME=example.org \
-  --publish 8993:993 \
-  antespi/docker-imap-devel:latest
-```
-
-```sh
-$ rake
-```
-
-To exclude Docker-based tests:
-
-```sh
-rake no-docker
-```
-
-or
-
-```sh
-$ rspec --tag ~docker
-```
-
-## Contributing
+# Documentation
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+* [Development](./docs/development.md)
+* [Restore](./docs/restore.md)

data/docs/development.md

@@ -0,0 +1,53 @@
+# Testing
+
+## Integration Tests
+
+Integration tests (feature specs) are run against a local IMAP server
+controlled by Docker Compose, which needs to be started
+before running the test suite.
+
+```sh
+$ docker-compose up -d
+```
+
+```sh
+$ rake
+```
+
+To exclude Docker-based tests:
+
+```sh
+rake no-docker
+```
+
+or
+
+```sh
+$ rspec --tag ~docker
+```
+
+## Access Docker imap server
+
+```ruby
+require "net/imap"
+
+imap = Net::IMAP.new("localhost", {port: 8993, ssl: {verify_mode: 0}})
+username = "address@example.org"
+imap.login(username, "pass")
+
+message = "From: #{username}\nSubject: Some Subject\n\nHello!\n"
+response = imap.append("INBOX", message, nil, nil)
+
+imap.examine("INBOX")
+uids = imap.uid_search(["ALL"]).sort
+
+fetch_data_items = imap.uid_fetch(uids, ["BODY[]"])
+```
+
+# Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/docs/restore.md

@@ -2,10 +2,27 @@
 
 # How does restore work?
 
+Backed-up emails are pushed to the IMAP server.
+If there are clashes, folders are renamed.
+
 # What are all these 'INBOX.12345' files?
 
+If, when the backup is launched, the IMAP server contains a folder with
+the same name, but different history to the local backup, the local
+emails cannot simply be added to the existing folder.
+
+In this case, a numeric suffix is added to the **local** folder,
+before it is restored.
+
+In this way, old and new emails are kept separate.
+
 # Will my email get overwritten?
 
+No.
+
+Emails are identified by folder and a specific email id. Any email that
+is already on the server is skipped.
+
 ## How do I restore to a different service?
 
 1. Run setup and add the new server, (but don't run any backups),

data/imap-backup.gemspec

@@ -1,6 +1,5 @@
 $LOAD_PATH.unshift(File.expand_path("lib", __dir__))
 require "imap/backup/version"
-require "rake/file_list"
 
 Gem::Specification.new do |gem|
   gem.name          = "imap-backup"
@@ -10,24 +9,22 @@ Gem::Specification.new do |gem|
   gem.email         = ["joe.g.yates@gmail.com"]
   gem.homepage      = "https://github.com/joeyates/imap-backup"
   gem.licenses      = ["MIT"]
+  gem.version       = Imap::Backup::VERSION
 
-  # Build list of files manually, see also
-  # https://github.com/rubygems/rubygems/blob/master/bundler/bundler.gemspec#L37
   gem.files         = %w[bin/imap-backup]
-  gem.files         += Dir.glob("docs/*{.png,.md}")
+  gem.files         += Dir.glob("docs/*.md")
   gem.files         += Dir.glob("lib/**/*.rb")
-  gem.files         += Dir.glob("spec/**/*{.rb,.yml}")
   gem.files         += %w[imap-backup.gemspec]
   gem.files         += %w[LICENSE README.md]
 
   gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
-  gem.test_files    = gem.files.grep(%r{^spec/})
+  gem.test_files    = Dir.glob("spec/**/*{.rb,.yml}")
   gem.require_paths = ["lib"]
   gem.required_ruby_version = ">= 2.5"
-  gem.version = Imap::Backup::VERSION
 
   gem.add_runtime_dependency "highline"
   gem.add_runtime_dependency "mail"
+  gem.add_runtime_dependency "os"
   gem.add_runtime_dependency "rake"
   gem.add_runtime_dependency "thor", "~> 1.1"
 

data/lib/email/mboxrd/message.rb

@@ -1,9 +1,13 @@
+require "forwardable"
 require "mail"
 
 module Email; end
 
 module Email::Mboxrd
   class Message
+    extend Forwardable
+    def_delegators :@parsed, :subject
+
     attr_reader :supplied_body
 
     def self.from_serialized(serialized)
@@ -36,12 +40,12 @@ module Email::Mboxrd
       supplied_body.gsub(/(?<!\r)\n/, "\r\n")
     end
 
+    private
+
     def parsed
       @parsed ||= Mail.new(supplied_body)
     end
 
-    private
-
     def from
       @from ||=
         begin

data/lib/email/provider/apple_mail.rb

@@ -0,0 +1,7 @@
+require "email/provider/default"
+
+class Email::Provider::AppleMail < Email::Provider::Default
+  def host
+    "imap.mail.me.com"
+  end
+end

data/lib/email/provider/default.rb

@@ -0,0 +1,12 @@
+module Email; end
+class Email::Provider; end
+
+class Email::Provider::Default
+  # We don't know how to guess the IMAP server
+  def host
+  end
+
+  def options
+    {port: 993, ssl: {ssl_version: :TLSv1_2}}
+  end
+end

data/lib/email/provider/fastmail.rb

@@ -0,0 +1,7 @@
+require "email/provider/default"
+
+class Email::Provider::Fastmail < Email::Provider::Default
+  def host
+    "imap.fastmail.com"
+  end
+end

data/lib/email/provider/gmail.rb

@@ -0,0 +1,7 @@
+require "email/provider/default"
+
+class Email::Provider::GMail < Email::Provider::Default
+  def host
+    "imap.gmail.com"
+  end
+end

data/lib/email/provider.rb

@@ -1,37 +1,27 @@
+require "email/provider/default"
+require "email/provider/apple_mail"
+require "email/provider/fastmail"
+require "email/provider/gmail"
+
 module Email; end
 
 class Email::Provider
-  GMAIL_IMAP_SERVER = "imap.gmail.com".freeze
-
   def self.for_address(address)
     case
     when address.end_with?("@fastmail.com")
-      new(:fastmail)
-    when address.end_with?("@gmail.com")
-      new(:gmail)
+      Email::Provider::Fastmail.new
     when address.end_with?("@fastmail.fm")
-      new(:fastmail)
+      Email::Provider::Fastmail.new
+    when address.end_with?("@gmail.com")
+      Email::Provider::GMail.new
+    when address.end_with?("@icloud.com")
+      Email::Provider::AppleMail.new
+    when address.end_with?("@mac.com")
+      Email::Provider::AppleMail.new
+    when address.end_with?("@me.com")
+      Email::Provider::AppleMail.new
     else
-      new(:default)
-    end
-  end
-
-  attr_reader :provider
-
-  def initialize(provider)
-    @provider = provider
-  end
-
-  def options
-    {port: 993, ssl: {ssl_version: :TLSv1_2}}
-  end
-
-  def host
-    case provider
-    when :gmail
-      GMAIL_IMAP_SERVER
-    when :fastmail
-      "imap.fastmail.com"
+      Email::Provider::Default.new
     end
   end
 end

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

@@ -1,4 +1,5 @@
-require "net/imap"
+require "imap/backup/client/apple_mail"
+require "imap/backup/client/default"
 
 require "retry_on_error"
 
@@ -29,17 +30,15 @@ module Imap::Backup
     def folders
       @folders ||=
         begin
-          root = provider_root
-          mailbox_lists = imap.list(root, "*")
+          folders = client.list
 
-          if mailbox_lists.nil?
+          if folders.empty?
             message = "Unable to get folder list for account #{username}"
             Imap::Backup.logger.info message
             raise message
           end
 
-          utf7_encoded = mailbox_lists.map(&:name)
-          utf7_encoded.map { |n| Net::IMAP.decode_utf7(n) }
+          folders
         end
     end
 
@@ -54,7 +53,7 @@ module Imap::Backup
     def run_backup
       Imap::Backup.logger.debug "Running backup of account: #{username}"
       # start the connection so we get logging messages in the right order
-      imap
+      client
       each_folder do |folder, serializer|
         next if !folder.exist?
 
@@ -89,34 +88,36 @@ module Imap::Backup
     end
 
     def disconnect
-      imap.disconnect if @imap
+      client.disconnect if @client
     end
 
     def reconnect
       disconnect
-      @imap = nil
+      @client = nil
     end
 
-    def imap
-      @imap ||=
+    def client
+      @client ||=
         retry_on_error(errors: LOGIN_RETRY_CLASSES) do
           options = provider_options
           Imap::Backup.logger.debug(
             "Creating IMAP instance: #{server}, options: #{options.inspect}"
           )
-          imap = Net::IMAP.new(server, options)
+          client =
+            if provider.is_a?(Email::Provider::AppleMail)
+              Client::AppleMail.new(server, options)
+            else
+              Client::Default.new(server, options)
+            end
           Imap::Backup.logger.debug "Logging in: #{username}/#{masked_password}"
-          imap.login(username, password)
+          client.login(username, password)
           Imap::Backup.logger.debug "Login complete"
-          imap
+          client
         end
     end
 
     def server
-      return @server if @server
-      return nil if provider.nil?
-
-      @server = provider.host
+      @server ||= provider.host
     end
 
     private
@@ -186,16 +187,5 @@ module Imap::Backup
     def provider_options
       provider.options.merge(connection_options)
     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
-      return @provider_root if @provider_root
-
-      root_info = imap.list("", "")[0]
-      @provider_root = root_info.name
-    end
   end
 end

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

@@ -11,13 +11,13 @@ module Imap::Backup
     extend Forwardable
     include RetryOnError
 
-    REQUESTED_ATTRIBUTES = %w[RFC822 FLAGS INTERNALDATE].freeze
+    BODY_ATTRIBUTE = "BODY[]".freeze
     UID_FETCH_RETRY_CLASSES = [EOFError].freeze
 
     attr_reader :connection
     attr_reader :name
 
-    delegate imap: :connection
+    delegate client: :connection
 
     def initialize(connection, name)
       @connection = connection
@@ -40,20 +40,20 @@ module Imap::Backup
     def create
       return if exist?
 
-      imap.create(utf7_encoded_name)
+      client.create(utf7_encoded_name)
     end
 
     def uid_validity
       @uid_validity ||=
         begin
           examine
-          imap.responses["UIDVALIDITY"][-1]
+          client.responses["UIDVALIDITY"][-1]
         end
     end
 
     def uids
       examine
-      imap.uid_search(["ALL"]).sort
+      client.uid_search(["ALL"]).sort
     rescue FolderNotFound
       []
     rescue NoMethodError
@@ -72,15 +72,14 @@ module Imap::Backup
       examine
       fetch_data_items =
         retry_on_error(errors: UID_FETCH_RETRY_CLASSES) do
-          imap.uid_fetch([uid.to_i], REQUESTED_ATTRIBUTES)
+          client.uid_fetch([uid.to_i], [BODY_ATTRIBUTE])
         end
       return nil if fetch_data_items.nil?
 
       fetch_data_item = fetch_data_items[0]
       attributes = fetch_data_item.attr
-      return nil if !attributes.key?("RFC822")
 
-      attributes
+      attributes[BODY_ATTRIBUTE]
     rescue FolderNotFound
       nil
     end
@@ -88,14 +87,14 @@ module Imap::Backup
     def append(message)
       body = message.imap_body
       date = message.date&.to_time
-      response = imap.append(utf7_encoded_name, body, nil, date)
+      response = client.append(utf7_encoded_name, body, nil, date)
       extract_uid(response)
     end
 
     private
 
     def examine
-      imap.examine(utf7_encoded_name)
+      client.examine(utf7_encoded_name)
     rescue Net::IMAP::NoResponseError
       Imap::Backup.logger.warn "Folder '#{name}' does not exist on server"
       raise FolderNotFound, "Folder '#{name}' does not exist on server"

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

@@ -5,12 +5,25 @@ module Imap::Backup::CLI::Helpers
     options.each.with_object({}) { |(k, v), acc| acc[k.intern] = v }
   end
 
+  def account(email)
+    connections = Imap::Backup::Configuration::List.new
+    account = connections.accounts.find { |a| a[:username] == email }
+    raise "#{email} is not a configured account" if !account
+
+    account
+  end
+
+  def connection(email)
+    account = account(email)
+
+    Imap::Backup::Account::Connection.new(account)
+  end
+
   def each_connection(names)
     begin
       connections = Imap::Backup::Configuration::List.new(names)
     rescue Imap::Backup::ConfigurationNotFound
       raise "imap-backup is not configured. Run `imap-backup setup`"
-      return
     end
 
     connections.each_connection do |connection|

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

@@ -6,49 +6,46 @@ module Imap::Backup
     desc "accounts", "List locally backed-up accounts"
     def accounts
       connections = Imap::Backup::Configuration::List.new
-      connections.accounts.each { |a| puts a[:username] }
+      connections.accounts.each { |a| Kernel.puts a[:username] }
     end
 
     desc "folders EMAIL", "List account folders"
     def folders(email)
-      connections = Imap::Backup::Configuration::List.new
-      account = connections.accounts.find { |a| a[:username] == email }
-      raise "#{email} is not a configured account" if !account
+      connection = connection(email)
 
-      account_connection = Imap::Backup::Account::Connection.new(account)
-      account_connection.local_folders.each do |_s, f|
-        puts %("#{f.name}")
+      connection.local_folders.each do |_s, f|
+        Kernel.puts %("#{f.name}")
       end
     end
 
     desc "list EMAIL FOLDER", "List emails in a folder"
     def list(email, folder_name)
-      connections = Imap::Backup::Configuration::List.new
-      account = connections.accounts.find { |a| a[:username] == email }
-      raise "#{email} is not a configured account" if !account
+      connection = connection(email)
 
-      account_connection = Imap::Backup::Account::Connection.new(account)
-      folder_serializer, folder = account_connection.local_folders.find do |(_s, f)|
+      folder_serializer, _folder = connection.local_folders.find do |(_s, f)|
         f.name == folder_name
       end
       raise "Folder '#{folder_name}' not found" if !folder_serializer
 
       max_subject = 60
-      puts format("%-10<uid>s  %-#{max_subject}<subject>s - %<date>s", {uid: "UID", subject: "Subject", date: "Date"})
-      puts "-" * (12 + max_subject + 28)
+      Kernel.puts format(
+        "%-10<uid>s  %-#{max_subject}<subject>s - %<date>s",
+        {uid: "UID", subject: "Subject", date: "Date"}
+      )
+      Kernel.puts "-" * (12 + max_subject + 28)
 
       uids = folder_serializer.uids
 
       folder_serializer.each_message(uids).map do |uid, message|
         m = {
           uid: uid,
-          date: message.parsed.date.to_s,
-          subject: message.parsed.subject || ""
+          date: message.date.to_s,
+          subject: message.subject || ""
         }
         if m[:subject].length > max_subject
-          puts format("% 10<uid>u: %.#{max_subject - 3}<subject>s... - %<date>s", m)
+          Kernel.puts format("% 10<uid>u: %.#{max_subject - 3}<subject>s... - %<date>s", m)
         else
-          puts format("% 10<uid>u: %-#{max_subject}<subject>s - %<date>s", m)
+          Kernel.puts format("% 10<uid>u: %-#{max_subject}<subject>s - %<date>s", m)
         end
       end
     end
@@ -60,12 +57,9 @@ module Imap::Backup
       the UID.
     DESC
     def show(email, folder_name, uids)
-      connections = Imap::Backup::Configuration::List.new
-      account = connections.accounts.find { |a| a[:username] == email }
-      raise "#{email} is not a configured account" if !account
+      connection = connection(email)
 
-      account_connection = Imap::Backup::Account::Connection.new(account)
-      folder_serializer, _folder = account_connection.local_folders.find do |(_s, f)|
+      folder_serializer, _folder = connection.local_folders.find do |(_s, f)|
         f.name == folder_name
       end
       raise "Folder '#{folder_name}' not found" if !folder_serializer
@@ -73,13 +67,13 @@ module Imap::Backup
       uid_list = uids.split(",")
       folder_serializer.each_message(uid_list).each do |uid, message|
         if uid_list.count > 1
-          puts <<~HEADER
-            #{"-" * 80}
-            #{format("| UID: %-71s |", uid)}
-            #{"-" * 80}
+          Kernel.puts <<~HEADER
+            #{'-' * 80}
+            #{format('| UID: %-71s |', uid)}
+            #{'-' * 80}
           HEADER
         end
-        puts message.supplied_body
+        Kernel.puts message.supplied_body
       end
     end
   end

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

@@ -1,7 +1,7 @@
 class Imap::Backup::CLI::Setup < Thor
   include Thor::Actions
 
-  def initialize()
+  def initialize
     super([])
   end