Blame README

Packit 3f4df8
NAME
Packit 3f4df8
    HTTP::Tiny - A small, simple, correct HTTP/1.1 client
Packit 3f4df8
Packit 3f4df8
VERSION
Packit 3f4df8
    version 0.074
Packit 3f4df8
Packit 3f4df8
SYNOPSIS
Packit 3f4df8
        use HTTP::Tiny;
Packit 3f4df8
Packit 3f4df8
        my $response = HTTP::Tiny->new->get('http://example.com/');
Packit 3f4df8
Packit 3f4df8
        die "Failed!\n" unless $response->{success};
Packit 3f4df8
Packit 3f4df8
        print "$response->{status} $response->{reason}\n";
Packit 3f4df8
Packit 3f4df8
        while (my ($k, $v) = each %{$response->{headers}}) {
Packit 3f4df8
            for (ref $v eq 'ARRAY' ? @$v : $v) {
Packit 3f4df8
                print "$k: $_\n";
Packit 3f4df8
            }
Packit 3f4df8
        }
Packit 3f4df8
Packit 3f4df8
        print $response->{content} if length $response->{content};
Packit 3f4df8
Packit 3f4df8
DESCRIPTION
Packit 3f4df8
    This is a very simple HTTP/1.1 client, designed for doing simple
Packit 3f4df8
    requests without the overhead of a large framework like LWP::UserAgent.
Packit 3f4df8
Packit 3f4df8
    It is more correct and more complete than HTTP::Lite. It supports
Packit 3f4df8
    proxies and redirection. It also correctly resumes after EINTR.
Packit 3f4df8
Packit 3f4df8
    If IO::Socket::IP 0.25 or later is installed, HTTP::Tiny will use it
Packit 3f4df8
    instead of IO::Socket::INET for transparent support for both IPv4 and
Packit 3f4df8
    IPv6.
Packit 3f4df8
Packit 3f4df8
    Cookie support requires HTTP::CookieJar or an equivalent class.
Packit 3f4df8
Packit 3f4df8
METHODS
Packit 3f4df8
  new
Packit 3f4df8
        $http = HTTP::Tiny->new( %attributes );
Packit 3f4df8
Packit 3f4df8
    This constructor returns a new HTTP::Tiny object. Valid attributes
Packit 3f4df8
    include:
Packit 3f4df8
Packit 3f4df8
    *   "agent" — A user-agent string (defaults to 'HTTP-Tiny/$VERSION'). If
Packit 3f4df8
        "agent" — ends in a space character, the default user-agent string
Packit 3f4df8
        is appended.
Packit 3f4df8
Packit 3f4df8
    *   "cookie_jar" — An instance of HTTP::CookieJar — or equivalent class
Packit 3f4df8
        that supports the "add" and "cookie_header" methods
Packit 3f4df8
Packit 3f4df8
    *   "default_headers" — A hashref of default headers to apply to
Packit 3f4df8
        requests
Packit 3f4df8
Packit 3f4df8
    *   "local_address" — The local IP address to bind to
Packit 3f4df8
Packit 3f4df8
    *   "keep_alive" — Whether to reuse the last connection (if for the same
Packit 3f4df8
        scheme, host and port) (defaults to 1)
Packit 3f4df8
Packit 3f4df8
    *   "max_redirect" — Maximum number of redirects allowed (defaults to 5)
Packit 3f4df8
Packit 3f4df8
    *   "max_size" — Maximum response size in bytes (only when not using a
Packit 3f4df8
        data callback). If defined, responses larger than this will return
Packit 3f4df8
        an exception.
Packit 3f4df8
Packit 3f4df8
    *   "http_proxy" — URL of a proxy server to use for HTTP connections
Packit 3f4df8
        (default is $ENV{http_proxy} — if set)
Packit 3f4df8
Packit 3f4df8
    *   "https_proxy" — URL of a proxy server to use for HTTPS connections
Packit 3f4df8
        (default is $ENV{https_proxy} — if set)
Packit 3f4df8
Packit 3f4df8
    *   "proxy" — URL of a generic proxy server for both HTTP and HTTPS
Packit 3f4df8
        connections (default is $ENV{all_proxy} — if set)
Packit 3f4df8
Packit 3f4df8
    *   "no_proxy" — List of domain suffixes that should not be proxied.
