[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