Class: Imap::Backup::Serializer::Imap

Inherits:
Object
  • Object
show all
Defined in:
lib/imap/backup/serializer/imap.rb

Overview

Stores message metadata

Constant Summary collapse

CURRENT_VERSION =

The version number to store in the metadata file

3

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(folder_path) ⇒ Imap

Returns a new instance of Imap.

Parameters:

  • folder_path (String) —

    The path of the imap metadata file, without the ‘.imap’ extension



21
22
23
24
25
26
27
28
 
# File 'lib/imap/backup/serializer/imap.rb', line 21

def initialize(folder_path)
  @folder_path = folder_path
  @loaded = false
  @uid_validity = nil
  @messages = nil
  @version = nil
  @tsx = nil
end

Instance Attribute Details

#folder_path ⇒ String (readonly)

Returns The path of the imap metadata file, without the ‘.imap’ extension.

Returns:

  • (String) —

    The path of the imap metadata file, without the ‘.imap’ extension



18
19
20
 
# File 'lib/imap/backup/serializer/imap.rb', line 18

def folder_path
  @folder_path
end

Instance Method Details

#append(uid, length, flags: []) ⇒ void

This method returns an undefined value.

Append message metadata

Parameters:

  • uid (Integer) —

    the message’s UID

  • length (Integer) —

    the length of the message (as stored on disk)

  • flags (Array[Symbol]) (defaults to: []) —

    the message’s flags



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/imap/backup/serializer/imap.rb', line 84

def append(uid, length, flags: [])
  offset =
    if messages.empty?
      0
    else
      last_message = messages[-1]
      last_message.offset + last_message.length
    end

  messages << Serializer::Message.new(
    uid: uid, offset: offset, length: length, mbox: mbox, flags: flags
  )

  save
end

#delete ⇒ void

This method returns an undefined value.

Deletes the metadata file and discards stored attributes



126
127
128
129
130
131
132
133
134
135
 
# File 'lib/imap/backup/serializer/imap.rb', line 126

def delete
  return if !exist?

  Logger.logger.info("Deleting metadata file '#{pathname}'")
  FileUtils.rm(pathname)
  @loaded = false
  @messages = nil
  @uid_validity = nil
  @version = nil
end

#exist? ⇒ Boolean

Returns:

  • (Boolean) 


67
68
69
 
# File 'lib/imap/backup/serializer/imap.rb', line 67

def exist?
  File.exist?(pathname)
end

#get(uid) ⇒ Serializer::Message

Get a copy of message metadata

Parameters:

  • uid (Integer) —

    a message UID

Returns:



118
119
120
121
 
# File 'lib/imap/backup/serializer/imap.rb', line 118

def get(uid)
  message = messages.find { |m| m.uid == uid }
  message&.dup
end

#messages ⇒ Array<Hash>

Returns:

  • (Array<Hash>) 


167
168
169
170
 
# File 'lib/imap/backup/serializer/imap.rb', line 167

def messages
  ensure_loaded
  @messages
end

#pathname ⇒ String

Returns The full path name of the metadata file.

Returns:

  • (String) —

    The full path name of the metadata file



63
64
65
 
# File 'lib/imap/backup/serializer/imap.rb', line 63

def pathname
  "#{folder_path}.imap"
end

#rename(new_path) ⇒ void

This method returns an undefined value.

Renames the metadata file, if it exists, otherwise, simply stores the new name

Parameters:

  • new_path (String) —

    the new path (without extension)



141
142
143
144
145
146
147
148
149
 
# File 'lib/imap/backup/serializer/imap.rb', line 141

def rename(new_path)
  if exist?
    old_pathname = pathname
    @folder_path = new_path
    File.rename(old_pathname, pathname)
  else
    @folder_path = new_path
  end
end

#rollback ⇒ void

This method returns an undefined value.

Discards stored changes to the data



53
54
55
56
57
58
59
60
 
# File 'lib/imap/backup/serializer/imap.rb', line 53

def rollback
  tsx.fail_outside_transaction!(:rollback)

  @messages = tsx.data[:savepoint][:messages]
  @uid_validity = tsx.data[:savepoint][:uid_validity]

  tsx.clear
