• NAME
• SYNOPSIS
• DESCRIPTION
• PUBLIC FILTER METHODS
• CAVEATS
• Streaming Media
• SEE ALSO
• BUGS
• AUTHORS & COPYRIGHTS

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.