名前¶

Furl::HTTP - Furlの低レベルのインターフェース

概要¶

    use Furl;

    my $furl = Furl::HTTP->new(
        agent   => 'MyGreatUA/2.0',
        timeout => 10,
    );

    my ($minor_version, $code, $msg, $headers, $body) = $furl->request(
        method     => 'GET',
        host       => 'example.com',
        port       => 80,
        path_query => '/'
    );
    # or

    # Accept-Encoding is supported but optional
    $furl = Furl->new(
        headers => [ 'Accept-Encoding' => 'gzip' ],
    );
    my $body = $furl->get('http://example.com/some/compressed');

説明¶

Furlはもう一つのHTTPクライアントライブラリです。LWPはPerl5のデファクトスタンダードな HTTPクライアントですが、クリティカルなジョブでは遅すぎますし、週末のハッキングには 複雑過ぎます。Furlはこれらの問題を解決します。楽しんで下さい！

このライブラリは ベータソフトウェアです。予告なくAPIが変更されるかも知れません。

インターフェース¶

クラスメソッド¶

Furl::HTTP->new(%args | \%args) :Furl¶

新しいFurlクライアントを%argsで作ります。エラーがあると死にます。

%args は:

agent :Str = "Furl/$VERSION"

timeout :Int = 10

Seconds until the call to $furl->request returns a timeout error (as an internally generated 500 error). The timeout might not be accurate since some underlying modules / built-ins function may block longer than the specified timeout. See the FAQ for how to support timeout during name resolution.

$furl->request の呼出がタイムアウトエラーを返すまでの秒数(内部的に500エラー)。基礎となるモジュール/組込の関数が指定の時間より長くブロックするかもしれないので、タイムアウトは正確ではないかもせいれません。名前解決時のタイムアウトサポートする方法はFAQを見てください。

max_redirects :Int = 7

proxy :Str

no_proxy :Str

headers :ArrayRef

header_format :Int = HEADERS_AS_ARRAYREF

This option choose return value format of $furl->request.

このオプションでは<$furl-request>>の返す値のフォーマットを選びます。

This option allows HEADERS_NONE or HEADERS_AS_ARRAYREF.

HEADERS_NONE か HEADERS_AS_ARRAYREF を使えます。

HEADERS_AS_ARRAYREF is a default value. This makes $headers as ArrayRef.

HEADERS_AS_ARRAYREF> はデフォルト値です。$headersをArrayRefとして作ります。

HEADERS_NONE makes $headers as undef. Furl does not return parsing result of headers. You should take needed headers from special_headers.

HEADERS_NONE $headers を undef にします。Furlヘッダを解析した結果を返しません。 special_headersから必要なヘッダ受けとるべきです。

connection_pool

This is the connection pool object for keep-alive requests. By default, it is a instance of Furl::ConnectionCache.

keep-aliveリクエスト用のコネクションプールオブジェクトです。デフォルトではFurl::ConnectionCacheのインスタンスです。