Packit 3f4df8
        Must be a comma-separated string or an array reference. (default is
Packit 3f4df8
        $ENV{no_proxy} —)
Packit 3f4df8
Packit 3f4df8
    *   "timeout" — Request timeout in seconds (default is 60) If a socket
Packit 3f4df8
        open, read or write takes longer than the timeout, an exception is
Packit 3f4df8
        thrown.
Packit 3f4df8
Packit 3f4df8
    *   "verify_SSL" — A boolean that indicates whether to validate the SSL
Packit 3f4df8
        certificate of an "https" — connection (default is false)
Packit 3f4df8
Packit 3f4df8
    *   "SSL_options" — A hashref of "SSL_*" — options to pass through to
Packit 3f4df8
        IO::Socket::SSL
Packit 3f4df8
Packit 3f4df8
    Passing an explicit "undef" for "proxy", "http_proxy" or "https_proxy"
Packit 3f4df8
    will prevent getting the corresponding proxies from the environment.
Packit 3f4df8
Packit 3f4df8
    Exceptions from "max_size", "timeout" or other errors will result in a
Packit 3f4df8
    pseudo-HTTP status code of 599 and a reason of "Internal Exception". The
Packit 3f4df8
    content field in the response will contain the text of the exception.
Packit 3f4df8
Packit 3f4df8
    The "keep_alive" parameter enables a persistent connection, but only to
Packit 3f4df8
    a single destination scheme, host and port. Also, if any
Packit 3f4df8
    connection-relevant attributes are modified, or if the process ID or
Packit 3f4df8
    thread ID change, the persistent connection will be dropped. If you want
Packit 3f4df8
    persistent connections across multiple destinations, use multiple
Packit 3f4df8
    HTTP::Tiny objects.
Packit 3f4df8
Packit 3f4df8
    See "SSL SUPPORT" for more on the "verify_SSL" and "SSL_options"
Packit 3f4df8
    attributes.
Packit 3f4df8
Packit 3f4df8
  get|head|put|post|delete
Packit 3f4df8
        $response = $http->get($url);
Packit 3f4df8
        $response = $http->get($url, \%options);
Packit 3f4df8
        $response = $http->head($url);
Packit 3f4df8
Packit 3f4df8
    These methods are shorthand for calling "request()" for the given
Packit 3f4df8
    method. The URL must have unsafe characters escaped and international
Packit 3f4df8
    domain names encoded. See "request()" for valid options and a
Packit 3f4df8
    description of the response.
Packit 3f4df8
Packit 3f4df8
    The "success" field of the response will be true if the status code is
Packit 3f4df8
    2XX.
Packit 3f4df8
Packit 3f4df8
  post_form
Packit 3f4df8
        $response = $http->post_form($url, $form_data);
Packit 3f4df8
        $response = $http->post_form($url, $form_data, \%options);
Packit 3f4df8
Packit 3f4df8
    This method executes a "POST" request and sends the key/value pairs from
Packit 3f4df8
    a form data hash or array reference to the given URL with a
Packit 3f4df8
    "content-type" of "application/x-www-form-urlencoded". If data is
Packit 3f4df8
    provided as an array reference, the order is preserved; if provided as a
Packit 3f4df8
    hash reference, the terms are sorted on key and value for consistency.
Packit 3f4df8
    See documentation for the "www_form_urlencode" method for details on the
Packit 3f4df8
    encoding.
Packit 3f4df8
Packit 3f4df8
    The URL must have unsafe characters escaped and international domain
Packit 3f4df8
    names encoded. See "request()" for valid options and a description of
Packit 3f4df8
    the response. Any "content-type" header or content in the options
Packit 3f4df8
    hashref will be ignored.
Packit 3f4df8
Packit 3f4df8
    The "success" field of the response will be true if the status code is
Packit 3f4df8
    2XX.
Packit 3f4df8
Packit 3f4df8
  mirror
Packit 3f4df8
        $response = $http->mirror($url, $file, \%options)
Packit 3f4df8
        if ( $response->{success} ) {
Packit 3f4df8
            print "$file is up to date\n";
Packit 3f4df8
        }
Packit 3f4df8
Packit 3f4df8
    Executes a "GET" request for the URL and saves the response body to the
