No description or website provided.
Perl Makefile
Latest commit 6a20525 Jan 14, 2017 gaa auto

README.pod

NAME

Web::Transport - Transport layer protocols for the Web

DESCRIPTION

These modules contain implementations of various protocols forming the Web platform's transport layer.

Following protocols are supported by these modules and underlying platform (partially or fully; see documentation of relevant modules): TCP (for IPv4 and IPv6), UNIX domain sockets, TLS (including SNI, OCSP stapling), HTTP (including Cookies, application/x-www-form-urlencoded, multipart/form-data, Basic authentication, OAuth 1.0, OAuth 2.0 Bearer, CONNECT), SOCKS4, SOCKS5, DNS.

MODULES

There are following modules that expose public APIs:

Web::Transport::ConnectionClient

A connection-oriented HTTP client.

Web::Transport::WSClient

A WebSocket client.

Web::Transport::PSGIServerConnection

A PSGI interface of HTTP server.

Web::Transport::PlatformResolver

A name resolver using system's resolver.

Web::Transport::CachedResolver

A DNS cache.

Web::Transport::ENVProxyManager

An environment variable based proxy manager.

Web::MIME::Type

MIME types.

REQUEST OPTIONS

For the request method of Web::Transport::ConnectionClient objects and the new class method of Web::Transport::WSClient, following key/value pairs can be used to specify the parameters of the request to send:

url => $url

Specify the request URL. If specified, the value must be a Web::URL object.

The scheme of the URL must be one of http, https, or ftp for Web::Transport::ConnectionClient, or ws or wss for Web::Transport::WSClient.

Any username, password, or fragment of the URL is ignored.

Either url or path option must be specified.

path => [$seg1, $seg2, ...]

Specify the path segments of the request URL. If specified, the value must be an array reference of zero or more character strings. They are encoded in UTF-8 and then concatenated with /.

If a "prefix" is defined by the context, the path segments given by this option is appended to the prefix.

When the url option is specified, this option is ignored.

This option is not available for Web::Transport::WSClient.

method => $string

Specify the HTTP request method. Note that HTTP request methods are case-sensitive. If not specified, GET is used.

This option is not available for Web::Transport::WSClient.

headers => {$string => $string, ...}

Specify HTTP headers. The value must be a hash reference, whose keys are header names and values are corresponding header values. If a value is an array reference, the array's items are used as the header values (i.e. multiple headers with same name are generated). Header names are case-insensitive.

cookies => {$string => $string, ...}

Specify cookies, to be included in the Cookie: header. The value must be a hash reference of zero or more key/value pairs, where keys are cookie names and values are corresponding cookie values. Any key whose value is undef is ignored.

Names and values must be strings of zero or more characters. They are encoded in UTF-8 and percent-encoded before included in the header value. If this behavior is inappropriate, use headers option instead.

This option also adds Cache-Control: no-store and Pragma: no-store headers.

params => {$string => $string, ...}

Parameters to be included in the request.

The value must be a hash reference of zero or more key/value pairs, where keys are parameter names and values are corresponding parameter values.

Parameter names and values must be strings of zero or more characters. Parameter values can be either a string or an array reference of zero or more strings, representing parameter values sharing same parameter name. Any parameter whose value is undef is ignored.

They are encoded in the application/x-www-form-urlencoded format (or multipart/form-data, if files option is also specified) in UTF-8. If the method is POST and there is no conflicting options, they are put into the request body. Otherwise, they are appended to the request URL.

files => {$string => $file, ...}

Files to be included in the request.

The value must be a hash reference of zero or more key/value pairs, where keys are parameter names and values are corresponding files.

Parameter names must be strings of zero or more characters.

Files can be either a hash reference or an array reference of zero or more hash references, representing files sharing same parameter name. Any pair whose value is undef is ignored.

A file hash reference must contain a body_ref key, whose value must be a reference to a scalar containing zero or more bytes, i.e. the file content.

