[Bps-public-commit] Net-IMAP-Server branch, master, updated. 1.28-2-g6f5d21a

Alex Vandiver alexmv at bestpractical.com
Tue Jun 8 15:37:27 EDT 2010


The branch, master has been updated
       via  6f5d21a2de3a9c77e93de6982b3d6266d0a2aaf2 (commit)
       via  9f31cf5243513b48f5f9e5b6f9478174039be236 (commit)
      from  bf4753086ddddbb8ce8f3c103adaf0c4e676163b (commit)

Summary of changes:
 README                 |  162 +++++++++++++++++++++++++++++++++++++++++++-----
 lib/Net/IMAP/Server.pm |    2 +-
 2 files changed, 148 insertions(+), 16 deletions(-)

- Log -----------------------------------------------------------------
commit 9f31cf5243513b48f5f9e5b6f9478174039be236
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Tue Jun 8 15:29:15 2010 -0400

    Bump copyright

diff --git a/lib/Net/IMAP/Server.pm b/lib/Net/IMAP/Server.pm
index a4a1d6a..4d1db52 100644
--- a/lib/Net/IMAP/Server.pm
+++ b/lib/Net/IMAP/Server.pm
@@ -540,7 +540,7 @@ Alex Vandiver  C<< <alexmv at bestpractical.com> >>
 
 =head1 LICENCE AND COPYRIGHT
 
-Copyright (c) 2009, Best Practical Solutions, LLC.  All rights reserved.
+Copyright (c) 2010, Best Practical Solutions, LLC.  All rights reserved.
 
 This module is free software; you can redistribute it and/or
 modify it under the same terms as Perl itself. See L<perlartistic>.

commit 6f5d21a2de3a9c77e93de6982b3d6266d0a2aaf2
Author: Alex Vandiver <alexmv at bestpractical.com>
Date:   Tue Jun 8 15:31:30 2010 -0400

    Update README

diff --git a/README b/README
index b1558f5..f53b7a1 100644
--- a/README
+++ b/README
@@ -23,7 +23,9 @@ DESCRIPTION
     a either SSL or TLS. Thus, you are required to have a certs/ directory
     under the current working directory, containing files server-cert.pem
     and "server-key.pem". Failure to do so will cause the server to fail to
-    start.
+    start. Note that if the default paths suit your needs, you can specify
+    different ones using the "server_cert" and "server_key" arguments to
+    "new".
 
 INTERFACE
     The primary method of using this module is to supply your own model and
@@ -58,17 +60,6 @@ METHODS
         On rare occasions, you may wish to subclass the connection class;
         this class must be a subclass of Net::IMAP::Server::Connection.
 
-    user
-        The name or ID of the user that the server should run as; this
-        defaults to the current user. Note that privileges are dropped after
-        binding to the port and reading the certificates, so escalated
-        privileges should not be needed. Running as your "nobody" user or
-        equivilent is suggested.
-
-    group
-        The name or ID of the group that the server should run as; see
-        "user", above.
-
     poll_every
         How often the current mailbox should be polled, in seconds; defaults
         to 0, which means it will be polled after every client command.
@@ -83,17 +74,46 @@ METHODS
         zero to disable (which is not advised).
 
     auth_idle
-        How long, in seconds, to wait before disconnecting authentiated
+        How long, in seconds, to wait before disconnecting authenticated
         connections. By RFC specification, this must be longer than 30
         minutes. The default is an hour; set to zero to disable.
 
+    server_cert
+        Path to the SSL certificate that the server should use. This can be
+        either a relative or absolute path.
+
+    server_key
+        Path to the SSL certificate key that the server should use. This can
+        be either a relative or absolute path.
+
+    It also accepts the following Net::Server arguments -- see its
+    documentation for details on their use.
+
+    "log_level" in Net::Server
+    "log_file" in Net::Server
+    "syslog_logsock" in Net::Server
+    "syslog_ident" in Net::Server
+    "syslog_logopt" in Net::Server
+    "syslog_facility" in Net::Server
+    "pid_file" in Net::Server
+    "chroot" in Net::Server
+    "user" in Net::Server
+    "group" in Net::Server
+    "reverse_lookups" in Net::Server
+    "allow" in Net::Server
+    "deny" in Net::Server
+    "cidr_allow" in Net::Server
+    "cidr_deny" in Net::Server
+
   run
     Starts the server; this method shouldn't be expected to return. Within
     this method, $Net::IMAP::Server::Server is set to the object that this
-    was called on; thus, all IMAP objecst have a way of referring to the
+    was called on; thus, all IMAP objects have a way of referring to the
     server -- and though "connection", whatever parts of the IMAP internals
     they need.
 
+    Any arguments are passed through to "run" in Net::Server.
+
   process_request
     Accepts a client connection; this method is needed for the Net::Server
     infrastructure.
@@ -131,6 +151,113 @@ METHODS
     Returns a hash of properties to be conveyed to the client, should they
     ask the server's identity.
 
