内容

名称

HTTP::Tiny - 一个小巧、简单、正确的 HTTP/1.1 客户端

版本

版本 0.086

概要

use HTTP::Tiny;

my $response = HTTP::Tiny->new->get('http://example.com/');

die "Failed!\n" unless $response->{success};

print "$response->{status} $response->{reason}\n";

while (my ($k, $v) = each %{$response->{headers}}) {
    for (ref $v eq 'ARRAY' ? @$v : $v) {
        print "$k: $_\n";
    }
}

print $response->{content} if length $response->{content};

描述

这是一个非常简单的 HTTP/1.1 客户端，旨在进行简单的请求，而无需像 LWP::UserAgent 这样的大型框架的开销。

它比 HTTP::Lite 更正确、更完整。它支持代理和重定向。它还可以在 EINTR 之后正确恢复。

如果安装了 IO::Socket::IP 0.25 或更高版本，HTTP::Tiny 将使用它而不是 IO::Socket::INET，以透明地支持 IPv4 和 IPv6。

Cookie 支持需要 HTTP::CookieJar 或支持 add 和 cookie_header 方法的等效类。

方法

new

$http = HTTP::Tiny->new( %attributes );

此构造函数返回一个新的 HTTP::Tiny 对象。有效的属性包括

每个属性都存在访问器/修改器方法。

为 proxy、http_proxy 或 https_proxy 传递显式 undef 将阻止从环境获取相应的代理。

请求执行期间的错误将导致伪 HTTP 状态码为 599，原因是“内部异常”。响应中的内容字段将包含错误文本。

keep_alive 参数启用持久连接，但仅限于单个目标方案、主机和端口。如果通过访问器修改了任何与连接相关的属性，或者进程 ID 或线程 ID 发生更改，则持久连接将被丢弃。如果您希望跨多个目标建立持久连接，请使用多个 HTTP::Tiny 对象。

有关 verify_SSL 和 SSL_options 属性的更多信息，请参阅 "SSL 支持"。

get|head|put|post|patch|delete

$response = $http->get($url);
$response = $http->get($url, \%options);
$response = $http->head($url);

这些方法是为给定方法调用 request() 的简写。URL 必须对不安全字符进行转义，并对国际域名进行编码。有关有效选项和对响应的描述，请参见 request()。

如果状态代码为 2XX，则响应的 success 字段将为 true。

post_form

$response = $http->post_form($url, $form_data);
$response = $http->post_form($url, $form_data, \%options);

此方法执行 POST 请求，并将表单数据哈希或数组引用中的键值对发送到给定 URL，并使用 content-type 为 application/x-www-form-urlencoded。如果数据作为数组引用提供，则顺序将保留；如果作为哈希引用提供，则条款将按键和值排序以确保一致性。有关编码的详细信息，请参见 www_form_urlencode 方法的文档。

URL 必须对不安全字符进行转义，并对国际域名进行编码。有关有效选项和对响应的描述，请参见 request()。选项哈希引用中的任何 content-type 标头或内容都将被忽略。

如果状态代码为 2XX，则响应的 success 字段将为 true。

mirror

$response = $http->mirror($url, $file, \%options)
if ( $response->{success} ) {
    print "$file is up to date\n";
}

对 URL 执行 GET 请求，并将响应主体保存到提供的文件名中。URL 必须对不安全字符进行转义，并对国际域名进行编码。如果文件已存在，则请求将包含一个 If-Modified-Since 标头，其中包含文件的修改时间戳。您可以在 $options->{headers} 哈希中自己指定不同的 If-Modified-Since 标头。

如果状态代码为 2XX 或 304（未修改），则响应的 success 字段将为 true。

如果文件已修改，并且服务器响应包含正确格式的 Last-Modified 标头，则文件修改时间将相应更新。

request

$response = $http->request($method, $url);
$response = $http->request($method, $url, \%options);

对给定 URL 执行给定方法类型（'GET'、'HEAD'、'POST'、'PUT' 等）的 HTTP 请求。URL 必须对不安全字符进行转义，并对国际域名进行编码。

注意：方法名称区分大小写，符合 HTTP/1.1 规范。不要在真正需要 GET 时使用 get。有关这如何应用于重定向，请参见 LIMITATIONS。

如果 URL 包含“user:password”节，它们将用于基本身份验证标头。（授权标头不会包含在重定向请求中。）例如

$http->request('GET', 'http://Aladdin:open [email protected]/');

如果 "user:password" 部分包含保留字符，则必须进行百分比转义。

$http->request('GET', 'http://john%40example.com:[email protected]/');

可以附加一个选项的哈希引用来修改请求。

有效的选项包括：

Host 标头根据 RFC 2616 从 URL 生成。在 headers 选项中指定 Host 是致命错误。其他标头可能会被忽略或覆盖，如果需要，以确保传输符合标准。

如果 content 选项是代码引用，它将被迭代调用以提供请求的正文内容。当迭代器耗尽时，它应该返回空字符串或 undef。

如果 content 选项为空字符串，则不会生成 content-type 或 content-length 标头。

如果提供了data_callback选项，它将被迭代调用，直到接收整个响应主体。第一个参数将是一个包含响应主体一部分的字符串，第二个参数将是正在进行的响应哈希引用，如下所述。（这允许根据在内容主体之前接收到的status或headers定制回调的操作。）

请求/响应中的内容数据被处理为“原始字节”。任何编码/解码（以及相关的标头）都是调用者的责任。

request方法返回一个包含响应的哈希引用。哈希引用将具有以下键

在请求执行期间发生错误时，status字段将包含 599，content字段将包含错误文本。

www_form_urlencode

$params = $http->www_form_urlencode( $data );
$response = $http->get("http://example.com/query?$params");

