/ 
POE-Filter-HTTPD-Chunked-0.9
River stage one • 1 direct dependent • 1 total dependent
/ POE::Filter::HTTPD::Chunked

NAME

POE::Filter::HTTPD::Chunked - Drop-in replacement for POE::Filter::HTTPD that also support HTTP1.1 chunked transfer-encoding.

SYNOPSIS

#!perl

use warnings;
use strict;

use POE qw(Component::Server::TCP Filter::HTTPD::Chunked);
use HTTP::Response;

POE::Component::Server::TCP->new(
  Port         => 8088,
  ClientFilter => 'POE::Filter::HTTPD::Chunked',

  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>" .
      "<tr><td>Body</td><td>" . $request->content . "</td>" .
      "</body></html>"
    );

    $_[HEAP]{client}->put($response);
    $_[KERNEL]->yield("shutdown");
  }
);

print "Aim your browser at port 8088 of this host.\n";
POE::Kernel->run();
exit;

For detail and an example of handling partial chunks, see "Handling of partial chunked data" below.

DESCRIPTION

POE::Filter::HTTPD::Chunked interprets input streams as HTTP requests. It returns a HTTP::Request object 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, this module accepts HTTP::Response objects and returns their corresponding streams.

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

The following are the major differences between this module and the core POE POE::Filter::HTTPD:

handling of incoming chunked data

POE::Filter::HTTPD has no support for handling 'chunked' requests (part of HTTP1.1 spec), and would return an error (in the form of an HTTP::Response object returned to the POE session). For many applications, this may not be a problem, as they can put an HTTP1.1 proxy in front of the application, that will de-chunk the request, and return the normal HTTP/1.0 content-length. This method, however, causes issues with applications that either a/ want to handle partial content for a request as it comes in, b/ don't want to have to artificially adjust request timeouts whilst waiting for the proxy to get the full request or c/ don't want the additional system complexity of having to use a proxy to dechunk.

support for any request type

POE::Filter::HTTPD didn't handle all request types (ie, DELETE). This restriction has been removed in this module.

PUBLIC FILTER METHODS

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

Handling of partial chunked data.

In order to allow for partial handling of data, if an optional constructor argument of 'event_on_chunk' is passed in with a true value, and a partial chunked request has been received since the last time the wheel causes a 'get' call to be emitted, the partial chunked data is returned back. This is wrapped in a class of HTTP::Request::Chunked, which is just a marker sub-class of HTTP::Request, with the following detail set:

content

Will be set to the partial content that has been received, since the last HTTP::Request::Chunked packet was returned.

x-chunk-offset header

The offset (in bytes) as to where the current partial content starts.

x-chunk-offset-size header

The number of bytes in this partial chunk.

Note that the final chunk will never be returned as an HTTP::Request::Chunked object. Instead, the full request will be returned as an HTTP::Request object instead.

An example usage of how partial chunks is as-follows:

my $filter = POE::Filter::HTTPD::Chunked->new( event_on_chunk => 1 );

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

    if ( $request->isa( 'HTTP::Response' ) ) {
        # if we get an HTTP::Response object in, this was due to an error
        # in parsing the request.  Just return to client.

        $heap->{ wheel }->put( $request );
    } elsif ( $request->isa( 'HTTP::Request::Chunked' ) ) {
        # more data has come in for the given request.  Can just be used
        # to reset timeout, or to deal with the data within it.

        $kernel->alarm( 'reset_timer' => time() + 30 );

        printf(
           "got partial data of '%s' from byte offset %i, with size of %i",
           $request->content,
           $request->header( 'x-chunk-offset' ),
           $request->header( 'x-chunk-offset-size' ),
       );
    } else {
        # got a completed request.  This will be an HTTP::Request object,
        # populated with all data from the original request, converted to
        # non-chunked format.  If any body was included in the request, be
        # it chunked or not, a content-length header will be set, giving
        # the number of bytes in the body.

        printf(
           "got complete request of '%s', with size of '%i'",
           $request->content,
           $request->header( 'content-length' )
       );
    }
}

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

SEE ALSO

POE::Filter::HTTPD - Original basis for this class. Note that much of the original POE::Filter::HTTPD code is redone for this class, due to different requirements. Assume that any errors that occour in POE::Filter::HTTPD::Chunked are mine, and not based on this module.

POE::Filter - Superclass, for general Filter API.

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.

AUTHORS AND LICENSE

Mark Morgan <makk384@gmail.com>

Tom Clark <tom@woot.co.uk>

This modules is bassed off of POE::Filter::HTTPD module, contributed by Arthur Bergman, with documentation provided by Rocco Caputo.

Thanks to trutap (www.trutap.com) for paying us whilst developing this code, and allowing it to be released.

Copyright (c) 2008-2010 Mark Morgan. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.