NAME

AnyEvent::Finger::Server - Simple asynchronous finger server

VERSION

version 0.10

SYNOPSIS

 use AnyEvent::Finger::Server;
 my $server = AnyEvent::Finger::Server->new;
 
 my %users = (
   grimlock => "ME GRIMLOCK HAVE PLAN",
   optimus  => "Freedom is the right of all sentient beings.",
 );
 
 $server->start(sub {
   my($tx) = @_;
   if($tx->req->listing_request)
   {
     # respond if remote requests list of users
     $tx->res->say('users:', keys %users);
   }
   else
   {
     # respond if user exists
     if(defined $users{$tx->req->username})
     {
       $tx->res->say($users{$tx->req->username});
     }
     # respond if user does not exist
     else
     {
       $tx->res->say('no such user');
     }
   }
   # required! done generating the reply,
   # close the connection with the client.
   $tx->res->done;
 });

DESCRIPTION

Provide a simple asynchronous finger server.

CONSTRUCTOR

new

 my $server = AnyEvent::Finger::Server->new(%args);

The constructor takes the following optional arguments:

• hostname (default 127.0.0.1)

  The hostname to connect to.

• port (default 79)

  The port to connect to.

• on_error (carp error)

  A callback subref to be called on error (either connection or transmission error). Passes the error string as the first argument to the callback.

• on_bind

  A callback subref to be called when the port number is known. This is useful when ephemeral port is used but other parts of the code depend on it. The first argument to the callback will be the AnyEvent::Finger::Server object.

• forward_deny (0)

  Deny forward requests, (for example: finger@host1@host2@... style requests). If neither forward_deny or forward is specified then forward requests will be passed on to the callback, like all other requests.

• forward (0)

  Forward forward requests. This can be set to either 1, or an instance of AnyEvent::Finger::Client which will be used to forward requests. If neither forward_deny or forward is specified then forward requests will be passed on to the callback, like all other requests.

METHODS

start

 $server->start( $callback )

Start the finger server. The callback will be called each time a client connects.

 $callback->($tx)

The first argument passed to the callback is the transaction object, which is an instance of AnyEvent::Finger::Transaction. The most important members of these objects that you will want to interact with are $tx->req for the request (an instance of AnyEvent::Finger::Request) and $tx->res for the response interface (an instance of AnyEvent::Finger::Response).

With the response object you can return a whole response at one time:

 $tx->res->say(
   "this is the first line", 
   "this is the second line", 
   "there will be no forth line",
 );
 $tx->res->done;

or you can send line one at a time as they become available (possibly asynchronously).

 # $dbh is a DBI database handle
 my $sth = $dbh->prepare("select user_name from user_list");
 while(my $h = $sth->fetchrow_hashref)
 {
   $tx->res->say($h->{user_name});
 }
 $tx->res->done;

The server will unbind from its port and stop if the server object falls out of scope, or if the stop method (see below) is called.

bindport

 $server->bindport

The bind port. If port is set to zero in the constructor or on start, then an ephemeral port will be used, and you can get the port number here. This value is not available until the socket has been allocated and bound to a port, so if you need this value after calling start but before any clients have connected use the on_bind callback.

stop

 $server->stop

Stop the server and unbind to the port.

SEE ALSO

• AnyEvent::Finger

• AnyEvent::Finger::Client

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm AnyEvent::Finger

perl -MCPAN -e shell
install AnyEvent::Finger