NAME

Net::Server::POP3proxy - POP3 Proxy class for working with virus scanners and anti-spam software

SYNOPSIS

    use Net::Server::POP3proxy;

    # Constructors
    $popproxy = new Net::Server::POP3proxy(
        Action => sub { filterAction ($_[0]); },
        Error  => sub { die ($_[0]); },
        Debug  => sub { print STDERR ($_[0]); }
    ) or die ("Cannot init POP3 proxy server");
        
    while ($popproxy->looper()) {
        # noop
    }

DESCRIPTION

This module implements a POP3 proxy server to enable you to call user defined actions uppon fetching a mail from the POP3 Server.

The destination server is taken from the username, the client connects to the pop3 proxy in the way remoteuser%remote.host:port.

Multiple clients can connect to the POP proxy at a time.

CONSTRUCTOR

new ( [ Port => [port] ], [ Action => [sub] ], [ Error => [sub] ], [ Debug => [sub] ], [ MaxSize => [maximumsize] ] )

This is the constructor for a new Net::POP3proxy object. No paramater is required.

Port is the TCP port the proxy listens on the local machine interface. The default port is 110.

MaxSize is the maximum message size im bytes, the action is called. E.g. no junk can be greater than 512k or much less! The default is 0 which means all messages are filtered.

Action is an anonymous function which is called, if a message arrives. It must return the message or the modified message. We use a normal scalar value for this, though we had problems with memory leaks using references under Windows. The default is to do nothing.

Error is an anonymous function which is called, if an error occures. It is assumed, that this function does stop the execution immediate. So use a die or so here. The parameter is the error message. The default is to do a die.

Debug is an anonymous function which is called, if a debug message occures. It is assumed, that this function does NOT stop the execution immediate. The default is to print the message.

METHODS

The concept is to do a loop. So we only descript the looping function and the cleanup functions.

looper ( )

Waits for connections and handles actions and errors.

cleanup ( [ FORCE ] )

Closes all sockets. If FORCE is ommitted or 0 only sockets containing with no waiting data are closed. If FORCE is 1 then all is closed. For example in case of no fatal error you can end by doing this:

        $popproxy->cleanup();

        # run last buffers - with a grace of 50
        # communications for the rest buffer
        
        my $gracecounter = 50;
        while ($popproxy->looper() && $gracecounter ) { $gracecounter--; }

        $popproxy->cleanup(1);    

POP3 commands

For you to understand, we try to give an example of a POP3 communication with the proxy:

    telnet localhost 110
    +OK welcome to perl pop3 proxy
    USER test@mail.test.it
    
    ... connection is created to mail.test.it port 110
    
    +OK
    
    ... now communication is done with mail.test.it
    

Using other ports:

    telnet localhost 110
    +OK welcome to perl pop3 proxy
    USER test@mail.test.it:1110
    
    ... connection is created to mail.test.it port 1110
    
    +OK
    
    ... now communication is done with mail.test.it
    

Special shutdown command

    telnet localhost 110
    +OK welcome to perl pop3 proxy
    shutdown
    
    ... looper returns false and all sockets are closed
      

NOTES

We work a lot with destroys and try to undefine a lot of data. This is because this was designed to work as a Windows Service using PerlSVC from ActiveState. So dont be confused if you read the code.

POP3 connections are done by socket communication.

This was only tested on Windows till now.

AUTHOR

Martin Boeck <martin.boeck@comnex.net>

COPYRIGHT

Copyright (c) 2005 Martin Boeck. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.