Packit 3f4df8
    file name provided. The URL must have unsafe characters escaped and
Packit 3f4df8
    international domain names encoded. If the file already exists, the
Packit 3f4df8
    request will include an "If-Modified-Since" header with the modification
Packit 3f4df8
    timestamp of the file. You may specify a different "If-Modified-Since"
Packit 3f4df8
    header yourself in the "$options->{headers}" hash.
Packit 3f4df8
Packit 3f4df8
    The "success" field of the response will be true if the status code is
Packit 3f4df8
    2XX or if the status code is 304 (unmodified).
Packit 3f4df8
Packit 3f4df8
    If the file was modified and the server response includes a properly
Packit 3f4df8
    formatted "Last-Modified" header, the file modification time will be
Packit 3f4df8
    updated accordingly.
Packit 3f4df8
Packit 3f4df8
  request
Packit 3f4df8
        $response = $http->request($method, $url);
Packit 3f4df8
        $response = $http->request($method, $url, \%options);
Packit 3f4df8
Packit 3f4df8
    Executes an HTTP request of the given method type ('GET', 'HEAD',
Packit 3f4df8
    'POST', 'PUT', etc.) on the given URL. The URL must have unsafe
Packit 3f4df8
    characters escaped and international domain names encoded.
Packit 3f4df8
Packit 3f4df8
    NOTE: Method names are case-sensitive per the HTTP/1.1 specification.
Packit 3f4df8
    Don't use "get" when you really want "GET". See LIMITATIONS for how this
Packit 3f4df8
    applies to redirection.
Packit 3f4df8
Packit 3f4df8
    If the URL includes a "user:password" stanza, they will be used for
Packit 3f4df8
    Basic-style authorization headers. (Authorization headers will not be
Packit 3f4df8
    included in a redirected request.) For example:
Packit 3f4df8
Packit 3f4df8
        $http->request('GET', 'http://Aladdin:open sesame@example.com/');
Packit 3f4df8
Packit 3f4df8
    If the "user:password" stanza contains reserved characters, they must be
Packit 3f4df8
    percent-escaped:
Packit 3f4df8
Packit 3f4df8
        $http->request('GET', 'http://john%40example.com:password@example.com/');
Packit 3f4df8
Packit 3f4df8
    A hashref of options may be appended to modify the request.
Packit 3f4df8
Packit 3f4df8
    Valid options are:
Packit 3f4df8
Packit 3f4df8
    *   "headers" — A hashref containing headers to include with the
Packit 3f4df8
        request. If the value for a header is an array reference, the header
Packit 3f4df8
        will be output multiple times with each value in the array. These
Packit 3f4df8
        headers over-write any default headers.
Packit 3f4df8
Packit 3f4df8
    *   "content" — A scalar to include as the body of the request OR a code
Packit 3f4df8
        reference that will be called iteratively to produce the body of the
Packit 3f4df8
        request
Packit 3f4df8
Packit 3f4df8
    *   "trailer_callback" — A code reference that will be called if it
Packit 3f4df8
        exists to provide a hashref of trailing headers (only used with
Packit 3f4df8
        chunked transfer-encoding)
Packit 3f4df8
Packit 3f4df8
    *   "data_callback" — A code reference that will be called for each
Packit 3f4df8
        chunks of the response body received.
Packit 3f4df8
Packit 3f4df8
    *   "peer" — Override host resolution and force all connections to go
Packit 3f4df8
        only to a specific peer address, regardless of the URL of the
Packit 3f4df8
        request. This will include any redirections! This options should be
Packit 3f4df8
        used with extreme caution (e.g. debugging or very special
Packit 3f4df8
        circumstances).
Packit 3f4df8
Packit 3f4df8
    The "Host" header is generated from the URL in accordance with RFC 2616.
Packit 3f4df8
    It is a fatal error to specify "Host" in the "headers" option. Other
Packit 3f4df8
    headers may be ignored or overwritten if necessary for transport
Packit 3f4df8
    compliance.
Packit 3f4df8
Packit 3f4df8
    If the "content" option is a code reference, it will be called
Packit 3f4df8
    iteratively to provide the content body of the request. It should return
Packit 3f4df8
    the empty string or undef when the iterator is exhausted.
Packit 3f4df8
Packit 3f4df8
    If the "content" option is the empty string, no "content-type" or
