1HTTP::Tiny(3) User Contributed Perl Documentation HTTP::Tiny(3)
2
6 HTTP::Tiny - A small, simple, correct HTTP/1.1 client
7
9 version 0.033
10
12 use HTTP::Tiny;
13 my $response = HTTP::Tiny->new->get('http://example.com/');
15 die "Failed!\n" unless $response->{success};
17 print "$response->{status} $response->{reason}\n";
19 while (my ($k, $v) = each %{$response->{headers}}) {
21 for (ref $v eq 'ARRAY' ? @$v : $v) {
22 print "$k: $_\n";
23 }
24 }
25 print $response->{content} if length $response->{content};
27
29 This is a very simple HTTP/1.1 client, designed for doing simple GET
30 requests without the overhead of a large framework like LWP::UserAgent.
31 It is more correct and more complete than HTTP::Lite. It supports
33 proxies (currently only non-authenticating ones) and redirection. It
34 also correctly resumes after EINTR.
35
37 new
38 $http = HTTP::Tiny->new( %attributes );
39 This constructor returns a new HTTP::Tiny object. Valid attributes
41 include:
42 · "agent"
44 A user-agent string (defaults to 'HTTP-Tiny/$VERSION'). If "agent"
46 ends in a space character, the default user-agent string is
47 appended.
48 · "cookie_jar"
50 An instance of HTTP::CookieJar or equivalent class that supports
52 the "add" and "cookie_header" methods
53 · "default_headers"
55 A hashref of default headers to apply to requests
57 · "local_address"
59 The local IP address to bind to
61 · "max_redirect"
63 Maximum number of redirects allowed (defaults to 5)
65 · "max_size"
67 Maximum response size (only when not using a data callback). If
69 defined, responses larger than this will return an exception.
70 · "proxy"
72 URL of a proxy server to use (default is $ENV{http_proxy} if set)
74 · "no_proxy"
76 List of domain suffixes that should not be proxied. Must be a
78 comma-separated string or an array reference. (default is
79 $ENV{no_proxy})
80 · "timeout"
82 Request timeout in seconds (default is 60)
84 · "verify_SSL"
86 A boolean that indicates whether to validate the SSL certificate of
88 an "https" connection (default is false)
89 · "SSL_options"
91 A hashref of "SSL_*" options to pass through to IO::Socket::SSL
93 Exceptions from "max_size", "timeout" or other errors will result in a
95 pseudo-HTTP status code of 599 and a reason of "Internal Exception".
96 The content field in the response will contain the text of the
97 exception.
98 See "SSL SUPPORT" for more on the "verify_SSL" and "SSL_options"
100 attributes.
101 get|head|put|post|delete
103 $response = $http->get($url);
104 $response = $http->get($url, \%options);
105 $response = $http->head($url);
106 These methods are shorthand for calling "request()" for the given
108 method. The URL must have unsafe characters escaped and international
109 domain names encoded. See "request()" for valid options and a
110 description of the response.
111 The "success" field of the response will be true if the status code is
113 2XX.
114 post_form
116 $response = $http->post_form($url, $form_data);
117 $response = $http->post_form($url, $form_data, \%options);
118 This method executes a "POST" request and sends the key/value pairs
120 from a form data hash or array reference to the given URL with a
121 "content-type" of "application/x-www-form-urlencoded". See
122 documentation for the "www_form_urlencode" method for details on the
123 encoding.
124 The URL must have unsafe characters escaped and international domain
126 names encoded. See "request()" for valid options and a description of
127 the response. Any "content-type" header or content in the options
128 hashref will be ignored.
129 The "success" field of the response will be true if the status code is
131 2XX.
132 mirror
134 $response = $http->mirror($url, $file, \%options)
135 if ( $response->{success} ) {
136 print "$file is up to date\n";
137 }
138 Executes a "GET" request for the URL and saves the response body to the
140 file name provided. The URL must have unsafe characters escaped and
141 international domain names encoded. If the file already exists, the
142 request will include an "If-Modified-Since" header with the
143 modification timestamp of the file. You may specify a different
144 "If-Modified-Since" header yourself in the "$options->{headers}" hash.
145 The "success" field of the response will be true if the status code is
147 2XX or if the status code is 304 (unmodified).
148 If the file was modified and the server response includes a properly
150 formatted "Last-Modified" header, the file modification time will be
151 updated accordingly.
152 request
154 $response = $http->request($method, $url);
155 $response = $http->request($method, $url, \%options);
156 Executes an HTTP request of the given method type ('GET', 'HEAD',
158 'POST', 'PUT', etc.) on the given URL. The URL must have unsafe
159 characters escaped and international domain names encoded. A hashref
160 of options may be appended to modify the request.
161 Valid options are:
163 · "headers"
165 A hashref containing headers to include with the request. If the
167 value for a header is an array reference, the header will be output
168 multiple times with each value in the array. These headers over-
169 write any default headers.
170 · "content"
172 A scalar to include as the body of the request OR a code reference
174 that will be called iteratively to produce the body of the request
175 · "trailer_callback"
177 A code reference that will be called if it exists to provide a
179 hashref of trailing headers (only used with chunked transfer-
180 encoding)
181 · "data_callback"
183 A code reference that will be called for each chunks of the
185 response body received.
186 If the "content" option is a code reference, it will be called
188 iteratively to provide the content body of the request. It should
189 return the empty string or undef when the iterator is exhausted.
190 If the "content" option is the empty string, no "content-type" or
192 "content-length" headers will be generated.
193 If the "data_callback" option is provided, it will be called
195 iteratively until the entire response body is received. The first
196 argument will be a string containing a chunk of the response body, the
197 second argument will be the in-progress response hash reference, as
198 described below. (This allows customizing the action of the callback
199 based on the "status" or "headers" received prior to the content body.)
200 The "request" method returns a hashref containing the response. The
202 hashref will have the following keys:
203 · "success"
205 Boolean indicating whether the operation returned a 2XX status code
207 · "url"
209 URL that provided the response. This is the URL of the request
211 unless there were redirections, in which case it is the last URL
212 queried in a redirection chain
213 · "status"
215 The HTTP status code of the response
217 · "reason"
219 The response phrase returned by the server
221 · "content"
223 The body of the response. If the response does not have any
225 content or if a data callback is provided to consume the response
226 body, this will be the empty string
227 · "headers"
229 A hashref of header fields. All header field names will be
231 normalized to be lower case. If a header is repeated, the value
232 will be an arrayref; it will otherwise be a scalar string
233 containing the value
234 On an exception during the execution of the request, the "status" field
236 will contain 599, and the "content" field will contain the text of the
237 exception.
238 www_form_urlencode
240 $params = $http->www_form_urlencode( $data );
241 $response = $http->get("http://example.com/query?$params");
242 This method converts the key/value pairs from a data hash or array
244 reference into a "x-www-form-urlencoded" string. The keys and values
245 from the data reference will be UTF-8 encoded and escaped per RFC 3986.
246 If a value is an array reference, the key will be repeated with each of
247 the values of the array reference. The key/value pairs in the
248 resulting string will be sorted by key and value.
249
251 Direct "https" connections are supported only if IO::Socket::SSL 1.56
252 or greater and Net::SSLeay 1.49 or greater are installed. An exception
253 will be thrown if a new enough versions of these modules not installed
254 or if the SSL encryption fails. There is no support for "https"
255 connections via proxy (i.e. RFC 2817).
256 SSL provides two distinct capabilities:
258 · Encrypted communication channel
260 · Verification of server identity
262 By default, HTTP::Tiny does not verify server identity.
264 Server identity verification is controversial and potentially tricky
266 because it depends on a (usually paid) third-party Certificate
267 Authority (CA) trust model to validate a certificate as legitimate.
268 This discriminates against servers with self-signed certificates or
269 certificates signed by free, community-driven CA's such as CAcert.org
270 <http://cacert.org>.
271 By default, HTTP::Tiny does not make any assumptions about your trust
273 model, threat level or risk tolerance. It just aims to give you an
274 encrypted channel when you need one.
275 Setting the "verify_SSL" attribute to a true value will make HTTP::Tiny
277 verify that an SSL connection has a valid SSL certificate corresponding
278 to the host name of the connection and that the SSL certificate has
279 been verified by a CA. Assuming you trust the CA, this will protect
280 against a man-in-the-middle attack <http://en.wikipedia.org/wiki/Man-
281 in-the-middle_attack>. If you are concerned about security, you should
282 enable this option.
283 Certificate verification requires a file containing trusted CA
285 certificates. If the Mozilla::CA module is installed, HTTP::Tiny will
286 use the CA file included with it as a source of trusted CA's. (This
287 means you trust Mozilla, the author of Mozilla::CA, the CPAN mirror
288 where you got Mozilla::CA, the toolchain used to install it, and your
289 operating system security, right?)
290 If that module is not available, then HTTP::Tiny will search several
292 system-specific default locations for a CA certificate file:
293 · /etc/ssl/certs/ca-certificates.crt
295 · /etc/pki/tls/certs/ca-bundle.crt
297 · /etc/ssl/ca-bundle.pem
299 An exception will be raised if "verify_SSL" is true and no CA
301 certificate file is available.
302 If you desire complete control over SSL connections, the "SSL_options"
304 attribute lets you provide a hash reference that will be passed through
305 to "IO::Socket::SSL::start_SSL()", overriding any options set by
306 HTTP::Tiny. For example, to provide your own trusted CA file:
307 SSL_options => {
309 SSL_ca_file => $file_path,
310 }
311 The "SSL_options" attribute could also be used for such things as
313 providing a client certificate for authentication to a server or
314 controlling the choice of cipher used for the SSL connection. See
315 IO::Socket::SSL documentation for details.
316
318 HTTP::Tiny is conditionally compliant with the HTTP/1.1 specification
319 <http://www.w3.org/Protocols/rfc2616/rfc2616.html>. It attempts to
320 meet all "MUST" requirements of the specification, but does not
321 implement all "SHOULD" requirements.
322 Some particular limitations of note include:
324 · HTTP::Tiny focuses on correct transport. Users are responsible for
326 ensuring that user-defined headers and content are compliant with
327 the HTTP/1.1 specification.
328 · Users must ensure that URLs are properly escaped for unsafe
330 characters and that international domain names are properly encoded
331 to ASCII. See URI::Escape, URI::_punycode and Net::IDN::Encode.
332 · Redirection is very strict against the specification. Redirection
334 is only automatic for response codes 301, 302 and 307 if the
335 request method is 'GET' or 'HEAD'. Response code 303 is always
336 converted into a 'GET' redirection, as mandated by the
337 specification. There is no automatic support for status 305 ("Use
338 proxy") redirections.
339 · Persistent connections are not supported. The "Connection" header
341 will always be set to "close".
342 · Cookie support requires HTTP::CookieJar or an equivalent class.
344 · Only the "http_proxy" environment variable is supported in the
346 format "http://HOST:PORT/". If a "proxy" argument is passed to
347 "new" (including undef), then the "http_proxy" environment variable
348 is ignored.
349 · "no_proxy" environment variable is supported in the format comma-
351 separated list of domain extensions proxy should not be used for.
352 If a "no_proxy" argument is passed to "new", then the "no_proxy"
353 environment variable is ignored.
354 · There is no provision for delaying a request body using an "Expect"
356 header. Unexpected "1XX" responses are silently ignored as per the
357 specification.
358 · Only 'chunked' "Transfer-Encoding" is supported.
360 · There is no support for a Request-URI of '*' for the 'OPTIONS'
362 request.
363 · There is no support for IPv6 of any kind.
365
367 · HTTP::Thin - HTTP::Tiny wrapper with HTTP::Request/HTTP::Response
368 compatibility
369 · HTTP::Tiny::Mech - Wrap WWW::Mechanize instance in HTTP::Tiny
371 compatible interface
372 · IO::Socket::SSL - Required for SSL support
374 · LWP::UserAgent - If HTTP::Tiny isn't enough for you, this is the
376 "standard" way to do things
377 · Mozilla::CA - Required if you want to validate SSL certificates
379 · Net::SSLeay - Required for SSL support
381
383 Bugs / Feature Requests
384 Please report any bugs or feature requests through the issue tracker at
385 <https://github.com/chansen/p5-http-tiny/issues>. You will be notified
386 automatically of any progress on your issue.
387 Source Code
389 This is open source software. The code repository is available for
390 public review and contribution under the terms of the license.
391 <https://github.com/chansen/p5-http-tiny>
393 git clone git://github.com/chansen/p5-http-tiny.git
395
397 · Christian Hansen <chansen@cpan.org>
398 · David Golden <dagolden@cpan.org>
400
402 · Alan Gardner <gardner@pythian.com>
403 · Alessandro Ghedini <al3xbio@gmail.com>
405 · Brad Gilbert <bgills@cpan.org>
407 · Chris Nehren <apeiron@cpan.org>
409 · Chris Weyl <cweyl@alumni.drew.edu>
411 · Claes Jakobsson <claes@surfar.nu>
413 · Craig Berry <cberry@cpan.org>
415 · David Mitchell <davem@iabyn.com>
417 · Edward Zborowski <ed@rubensteintech.com>
419 · Jess Robinson <castaway@desert-island.me.uk>
421 · Lukas Eklund <leklund@gmail.com>
423 · Martin-Louis Bright <mlbright@gmail.com>
425 · Mike Doherty <doherty@cpan.org>
427 · Serguei Trouchelle <stro@cpan.org>
429 · Syohei YOSHIDA <syohex@gmail.com>
431 · Tony Cook <tony@develop-help.com>
433
435 This software is copyright (c) 2013 by Christian Hansen.
436 This is free software; you can redistribute it and/or modify it under
438 the same terms as the Perl 5 programming language system itself.
439perl v5.16.3 2014-06-09 HTTP::Tiny(3)