`Web::Transport::BasicClient`

A basic HTTP client

SYNOPSIS

  use Web::Transport::BasicClient;
  $client = Web::Transport::BasicClient->new_from_host (q<server.test>);
  
  ## First request
  $client->request (
    url => Web::URL->parse_url (q<https://server.test/p1>), ...
  )->then (sub {
    my $res = $_[0];
    warn $res->body_bytes;
    
    ## Second request
    return $client->request (
      url => Web::URL->parse_url (q<https://server.test/p2>), ...
    );
  })->then (sub {
    return $client->close;
  });

DESCRIPTION

The Web::Transport::BasicClient module is a connection-oriented HTTP client. It represents an HTTP connection between this client and an HTTP server and provides API to send requests and receive responses.

It establishes an HTTP connection to the server when a request is sent. The connection is persisted until it is requested to close the connection by the application (via e.g. the close method) or the server has closed the connection, such that subsequent requests can reuse the connection. When a new request is asked to be sent nevertheless the connection has been closed by the server, another connection is established. In this way a Web::Transport::BasicClient object can be used until it is explicitly closed by close or abort.

It can only be used to send requests to a specific origin. It does not support HTTP redirects by design.

METHODS

There are following methods:

$client = Web::Transport::BasicClient->new_from_host ($string[, $opts])

Create a new client object, which is associated with a origin (https, $string, undef). That is, a client for the specified host using HTTPS with port 443 is created.

The first argument must be a string, which is either a domain, an IPv4 address, or an IPv6 address enclosed by [ and ]. They don't have to be in their canonicalized form. IDNs are also allowed.

The second argument, if any, must be a client options (see "CLIENT OPTIONS").

$client = Web::Transport::BasicClient->new_from_url ($url[, $opts])

Create a new client object, which is associated with a URL's origin and path.

The first argument must be a URL record object (Web::URL). It's origin must be a tuple origin (typically an http: or https: URL).

The path of the URL is used as the "prefix" of the URL path used for the requests (See "REQUEST OPTIONS" in Web::Transport' path).

Note that anything other than the origin and path of the URL is ignored.

The second argument, if any, must be a client options (see "CLIENT OPTIONS").

Example:

  $client = Web::Transport::BasicClient->new_from_url
      (Web::URL->parse_url (q<https://server.test>));
  $client->request (path => []); # https://server.test/
  $client->request (path => ['a', 'b']); # https://server.test/a/b
  $client->request (url => Web::URL->parse_string (q<https://server.test/x>));

Example:

  $client = Web::Transport::BasicClient->new_from_url
      (Web::URL->parse_url (q<https://server.test/z>));
  $client->request (path => []); # https://server.test/z/
  $client->request (path => ['a', 'b']); # https://server.test/z/a/b
  $client->request (url => Web::URL->parse_string (q<https://server.test/x>));

$promise = $client->request (url => ..., ..., stream => $boolean)

Send a request and return a promise (Promise), which is to be resolved with the result.

The arguments are name/value pairs, as described in "REQUEST OPTIONS" in Web::Transport. At minimum, the url argument must be specified. It is a URL record object (Web::URL). It must have same origin as the client's origin (i.e. the origin of the argument to the new_from_url method).

The promise is resolved with a response (Web::Transport::Response object). If the request has failed (i.e. a network error; which is different from an error response), the promise is rejected with a response representing a network error. Otherwise, if the stream option is set to a true value, the promise is fulfilled with a response with a body stream. Otherwise, it is fulfilled with a response with a body bytes.

This method creates an HTTP connection, if there is no existing connection, or the existing connection has terminated for some reason. Otherwise the existing connection is used to send the new request. If the connection is in use, the new request is delayed until any current and enqueued request has been processed unless HTTP/2 is available.

$promise = $client->close

Close any existing connection. This method must be explicitly invoked whenever the client has sent some request.

If the connection is in use, it is closed only after any current and enqueued request are processed.

This method returns a promise, which is resolved once any connection has been closed.

$promise = $client->abort ($reason)

Close any existing connection, aborting any currently processing or queued requests and responses. The client object is neuted.

A Perl value can be specified as an optional argument, which represents the reason of the aborting. This is only used for the aid of the debugging and is never sent to the remote server.

This method returns a promise, which is fulfilled once the connection has been closed.

$origin = $client->origin

Return the origin (Web::Origin) of the connection.

CLIENT OPTIONS

A client options is a hash reference with zero or more key/value pairs:

proxy_manager => $proxy_manager

The proxy manager used to establish connections (see "PROXY MANAGERS" in Web::Transport). If not defined, a proxy manager which takes standard environment variables (i.e. http_proxy, https_proxy, ftp_proxy, and no_proxy) into account (i.e. Web::Transport::ENVProxyManager) is used.

resolver => $resolver

The name resolver used to establish connections (see "RESOLVERS" in Web::Transport). If not defined, a resolver using platform's name resolution API (Web::Transport::PlatformResolver) wrapped by in-memory DNS cache (Web::Transport::CachedResolver) is used.

server_connection => {url => $http_url_record}

The URL of the server connection. If a non-undef value is specified, it must be a hash reference whose url is a URL record (Web::URL) whose scheme is http. If specified, the URL is used to establish a connection instead of the request URL.

  For example, if the request URL is <http://website.test/>, the
  client would try to connect to the TCP server at website.test port
  80, with the Host: header set to the value |website.test|.  However,
  given the server connection URL <http://backend.test/> is also
  specified, the client would try to connect to the TCP server at
  backend.test host 80, still setting the Host: header value
  |website.test|.  This feature can be used to implement a reverse
  proxy.

protocol_clock => $clock

The clock object used for various protocol-level date-time operations (e.g. obtaining timestamps used in authentications). If not defined, a clock of Web::DateTime::Clock->realtime_clock is used.

Please note that this clock cannot alter the value used by OpenSSL.

tls_options => {...}

XXX

max_size => $integer

The maximum size of the (uncompressed) body of the response, in bytes. If not defined, the maximum is -1, i.e. no limit is set.

If a non-negative number is specified and the response body is greater than the value, the connection is aborted as soon as possible after receiving the specified number of bytes.

debug => $mode

The debug mode. If not defined, the WEBUA_DEBUG environment variable's value is used. See WEBUA_DEBUG section in "ENVIRONMENT VARIABLES" in Web::Transport for available mode values.

parent_id => $string

A short string that identifies the "parent" context in which the client appears, which will be used in debug outputs.

last_resort_timeout => $seconds

The last-resort timeout value, in seconds. Most applications do not have to set this value. It is used to avoid the application blocked by a server which returns infinite response body. If your application has specific realtimeness requirement, use your own timer to abort the request, rather than reusing this timer. If the value is negative, no timer is enabled. If not defined, a value large enough for most normal requests is used.

These options are also used by Web::Transport::ProxyServerConnection's clients.

ENVIRONMENT VARIABLES

See the resolver and debug options in the "CLIENT OPTIONS" section.

SPECIFICATION

Web Transport Processing <https://wiki.suikawiki.org/n/Web%20Transport%20Processing>.

AUTHOR

Wakaba <wakaba@suikawiki.org>.

LICENSE

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

The manakai project

Web::Transport::BasicClient