Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
 
 
 
 
 
 
 
 
 
 
 
 
src
 
 
t
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.pod

=head1 NAME Web::Transport - Transport layer protocols for the Web =head1 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, C, C, Basic authentication, OAuth 1.0, OAuth 2.0 Bearer, C), SOCKS4, SOCKS5, DNS, MIME types, MIME sniffing. =head1 MODULES There are following modules that expose public APIs: =over 4 =item L A basic HTTP client. =item L A WebSocket client. =item L A PSGI interface of HTTP server. =item L A HTTP proxy server. =item L A name resolver using system's resolver. =item L A DNS cache. =item L An environment variable based proxy manager. =item L MIME type parser. =item L MIME type sniffing. =item L AWS API signature calculation. =item L A Base64 API. =item L A C URL processor. =item L Find TCP ports for testing. =back The module L is deprecated. =head1 REQUEST OPTIONS For the C method of a L object, following key/value pairs can be used to specify the parameters of the request to send: =over 4 =item url => $url Specify the request URL. If specified, the value must be a L object. The scheme of the URL must be one of C, C, C, C, or C. Any username, password, or fragment of the URL is ignored. Either C or C option must be specified. =item 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 C. If a "prefix" is defined by the context, the path segments given by this option is appended to the prefix. When the C option is specified, this option is ignored. =item method => $string Specify the HTTP request method. Note that HTTP request methods are case-sensitive. If not specified, C is used. =item headers => {$name => $value, ...} =item headers => [[$name => $value], ...] Specify HTTP headers. The value must be a headers value (see L). =item cookies => {$string => $string, ...} Specify cookies, to be included in the C 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 C 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 C option instead. This option also adds C and C headers. =item 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 C is ignored. They are encoded in the C format (or C, if C option is also specified) in UTF-8. If the C is C and there is no conflicting options, they are put into the request body. Otherwise, they are appended to the request URL. =item 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 C is ignored. A file hash reference must contain a C 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 C key, whose value is a MIME type string (C header value) and C key, whose value is a file name string (C header's C parameter value). Their defaults, used when the key is omitted or the value is C, are C and the empty string, respectively. They are encoded in the C format in UTF-8. =item basic_auth => [$userid, $password] Specifies the credentials of the C authentication. The value must be an array reference of two strings, which are used as user ID and password. =item bearer => $string Specifies the credentials of the C authentication. =item oauth1 => [$string, $string, $string, $string] If a non-C value is specified, the request is to be signed using OAuth 1.0 C 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 C and C headers. =item oauth1_container => 'authorization' | 'query' | 'body' Where to add OAuth 1.0 request parameters. This option is ignored unless the C option is also specified. The value C designates the HTTP C header. The value C designates the URL query component. The value C designates the request body. If this option is not specified, or C is specified, parameters are added to the HTTP C header, unless there is another C header, in which case they are added to the same slot as C. =item oauth_verifier => $string The OAuth 1.0 C request parameter value. If a non-C value is specified and the C option is also specified, this value is taken into account as a request parameter. Otherwise this option is ignored. =item oauth_callback => $string The OAuth 1.0 C request parameter value. If a non-C value is specified and the C option is also specified, this value is taken into account as a request parameter. Otherwise this option is ignored. =item aws4 => [$access_key_id, $secret_access_key, $region, $service] If specified, signature of the request is attached using AWS Signature Version 4 and the L header. The value must be an array reference of four values. The zeroth item must be the access key ID. The first item must be the secret access key. The second item must be the AWS region, such as C. The third item must be the AWS service, such as C. =item aws4_signed_headers => {$name1 => 1, $name2 => 1, ...} Specifies additionally signed headers. This option is ignored unless C option is also specified. If specified, the value must be a hash reference, whose keys are header names (ASCII case-insensitive) and values are true values. =item ws_protocols => [$name1, $name2, ...] Specifies WebSocket protocol names. The value must be an array reference of zero or more byte strings. Only applicable to WebSocket requests. To establish a WebSocket connection with WebSocket protocol names as a WebSocket client, this option must be used (rather than directly specifying the C header value) as the protocol names are directly handled by the client module as part of the protocol handshake. =item superreload => $boolean If true, C and C headers are added. =item body => $bytes The request body. If a non-C value is specified, it must be a string of zero or more bytes. This option is not allowed when C is specified. =item body_stream => $readable_stream The request body. If a non-C value is specified, it must be a L with type C (i.e. a readable byte stream) which is not locked. If this option has non-C value, the C option must also be specified. This option is not allowed when C is specified. =item length => $byte_length The byte length of the request body. If a non-C value is specified, it must be equal to the number of bytes contained by the C readable byte stream. If this option has non-C value, the C option must also be specified. This option is not allowed when C is specified. =item stream => $boolean Whether the result of the operation should contain a L object (true) or a byte string (false) for the response body. See L for more information. =item forwarding => $boolean (for proxy) Whether this client is a component of a proxy, forwarding a request to the upstream. This option is only applicable to the C hash reference of the argument (or return value) to the C callback of L. =back Different subsets of these options are also supported by relevant methods of deprecated modules L and L. =head2 Relevant specifications Fetch Standard . URL Standard . Encoding Standard . 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 . RFC 5849, The OAuth 1.0 Protocol . HTML Standard . Signature Calculations for the Authorization Header: Transferring Payload in a Single Chunk (AWS Signature Version 4) - Amazon Simple Storage Service . =head1 HEADERS A B is either a headers hash reference or a headers array reference. A B is a reference to a hash whose keys are header names and its values are corresponding header values. If a value is an array reference, that array's items are used as the header values (i.e. multiple headers with same name are generated). A B is a reference to an array which contain zero or more array references which contains header name (index 0) and header value (index 1). A B is a headers array reference whose items contain third item (index 2), which is the ASCII lowercased variant of the header name. Header names and values must be byte strings. Header names and values cannot contain 0x0D or 0x0A bytes. Header names are case-insensitive. Header names cannot be empty and cannot contain certain bytes (e.g. 0x3A). =head1 PROXY MANAGERS A B is used to retrieve proxy configurations used for fetching. It is an object with the C method. The C method is expected to return the list of the proxies for the specified URL. It has a required argument, which must be a URL record (L), for which a proxy configuration is requested. Additionally, following named argument chould be specified: =over 4 =item signal => $signal The abort signal (L) for the operation. If the abort controller (L) associated with the signal is aborted, the operation is expected to be aborted and the method's promise is rejected with an object whose C is C whenever possible. =back The method is expected to return a promise (L), which is to be resolved with a proxy configuration list (see L), or to be rejected with an error. There are following proxy managers in this repository: L and L. Any other object can be used as well. =head1 PROXY CONFIGURATIONS A B is ... XXX host => ... XXX For a proxy configuration returned by a proxy manager, the value must be a L object. For a proxy configuration used as part of an input to the L's constructor, the value may be a string which is a valid host string. debug => $mode Specify the debug mode. The default value is the C environment variable's value. See C section for available mode values. This option is only applicable to C and C protocols. =head1 RESOLVERS XXX The C method is expected to return a promise. XXX If aborted, or the resolver is unable to resolve (note that this is B from the resolver is ready but the result is "not found"), the promise is expected to be rejected with the exception describing the failure. There are following resolvers in this repository: L, L. =head1 CERTIFICATE MANAGER A B is an object from which TLS certifciates can be retrieved. It is expected to have following methods: =over 4 =item $cm->prepare ($name => $value, ...)->then (sub { ... }) Run preparation steps for the certificate manager. The concrete steps are implementation specific. The method must return a promise, which is fulfilled or rejected when the certificate manager is ready to return relevant certificates. It receives zero or more options as name/value pair arguments. The C option has a boolean value, representing server (true) or client (false). If the C value is true but the certificate manager is not ready to return the server certificates (including CA certificates), the method must reject the promise. =item {$name => $value, ...} = $cm->to_anyevent_tls_args_sync Return a hash reference containing zero or more arguments to the C method of the L class. It should only contain certificate-related options. If the certificate manager's C method has been invoked with C option set to true and its promise has been fulfilled, the hash reference must contain the server certificates and all other relevant options. Otherwise, if the certificate manager's C method has been invoked and its promise has been fulfilled, the hash reference must contain all relevant options. =item {$name => $value, ...} = $cm->to_anyevent_tls_args_for_host_sync ($host) Same as C but returns argument for a host-specific certificate. The method is invoked with an argument of type L, representing the domain name given in the SNI extension's field received from the client. The method can return C if there is no host-specific certificate (such that the default certificate returned by C should be used instead). =back There is following module in this repository: L. =head1 UNDERLYING PLATFORM INFORMATION OBJECT An B represents the underlying platform on which the application is running, used to retrive platform-dependent configurations. It is expected to have following methods: =over 4 =item $string = $info->user_agent Return the default C value. =item $string = $info->accept_language Return the appropriate value for the HTTP C header. =back There is following module in this repository: L. =head1 ENVIRONMENT VARIABLES The C and C 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 C<1>, more verbose messages are printed. =head1 DEPENDENCY These module requires Perl 5.14 or later. They require several core modules such as L and L. They require L and L. The L module requires OpenSSL or equivalent (e.g. LibreSSL). For Web compatibility and security, OpenSSL version must be latest enough. They require following modules (which are submodules of this Git repository): =over 4 =item modules from perl-promise repository , e.g. L and L =item modules from perl-web-url repository , e.g. L, L, and L =item modules from perl-web-encodings package , e.g. L =item modules from perl-web-datetime package , e.g. L =back Additionally, modules L, L, L, L, L, L, L, L, and L require following modules (which are also part of submodule of this Git repository): =over 4 =item modules from perl-streams package , e.g. L and L =back =head1 AUTHOR Wakaba . =head1 ACKNOWLEDGEMENTS Some of modules derived from various earlier effort on these areas. See documentations of modules and comments in source codes for more information. =head1 LICENSE Copyright 2009-2013 Hatena . Copyright 2014-2020 Wakaba . This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The license of the C file is: This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at . =cut
You can’t perform that action at this time.