Class: HTTP::Client::Request

Inherits:
Object
  • Object
show all
Defined in:
lib/http/client.rb

Constant Summary collapse

VALID_PARAMETERS = 
%w(headers files query body auth timeout open_timeout ssl_timeout read_timeout max_redirects ssl_verify jar)
DEFAULT_HEADERS = 
{'User-Agent' => 'HTTP Client API/1.0'}
REDIRECT_WITH_GET = 
[301, 302, 303]
REDIRECT_WITH_ORIGINAL = 
[307, 308]
VALID_VERBS = 
[GET, HEAD, PUT, POST, DELETE, OPTIONS, TRACE]
VALID_SSL_VERIFICATIONS = 
[SSL_VERIFY_NONE, SSL_VERIFY_PEER]
VALID_REDIRECT_CODES = 
REDIRECT_WITH_GET + REDIRECT_WITH_ORIGINAL

Instance Method Summary collapse

Constructor Details

#initialize(verb, uri, args = {}) ⇒ HTTP::Client::Request

Create a new HTTP Client Request.

Examples:

Retrieve a page using GET.

request  = HTTP::Client::Request.new(:get, "http://www.example.org/", query: {q: "search something"})
response = request.execute

Handle redirects.

request  = HTTP::Client::Request.new(:get, "http://www.example.org/", max_redirects: 3)
response = request.execute

Perform request and return result in one go.

response = HTTP::Client.get("http://www.example.org/", max_redirects: 3)

Upload a few files in a POST request.

request  = HTTP::Client::Request.new(
  :post, "http://www.example.org/",
  files: {"cats" => "cats.jpg", "dogs" => "dogs.jpg"},
  query: {title: "cute pics"}
)
response = request.execute

Pass in an external cookie jar.

jar  = HTTP::CookieJar.new
jar.load("mycookies.cky")
response = HTTP::Client.get("http://www.example.org/", jar: jar)

Parameters:

  • verb (Symbol) —

    HTTP verb, one of :get, :head, :put, :post, :delete, :options, :trace.

  • uri (String or URI) —

    Remote URI.

  • args (Hash) (defaults to: {}) —

    Options, see below.

Options Hash (args):

  • headers (Hash) —

    Net::HTTP headers, in key-value pairs.

  • query (Hash) —

    Net::HTTP query-string in key-value pairs.

  • files (Hash) —

    Multi-part file uploads, in key-value pairs of name & path or name & File object.

  • body (String) —

    Request body.

  • auth (Hash) —

    Basic-Auth hash. Requires :username and :password.

  • timeout (Integer) —

    Fixed timeout for connection, read and ssl handshake in seconds.

  • open_timeout (Integer) —

    Connection timeout in seconds.

  • read_timeout (Integer) —

    Read timeout in seconds.

  • ssl_timeout (Integer) —

    SSL handshake timeout in seconds.

  • max_redirects (Integer) —

    Max redirect follow, default: 0

  • ssl_verify (Integer) —

    OpenSSL verification, SSL_VERIFY_PEER (default) or SSL_VERIFY_NONE.

  • jar (HTTP::CookieJar) —

    Optional cookie jar to use. Relies on HTTP::CookieJar from http-cookie gem.



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
 
# File 'lib/http/client.rb', line 84

def initialize verb, uri, args = {}
  args.each do |k, v|
    raise Error::Argument, "unknown argument #{k}" unless VALID_PARAMETERS.include?(k.to_s)
  end

  uri       = parse_uri!(uri)
  @delegate = create_request_delegate(verb, uri, args)

  if body = args[:body]
    raise Error::Argument, "#{verb} cannot have body" unless @delegate.class.const_get(:REQUEST_HAS_BODY)
    @delegate.body = body
  end

  # if auth is passed as arguments.
  if auth = args[:auth]
    @delegate.basic_auth(auth.fetch(:username), auth.fetch(:password))
  end

  # if auth is passed in uri.
  if uri.user && uri.password
    @delegate.basic_auth(uri.user, uri.password)
  end

  @open_timeout = HTTP::Client.open_timeout
  @read_timeout = HTTP::Client.read_timeout
  @ssl_timeout  = HTTP::Client.ssl_timeout

  # generic timeout
  if timeout = args[:timeout]
    @open_timeout = timeout
    @read_timeout = timeout
    @ssl_timeout  = timeout
  end

  # overrides
  @open_timeout = args[:open_timeout] if args[:open_timeout]
  @read_timeout = args[:read_timeout] if args[:read_timeout]
  @ssl_timeout  = args[:ssl_timeout]  if args[:ssl_timeout]

  @max_redirects = args.fetch(:max_redirects, 0)
  @ssl_verify    = args.fetch(:ssl_verify, SSL_VERIFY_PEER)
  @jar           = args.fetch(:jar, HTTP::CookieJar.new)
end

Instance Method Details

#execute ⇒ HTTP::Client::Response

Executes a request.

Returns:



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
 
# File 'lib/http/client.rb', line 132

def execute
  last_effective_uri = uri

  cookie = HTTP::Cookie.cookie_value(@jar.cookies(uri))
  if cookie && !cookie.empty?
    @delegate.add_field('Cookie', cookie)
  end

  response = request!(uri, @delegate)
  @jar.parse(response['set-cookie'].to_s, uri)

  redirects = 0
  while redirects < @max_redirects && VALID_REDIRECT_CODES.include?(response.code.to_i)
    redirects         += 1
    last_effective_uri = parse_uri! response['location']
    redirect_delegate  = redirect_to(last_effective_uri, response.code.to_i)

    cookie = HTTP::Cookie.cookie_value(@jar.cookies(last_effective_uri))
    if cookie && !cookie.empty?
      redirect_delegate.add_field('Cookie', cookie)
    end

    response = request!(last_effective_uri, redirect_delegate)
    @jar.parse(response['set-cookie'].to_s, last_effective_uri)
  end

  Response.new(response, last_effective_uri)
end