net-http 0.3.0 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.gitignore +0 -1
- data/doc/net-http/examples.rdoc +30 -0
- data/lib/net/http/header.rb +381 -73
- data/lib/net/http/request.rb +27 -5
- data/lib/net/http/requests.rb +296 -24
- data/lib/net/http/response.rb +127 -11
- data/lib/net/http.rb +311 -295
- metadata +3 -2
data/lib/net/http.rb
CHANGED
@@ -32,110 +32,237 @@ module Net #:nodoc:
|
|
32
32
|
class HTTPHeaderSyntaxError < StandardError; end
|
33
33
|
# :startdoc:
|
34
34
|
|
35
|
-
#
|
35
|
+
# \Class \Net::HTTP provides a rich library that implements the client
|
36
|
+
# in a client-server model that uses the \HTTP request-response protocol.
|
37
|
+
# For information about \HTTP, see
|
38
|
+
#
|
39
|
+
# - {Hypertext Transfer Protocol}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol].
|
40
|
+
# - {Technical overview}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Technical_overview].
|
41
|
+
#
|
42
|
+
# Note: If you are performing only a few GET requests, consider using
|
43
|
+
# {OpenURI}[https://docs.ruby-lang.org/en/master/OpenURI.html];
|
44
|
+
# otherwise, read on.
|
45
|
+
#
|
46
|
+
# == Synopsis
|
47
|
+
#
|
48
|
+
# If you are already familiar with \HTTP, this synopsis may be helpful.
|
49
|
+
#
|
50
|
+
# {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for
|
51
|
+
# {HTTP methods}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods]:
|
52
|
+
#
|
53
|
+
# Net::HTTP.start(hostname) do |http|
|
54
|
+
# # Session started automatically before block execution.
|
55
|
+
# http.get(path_or_uri, headers = {})
|
56
|
+
# http.head(path_or_uri, headers = {})
|
57
|
+
# http.post(path_or_uri, data, headers = {}) # Can also have a block.
|
58
|
+
# http.put(path_or_uri, data, headers = {})
|
59
|
+
# http.delete(path_or_uri, headers = {Depth: 'Infinity'})
|
60
|
+
# http.options(path_or_uri, headers = {})
|
61
|
+
# http.trace(path_or_uri, headers = {})
|
62
|
+
# http.patch(path_or_uri, data, headers = {}) # Can also have a block.
|
63
|
+
# # Session finished automatically at block exit.
|
64
|
+
# end
|
36
65
|
#
|
37
|
-
# Net::HTTP
|
38
|
-
#
|
39
|
-
#
|
66
|
+
# {Session}[rdoc-ref:Net::HTTP@Sessions] with multiple requests for
|
67
|
+
# {WebDAV methods}[https://en.wikipedia.org/wiki/WebDAV#Implementation]:
|
68
|
+
#
|
69
|
+
# Net::HTTP.start(hostname) do |http|
|
70
|
+
# # Session started automatically before block execution.
|
71
|
+
# http.copy(path_or_uri, headers = {})
|
72
|
+
# http.lock(path_or_uri, body, headers = {})
|
73
|
+
# http.mkcol(path_or_uri, body = nil, headers = {})
|
74
|
+
# http.move(path_or_uri, headers = {})
|
75
|
+
# http.propfind(path_or_uri, body = nil, headers = {'Depth' => '0'})
|
76
|
+
# http.proppatch(path_or_uri, body, headers = {})
|
77
|
+
# http.unlock(path_or_uri, body, headers = {})
|
78
|
+
# # Session finished automatically at block exit.
|
79
|
+
# end
|
40
80
|
#
|
41
|
-
#
|
42
|
-
#
|
43
|
-
# Net::HTTP.
|
81
|
+
# Each of the following methods automatically starts and finishes
|
82
|
+
# a {session}[rdoc-ref:Net::HTTP@Sessions] that sends a single request:
|
44
83
|
#
|
45
|
-
#
|
84
|
+
# # Return string response body.
|
85
|
+
# Net::HTTP.get(hostname, path, port = 80)
|
86
|
+
# Net::HTTP.get(uri, headers = {}, port = 80)
|
46
87
|
#
|
47
|
-
#
|
88
|
+
# # Write string response body to $stdout.
|
89
|
+
# Net::HTTP.get_print(hostname, path_or_uri, port = 80)
|
90
|
+
# Net::HTTP.get_print(uri, headers = {}, port = 80)
|
48
91
|
#
|
49
|
-
#
|
92
|
+
# # Return response as Net::HTTPResponse object.
|
93
|
+
# Net::HTTP.get_response(hostname, path_or_uri, port = 80)
|
94
|
+
# Net::HTTP.get_response(uri, headers = {}, port = 80)
|
50
95
|
#
|
51
|
-
#
|
96
|
+
# Net::HTTP.post(uri, data, headers = {})
|
97
|
+
# Net::HTTP.post_form(uri, params)
|
52
98
|
#
|
53
|
-
#
|
99
|
+
# == About the Examples
|
54
100
|
#
|
55
|
-
#
|
56
|
-
# connections. They are not recommended if you are performing many HTTP
|
57
|
-
# requests.
|
101
|
+
# :include: doc/net-http/examples.rdoc
|
58
102
|
#
|
59
|
-
#
|
103
|
+
# == URIs
|
60
104
|
#
|
61
|
-
#
|
105
|
+
# On the internet, a URI
|
106
|
+
# ({Universal Resource Identifier}[https://en.wikipedia.org/wiki/Uniform_Resource_Identifier])
|
107
|
+
# is a string that identifies a particular resource.
|
108
|
+
# It consists of some or all of: scheme, hostname, path, query, and fragment;
|
109
|
+
# see {URI syntax}[https://en.wikipedia.org/wiki/Uniform_Resource_Identifier#Syntax].
|
62
110
|
#
|
63
|
-
#
|
111
|
+
# A Ruby {URI::Generic}[https://docs.ruby-lang.org/en/master/URI/Generic.html] object
|
112
|
+
# represents an internet URI.
|
113
|
+
# It provides, among others, methods
|
114
|
+
# +scheme+, +hostname+, +path+, +query+, and +fragment+.
|
64
115
|
#
|
65
|
-
#
|
66
|
-
# Net::HTTP.get(uri) # => String
|
116
|
+
# === Schemes
|
67
117
|
#
|
68
|
-
#
|
118
|
+
# An internet \URI has
|
119
|
+
# a {scheme}[https://en.wikipedia.org/wiki/List_of_URI_schemes].
|
69
120
|
#
|
70
|
-
#
|
71
|
-
# params = { :limit => 10, :page => 3 }
|
72
|
-
# uri.query = URI.encode_www_form(params)
|
121
|
+
# The two schemes supported in \Net::HTTP are <tt>'https'</tt> and <tt>'http'</tt>:
|
73
122
|
#
|
74
|
-
#
|
75
|
-
#
|
123
|
+
# uri.scheme # => "https"
|
124
|
+
# URI('http://example.com').scheme # => "http"
|
76
125
|
#
|
77
|
-
# ===
|
126
|
+
# === Hostnames
|
78
127
|
#
|
79
|
-
#
|
80
|
-
# res = Net::HTTP.post_form(uri, 'q' => 'ruby', 'max' => '50')
|
81
|
-
# puts res.body
|
128
|
+
# A hostname identifies a server (host) to which requests may be sent:
|
82
129
|
#
|
83
|
-
#
|
130
|
+
# hostname = uri.hostname # => "jsonplaceholder.typicode.com"
|
131
|
+
# Net::HTTP.start(hostname) do |http|
|
132
|
+
# # Some HTTP stuff.
|
133
|
+
# end
|
84
134
|
#
|
85
|
-
#
|
86
|
-
# res = Net::HTTP.post_form(uri, 'q' => ['ruby', 'perl'], 'max' => '50')
|
87
|
-
# puts res.body
|
135
|
+
# === Paths
|
88
136
|
#
|
89
|
-
#
|
137
|
+
# A host-specific path identifies a resource on the host:
|
90
138
|
#
|
91
|
-
#
|
92
|
-
#
|
93
|
-
#
|
139
|
+
# _uri = uri.dup
|
140
|
+
# _uri.path = '/todos/1'
|
141
|
+
# hostname = _uri.hostname
|
142
|
+
# path = _uri.path
|
143
|
+
# Net::HTTP.get(hostname, path)
|
94
144
|
#
|
95
|
-
#
|
145
|
+
# === Queries
|
96
146
|
#
|
97
|
-
#
|
98
|
-
# request = Net::HTTP::Get.new uri
|
147
|
+
# A host-specific query adds name/value pairs to the URI:
|
99
148
|
#
|
100
|
-
#
|
101
|
-
#
|
149
|
+
# _uri = uri.dup
|
150
|
+
# params = {userId: 1, completed: false}
|
151
|
+
# _uri.query = URI.encode_www_form(params)
|
152
|
+
# _uri # => #<URI::HTTPS https://jsonplaceholder.typicode.com?userId=1&completed=false>
|
153
|
+
# Net::HTTP.get(_uri)
|
102
154
|
#
|
103
|
-
#
|
104
|
-
# is kept open for the duration of the block. The connection will remain
|
105
|
-
# open for multiple requests in the block if the server indicates it
|
106
|
-
# supports persistent connections.
|
155
|
+
# === Fragments
|
107
156
|
#
|
108
|
-
#
|
109
|
-
#
|
110
|
-
#
|
157
|
+
# A {URI fragment}[https://en.wikipedia.org/wiki/URI_fragment] has no effect
|
158
|
+
# in \Net::HTTP;
|
159
|
+
# the same data is returned, regardless of whether a fragment is included.
|
111
160
|
#
|
112
|
-
#
|
113
|
-
# Request Classes".
|
161
|
+
# == Request Headers
|
114
162
|
#
|
115
|
-
#
|
116
|
-
#
|
117
|
-
#
|
163
|
+
# Request headers may be used to pass additional information to the host,
|
164
|
+
# similar to arguments passed in a method call;
|
165
|
+
# each header is a name/value pair.
|
118
166
|
#
|
119
|
-
#
|
167
|
+
# Each of the \Net::HTTP methods that sends a request to the host
|
168
|
+
# has optional argument +headers+,
|
169
|
+
# where the headers are expressed as a hash of field-name/value pairs:
|
120
170
|
#
|
121
|
-
#
|
122
|
-
#
|
171
|
+
# headers = {Accept: 'application/json', Connection: 'Keep-Alive'}
|
172
|
+
# Net::HTTP.get(uri, headers)
|
123
173
|
#
|
124
|
-
#
|
125
|
-
#
|
126
|
-
#
|
127
|
-
# res.to_hash['set-cookie'] # => Array
|
128
|
-
# puts "Headers: #{res.to_hash.inspect}"
|
174
|
+
# See lists of both standard request fields and common request fields at
|
175
|
+
# {Request Fields}[https://en.wikipedia.org/wiki/List_of_HTTP_header_fields#Request_fields].
|
176
|
+
# A host may also accept other custom fields.
|
129
177
|
#
|
130
|
-
#
|
131
|
-
# puts res.code # => '200'
|
132
|
-
# puts res.message # => 'OK'
|
133
|
-
# puts res.class.name # => 'HTTPOK'
|
178
|
+
# == Sessions
|
134
179
|
#
|
135
|
-
#
|
136
|
-
#
|
180
|
+
# A _session_ is a connection between a server (host) and a client that:
|
181
|
+
#
|
182
|
+
# - Is begun by instance method Net::HTTP#start.
|
183
|
+
# - May contain any number of requests.
|
184
|
+
# - Is ended by instance method Net::HTTP#finish.
|
185
|
+
#
|
186
|
+
# See example sessions at the {Synopsis}[rdoc-ref:Net::HTTP@Synopsis].
|
187
|
+
#
|
188
|
+
# === Session Using \Net::HTTP.start
|
189
|
+
#
|
190
|
+
# If you have many requests to make to a single host (and port),
|
191
|
+
# consider using singleton method Net::HTTP.start with a block;
|
192
|
+
# the method handles the session automatically by:
|
193
|
+
#
|
194
|
+
# - Calling #start before block execution.
|
195
|
+
# - Executing the block.
|
196
|
+
# - Calling #finish after block execution.
|
197
|
+
#
|
198
|
+
# In the block, you can use these instance methods,
|
199
|
+
# each of which that sends a single request:
|
200
|
+
#
|
201
|
+
# - {HTTP methods}[https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods]:
|
202
|
+
#
|
203
|
+
# - #get, #request_get: GET.
|
204
|
+
# - #head, #request_head: HEAD.
|
205
|
+
# - #post, #request_post: POST.
|
206
|
+
# - #delete: DELETE.
|
207
|
+
# - #options: OPTIONS.
|
208
|
+
# - #trace: TRACE.
|
209
|
+
# - #patch: PATCH.
|
210
|
+
#
|
211
|
+
# - {WebDAV methods}[https://en.wikipedia.org/wiki/WebDAV#Implementation]:
|
212
|
+
#
|
213
|
+
# - #copy: COPY.
|
214
|
+
# - #lock: LOCK.
|
215
|
+
# - #mkcol: MKCOL.
|
216
|
+
# - #move: MOVE.
|
217
|
+
# - #propfind: PROPFIND.
|
218
|
+
# - #proppatch: PROPPATCH.
|
219
|
+
# - #unlock: UNLOCK.
|
137
220
|
#
|
138
|
-
# ===
|
221
|
+
# === Session Using \Net::HTTP.start and \Net::HTTP.finish
|
222
|
+
#
|
223
|
+
# You can manage a session manually using methods #start and #finish:
|
224
|
+
#
|
225
|
+
# http = Net::HTTP.new(hostname)
|
226
|
+
# http.start
|
227
|
+
# http.get('/todos/1')
|
228
|
+
# http.get('/todos/2')
|
229
|
+
# http.delete('/posts/1')
|
230
|
+
# http.finish # Needed to free resources.
|
231
|
+
#
|
232
|
+
# === Single-Request Session
|
233
|
+
#
|
234
|
+
# Certain convenience methods automatically handle a session by:
|
235
|
+
#
|
236
|
+
# - Creating an \HTTP object
|
237
|
+
# - Starting a session.
|
238
|
+
# - Sending a single request.
|
239
|
+
# - Finishing the session.
|
240
|
+
# - Destroying the object.
|
241
|
+
#
|
242
|
+
# Such methods that send GET requests:
|
243
|
+
#
|
244
|
+
# - ::get: Returns the string response body.
|
245
|
+
# - ::get_print: Writes the string response body to $stdout.
|
246
|
+
# - ::get_response: Returns a Net::HTTPResponse object.
|
247
|
+
#
|
248
|
+
# Such methods that send POST requests:
|
249
|
+
#
|
250
|
+
# - ::post: Posts data to the host.
|
251
|
+
# - ::post_form: Posts form data to the host.
|
252
|
+
#
|
253
|
+
# == \HTTP Requests and Responses
|
254
|
+
#
|
255
|
+
# Many of the methods above are convenience methods,
|
256
|
+
# each of which sends a request and returns a string
|
257
|
+
# without directly using \Net::HTTPRequest and \Net::HTTPResponse objects.
|
258
|
+
#
|
259
|
+
# You can, however, directly create a request object, send the request,
|
260
|
+
# and retrieve the response object; see:
|
261
|
+
#
|
262
|
+
# - Net::HTTPRequest.
|
263
|
+
# - Net::HTTPResponse.
|
264
|
+
#
|
265
|
+
# == Following Redirection
|
139
266
|
#
|
140
267
|
# Each Net::HTTPResponse object belongs to a class for its response code.
|
141
268
|
#
|
@@ -167,56 +294,7 @@ module Net #:nodoc:
|
|
167
294
|
#
|
168
295
|
# print fetch('http://www.ruby-lang.org')
|
169
296
|
#
|
170
|
-
#
|
171
|
-
#
|
172
|
-
# A POST can be made using the Net::HTTP::Post request class. This example
|
173
|
-
# creates a URL encoded POST body:
|
174
|
-
#
|
175
|
-
# uri = URI('http://www.example.com/todo.cgi')
|
176
|
-
# req = Net::HTTP::Post.new(uri)
|
177
|
-
# req.set_form_data('from' => '2005-01-01', 'to' => '2005-03-31')
|
178
|
-
#
|
179
|
-
# res = Net::HTTP.start(uri.hostname, uri.port) do |http|
|
180
|
-
# http.request(req)
|
181
|
-
# end
|
182
|
-
#
|
183
|
-
# case res
|
184
|
-
# when Net::HTTPSuccess, Net::HTTPRedirection
|
185
|
-
# # OK
|
186
|
-
# else
|
187
|
-
# res.value
|
188
|
-
# end
|
189
|
-
#
|
190
|
-
# To send multipart/form-data use Net::HTTPHeader#set_form:
|
191
|
-
#
|
192
|
-
# req = Net::HTTP::Post.new(uri)
|
193
|
-
# req.set_form([['upload', File.open('foo.bar')]], 'multipart/form-data')
|
194
|
-
#
|
195
|
-
# Other requests that can contain a body such as PUT can be created in the
|
196
|
-
# same way using the corresponding request class (Net::HTTP::Put).
|
197
|
-
#
|
198
|
-
# === Setting Headers
|
199
|
-
#
|
200
|
-
# The following example performs a conditional GET using the
|
201
|
-
# If-Modified-Since header. If the files has not been modified since the
|
202
|
-
# time in the header a Not Modified response will be returned. See RFC 2616
|
203
|
-
# section 9.3 for further details.
|
204
|
-
#
|
205
|
-
# uri = URI('http://example.com/cached_response')
|
206
|
-
# file = File.stat 'cached_response'
|
207
|
-
#
|
208
|
-
# req = Net::HTTP::Get.new(uri)
|
209
|
-
# req['If-Modified-Since'] = file.mtime.rfc2822
|
210
|
-
#
|
211
|
-
# res = Net::HTTP.start(uri.hostname, uri.port) {|http|
|
212
|
-
# http.request(req)
|
213
|
-
# }
|
214
|
-
#
|
215
|
-
# open 'cached_response', 'w' do |io|
|
216
|
-
# io.write res.body
|
217
|
-
# end if res.is_a?(Net::HTTPSuccess)
|
218
|
-
#
|
219
|
-
# === Basic Authentication
|
297
|
+
# == Basic Authentication
|
220
298
|
#
|
221
299
|
# Basic authentication is performed according to
|
222
300
|
# [RFC2617](http://www.ietf.org/rfc/rfc2617.txt).
|
@@ -231,7 +309,7 @@ module Net #:nodoc:
|
|
231
309
|
# }
|
232
310
|
# puts res.body
|
233
311
|
#
|
234
|
-
#
|
312
|
+
# == Streaming Response Bodies
|
235
313
|
#
|
236
314
|
# By default Net::HTTP reads an entire response into memory. If you are
|
237
315
|
# handling large files or wish to implement a progress bar you can instead
|
@@ -251,7 +329,7 @@ module Net #:nodoc:
|
|
251
329
|
# end
|
252
330
|
# end
|
253
331
|
#
|
254
|
-
#
|
332
|
+
# == HTTPS
|
255
333
|
#
|
256
334
|
# HTTPS is enabled for an HTTP connection by Net::HTTP#use_ssl=.
|
257
335
|
#
|
@@ -272,7 +350,7 @@ module Net #:nodoc:
|
|
272
350
|
# In previous versions of Ruby you would need to require 'net/https' to use
|
273
351
|
# HTTPS. This is no longer true.
|
274
352
|
#
|
275
|
-
#
|
353
|
+
# == Proxies
|
276
354
|
#
|
277
355
|
# Net::HTTP will automatically create a proxy from the +http_proxy+
|
278
356
|
# environment variable if it is present. To disable use of +http_proxy+,
|
@@ -290,7 +368,7 @@ module Net #:nodoc:
|
|
290
368
|
# See Net::HTTP.new for further details and examples such as proxies that
|
291
369
|
# require a username and password.
|
292
370
|
#
|
293
|
-
#
|
371
|
+
# == Compression
|
294
372
|
#
|
295
373
|
# Net::HTTP automatically adds Accept-Encoding for compression of response
|
296
374
|
# bodies and automatically decompresses gzip and deflate responses unless a
|
@@ -298,106 +376,10 @@ module Net #:nodoc:
|
|
298
376
|
#
|
299
377
|
# Compression can be disabled through the Accept-Encoding: identity header.
|
300
378
|
#
|
301
|
-
# == HTTP Request Classes
|
302
|
-
#
|
303
|
-
# Here is the HTTP request class hierarchy.
|
304
|
-
#
|
305
|
-
# * Net::HTTPRequest
|
306
|
-
# * Net::HTTP::Get
|
307
|
-
# * Net::HTTP::Head
|
308
|
-
# * Net::HTTP::Post
|
309
|
-
# * Net::HTTP::Patch
|
310
|
-
# * Net::HTTP::Put
|
311
|
-
# * Net::HTTP::Proppatch
|
312
|
-
# * Net::HTTP::Lock
|
313
|
-
# * Net::HTTP::Unlock
|
314
|
-
# * Net::HTTP::Options
|
315
|
-
# * Net::HTTP::Propfind
|
316
|
-
# * Net::HTTP::Delete
|
317
|
-
# * Net::HTTP::Move
|
318
|
-
# * Net::HTTP::Copy
|
319
|
-
# * Net::HTTP::Mkcol
|
320
|
-
# * Net::HTTP::Trace
|
321
|
-
#
|
322
|
-
# == HTTP Response Classes
|
323
|
-
#
|
324
|
-
# Here is HTTP response class hierarchy. All classes are defined in Net
|
325
|
-
# module and are subclasses of Net::HTTPResponse.
|
326
|
-
#
|
327
|
-
# HTTPUnknownResponse:: For unhandled HTTP extensions
|
328
|
-
# HTTPInformation:: 1xx
|
329
|
-
# HTTPContinue:: 100
|
330
|
-
# HTTPSwitchProtocol:: 101
|
331
|
-
# HTTPProcessing:: 102
|
332
|
-
# HTTPEarlyHints:: 103
|
333
|
-
# HTTPSuccess:: 2xx
|
334
|
-
# HTTPOK:: 200
|
335
|
-
# HTTPCreated:: 201
|
336
|
-
# HTTPAccepted:: 202
|
337
|
-
# HTTPNonAuthoritativeInformation:: 203
|
338
|
-
# HTTPNoContent:: 204
|
339
|
-
# HTTPResetContent:: 205
|
340
|
-
# HTTPPartialContent:: 206
|
341
|
-
# HTTPMultiStatus:: 207
|
342
|
-
# HTTPAlreadyReported:: 208
|
343
|
-
# HTTPIMUsed:: 226
|
344
|
-
# HTTPRedirection:: 3xx
|
345
|
-
# HTTPMultipleChoices:: 300
|
346
|
-
# HTTPMovedPermanently:: 301
|
347
|
-
# HTTPFound:: 302
|
348
|
-
# HTTPSeeOther:: 303
|
349
|
-
# HTTPNotModified:: 304
|
350
|
-
# HTTPUseProxy:: 305
|
351
|
-
# HTTPTemporaryRedirect:: 307
|
352
|
-
# HTTPPermanentRedirect:: 308
|
353
|
-
# HTTPClientError:: 4xx
|
354
|
-
# HTTPBadRequest:: 400
|
355
|
-
# HTTPUnauthorized:: 401
|
356
|
-
# HTTPPaymentRequired:: 402
|
357
|
-
# HTTPForbidden:: 403
|
358
|
-
# HTTPNotFound:: 404
|
359
|
-
# HTTPMethodNotAllowed:: 405
|
360
|
-
# HTTPNotAcceptable:: 406
|
361
|
-
# HTTPProxyAuthenticationRequired:: 407
|
362
|
-
# HTTPRequestTimeOut:: 408
|
363
|
-
# HTTPConflict:: 409
|
364
|
-
# HTTPGone:: 410
|
365
|
-
# HTTPLengthRequired:: 411
|
366
|
-
# HTTPPreconditionFailed:: 412
|
367
|
-
# HTTPRequestEntityTooLarge:: 413
|
368
|
-
# HTTPRequestURITooLong:: 414
|
369
|
-
# HTTPUnsupportedMediaType:: 415
|
370
|
-
# HTTPRequestedRangeNotSatisfiable:: 416
|
371
|
-
# HTTPExpectationFailed:: 417
|
372
|
-
# HTTPMisdirectedRequest:: 421
|
373
|
-
# HTTPUnprocessableEntity:: 422
|
374
|
-
# HTTPLocked:: 423
|
375
|
-
# HTTPFailedDependency:: 424
|
376
|
-
# HTTPUpgradeRequired:: 426
|
377
|
-
# HTTPPreconditionRequired:: 428
|
378
|
-
# HTTPTooManyRequests:: 429
|
379
|
-
# HTTPRequestHeaderFieldsTooLarge:: 431
|
380
|
-
# HTTPUnavailableForLegalReasons:: 451
|
381
|
-
# HTTPServerError:: 5xx
|
382
|
-
# HTTPInternalServerError:: 500
|
383
|
-
# HTTPNotImplemented:: 501
|
384
|
-
# HTTPBadGateway:: 502
|
385
|
-
# HTTPServiceUnavailable:: 503
|
386
|
-
# HTTPGatewayTimeOut:: 504
|
387
|
-
# HTTPVersionNotSupported:: 505
|
388
|
-
# HTTPVariantAlsoNegotiates:: 506
|
389
|
-
# HTTPInsufficientStorage:: 507
|
390
|
-
# HTTPLoopDetected:: 508
|
391
|
-
# HTTPNotExtended:: 510
|
392
|
-
# HTTPNetworkAuthenticationRequired:: 511
|
393
|
-
#
|
394
|
-
# There is also the Net::HTTPBadResponse exception which is raised when
|
395
|
-
# there is a protocol error.
|
396
|
-
#
|
397
379
|
class HTTP < Protocol
|
398
380
|
|
399
381
|
# :stopdoc:
|
400
|
-
VERSION = "0.3.
|
382
|
+
VERSION = "0.3.1"
|
401
383
|
Revision = %q$Revision$.split[1]
|
402
384
|
HTTPVersion = '1.1'
|
403
385
|
begin
|
@@ -408,18 +390,17 @@ module Net #:nodoc:
|
|
408
390
|
end
|
409
391
|
# :startdoc:
|
410
392
|
|
411
|
-
#
|
412
|
-
# Defaults to ON in Ruby 1.8 or later.
|
393
|
+
# Returns +true+; retained for compatibility.
|
413
394
|
def HTTP.version_1_2
|
414
395
|
true
|
415
396
|
end
|
416
397
|
|
417
|
-
# Returns true
|
418
|
-
# Defaults to true.
|
398
|
+
# Returns +true+; retained for compatibility.
|
419
399
|
def HTTP.version_1_2?
|
420
400
|
true
|
421
401
|
end
|
422
402
|
|
403
|
+
# Returns +false+; retained for compatibility.
|
423
404
|
def HTTP.version_1_1? #:nodoc:
|
424
405
|
false
|
425
406
|
end
|
@@ -429,25 +410,12 @@ module Net #:nodoc:
|
|
429
410
|
alias is_version_1_2? version_1_2? #:nodoc:
|
430
411
|
end
|
431
412
|
|
413
|
+
# :call-seq:
|
414
|
+
# Net::HTTP.get_print(hostname, path, port = 80) -> nil
|
415
|
+
# Net::HTTP:get_print(uri, headers = {}, port = uri.port) -> nil
|
432
416
|
#
|
433
|
-
#
|
434
|
-
#
|
435
|
-
|
436
|
-
#
|
437
|
-
# Gets the body text from the target and outputs it to $stdout. The
|
438
|
-
# target can either be specified as
|
439
|
-
# (+uri+, +headers+), or as (+host+, +path+, +port+ = 80); so:
|
440
|
-
#
|
441
|
-
# Net::HTTP.get_print URI('http://www.example.com/index.html')
|
442
|
-
#
|
443
|
-
# or:
|
444
|
-
#
|
445
|
-
# Net::HTTP.get_print 'www.example.com', '/index.html'
|
446
|
-
#
|
447
|
-
# you can also specify request headers:
|
448
|
-
#
|
449
|
-
# Net::HTTP.get_print URI('http://www.example.com/index.html'), { 'Accept' => 'text/html' }
|
450
|
-
#
|
417
|
+
# Like Net::HTTP.get, but writes the returned body to $stdout;
|
418
|
+
# returns +nil+.
|
451
419
|
def HTTP.get_print(uri_or_host, path_or_headers = nil, port = nil)
|
452
420
|
get_response(uri_or_host, path_or_headers, port) {|res|
|
453
421
|
res.read_body do |chunk|
|
@@ -457,40 +425,43 @@ module Net #:nodoc:
|
|
457
425
|
nil
|
458
426
|
end
|
459
427
|
|
460
|
-
#
|
461
|
-
#
|
462
|
-
#
|
428
|
+
# :call-seq:
|
429
|
+
# Net::HTTP.get(hostname, path, port = 80) -> body
|
430
|
+
# Net::HTTP:get(uri, headers = {}, port = uri.port) -> body
|
463
431
|
#
|
464
|
-
#
|
432
|
+
# Sends a GET request and returns the \HTTP response body as a string.
|
465
433
|
#
|
466
|
-
#
|
434
|
+
# With string arguments +hostname+ and +path+:
|
467
435
|
#
|
468
|
-
#
|
436
|
+
# hostname = 'jsonplaceholder.typicode.com'
|
437
|
+
# path = '/todos/1'
|
438
|
+
# puts Net::HTTP.get(hostname, path)
|
469
439
|
#
|
470
|
-
#
|
440
|
+
# Output:
|
471
441
|
#
|
472
|
-
#
|
442
|
+
# {
|
443
|
+
# "userId": 1,
|
444
|
+
# "id": 1,
|
445
|
+
# "title": "delectus aut autem",
|
446
|
+
# "completed": false
|
447
|
+
# }
|
448
|
+
#
|
449
|
+
# With URI object +uri+ and optional hash argument +headers+:
|
450
|
+
#
|
451
|
+
# uri = URI('https://jsonplaceholder.typicode.com/todos/1')
|
452
|
+
# headers = {'Content-type' => 'application/json; charset=UTF-8'}
|
453
|
+
# Net::HTTP.get(uri, headers)
|
473
454
|
#
|
474
455
|
def HTTP.get(uri_or_host, path_or_headers = nil, port = nil)
|
475
456
|
get_response(uri_or_host, path_or_headers, port).body
|
476
457
|
end
|
477
458
|
|
478
|
-
#
|
479
|
-
#
|
480
|
-
#
|
481
|
-
#
|
482
|
-
# res = Net::HTTP.get_response(URI('http://www.example.com/index.html'))
|
483
|
-
# print res.body
|
484
|
-
#
|
485
|
-
# or:
|
486
|
-
#
|
487
|
-
# res = Net::HTTP.get_response('www.example.com', '/index.html')
|
488
|
-
# print res.body
|
489
|
-
#
|
490
|
-
# you can also specify request headers:
|
491
|
-
#
|
492
|
-
# Net::HTTP.get_response(URI('http://www.example.com/index.html'), { 'Accept' => 'text/html' })
|
459
|
+
# :call-seq:
|
460
|
+
# Net::HTTP.get_response(hostname, path, port = 80) -> http_response
|
461
|
+
# Net::HTTP:get_response(uri, headers = {}, port = uri.port) -> http_response
|
493
462
|
#
|
463
|
+
# Like Net::HTTP.get, but returns an Net::HTTPResponse object
|
464
|
+
# instead of the body string.
|
494
465
|
def HTTP.get_response(uri_or_host, path_or_headers = nil, port = nil, &block)
|
495
466
|
if path_or_headers && !path_or_headers.is_a?(Hash)
|
496
467
|
host = uri_or_host
|
@@ -577,35 +548,80 @@ module Net #:nodoc:
|
|
577
548
|
end
|
578
549
|
|
579
550
|
# :call-seq:
|
580
|
-
# HTTP.start(address, port, p_addr, p_port, p_user, p_pass
|
581
|
-
# HTTP.start(address, port=nil, p_addr=:ENV, p_port=nil, p_user=nil, p_pass=nil, opt
|
582
|
-
#
|
583
|
-
#
|
584
|
-
#
|
585
|
-
#
|
586
|
-
#
|
587
|
-
#
|
588
|
-
#
|
589
|
-
#
|
590
|
-
#
|
591
|
-
#
|
592
|
-
#
|
593
|
-
#
|
594
|
-
#
|
595
|
-
#
|
596
|
-
#
|
597
|
-
#
|
598
|
-
#
|
599
|
-
#
|
600
|
-
#
|
601
|
-
#
|
602
|
-
#
|
603
|
-
#
|
604
|
-
#
|
605
|
-
#
|
606
|
-
#
|
607
|
-
#
|
608
|
-
#
|
551
|
+
# HTTP.start(address, port, p_addr, p_port, p_user, p_pass) {|http| ... }
|
552
|
+
# HTTP.start(address, port=nil, p_addr=:ENV, p_port=nil, p_user=nil, p_pass=nil, opt) {|http| ... }
|
553
|
+
# Creates a new \Net::HTTP object,
|
554
|
+
# opens a TCP connection and \HTTP session.
|
555
|
+
#
|
556
|
+
# Argument +address+ is the hostname or IP address of the server.
|
557
|
+
#
|
558
|
+
# With a block given:
|
559
|
+
#
|
560
|
+
# - Passes the object to the given block,
|
561
|
+
# which may make any number of requests to the host.
|
562
|
+
# - Closes the \HTTP session on block exit.
|
563
|
+
# - Returns the block's value.
|
564
|
+
#
|
565
|
+
# Example:
|
566
|
+
#
|
567
|
+
# hostname = 'jsonplaceholder.typicode.com'
|
568
|
+
# Net::HTTP.start(hostname) do |http|
|
569
|
+
# puts http.get('/todos/1').body
|
570
|
+
# puts http.get('/todos/2').body
|
571
|
+
# end
|
572
|
+
#
|
573
|
+
# Output:
|
574
|
+
#
|
575
|
+
# {
|
576
|
+
# "userId": 1,
|
577
|
+
# "id": 1,
|
578
|
+
# "title": "delectus aut autem",
|
579
|
+
# "completed": false
|
580
|
+
# }
|
581
|
+
# {
|
582
|
+
# "userId": 1,
|
583
|
+
# "id": 2,
|
584
|
+
# "title": "quis ut nam facilis et officia qui",
|
585
|
+
# "completed": false
|
586
|
+
# }
|
587
|
+
#
|
588
|
+
# With no block given, returns the \Net::HTTP object;
|
589
|
+
# the caller should call #finish to close the session.
|
590
|
+
#
|
591
|
+
# Other arguments:
|
592
|
+
#
|
593
|
+
# - +port+: Server port number.
|
594
|
+
# - +p_addr+: Proxy address.
|
595
|
+
# - +p_port+: Proxy port.
|
596
|
+
# - +p_user+: Proxy user name.
|
597
|
+
# - +p_pass+: Proxy password.
|
598
|
+
# - +opts+: Optional options hash.
|
599
|
+
#
|
600
|
+
# The options hash +opts+ sets certain values,
|
601
|
+
# where each key is a method or accessor to be called,
|
602
|
+
# and its value is the value to be set.
|
603
|
+
#
|
604
|
+
# The keys may include:
|
605
|
+
#
|
606
|
+
# - #ca_file
|
607
|
+
# - #ca_path
|
608
|
+
# - #cert
|
609
|
+
# - #cert_store
|
610
|
+
# - #ciphers
|
611
|
+
# - #close_on_empty_response
|
612
|
+
# - +ipaddr+ (calls #ipaddr=)
|
613
|
+
# - #keep_alive_timeout
|
614
|
+
# - #key
|
615
|
+
# - #open_timeout
|
616
|
+
# - #read_timeout
|
617
|
+
# - #ssl_timeout
|
618
|
+
# - #ssl_version
|
619
|
+
# - +use_ssl+ (calls #use_ssl=)
|
620
|
+
# - #verify_callback
|
621
|
+
# - #verify_depth
|
622
|
+
# - #verify_mode
|
623
|
+
# - #write_timeout
|
624
|
+
#
|
609
625
|
def HTTP.start(address, *arg, &block) # :yield: +http+
|
610
626
|
arg.pop if opt = Hash.try_convert(arg[-1])
|
611
627
|
port, p_addr, p_port, p_user, p_pass = *arg
|