/ 
POE-0.9999
River stage three • 402 direct dependents • 539 total dependents
/ POE::Filter::HTTPD

NAME

POE::Filter::HTTPD - convert stream to HTTP::Request; HTTP::Response to stream

SYNOPSIS

$httpd = POE::Filter::HTTPD->new();
$arrayref_with_http_response_as_string =
  $httpd->put($full_http_response_object);
$arrayref_with_http_request_object =
  $line->get($arrayref_of_raw_data_chunks_from_driver);

DESCRIPTION

The HTTPD filter parses the first HTTP 1.0 request from an incoming stream into an HTTP::Request object (if the request is good) or an HTTP::Response object (if the request was malformed). To send a response, give its put() method a HTTP::Response object.

Here is a sample input handler:

sub got_request {
  my ($heap, $request) = @_[HEAP, ARG0];

  # The Filter::HTTPD generated a response instead of a request.
  # There must have been some kind of error.  You could also check
  # (ref($request) eq 'HTTP::Response').
  if ($request->isa('HTTP::Response')) {
    $heap->{wheel}->put($request);
    return;
  }

  # Process the request here.
  my $response = HTTP::Response->new(200);
  $response->push_header( 'Content-Type', 'text/html' );
  $response->content( $request->as_string() );

  $heap->{wheel}->put($response);
}

Please see the documentation for HTTP::Request and HTTP::Response.

PUBLIC FILTER METHODS

Please see POE::Filter.

CAVEATS

It is possible to generate invalid HTTP using libwww. This is specifically a problem if you are talking to a Filter::HTTPD driven daemon using libwww. For example, the following code (taken almost verbatim from the HTTP::Request::Common documentation) will cause an error in a 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. 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 perfectly possible to use Filter::HTTPD for streaming output media. Even if it's not possible to change the input filter from Filter::HTTPD, by setting the output_filter to Filter::Stream and omitting any content in the HTTP::Response object.

$wheel->put($response); # Without content, it sends just headers.
$wheel->set_output_filter(POE::Filter::Stream->new());
$wheel->put("Raw content.");

SEE ALSO

POE::Filter.

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

BUGS

  • Keep-alive is not supported.

  • The full http 1.0 spec is not supported, specifically DELETE, LINK, and UNLINK.

AUTHORS & COPYRIGHTS

The HTTPD filter was contributed by Artur Bergman.

Please see POE for more information about authors and contributors.