Class: Imap::Backup::Account

Inherits:
Object
  • Object
show all
Defined in:
lib/imap/backup/account.rb,
lib/imap/backup/account/backup.rb,
lib/imap/backup/account/folder.rb,
lib/imap/backup/account/locker.rb,
lib/imap/backup/account/restore.rb,
lib/imap/backup/account/folder_backup.rb,
lib/imap/backup/account/folder_mapper.rb,
lib/imap/backup/account/backup_folders.rb,
lib/imap/backup/account/client_factory.rb,
lib/imap/backup/account/serialized_folders.rb,
lib/imap/backup/account/local_only_folder_deleter.rb

Overview

Contains the attributes relating to an email account.

Defined Under Namespace

Classes: Backup, BackupFolders, ClientFactory, Folder, FolderBackup, FolderMapper, LocalOnlyFolderDeleter, Locker, Restore, SerializedFolders

Constant Summary collapse

DEFAULT_MULTI_FETCH_SIZE =

By default, the backup process fetches one email at a time

1

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Account

Returns a new instance of Account.

Parameters:

  • options (Hash) —

    Account attributes

  • opts (Hash) —

    a customizable set of options



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/imap/backup/account.rb', line 86

def initialize(options)
  check_options!(options)
  @username = options[:username]
  @password = options[:password]
  @local_path = options[:local_path]
  @folders = options[:folders]
  @folder_blacklist = options[:folder_blacklist] || false
  @mirror_mode = options[:mirror_mode] || false
  @server = options[:server]
  @connection_options = nil
  @supplied_connection_options = options[:connection_options]
  @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
end

Instance Attribute Details

#download_strategy ⇒ String

The name of the download strategy to adopt during backups

Returns:

  • (String) 


46
47
48
 
# File 'lib/imap/backup/account.rb', line 46

def download_strategy
  @download_strategy
end

#folder_blacklist ⇒ Boolean

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

Returns:

  • (Boolean) 


36
37
38
 
# File 'lib/imap/backup/account.rb', line 36

def folder_blacklist
  @folder_blacklist
end

#folders ⇒ Array<String>, void #folders=(value) ⇒ void

Overloads:

  • #folders ⇒ Array<String>, void

    The list of folders that have been configured for the Account

    Returns:

    • (Array<String>, void)

    See Also:

  • #folders=(value) ⇒ void

    This method returns an undefined value.

    Sets the folders attribute and marks it as modified, storing the original value

    Parameters:

    • value (Array<String>) —

      a list of folders



28
29
30
 
# File 'lib/imap/backup/account.rb', line 28

def folders
  @folders
end

#local_path ⇒ String

Returns the path where backups will be saved.

Returns:

  • (String) —

    the path where backups will be saved



19
20
21
 
# File 'lib/imap/backup/account.rb', line 19

def local_path
  @local_path
end

#mirror_mode ⇒ Boolean

Should all emails be backed up progressively, or should emails which are deleted from the server be deleted locally?

Returns:

  • (Boolean) 


40
41
42
 
# File 'lib/imap/backup/account.rb', line 40

def mirror_mode
  @mirror_mode
end

#password ⇒ String

Returns password of the Account.

Returns:

  • (String) —

    password of the Account



17
18
19
 
# File 'lib/imap/backup/account.rb', line 17

def password
  @password
end

#reset_seen_flags_after_fetch ⇒ Boolean

Should ‘Seen’ flags be cached before fetching 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).

Returns:

  • (Boolean) 


59
60
61
 
# File 'lib/imap/backup/account.rb', line 59

def reset_seen_flags_after_fetch
  @reset_seen_flags_after_fetch
end

#server ⇒ String

The address of the IMAP server

Returns:

  • (String) 


43
44
45
 
# File 'lib/imap/backup/account.rb', line 43

def server
  @server
end

#status ⇒ String

The status of the account - controls backup and migration behaviour “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.

Returns:

  • (String) —

    one of “active” (the default), “archived”, or “offline”



65
66
67
 
# File 'lib/imap/backup/account.rb', line 65

def status
  @status
end

#username ⇒ String

The username of the account (usually the same as the email address)

Returns:

  • (String) 


15
16
17
 
# File 'lib/imap/backup/account.rb', line 15

def username
  @username
end

Instance Method Details

#active? ⇒ Boolean

Returns true if the account is active.

Returns:

  • (Boolean) —

    true if the account is active



289
290
291
 
# File 'lib/imap/backup/account.rb', line 289

def active?
  @status == "active"
end

#archived? ⇒ Boolean

Returns true if the account is archived.

Returns:

  • (Boolean) —

    true if the account is archived



294
295
296
 
# File 'lib/imap/backup/account.rb', line 294

def archived?
  @status == "archived"
end

#available_for_backup? ⇒ Boolean

Returns true if the account is available for backup operations.

Returns:

  • (Boolean) —

    true if the account is available for backup operations



304
305
306
 
# File 'lib/imap/backup/account.rb', line 304

def available_for_backup?
  active?
end

#available_for_migration? ⇒ Boolean

Returns true if the account is available for migration operations.

