oracular (3) Mail::SpamAssassin::Pyzor::Client.3pm.gz

NAME

       Mail::SpamAssassin::Pyzor::Client - Pyzor client logic

SYNOPSIS

           use Mail::SpamAssassin::Pyzor::Client ();
           use Mail::SpamAssassin::Pyzor::Digest ();

           my $client = Mail::SpamAssassin::Pyzor::Client->new();

           my $digest = Mail::SpamAssassin::Pyzor::Digest::get( $msg );

           my $check_ref = $client->check($digest);
           die $check_ref->{'Diag'} if $check_ref->{'Code'} ne '200';

           my $report_ref = $client->report($digest);
           die $report_ref->{'Diag'} if $report_ref->{'Code'} ne '200';

DESCRIPTION

       A bare-bones Pyzor <http://pyzor.org> client that currently only implements the functionality needed for
       Mail::SpamAssassin.

PROTOCOL DETAILS

       The Pyzor protocol is not a published standard, and there appears to be no meaningful public
       documentation. What follows is enough information, largely gleaned through forum posts and reverse
       engineering, to facilitate effective use of this module:

       Pyzor is an RPC-oriented, message-based protocol. Each message is a simple dictionary of 7-bit ASCII keys
       and values. Server responses always include at least the following:

       •   "Code" - Similar to HTTP status codes; anything besides 200 is an error.

       •   "Diag" - Similar to HTTP status reasons: a text description of the status.

       (NB: There are additional standard response headers that are useful only for the protocol itself and thus
       are not part of this module's returns.)

   Reliability
       Pyzor uses UDP rather than TCP, so no message is guaranteed to reach its destination. A transmission
       failure can happen in either the request or the response; in either case, a timeout error will result.
       Such errors are represented as thrown instances of Mail::Pyzor::X::Timeout.

CONSTRUCTOR

   new(%OPTS)
       Create a new pyzor client.

       Input
         %OPTS are (all optional):

         •  "server_host" - The pyzor server host to connect to (default is "public.pyzor.org")

         •  "server_port" - The pyzor server port to connect to (default is 24441)

         •  "username" - The username to present to the pyzor server (default is "anonymous")

         •  "password" - The password to present to the pyzor server (default is empty)

         •  "timeout" - The maximum time, in seconds, to wait for a response from the pyzor server (defeault is
            3.5)

       Output
            Returns a Mail::SpamAssassin::Pyzor::Client object.

REQUEST METHODS

   report($digest)
       Report the digest of a spam message to the pyzor server. This function will throw if a messaging failure
       or timeout happens.

       Input
         $digest "SCALAR"
            The message digest to report, as given by Mail::SpamAssassin::Pyzor::Digest::get().

       Output
         "HASHREF"
            Returns a hashref of the standard attributes noted above.

   check($digest)
       Check the digest of a message to see if the pyzor server has a report for it. This function will throw if
       a messaging failure or timeout happens.

       Input
         $digest "SCALAR"
            The message digest to check, as given by Mail::SpamAssassin::Pyzor::Digest::get().

       Output
         "HASHREF"
            Returns a hashref of the standard attributes noted above as well as the following:

            •   "Count" - The number of reports the server has received for the given digest.

            •   "WL-Count" - The number of whitelist requests the server has received for the given digest.