EzClient is HTTP gem wrapper for easy persistent connections and more.
Add this line to your application's Gemfile:
gem "ezclient"
url = "http://example.com"
client_options = { timeout: 10 }
client = EzClient.new(client_options) # => EzClient::Client object
request_options = { params: { a: 1 } }
request = client.request(:get, url, request_options) # => EzClient::Request object
# Performs a GET request to https://example.com/?a=1
response = request.perform # => EzClient::Response object
# Same request but will raise EzClient::ResponseStatusError in case of 4xx or 5xx response code
response = request.perform!
# Alternatively, you can just do:
response = client.perform!(:get, url, request_options) # => EzClient::Response object
Valid client options are:
api_auth
– arguments forApiAuth.sign!
(see https://github.com/mgomes/api_auth)basic_auth
– arguments for basic authentication (either a hash with:user
and:pass
keys or a two-element array)cookies
– a hash of cookies (orHTTP::CookieJar
object) for requestsheaders
– a hash of headers for requestskeep_alive
– timeout for persistent connection in secondsmax_retries
– maximum number of retries in caseretry_exceptions
option is providedon_complete
– callback called on request completionon_error
– callback called on request exceptionon_retry
– callback called on request retryretry_exceptions
– an array of exception classes to retryssl_context
– ssl context for requests (anOpenSSL::SSL::SSLContext
instance)timeout
– timeout for requests in seconds or hash like{ read: 5, write: 5, connect: 1 }
follow
– enable following redirects (true
or hash with options – e.g.{ max_hops: 1, strict: false}
)
All these options are passed to each request made by this client but can be overriden on per-request basis.
Extra per-request only options are:
body
– raw request bodyform
– hash for urlencoded bodyjson
– data for json (also addsapplication/json
content-type header)metadata
– metadata for request (passed in callbacks)params
– becomesquery
for GET andform
for other requestsquery
– hash for uri query
If you provide keep_alive
option to the client or particular request, the connection will be stored in the client and then
reused for all following requests to the same origin within specified amount of time.
Note that if you are using persistent connections, you shouldn't store your client in a variable that is accessable by different threads. See the example:
module MyApp
# Bad: multiple threads will use the same socket
def self.bad_client
@ezclient ||= EzClient.new(keep_alive: 100)
end
# Good: each thread has it's own socket
def self.good_client
Thread.current[:ezclient] ||= EzClient.new(keep_alive: 100)
end
end
Alose note that, as of now, EzClient will
automatically retry the request on any HTTP::ConnectionError
exception in this case which may possibly result in two requests
received by a server (see httprb/http#459).
You can provide on_complete
, on_error
and on_retry
callbacks like this:
on_complete = -> (request, response, metadata) { ... }
on_error = -> (request, error, metadata) { ... }
on_retry = -> (request, error, metadata) { ... }
client = EzClient.new(
on_complete: on_complete,
on_error: on_error,
on_retry: on_retry,
retry_exceptions: [StandardError],
max_retries: 2,
)
response = client.perform!(:get, url, metadata: :hello)
The arguments passed into callbacks are:
request
– anEzClient::Request
instanceresponse
– anEzClient::Response
instanceerror
– an exception instancemetadata
- themetadata
option passed into a request
request = client.request(:post, "http://example.com", json: { a: 1 }, timeout: 15)
request.verb # => "POST"
request.url # => "http://example.com"
request.body # => '{"a": 1}'
request.headers # => { "Content-Type" => "application/json; charset=UTF-8", ... }
request.elapsed_seconds # => 0.08117745001072763
response = request.perform(...)
response.body # => String
response.headers # => Hash
response.code # => Integer
response.ok? # Returns if request was 2xx status
response.redirect? # Returns if request was 3xx status
response.client_error? # Returns if request was 4xx status
response.server_error? # Returns if request was 5xx status
response.error? # Returns if request was 4xx or 5xx status
Bug reports and pull requests are welcome on GitHub at https://github.com/umbrellio/ezclient.
Released under MIT License.
Created by Yuri Smirnov.