NAME¶

Furl - Lightning-fast URL fetcher

SYNOPSIS¶

    use Furl;
    my $furl = Furl->new(
        agent   => 'MyGreatUA/2.0',
        timeout => 10,
    );
    my $res = $furl->get('http://example.com/');
    die $res->status_line unless $res->is_success;
    print $res->content;
    my $res = $furl->post(
        'http://example.com/', # URL
        [...],                 # headers
        [ foo => 'bar' ],      # form data (HashRef/FileHandle are also okay)
    );
    # Accept-Encoding is supported but optional
    $furl = Furl->new(
        headers => [ 'Accept-Encoding' => 'gzip' ],
    );
    my $body = $furl->get('http://example.com/some/compressed');

DESCRIPTION¶

Furl is yet another HTTP client library. LWP is the de facto standard HTTP client for Perl 5, but it is too slow for some critical jobs, and too complex for weekend hacking. Furl resolves these issues. Enjoy it!

INTERFACE¶

    my $req = HTTP::Request->new(...);
    my $res = $furl->request($req);

TIPS¶

IO::Socket::SSL preloading

Furl interprets the "timeout" argument as the maximum time the module is permitted to spend before returning an error.

The module also lazy-loads IO::Socket::SSL when an HTTPS request is being issued for the first time. Loading the module usually takes ~0.1 seconds.

The time spent for loading the SSL module may become an issue in case you want to impose a very small timeout value for connection establishment. In such case, users are advised to preload the SSL module explicitly.

FAQ¶

Does Furl depends on XS modules?

No. Although some optional features require XS modules, basic features are available without XS modules.

Note that Furl requires HTTP::Parser::XS, which seems an XS module but includes a pure Perl backend, HTTP::Parser::XS::PP.

I need more speed.

See Furl::HTTP, which provides the low level interface of Furl. It is faster than "Furl.pm" since Furl::HTTP does not create response objects.

How do you use cookie_jar?

Furl does not directly support the cookie_jar option available in LWP. You can use HTTP::Cookies, HTTP::Request, HTTP::Response like following.

    my $f = Furl->new();
    my $cookies = HTTP::Cookies->new();
    my $req = HTTP::Request->new(...);
    $cookies->add_cookie_header($req);
    my $res = $f->request($req)->as_http_response;
    $res->request($req);
    $cookies->extract_cookies($res);
    # and use $res.
    

How do you limit the response content length?

You can limit the content length by callback function.

    my $f = Furl->new();
    my $content = '';
    my $limit = 1_000_000;
    my %special_headers = ('content-length' => undef);
    my $res = $f->request(
        method          => 'GET',
        url             => $url,
        special_headers => \%special_headers,
        write_code      => sub {
            my ( $status, $msg, $headers, $buf ) = @_;
            if (($special_headers{'content-length'}||0) > $limit || length($content) > $limit) {
                die "over limit: $limit";
            }
            $content .= $buf;
        }
    );
    

How do you display the progress bar?

    my $bar = Term::ProgressBar->new({count => 1024, ETA => 'linear'});
    $bar->minor(0);
    $bar->max_update_rate(1);
    my $f = Furl->new();
    my $content = '';
    my %special_headers = ('content-length' => undef);;
    my $did_set_target = 0;
    my $received_size = 0;
    my $next_update  = 0;
    $f->request(
        method          => 'GET',
        url             => $url,
        special_headers => \%special_headers,
        write_code      => sub {
            my ( $status, $msg, $headers, $buf ) = @_;
            unless ($did_set_target) {
                if ( my $cl = $special_headers{'content-length'} ) {
                    $bar->target($cl);
                    $did_set_target++;
                }
                else {
                    $bar->target( $received_size + 2 * length($buf) );
                }
            }
            $received_size += length($buf);
            $content .= $buf;
            $next_update = $bar->update($received_size)
            if $received_size >= $next_update;
        }
    );
    

HTTPS requests claims warnings!

When you make https requests, IO::Socket::SSL may complain about it like:

    *******************************************************************
     Using the default of SSL_verify_mode of SSL_VERIFY_NONE for client
     is depreciated! Please set SSL_verify_mode to SSL_VERIFY_PEER
     together with SSL_ca_file|SSL_ca_path for verification.
     If you really don't want to verify the certificate and keep the
     connection open to Man-In-The-Middle attacks please set
     SSL_verify_mode explicitly to SSL_VERIFY_NONE in your application.
    *******************************************************************
    

You should set "SSL_verify_mode" explicitly with Furl's "ssl_opts".

    use IO::Socket::SSL;
    my $ua = Furl->new(
        ssl_opts => {
            SSL_verify_mode => SSL_VERIFY_PEER(),
        },
    );
    

See IO::Socket::SSL for details.

AUTHOR¶

Tokuhiro Matsuno <tokuhirom@gmail.com>

Fuji, Goro (gfx)

THANKS TO¶

Kazuho Oku

mala

mattn

lestrrat

walf443

lestrrat

audreyt

SEE ALSO¶

LWP

IO::Socket::SSL

Furl::HTTP

Furl::Response

LICENSE¶

Copyright (C) Tokuhiro Matsuno.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.