[Bps-public-commit] r11038 - in Net-IMAP-Server: lib/Net/IMAP/Server t
alexmv at bestpractical.com
alexmv at bestpractical.com
Mon Mar 10 17:10:19 EDT 2008
Author: alexmv
Date: Mon Mar 10 17:10:18 2008
New Revision: 11038
Modified:
Net-IMAP-Server/ (props changed)
Net-IMAP-Server/Changes
Net-IMAP-Server/README
Net-IMAP-Server/lib/Net/IMAP/Server/Command.pm
Net-IMAP-Server/lib/Net/IMAP/Server/Message.pm
Net-IMAP-Server/t/pod-coverage.t
Log:
r28400 at kohr-ah: chmrr | 2008-03-10 17:10:09 -0400
* Pass our own POD tests
* Replace stub README
Modified: Net-IMAP-Server/Changes
==============================================================================
--- Net-IMAP-Server/Changes (original)
+++ Net-IMAP-Server/Changes Mon Mar 10 17:10:18 2008
@@ -1,5 +1,4 @@
Revision history for Net-IMAP-Server
-0.0.1 Mon Apr 3 11:31:52 2006
- Initial release.
-
+0.2 Mon Mar 10 16:47:52 2008
+ Initial release to CPAN
Modified: Net-IMAP-Server/README
==============================================================================
--- Net-IMAP-Server/README (original)
+++ Net-IMAP-Server/README Mon Mar 10 17:10:18 2008
@@ -1,40 +1,174 @@
-Net-IMAP-Server version 0.0.1
-
-[ REPLACE THIS...
-
- The README is used to introduce the module and provide instructions on
- how to install the module, any machine dependencies it may have (for
- example C compilers and installed libraries) and any other information
- that should be understood before the module is installed.
-
- A README file is required for CPAN modules since CPAN extracts the
- README file from a module distribution so that people browsing the
- archive can use it get an idea of the modules uses. It is usually a
- good idea to provide version information here so that people can
- decide whether fixes for the module are worth downloading.
-]
-
-
-INSTALLATION
-
-To install this module, run the following commands:
-
- perl Makefile.PL
- make
- make test
- make install
-
-
+NAME
+ Net::IMAP::Server - A single-threaded multiplexing IMAP server
+ implementation, using Net::Server::Coro.
+
+SYNOPSIS
+ use Net::IMAP::Server;
+ Net::IMAP::Server->new(
+ port => 193,
+ ssl_port => 993,
+ auth_class => "Your::Auth::Class",
+ model_class => "Your::Model::Class",
+ user => "nobody",
+ group => "nobody",
+ )->run;
+
+DESCRIPTION
+ This model provides a complete implementation of the "RFC 3501"
+ specification, along with several IMAP4rev1 extensions. It provides
+ separation of the mailbox and message store from the client interaction
+ loop.
+
+ Note that, following RFC suggestions, login is not allowed except under
+ 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.
+
+INTERFACE
+ The primary method of using this module is to supply your own model and
+ auth classes, which inherit from Net::IMAP::Server::DefaultModel and
+ Net::IMAP::Server::DefaultAuth. This allows you to back your messages
+ from arbitrary data sources, or provide your own authorization backend.
+ For the most part, the implementation of the IMAP components should be
+ opaque.
+
+METHODS
+ new PARAMHASH
+ Creates a new IMAP server object. This doesn't even bind to the sockets;
+ it merely initializes the object. It will "die" if it cannot find the
+ appropriate certificate files. Valid arguments to "new" include:
+
+ port
+ The port to bind to. Defaults to port 1430.
+
+ ssl_port
+ The port to open an SSL listener on; by default, this is disabled,
+ and any true value enables it.
+
+ auth_class
+ The name of the class which implements authentication. This must be
+ a subclass of Net::IMAP::Server::DefaultAuth.
+
+ model_class
+ The name of the class which implements the model backend. This must
+ be a subclass of Net::IMAP::Server::DefaultModel.
+
+ connection_class
+ 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.
+
+ unauth_commands
+ The number of commands before unauthenticated users are
+ disconnected. The default is 10; set to zero to disable.
+
+ unauth_idle
+ How long, in seconds, to wait before disconnecting idle connections
+ which have not authenticated yet. The default is 5 minutes; set to
+ zero to disable (which is not advised).
+
+ auth_idle
+ How long, in seconds, to wait before disconnecting authentiated
+ connections. By RFC specification, this must be longer than 30
+ minutes. The default is an hour; set to zero to disable.
+
+ 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
+ server -- and though "connection", whatever parts of the IMAP internals
+ they need.
+
+ process_request
+ Accepts a client connection; this method is needed for the Net::Server
+ infrastructure.
+
+ DESTROY
+ On destruction, ensure that we close all client connections and
+ listening sockets.
+
+ connections
+ Returns an arrayref of Net::IMAP::Server::Connection objects which are
+ currently connected to the server.
+
+ connection
+ Returns the currently active Net::IMAP::Server::Connection object, if
+ there is one. This is determined by examining the current coroutine.
+
+ concurrent_mailbox_connections [MAILBOX]
+ This can be called as either a class method or an instance method; it
+ returns the set of connections which are concurrently connected to the
+ given mailbox object (which defaults to the current connection's
+ selected mailbox)
+
+ concurrent_user_connections [USER]
+ This can be called as either a class method or an instance method; it
+ returns the set of connections whose "user" in
+ Net::IMAP::Server::DefaultAuth is the same as the given USER (which
+ defaults to the current connection's user)
+
+ capability
+ Returns the "CAPABILITY" string for the server. This string my be
+ modified by the connection before being sent to the client (see
+ "capability" in Net::IMAP::Server::Connection).
+
+ id
+ Returns a hash of properties to be conveyed to the client, should they
+ ask the server's identity.
DEPENDENCIES
+ Coro, Net::Server::Coro
-None.
-
-
-COPYRIGHT AND LICENCE
-
-Copyright (C) 2006, Best Practical Solutions LLC.
+BUGS AND LIMITATIONS
+ No bugs have been reported.
-This library is free software; you can redistribute it and/or modify
-it under the same terms as Perl itself.
+ Please report any bugs or feature requests to
+ "bug-net-imap-server at rt.cpan.org", or through the web interface at
+ <http://rt.cpan.org>.
+
+AUTHOR
+ Alex Vandiver "<alexmv at bestpractical.com>"
+
+LICENCE AND COPYRIGHT
+ Copyright (c) 2008, 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.
+
+DISCLAIMER OF WARRANTY
+ BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+ FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
+ OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+ PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
+ EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
+ ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
+ YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
+ NECESSARY SERVICING, REPAIR, OR CORRECTION.
+
+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+ WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+ REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
+ TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
+ CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
+ SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
+ RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
+ FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
+ SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+ DAMAGES.
Modified: Net-IMAP-Server/lib/Net/IMAP/Server/Command.pm
==============================================================================
--- Net-IMAP-Server/lib/Net/IMAP/Server/Command.pm (original)
+++ Net-IMAP-Server/lib/Net/IMAP/Server/Command.pm Mon Mar 10 17:10:18 2008
@@ -339,7 +339,7 @@
%extra_responses );
}
-=head2 ok_command MESSAGE [, RESPONSECODE => STRING, ...]
+=head2 no_command MESSAGE [, RESPONSECODE => STRING, ...]
Sends untagged NO responses for any C<RESPONSECODE> pairs, then
outputs untagged messages via L</send_untagged>, then sends a tagged
Modified: Net-IMAP-Server/lib/Net/IMAP/Server/Message.pm
==============================================================================
--- Net-IMAP-Server/lib/Net/IMAP/Server/Message.pm (original)
+++ Net-IMAP-Server/lib/Net/IMAP/Server/Message.pm Mon Mar 10 17:10:18 2008
@@ -307,9 +307,9 @@
} elsif ( uc $part eq "RFC822.SIZE" ) {
push @out, length $self->mime_select( [], undef, undef );
} elsif ( uc $part eq "BODY" ) {
- push @out, $self->mime_bodystructure( $self->mime, 0 );
+ push @out, $self->mime_bodystructure( 0 );
} elsif ( uc $part eq "BODYSTRUCTURE" ) {
- push @out, $self->mime_bodystructure( $self->mime, 1 );
+ push @out, $self->mime_bodystructure( 1 );
} elsif ( uc $part eq "ENVELOPE" ) {
push @out, $self->mime_envelope;
} else {
@@ -319,13 +319,25 @@
return @out;
}
+=head2 mime_select SECTIONS [, START [, END [, EXTRA]]]
+
+This method is generally only used internally by L</fetch>.
+
+C<SECTIONS> should be an array reference of indexes into MIME parts,
+or pulled from the set of strings: C<HEADER>, C<MIME>, C<FIELDS>,
+C<TEXT>. C<START> and C<END> determine which bytes of the resulting
+content to send. C<EXTRA> is used only for C<FIELDS>, and supplies
+the names of headers to fetch.
+
+=cut
+
sub mime_select {
my $self = shift;
my ( $sections, $start, $end, $extras ) = @_;
my $mime;
- my @sections = @{$sections};
+ my @sections = @{$sections || []};
my $result;
$result = $self->mime->as_string unless @sections;
for (@sections) {
@@ -337,7 +349,7 @@
my $mime_header = $mime ? $mime->header_obj : $self->mime_header;
$case{ uc $_ } = $_ for $mime_header->header_names;
my $copy = Email::Simple::Header->new("");
- for my $h ( @{$extras} ) {
+ for my $h ( @{$extras || []} ) {
$copy->header_set( $case{$h}
|| $h => $mime_header->header($h) );
}
@@ -358,9 +370,16 @@
return substr( $result, $start, $end );
}
+=head2 mime_bodystructure [LONG [, MIME]]
+
+Returns a string describing the MIME body structure of the message.
+
+=cut
+
sub mime_bodystructure {
my $self = shift;
- my ( $mime, $long ) = @_;
+ my ( $long, $mime ) = @_;
+ $mime ||= $self->mime;
# Grab the content type
my $data = parse_content_type( $mime->content_type );
@@ -387,7 +406,7 @@
@parts = () if @parts == 1 and $parts[0] == $mime;
my $parts = join '', map {
Net::IMAP::Server::Command->data_out(
- $self->mime_bodystructure( $_, $long ) )
+ $self->mime_bodystructure( $long, $_ ) )
} @parts;
return [
@@ -449,6 +468,13 @@
}
}
+=head2 address_envelope HEADER
+
+Returns a data structure defining the email addresses listed in the
+given C<HEADER>. This is used internally by L</mime_envelope>.
+
+=cut
+
sub address_envelope {
my $self = shift;
my $header = shift;
@@ -466,6 +492,13 @@
];
}
+=head2 mime_envelope
+
+Returns a data structure defining properties of significant header
+fields. This is used internally by L</fetch>.
+
+=cut
+
sub mime_envelope {
my $self = shift;
my $mime = $self->mime_header;
Modified: Net-IMAP-Server/t/pod-coverage.t
==============================================================================
--- Net-IMAP-Server/t/pod-coverage.t (original)
+++ Net-IMAP-Server/t/pod-coverage.t Mon Mar 10 17:10:18 2008
@@ -3,4 +3,12 @@
use Test::More;
eval "use Test::Pod::Coverage 1.04";
plan skip_all => "Test::Pod::Coverage 1.04 required for testing POD coverage" if $@;
-all_pod_coverage_ok();
+
+my @modules
+ = grep { not /^Net::IMAP::Server::Command::/ } Test::Pod::Coverage::all_modules();
+plan( tests => scalar @modules );
+
+pod_coverage_ok(
+ $_,
+ "Pod coverage on $_"
+) for @modules;
More information about the Bps-public-commit
mailing list