Returns:

  • (Boolean) —

    true if the account is available for migration operations



309
310
311
 
# File 'lib/imap/backup/account.rb', line 309

def available_for_migration?
  active? || archived?
end

#capabilities ⇒ Array<String>

Returns the capabilites of the IMAP server

Returns:

  • (Array<String>) —

    the capabilities



123
124
125
 
# File 'lib/imap/backup/account.rb', line 123

def capabilities
  client.capability
end

#clear_changes ⇒ void

This method returns an undefined value.

Resets the store of changes, indicating that the current state is the saved state



133
134
135
 
# File 'lib/imap/backup/account.rb', line 133

def clear_changes
  @changes = {}
end

#client ⇒ Account::Client::Default

Initializes a client for the account’s IMAP server

Returns:

  • (Account::Client::Default) —

    the client



109
110
111
 
# File 'lib/imap/backup/account.rb', line 109

def client
  @client ||= ::ClientFactory.new(account: self).run
end

#connection_options ⇒ Hash, void

Extra options to be passed to the IMAP server when connecting

Returns:

  • (Hash, void) 


228
229
230
231
232
233
234
235
236
 
# File 'lib/imap/backup/account.rb', line 228

def connection_options
  @connection_options ||=
    case @supplied_connection_options
    when String
      JSON.parse(@supplied_connection_options, symbolize_names: true)
    else
      @supplied_connection_options
    end
end

#connection_options=(value) ⇒ void

This method returns an undefined value.



239
240
241
242
243
244
245
246
247
248
 
# File 'lib/imap/backup/account.rb', line 239

def connection_options=(value)
  # Ensure we've loaded the connection_options
  connection_options
  parsed = if value == ""
             nil
           else
             JSON.parse(value, symbolize_names: true)
           end
  update(:connection_options, parsed)
end

#files_path ⇒ Serializer::Files::Path

Returns the base files path for the account.

Returns:



191
192
193
 
# File 'lib/imap/backup/account.rb', line 191

def files_path
  Serializer::Files::Path.new(base_path: local_path, folder_name: nil)
end

#lockfile_path ⇒ String

Returns the path to the lockfile for the account.

Returns:

  • (String) —

    the path to the lockfile for the account

Raises:

  • (RuntimeError) —

    if the local_path is not set



197
198
199
200
201
 
# File 'lib/imap/backup/account.rb', line 197

def lockfile_path
  raise "local_path is not set" if !local_path

  File.join(local_path, "imap-backup.lock")
end

#mark_for_deletion ⇒ void

This method returns an undefined value.

Sets a flag indicating the Account should be excluded from the next save operation



140
141
142
 
# File 'lib/imap/backup/account.rb', line 140

def mark_for_deletion
  @marked_for_deletion = true
end

#marked_for_deletion? ⇒ Boolean

Returns whether the account has been flagged for deletion during setup.

Returns:

  • (Boolean) —

    whether the account has been flagged for deletion during setup



145
146
147
 
# File 'lib/imap/backup/account.rb', line 145

def marked_for_deletion?
  @marked_for_deletion
end

#modified? ⇒ Boolean

Returns:

  • (Boolean) 


127
128
129
 
# File 'lib/imap/backup/account.rb', line 127

def modified?
  changes.any?
end

#multi_fetch_size ⇒ Integer

The number of emails to fetch from the IMAP server at a time

Returns:

  • (Integer) 


253
254
255
256
257
258
 
# File 'lib/imap/backup/account.rb', line 253

def multi_fetch_size
  @multi_fetch_size ||= begin
    int = @multi_fetch_size_orignal.to_i
    int.positive? ? int : DEFAULT_MULTI_FETCH_SIZE
  end
end

#multi_fetch_size=(value) ⇒ void

This method returns an undefined value.

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



264
265
266
267
268
 
# File 'lib/imap/backup/account.rb', line 264

def multi_fetch_size=(value)
  parsed = value.to_i
  parsed = DEFAULT_MULTI_FETCH_SIZE if !parsed.positive?
  update(:multi_fetch_size, parsed)
end

#namespaces ⇒ Array<String>

Returns the namespaces configured for the account on the IMAP server

Returns:

  • (Array<String>) —

    the namespaces



116
117
118
 
# File 'lib/imap/backup/account.rb', line 116

def namespaces
  client.namespace
end

#offline? ⇒ Boolean

Returns true if the account is offline.

Returns:

  • (Boolean) —

    true if the account is offline



299
300
301
 
# File 'lib/imap/backup/account.rb', line 299

def offline?
  @status == "offline"
end

#to_h ⇒ Hash

Returns all Account data for serialization.

Returns:

  • (Hash) —

    all Account data for serialization



150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/imap/backup/account.rb', line 150

def to_h
  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
  h[:mirror_mode] = true if mirror_mode
  h[:server] = server if server
  h[:connection_options] = connection_options if connection_options
  h[:multi_fetch_size] = multi_fetch_size
  if reset_seen_flags_after_fetch
    h[:reset_seen_flags_after_fetch] = reset_seen_flags_after_fetch
  end
  h
end