Document everything with YARD and fix some bugs along the way.

[mailshears.git] / lib / common / postfixadmin_plugin.rb

diff --git a/lib/common/postfixadmin_plugin.rb b/lib/common/postfixadmin_plugin.rb
index 3a5494bced822593e7a63f7a65c4422a02f3fb75..8bf03f96f5a95d8bf8279cff6721035dc13f835f 100644 (file)
--- a/lib/common/postfixadmin_plugin.rb
+++ b/lib/common/postfixadmin_plugin.rb
@@ -3,11 +3,18 @@ require 'common/plugin'
 require 'common/user'
 require 'pg'
 
+# Code that all Postfixadmin plugins ({PostfixadminPrune},
+# {PostfixadminRm}, {PostfixadminMv}) share.
+#
 module PostfixadminPlugin
-  # Code that all Postfixadmin plugins (Prune, Rm, Mv...) will
-  # share.  That is, we implement the Plugin interface.
+
+  # We implement the Plugin "interface."
   include Plugin
 
+  # Initialize this Postfixadmin {Plugin} with values in *cfg*.
+  #
+  # @param cfg [Configuration] the configuration for this plugin.
+  #
   def initialize(cfg)
     @db_host = cfg.postfixadmin_dbhost
     @db_port = cfg.postfixadmin_dbport
@@ -19,6 +26,13 @@ module PostfixadminPlugin
   end
 
 
+  # Obtain a list of domains from Postfixadmin. This is more efficient
+  # than the {Plugin} default implementation because domains have
+  # their own table in the database and we can easily select them
+  # rather than filtering the list of users.
+  #
+  # @return [Array<Domain>] a list of the domains in Postfixadmin.
+  #
   def list_domains()
     domains = []
 
@@ -37,7 +51,11 @@ module PostfixadminPlugin
   end
 
 
-
+  # Return a list of Postfixadmin users.
+  #
+  # @return [Array<User>] a list of users contained in the
+  #   Postfixadmin database.
+  #
   def list_users()
     users = []
 
@@ -55,15 +73,31 @@ module PostfixadminPlugin
   end
 
 
+
+  # Efficiently list all Postfixadmin users belonging to the given
+  # Postfixadmin *domains*.
+  #
+  # @param domains [Array<Domain>] the domains whose users we want.
+  #
+  # @return [Array<User>] a list of {User} objects belonging to
+  #   *domains* for this plugin.
+  #
   def list_domains_users(domains)
     usernames = []
+    return usernames if domains.length() == 0
 
     connection = PGconn.connect(@db_host, @db_port, @db_opts, @db_tty,
                                 @db_name, @db_user, @db_pass)
 
-    sql_query  = 'SELECT username FROM mailbox WHERE domain IN $1;'
+    # The number of parameters that we'll pass into our prepared query
+    # is the number of domains that we're given. It's important that
+    # we have at least one domain here.
+    params = 1.upto(domains.length()).map{ |i| '$' + i.to_s() }.join(',')
+    sql_query  = "SELECT username FROM mailbox WHERE domain IN (#{params});"
 
-    connection.query(sql_query, domains.map{|d| d.to_s()}) do |result|
+    # Now replace each Domain with its string representation and pass
+    # those in as our individual parameters.
+    connection.query(sql_query, domains.map{ |d| d.to_s() }) do |result|
       usernames = result.field_values('username')
     end
 
@@ -73,10 +107,14 @@ module PostfixadminPlugin
   end
 
 
+  # Get a list of all Postfixadmin aliases as a <tt>from => to</tt>
+  # hash. This is useful for testing, since aliases should be removed
+  # when either the "from user" or "to user" are removed.
+  #
+  # @return [Hash] all aliases known to Postfixadmin in the form of a
+  #   <tt>from => to</tt> hash.
+  #
   def list_aliases()
-    #
-    # Get a list of all aliases, useful for testing.
-    #
     aliases = []
 
     connection = PGconn.connect(@db_host, @db_port, @db_opts, @db_tty,
@@ -85,7 +123,8 @@ module PostfixadminPlugin
     sql_query = 'SELECT address,goto FROM alias;'
     results = connection.query(sql_query)
     results.each do |row|
-      aliases << row # row should be a hash
+      # row should be a hash
+      aliases << row
     end
 
     connection.close()
@@ -93,4 +132,34 @@ module PostfixadminPlugin
     return aliases
   end
 
+
+  # A fast implementation of the "does this domain exist?"
+  # operation. It only queries the database for the existence of
+  # *domain* rather than a list of all domains (which is the default
+  # implementation).
+  #
+  # @param domain [Domain] the domain whose existence is in question.
+  #
+  # @return [Boolean] true if *domain* exists in the Postfixadmin
+  #   database and false otherwise.
+  #
+  def domain_exists(domain)
+    count = 0
+
+    connection = PGconn.connect(@db_host, @db_port, @db_opts, @db_tty,
+                                @db_name, @db_user, @db_pass)
+
+    sql_query = 'SELECT COUNT(domain) as count FROM domain WHERE domain = $1;'
+    connection.query(sql_query, [domain.to_s()]) do |result|
+      return false if result.ntuples() < 1
+      count = result.getvalue(0,0).to_i()
+
+      return false if count.nil?
+    end
+
+    connection.close()
+
+    return (count > 0)
+  end
+
 end