NAME IO::Stream::HTTP::Persistent - HTTP persistent connections plugin VERSION This document describes IO::Stream::HTTP::Persistent version v0.1.0 SYNOPSIS use IO::Stream; use IO::Stream::HTTP::Persistent; IO::Stream->new({ ... wait_for => EOF|HTTP_SENT|HTTP_RECV, cb => \&io, out_buf => join(q{}, @http_requests), ... plugin => [ ... http => IO::Stream::HTTP::Persistent->new(), ... ], }); sub io { my ($io, $e, $err) = @_; my $http = $io->{plugin}{http}; if ($e & HTTP_SENT) { printf "%d requests was sent\n", 0+@{ $http->{out_sizes} }; $http->{out_sizes} = []; } if ($e & HTTP_RECV) { while (my $size = shift @{ $http->{in_sizes} }) { my $http_reply = substr $io->{in_buf}, 0, $size, q{}; ... } } ... } DESCRIPTION This module is plugin for IO::Stream which allow you to process complete HTTP requests and responses read/written by this stream. It's useful only for persistent HTTP connections (HTTP/1.0 with Keep-Alive and HTTP/1.1). On usual HTTP/1.0 non-persistent connections it's ease to detect sent HTTP request using SENT event and received HTTP response using EOF event. But on persistent connections that's become much more complicated: to detect end of single received HTTP response (or boundaries between several received responses) you have to parse HTTP protocol, and when HTTP/1.1 Pipelining is used it's not easy to find out how many complete requests was already sent. This module will parse HTTP protocol for sent and received data, and will generate non-standard events HTTP_SENT and HTTP_RECV when one or more complete HTTP requests will be sent or HTTP responses received. It will provide you with list of sizes for each sent request and received response, which make it ease to find how many requests was sent or get separate responses from {in_buf}. EXPORTS This modules doesn't export any functions/methods/variables, but it exports some constants. There two groups of constants: events and errors (which can be imported using tags ':Event' and ':Error'). By default all constants are exported. Events: HTTP_SENT HTTP_RECV Errors: HTTP_EREQINCOMPLETE HTTP_ERESINCOMPLETE Errors are similar to $! - they're dualvars, having both textual and numeric values. INTERFACE new() Create and return new IO::Stream plugin object. PUBLIC FIELDS in_sizes =[] out_sizes =[] Size of each complete sent HTTP request or received HTTP response will be pushed into these fields. You can remove elements from these arrays if you need, but you should keep these fields in ARRAYREF format. EVENTS HTTP_SENT HTTP_RECV These non-standard events will be generated when one or more complete HTTP requests will be sent or one or more HTTP responses will be received. Their sizes will be push()ed into fields {out_sizes} and {in_sizes} before generating events. Instead of using these events you can use standard IN and OUT events and check is new items was added to {out_sizes} and {in_sizes}. ERRORS HTTP_EREQINCOMPLETE All HTTP headers of one request MUST be appended to {out_buf} using single $io->write(), otherwise you'll get HTTP_EREQINCOMPLETE. It's safe to add request body after that using any amount of $io->write(). You can safely continue I/O after receiving HTTP_EREQINCOMPLETE, but after that error you'll not get HTTP_SENT event and {out_sizes} won't be updated anymore. HTTP_ERESINCOMPLETE Unexpected EOF happens while receiving HTTP response. LIMITATIONS * This plugin usually should be first (top) plugin in IO::Stream object's plugin chain, because if upper plugins will somehow modify {in_buf} or {out_buf} then values in {in_sizes} and {out_sizes} may become wrong. * {out_buf} MUST NOT be modified in any way except by appending new data. * Partial HTTP response in {in_buf} MUST NOT be modified. It's safe to cut from start of {in_buf} complete HTTP responses. SUPPORT Bugs / Feature Requests Please report any bugs or feature requests through the issue tracker at https://github.com/powerman/perl-IO-Stream-HTTP-Persistent/issues. You will be notified automatically of any progress on your issue. Source Code This is open source software. The code repository is available for public review and contribution under the terms of the license. Feel free to fork the repository and submit pull requests. https://github.com/powerman/perl-IO-Stream-HTTP-Persistent git clone https://github.com/powerman/perl-IO-Stream-HTTP-Persistent.git Resources * MetaCPAN Search https://metacpan.org/search?q=IO-Stream-HTTP-Persistent * CPAN Ratings http://cpanratings.perl.org/dist/IO-Stream-HTTP-Persistent * AnnoCPAN: Annotated CPAN documentation http://annocpan.org/dist/IO-Stream-HTTP-Persistent * CPAN Testers Matrix http://matrix.cpantesters.org/?dist=IO-Stream-HTTP-Persistent * CPANTS: A CPAN Testing Service (Kwalitee) http://cpants.cpanauthors.org/dist/IO-Stream-HTTP-Persistent AUTHOR Alex Efros COPYRIGHT AND LICENSE This software is Copyright (c) 2012 by Alex Efros . This is free software, licensed under: The MIT (X11) License