此方法将数据哈希或数组引用中的键/值对转换为x-www-form-urlencoded字符串。数据引用中的键和值将根据 RFC 3986 进行 UTF-8 编码和转义。如果值是数组引用，则键将与数组引用的每个值一起重复。如果数据作为哈希引用提供，则结果字符串中的键/值对将按键和值排序，以确保一致的排序。

can_ssl

$ok         = HTTP::Tiny->can_ssl;
($ok, $why) = HTTP::Tiny->can_ssl;
($ok, $why) = $http->can_ssl;

指示是否支持 SSL。当作为类对象调用时，它检查Net::SSLeay和IO::Socket::SSL的正确版本。当作为对象方法调用时，如果SSL_verify为真，或者如果在SSL_options中设置了SSL_verify_mode，它将检查 CA 文件是否可用。

在标量上下文中，返回一个布尔值，指示 SSL 是否可用。在列表上下文中，返回布尔值和一个（可能是多行的）错误字符串，指示 SSL 为什么不可用。

connected

$host = $http->connected;
($host, $port) = $http->connected;

指示是否根据 keep_alive 选项保持与对等方的连接。

在标量上下文中，返回用冒号分隔的对等方主机和端口，或 undef（如果未连接到对等方）。在列表上下文中，返回对等方主机和端口或空列表（如果未连接到对等方）。

注意：此方法不能可靠地用于发现远程主机是否已关闭其套接字端。

TLS/SSL 支持

仅当安装了 IO::Socket::SSL 1.56 或更高版本和 Net::SSLeay 1.49 或更高版本时，才支持直接 https 连接。如果未安装这些模块的最新版本或 TLS 加密失败，则会发生错误。您还可以使用 HTTP::Tiny::can_ssl() 实用程序函数，该函数返回布尔值以查看是否安装了所需的模块。

可以通过支持 CONNECT 命令（即 RFC 2817）的 http 代理建立 https 连接。您不能通过本身需要 https 进行通信的代理代理 https。

TLS/SSL 提供两种不同的功能

默认情况下，HTTP::Tiny 会验证服务器身份.

由于安全问题，此行为在 0.083 版本中发生了更改。可以通过将 $ENV{PERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULT} 设置为 1 来启用之前的默认行为。

验证通过检查 TLS/SSL 连接是否具有与连接主机名相对应的有效证书以及证书是否已由 CA 验证来完成。假设您信任 CA，这将防止 中间人攻击。

证书验证需要包含受信任 CA 证书的文件。

如果存在环境变量 SSL_CERT_FILE，HTTP::Tiny 将尝试在该位置查找 CA 证书文件。

如果安装了 Mozilla::CA 模块，HTTP::Tiny 将使用其中包含的 CA 文件作为受信任 CA 的来源。

如果该模块不可用，则 HTTP::Tiny 将在多个系统特定的默认位置搜索 CA 证书文件

如果 verify_SSL 为真且没有可用的 CA 证书文件，则会发生错误。

如果您希望完全控制 TLS/SSL 连接，则 SSL_options 属性允许您提供一个哈希引用，该引用将传递给 IO::Socket::SSL::start_SSL()，覆盖 HTTP::Tiny 设置的任何选项。例如，要提供您自己的受信任 CA 文件

SSL_options => {
    SSL_ca_file => $file_path,
}

SSL_options 属性也可以用于诸如为服务器身份验证提供客户端证书或控制用于 TLS/SSL 连接的密码选择等操作。有关详细信息，请参阅 IO::Socket::SSL 文档。

代理支持

HTTP::Tiny 可以代理 http 和 https 请求。仅支持基本代理授权，并且必须作为代理 URL 的一部分提供：http://user:[email protected]/。

HTTP::Tiny 支持以下代理环境变量

如果设置了 REQUEST_METHOD 环境变量，则这可能是一个 CGI 进程，并且 HTTP_PROXY 将从 Proxy: 标头设置，这是一个安全风险。如果设置了 REQUEST_METHOD，则会忽略 HTTP_PROXY（仅忽略大写变体），但会考虑 CGI_HTTP_PROXY。

支持使用 CONNECT 方法通过 http 代理隧道 https。如果您的代理本身使用 https，则无法通过它隧道 https。

请注意，代理 https 连接会使您面临代理服务器中间人攻击的风险。

no_proxy 环境变量以逗号分隔的域名扩展列表的形式支持，代理不应为此列表使用代理。

传递给 new 的代理参数将覆盖其相应的环境变量。

限制

HTTP::Tiny 有条件地符合 HTTP/1.1 规范

它试图满足规范中所有“必须”的要求，但没有实现所有“应该”的要求。（注意：它是针对早期的 RFC 2616 规范开发的，可能尚未满足修订后的 RFC 7230-7235 规范。）此外，HTTP::Tiny 支持 RFC 5789 的 PATCH 方法。

一些值得注意的特定限制包括

尽管存在上述限制，但 HTTP::Tiny 被认为功能齐全。新的功能请求应发送到 HTTP::Tiny::UA。

另请参阅

支持

Bug / 功能请求

请通过以下问题跟踪器报告任何 Bug 或功能请求：https://github.com/chansen/p5-http-tiny/issues。您将自动收到有关您问题进度的通知。

源代码

这是一个开源软件。代码库可供公众根据许可条款进行审查和贡献。

https://github.com/chansen/p5-http-tiny

git clone https://github.com/chansen/p5-http-tiny.git

作者

贡献者

版权和许可

本软件版权 (c) 2023 由 Christian Hansen 所有。

这是一个自由软件；您可以根据 Perl 5 编程语言系统本身的相同条款重新发布和/或修改它。