Packit 3f4df8
    "content-length" headers will be generated.
Packit 3f4df8
Packit 3f4df8
    If the "data_callback" option is provided, it will be called iteratively
Packit 3f4df8
    until the entire response body is received. The first argument will be a
Packit 3f4df8
    string containing a chunk of the response body, the second argument will
Packit 3f4df8
    be the in-progress response hash reference, as described below. (This
Packit 3f4df8
    allows customizing the action of the callback based on the "status" or
Packit 3f4df8
    "headers" received prior to the content body.)
Packit 3f4df8
Packit 3f4df8
    The "request" method returns a hashref containing the response. The
Packit 3f4df8
    hashref will have the following keys:
Packit 3f4df8
Packit 3f4df8
    *   "success" — Boolean indicating whether the operation returned a 2XX
Packit 3f4df8
        status code
Packit 3f4df8
Packit 3f4df8
    *   "url" — URL that provided the response. This is the URL of the
Packit 3f4df8
        request unless there were redirections, in which case it is the last
Packit 3f4df8
        URL queried in a redirection chain
Packit 3f4df8
Packit 3f4df8
    *   "status" — The HTTP status code of the response
Packit 3f4df8
Packit 3f4df8
    *   "reason" — The response phrase returned by the server
Packit 3f4df8
Packit 3f4df8
    *   "content" — The body of the response. If the response does not have
Packit 3f4df8
        any content or if a data callback is provided to consume the
Packit 3f4df8
        response body, this will be the empty string
Packit 3f4df8
Packit 3f4df8
    *   "headers" — A hashref of header fields. All header field names will
Packit 3f4df8
        be normalized to be lower case. If a header is repeated, the value
Packit 3f4df8
        will be an arrayref; it will otherwise be a scalar string containing
Packit 3f4df8
        the value
Packit 3f4df8
Packit 3f4df8
    *   "protocol" - If this field exists, it is the protocol of the
Packit 3f4df8
        response such as HTTP/1.0 or HTTP/1.1
Packit 3f4df8
Packit 3f4df8
    *   "redirects" If this field exists, it is an arrayref of response hash
Packit 3f4df8
        references from redirects in the same order that redirections
Packit 3f4df8
        occurred. If it does not exist, then no redirections occurred.
Packit 3f4df8
Packit 3f4df8
    On an exception during the execution of the request, the "status" field
Packit 3f4df8
    will contain 599, and the "content" field will contain the text of the
Packit 3f4df8
    exception.
Packit 3f4df8
Packit 3f4df8
  www_form_urlencode
Packit 3f4df8
        $params = $http->www_form_urlencode( $data );
Packit 3f4df8
        $response = $http->get("http://example.com/query?$params");
Packit 3f4df8
Packit 3f4df8
    This method converts the key/value pairs from a data hash or array
Packit 3f4df8
    reference into a "x-www-form-urlencoded" string. The keys and values
Packit 3f4df8
    from the data reference will be UTF-8 encoded and escaped per RFC 3986.
Packit 3f4df8
    If a value is an array reference, the key will be repeated with each of
Packit 3f4df8
    the values of the array reference. If data is provided as a hash
Packit 3f4df8
    reference, the key/value pairs in the resulting string will be sorted by
Packit 3f4df8
    key and value for consistent ordering.
Packit 3f4df8
Packit 3f4df8
  can_ssl
Packit 3f4df8
        $ok         = HTTP::Tiny->can_ssl;
Packit 3f4df8
        ($ok, $why) = HTTP::Tiny->can_ssl;
Packit 3f4df8
        ($ok, $why) = $http->can_ssl;
Packit 3f4df8
Packit 3f4df8
    Indicates if SSL support is available. When called as a class object, it
Packit 3f4df8
    checks for the correct version of Net::SSLeay and IO::Socket::SSL. When
Packit 3f4df8
    called as an object methods, if "SSL_verify" is true or if
Packit 3f4df8
    "SSL_verify_mode" is set in "SSL_options", it checks that a CA file is
Packit 3f4df8
    available.
Packit 3f4df8
Packit 3f4df8
    In scalar context, returns a boolean indicating if SSL is available. In
Packit 3f4df8
    list context, returns the boolean and a (possibly multi-line) string of
