README.md
1# NAME
2
3Net::HTTP - Low-level HTTP connection (client)
4
5# VERSION
6
7version 6.21
8
9# SYNOPSIS
10
11 use Net::HTTP;
12 my $s = Net::HTTP->new(Host => "www.perl.com") || die $@;
13 $s->write_request(GET => "/", 'User-Agent' => "Mozilla/5.0");
14 my($code, $mess, %h) = $s->read_response_headers;
15
16 while (1) {
17 my $buf;
18 my $n = $s->read_entity_body($buf, 1024);
19 die "read failed: $!" unless defined $n;
20 last unless $n;
21 print $buf;
22 }
23
24# DESCRIPTION
25
26The `Net::HTTP` class is a low-level HTTP client. An instance of the
27`Net::HTTP` class represents a connection to an HTTP server. The
28HTTP protocol is described in RFC 2616. The `Net::HTTP` class
29supports `HTTP/1.0` and `HTTP/1.1`.
30
31`Net::HTTP` is a sub-class of one of `IO::Socket::IP` (IPv6+IPv4),
32`IO::Socket::INET6` (IPv6+IPv4), or `IO::Socket::INET` (IPv4 only).
33You can mix the methods described below with reading and writing from the
34socket directly. This is not necessary a good idea, unless you know what
35you are doing.
36
37The following methods are provided (in addition to those of
38`IO::Socket::INET`):
39
40- $s = Net::HTTP->new( %options )
41
42 The `Net::HTTP` constructor method takes the same options as
43 `IO::Socket::INET`'s as well as these:
44
45 Host: Initial host attribute value
46 KeepAlive: Initial keep_alive attribute value
47 SendTE: Initial send_te attribute_value
48 HTTPVersion: Initial http_version attribute value
49 PeerHTTPVersion: Initial peer_http_version attribute value
50 MaxLineLength: Initial max_line_length attribute value
51 MaxHeaderLines: Initial max_header_lines attribute value
52
53 The `Host` option is also the default for `IO::Socket::INET`'s
54 `PeerAddr`. The `PeerPort` defaults to 80 if not provided.
55 The `PeerPort` specification can also be embedded in the `PeerAddr`
56 by preceding it with a ":", and closing the IPv6 address on brackets "\[\]" if
57 necessary: "192.0.2.1:80","\[2001:db8::1\]:80","any.example.com:80".
58
59 The `Listen` option provided by `IO::Socket::INET`'s constructor
60 method is not allowed.
61
62 If unable to connect to the given HTTP server then the constructor
63 returns `undef` and $@ contains the reason. After a successful
64 connect, a `Net:HTTP` object is returned.
65
66- $s->host
67
68 Get/set the default value of the `Host` header to send. The $host
69 must not be set to an empty string (or `undef`) for HTTP/1.1.
70
71- $s->keep\_alive
72
73 Get/set the _keep-alive_ value. If this value is TRUE then the
74 request will be sent with headers indicating that the server should try
75 to keep the connection open so that multiple requests can be sent.
76
77 The actual headers set will depend on the value of the `http_version`
78 and `peer_http_version` attributes.
79
80- $s->send\_te
81
82 Get/set the a value indicating if the request will be sent with a "TE"
83 header to indicate the transfer encodings that the server can choose to
84 use. The list of encodings announced as accepted by this client depends
85 on availability of the following modules: `Compress::Raw::Zlib` for
86 _deflate_, and `IO::Compress::Gunzip` for _gzip_.
87
88- $s->http\_version
89
90 Get/set the HTTP version number that this client should announce.
91 This value can only be set to "1.0" or "1.1". The default is "1.1".
92
93- $s->peer\_http\_version
94
95 Get/set the protocol version number of our peer. This value will
96 initially be "1.0", but will be updated by a successful
97 read\_response\_headers() method call.
98
99- $s->max\_line\_length
100
101 Get/set a limit on the length of response line and response header
102 lines. The default is 8192. A value of 0 means no limit.
103
104- $s->max\_header\_length
105
106 Get/set a limit on the number of header lines that a response can
107 have. The default is 128. A value of 0 means no limit.
108
109- $s->format\_request($method, $uri, %headers, \[$content\])
110
111 Format a request message and return it as a string. If the headers do
112 not include a `Host` header, then a header is inserted with the value
113 of the `host` attribute. Headers like `Connection` and
114 `Keep-Alive` might also be added depending on the status of the
115 `keep_alive` attribute.
116
117 If $content is given (and it is non-empty), then a `Content-Length`
118 header is automatically added unless it was already present.
119
120- $s->write\_request($method, $uri, %headers, \[$content\])
121
122 Format and send a request message. Arguments are the same as for
123 format\_request(). Returns true if successful.
124
125- $s->format\_chunk( $data )
126
127 Returns the string to be written for the given chunk of data.
128
129- $s->write\_chunk($data)
130
131 Will write a new chunk of request entity body data. This method
132 should only be used if the `Transfer-Encoding` header with a value of
133 `chunked` was sent in the request. Note, writing zero-length data is
134 a no-op. Use the write\_chunk\_eof() method to signal end of entity
135 body data.
136
137 Returns true if successful.
138
139- $s->format\_chunk\_eof( %trailers )
140
141 Returns the string to be written for signaling EOF when a
142 `Transfer-Encoding` of `chunked` is used.
143
144- $s->write\_chunk\_eof( %trailers )
145
146 Will write eof marker for chunked data and optional trailers. Note
147 that trailers should not really be used unless is was signaled
148 with a `Trailer` header.
149
150 Returns true if successful.
151
152- ($code, $mess, %headers) = $s->read\_response\_headers( %opts )
153
154 Read response headers from server and return it. The $code is the 3
155 digit HTTP status code (see [HTTP::Status](https://metacpan.org/pod/HTTP%3A%3AStatus)) and $mess is the textual
156 message that came with it. Headers are then returned as key/value
157 pairs. Since key letter casing is not normalized and the same key can
158 even occur multiple times, assigning these values directly to a hash
159 is not wise. Only the $code is returned if this method is called in
160 scalar context.
161
162 As a side effect this method updates the 'peer\_http\_version'
163 attribute.
164
165 Options might be passed in as key/value pairs. There are currently
166 only two options supported; `laxed` and `junk_out`.
167
168 The `laxed` option will make read\_response\_headers() more forgiving
169 towards servers that have not learned how to speak HTTP properly. The
170 `laxed` option is a boolean flag, and is enabled by passing in a TRUE
171 value. The `junk_out` option can be used to capture bad header lines
172 when `laxed` is enabled. The value should be an array reference.
173 Bad header lines will be pushed onto the array.
174
175 The `laxed` option must be specified in order to communicate with
176 pre-HTTP/1.0 servers that don't describe the response outcome or the
177 data they send back with a header block. For these servers
178 peer\_http\_version is set to "0.9" and this method returns (200,
179 "Assumed OK").
180
181 The method will raise an exception (die) if the server does not speak
182 proper HTTP or if the `max_line_length` or `max_header_length`
183 limits are reached. If the `laxed` option is turned on and
184 `max_line_length` and `max_header_length` checks are turned off,
185 then no exception will be raised and this method will always
186 return a response code.
187
188- $n = $s->read\_entity\_body($buf, $size);
189
190 Reads chunks of the entity body content. Basically the same interface
191 as for read() and sysread(), but the buffer offset argument is not
192 supported yet. This method should only be called after a successful
193 read\_response\_headers() call.
194
195 The return value will be `undef` on read errors, 0 on EOF, -1 if no data
196 could be returned this time, otherwise the number of bytes assigned
197 to $buf. The $buf is set to "" when the return value is -1.
198
199 You normally want to retry this call if this function returns either
200 \-1 or `undef` with `$!` as EINTR or EAGAIN (see [Errno](https://metacpan.org/pod/Errno)). EINTR
201 can happen if the application catches signals and EAGAIN can happen if
202 you made the socket non-blocking.
203
204 This method will raise exceptions (die) if the server does not speak
205 proper HTTP. This can only happen when reading chunked data.
206
207- %headers = $s->get\_trailers
208
209 After read\_entity\_body() has returned 0 to indicate end of the entity
210 body, you might call this method to pick up any trailers.
211
212- $s->\_rbuf
213
214 Get/set the read buffer content. The read\_response\_headers() and
215 read\_entity\_body() methods use an internal buffer which they will look
216 for data before they actually sysread more from the socket itself. If
217 they read too much, the remaining data will be left in this buffer.
218
219- $s->\_rbuf\_length
220
221 Returns the number of bytes in the read buffer. This should always be
222 the same as:
223
224 length($s->_rbuf)
225
226 but might be more efficient.
227
228# SUBCLASSING
229
230The read\_response\_headers() and read\_entity\_body() will invoke the
231sysread() method when they need more data. Subclasses might want to
232override this method to control how reading takes place.
233
234The object itself is a glob. Subclasses should avoid using hash key
235names prefixed with `http_` and `io_`.
236
237# SEE ALSO
238
239[LWP](https://metacpan.org/pod/LWP), [IO::Socket::INET](https://metacpan.org/pod/IO%3A%3ASocket%3A%3AINET), [Net::HTTP::NB](https://metacpan.org/pod/Net%3A%3AHTTP%3A%3ANB)
240
241# AUTHOR
242
243Gisle Aas <gisle@activestate.com>
244
245# COPYRIGHT AND LICENSE
246
247This software is copyright (c) 2001-2017 by Gisle Aas.
248
249This is free software; you can redistribute it and/or modify it under
250the same terms as the Perl 5 programming language system itself.
251