bingos / poe-component-client-dnsbl

NAME
    POE::Component::Client::DNSBL - A component that provides non-blocking
    DNSBL lookups

SYNOPSIS
      use strict;
      use POE qw(Component::Client::DNSBL);

      die "Please provide at least one IP address to lookup\n" unless scalar @ARGV;

      my $dnsbl = POE::Component::Client::DNSBL->spawn();

      POE::Session->create(
            package_states => [
                'main' => [ qw(_start _stop _response) ],
            ],
            heap => { 
                      addresses => [ @ARGV ], 
                      dnsbl => $dnsbl 
            },
      );

      $poe_kernel->run();
      exit 0;

      sub _start {
         my ($kernel,$heap) = @_[KERNEL,HEAP];
         $heap->{dnsbl}->lookup(
            event => '_response',
            address => $_,
         ) for @{ $heap->{addresses} };
         return;
      }

      sub _stop {
         my ($kernel,$heap) = @_[KERNEL,HEAP];
         $kernel->call( $heap->{dnsbl}->session_id(), 'shutdown' );
         return;
      }

      sub _response {
         my ($kernel,$heap,$record) = @_[KERNEL,HEAP,ARG0];
         if ( $record->{error} ) {
            print "An error occurred, ", $record->{error}, "\n";
            return;
         }
         if ( $record->{response} eq 'NXDOMAIN' ) {
            print $record->{address}, " is okay\n";
            return;
         }
         print join( " ", $record->{address}, $record->{response}, $record->{reason} ), "\n";
         return;
      }

DESCRIPTION
    POE::Component::Client::DNSBL is a POE component that provides
    non-blocking DNS blacklist lookups to other components and POE sessions.
    It uses POE::Component::Client::DNS to perform the requested queries.

    Only IPv4 lookups are supported and unless a DNSBL zone is specified the
    component will use zen.spamhaus.org.

CONSTRUCTOR
    spawn
        Takes a number of parameters:

          'alias', set an alias that you can use to address the component later;
          'options', a hashref of POE session options;
          'dnsbl', the DNSBL zone to send queries to, default zen.spamhaus.org;
          'resolver', optionally provide a POE::Component::Client::DNS to use;

        Returns an object.

METHODS
    session_id
        Takes no arguments. Returns the ID of the component's session.

    shutdown
        Terminates the component.

    lookup
        Performs a DNSBL lookup. Takes a number of parameters:

          'event', the name of the event to send the reply to. ( Mandatory );
          'address', the IPv4 address to lookup ( Mandatory );
          'session', send the resultant event to an alternative session, ( default is the sender );

        You may also pass arbitary key/values. Arbitary keys should have an
        underscore prefix '_'.

INPUT EVENTS
    shutdown
        Terminates the component.

    lookup
        Performs a DNSBL lookup. Takes a number of parameters:

          'event', the name of the event to send the reply to. ( Mandatory );
          'address', the IPv4 address to lookup ( Mandatory );
          'session', send the resultant event to an alternative session, ( default is the sender );

        You may also pass arbitary key/values. Arbitary keys should have an
        underscore prefix '_'.

OUTPUT EVENTS
    The component will send an event in response to "lookup" requests. ARG0
    will be a hashref containing the key/values of the original request (
    including any arbitary key/values passed ).

      'response', the status returned by the DNSBL, it will be NXDOMAIN if the address given was okay;
      'reason', if an address is blacklisted, this may contain the reason;
      'error', if something goes wrong with the DNS lookup the error string will be contained here;

AUTHOR
    Chris "BinGOs" Williams <chris@bingosnet.co.uk>

SEE ALSO
    <http://en.wikipedia.org/wiki/DNSBL>

    <http://www.spamhaus.org/zen/>

    POE

    POE::Component::Client::DNS