end

#save ⇒ void

This method returns an undefined value.

Saves the file, except in a transaction when it does nothing

Raises:

  • (RuntimeError) —

    if UID validity has not been set



203
204
205
206
207
208
209
 
# File 'lib/imap/backup/serializer/imap.rb', line 203

def save
  return if tsx.in_transaction?

  ensure_loaded

  save_internal(version: version, uid_validity: uid_validity, messages: messages)
end

#transaction(&block) ⇒ void

This method returns an undefined value.

Opens a transaction

Parameters:

  • block (block) —

    the block that is wrapped by the transaction

Raises:

  • any exception ocurring in the block



34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/imap/backup/serializer/imap.rb', line 34

def transaction(&block)
  tsx.fail_in_transaction!(:transaction, message: "nested transactions are not supported")

  ensure_loaded
  # rubocop:disable Lint/RescueException
  tsx.begin({savepoint: {messages: messages.dup, uid_validity: uid_validity}}) do
    block.call

    save_internal(version: version, uid_validity: uid_validity, messages: messages) if tsx.data
  rescue Exception => e
    Logger.logger.error "#{self.class} handling #{e.class}"
    rollback
    raise e
  end
  # rubocop:enable Lint/RescueException
end

#uid_validity ⇒ Integer

Returns the UID validity for the folder.

Returns:

  • (Integer) —

    the UID validity for the folder



152
153
154
155
 
# File 'lib/imap/backup/serializer/imap.rb', line 152

def uid_validity
  ensure_loaded
  @uid_validity
end

#uid_validity=(value) ⇒ void

This method returns an undefined value.

Sets the folder’s UID validity and saves the metadata file

Parameters:

  • value (Integer) —

    the new UID validity



160
161
162
163
164
 
# File 'lib/imap/backup/serializer/imap.rb', line 160

def uid_validity=(value)
  ensure_loaded
  @uid_validity = value
  save
end

#uids ⇒ Array<Integer>

Returns The uids of all messages.

Returns:

  • (Array<Integer>) —

    The uids of all messages



173
174
175
 
# File 'lib/imap/backup/serializer/imap.rb', line 173

def uids
  messages.map(&:uid)
end

#update(uid, length: nil, flags: nil) ⇒ void

This method returns an undefined value.

Updates a message’s length and/or flags

Parameters:

  • uid (Integer) —

    the existing message’s UID

  • length (Integer) (defaults to: nil) —

    the length of the message (as stored on disk)

  • flags (Array[Symbol]) (defaults to: nil) —

    the message’s flags

Raises:

  • (RuntimeError) —

    if the UID does not exist



106
107
108
109
110
111
112
113
 
# File 'lib/imap/backup/serializer/imap.rb', line 106

def update(uid, length: nil, flags: nil)
  index = messages.find_index { |m| m.uid == uid }
  raise "UID #{uid} not found" if !index

  messages[index].length = length if length
  messages[index].flags = flags if flags
  save
end

#update_uid(old, new) ⇒ void

This method returns an undefined value.

Update a message’s UID

Parameters:

  • old (Integer) —

    the existing message UID

  • new (Integer) —

    the new UID to apply to the message

Raises:

  • (RuntimeError) —

    if the new UID already exists



182
183
184
185
186
187
188
189
190
191
 
# File 'lib/imap/backup/serializer/imap.rb', line 182

def update_uid(old, new)
  existing = messages.find_index { |m| m.uid == new }
  raise "UID #{new} already exists" if existing

  index = messages.find_index { |m| m.uid == old }
  return if index.nil?

  messages[index].uid = new
  save
end

#valid? ⇒ Boolean

Returns:

  • (Boolean) 


71
72
73
74
75
76
77
 
# File 'lib/imap/backup/serializer/imap.rb', line 71

def valid?
  return false if !exist?
  return false if version != CURRENT_VERSION
  return false if !uid_validity

  true
end

#version ⇒ String

Returns The format version for the metadata file.

Returns:

  • (String) —

    The format version for the metadata file



194
195
196
197
 
# File 'lib/imap/backup/serializer/imap.rb', line 194

def version
  ensure_loaded
  @version
end