Gem Version Build Status Test Coverage Code Climate

Request Info is a Rack middleware which analyzes client’s IP address and HTTP headers in order to provide detailed information about that client, particularly:

  • IP address

  • approximated location (basing on IP)

  • time zone (basing on location)

  • preferred locale (basing on Accept-Language header and location)

Usage

Installation

Then add this line to your application’s Gemfile:

gem 'request_info', github: 'riboseinc/request_info'

And then execute:

bundle

Or install it yourself as:

gem install request_info

Getting started

Simply set up a middleware in config/application.rb like that:

Rails.application.configure do
  config.middleware.use RequestInfo::DetectorApp
end

If you have ActionDispatch::RemoteIp in your middleware stack, then the RequestInfo::DetectorApp should be inserted after it. Please do not add ActionDispatch::RemoteIp to your middleware stack without considering potential security issues described in Rails documentation.

Read more about configuring the middleware stack in Rails Guides.

Detection results are saved as fiber-local variable which can be conveniently accessed later via RequestInfo.results method:

RequestInfo.results.class # => RequestInfo::Results
RequestInfo.results.ip # => "192.0.2.27"
RequestInfo.results.timezone # => #<TZInfo::DataTimezone: Asia/Hong_Kong>

IP geolocalization

This gem can use MaxMind IP intelligence databases for IP address geolocalization. It is optional, but several detections rely on it.

  1. Make sure that libmaxminddb is available. You’ll find detailed instructions here.

  2. Add maxmind_geoip2 gem to your Gemfile.

  3. Download a City or Country database in binary format from Maxmind. Both free of charge GeoLite2, and more detailed but paid GeoIP2 databases will work.

  4. Configure database path

    RequestInfo.configure do |config|
      config.geoip2_db_path = "path/to/downloaded/mmdb/database"
    end

Detections

As mentioned above, analysis results are accessible via RequestInfo.results method. The object returned by this method responds to following getters:

Field Description

Browser detections

browser

A Browser object which holds details about user agent. See browser gem documentation for more details.

IP detections

ip

Client’s remote IP address which is obtained either from ActionDispatch::RemoteIp middleware (if available), or Rack::Request object (otherwise).

ipinfo

A hash with detailed information about user location which is guessed by looking at client’s IP address (requires GeoIP2 or GeoLite2).

Locale detections

locale

Best-matching locale from available ones. First Accept-Language header is checked, then locales popular in client’s country (according to IP address, requires GeoIP2 or GeoLite2). If neither matching locale is available, then the default one is used.

Time zone detections

timezone

An instance of TZInfo::Timezone respective to detected time zone (requires GeoIP2 or GeoLite2).

timezone_id

An identifier of detected time zone, e.g. "Europe/Warsaw" (requires GeoIP2 or GeoLite2).

timezone_offset

Detected time zone offset as a floating point number, e.g. 1.0. In other words, how many hours UTC is behind the detected time zone (requires GeoIP2 or GeoLite2).

timezone_desc

Human-readable time zone description, e.g. "GMT(+1.0) Europe - Warsaw" (requires GeoIP2 or GeoLite2).

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

You will need to have gem libmaxminddb installed in your machine before running 'bin/setup'. If you do not have it setup please follow the steps outlined in this gist https://gist.github.com/leonardteo/9a128bc8ca983fa728aa08d8209e714a, as as homebrew install will not work.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/riboseinc/request_info. 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.

License

The gem is available as open source under the terms of the MIT License.

This repository contains a copy of GeoLite2 City database created by Maxmind, and licensed on CC BY-SA 4.0.