No description or website provided.
Ruby
Pull request Compare This branch is 7 commits behind chtrinh:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
data/geoip
lib
.gitignore
Gemfile
LICENSE
README
README.rdoc
init.rb
ip_filter.gemspec

README.rdoc

IpFilter

IpFilter is IP filtering solution for Ruby. Common use case for this is DRM. Uses a GeoIP (or Geo::IP) database to determine the request ip's location.

Compatibility

  • Supports Ruby version: 1.9.2

  • Supports cache store: Memcache.

  • Supports Rails 3.

Install

As a Gem

Add to your Gemfile:

gem "ip_filter"

and run at the command prompt:

bundle install

Or As a Plugin

At the command prompt:

rails plugin install git://github.com/chtrinh/ip_filter.git

Typical Rails Configuration

# config/initializers/ip_filter.rb

# Location of GeoIP database file.
IpFilter::Configuration.geo_ip_dat = "lib/assets/GeoIP.dat"

# Type of ip country code to compare by.
IpFilter::Configuration.ip_code_type = "country_code2"

# Accepts a proc that must return an array with corresponding format as :ip_code_type
IpFilter::Configuration.ip_codes = Proc.new { ["FI", "US", "GB"] }

# Accepts a proc that must return an array of IPs to
IpFilter::Configuration.ip_whitelist = Proc.new { ["22.33.11.44", "2.3.1.4"] }

# Exception to throw when IP is NOT allowed.
# Accepts a Proc for fine-grain control of the appropriate response. 
IpFilter::Configuration.ip_exception = Proc.new { raise Api::Exception::AuthorizationError.new("You region is blocked!") }

# Cache object (Memcache only).
IpFilter::Configuration.cache = Rails.cache

Whitelist Ip

See above configuration.

Validate IP

Add the following method to any controller to validate the Request#ip. IpFilter::Configuration.ip_exception is a Proc which is called when ip is NOT within the specified region/country code and NOT in IP whitelist. You can pass in filter options similar to those in before_filter.

validate_ip

You can also pass a block (with filter options) to be executed when validation of ip fails like so (defaults to IpFilter::Configuration.ip_exception proc if no block present):

validate_ip do 
  raise Exception.new "Sorry access not granted!"
end

By default, loopback/private network addresses are allowed. You can disable this in like so:

#config/initializers/ip_filter.rb

IpFilter::Configuration.allow_loopback = false

Skip validation of IP

Add the following method to any controller that contains validate_ip to skip over the validation.

skip_validate_ip

Internally it is just skip_before_filter so filter options can be pass to it as well.

skip_validate_ip :only => [:index, :show], :if => lambda { account.roles == "admin" }

Request Geocoding by IP Address

IpFilter adds a location method to the standard Rack::Request object so you can easily look up the location of any HTTP request by IP address. For example, in a Rails controller:

# returns IpFilter::Result object
result = request.location

See “Advanced Geocoding” below for more information about IpFilter::Result objects.

Advanced Geocoding

So far we have looked at shortcuts for assigning geocoding results to object attributes.

Every IpFilter::Result object, result, provides the following data:

  • result.ip - string

  • result.country_code - string

  • result.country_code2 - string

  • result.country_code3 - string

  • result.country_name - string

  • result.continent_code - string

Caching

It's easy to cache ip results with IpFilter, just configure a cache store:

IpFilter::Configuration.cache = Rails.cache

Currently only Memcache is supported.

You can also set a custom prefix to be used for cache keys:

IpFilter::Configuration.cache_prefix = "..."

By default the prefix is ip_filter:

Before you implement caching in your app please be sure that doing so does not violate the Terms of Service for your geocoding service.

Use Outside of Rails

You can use IpFilter outside of Rails by calling the IpFilter.search method:

results = IpFilter.search("147.243.3.83")

This returns an array of IpFilter::Result objects. Please see above and in the code for details.

Acknowledgements

The architecture/design of this gem is heavily based off of Geocoder (by Alex Reisner github.com/alexreisner/geocoder). Whereas Geocoder was built with 3rd party API resources in mind, IpFilter uses a local database file (.dat) similar to Geoip (by Clifford Heath github.com/cjheath/geoip).