README.md

We::Call

Requires metadata and offers client/server middleware to help debug HTTP calls, raise warnings for deprecations, supporting trace IDs, etc.

It aims to arm API developers and users with tools to make their calls more robust, and enforces Good Ideas™ with sane defaults whenever possible.

Goals

• Work just like Faraday out of the box
• Remove some of the guesswork that comes with HTTP service orientated architecures
• Provide sane defaults whenever possible, but ask for more information if required
• Facilitate HTTP Evolution

Usage

gem 'we-call'

# config/initializers/we-call.rb

We::Call.configure do |config|
  config.app_name = 'service-a'       # default nil (Connection class falls back to APP_NAME or Rails name)
  config.app_env = 'staging'          # default nil (Connection class back to RACK_ENV || RAILS_ENV)
  config.detect_deprecations = false  # default true
end

As this is a Faraday wrapper, the only thing that will change from normal Faraday usage is initialization.

connection = We::Call::Connection.new(host: 'https://some-service.example.com/', timeout: 2)

# or with a Faraday connection block
connection = We::Call::Connection.new(host: 'https://some-service.example.com/', timeout: 2) do |conn|
  conn.token_auth('abc123token')
  conn.headers['Foo'] = 'bar'
end

See more connection block options in the Faraday documentation.

Provide an App

An application should provide its own name in the user agent when calling other services. This is important in case this app busts a local cache, causing it to stampeding herd other service(s).

Other services need to know which server is causing the problem, so no connections are allowed through We::Call without an app being set.

# Provided at config
connection = We::Call.configure do |config|
  config.app_name = 'Service A'
end

# Provided at initialization
connection = We::Call::Connection.new(host: 'https://service-b.example.com/', app: 'Service A', timeout: 2)

Ofc services could lie about this, so do not use App Name for any sort of security. For that you need to use tokens assigned to applications. This is essentially just forcing a user agent.

Provide an Env

# Provided at config
connection = We::Call.configure do |config|
  config.app_env = 'staging'
end

# Provided at initialization
connection = We::Call::Connection.new(host: 'https://service-b.example.com/', env: 'staging', timeout: 2)

Not only is knowing the app name important, but knowing the env is necessary too. Sometimes people configure stuff wrong, and Service A (staging) will hit Service B (production) 😨.

If you are using Rack or Rails, you should not need to do this, as it'll use RACK_ENV or RAILS_ENV by default.

Timeouts

By default Faraday will let HTTP calls go on forever. In reality this is often 30 seconds for e.g: a Heroku app. Asking developers to make a choice about how long they're willing to wait on this call gives them a chance to consider an acceptable timeout.

The lower this number can be the better, as it reduces time web threads spend waiting for calls that are unlikely to respond anyway.

# Provided at initialization
connection = We::Call::Connection.new(host: 'https://service-b.example.com/', timeout: 2)

Timeouts can only be provided at initialization of a connection, as they should be different for each service. This is down to the sad reality that some internal services are more performant than others, and various third-parties will have different SLAs.

As well as timeout: num_seconds which can set the entire open/read (essentially the total response time of the server), another optional argument exists for open_timeout: numseconds. This is how long We::Call should spend waiting for a vague sign of life from the server, which by default is 1.

Middleware

Client

Retry

Automatically enabled, the retry middleware will retry the request in case of network errors. By default, the middleware will retry up to 3 times, waiting 1 second between the retries.

Disable the middleware:

We::Call.configure do |config|
  config.retry = false
end

# Provided at initialization
connection = We::Call::Connection.new(retry_options: false)

Adjust the middleware:

We::Call.configure do |config|
  config.retry_options = { interval: 0.5 }
end

# Provided at initialization
connection = We::Call::Connection.new(retry_options: { interval: 0.5 })

The gem smartly merges the options passed, so you can specify your own list of exceptions without being afraid to override the default ones:

We::Call.configure do |config|
  config.retry_options = { exceptions: [Faraday::ResourceNotFound] }
end

Check Faraday's Retry Docs for a list of available options.

DetectDeprecations

Automatically enabled, the faraday-sunset middleware will watch for the Sunset header and send warning to ActiveSupport::Deprecation if enabled, or to whatever is in ENV['rake.logger'].

Server

LogUserAgent

(Optional) Log the User Agent, which might just be browser information (merely kinda handy), or could be an app name, like the one We::Call::Connection asks you for.

config.middleware.insert_after Rails::Rack::Logger, We::Call::Middleware::Server::LogUserAgent

Easy! Check your logs for user_agent=service-name; app_name=service-name; The app_name will only show up if this was called by We::Call::Connection (as this is the only thing setting the X-App-Name header.)

Requirements

• Ruby: v2.2 - v2.5
• Faraday: v0.10 - v0.15

Note: Other versions of Faraday may work, but we can't test against all of them forever.

TODO

• Split DetectDeprecations into standalone faraday-sunset gem
• Work on sane defaults for retries and error raising

Testing

To run tests and modify locally, you'll want to bundle install in this directory.

bundle exec appraisal rspec

Development

If you want to test this gem within an application, update your Gemfile to have something like this: gem 'we-call', github: 'wework/we-call-gem', branch: 'BRANCHNAME' and set your local config: bundle config --local local.we-call path/to/we-call-gem

Simply revert the Gemfile change (updating the version as necessary!) and remove the config with bundle config --delete local.we-call.

References: Blog Post and Bundle Documentation

Contributing

Bug reports and pull requests are welcome on GitHub at wework/we-call. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.