Packit 3f4df8
    errors indicating why SSL isn't available.
Packit 3f4df8
Packit 3f4df8
  connected
Packit 3f4df8
        $host = $http->connected;
Packit 3f4df8
        ($host, $port) = $http->connected;
Packit 3f4df8
Packit 3f4df8
    Indicates if a connection to a peer is being kept alive, per the
Packit 3f4df8
    "keep_alive" option.
Packit 3f4df8
Packit 3f4df8
    In scalar context, returns the peer host and port, joined with a colon,
Packit 3f4df8
    or "undef" (if no peer is connected). In list context, returns the peer
Packit 3f4df8
    host and port or an empty list (if no peer is connected).
Packit 3f4df8
Packit 3f4df8
    Note: This method cannot reliably be used to discover whether the remote
Packit 3f4df8
    host has closed its end of the socket.
Packit 3f4df8
Packit 3f4df8
SSL SUPPORT
Packit 3f4df8
    Direct "https" connections are supported only if IO::Socket::SSL 1.56 or
Packit 3f4df8
    greater and Net::SSLeay 1.49 or greater are installed. An exception will
Packit 3f4df8
    be thrown if new enough versions of these modules are not installed or
Packit 3f4df8
    if the SSL encryption fails. You can also use "HTTP::Tiny::can_ssl()"
Packit 3f4df8
    utility function that returns boolean to see if the required modules are
Packit 3f4df8
    installed.
Packit 3f4df8
Packit 3f4df8
    An "https" connection may be made via an "http" proxy that supports the
Packit 3f4df8
    CONNECT command (i.e. RFC 2817). You may not proxy "https" via a proxy
Packit 3f4df8
    that itself requires "https" to communicate.
Packit 3f4df8
Packit 3f4df8
    SSL provides two distinct capabilities:
Packit 3f4df8
Packit 3f4df8
    *   Encrypted communication channel
Packit 3f4df8
Packit 3f4df8
    *   Verification of server identity
Packit 3f4df8
Packit 3f4df8
    By default, HTTP::Tiny does not verify server identity.
Packit 3f4df8
Packit 3f4df8
    Server identity verification is controversial and potentially tricky
Packit 3f4df8
    because it depends on a (usually paid) third-party Certificate Authority
Packit 3f4df8
    (CA) trust model to validate a certificate as legitimate. This
Packit 3f4df8
    discriminates against servers with self-signed certificates or
Packit 3f4df8
    certificates signed by free, community-driven CA's such as CAcert.org
Packit 3f4df8
    <http://cacert.org>.
Packit 3f4df8
Packit 3f4df8
    By default, HTTP::Tiny does not make any assumptions about your trust
Packit 3f4df8
    model, threat level or risk tolerance. It just aims to give you an
Packit 3f4df8
    encrypted channel when you need one.
Packit 3f4df8
Packit 3f4df8
    Setting the "verify_SSL" attribute to a true value will make HTTP::Tiny
Packit 3f4df8
    verify that an SSL connection has a valid SSL certificate corresponding
Packit 3f4df8
    to the host name of the connection and that the SSL certificate has been
Packit 3f4df8
    verified by a CA. Assuming you trust the CA, this will protect against a
Packit 3f4df8
    man-in-the-middle attack
Packit 3f4df8
    <http://en.wikipedia.org/wiki/Man-in-the-middle_attack>. If you are
Packit 3f4df8
    concerned about security, you should enable this option.
Packit 3f4df8
Packit 3f4df8
    Certificate verification requires a file containing trusted CA
Packit 3f4df8
    certificates.
Packit 3f4df8
Packit 3f4df8
    If the environment variable "SSL_CERT_FILE" is present, HTTP::Tiny will
Packit 3f4df8
    try to find a CA certificate file in that location.
Packit 3f4df8
Packit 3f4df8
    If the Mozilla::CA module is installed, HTTP::Tiny will use the CA file
Packit 3f4df8
    included with it as a source of trusted CA's. (This means you trust
Packit 3f4df8
    Mozilla, the author of Mozilla::CA, the CPAN mirror where you got
Packit 3f4df8
    Mozilla::CA, the toolchain used to install it, and your operating system
Packit 3f4df8
    security, right?)
Packit 3f4df8
Packit 3f4df8
    If that module is not available, then HTTP::Tiny will search several
