=pod

=for vim
   vim: tw=72 ts=3 sts=3 sw=3 et ai :

=encoding utf8

=head1 NAME

Mail::Colander::Server - SMTP server leveraging Mail::Colander


=head1 VERSION

This document describes Mail::Colander::Server version {{[ version ]}}.

=begin html

<a href="https://travis-ci.org/polettix/Mail-Colander-Server">
<img alt="Build Status" src="https://travis-ci.org/polettix/Mail-Colander-Server.svg?branch=master">
</a>
<a href="https://www.perl.org/">
<img alt="Perl Version" src="https://img.shields.io/badge/perl-5.24+-brightgreen.svg">
</a>
<a href="https://badge.fury.io/pl/Mail-Colander-Server">
<img alt="Current CPAN version" src="https://badge.fury.io/pl/Mail-Colander-Server.svg">
</a>
<a href="http://cpants.cpanauthors.org/dist/Mail-Colander-Server">
<img alt="Kwalitee" src="http://cpants.cpanauthors.org/dist/Mail-Colander-Server.png">
</a>
<a href="http://www.cpantesters.org/distro/O/Mail-Colander-Server.html?distmat=1">
<img alt="CPAN Testers" src="https://img.shields.io/badge/cpan-testers-blue.svg">
</a>
<a href="http://matrix.cpantesters.org/?dist=Mail-Colander-Server">
<img alt="CPAN Testers Matrix" src="https://img.shields.io/badge/matrix-@testers-blue.svg">
</a>

=end html

=head1 SYNOPSIS

   use Mail::Colander::Server qw< mojo_ioloop_server_callback_factory >;

   my $mss = mojo_ioloop_server_callback_factory(
      sieve => $mail_sieve_definition,
      esmtp_extensions => [qw< PIPELINING >],
      esmtp_args => { idle_timeout => 1 },
      callback_for => {
         HELO   => sub ($session) { warn "accept HELO" },
         EHLO   => sub ($session) { warn "accept EHLO" },
         DATA   => sub ($session) { warn "accept DATA" },
         reject => sub ($phase, $session) { warn "reject $phase" },
      },
   );
   Mojo::IOLoop->server(port => $port, $mss);
   Mojo::IOLoop->start unless Mojo::IOLoop->is_running;


=head1 DESCRIPTION

ESMTP server that allows analyzing incoming messages via
L<Mail::Colander>/L<Data::Annotation> and then act based on callbacks.

=head1 INTERFACE

=head2 B<< mojo_ioloop_server_callback_factory >>

   my $mss = mojo_ioloop_server_callback_factory(%args);

Do-it-all function that is a factory for a sub reference suitable to be
passed to L<< Mojo::IOLoop->server >>.

The input C<%args> support the following keys:

=over

=item *

C<callback_for>: a hash reference of key/value pairs, where keys
represent either a phase supported by L<Net::Server::Mail::ESMTP> (like
C<EHLO>, C<DATA>, etc.) or key C<reject>, and values are callback
functions.

The callback for C<reject> takes two parameters, namely the phase where
the rejection happened, and the L<Mail::Colander::Session> object tracking
the ESMTP session:

   sub reject_cb ($phase, $session) { ... }

All other callbacks take one single parameter, i.e. the
L<Mail::Colander::Session>:

   sub phase_success_cb ($session) { ... }

=item *

C<esmtp_args>: list of arguments for creating an instance of class
L<Net::Server::Mail::ESMTP>.

=item *

C<esmtp_extensions>: a list of extensions for
L<Net::Server::Mail::ESMTP>.

=item *

C<sieve>: a L<Mail::Colander> instance, or a hash reference with the data to
create one.

=item *

C<timeout>: the timeout set on each client connection stream in seconds,
defaulting to 3.

=back

=head1 ANYTHING ELSE (INCLUDING AUTHOR, COPYRIGHT AND LICENSE)

See documentation for Mail::Colander.

=cut
