Mojo::UserAgent

简介

Mojo::UserAgent 是一个全功能的非阻塞 I/O HTTP 和 WebSocket 的用户代理, 支持 IPv6, TLS, SNI, IDNA, Comet (long polling), keep-alive, connection pooling, timeout, cookie, multipart, proxy, gzip 压缩和多种事件循环支持.

如果通过fork产生一个新的进程, 全部的连接相关的信息会被 reset. 所以这个允许多个进程安全的共享Mojo::UserAgent对象。

事件

Mojo::UserAgent 从Mojo::EventEmitter中继承了全部的事件，并支持了start事件。

$ua->on(start => sub {
  my ($ua, $tx) = @_;
  ...
});

当有任何新的事务开始之后，在发起请求之前，会触发一次start事件。这包含在proxy中自动发起的请求和重定向。

$ua->on(start => sub {
  my ($ua, $tx) = @_;
  $tx->req->headers->header('X-Bender' => 'Bite my shiny metal ass!');
});

属性

Mojo::UserAgent实现的属性如下。

ca

my $ca = $ua->ca;
$ua    = $ua->ca('/etc/tls/ca.crt');

用于指定TLS证书授权文件所在的路径，默认是MOJO_CA_FILE环境变量的值，使用这个属性会激活主机名验证。

 # 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环境变量的值。

connect_timeout

my $timeout = $ua->connect_timeout;
$ua         = $ua->connect_timeout(5);

建立连接所需的最长时间，单位为：秒(s)。如果连接在这个时间内还没有建立完成，则当前请求会被取消。默认值是MOJO_CONNECT_TIMEOUT环境变量的值或者是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);

连接在关闭之前被允许处于inactive状态的最长时间。默认为MOJO_INACTIVITY_TIMEOUT 环境变量的值或20。如果设置为0则表示允许连接一直处于inactive状态。

ioloop

my $loop = $ua->ioloop;
$ua = $ua->ioloop(Mojo::IOLoop->new);

用于阻塞I/O操作的事件循环对象。默认是Mojo::IOLoop对象。

key

my $key = $ua->key;
$ua     = $ua->key('/etc/tls/client.crt');

TLS密钥文件的路径，默认为MOJO_KEY_FILE环境变量的默认值。

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连接的最大数量，当keep-alive连接数量超过这个值时，旧的连接将会被关闭。默认值是5；如果将值设置为0，则表示禁止使用keep-alive连接保持。

max_redirects

my $max = $ua->max_redirects;
$ua     = $ua->max_redirects(3);

用户代理在完成一次请求前允许进行重定向的最大次数。超出这个次数就会请求失败。默认值是MOJO_MAX_REDIRECTS环境变量的值或是0。

max_response_size

用户代理允许的response的最大值，默认为Mojo::Message::Response中的max_message_size的值。将值设置为0表示允许无限大的response。

注：如果您尝试使用Mojo::Message中的方法dom或json来解析一个很大的response，会消耗非常大的内在。

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);

建立连接、发送请求和接收响应的最长时间(秒s)，超时而没有完成的请求会被用户代理关闭。默认为MOJO_RESQUEST_TIMEOUT环境变量的值或0。将值设为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);

应用程序服务器，相对路径的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);

事务构建器，默认为Mojo::UserAgent::Transactor对象。

# Change name of user agent
$ua->transactor->name('MyUA 1.0');

方法

Mojo::UserAgent从Mojo::EventEmitter中函数了所有的方法，并实现了以下新方法。

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方法创建一个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'});

执行阻塞的HTTP DELETE请求，并返回Mojo::Transaction::HTTP的对象，除了默认使用了DELETE方法之外和调用Mojo::UserAgent::Transactor中的tx函数使用相同的参数。如果在后面附加了回调函数，则可以执行非阻塞的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'});

执行阻塞的HTTP GET请求，并返回Mojo::Transaction::HTTP的对象，除了默认使用了GET方法之外和调用Mojo::UserAgent::Transactor中的tx函数使用相同的参数。如果在后面附加了回调函数，则可以执行非阻塞的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'});

执行阻塞的HTTP HEAD请求，并返回Mojo::Transaction::HTTP的对象，除了默认使用了HEAD方法之外和调用Mojo::UserAgent::Transactor中的tx函数使用相同的参数。如果在后面附加了回调函数，则可以执行非阻塞的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'});

执行阻塞的HTTP OPTIONS请求，并返回Mojo::Transaction::HTTP的对象，除了默认使用了OPTIONS方法之外和调用Mojo::UserAgent::Transactor中的tx函数使用相同的参数。如果在后面附加了回调函数，则可以执行非阻塞的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'});

执行阻塞的HTTP PATCH请求，并返回Mojo::Transaction::HTTP的对象，除了默认使用了PATCH方法之外和调用Mojo::UserAgent::Transactor中的tx函数使用相同的参数。如果在后面附加了回调函数，则可以执行非阻塞的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'});

执行阻塞的HTTP POST请求，并返回Mojo::Transaction::HTTP的对象，除了默认使用了POST方法之外和调用Mojo::UserAgent::Transactor中的tx函数使用相同的参数。如果在后面附加了回调函数，则可以执行非阻塞的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'});

执行阻塞的HTTP PUT请求，并返回Mojo::Transaction::HTTP的对象，除了默认使用了PUT方法之外和调用Mojo::UserAgent::Transactor中的tx函数使用相同的参数。如果在后面附加了回调函数，则可以执行非阻塞的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对象执行阻塞请求，可以手动或使用build_tx进行准备。如果在调用此函数时的参数的最后有回调函数，就可以执行非阻塞的请求。回调函数接收到的参数是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方法时的参数完全相同。回调函数接收的参数可能是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;

可以通过设置报文头Sec-WebSocket-Extensions参数的值为permessage-deflate来启用压缩，这样可以提高性能；但这样会使得每个连接的内在使用高达300kb。

$ua->websocket('ws://example.com/foo' => {
  'Sec-WebSocket-Extensions' => 'permessage-deflate'
} => sub {...});

调试功能

可以通过设置MOJO_USERAGENT_DEBUG环境变量来开启高度功能，这样就可以从STDERR中获取一些高级的诊断信息。

MOJO_USERAGENT_DEBUG=1