Packit 3f4df8
    system-specific default locations for a CA certificate file:
Packit 3f4df8
Packit 3f4df8
    *   /etc/ssl/certs/ca-certificates.crt
Packit 3f4df8
Packit 3f4df8
    *   /etc/pki/tls/certs/ca-bundle.crt
Packit 3f4df8
Packit 3f4df8
    *   /etc/ssl/ca-bundle.pem
Packit 3f4df8
Packit 3f4df8
    An exception will be raised if "verify_SSL" is true and no CA
Packit 3f4df8
    certificate file is available.
Packit 3f4df8
Packit 3f4df8
    If you desire complete control over SSL connections, the "SSL_options"
Packit 3f4df8
    attribute lets you provide a hash reference that will be passed through
Packit 3f4df8
    to "IO::Socket::SSL::start_SSL()", overriding any options set by
Packit 3f4df8
    HTTP::Tiny. For example, to provide your own trusted CA file:
Packit 3f4df8
Packit 3f4df8
        SSL_options => {
Packit 3f4df8
            SSL_ca_file => $file_path,
Packit 3f4df8
        }
Packit 3f4df8
Packit 3f4df8
    The "SSL_options" attribute could also be used for such things as
Packit 3f4df8
    providing a client certificate for authentication to a server or
Packit 3f4df8
    controlling the choice of cipher used for the SSL connection. See
Packit 3f4df8
    IO::Socket::SSL documentation for details.
Packit 3f4df8
Packit 3f4df8
PROXY SUPPORT
Packit 3f4df8
    HTTP::Tiny can proxy both "http" and "https" requests. Only Basic proxy
Packit 3f4df8
    authorization is supported and it must be provided as part of the proxy
Packit 3f4df8
    URL: "http://user:pass@proxy.example.com/".
Packit 3f4df8
Packit 3f4df8
    HTTP::Tiny supports the following proxy environment variables:
Packit 3f4df8
Packit 3f4df8
    *   http_proxy or HTTP_PROXY
Packit 3f4df8
Packit 3f4df8
    *   https_proxy or HTTPS_PROXY
Packit 3f4df8
Packit 3f4df8
    *   all_proxy or ALL_PROXY
Packit 3f4df8
Packit 3f4df8
    If the "REQUEST_METHOD" environment variable is set, then this might be
Packit 3f4df8
    a CGI process and "HTTP_PROXY" would be set from the "Proxy:" header,
Packit 3f4df8
    which is a security risk. If "REQUEST_METHOD" is set, "HTTP_PROXY" (the
Packit 3f4df8
    upper case variant only) is ignored.
Packit 3f4df8
Packit 3f4df8
    Tunnelling "https" over an "http" proxy using the CONNECT method is
Packit 3f4df8
    supported. If your proxy uses "https" itself, you can not tunnel "https"
Packit 3f4df8
    over it.
Packit 3f4df8
Packit 3f4df8
    Be warned that proxying an "https" connection opens you to the risk of a
Packit 3f4df8
    man-in-the-middle attack by the proxy server.
Packit 3f4df8
Packit 3f4df8
    The "no_proxy" environment variable is supported in the format of a
Packit 3f4df8
    comma-separated list of domain extensions proxy should not be used for.
Packit 3f4df8
Packit 3f4df8
    Proxy arguments passed to "new" will override their corresponding
Packit 3f4df8
    environment variables.
Packit 3f4df8
Packit 3f4df8
LIMITATIONS
Packit 3f4df8
    HTTP::Tiny is *conditionally compliant* with the HTTP/1.1 specifications
Packit 3f4df8
    <http://www.w3.org/Protocols/>:
Packit 3f4df8
Packit 3f4df8
    *   "Message Syntax and Routing" [RFC7230]
Packit 3f4df8
Packit 3f4df8
    *   "Semantics and Content" [RFC7231]
Packit 3f4df8
Packit 3f4df8
    *   "Conditional Requests" [RFC7232]
Packit 3f4df8
Packit 3f4df8
    *   "Range Requests" [RFC7233]
Packit 3f4df8
Packit 3f4df8
    *   "Caching" [RFC7234]
Packit 3f4df8
Packit 3f4df8
    *   "Authentication" [RFC7235]
