The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Hijk-0.12
River stage one • 5 direct dependents • 5 total dependents
14 ++
/ Hijk

NAME

Hijk - Specialized HTTP client

SYNOPSIS

A simple GET request:

    use Hijk;
    my $res = Hijk::request({
        method       => "GET",
        host         => "example.com",
        port         => "80",
        path         => "/flower",
        query_string => "color=red"
    });

    if (exists $res->{error} and $res->{error} & Hijk::Error::TIMEOUT) {
        die "Oh noes we had some sort of timeout";
    }

    die unless ($res->{status} == "200");

    say $res->{body};

A POST request, you have to manually set the appropriate headers, URI escape your values etc.

    use Hijk;
    use URI::Escape qw(uri_escape);

    my $res = Hijk::request({
        method       => "POST",
        host         => "example.com",
        port         => "80",
        path         => "/new",
        head         => [ "Content-Type" => "application/x-www-form-urlencoded" ],
        query_string => "type=flower&bucket=the%20one%20out%20back",
        body         => "description=" . uri_escape("Another flower, let's hope it's exciting"),
    });

    die unless ($res->{status} == "200");

DESCRIPTION

Hijk is a specialized HTTP Client that does nothing but transport the response body back. It does not feature as a "user agent", but as a dumb client. It is suitable for connecting to data servers transporting via HTTP rather then web servers.

Most of HTTP features like proxy, redirect, Transfer-Encoding, or SSL are not supported at all. For those requirements we already have many good HTTP clients like HTTP::Tiny, Furl or LWP::UserAgent.

FUNCTION: Hijk::request( $args :HashRef ) :HashRef

Hijk::request is the only function to be used. It is not exported to its caller namespace at all. It takes a request arguments in HashRef and returns the response in HashRef.

The $args request arg should be a HashRef containing key-value pairs from the following list. The value for host and port are mandatory and others are optional with default values listed below

    protocol        => "HTTP/1.1", # (or "HTTP/1.0")
    host            => ...,
    port            => ...,
    connect_timeout => 0,
    read_timeout    => 0,
    method          => "GET",
    path            => "/",
    query_string    => "",
    head            => [],
    body            => "",
    socket_cache    => {}, # (undef to disable, or \my %your_socket_cache)
    on_connect      => undef, # (or sub { ... })

To keep the implementation minimal, Hijk does not take full URL string as input. User who need to parse URL string could use URI modules.

The value of head is an ArrayRef of key-value pairs instead of HashRef, this way the order of headers can be maintained. For example:

    head => [
        "Content-Type" => "application/json",
        "X-Requested-With" => "Hijk",
    ]

... will produce these request headers:

    Content-Type: application/json
    X-Requested-With: Hijk

Again, there are no extra character-escaping filters within Hijk.

The value of connect_timeout or read_timeout is in seconds, and is used as the time limit for connecting to the host, and reading from the socket, respectively. You can't provide a non-zero read timeout without providing a non-zero connect timeout, as the socket has to be set up with the O_NONBLOCK flag for the read_timeout to work, which we only do if we have a connect_timeout. The default value for both is 0, meaning no timeout limit. If the host is really unreachable or slow, we'll reach the TCP timeout limit before dying.

The optional on_connect callback is intended to be used for you to figure out from production traffic what you should set the connect_timeout. I.e. you can start a timer when you call Hijk::request() that you end when on_connect is called, that's how long it took us to get a connection. If you start another timer in that callback that you end when Hijk::request() returns to you that'll give you how long it took to send/receive data after we constructed the socket, i.e. it'll help you to tweak your read_timeout. The on_connect callback is provided with no arguments, and is called in void context.

The default protocol is HTTP/1.1, but you can also specify HTTP/1.0. The advantage of using HTTP/1.1 is support for keep-alive, which matters a lot in environments where the connection setup represents non-trivial overhead. Sometimes that overhead is negligible (e.g. on Linux talking to an nginx on the local network), and keeping open connections down and reducing complexity is more important, in those cases you can use HTTP/1.0.

By default we will provide a socket_cache for you which is a global singleton that we maintain keyed on join($;, $$, $host, $port). Alternatively you can pass in socket_cache hash of your own which we'll use as the cache. To completely disable the cache pass in undef.

The return vaue is a HashRef representing a response. It contains the following key-value pairs.

    proto  => :Str
    status => :StatusCode
    body   => :Str
    head   => :HashRef
    error  => :Int

For example, to send request to http://example.com/flower?color=red, use the following code:

    my $res = Hijk::request({
        host => "example.com",
        port => "80",
        path => "/flower",
        query_string => "color=red"
    });
    die "Response is not OK" unless $res->{status} ne "200";

Notice that you do not need to put the leading "?" character in the query_string. You do, however, need to propery uri_escape the content of query_string.

All values are assumed to be valid. Hijk simply passes the values through without validating the content. It is possible that it constructs invalid HTTP Messages. Users should keep this in mind when using Hijk.

Noticed that the head in the response is a HashRef rather then an ArrayRef. This makes it easier to retrieve specific header fields.

We currently don't support servers returning a http body without an accompanying Content-Length header; bodies MUST have a Content-Length or we won't pick them up.

ERROR CODES

If we had an error we'll include an "error" key whose value is a bitfield that you can check against Hijk::Error::* constants. Those are:

Hijk::Error::CONNECT_TIMEOUT
Hijk::Error::READ_TIMEOUT
Hijk::Error::TIMEOUT
Hijk::Error::CANNOT_RESOLVE

The Hijk::Error::TIMEOUT constant is the same as Hijk::Error::CONNECT_TIMEOUT | Hijk::Error::READ_TIMEOUT. It's there for convenience so you can do:

    .. if exists $res->{error} and $res->{error} & Hijk::Error::TIMEOUT;

Instead of the more verbose:

    .. if exists $res->{error} and $res->{error} & (Hijk::Error::CONNECT_TIMEOUT | Hijk::Error::READ_TIMEOUT)

We'll return Hijk::Error::CANNOT_RESOLVE if we can't gethostbyname() the host you've provided.

Hijk WILL call die if any system calls that it executes fail with errors that aren't covered by Hijk::Error::*, so wrap it in an eval if you don't want to die in those cases. We just provide Hijk::Error::* for non-exceptional failures like timeouts, not for e.g. you trying to connect to a host that doesn't exist or a socket unexpectedly going away etc.

AUTHORS

Kang-min Liu <gugod@gugod.org>
Ævar Arnfjörð Bjarmason <avar@cpan.org>
Borislav Nikolov <jack@sofialondonmoskva.com>
Damian Gryski <damian@gryski.com>

COPYRIGHT

Copyright (c) 2013 Kang-min Liu <gugod@gugod.org>.

LICENCE

The MIT License

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.