Debian Codegraph @

upstream/mageia-cauldron/man3pm/HTTP::Tiny.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "HTTP::Tiny 3pm"
61 .TH HTTP::Tiny 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 HTTP::Tiny \- A small, simple, correct HTTP/1.1 client
68 .SH VERSION
69 .IX Header "VERSION"
70 version 0.090
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& use HTTP::Tiny;
75 \&
76 \& my $response = HTTP::Tiny\->new\->get(\*(Aqhttp://example.com/\*(Aq);
77 \&
78 \& die "Failed!\en" unless $response\->{success};
79 \&
80 \& print "$response\->{status} $response\->{reason}\en";
81 \&
82 \& while (my ($k, $v) = each %{$response\->{headers}}) {
83 \& for (ref $v eq \*(AqARRAY\*(Aq ? @$v : $v) {
84 \& print "$k: $_\en";
85 \& }
86 \& }
87 \&
88 \& print $response\->{content} if length $response\->{content};
89 .Ve
90 .SH DESCRIPTION
91 .IX Header "DESCRIPTION"
92 This is a very simple HTTP/1.1 client, designed for doing simple
93 requests without the overhead of a large framework like LWP::UserAgent.
94 .PP
95 It is more correct and more complete than HTTP::Lite. It supports
96 proxies and redirection. It also correctly resumes after EINTR.
97 .PP
98 If IO::Socket::IP 0.25 or later is installed, HTTP::Tiny will use it instead
99 of IO::Socket::INET for transparent support for both IPv4 and IPv6.
100 .PP
101 Cookie support requires HTTP::CookieJar or an equivalent class.
102 .SH METHODS
103 .IX Header "METHODS"
104 .SS new
105 .IX Subsection "new"
106 .Vb 1
107 \& $http = HTTP::Tiny\->new( %attributes );
108 .Ve
109 .PP
110 This constructor returns a new HTTP::Tiny object. Valid attributes include:
111 .IP \(bu 4
112 \&\f(CW\*(C`agent\*(C'\fR — A user\-agent string (defaults to \*(AqHTTP\-Tiny/$VERSION\*(Aq). If \f(CW\*(C`agent\*(C'\fR — ends in a space character, the default user\-agent string is appended.
113 .IP \(bu 4
114 \&\f(CW\*(C`cookie_jar\*(C'\fR — An instance of HTTP::CookieJar — or equivalent class that supports the \f(CW\*(C`add\*(C'\fR and \f(CW\*(C`cookie_header\*(C'\fR methods
115 .IP \(bu 4
116 \&\f(CW\*(C`default_headers\*(C'\fR — A hashref of default headers to apply to requests
117 .IP \(bu 4
118 \&\f(CW\*(C`local_address\*(C'\fR — The local IP address to bind to
119 .IP \(bu 4
120 \&\f(CW\*(C`keep_alive\*(C'\fR — Whether to reuse the last connection (if for the same scheme, host and port) (defaults to 1)
121 .IP \(bu 4
122 \&\f(CW\*(C`max_redirect\*(C'\fR — Maximum number of redirects allowed (defaults to 5)
123 .IP \(bu 4
124 \&\f(CW\*(C`max_size\*(C'\fR — Maximum response size in bytes (only when not using a data callback). If defined, requests with responses larger than this will return a 599 status code.
125 .IP \(bu 4
126 \&\f(CW\*(C`http_proxy\*(C'\fR — URL of a proxy server to use for HTTP connections (default is \f(CW$ENV{http_proxy}\fR — if set)
127 .IP \(bu 4
128 \&\f(CW\*(C`https_proxy\*(C'\fR — URL of a proxy server to use for HTTPS connections (default is \f(CW$ENV{https_proxy}\fR — if set)
129 .IP \(bu 4
130 \&\f(CW\*(C`proxy\*(C'\fR — URL of a generic proxy server for both HTTP and HTTPS connections (default is \f(CW$ENV{all_proxy}\fR — if set)
131 .IP \(bu 4
132 \&\f(CW\*(C`no_proxy\*(C'\fR — List of domain suffixes that should not be proxied. Must be a comma\-separated string or an array reference. (default is \f(CW$ENV{no_proxy}\fR —)
133 .IP \(bu 4
134 \&\f(CW\*(C`timeout\*(C'\fR — Request timeout in seconds (default is 60) If a socket open, read or write takes longer than the timeout, the request response status code will be 599.
135 .IP \(bu 4
136 \&\f(CW\*(C`verify_SSL\*(C'\fR — A boolean that indicates whether to validate the TLS/SSL certificate of an \f(CW\*(C`https\*(C'\fR — connection (default is true). Changed from false to true in version 0.083.
137 .IP \(bu 4
138 \&\f(CW\*(C`SSL_options\*(C'\fR — A hashref of \f(CW\*(C`SSL_*\*(C'\fR — options to pass through to IO::Socket::SSL
139 .IP \(bu 4
140 \&\f(CW$ENV{PERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULT}\fR \- Changes the default certificate verification behavior to not check server identity if set to 1. Only effective if \f(CW\*(C`verify_SSL\*(C'\fR is not set. Added in version 0.083.
141 .PP
142 An accessor/mutator method exists for each attribute.
143 .PP
144 Passing an explicit \f(CW\*(C`undef\*(C'\fR for \f(CW\*(C`proxy\*(C'\fR, \f(CW\*(C`http_proxy\*(C'\fR or \f(CW\*(C`https_proxy\*(C'\fR will
145 prevent getting the corresponding proxies from the environment.
146 .PP
147 Errors during request execution will result in a pseudo\-HTTP status code of 599
148 and a reason of "Internal Exception". The content field in the response will
149 contain the text of the error.
150 .PP
151 The \f(CW\*(C`keep_alive\*(C'\fR parameter enables a persistent connection, but only to a
152 single destination scheme, host and port. If any connection\-relevant
153 attributes are modified via accessor, or if the process ID or thread ID change,
154 the persistent connection will be dropped. If you want persistent connections
155 across multiple destinations, use multiple HTTP::Tiny objects.
156 .PP
157 See "TLS/SSL SUPPORT" for more on the \f(CW\*(C`verify_SSL\*(C'\fR and \f(CW\*(C`SSL_options\*(C'\fR
158 attributes.
159 .SS get|head|put|post|patch|delete
160 .IX Subsection "get|head|put|post|patch|delete"
161 .Vb 3
162 \& $response = $http\->get($url);
163 \& $response = $http\->get($url, \e%options);
164 \& $response = $http\->head($url);
165 .Ve
166 .PP
167 These methods are shorthand for calling \f(CWrequest()\fR for the given method. The
168 URL must have unsafe characters escaped and international domain names encoded.
169 See \f(CWrequest()\fR for valid options and a description of the response.
170 .PP
171 The \f(CW\*(C`success\*(C'\fR field of the response will be true if the status code is 2XX.
172 .SS post_form
173 .IX Subsection "post_form"
174 .Vb 2
175 \& $response = $http\->post_form($url, $form_data);
176 \& $response = $http\->post_form($url, $form_data, \e%options);
177 .Ve
178 .PP
179 This method executes a \f(CW\*(C`POST\*(C'\fR request and sends the key/value pairs from a
180 form data hash or array reference to the given URL with a \f(CW\*(C`content\-type\*(C'\fR of
181 \&\f(CW\*(C`application/x\-www\-form\-urlencoded\*(C'\fR. If data is provided as an array
182 reference, the order is preserved; if provided as a hash reference, the terms
183 are sorted by key for consistency. See documentation for the
184 \&\f(CW\*(C`www_form_urlencode\*(C'\fR method for details on the encoding.
185 .PP
186 The URL must have unsafe characters escaped and international domain names
187 encoded. See \f(CWrequest()\fR for valid options and a description of the response.
188 Any \f(CW\*(C`content\-type\*(C'\fR header or content in the options hashref will be ignored.
189 .PP
190 The \f(CW\*(C`success\*(C'\fR field of the response will be true if the status code is 2XX.
191 .SS mirror
192 .IX Subsection "mirror"
193 .Vb 4
194 \& $response = $http\->mirror($url, $file, \e%options)
195 \& if ( $response\->{success} ) {
196 \& print "$file is up to date\en";
197 \& }
198 .Ve
199 .PP
200 Executes a \f(CW\*(C`GET\*(C'\fR request for the URL and saves the response body to the file
201 name provided. The URL must have unsafe characters escaped and international
202 domain names encoded. If the file already exists, the request will include an
203 \&\f(CW\*(C`If\-Modified\-Since\*(C'\fR header with the modification timestamp of the file. You
204 may specify a different \f(CW\*(C`If\-Modified\-Since\*(C'\fR header yourself in the \f(CW\*(C`$options\->{headers}\*(C'\fR hash.
205 .PP
206 The \f(CW\*(C`success\*(C'\fR field of the response will be true if the status code is 2XX
207 or if the status code is 304 (unmodified).
208 .PP
209 If the file was modified and the server response includes a properly
210 formatted \f(CW\*(C`Last\-Modified\*(C'\fR header, the file modification time will
211 be updated accordingly.
212 .SS request
213 .IX Subsection "request"
214 .Vb 2
215 \& $response = $http\->request($method, $url);
216 \& $response = $http\->request($method, $url, \e%options);
217 .Ve
218 .PP
219 Executes an HTTP request of the given method type (\*(AqGET\*(Aq, \*(AqHEAD\*(Aq, \*(AqPOST\*(Aq,
220 \&\*(AqPUT\*(Aq, etc.) on the given URL. The URL must have unsafe characters escaped and
221 international domain names encoded.
222 .PP
223 \&\fBNOTE\fR: Method names are \fBcase\-sensitive\fR per the HTTP/1.1 specification.
224 Don\*(Aqt use \f(CW\*(C`get\*(C'\fR when you really want \f(CW\*(C`GET\*(C'\fR. See LIMITATIONS for
225 how this applies to redirection.
226 .PP
227 If the URL includes a "user:password" stanza, they will be used for Basic\-style
228 authorization headers. (Authorization headers will not be included in a
229 redirected request.) For example:
230 .PP
231 .Vb 1
232 \& $http\->request(\*(AqGET\*(Aq, \*(Aqhttp://Aladdin:open [email protected]/\*(Aq);
233 .Ve
234 .PP
235 If the "user:password" stanza contains reserved characters, they must
236 be percent\-escaped:
237 .PP
238 .Vb 1
239 \& $http\->request(\*(AqGET\*(Aq, \*(Aqhttp://john%40example.com:[email protected]/\*(Aq);
240 .Ve
241 .PP
242 A hashref of options may be appended to modify the request.
243 .PP
244 Valid options are:
245 .IP \(bu 4
246 \&\f(CW\*(C`headers\*(C'\fR — A hashref containing headers to include with the request. If the value for a header is an array reference, the header will be output multiple times with each value in the array. These headers over\-write any default headers.
247 .IP \(bu 4
248 \&\f(CW\*(C`content\*(C'\fR — A scalar to include as the body of the request OR a code reference that will be called iteratively to produce the body of the request
249 .IP \(bu 4
250 \&\f(CW\*(C`trailer_callback\*(C'\fR — A code reference that will be called if it exists to provide a hashref of trailing headers (only used with chunked transfer\-encoding)
251 .IP \(bu 4
252 \&\f(CW\*(C`data_callback\*(C'\fR — A code reference that will be called for each chunks of the response body received.
253 .IP \(bu 4
254 \&\f(CW\*(C`peer\*(C'\fR — Override host resolution and force all connections to go only to a specific peer address, regardless of the URL of the request. This will include any redirections! This options should be used with extreme caution (e.g. debugging or very special circumstances). It can be given as either a scalar or a code reference that will receive the hostname and whose response will be taken as the address.
255 .PP
256 The \f(CW\*(C`Host\*(C'\fR header is generated from the URL in accordance with RFC 2616. It
257 is a fatal error to specify \f(CW\*(C`Host\*(C'\fR in the \f(CW\*(C`headers\*(C'\fR option. Other headers
258 may be ignored or overwritten if necessary for transport compliance.
259 .PP
260 If the \f(CW\*(C`content\*(C'\fR option is a code reference, it will be called iteratively
261 to provide the content body of the request. It should return the empty
262 string or undef when the iterator is exhausted.
263 .PP
264 If the \f(CW\*(C`content\*(C'\fR option is the empty string, no \f(CW\*(C`content\-type\*(C'\fR or
265 \&\f(CW\*(C`content\-length\*(C'\fR headers will be generated.
266 .PP
267 If the \f(CW\*(C`data_callback\*(C'\fR option is provided, it will be called iteratively until
268 the entire response body is received. The first argument will be a string
269 containing a chunk of the response body, the second argument will be the
270 in\-progress response hash reference, as described below. (This allows
271 customizing the action of the callback based on the \f(CW\*(C`status\*(C'\fR or \f(CW\*(C`headers\*(C'\fR
272 received prior to the content body.)
273 .PP
274 Content data in the request/response is handled as "raw bytes". Any
275 encoding/decoding (with associated headers) are the responsibility of the
276 caller.
277 .PP
278 The \f(CW\*(C`request\*(C'\fR method returns a hashref containing the response. The hashref
279 will have the following keys:
280 .IP \(bu 4
281 \&\f(CW\*(C`success\*(C'\fR — Boolean indicating whether the operation returned a 2XX status code
282 .IP \(bu 4
283 \&\f(CW\*(C`url\*(C'\fR — URL that provided the response. This is the URL of the request unless there were redirections, in which case it is the last URL queried in a redirection chain
284 .IP \(bu 4
285 \&\f(CW\*(C`status\*(C'\fR — The HTTP status code of the response
286 .IP \(bu 4
287 \&\f(CW\*(C`reason\*(C'\fR — The response phrase returned by the server
288 .IP \(bu 4
289 \&\f(CW\*(C`content\*(C'\fR — The body of the response. If the response does not have any content or if a data callback is provided to consume the response body, this will be the empty string
290 .IP \(bu 4
291 \&\f(CW\*(C`headers\*(C'\fR — A hashref of header fields. All header field names will be normalized to be lower case. If a header is repeated, the value will be an arrayref; it will otherwise be a scalar string containing the value
292 .IP \(bu 4
293 \&\f(CW\*(C`protocol\*(C'\fR \- If this field exists, it is the protocol of the response such as HTTP/1.0 or HTTP/1.1
294 .IP \(bu 4
295 \&\f(CW\*(C`redirects\*(C'\fR If this field exists, it is an arrayref of response hash references from redirects in the same order that redirections occurred. If it does not exist, then no redirections occurred.
296 .PP
297 On an error during the execution of the request, the \f(CW\*(C`status\*(C'\fR field will
298 contain 599, and the \f(CW\*(C`content\*(C'\fR field will contain the text of the error.
299 .SS www_form_urlencode
300 .IX Subsection "www_form_urlencode"
301 .Vb 2
302 \& $params = $http\->www_form_urlencode( $data );
303 \& $response = $http\->get("http://example.com/query?$params");
304 .Ve
305 .PP
306 This method converts the key/value pairs from a data hash or array reference
307 into a \f(CW\*(C`x\-www\-form\-urlencoded\*(C'\fR string. The keys and values from the data
308 reference will be UTF\-8 encoded and escaped per RFC 3986. If a value is an
309 array reference, the key will be repeated with each of the values of the array
310 reference. If data is provided as a hash reference, the key/value pairs in the
311 resulting string will be sorted by key and value for consistent ordering.
312 .SS can_ssl
313 .IX Subsection "can_ssl"
314 .Vb 3
315 \& $ok = HTTP::Tiny\->can_ssl;
316 \& ($ok, $why) = HTTP::Tiny\->can_ssl;
317 \& ($ok, $why) = $http\->can_ssl;
318 .Ve
319 .PP
320 Indicates if SSL support is available. When called as a class object, it
321 checks for the correct version of Net::SSLeay and IO::Socket::SSL.
322 When called as an object methods, if \f(CW\*(C`SSL_verify\*(C'\fR is true or if \f(CW\*(C`SSL_verify_mode\*(C'\fR
323 is set in \f(CW\*(C`SSL_options\*(C'\fR, it checks that a CA file is available.
324 .PP
325 In scalar context, returns a boolean indicating if SSL is available.
326 In list context, returns the boolean and a (possibly multi\-line) string of
327 errors indicating why SSL isn\*(Aqt available.
328 .SS connected
329 .IX Subsection "connected"
330 .Vb 2
331 \& $host = $http\->connected;
332 \& ($host, $port) = $http\->connected;
333 .Ve
334 .PP
335 Indicates if a connection to a peer is being kept alive, per the \f(CW\*(C`keep_alive\*(C'\fR
336 option.
337 .PP
338 In scalar context, returns the peer host and port, joined with a colon, or
339 \&\f(CW\*(C`undef\*(C'\fR (if no peer is connected).
340 In list context, returns the peer host and port or an empty list (if no peer
341 is connected).
342 .PP
343 \&\fBNote\fR: This method cannot reliably be used to discover whether the remote
344 host has closed its end of the socket.
345 .SH "TLS/SSL SUPPORT"
346 .IX Header "TLS/SSL SUPPORT"
347 Direct \f(CW\*(C`https\*(C'\fR connections are supported only if IO::Socket::SSL 1.56 or
348 greater and Net::SSLeay 1.49 or greater are installed. An error will occur
349 if new enough versions of these modules are not installed or if the TLS
350 encryption fails. You can also use \f(CWHTTP::Tiny::can_ssl()\fR utility function
351 that returns boolean to see if the required modules are installed.
352 .PP
353 An \f(CW\*(C`https\*(C'\fR connection may be made via an \f(CW\*(C`http\*(C'\fR proxy that supports the CONNECT
354 command (i.e. RFC 2817). You may not proxy \f(CW\*(C`https\*(C'\fR via a proxy that itself
355 requires \f(CW\*(C`https\*(C'\fR to communicate.
356 .PP
357 TLS/SSL provides two distinct capabilities:
358 .IP \(bu 4
359 Encrypted communication channel
360 .IP \(bu 4
361 Verification of server identity
362 .PP
363 \&\fBBy default, HTTP::Tiny verifies server identity\fR.
364 .PP
365 This was changed in version 0.083 due to security concerns. The previous default
366 behavior can be enabled by setting \f(CW$ENV{PERL_HTTP_TINY_SSL_INSECURE_BY_DEFAULT}\fR
367 to 1.
368 .PP
369 Verification is done by checking that that the TLS/SSL connection has a valid
370 certificate corresponding to the host name of the connection and that the
371 certificate has been verified by a CA. Assuming you trust the CA, this will
372 protect against machine\-in\-the\-middle
373 attacks <http://en.wikipedia.org/wiki/Machine-in-the-middle_attack>.
374 .PP
375 Certificate verification requires a file or directory containing trusted CA
376 certificates.
377 .PP
378 \&\f(CWIO::Socket::SSL::default_ca()\fR is called to detect the default location of
379 your CA certificates. This also supports the environment variables
380 \&\f(CW\*(C`SSL_CERT_FILE\*(C'\fR and \f(CW\*(C`SSL_CERT_DIR\*(C'\fR, and will fail over to Mozilla::CA if no
381 certs are found.
382 .PP
383 If \f(CWIO::Socket::SSL::default_ca()\fR is not able to find usable CA certificates,
384 HTTP::Tiny will search several well\-known system\-specific default locations for
385 a CA certificate file as a last resort:
386 .IP \(bu 4
387 /etc/ssl/certs/ca\-certificates.crt
388 .IP \(bu 4
389 /etc/pki/tls/certs/ca\-bundle.crt
390 .IP \(bu 4
391 /etc/ssl/ca\-bundle.pem
392 .IP \(bu 4
393 /etc/openssl/certs/ca\-certificates.crt
394 .IP \(bu 4
395 /etc/ssl/cert.pem
396 .IP \(bu 4
397 /usr/local/share/certs/ca\-root\-nss.crt
398 .IP \(bu 4
399 /etc/pki/tls/cacert.pem
400 .IP \(bu 4
401 /etc/certs/ca\-certificates.crt
402 .PP
403 An error will be occur if \f(CW\*(C`verify_SSL\*(C'\fR is true and no CA certificate file
404 is available.
405 .PP
406 If you desire complete control over TLS/SSL connections, the \f(CW\*(C`SSL_options\*(C'\fR
407 attribute lets you provide a hash reference that will be passed through to
408 \&\f(CWIO::Socket::SSL::start_SSL()\fR, overriding any options set by HTTP::Tiny. For
409 example, to provide your own trusted CA file:
410 .PP
411 .Vb 3
412 \& SSL_options => {
413 \& SSL_ca_file => $file_path,
414 \& }
415 .Ve
416 .PP
417 The \f(CW\*(C`SSL_options\*(C'\fR attribute could also be used for such things as providing a
418 client certificate for authentication to a server or controlling the choice of
419 cipher used for the TLS/SSL connection. See IO::Socket::SSL documentation for
420 details.
421 .SH "PROXY SUPPORT"
422 .IX Header "PROXY SUPPORT"
423 HTTP::Tiny can proxy both \f(CW\*(C`http\*(C'\fR and \f(CW\*(C`https\*(C'\fR requests. Only Basic proxy
424 authorization is supported and it must be provided as part of the proxy URL:
425 \&\f(CW\*(C`http://user:[email protected]/\*(C'\fR.
426 .PP
427 HTTP::Tiny supports the following proxy environment variables:
428 .IP \(bu 4
429 http_proxy or HTTP_PROXY
430 .IP \(bu 4
431 https_proxy or HTTPS_PROXY
432 .IP \(bu 4
433 all_proxy or ALL_PROXY
434 .PP
435 If the \f(CW\*(C`REQUEST_METHOD\*(C'\fR environment variable is set, then this might be a CGI
436 process and \f(CW\*(C`HTTP_PROXY\*(C'\fR would be set from the \f(CW\*(C`Proxy:\*(C'\fR header, which is a
437 security risk. If \f(CW\*(C`REQUEST_METHOD\*(C'\fR is set, \f(CW\*(C`HTTP_PROXY\*(C'\fR (the upper case
438 variant only) is ignored, but \f(CW\*(C`CGI_HTTP_PROXY\*(C'\fR is considered instead.
439 .PP
440 Tunnelling \f(CW\*(C`https\*(C'\fR over an \f(CW\*(C`http\*(C'\fR proxy using the CONNECT method is
441 supported. If your proxy uses \f(CW\*(C`https\*(C'\fR itself, you can not tunnel \f(CW\*(C`https\*(C'\fR
442 over it.
443 .PP
444 Be warned that proxying an \f(CW\*(C`https\*(C'\fR connection opens you to the risk of a
445 man\-in\-the\-middle attack by the proxy server.
446 .PP
447 The \f(CW\*(C`no_proxy\*(C'\fR environment variable is supported in the format of a
448 comma\-separated list of domain extensions proxy should not be used for.
449 .PP
450 Proxy arguments passed to \f(CW\*(C`new\*(C'\fR will override their corresponding
451 environment variables.
452 .SH LIMITATIONS
453 .IX Header "LIMITATIONS"
454 HTTP::Tiny is \fIconditionally compliant\fR with the
455 HTTP/1.1 specifications <http://www.w3.org/Protocols/>:
456 .IP \(bu 4
457 "Message Syntax and Routing" [RFC7230]
458 .IP \(bu 4
459 "Semantics and Content" [RFC7231]
460 .IP \(bu 4
461 "Conditional Requests" [RFC7232]
462 .IP \(bu 4
463 "Range Requests" [RFC7233]
464 .IP \(bu 4
465 "Caching" [RFC7234]
466 .IP \(bu 4
467 "Authentication" [RFC7235]
468 .PP
469 It attempts to meet all "MUST" requirements of the specification, but does not
470 implement all "SHOULD" requirements. (Note: it was developed against the
471 earlier RFC 2616 specification and may not yet meet the revised RFC 7230\-7235
472 spec.) Additionally, HTTP::Tiny supports the \f(CW\*(C`PATCH\*(C'\fR method of RFC 5789.
473 .PP
474 Some particular limitations of note include:
475 .IP \(bu 4
476 HTTP::Tiny focuses on correct transport. Users are responsible for ensuring
477 that user\-defined headers and content are compliant with the HTTP/1.1
478 specification.
479 .IP \(bu 4
480 Users must ensure that URLs are properly escaped for unsafe characters and that
481 international domain names are properly encoded to ASCII. See URI::Escape,
482 URI::_punycode and Net::IDN::Encode.
483 .IP \(bu 4
484 Redirection is very strict against the specification. Redirection is only
485 automatic for response codes 301, 302, 307 and 308 if the request method is
486 \&\*(AqGET\*(Aq or \*(AqHEAD\*(Aq. Response code 303 is always converted into a \*(AqGET\*(Aq
487 redirection, as mandated by the specification. There is no automatic support
488 for status 305 ("Use proxy") redirections.
489 .IP \(bu 4
490 There is no provision for delaying a request body using an \f(CW\*(C`Expect\*(C'\fR header.
491 Unexpected \f(CW\*(C`1XX\*(C'\fR responses are silently ignored as per the specification.
492 .IP \(bu 4
493 Only \*(Aqchunked\*(Aq \f(CW\*(C`Transfer\-Encoding\*(C'\fR is supported.
494 .IP \(bu 4
495 There is no support for a Request\-URI of \*(Aq*\*(Aq for the \*(AqOPTIONS\*(Aq request.
496 .IP \(bu 4
497 Headers mentioned in the RFCs and some other, well\-known headers are
498 generated with their canonical case. Other headers are sent in the
499 case provided by the user. Except for control headers (which are sent first),
500 headers are sent in arbitrary order.
501 .PP
502 Despite the limitations listed above, HTTP::Tiny is considered
503 feature\-complete. New feature requests should be directed to
504 HTTP::Tiny::UA.
505 .SH "SEE ALSO"
506 .IX Header "SEE ALSO"
507 .IP \(bu 4
508 HTTP::Tiny::UA \- Higher level UA features for HTTP::Tiny
509 .IP \(bu 4
510 HTTP::Thin \- HTTP::Tiny wrapper with HTTP::Request/HTTP::Response compatibility
511 .IP \(bu 4
512 HTTP::Tiny::Mech \- Wrap WWW::Mechanize instance in HTTP::Tiny compatible interface
513 .IP \(bu 4
514 IO::Socket::IP \- Required for IPv6 support
515 .IP \(bu 4
516 IO::Socket::SSL \- Required for SSL support
517 .IP \(bu 4
518 LWP::UserAgent \- If HTTP::Tiny isn\*(Aqt enough for you, this is the "standard" way to do things
519 .IP \(bu 4
520 Net::SSLeay \- Required for SSL support
521 .SH SUPPORT
522 .IX Header "SUPPORT"
523 .SS "Bugs / Feature Requests"
524 .IX Subsection "Bugs / Feature Requests"
525 Please report any bugs or feature requests through the issue tracker
526 at <https://github.com/Perl\-Toolchain\-Gang/HTTP\-Tiny/issues>.
527 You will be notified automatically of any progress on your issue.
528 .SS "Source Code"
529 .IX Subsection "Source Code"
530 This is open source software. The code repository is available for
531 public review and contribution under the terms of the license.
532 .PP
533 <https://github.com/Perl\-Toolchain\-Gang/HTTP\-Tiny>
534 .PP
535 .Vb 1
536 \& git clone https://github.com/Perl\-Toolchain\-Gang/HTTP\-Tiny.git
537 .Ve
538 .SH AUTHORS
539 .IX Header "AUTHORS"
540 .IP \(bu 4
541 Christian Hansen <[email protected]>
542 .IP \(bu 4
543 David Golden <[email protected]>
544 .SH CONTRIBUTORS
545 .IX Header "CONTRIBUTORS"
546 .IP \(bu 4
547 Alan Gardner <[email protected]>
548 .IP \(bu 4
549 Alessandro Ghedini <[email protected]>
550 .IP \(bu 4
551 A. Sinan Unur <[email protected]>
552 .IP \(bu 4
553 Brad Gilbert <[email protected]>
554 .IP \(bu 4
555 brian m. carlson <[email protected]>
556 .IP \(bu 4
557 Chris Nehren <[email protected]>
558 .IP \(bu 4
559 Chris Weyl <[email protected]>
560 .IP \(bu 4
561 Claes Jakobsson <[email protected]>
562 .IP \(bu 4
563 Clinton Gormley <[email protected]>
564 .IP \(bu 4
565 Craig A. Berry <[email protected]>
566 .IP \(bu 4
567 David Golden <[email protected]>
568 .IP \(bu 4
569 David Mitchell <[email protected]>
570 .IP \(bu 4
571 Dean Pearce <[email protected]>
572 .IP \(bu 4
573 Edward Zborowski <[email protected]>
574 .IP \(bu 4
575 Felipe Gasper <[email protected]>
576 .IP \(bu 4
577 Graham Knop <[email protected]>
578 .IP \(bu 4
579 Greg Kennedy <[email protected]>
580 .IP \(bu 4
581 James E Keenan <[email protected]>
582 .IP \(bu 4
583 James Raspass <[email protected]>
584 .IP \(bu 4
585 Jeremy Mates <[email protected]>
586 .IP \(bu 4
587 Jess Robinson <castaway@desert\-island.me.uk>
588 .IP \(bu 4
589 Karen Etheridge <[email protected]>
590 .IP \(bu 4
591 Lukas Eklund <[email protected]>
592 .IP \(bu 4
593 Martin J. Evans <[email protected]>
594 .IP \(bu 4
595 Martin\-Louis Bright <[email protected]>
596 .IP \(bu 4
597 Matthew Horsfall <[email protected]>
598 .IP \(bu 4
599 Michael R. Davis <[email protected]>
600 .IP \(bu 4
601 Mike Doherty <[email protected]>
602 .IP \(bu 4
603 Nicolas Rochelemagne <[email protected]>
604 .IP \(bu 4
605 Olaf Alders <[email protected]>
606 .IP \(bu 4
607 Olivier Mengué <[email protected]>
608 .IP \(bu 4
609 Petr Písař <[email protected]>
610 .IP \(bu 4
611 sanjay\-cpu <[email protected]>
612 .IP \(bu 4
613 Serguei Trouchelle <[email protected]>
614 .IP \(bu 4
615 Shoichi Kaji <[email protected]>
616 .IP \(bu 4
617 SkyMarshal <[email protected]>
618 .IP \(bu 4
619 Sören Kornetzki <[email protected]>
620 .IP \(bu 4
621 Steve Grazzini <[email protected]>
622 .IP \(bu 4
623 Stig Palmquist <[email protected]>
624 .IP \(bu 4
625 Syohei YOSHIDA <[email protected]>
626 .IP \(bu 4
627 Tatsuhiko Miyagawa <[email protected]>
628 .IP \(bu 4
629 Tom Hukins <[email protected]>
630 .IP \(bu 4
631 Tony Cook <tony@develop\-help.com>
632 .IP \(bu 4
633 Xavier Guimard <[email protected]>
634 .SH "COPYRIGHT AND LICENSE"
635 .IX Header "COPYRIGHT AND LICENSE"
636 This software is copyright (c) 2024 by Christian Hansen.
637 .PP
638 This is free software; you can redistribute it and/or modify it under
639 the same terms as the Perl 5 programming language system itself.