Debian Codegraph @

upstream/debian-unstable/man3/HTTP::Tiny.3perl

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