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.