Packit 3f4df8
Packit 3f4df8
    It attempts to meet all "MUST" requirements of the specification, but
Packit 3f4df8
    does not implement all "SHOULD" requirements. (Note: it was developed
Packit 3f4df8
    against the earlier RFC 2616 specification and may not yet meet the
Packit 3f4df8
    revised RFC 7230-7235 spec.)
Packit 3f4df8
Packit 3f4df8
    Some particular limitations of note include:
Packit 3f4df8
Packit 3f4df8
    *   HTTP::Tiny focuses on correct transport. Users are responsible for
Packit 3f4df8
        ensuring that user-defined headers and content are compliant with
Packit 3f4df8
        the HTTP/1.1 specification.
Packit 3f4df8
Packit 3f4df8
    *   Users must ensure that URLs are properly escaped for unsafe
Packit 3f4df8
        characters and that international domain names are properly encoded
Packit 3f4df8
        to ASCII. See URI::Escape, URI::_punycode and Net::IDN::Encode.
Packit 3f4df8
Packit 3f4df8
    *   Redirection is very strict against the specification. Redirection is
Packit 3f4df8
        only automatic for response codes 301, 302, 307 and 308 if the
Packit 3f4df8
        request method is 'GET' or 'HEAD'. Response code 303 is always
Packit 3f4df8
        converted into a 'GET' redirection, as mandated by the
