POE::Filter::HTTPD.3pm

Langue: en

Autres versions - même langue

Version: 2008-07-05 (fedora - 05/07/09)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

POE::Filter::HTTPD - parse simple HTTP requests, and serialize HTTP::Response

SYNOPSIS

   #!perl
 
   use warnings;
   use strict;
 
   use POE qw(Component::Server::TCP Filter::HTTPD);
   use HTTP::Response;
 
   POE::Component::Server::TCP->new(
     Port         => 8088,
     ClientFilter => 'POE::Filter::HTTPD',  ### <-- HERE WE ARE!
 
     ClientInput => sub {
       my $request = $_[ARG0];
 
       # It's a response for the client if there was a problem.
       if ($request->isa("HTTP::Response")) {
         $_[HEAP]{client}->put($request);
         $_[KERNEL]->yield("shutdown");
         return;
       }
 
       my $request_fields = '';
       $request->headers()->scan(
         sub {
           my ($header, $value) = @_;
           $request_fields .= (
             "<tr><td>$header</td><td>$value</td></tr>"
           );
         }
       );
 
       my $response = HTTP::Response->new(200);
       $response->push_header( 'Content-type', 'text/html' );
       $response->content(
         "<html><head><title>Your Request</title></head>" .
         "<body>Details about your request:" .
         "<table border='1'>$request_fields</table>" .
         "</body></html>"
       );
 
       $_[HEAP]{client}->put($response);
       $_[KERNEL]->yield("shutdown");
     }
   );
 
   print "Aim your browser at port 8088 of this host.\n";
   POE::Kernel->run();
   exit;

DESCRIPTION

POE::Filter::HTTPD interprets input streams as HTTP 0.9 or 1.0 requests. It returns a HTTP::Request objects upon successfully parsing a request. On failure, it returns an HTTP::Response object describing the failure. The intention is that application code will notice the HTTP::Response and send it back without further processing. This is illustrated in the ``SYNOPSIS''.

For output, POE::Filter::HTTPD accepts HTTP::Response objects and returns their corresponding streams.

Please see HTTP::Request and HTTP::Response for details about how to use these objects.

PUBLIC FILTER METHODS

POE::Filter::HTTPD implements the basic POE::Filter interface.

CAVEATS

Some versions of libwww are known to generate invalid HTTP. For example, this code (adapted from the HTTP::Request::Common documentation) will cause an error in a POE::Filter::HTTPD daemon: 
   use HTTP::Request::Common;
   use LWP::UserAgent;
 
   my $ua = LWP::UserAgent->new();
   $ua->request(POST 'http://some/poe/driven/site', [ foo => 'bar' ]);

By default, HTTP::Request is HTTP version agnostic. It makes no attempt to add an HTTP version header unless you specifically declare a protocol using "$request->protocol('HTTP/1.0')".

According to the HTTP 1.0 RFC (1945), when faced with no HTTP version header, the parser is to default to HTTP/0.9. POE::Filter::HTTPD follows this convention. In the transaction detailed above, the Filter::HTTPD based daemon will return a 400 error since POST is not a valid HTTP/0.9 request type.

Streaming Media

It is possible to use POE::Filter::HTTPD for streaming content, but an application can use it to send headers and then switch to POE::Filter::Stream.

From the input handler (the InputEvent handler if you're using wheels, or the ClientInput handler for POE::Component::Server::TCP):

   my $response = HTTP::Response->new(200);
   $response->push_header('Content-type', 'audio/x-mpeg');
   $_[HEAP]{client}->put($response);
   $_[HEAP]{client}->set_output_filter(POE::Filter::Stream->new());

Then the output-flushed handler (FlushEvent for POE::Wheel::ReadWrite, or ClientFlushed for POE::Component::Server::TCP) can put() chunks of the stream as needed.

   my $bytes_read = sysread(
     $_[HEAP]{file_to_stream}, my $buffer = '', 4096
   );
 
   if ($bytes_read) {
     $_[HEAP]{client}->put($buffer);
   }
   else {
     delete $_[HEAP]{file_to_stream};
     $_[KERNEL]->yield("shutdown");
   }

SEE ALSO

Please see POE::Filter for documentation regarding the base interface.

The SEE ALSO section in POE contains a table of contents covering the entire POE distribution.

HTTP::Request and HTTP::Response explain all the wonderful things you can do with these classes.

BUGS

Many aspects of HTTP 1.0 and higher are not supported, such as keep-alive. A simple I/O filter can't support keep-alive, for example. A number of more feature-rich POE HTTP servers are on the CPAN. See <http://search.cpan.org/search?query=POE+http+server&mode=dist>

AUTHORS & COPYRIGHTS

POE::Filter::HTTPD was contributed by Artur Bergman. Documentation is provided by Rocco Caputo.

Please see POE for more information about authors and contributors.