簡介
Mojo::UserAgent 是一個全功能的非阻塞 I/O HTTP 和 WebSocket 的用戶代理, 支持 IPv6, TLS, SNI, IDNA, Comet (long polling), keep-alive, connection pooling, timeout, cookie, multipart, proxy, gzip 壓縮和多種事件循環(huán)支持.
如果通過fork產(chǎn)生一個新的進程, 全部的連接相關(guān)的信息會被 reset. 所以這個允許多個進程安全的共享Mojo::UserAgent對象。
事件
Mojo::UserAgent 從Mojo::EventEmitter中繼承了全部的事件,并支持了start事件。
$ua->on(start => sub {
my ($ua, $tx) = @_;
...
});
當有任何新的事務(wù)開始之后,在發(fā)起請求之前,會觸發(fā)一次start事件。這包含在proxy中自動發(fā)起的請求和重定向。
$ua->on(start => sub {
my ($ua, $tx) = @_;
$tx->req->headers->header('X-Bender' => 'Bite my shiny metal ass!');
});
屬性
Mojo::UserAgent實現(xiàn)的屬性如下。
ca
my $ca = $ua->ca;
$ua = $ua->ca('/etc/tls/ca.crt');
用于指定TLS證書授權(quán)文件所在的路徑,默認是MOJO_CA_FILE環(huán)境變量的值,使用這個屬性會激活主機名驗證。
# Show certificate authorities for debugging
IO::Socket::SSL::set_defaults( SSL_verify_callback => sub { say "Authority: $_[2]" and return $_[0] });
cert
my $cert = $ua->cert;
$ua = $ua->cert('/etc/tls/client.crt');
指定TLS證書文件所在路徑,默認是MOJO_CERT_FILE環(huán)境變量的值。
connect_timeout
my $timeout = $ua->connect_timeout;
$ua = $ua->connect_timeout(5);
建立連接所需的最長時間,單位為:秒(s)。如果連接在這個時間內(nèi)還沒有建立完成,則當前請求會被取消。默認值是MOJO_CONNECT_TIMEOUT環(huán)境變量的值或者是10。
cookie_jar
my $cookie_jar = $ua->cookie_jar;
$ua = $ua->cookie_jar(Mojo::UserAgent::CookieJar->new);
對用戶代理(Mojo::UserAgent對象)的請求進行Cookie管理的類,默認是Mojo::UserAgent::CookieJar對象。
# Ignore all cookies
$ua->cookie_jar->ignore(sub { 1 });
# Ignore cookies for public suffixes
my $ps = IO::Socket::SSL::PublicSuffix->default;
$ua->cookie_jar->ignore(sub {
my $cookie = shift;
return undef unless my $domain = $cookie->domain;
return ($ps->public_suffix($domain))[0] eq '';
});
# Add custom cookie to the jar
$ua->cookie_jar->add(
Mojo::Cookie::Response->new(
name => 'foo',
value => 'bar',
domain => 'mojolicious.org',
path => '/perldoc'
)
);
inactivity_timeout
my $timeout = $ua->inactivity_timeout;
$ua = $ua->inactivity_timeout(15);
連接在關(guān)閉之前被允許處于inactive狀態(tài)的最長時間。默認為MOJO_INACTIVITY_TIMEOUT 環(huán)境變量的值或20。如果設(shè)置為0則表示允許連接一直處于inactive狀態(tài)。
ioloop
my $loop = $ua->ioloop;
$ua = $ua->ioloop(Mojo::IOLoop->new);
用于阻塞I/O操作的事件循環(huán)對象。默認是Mojo::IOLoop對象。
key
my $key = $ua->key;
$ua = $ua->key('/etc/tls/client.crt');
TLS密鑰文件的路徑,默認為MOJO_KEY_FILE環(huán)境變量的默認值。
local_address
my $address = $ua->local_address;
$ua = $ua->local_address('127.0.0.1');
要綁定的本地地址。
max_connections
my $max = $ua->max_connections;
$ua = $ua->max_connections(5);
允許存在的keep-alive連接的最大數(shù)量,當keep-alive連接數(shù)量超過這個值時,舊的連接將會被關(guān)閉。默認值是5;如果將值設(shè)置為0,則表示禁止使用keep-alive連接保持。
max_redirects
my $max = $ua->max_redirects;
$ua = $ua->max_redirects(3);
用戶代理在完成一次請求前允許進行重定向的最大次數(shù)。超出這個次數(shù)就會請求失敗。默認值是MOJO_MAX_REDIRECTS環(huán)境變量的值或是0。
max_response_size
用戶代理允許的response的最大值,默認為Mojo::Message::Response中的max_message_size的值。將值設(shè)置為0表示允許無限大的response。
注:如果您嘗試使用Mojo::Message中的方法dom或json來解析一個很大的response,會消耗非常大的內(nèi)在。
proxy
my $proxy = $ua->proxy;
$ua = $ua->proxy(Mojo::UserAgent::Proxy->new);
代理管理器,默認使用Mojo::UserAgent::Proxy對象。
# Detect proxy servers from environment
$ua->proxy->detect;
# Manually configure HTTP proxy (using CONNECT for HTTPS/WebSockets)
$ua->proxy->http('http://127.0.0.1:8080')->https('http://127.0.0.1:8080');
# Manually configure Tor (SOCKS5)
$ua->proxy->http('socks://127.0.0.1:9050')->https('socks://127.0.0.1:9050');
# Manually configure UNIX domain socket (using CONNECT for HTTPS/WebSockets)
$ua->proxy->http('http+unix://%2Ftmp%2Fproxy.sock')->https('http+unix://%2Ftmp%2Fproxy.sock');
request_timeout
my $timeout = $ua->request_timeout;
$ua = $ua->request_timeout(5);
建立連接、發(fā)送請求和接收響應的最長時間(秒s),超時而沒有完成的請求會被用戶代理關(guān)閉。默認為MOJO_RESQUEST_TIMEOUT環(huán)境變量的值或0。將值設(shè)為0表示讓用戶代理一直等待直到。每次重定向都會重值請求時長。
# Total limit of 5 seconds, of which 3 seconds may be spent connecting
$ua->max_redirects(0)->connect_timeout(3)->request_timeout(5);
server
my $server = $ua->server;
$ua = $ua->server(Mojo::UserAgent::Server->new);
應用程序服務(wù)器,相對路徑的URL會被它處理。默認值為Mojo::UserAgent::Server對象。
# Mock web service
$ua->server->app(Mojolicious->new);
$ua->server->app->routes->get('/time' => sub {
my $c = shift;
$c->render(json => {now => time});
});
my $time = $ua->get('/time')->result->json->{now};
# Change log level
$ua->server->app->log->level('fatal');
# Port currently used for processing relative URLs blocking
say $ua->server->url->port;
# Port currently used for processing relative URLs non-blocking
say $ua->server->nb_url->port;
transactor
my $t = $ua->transactor;
$ua = $ua->transactor(Mojo::UserAgent::Transactor->new);
事務(wù)構(gòu)建器,默認為Mojo::UserAgent::Transactor對象。
# Change name of user agent
$ua->transactor->name('MyUA 1.0');
方法
Mojo::UserAgent從Mojo::EventEmitter中函數(shù)了所有的方法,并實現(xiàn)了以下新方法。
build_tx
my $tx = $ua->build_tx(GET => 'example.com');
my $tx = $ua->build_tx(PUT=>'http://example.com'=>{Accept => '*/*'} => 'Content!');
my $tx = $ua->build_tx(PUT => 'http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->build_tx(PUT => 'http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
使用Mojo::UserAgent::Transactor包中的tx方法創(chuàng)建一個Mojo::Transaction::HTTP對象。
# Request with custom cookie
my $tx = $ua->build_tx(GET => 'https://example.com/account');
$tx->req->cookies({name => 'user', value => 'sri'});
$tx = $ua->start($tx);
# Deactivate gzip compression
my $tx = $ua->build_tx(GET => 'example.com');
$tx->req->headers->remove('Accept-Encoding');
$tx = $ua->start($tx);
# Interrupt response by raising an error
my $tx = $ua->build_tx(GET => 'http://example.com');
$tx->res->on(progress => sub {
my $res = shift;
return unless my $server = $res->headers->server;
$res->error({message => 'Oh noes, it is IIS!'}) if $server =~ /IIS/;
});
$tx = $ua->start($tx);
build_websocket_tx
my $tx = $ua->build_websocket_tx('ws://example.com');
my $tx = $ua->build_websocket_tx('ws://example.com' => {DNT => 1} => ['v1.proto']);
使用mojo::UserAgent::Transactor包中的websocket方法生成一個Mojo::Transaction::HTTP對象。
# Custom WebSocket handshake with cookie
my $tx = $ua->build_websocket_tx('wss://example.com/echo');
$tx->req->cookies({name => 'user', value => 'sri'});
$ua->start($tx => sub {
my ($ua, $tx) = @_;
say 'WebSocket handshake failed!' and return unless $tx->is_websocket;
$tx->on(message => sub {
my ($tx, $msg) = @_;
say "WebSocket message: $msg";
$tx->finish;
});
$tx->send('Hi!');
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
delete
my $tx = $ua->delete('example.com');
my $tx = $ua->delete('http://example.com' => {Accept => '*/*'} => 'Content!');
my $tx = $ua->delete('http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->delete('http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
執(zhí)行阻塞的HTTP DELETE請求,并返回Mojo::Transaction::HTTP的對象,除了默認使用了DELETE方法之外和調(diào)用Mojo::UserAgent::Transactor中的tx函數(shù)使用相同的參數(shù)。如果在后面附加了回調(diào)函數(shù),則可以執(zhí)行非阻塞的DELETE請求。
$ua->delete('http://example.com' => json => {a => 'b'} => sub {
my ($ua, $tx) = @_;
say $tx->result->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
get
my $tx = $ua->get('example.com');
my $tx = $ua->get('http://example.com' => {Accept => '*/*'} => 'Content!');
my $tx = $ua->get('http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->get('http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
執(zhí)行阻塞的HTTP GET請求,并返回Mojo::Transaction::HTTP的對象,除了默認使用了GET方法之外和調(diào)用Mojo::UserAgent::Transactor中的tx函數(shù)使用相同的參數(shù)。如果在后面附加了回調(diào)函數(shù),則可以執(zhí)行非阻塞的GET請求。
$ua->get('http://example.com' => json => {a => 'b'} => sub {
my ($ua, $tx) = @_;
say $tx->result->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
head
my $tx = $ua->head('example.com');
my $tx = $ua->head('http://example.com' => {Accept => '*/*'} => 'Content!');
my $tx = $ua->head('http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->head('http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
執(zhí)行阻塞的HTTP HEAD請求,并返回Mojo::Transaction::HTTP的對象,除了默認使用了HEAD方法之外和調(diào)用Mojo::UserAgent::Transactor中的tx函數(shù)使用相同的參數(shù)。如果在后面附加了回調(diào)函數(shù),則可以執(zhí)行非阻塞的HEAD請求。
$ua->head('http://example.com' => json => {a => 'b'} => sub {
my ($ua, $tx) = @_;
say $tx->result->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
options
my $tx = $ua->options('example.com');
my $tx = $ua->options('http://example.com' => {Accept => '*/*'} => 'Content!');
my $tx = $ua->options('http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->options('http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
執(zhí)行阻塞的HTTP OPTIONS請求,并返回Mojo::Transaction::HTTP的對象,除了默認使用了OPTIONS方法之外和調(diào)用Mojo::UserAgent::Transactor中的tx函數(shù)使用相同的參數(shù)。如果在后面附加了回調(diào)函數(shù),則可以執(zhí)行非阻塞的OPTIONS請求。
$ua->options('http://example.com' => json => {a => 'b'} => sub {
my ($ua, $tx) = @_;
say $tx->result->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
patch
my $tx = $ua->patch('example.com');
my $tx = $ua->patch('http://example.com' => {Accept => '*/*'} => 'Content!');
my $tx = $ua->patch('http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->patch('http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
執(zhí)行阻塞的HTTP PATCH請求,并返回Mojo::Transaction::HTTP的對象,除了默認使用了PATCH方法之外和調(diào)用Mojo::UserAgent::Transactor中的tx函數(shù)使用相同的參數(shù)。如果在后面附加了回調(diào)函數(shù),則可以執(zhí)行非阻塞的PATCH請求。
$ua->patch('http://example.com' => json => {a => 'b'} => sub {
my ($ua, $tx) = @_;
say $tx->result->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
post
my $tx = $ua->post('example.com');
my $tx = $ua->post('http://example.com' => {Accept => '*/*'} => 'Content!');
my $tx = $ua->post('http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->post('http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
執(zhí)行阻塞的HTTP POST請求,并返回Mojo::Transaction::HTTP的對象,除了默認使用了POST方法之外和調(diào)用Mojo::UserAgent::Transactor中的tx函數(shù)使用相同的參數(shù)。如果在后面附加了回調(diào)函數(shù),則可以執(zhí)行非阻塞的POST請求。
$ua->post('http://example.com' => json => {a => 'b'} => sub {
my ($ua, $tx) = @_;
say $tx->result->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
put
my $tx = $ua->put('example.com');
my $tx = $ua->put('http://example.com' => {Accept => '*/*'} => 'Content!');
my $tx = $ua->put('http://example.com' => {Accept => '*/*'} => form => {a => 'b'});
my $tx = $ua->put('http://example.com' => {Accept => '*/*'} => json => {a => 'b'});
執(zhí)行阻塞的HTTP PUT請求,并返回Mojo::Transaction::HTTP的對象,除了默認使用了PUT方法之外和調(diào)用Mojo::UserAgent::Transactor中的tx函數(shù)使用相同的參數(shù)。如果在后面附加了回調(diào)函數(shù),則可以執(zhí)行非阻塞的PUT請求。
$ua->put('http://example.com' => json => {a => 'b'} => sub {
my ($ua, $tx) = @_;
say $tx->result->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
start
my $tx = $ua->start(Mojo::Transaction::HTTP->new);
對自定義的Mojo::Transaction::HTTP對象執(zhí)行阻塞請求,可以手動或使用build_tx進行準備。如果在調(diào)用此函數(shù)時的參數(shù)的最后有回調(diào)函數(shù),就可以執(zhí)行非阻塞的請求?;卣{(diào)函數(shù)接收到的參數(shù)是Mojo::UserAgent對象和Mojo::Transaction::HTTP對象。
my $tx = $ua->build_tx(GET => 'http://example.com');
$ua->start($tx => sub {
my ($ua, $tx) = @_;
say $tx->result->body;
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
websocket
$ua->websocket('ws://example.com' => sub {...});
$ua->websocket('ws://example.com' => {DNT => 1} => ['v1.proto'] => sub {...});
使用對用戶透明的握手連接方式打開非阻塞的WebSocket連接。與使用Mojo::UserAgent::Transactor中的websocket方法時的參數(shù)完全相同?;卣{(diào)函數(shù)接收的參數(shù)可能是Mojo::Transaction::Websocket對象也可能是Mojo::Transaction::HTTP對象,這取決于握手連接是否成功。
$ua->websocket('wss://example.com/echo' => ['v1.proto'] => sub {
my ($ua, $tx) = @_;
say 'WebSocket handshake failed!' and return unless $tx->is_websocket;
say 'Subprotocol negotiation failed!' and return unless $tx->protocol;
$tx->on(finish => sub {
my ($tx, $code, $reason) = @_;
say "WebSocket closed with status $code.";
});
$tx->on(message => sub {
my ($tx, $msg) = @_;
say "WebSocket message: $msg";
$tx->finish;
});
$tx->send('Hi!');
});
Mojo::IOLoop->start unless Mojo::IOLoop->is_running;
可以通過設(shè)置報文頭Sec-WebSocket-Extensions參數(shù)的值為permessage-deflate來啟用壓縮,這樣可以提高性能;但這樣會使得每個連接的內(nèi)在使用高達300kb。
$ua->websocket('ws://example.com/foo' => {
'Sec-WebSocket-Extensions' => 'permessage-deflate'
} => sub {...});
調(diào)試功能
可以通過設(shè)置MOJO_USERAGENT_DEBUG環(huán)境變量來開啟高度功能,這樣就可以從STDERR中獲取一些高級的診斷信息。
MOJO_USERAGENT_DEBUG=1