imap-backup 4.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85e081f686a106384d27ffc91cb21965832edd629da671261bda69b668776d5e
-  data.tar.gz: 8253587491a279e76ebed2268a66b60d9aab4f517cdafadb8c9494e7c3f3648b
+  metadata.gz: 97ae9089aa19dee6fcf7a1c211091671a6befe882d5b664654a25d6d10e81704
+  data.tar.gz: 2677746ed662c457a738033224da11a40a76367e4031e7636b33391d51ee4659
 SHA512:
-  metadata.gz: e2b3806cedfe124c286477f50690781c4593db1f3b12d53281c666d3d5771f9a42aa4cc24851fb88f9205a2f11a8e299c74a331a606de1aab056e56b753e3cf1
-  data.tar.gz: fc96edce37dd33793d04da272f2aea087ad7a16aa409726c83d6cf453bd386e3673a75b8d4e0eee90f352fc1e9168d611865dd87f79c05ff0cf132278bf59df3
+  metadata.gz: 5e97ba8ab64e27924166609c1cb80e52dbfa8136b4248324a7589e143d64ebddbb415ad6c4c7a0e472732db55c717d14e08be47c7640efcb36029c80b10938ef
+  data.tar.gz: 2fd74f2b86946b79d07a1354a55b00444022838fcd4968a6a2f0dc15494f4c2d80d0ea06b1e0290b921e7f2242566a56fb8e9bd6bf03b5a88595871c91d08604

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
@@ -178,6 +178,7 @@ If you have problems:
   "debug": true
 }
 ```
+
 # Restore
 
 All missing messages are pushed to the IMAP server.
@@ -206,48 +207,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,60 @@
+# 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
+```
+
+## 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
+
+REQUESTED_ATTRIBUTES = ["RFC822", "FLAGS", "INTERNALDATE"].freeze
+fetch_data_items = imap.uid_fetch(uids, REQUESTED_ATTRIBUTES)
+```
+
+# 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,21 +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.extra_rdoc_files += Dir.glob("README.md")
+  gem.extra_rdoc_files += Dir.glob("docs/*.md")
+  gem.rdoc_options = ["--main", "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"

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

@@ -10,7 +10,6 @@ module Imap::Backup::CLI::Helpers
       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

@@ -28,7 +28,7 @@ module Imap::Backup
       raise "#{email} is not a configured account" if !account
 
       account_connection = Imap::Backup::Account::Connection.new(account)
-      folder_serializer, folder = account_connection.local_folders.find do |(_s, f)|
+      folder_serializer, _folder = account_connection.local_folders.find do |(_s, f)|
         f.name == folder_name
       end
       raise "Folder '#{folder_name}' not found" if !folder_serializer
@@ -74,9 +74,9 @@ module Imap::Backup
       folder_serializer.each_message(uid_list).each do |uid, message|
         if uid_list.count > 1
           puts <<~HEADER
-            #{"-" * 80}
-            #{format("| UID: %-71s |", uid)}
-            #{"-" * 80}
+            #{'-' * 80}
+            #{format('| UID: %-71s |', uid)}
+            #{'-' * 80}
           HEADER
         end
         puts message.supplied_body

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
 

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

@@ -0,0 +1,41 @@
+module Imap::Backup
+  class CLI::Utils < Thor
+    include Thor::Actions
+
+    FAKE_EMAIL = "fake@email.com"
+
+    desc "ignore-history EMAIL", "Skip downloading emails up to today for all configured folders"
+    def ignore_history(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 = Imap::Backup::Account::Connection.new(account)
+
+      connection.local_folders.each do |_s, f|
+        next if !folder.exist?
+        do_ignore_folder_history(connection, folder)
+      end
+    end
+
+    no_commands do
+      def do_ignore_folder_history(connection, folder)
+        serializer = Imap::Backup::Serializer::Mbox.new(connection.local_path, folder.name)
+        uids = folder.uids - serializer.uids
+        Imap::Backup.logger.info "Folder '#{folder.name}' - #{uids.length} messages"
+
+        serializer.apply_uid_validity(folder.uid_validity)
+
+        uids.each do |uid|
+          message = <<~MESSAGE
+            From: #{FAKE_EMAIL}
+            Subject: Message #{uid} not backed up
+            Skipped #{uid}
+          MESSAGE
+
+          serializer.save(uid, message)
+        end
+      end
+    end
+  end
+end

data/lib/imap/backup/cli.rb

@@ -13,6 +13,7 @@ module Imap::Backup
     autoload :Restore, "imap/backup/cli/restore"
     autoload :Setup, "imap/backup/cli/setup"
     autoload :Status, "imap/backup/cli/status"
+    autoload :Utils, "imap/backup/cli/utils"
 
     include Helpers
 
@@ -73,7 +74,7 @@ module Imap::Backup
       Configure email accounts to back up.
     DESC
     def setup
-      Setup.new().run
+      Setup.new.run
     end
 
     desc "status", "Show backup status"
@@ -87,5 +88,8 @@ module Imap::Backup
 
     desc "local SUBCOMMAND [OPTIONS]", "View local info"
     subcommand "local", Local
+
+    desc "utils SUBCOMMAND [OPTIONS]", "Various utilities"
+    subcommand "utils", Utils
   end
 end

data/lib/imap/backup/version.rb

@@ -3,7 +3,7 @@ module Imap; end
 module Imap::Backup
   MAJOR    = 4
   MINOR    = 0
-  REVISION = 0
+  REVISION = 1
   PRE      = nil
   VERSION  = [MAJOR, MINOR, REVISION, PRE].compact.map(&:to_s).join(".")
 end

data/spec/spec_helper.rb

@@ -15,5 +15,6 @@ SimpleCov.start do
 end
 
 require "imap/backup"
+require "imap/backup/cli"
 
 silence_logging

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: imap-backup
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.0.1
 platform: ruby
 authors:
 - Joe Yates
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-11-22 00:00:00.000000000 Z
+date: 2021-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: highline
@@ -156,12 +156,16 @@ email:
 executables:
 - imap-backup
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
+- docs/setup.md
+- docs/restore.md
+- docs/development.md
 files:
 - LICENSE
 - README.md
 - bin/imap-backup
-- docs/docker-imap.md
+- docs/development.md
 - docs/restore.md
 - docs/setup.md
 - imap-backup.gemspec
@@ -178,6 +182,7 @@ files:
 - lib/imap/backup/cli/restore.rb
 - lib/imap/backup/cli/setup.rb
 - lib/imap/backup/cli/status.rb
+- lib/imap/backup/cli/utils.rb
 - lib/imap/backup/configuration/account.rb
 - lib/imap/backup/configuration/asker.rb
 - lib/imap/backup/configuration/connection_tester.rb
@@ -231,7 +236,9 @@ licenses:
 - MIT
 metadata: {}
 post_install_message: 
-rdoc_options: []
+rdoc_options:
+- "--main"
+- README.md
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
@@ -250,35 +257,35 @@ signing_key:
 specification_version: 4
 summary: Backup GMail (or other IMAP) accounts to disk
 test_files:
-- spec/features/backup_spec.rb
-- spec/features/helper.rb
-- spec/features/restore_spec.rb
-- spec/features/support/backup_directory.rb
-- spec/features/support/email_server.rb
-- spec/features/support/shared/connection_context.rb
-- spec/features/support/shared/message_fixtures.rb
-- spec/fixtures/connection.yml
-- spec/gather_rspec_coverage.rb
 - spec/spec_helper.rb
-- spec/support/fixtures.rb
-- spec/support/higline_test_helpers.rb
-- spec/support/shared_examples/account_flagging.rb
-- spec/support/silence_logging.rb
-- spec/unit/email/mboxrd/message_spec.rb
-- spec/unit/email/provider_spec.rb
-- spec/unit/imap/backup/account/connection_spec.rb
-- spec/unit/imap/backup/account/folder_spec.rb
+- spec/unit/imap/backup_spec.rb
 - spec/unit/imap/backup/configuration/account_spec.rb
-- spec/unit/imap/backup/configuration/asker_spec.rb
-- spec/unit/imap/backup/configuration/connection_tester_spec.rb
-- spec/unit/imap/backup/configuration/folder_chooser_spec.rb
 - spec/unit/imap/backup/configuration/list_spec.rb
+- spec/unit/imap/backup/configuration/connection_tester_spec.rb
 - spec/unit/imap/backup/configuration/setup_spec.rb
+- spec/unit/imap/backup/configuration/asker_spec.rb
+- spec/unit/imap/backup/configuration/folder_chooser_spec.rb
 - spec/unit/imap/backup/configuration/store_spec.rb
-- spec/unit/imap/backup/downloader_spec.rb
-- spec/unit/imap/backup/serializer/mbox_enumerator_spec.rb
 - spec/unit/imap/backup/serializer/mbox_spec.rb
 - spec/unit/imap/backup/serializer/mbox_store_spec.rb
+- spec/unit/imap/backup/serializer/mbox_enumerator_spec.rb
+- spec/unit/imap/backup/downloader_spec.rb
 - spec/unit/imap/backup/uploader_spec.rb
+- spec/unit/imap/backup/account/folder_spec.rb
+- spec/unit/imap/backup/account/connection_spec.rb
 - spec/unit/imap/backup/utils_spec.rb
-- spec/unit/imap/backup_spec.rb
+- spec/unit/email/mboxrd/message_spec.rb
+- spec/unit/email/provider_spec.rb
+- spec/features/backup_spec.rb
+- spec/features/helper.rb
+- spec/features/restore_spec.rb
+- spec/features/support/email_server.rb
+- spec/features/support/backup_directory.rb
+- spec/features/support/shared/connection_context.rb
+- spec/features/support/shared/message_fixtures.rb
+- spec/support/fixtures.rb
+- spec/support/silence_logging.rb
+- spec/support/higline_test_helpers.rb
+- spec/support/shared_examples/account_flagging.rb
+- spec/fixtures/connection.yml
+- spec/gather_rspec_coverage.rb

data/docs/docker-imap.md

@@ -1,18 +0,0 @@
-# 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
-
-REQUESTED_ATTRIBUTES = ["RFC822", "FLAGS", "INTERNALDATE"].freeze
-fetch_data_items = imap.uid_fetch(uids, REQUESTED_ATTRIBUTES)
-```