$> ls -l ~/projects/timecop/lib
drwxr-xr-x 5 john staff 170 Jan 14 20:31 timecop
-rw-r--r-- 1 john staff 82 Jan 14 20:31 timecop.rb


The reason for this is related to how RubyGems hijacks Ruby’s require method. When a gem is activated its lib/ folder is added to the load path. This means that anything inside that directory is now accessible via the require method. In order to avoid file naming collisions across gems, you must name these exactly the same as your gem. (see slides for I Don’t Trust Your Code for a more complete discussions of this)

However, this is slightly different with rack gems. The convention for naming rack middleware is by using a dash, e.g. rack-rewrite. The convention for requiring rack middleware though is to replace that dash with a slash, e.g. require 'rack/rewrite'.

The convention I’ve adopted for structuring rack middleware within a gem is to include a file by the same name as the gem and a rack directory in lib/, and then to include the second part of the middleware name as a subdirectory under that.


~/projects/rack-rewrite (master) $> ls -l lib/
total 8
drwxr-xr-x 4 john staff 136 Apr 17 18:02 rack
-rw-r--r--@ 1 john staff 22 Apr 17 18:02 rack-rewrite.rb

~/projects/rack-rewrite (master) $> ls -l lib/rack
total 8
drwxr-xr-x 3 john staff 102 May 13 11:09 rewrite
-rw-r--r--@ 1 john staff 827 Apr 17 18:02 rewrite.rb


This allows my users to use either require 'rack-rewrite' or require 'rack/rewrite'.

Rack::Rewrite is a web-server agnostic rack middleware for defining and applying rewrite rules. In many cases you can get away with Rack::Rewrite instead of writing Apache mod_rewrite rules.

Documentation is hosted at RubyForge. The source code is hosted at GitHub.

Updates include:

API

• Fix rack 1.1.0 / rails3 compatibility by eliminating reliance on REQUEST_URI env param. Paths are now constructed with PATH_INFO and QUERY_STRING
• Follow rack directory/require convention: require ‘rack/rewrite’ instead of ‘rack-rewrite’
• Include an HTML anchor tag linked to where the URL being redirected to in the body of 301′s and 302′s

Rack::Rewrite is a web-server agnostic rack middleware for defining and applying rewrite rules. In many cases you can get away with Rack::Rewrite instead of writing Apache mod_rewrite rules.

Documentation is hosted at RubyForge. The source code is hosted at GitHub.

Updates include:

API

• Implement $& substitution pattern (thanks to Ben Brinckerhoff)

Maintenance

• Ignore empty captures instead of failing during subsitution (thanks to Ben Brinckerhoff)
• Play nice with Rack::Test requests which only set PATH_INFO and not REQUEST_URI (thanks to @docunext)
• Use QUERY_STRING instead of QUERYSTRING as per Rack spec. Closes Issue #1.

Google Analytics Navigation

Enter Rack::Rewrite. Rack::Rewrite is a Rack middleware for defining and applying rewrite rules. Though it’s not a full replacement for Apache’s mod_rewrite, a great deal of rules I’ve previously written in Apache config files can be replaced by Rack::Rewrite. Run gem install rack-rewrite to install the gem.

In order to determine which URL’s were most important to issue 301′s for, we turned to Google Analytics. By reviewing the most popular landing pages of the past two months from our site, we were able to methodically write our redirect rules.

Google Analytics | Top Landing Pages

Here is a subset of the associated Rack::Rewrite rules.

  config.middleware.insert_before(Rack::Lock, Rack::Rewrite) do        
    # original wiki smartlogicsolutions.com website
    r301 '/wiki/Main_Page', '/'
    r301 '/wiki/John_Trupiano', '/john'
    r301 %r{^/wiki/(Charity|Charities|Local_Connection)$}, '/gratis-work-and-charities'
    r301 '/wiki/Category:Portfolio', '/portfolio'
    r301 '/wiki/ExxonMobil_-_Brand_Asset_Center', '/portfolio/exxonmobil-brand-asset-center'
    r301 '/wiki/In_the_News', '/in-the-news'
    r301 '/wiki/Getting_to_our_Office', '/driving-directions'
    r301 '/wiki/Category:Employees', '/our-team'
    r301 '/wiki/SimNet_for_Office_2007', '/portfolio/simnet-for-office-2007-and-vista'
    r301 '/wiki/VNC_Collaboration_Application', '/portfolio/shared-desktop'
    r301 '/wiki/Contact_Information', '/contact-us'
  end

This scheme is great for landing pages, but what if we had querystring information that we wanted to keep around? This is common for tracking codes — many marketing platforms generate URL’s that embed data in the querystring for recording and tracking purposes. We can leverage the following trick to maintain the querystring across a rewrite.

  r301 %r{^/wiki/Main_Page(\?.*)?$}, '/$1'

Note the following:

• We are conditionally matching a querystring so that the rule continues to match in the absence of a querystring.
• We are leveraging substitution patterns to reconstitute the querystring in the rewritten URL.

Many more great use cases for Rack::Rewrite are covered in the project’s README.

I typically leverage rewrite rules to take my sites offline for maintenance. Most capistrano users will be familiar with the following Apache rewrite ruleset.

  RewriteCond %{REQUEST_URI} !\.(css|jpg|png)$
  RewriteCond %{DOCUMENT_ROOT}/system/maintenance.html -f
  RewriteCond %{SCRIPT_FILENAME} !maintenance.html
  RewriteRule ^.*$ /system/maintenance.html [L]

This ruleset matches requests for non-asset URL’s and renders a maintenance page if it exists on the filesystem. When capistrano users run cap deploy:web:disable REASON="site upgrade" UNTIL="2PM" a maintenance page is placed in public/system and this ruleset begins to kick in. Running cap deploy:web:enable will remove this page and the ruleset ceases to match.

We can replace this ruleset with the following Rack::Rewrite rule:

  # Ruby 1.8.x
  maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
  send_file /.*/, maintenance_file, :if => Proc.new { |rack_env|
    File.exists?(maintenance_file) && rack_env['REQUEST_URI'] !~ /\.(css|jpg|png)/
  }

This rewrite rule uses the send_file method to return the maintenance page, uses a rule guard (the :if proc) to check for the existence of the file, and accesses the rack environment directly (rack_env arg to the Proc) to check the request URI. Due to the shortcomings of the Ruby 1.8′s regular expression library (no negative lookahead), we have to leverage the rule guard to allow assets to continue to be served (css, jpg, png).

Using Ruby 1.9, this rule is simpler.

  # Ruby 1.9.x
  maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
  send_file /(.*)$(?<!css|png|jpg)/, maintenance_file, :if => Proc.new { |rack_env|
    File.exists?(maintenance_file)
  }

Users of 1.8.x can leverage Oniguruma to keep the rule simpler.

  # Ruby 1.8.x + Oniguruma
  maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
  send_file Oniguruma::ORegexp.new("(.*)$(?<!css|png|jpg)"), maintenance_file, :if => Proc.new { |rack_env|
    File.exists?(maintenance_file)
  }