+  add_command NAME => PACKAGE
+    Adds the given command "NAME" to the server's list of known commands.
+    "PACKAGE" should be the name of a class which inherits from
+    Net::IMAP::Server::Command.
+
+  log SEVERITY, MESSAGE
+    By default, defers to "log" in Net::Server, which outputs to syslog, a
+    logfile, or STDERR, depending how it was configured. Net::Server's
+    default is to print to STDERR. If you have custom logging needs,
+    override this method, or "write_to_log_hook" in Net::Server.
+
+Object model
+    An ASCII model of the relationship between objects is below. In it,
+    single lines represent scalar values, and lines made of other characters
+    denote array references or relations.
+
+       +----------------------------------------------+
+       |                                              |
+       |                    Server                    |
+       |                                              |
+       +1-----2---------------------------------------+
+        #     '      ^         ^            ^        ^
+        #     '      |         |            |        |
+        #     v      |         |            |        |
+        #   +--------1-------+ |     +------1------+ |
+        ###>|   Connection   |<------2   Command   | |
+        #   +--4-----3------2+ |     +-------------+ |
+      /-#------/     |      \--------------\         |
+      | #            v         |           v         |
+      | #   +----------------+ |     +-------------+ |
+      | #   |     Model      2------>|    Auth     | |
+      | #   +--------1-------+ |     +-------------+ |
+      | #            \---------------------------------\
+      | #                      |                     | |
+      | #                  /---/                 /---/ |
+      | #   +--------------1-+       +-----------1-+   |
+      | ###>|   Connection   |<------2   Command   |   |
+      |     +--4-5---3------2+       +-------------+   |
+      | /------/ *   |      \--------------\           |
+      | | ********   v                     v           |
+      | | * +----------------+       +-------------+   |
+      | | * |     Model      2------>|    Auth     |   |
+      | | * +--------1-------+       +-------------+   |
+      | | *          |                                 |
+      | | *          |  /------------------------------/
+      | | *          |  |           ^ SERVER
+      |.|.*..........|..|................................
+      | | *          |  |           v MODEL
+      | | *          v  v
+      | \-*---->+-------------+<------------\
+      \---*---->|   Mailbox   |<----------\ |
+          *     +-1------2-3--+<----\     | |
+          *       @   ^  $ %        |     | |
+          *       @   |  $$%$>+-----1---+ | |
+          *       @   |  $ %%>| Message | | |
+          ********@***|****%*>+---------+ | |
+          *       @   |  $ %              | |
+          *       @   |  $$%$>+---------+ | |
+          *       @   |    %%>| Message 1-/ |
+          ********@***|******>+---------+   |
+          *       @   |                     |
+          *       @   |       +---------+   |
+          *       @   |       | Message 1---/
+          ********@***|******>+---------+
+                  @   |
+                  @  +4----------+
+                  @@>|  Mailbox  |
+                     +-----------+
+
+    The top half consists of the parts which implement the IMAP protocol
+    itself; the bottom contains the models for the backing store. Note that,
+    for the most part, the backing store is unaware of the framework of the
+    server itself.
+
+    Each model has references to others, as follows:
+
+    Server
+        Contains references to the set of "connections" (1). It also has a
+        sense of the *current* "connection" (2), based on the active Coro
+        thread.
+
+    Connection
+        Connections hold a reference to their "server" (1). If the
+        connection has authenticated, they hold a reference to the "auth"
+        object (2), and to their "model" (3). If a mailbox is "selected"
+        (4), they hold a pointer to that, as well. Infrequently, the
+        connection will need to temporarily store references to the set of
+        "temporary_messages" (5) which have been expunged in other
+        connections, but we have been unable to notify this connection of.
+
+    Command
+        Commands store their "server" (1) and "connection" (2).
+
+    Model
+        Models store a reference to the "root" (1) of their mailbox tree, as
+        well as to the "auth" (2) which gives them access to such.
+
+    Mailbox
+        Mailboxes store a list of "children" mailboxes (1), and "messages"
+        (2) contained within them, which are stored in sequence order. They
+        also contain a hash of "uids" (3) for fast UID retrieval of
+        messages. If they are not the root mailbox, they also store a
+        reference to their "parent" mailbox (4).
+
+    Message
+        Messages store the "mailbox" (1) in which they are contained.
+
 DEPENDENCIES
     Coro, Net::Server::Coro
 
@@ -141,11 +268,16 @@ BUGS AND LIMITATIONS
     "bug-net-imap-server at rt.cpan.org", or through the web interface at
     <http://rt.cpan.org>.
 
+    A low-traffic mailing list exists for discussion on how to (ab)use this
+    module, at
+    <http://lists.bestpractical.com/cgi-bin/mailman/listinfo/net-imap-server
+    >.
+
 AUTHOR
     Alex Vandiver "<alexmv at bestpractical.com>"
 
 LICENCE AND COPYRIGHT
-    Copyright (c) 2008, Best Practical Solutions, LLC. All rights reserved.
+    Copyright (c) 2010, Best Practical Solutions, LLC. All rights reserved.
 
     This module is free software; you can redistribute it and/or modify it
     under the same terms as Perl itself. See perlartistic.

-----------------------------------------------------------------------



More information about the Bps-public-commit mailing list