Packit 3f4df8
        specification. There is no automatic support for status 305 ("Use
Packit 3f4df8
        proxy") redirections.
Packit 3f4df8
Packit 3f4df8
    *   There is no provision for delaying a request body using an "Expect"
Packit 3f4df8
        header. Unexpected "1XX" responses are silently ignored as per the
Packit 3f4df8
        specification.
Packit 3f4df8
Packit 3f4df8
    *   Only 'chunked' "Transfer-Encoding" is supported.
Packit 3f4df8
Packit 3f4df8
    *   There is no support for a Request-URI of '*' for the 'OPTIONS'
Packit 3f4df8
        request.
Packit 3f4df8
Packit 3f4df8
    *   Headers mentioned in the RFCs and some other, well-known headers are
Packit 3f4df8
        generated with their canonical case. Other headers are sent in the
Packit 3f4df8
        case provided by the user. Except for control headers (which are
Packit 3f4df8
        sent first), headers are sent in arbitrary order.
Packit 3f4df8
Packit 3f4df8
    Despite the limitations listed above, HTTP::Tiny is considered
Packit 3f4df8
    feature-complete. New feature requests should be directed to
Packit 3f4df8
    HTTP::Tiny::UA.
Packit 3f4df8
Packit 3f4df8
SEE ALSO
Packit 3f4df8
    *   HTTP::Tiny::UA - Higher level UA features for HTTP::Tiny
Packit 3f4df8
Packit 3f4df8
    *   HTTP::Thin - HTTP::Tiny wrapper with HTTP::Request/HTTP::Response
Packit 3f4df8
        compatibility
Packit 3f4df8
Packit 3f4df8
    *   HTTP::Tiny::Mech - Wrap WWW::Mechanize instance in HTTP::Tiny
Packit 3f4df8
        compatible interface
Packit 3f4df8
Packit 3f4df8
    *   IO::Socket::IP - Required for IPv6 support
Packit 3f4df8
Packit 3f4df8
    *   IO::Socket::SSL - Required for SSL support
Packit 3f4df8
Packit 3f4df8
    *   LWP::UserAgent - If HTTP::Tiny isn't enough for you, this is the
Packit 3f4df8
        "standard" way to do things
Packit 3f4df8
Packit 3f4df8
    *   Mozilla::CA - Required if you want to validate SSL certificates
Packit 3f4df8
Packit 3f4df8
    *   Net::SSLeay - Required for SSL support
Packit 3f4df8
Packit 3f4df8
SUPPORT
Packit 3f4df8
  Bugs / Feature Requests
Packit 3f4df8
    Please report any bugs or feature requests through the issue tracker at
Packit 3f4df8
    <https://github.com/chansen/p5-http-tiny/issues>. You will be notified
Packit 3f4df8
    automatically of any progress on your issue.
Packit 3f4df8
Packit 3f4df8
  Source Code
Packit 3f4df8
    This is open source software. The code repository is available for
Packit 3f4df8
    public review and contribution under the terms of the license.
Packit 3f4df8
Packit 3f4df8
    <https://github.com/chansen/p5-http-tiny>
Packit 3f4df8
Packit 3f4df8
      git clone https://github.com/chansen/p5-http-tiny.git
Packit 3f4df8
Packit 3f4df8
AUTHORS
Packit 3f4df8
    *   Christian Hansen <chansen@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   David Golden <dagolden@cpan.org>
Packit 3f4df8
Packit 3f4df8
CONTRIBUTORS
Packit 3f4df8
    *   Alan Gardner <gardner@pythian.com>
Packit 3f4df8
Packit 3f4df8
    *   Alessandro Ghedini <al3xbio@gmail.com>
Packit 3f4df8
Packit 3f4df8
    *   A. Sinan Unur <nanis@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   Brad Gilbert <bgills@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   brian m. carlson <sandals@crustytoothpaste.net>
Packit 3f4df8
Packit 3f4df8
    *   Chris Nehren <apeiron@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   Chris Weyl <cweyl@alumni.drew.edu>
Packit 3f4df8
Packit 3f4df8
    *   Claes Jakobsson <claes@surfar.nu>
Packit 3f4df8
Packit 3f4df8
    *   Clinton Gormley <clint@traveljury.com>
Packit 3f4df8
Packit 3f4df8
    *   Craig A. Berry <craigberry@mac.com>
Packit 3f4df8
Packit 3f4df8
    *   Craig Berry <cberry@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   David Golden <xdg@xdg.me>
Packit 3f4df8
Packit 3f4df8
    *   David Mitchell <davem@iabyn.com>
Packit 3f4df8
Packit 3f4df8
    *   Dean Pearce <pearce@pythian.com>
Packit 3f4df8
Packit 3f4df8
    *   Edward Zborowski <ed@rubensteintech.com>
Packit 3f4df8
Packit 3f4df8
    *   James Raspass <jraspass@gmail.com>
Packit 3f4df8
Packit 3f4df8
    *   Jeremy Mates <jmates@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   Jess Robinson <castaway@desert-island.me.uk>
Packit 3f4df8
Packit 3f4df8
    *   Karen Etheridge <ether@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   Lukas Eklund <leklund@gmail.com>
Packit 3f4df8
Packit 3f4df8
    *   Martin J. Evans <mjegh@ntlworld.com>
Packit 3f4df8
Packit 3f4df8
    *   Martin-Louis Bright <mlbright@gmail.com>
Packit 3f4df8
Packit 3f4df8
    *   Mike Doherty <doherty@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   Nicolas Rochelemagne <rochelemagne@cpanel.net>
Packit 3f4df8
Packit 3f4df8
    *   Olaf Alders <olaf@wundersolutions.com>
Packit 3f4df8
Packit 3f4df8
    *   Olivier Mengué <dolmen@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   Petr Písař <ppisar@redhat.com>
Packit 3f4df8
Packit 3f4df8
    *   Serguei Trouchelle <stro@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   Shoichi Kaji <skaji@cpan.org>
Packit 3f4df8
Packit 3f4df8
    *   SkyMarshal <skymarshal1729@gmail.com>
Packit 3f4df8
Packit 3f4df8
    *   Sören Kornetzki <soeren.kornetzki@delti.com>
Packit 3f4df8
Packit 3f4df8
    *   Steve Grazzini <steve.grazzini@grantstreet.com>
Packit 3f4df8
Packit 3f4df8
    *   Syohei YOSHIDA <syohex@gmail.com>
Packit 3f4df8
Packit 3f4df8
    *   Tatsuhiko Miyagawa <miyagawa@bulknews.net>
Packit 3f4df8
Packit 3f4df8
    *   Tom Hukins <tom@eborcom.com>
Packit 3f4df8
Packit 3f4df8
    *   Tony Cook <tony@develop-help.com>
Packit 3f4df8
Packit 3f4df8
COPYRIGHT AND LICENSE
Packit 3f4df8
    This software is copyright (c) 2018 by Christian Hansen.
Packit 3f4df8
Packit 3f4df8
    This is free software; you can redistribute it and/or modify it under
Packit 3f4df8
    the same terms as the Perl 5 programming language system itself.
Packit 3f4df8