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.