Permalink
Browse files

Document that it's good practice to scrap the connection when there's

a client error.
  • Loading branch information...
1 parent 571b47a commit 89ff2b1a0165bd1e55c9a44c7d70ff16e924789c @rcaputo committed Aug 27, 2009
Showing with 19 additions and 7 deletions.
  1. +19 −7 lib/POE/Filter/HTTPD.pm
View
@@ -414,14 +414,15 @@ POE::Filter::HTTPD - parse simple HTTP requests, and serialize HTTP::Response
=head1 DESCRIPTION
POE::Filter::HTTPD interprets input streams as HTTP 0.9, 1.0 or 1.1
-requests. It returns a HTTP::Request objects upon successfully parsing a
-request.
+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. The erroneous request object is
-sometimes available via the L<HTTP::Response/request> method. This is
-illustrated in the L</SYNOPSIS>.
+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. The
+erroneous request object is sometimes available via the
+L<HTTP::Response/request> method. This is illustrated in the
+L</SYNOPSIS>.
For output, POE::Filter::HTTPD accepts HTTP::Response objects and
returns their corresponding streams.
@@ -455,6 +456,17 @@ 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.
+Upon handling a request error, it is most expedient and reliable to
+respond with the error and shut down the connection. Invalid HTTP
+requests may corrupt the request stream. For example, the absence of
+a Content-Length header signals that a request has no content.
+Requests with content but not that header will be broken into a
+content-less request and invalid data. The invalid data may also
+appear to be a request! Hilarity will ensue, possibly repeatedly,
+until the filter can find the next valid request. By shutting down
+the connection on the first sign of error, the client can retry its
+request with a clean connection and filter.
+
=head1 Streaming Media
It is possible to use POE::Filter::HTTPD for streaming content, but an

0 comments on commit 89ff2b1

Please sign in to comment.