You may not customize this variable otherwise to use Coro. This attribute requires a duck type object. It has two methods, $obj->steal($host, $port and $obj->push($host, $port, $sock).

Coro を使う以外の方法でこの値をカスタマイズできないでしょう。このアトリビュートはダックタイプオブジェクトを必要とします。2つのメソッド、$obj->steal($host, $port と $obj->push($host, $port, $sock) があります。

stop_if

A callback function that is called by Furl after when a blocking function call returns EINTR. Furl will abort the HTTP request and return immediately if the callback returns true. Otherwise the operation is continued (the default behaviour).

ブロッキング関数がEINTRを呼んだ後にFurlが呼ぶコールバック関数です。コールバックが真なら、FurlはHTTPリクエストを中断し、即座に戻ります。そうでなければ、オペレーションは続行されます(デフォルトの挙動)。

inet_aton

A callback function to customize name resolution. Takes two arguments: ($hostname, $timeout_in_seconds). If omitted, Furl calls Socket::inet_aton.

名前解決をカスタマイズするためのコールバック関数です。2つの引数を取ります: ($hostname, $timeout_in_seconds)。省略すると、FurlはSocket::inet_atonを呼びます。

Instance Methods¶

$furl->request(%args) :($protocol_minor_version, $code, $msg, \@headers, $body)¶

HTTPリクエストを指定したURLへ送り、プロトコルのマイナーバージョン、ステータスコード、 ステータースメッセージ、レスポンスヘッダー、レスポンスボディーをそれぞれ返します。

%args は:

scheme :Str = "http"

Protocol scheme. May be http or https.

プロトコロスキーマ。http か https でしょう。

host :Str

Server host to connect.

接続するサーバホスト。

You must specify at least host or url.

host か urlのいずれかを指定しなければいけません。

port :Int = 80

Server port to connect. The default is 80 on scheme => 'http', or 443 on scheme => 'https'.

接続するサーバのポート。デフォルトは、schema => 'http'なら80で、 scheme => 'https'なら、443です。

path_query :Str = "/"

Path and query to request.

リクエストするパスとクエリ。

url :Str

URL to request.

リクエストするURL。

You can use url instead of scheme, host, port and path_query.

schema、host、port、path_queryを指定する代わりにurlを使えます。

headers :ArrayRef

HTTP request headers. e.g. headers => [ 'Accept-Encoding' => 'gzip' ].

HTTPリクエストヘッダ。例 headers => [ 'Accept-Encoding' => 'gzip' ].

content : Str | ArrayRef[Str] | HashRef[Str] | FileHandle

Content to request.

リクエストする内容。

write_file : FileHandle

If this parameter is set, the response content will be saved here instead of in the response object.

このパラメータがセットされていると、レスポンスの内容はレスポンスオブジェクトではなく指定されたファイルハンドル に保存されます。

It's like a ':content_file' in LWP::UserAgent.

LWP::UserAgentの':content_file'と似ています。

write_code : CodeRef

If a callback is provided with the "write_code" option then this function will be called for each chunk of the response content as it is received from the server.

"write_code"オプションでコールバックを指定した場合、 この関数は、サーバから受け取るレスポンスの内容のチャンク毎に呼ばれます。

It's like a ':content_cb' in LWP::UserAgent.

LWP::UserAgentの':content_cb'と似ています。

response() メソッドは引数が奇数の場合、最初の引数をHTTP::Requestのインスタンスと想定します。

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

すべてのクエリをエンコードする必要があります。さもなくば、Wide character in ... を吐いて死にます。

$furl->get($url :Str, $headers :ArrayRef[Str] )¶

request()簡単に使うためのエイリアスです。GETメソッドを送ります。

$furl->head($url :Str, $headers :ArrayRef[Str] )¶

request()簡単に使うためのエイリアスです。HEDメソッドを送ります。

$furl->post($url :Str, $headers :ArrayRef[Str], $content :Any)¶

request()簡単に使うためのエイリアスです。POSTメソッドを送ります。

$furl->put($url :Str, $headers :ArrayRef[Str], $content :Any)¶

request()簡単に使うためのエイリアスです。PUTメソッドを送ります。

$furl->delete($url :Str, $headers :ArrayRef[Str] )¶

request()簡単に使うためのエイリアスです。DELETEメソッドを送ります。

FAQ¶

どうして IO::Socket::SSL?

(Why IO::Socket::SSL?)

Net::SSL is not well documented.

Net::SSL はドキュメントが貧弱です。

env_proxy はなぜオプショナルなのですか?

(Why is env_proxy optional?)

Environment variables are highly dependent on each users' environment, and we think it may confuse users when something doesn't go right.

環境変数はユーザーの環境に強く依存します。 うまく動かないときにユーザーを混乱させます。

サポートしているオペレーティングシステムは?

(What operating systems are supported?)

Linux 2.6 or higher, OSX Tiger or higher, Windows XP or higher.

Linux 2.6 以上、 OSX Tiger 以上、 Windows XP 以上。

And other operating systems will be supported if you send a patch.

あなたがパッチを送れば、他のオペレーティングシステムもサポートされるでしょう。

なぜFurlはチャンクされたアップロードをサポートしないのですか?

(Why doesn't Furl support chunked upload?)

There are reasons why chunked POST/PUTs should not be used in general.

一般的に、チャンクされたPOST/PUTをなぜ使うべきではないかという理由があります。

First, you cannot send chunked requests unless the peer server at the other end of the established TCP connection is known to be a HTTP/1.1 server.

まず、確立されたTCPの接続のもう一方の終端のピアサーバがHTTP/1.1のサーバとわかっていなければ、チャンクされたリクエストを送ることができません。

Second, HTTP/1.1 servers disconnect their persistent connection quite quickly (compared to the time they wait for the first request), so it is not a good idea to post non-idempotent requests (e.g. POST, PUT, etc.) as a succeeding request over persistent connections.

次に、HTTP/1.1のサーバは永続的な接続を非常に速く切断します(最初のリクエストを待つ時間に比べて)。 そのため、永続的な接続越しに、連続するリクエストとして不変でないリクエスト(例 POST,PUTなど)をポストするのは良くありません。

These facts together makes using chunked requests virtually impossible (unless you _know_ that the server supports HTTP/1.1), and this is why we decided that supporting the feature is NOT of high priority.

これらの要因でチャンクされたリクエストを使うのは事実上不可能です(サーバがHTTP/1.1をサポートしているとわかっていなければ)。 そのため、この機能のサポートは高いプライオリティではありません。

到達したレスポンスの内容をどのように作れますか?

(How do you build the response content as it arrives?)

You can use IO::Callback for this purpose.

そのためにIO::Callbackが使えます。

    my $fh = IO::Callback->new(
        '<',
        sub {
            my $x = shift @data;
            $x ? "-$x" : undef;
        }
    );
    my ( $code, $msg, $headers, $content ) =
      $furl->put( "http://127.0.0.1:$port/", [ 'Content-Length' => $len ], $fh,
      );

gzip/deflate 圧縮されたコミュニケーションを使えますか?

(How do you use gzip/deflate compressed communication?)

Add an Accept-Encoding header to your request. Furl inflates response bodies transparently according to the Content-Encoding response header.

Accept-Encodingヘッダをリクエストに追加してください。FurlレスポンスボディーをContent-Encodingレスポンスヘッダに従って透過的にインフレートします。

mutipart/form-data を使うには?

(How do you use mutipart/form-data?)

You can use multipart/form-data with HTTP::Request::Common.

HTTP::Request::Commonを使って、multipart/form-dataを使えます。

    use HTTP::Request::Common;

    my $furl = Furl->new();
    $req = POST 'http://www.perl.org/survey.cgi',
      Content_Type => 'form-data',
      Content      => [
        name   => 'Hiromu Tokunaga',
        email  => '[email protected]',
        gender => 'F',
        born   => '1978',
        init   => ["$ENV{HOME}/.profile"],
      ];
    $furl->request($req);

Native multipart/form-data support for Furl is available if you can send a patch for me.

パッチを送ることができるなら、Furlでネイティブのmultipart/form-dataサポートは利用可能です。

Kee-Alive をどうやって使うのかとHEADメソッドでは何が起きるのか?

(How do you use Keep-Alive and what happens on the HEAD method?)

Furl supports HTTP/1.1, hence Keep-Alive. However, if you use the HEAD method, the connection is closed immediately.

FurlはHTTP/1.1をサポートします。従って、Keep-Aliveもサポートします。 ですが、HEADメソッドで使っても、接続は即座に切断されます。

RFC 2616 section 9.4 says:

RFC 2616 section 9.4 によると:

    The HEAD method is identical to GET except that the server MUST NOT
    return a message-body in the response.

    HEADメソッドは、サーバがレスポンスにメッセージボディを返さしてはいけないことを
    除いて、GETメソッドと同一です。

Some web applications, however, returns message bodies on the HEAD method, which might confuse Keep-Alive processes, so Furl closes connection in such cases.

ですがWebアプリケーションによっては、HEADメソッドでメッセージボディを 返すこともありますが、Kee-Aliveプロセスを混乱させます。そのためFurl はそのようなケースでは接続を閉じます。

Anyway, the HEAD method is not so useful nowadays. The GET method and If-Modified-Sinse are more suitable to cache HTTP contents.

いずれにせよ、HEADメソッドは、今日では、そんなに有用ではありません。GETメソッドと If-Modified-SinseのほうがHTTPコンテンツをキャッシュするのに合っています。

なぜFurlはタイムアウトエラーを返すまで指定より長くかかるのですか?

(Why does Furl take longer than specified until it returns a timeout error?)

Although Furl itself supports timeout, some underlying modules / functions do not. And the most noticeable one is Socket::inet_aton, the function used for name resolution (a function that converts hostnames to IP addresses). If you need accurate and short timeout for name resolution, the use of Net::DNS::Lite is recommended. The following code snippet describes how to use the module in conjunction with Furl.

Furl自身はタイムアウトをサポートしますが、基礎的なモジュールや関数はサポートしません。もっとも顕著な例としては、Socket::inet_atonです。この関数は名前解決(ホストネームからIPアドレスへの変換)に使われています。 もし名前解決に正確で短かいタイムアウトが必要なら、Net::DNS::Liteをお勧めします。下記のコードスニペットは、Furlでどのように使うかを説明しています。

    use Net::DNS::Lite qw();

    my $furl = Furl->new(
        timeout   => $my_timeout_in_seconds,
        inet_aton => sub { Net::DNS::Lite::inet_aton(@_) },
    );

TODO¶

    - AnyEvent::Furl?
    - ipv6 support
    - better docs for NO_PROXY

オプショナルな機能¶

国際ドメイン名(IDN)¶

この機能は Net::IDN::Encode が必要です。

SSL¶

この機能は IO::Socket::SSL が必要です。

Content-Encoding (deflate, gzip)¶

この機能は Compress::Raw::Zlib が必要です。

開発¶

環境のセットアップ:

    $ git clone http://github.com/tokuhirom/p5-Furl.git
    $ cd p5-Furl

picohttpparser の取得:

    $ git submodule init
    $ git submodule update

    $ perl Makefile.PL
    $ make
    $ sudo make install

貢献するには¶

http://github.com/tokuhirom/p5-Furl/にpull-reqを送ってください。

参照¶

LWP

HTTP specs: http://www.w3.org/Protocols/HTTP/1.0/spec.html http://www.w3.org/Protocols/HTTP/1.1/spec.html

ライセンス¶

Copyright (C) Tokuhiro Matsuno.

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