A set of modules to add common functionality to a Ruby service client
gem install px-service-client
Or, with bundler
gem 'px-service-client'Then use it:
require 'px-service-client'
class MyClient < Px::Service::Client::Base
include Px::Service::Client::Caching
include Px::Service::Client::CircuitBreaker
endThis gem includes several common features used in 500px service client libraries.
The features are:
This class provides a basic make_request(method, url, ...) method that produces an asynchronous request. The method immediately returns a Future. It works together with Multiplexer(discussed below) and uses Typhoeus as the underlying HTTP client to support asynchronicity.
Clients should subclass this class and include other features/mixins, if needed.
config do |config| config.statsd_client = Statsd.new(host, port) end
See the following section for an example of how to use make_request and Multiplexer.
This class works together with Px::Service::Client::Base sub-classes to support request parallel execution.
Example:
multi = Px::Service::Client::Multiplexer.new
multi.context do
method = :get
url = 'http://www.example.com'
req = make_request(method, url) # returns a Future
multi.do(req) # queues the request/future into hydra
end
multi.run # a blocking call, like hydra.runmulti.context encapsulates the block into a Fiber object and immediately runs (or resume, in Fiber's term) that fiber until the block explicitly gives up control. The method returns multi itself.
multi.do(request_or_future,retries) queues the request into hydra. It always returns a Future. A Typhoeus::Request will be converted into a Future in this call.
Finally, multi.run starts hydra to execute the requests in parallel. The request is made as soon as the multiplexer is started. You get the results of the request by evaluating the value of the Future.
Provides client-side response caching of service requests.
include Px::Service::Client::Caching
# Optional
config do |config|
config.cache_expiry = 30.seconds
config.cache_default_policy_group = 'general'
config.cache_client = Dalli::Client.new(...)
config.cache_logger = Logger.new(STDOUT) # or Rails.logger, for example. Can be nil.
end
# An example of a cached request
result = cache_request(url, :last_resort, refresh_probability: 1) do
req = make_request(method, url)
response = @multi.do(req)
# cache_request() expects a future that returns the result to be cached
Px::Service::Client::Future.new do
JSON.parse(response.body)
end
endcache_request expects a block that returns a Future object. The return value (usually the response body) of that future will be cached. cache_request always returns a future. By evaluating the future, i.e., via the Future.value! call, you get the result (whether cached or not).
Note: DO NOT cache the Typhoeus::Response directly (See the below code snippet), because the response object cannot be serializable to be stored in memcached. That's the reason why we see warning message: You are trying to cache a Ruby object which cannot be serialized to memcached.
# An incorrect example of using cache_request()
cache_request(url, :last_resort) do
req = make_request(method, url)
response = @multi.do(req) # DO NOT do this
end
Responses are cached in either a last-resort or first-resort manner.
last-resort means that the cached value is only used when the service client request fails (with a
ServiceError). If the service client request succeeds, there is a chance that the cache value may get refreshed. The refresh_probability is provided to let the cached value
be refreshed probabilistically (rather than on every request).
If the service client request fails and there is a ServiceError, cache_logger will record the exception message, and attempt to read the existing cache value.
first-resort means that the cached value is always used, if present. If the cached value is present but expired, the it sends the service client request and, if the request succeeds, it refreshes the cached value expiry. If the request fails, it uses the expired cached value, but the value remain expired. A retry may be needed.
This mixin overrides Px::Service::Client::Base#make_request method and implements the circuit breaker pattern.
include Px::Service::Client::CircuitBreaker
# Optional
circuit_handler do |handler|
handler.logger = Logger.new(STDOUT)
handler.failure_threshold = 5
handler.failure_timeout = 5
handler.invocation_timeout = 10
handler.excluded_exceptions += [NotConsideredFailureException]
end
# An example of a make a request with circuit breaker
req = make_request(method, url) # overrides Px::Service::Client::BaseAdds a circuit breaker to the client. make_request always returns Future
The circuit will open on any exception from the wrapped method, or if the request runs for longer than the invocation_timeout.
If the circuit is open, any future request will be get an error message wrapped in Px::Service::ServiceError.
By default, Px::Service::ServiceRequestError is excluded by the handler. That is, when the request fails with a ServiceRequestError exceptions, the same ServiceRequestError will be raised. But it does NOT increase the failure count or trip the breaker, as these exceptions indicate an error on the caller's part (e.g. an HTTP 4xx error).
Every instance of the class that includes the CircuitBreaker concern will share the same circuit state. You should therefore include Px::Service::Client::CircuitBreaker in the most-derived class that subclasses
Px::Service::Client::Base.
This module is based on (and uses) the Circuit Breaker gem by Will Sargent.
Similar to Px::Service::Client::CircuitBreaker, this mixin overrides Px::Service::Client::Base#make_request method and appends a HMAC signature in the request header.
To use this mixin:
class MyClient < Px::Service::Client::Base
include Px::Service::Client::HmacSigning
#optional
config do |config|
config.hmac_secret = 'mykey'
config.hmac_keyspan = 300
end
endNote: key and keyspan are class variables and shared among instances of the same class.
The signature is produced from the secret key, a nonce, HTTP method, url, query, body. The nonce is generated from the timestamp.
To retrieve and verify the signature:
# Make a request with signed headers
resp = make_request(method, url, query, headers, body)
signature = resp.request.options[:headers]["X-Service-Auth"]
timestamp = resp.request.options[:headers]["Timestamp"]
# Call the class method to regenerate the signature
expected_signature = MyClient.generate_signature(method, url, query, body, timestamp)
# assert signature == expected_signature def get_something(page, page_size)
response = JSON.parse(http_get("http://some/url?p=#{page}&l=#{page_size}"))
return Px::Service::Client::ListResponse(page_size, response, "items")
endWraps a deserialized response. A ListResponse implements the Ruby Enumerable module, as well
as the methods required to work with WillPaginate.
It assumes that the response resembles this form:
{
"current_page": 1,
"total_items": 100,
"total_pages": 10,
"items": [
{ /* item 1 */ },
{ /* item 2 */ },
...
]
}The name of the "items" key is given in the third argument.
The MIT License (MIT)
Copyright (c) 2014 500px, Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.