request_info

= request_info :source-highlighter: pygments

image:https://img.shields.io/gem/v/request_info.svg["Gem Version", link="https://rubygems.org/gems/request_info"] image:https://img.shields.io/travis/riboseinc/request_info/master.svg["Build Status", link="https://travis-ci.org/riboseinc/request_info"] image:https://img.shields.io/codecov/c/github/riboseinc/request_info.svg["Test Coverage", link="https://codecov.io/gh/riboseinc/request_info"] image:https://img.shields.io/codeclimate/github/riboseinc/request_info.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/request_info"]

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:

[source,ruby]

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:

[source,ruby]

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 http://api.rubyonrails.org/classes/ActionDispatch/RemoteIp.html[Rails documentation].

Read more about configuring the middleware stack in http://guides.rubyonrails.org/rails_on_rack.html[Rails Guides].

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

[source,ruby]

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 https://github.com/maxmind/libmaxminddb[here].

2. Add https://rubygems.org/gems/maxmind_geoip2[`maxmind_geoip2`] gem to your Gemfile.

3. Download a City or Country database in binary format from https://dev.maxmind.com/geoip[Maxmind]. Both free of charge GeoLite2, and more detailed but paid GeoIP2 databases will work.

4. Configure database path

[source,ruby]

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:

[cols="1,3" options="header"] |=============================================================================== | Field | Description

2+^h| Browser detections

| browser | A Browser object which holds details about user agent. See browser gem https://github.com/fnando/browser[documentation] for more details.

2+^h| IP detections

| ip | Client's remote IP address which is obtained either from http://api.rubyonrails.org/classes/ActionDispatch/RemoteIp.html[`ActionDispatch::RemoteIp`] middleware (if available), or http://www.rubydoc.info/gems/rack/Rack/Request/Helpers#ip-instance_method[`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).

2+^h| 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.

2+^h| 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 http://contributor-covenant.org[Contributor Covenant] code of conduct.

== License

The gem is available as open source under the terms of the http://opensource.org/licenses/MIT[MIT License].

This repository contains a copy of GeoLite2 City database created by Maxmind, and licensed on https://creativecommons.org/licenses/by-sa/4.0[CC BY-SA 4.0].