-require 'common/plugin'
+require 'common/domain'
require 'common/filesystem'
+require 'common/plugin'
+require 'common/user'
+# Code that all Dovecot plugins ({DovecotPrune}, {DovecotRm}, and
+# {DovecotMv}) will share.
+#
module DovecotPlugin
- # Code that all Dovecot plugins (Prune, Rm, Mv...) will
- # share. That is, we implement the Plugin interface.
+
+ # We implement the Plugin "interface."
include Plugin
+
+ # Initialize this Dovecot {Plugin} with values in *cfg*.
+ #
+ # @param cfg [Configuration] the configuration for this plugin.
+ #
def initialize(cfg)
- @domain_root = cfg.mail_root
+ @domain_root = cfg.dovecot_mail_root
end
+ # Describe the given Dovecot domain by its filesystem path. The
+ # domain need not exist to obtain its path.
+ #
+ # @param domain [Domain] the {Domain} object whose description we want.
+ #
+ # @return [String] a String giving the path under which this domain's
+ # mailboxes would reside on the filesystem.
+ #
def describe_domain(domain)
- begin
- domain_path = get_domain_path(domain)
- return domain_path
- rescue NonexistentDomainError => e
- return "Doesn't exist: #{e.to_s}"
- end
+ return get_domain_path(domain)
end
+
+ # Describe the given Dovecot user by its filesystem mailbox
+ # path. The user need not exist to obtain its mailbox path.
+ #
+ # @param user [User] the {User} object whose description we want.
+ #
+ # @return [String] a String giving the path where this user's
+ # mailbox would reside on the filesystem.
+ #
def describe_user(user)
- begin
- user_path = get_user_path(user)
- return user_path
- rescue NonexistentUserError => e
- return "Doesn't exist: #{e.to_s}"
- end
+ return get_user_path(user)
end
protected;
+ # Return the filesystem path for the given {Domain} object.
+ #
+ # @param domain [Domain] the {Domain} whose path we want.
+ #
+ # @return [String] the filesystem path where this domain's mail
+ # would be located.
+ #
def get_domain_path(domain)
- # Return the filesystem path for the given domain.
- # That is, the directory where its mail is stored.
- # Only works if the domain directory exists!
- domain_path = File.join(@domain_root, domain)
-
- if File.directory?(domain_path)
- return domain_path
- else
- raise NonexistentDomainError.new(domain)
- end
+ return File.join(@domain_root, domain.to_s())
end
+ # Return the filesystem path of this {User}'s mailbox.
+ #
+ # @param user [User] the {User} whose mailbox path we want.
+ #
+ # @return [String] the filesystem path where this user's mail
+ # would be located.
+ #
def get_user_path(user)
- # Return the filesystem path of this user's mailbox.
- # Only works if the user exists!
- if not user.include?('@')
- msg = "#{user}: Users must contain an '@' symbol."
- raise InvalidUserError.new(msg)
- end
-
- user_parts = user.split('@')
- local_part = user_parts[0]
- domain_part = user_parts[1]
-
- begin
- domain_path = get_domain_path(domain_part)
- rescue NonexistentDomainError
- raise NonexistentUserError.new(user)
- end
-
- user_path = File.join(domain_path, local_part)
-
- if File.directory?(user_path)
- return user_path
- else
- raise NonexistentUserError.new(user)
- end
+ domain_path = get_domain_path(user.domain())
+ return File.join(domain_path, user.localpart())
end
+ # Produce a list of domains that exist in the Dovecot mailstore.
+ #
+ # @return [Array<Domain>] an array of {Domain} objects that have
+ # corresponding directories within the Dovecot mailstore.
+ #
def list_domains()
- return Filesystem.get_subdirs(@domain_root)
+ return Filesystem.get_subdirs(@domain_root).map{ |d| Domain.new(d) }
end
+
+ # Produce a list of users belonging to the given *domains* in the
+ # Dovecot mailstore.
+ #
+ # @param domains [Array<Domain>] an array of {Domain} objects whose
+ # users we'd like to find.
+ #
+ # @return [Array<User>] an array of {User} objects that have
+ # corresponding directories within the Dovecot mailstore belonging
+ # to the specified *domains*.
+ #
def list_domains_users(domains)
users = []
usernames = Filesystem.get_subdirs(domain_path)
usernames.each do |username|
- users << "#{username}@#{domain}"
+ users << User.new("#{username}@#{domain}")
end
rescue NonexistentDomainError
# Party hard.
end
+ # Produce a list of all users in the Dovecot mailstore.
+ #
+ # @return [Array<User>] a list of users who have mailbox directories
+ # within the Dovecot mailstore.
+ #
def list_users()
domains = list_domains()
users = list_domains_users(domains)