A file hash reference can also contain mime_type key, whose value is a MIME type string (Content-Type: header value) and mime_filename key, whose value is a file name string (Content-Disposition: header's filename parameter value). Their defaults, used when the key is omitted or the value is undef, are application/octet-stream and the empty string, respectively.

They are encoded in the multipart/form-data format in UTF-8.

This option is not available for Web::Transport::WSClient.

basic_auth => [$userid, $password]

Specifies the credentials of the Basic authentication. The value must be an array reference of two strings, which are used as user ID and password.

bearer => $string

Specifies the credentials of the Bearer authentication.

oauth1 => [$string, $string, $string, $string]

If a non-undef value is specified, the request is to be signed using OAuth 1.0 HMAC-SHA1 signature method.

The value must be an array reference of strings, which are consumer key, consumer secret, access token, and access token secret. They must be specified even though they can be empty strings.

This option also adds Cache-Control: no-store and Pragma: no-store headers.

oauth1_container => 'authorization' | 'query' | 'body'

Where to add OAuth 1.0 request parameters. This option is ignored unless the oauth1 option is also specified.

The value authorization designates the HTTP Authorization: header.

The value query designates the URL query component.

The value body designates the request body.

If this option is not specified, or undef is specified, parameters are added to the HTTP Authorization: header, unless there is another Authorization: header, in which case they are added to the same slot as params.

oauth_verifier => $string

The OAuth 1.0 oauth_verifier request parameter value. If a non-undef value is specified and the oauth1 option is also specified, this value is taken into account as a request parameter. Otherwise this option is ignored.

This option is not available for Web::Transport::WSClient.

oauth_callback => $string

The OAuth 1.0 oauth_callback request parameter value. If a non-undef value is specified and the oauth1 option is also specified, this value is taken into account as a request parameter. Otherwise this option is ignored.

This option is not available for Web::Transport::WSClient.

superreload => $boolean

If true, Cache-Control: no-cache and Pragma: no-store headers are added.

body => $bytes

The request body. If a non-undef value is specified, it must be a string of zero or more bytes.

This option is not available for Web::Transport::WSClient.

Relevant specifications

Fetch Standard <https://fetch.spec.whatwg.org/>.

URL Standard <https://url.spec.whatwg.org/>.

Encoding Standard <https://encoding.spec.whatwg.org/>.

When a text is encoded in UTF-8, the UTF-8 encode steps of the Encoding Standard MUST be used.

RFC 6265, HTTP State Management Mechanism <https://tools.ietf.org/html/rfc6265>.

RFC 5849, The OAuth 1.0 Protocol <https://tools.ietf.org/html/rfc5849>.

HTML Standard <https://html.spec.whatwg.org/>.

PROXY MANAGERS

XXX

There is following proxy manager in this repository: Web::Transport::ENVProxyManager.

PROXY CONFIGURATIONS

XXX

debug => $mode

Specify the debug mode. The default value is the WEBUA_DEBUG environment variable's value. See WEBUA_DEBUG section for available mode values.

This option is only applicable to http and https protocols.

RESOLVERS

XXX

There are following resolvers in this repository: Web::Transport::PlatformResolver, Web::Transport::CachedResolver.

ENVIRONMENT VARIABLE

The WEBUA_DEBUG and WEBSERVER_DEBUG environment variables can be used to enable the debug mode of client and server modules, respectively. If a true value is specified, debug output, such as some of network input and output, are printed to the standard error output. If its value is greater than 1, more verbose messages are printed.

DEPENDENCY

These module requires Perl 5.10 or later. They require several core modules such as Digest::SHA.

They require AnyEvent and Net::SSLeay. The Net::SSLeay module requires OpenSSL or equivalent (e.g. LibreSSL). For Web compatibility and security, OpenSSL version must be latest enough.

They also require following modules (which are submodules of this Git repository):

Promise <https://github.com/wakaba/perl-promise>
modules from perl-web-url repository <https://github.com/manakai/perl-web-url>, e.g. Web::URL Web::Host, and Web::Origin
modules from perl-web-encodings package <https://github.com/manakai/perl-web-encodings>, e.g. Web::Encoding
modules from perl-web-datetime package <https://github.com/manakai/perl-web-datetime>, e.g. Web::DateTime::Parser

AUTHOR

Wakaba <wakaba@suikawiki.org>.

ACKNOWLEDGEMENTS

Some of modules derived from various earlier effort on these areas. See documentations of modules and comments in source codes for more information.

LICENSE

Copyright 2009-2013 Hatena <https://www.hatena.ne.jp/>.

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

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