DESCRIPTION

This module is DEPRECATED. Use Web::Transport::BasicClient instead.

The Web::Transport::ConnectionClient 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::ConnectionClient 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::ConnectionClient->new_from_host ($string)

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 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.

$client = Web::Transport::ConnectionClient->new_from_url ($url)

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

The 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.

Example:

  $client = Web::Transport::ConnectionClient->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::ConnectionClient->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 => ..., ...)

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). Options stream, body_stream, and body_length are not supported.

The promise is resolved with a response (Web::Transport::Response object).

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 (message => $string)

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

An optional name/value pair whose name is message can be a character string which should contain the reason of the aborting. This message is only used for the aid of the debugging and is never sent to the remote server.

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

$client->proxy_manager ($pm)

$pm = $client->proxy_manager

Get or set the proxy manager used to establish connections. Initially, a proxy manager which takes standard environment variables into account (i.e. Web::Transport::ENVProxyManager) is set as the proxy manager.

This option must be set before the first invocation of the request method.

$client->resolver ($resolver)

$resolver = $client->resolver

Get or set the name resolver used to establish connections. Initially, a resolver using system's name resolution API (Web::Transport::PlatformResolver) wrapped by DNS caching (Web::Transport::CachedResolver) is set as the resolver.

This option must be set before the first invocation of the request method.

$client->protocol_clock ($clock)

$clock = $client->protocol_clock

Get or set the clock object used for various protocol-level date-time operations (e.g. obtaining timestamps used in authentications). Initially, a clock of Web::DateTime::Clock->realtime_clock is set.

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

This option must be set before the first invocation of the request method.

$client->tls_options ({...})

$hashref = $client->tls_options

XXX

This option must be set before the first invocation of the request method.

$client->max_size ($integer)

$integer = $client->max_size

Get or set the maximum size of the (uncompressed) body of the response, in bytes. The initial value 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.

This option must be set before the first invocation of the request method.

$client->debug ($mode)

$mode = $client->debug

Get or set the debug mode. The initial value is the WEBUA_DEBUG environment variable's value. See WEBUA_DEBUG section in Web::Transport for available mode values.

$client->last_resort_timeout ($seconds)

$seconds = $client->last_resort_timeout

Get or set the last-resort timeout value, in seconds. In most applications, this value does not have to be changed. 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.

This option must be set before the first invocation of the request method.

$origin = $client->origin

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

ENVIRONMENT VARIABLES

This module supports WEBUA_DEBUG. See Web::Transport.

When the default resolver is used, proxy environment variables http_proxy, https_proxy, ftp_proxy, and no_proxy are taken into account. See Web::Transport::ENVProxyManager.

SPECIFICATION

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

AUTHOR

Wakaba <wakaba@suikawiki.org>.

LICENSE

Copyright 2016-2017 Wakaba <wakaba@suikawiki.org>.

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