/
UA.pm
304 lines (188 loc) · 6.93 KB
/
UA.pm
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
use strict;
use warnings;
package HTTP::Tiny::UA;
# ABSTRACT: Higher-level UA features for HTTP::Tiny
our $VERSION = '0.006';
use superclass 'HTTP::Tiny' => 0.036;
use HTTP::Tiny::UA::Response;
#pod =method new
#pod
#pod $http = HTTP::Tiny::UA->new( %attributes );
#pod
#pod This is inherited from L<HTTP::Tiny>. The only difference so far is that
#pod C<agent> will be C<HTTP-Tiny-UA/$VERSION>.
#pod
#pod =for :list
#pod * C<agent>
#pod A user-agent string (defaults to 'HTTP-Tiny-UA/$VERSION'). If C<agent> ends in a space character, the default user-agent string is appended.
#pod * C<cookie_jar>
#pod An instance of L<HTTP::CookieJar> or equivalent class that supports the C<add> and C<cookie_header> methods
#pod * C<default_headers>
#pod A hashref of default headers to apply to requests
#pod * C<local_address>
#pod The local IP address to bind to
#pod * C<max_redirect>
#pod Maximum number of redirects allowed (defaults to 5)
#pod * C<max_size>
#pod Maximum response size (only when not using a data callback). If defined,
#pod responses larger than this will return an exception.
#pod * C<proxy>
#pod URL of a proxy server to use (default is C<$ENV{http_proxy}> if set)
#pod * C<no_proxy>
#pod List of domain suffixes that should not be proxied. Must be a comma-separated string or an array reference. (default is C<$ENV{no_proxy}>)
#pod * C<timeout>
#pod Request timeout in seconds (default is 60)
#pod * C<verify_SSL>
#pod A boolean that indicates whether to validate the SSL certificate of an C<https>
#pod connection (default is false)
#pod * C<SSL_options>
#pod A hashref of C<SSL_*> options to pass through to L<IO::Socket::SSL>
#pod
#pod See L<SSL SUPPORT in HTTP::Tiny|HTTP::Tiny/SSL SUPPORT> for more on the
#pod C<verify_SSL> and C<SSL_options> attributes.
#pod
#pod =method get|head|put|post|post_form|mirror|delete
#pod
#pod These methods are inherited from L<HTTP::Tiny> and work the same, except they
#pod invoke the L<HTTP::Tiny::UA request|/request> method and return a
#pod L<HTTP::Tiny::UA::Response> object.
#pod
#pod =method request
#pod
#pod my $res = HTTP::Tiny->new->get( $url );
#pod
#pod Just like L<HTTP::Tiny::request|HTTP::Tiny/request>, but returns a
#pod L<HTTP::Tiny::UA::Response> object. All other C<get>, C<post>, etc. methods
#pod eventually invoke this one so all such methods return response objects now.
#pod
#pod =cut
sub request {
my ( $self, @args ) = @_;
my $res = $self->SUPER::request(@args);
return HTTP::Tiny::UA::Response->new($res);
}
1;
# vim: ts=4 sts=4 sw=4 et:
__END__
=pod
=encoding UTF-8
=head1 NAME
HTTP::Tiny::UA - Higher-level UA features for HTTP::Tiny
=head1 VERSION
version 0.006
=head1 SYNOPSIS
use HTTP::Tiny::UA;
my $ua = HTTP::Tiny::UA->new(
...
);
=head1 DESCRIPTION
This module extends L<HTTP::Tiny> with higher-level convenience features.
=head1 METHODS
=head2 new
$http = HTTP::Tiny::UA->new( %attributes );
This is inherited from L<HTTP::Tiny>. The only difference so far is that
C<agent> will be C<HTTP-Tiny-UA/$VERSION>.
=over 4
=item *
C<agent>
A user-agent string (defaults to 'HTTP-Tiny-UA/$VERSION'). If C<agent> ends in a space character, the default user-agent string is appended.
=item *
C<cookie_jar>
An instance of L<HTTP::CookieJar> or equivalent class that supports the C<add> and C<cookie_header> methods
=item *
C<default_headers>
A hashref of default headers to apply to requests
=item *
C<local_address>
The local IP address to bind to
=item *
C<max_redirect>
Maximum number of redirects allowed (defaults to 5)
=item *
C<max_size>
Maximum response size (only when not using a data callback). If defined,
responses larger than this will return an exception.
=item *
C<proxy>
URL of a proxy server to use (default is C<$ENV{http_proxy}> if set)
=item *
C<no_proxy>
List of domain suffixes that should not be proxied. Must be a comma-separated string or an array reference. (default is C<$ENV{no_proxy}>)
=item *
C<timeout>
Request timeout in seconds (default is 60)
=item *
C<verify_SSL>
A boolean that indicates whether to validate the SSL certificate of an C<https>
connection (default is false)
=item *
C<SSL_options>
A hashref of C<SSL_*> options to pass through to L<IO::Socket::SSL>
=back
See L<SSL SUPPORT in HTTP::Tiny|HTTP::Tiny/SSL SUPPORT> for more on the
C<verify_SSL> and C<SSL_options> attributes.
=head2 get|head|put|post|post_form|mirror|delete
These methods are inherited from L<HTTP::Tiny> and work the same, except they
invoke the L<HTTP::Tiny::UA request|/request> method and return a
L<HTTP::Tiny::UA::Response> object.
=head2 request
my $res = HTTP::Tiny->new->get( $url );
Just like L<HTTP::Tiny::request|HTTP::Tiny/request>, but returns a
L<HTTP::Tiny::UA::Response> object. All other C<get>, C<post>, etc. methods
eventually invoke this one so all such methods return response objects now.
=for Pod::Coverage BUILD
=head1 EXCEPTIONS
Exceptions from C<max_size>, C<timeout> or other error conditions will result
in a pseudo-HTTP status code of 599 and a reason of "Internal Exception". The
content field in the response will contain the text of the exception.
=head1 CONTRIBUTING
Unlike L<HTTP::Tiny>, this module is open to additional features. Please
discuss new ideas on the bug tracker for feedback before implementing.
While this module is not strictly "Tiny", here are some general guidelines:
=over 4
=item *
The goal for this module is B<not> feature/API equivalence with L<LWP::UserAgent>
=item *
Core module dependencies and "Tiny"-ish module dependencies are OK
=item *
Other CPAN modules should be used sparingly and only for good reasons
=item *
Any XS dependencies must be optional
=back
=head1 SEE ALSO
=over 4
=item *
L<HTTP::Tiny> — the underlying client
=item *
L<HTTP::Thin> — another HTTP::Tiny extension that uses L<HTTP::Message> objects
=item *
L<LWP::UserAgent> — when you outgrow HTTP::Tiny, use this
=back
=for :stopwords cpan testmatrix url annocpan anno bugtracker rt cpants kwalitee diff irc mailto metadata placeholders metacpan
=head1 SUPPORT
=head2 Bugs / Feature Requests
Please report any bugs or feature requests through the issue tracker
at L<https://github.com/dagolden/HTTP-Tiny-UA/issues>.
You will be notified automatically of any progress on your issue.
=head2 Source Code
This is open source software. The code repository is available for
public review and contribution under the terms of the license.
L<https://github.com/dagolden/HTTP-Tiny-UA>
git clone https://github.com/dagolden/HTTP-Tiny-UA.git
=head1 AUTHOR
David Golden <dagolden@cpan.org>
=head1 CONTRIBUTORS
=for stopwords Felipe Gasper Graham Ollis Michael G. Schwern
=over 4
=item *
Felipe Gasper <felipe@felipegasper.com>
=item *
Graham Ollis <perl@wdlabs.com>
=item *
Michael G. Schwern <schwern@pobox.com>
=back
=head1 COPYRIGHT AND LICENSE
This software is Copyright (c) 2013 by David Golden.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
=cut