Faraday::Conductivity

Extra Faraday Middleware! Geared towards a service oriented architecture.

These middlewares are currently included:

  • user_agent, adds a dynamic User-Agent header to the request, so you know which server and process the request is coming from.
  • extended_logging, logs all the information of the request.
  • request_id, passes along the X-Request-Id header to track API request back to the source.
  • mimetype, allows you to specify the Accept header for API versioning.

Further information:

Example

Here is an overview of my favorite stack. More information about each middleware is below.

APP_VERSION = IO.popen(["git", "rev-parse", "HEAD", :chdir => Rails.root]).read.chomp

require "faraday_middleware"
require "faraday/conductivity"

connection = Faraday.new(url: "http://widgets.yourapp.com") do |faraday|

  # provided by Faraday itself
  faraday.token_auth "secret"


  # provided by Faraday
  faraday.request :multipart
  faraday.request :url_encoded

  # provided by this gem
  faraday.request :user_agent, app: "MarketingSite", version: APP_VERSION
  faraday.request :request_id
  faraday.request :mimetype, accept: "application/vnd.widgets-v2+json"

  # provided by this gem
  faraday.use :extended_logging, logger: Rails.logger

  # provided by faraday_middleware
  faraday.response :json, content_type: /\bjson$/

  faraday.adapter Faraday.default_adapter

end

Installation

Add this line to your application's Gemfile:

gem 'faraday-conductivity'

And then execute:

$ bundle

Or install it yourself as:

$ gem install faraday-conductivity

Usage

Here is an overview of the middleware included in this gem.

Extended Logging

Provides pretty logging, allowing you to inspect every detail of the request and response.

connection = Faraday.new(url: "http://widgets.yourapp.com") do |faraday|
  faraday.use :extended_logging, logger: Rails.logger
end

Be sure to put this middleware after other middleware that add headers, otherwise it will log incomplete requests.

RequestID

Pass on a request ID from your frontend applications to your backend services. This allows for tracking requests over multiple services. Use this in combination with something like the Rails tagged logger and you'll always know what triggered something to happen in your application.

It works by trying to find the request id in Thread.current[:request_id] and setting the X-Request-Id header.

connection = Faraday.new(url: "http://widgets.yourapp.com") do |faraday|
  faraday.request :request_id
end

In order for this to work, you need to make the Request ID globally available. To do this in Rails:

class Application < ActionController::Base
  before_filter Faraday::Conductivity::RequestIdFilter
end

It's a hack, because it uses a thread local variable, but it works really well.

Don't forget to turn on uuid logging in Rails too, by uncommenting the line in config/environments/production.rb:

# Prepend all log lines with the following tags
config.log_tags = [ :uuid ]

User Agent

Which application, on which server, made this request? With this middleware you know! It sets the User-Agent string based on the user, pid and hostname.

connection = Faraday.new(url: "http://widgets.yourapp.com") do |faraday|
  faraday.request :user_agent, app: "MarketingSite", version: "1.1"
end

The User-Agent will looks like this on my machine:

MarketingSite/1.1 (iain.local; iain; 30360) ruby/1.9.3 (327; x86_64-darwin12.2.0)

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request