/ 
IO-Stream-HTTP-Persistent-v0.2.2
River stage zero No dependents
/ IO::Stream::HTTP::Persistent

NAME

IO::Stream::HTTP::Persistent - HTTP persistent connections plugin

VERSION

This document describes IO::Stream::HTTP::Persistent version v0.2.2

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

$plugin = IO::Stream::HTTP::Persistent->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

AUTHOR

Alex Efros <powerman@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2012- by Alex Efros <powerman@cpan.org>.

This is free software, licensed under:

The MIT (X11) License