Skip to content
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.
Find file
New pull request
Pull request Compare This branch is 62 commits behind jtrupiano:master.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



A 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.



Sample rackup file

gem 'rack-rewrite', '~> 1.2.1'
require 'rack/rewrite'
use Rack::Rewrite do
  rewrite '/wiki/John_Trupiano', '/john'
  r301 '/wiki/Yair_Flicker', '/yair'
  r302 '/wiki/Greg_Jastrab', '/greg'
  r301 %r{/wiki/(\w+)_\w+}, '/$1'

Sample usage in a rails app

config.middleware.insert_before(Rack::Lock, Rack::Rewrite) do
  rewrite '/wiki/John_Trupiano', '/john'
  r301 '/wiki/Yair_Flicker', '/yair'
  r302 '/wiki/Greg_Jastrab', '/greg'
  r301 %r{/wiki/(\w+)_\w+}, '/$1'

Use Cases

Rebuild of existing site in a new technology

It's very common for sites built in older technologies to be rebuilt with the latest and greatest. Let's consider a site that has already established quite a bit of “google juice.” When we launch the new site, we don't want to lose that hard-earned reputation. By writing rewrite rules that issue 301's for old URL's, we can “transfer” that google ranking to the new site. An example rule might look like:

r301 '/contact-us.php', '/contact-us'
r301 '/wiki/John_Trupiano', '/john'

Retiring old routes

As a web application evolves you will undoubtedly reach a point where you need to change the name of something (a model, e.g.). This name change will typically require a similar change to your routing. The danger here is that any URL's previously generated (in a transactional email for instance) will have the URL hard-coded. In order for your rails app to continue to serve this URL, you'll need to add an extra entry to your routes file. Alternatively, you could use rack-rewrite to redirect or pass through requests to these routes and keep your routes.rb clean.

rewrite %r{/features(.*)}, '/facial_features$1'

CNAME alternative

In the event that you do not control your DNS, you can leverage Rack::Rewrite to redirect to a canonical domain. In the following rule we utilize the $& substitution operator to capture the entire request URI.

r301 %r{.*}, '$&', :if => {|rack_env|
  rack_env['SERVER_NAME'] != ''

Site Maintenance

Most capistrano users will be familiar with the following Apache rewrite rules:

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

This rewrite rule says to render a maintenance page for all non-asset requests if the maintenance file exists. In capistrano, you can quickly upload a maintenance file using:

cap deploy:web:disable REASON=upgrade UNTIL=12:30PM

We can replace the mod_rewrite rules with the following Rack::Rewrite rule:

maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
send_file /.*/, maintenance_file, :if => { |rack_env|
  File.exists?(maintenance_file) && rack_env['PATH_INFO'] !~ /\.(css|jpg|png)/

If you're running Ruby 1.9, this rule is simplified:

maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
send_file /(.*)$(?<!css|png|jpg)/, maintenance_file, :if => { |rack_env|

For those using the oniguruma gem with their ruby 1.8 installation, you can get away with:

maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
send_file"(.*)$(?<!css|png|jpg)"), maintenance_file, :if => { |rack_env|

Rewrite Rules


Calls to #rewrite will simply update the PATH_INFO, QUERY_STRING and REQUEST_URI HTTP header values and pass the request onto the next chain in the Rack stack. The URL that a user's browser will show will not be changed. See these examples:

rewrite '/wiki/John_Trupiano', '/john'   # [1]
rewrite %r{/wiki/(\w+)_\w+}, '/$1'       # [2]

For [1], the user's browser will continue to display /wiki/John_Trupiano, but the actual HTTP header values for PATH_INFO and REQUEST_URI in the request will be changed to /john for subsequent nodes in the Rack stack. Rails reads these headers to determine which routes will match.

Rule [2] showcases the use of regular expressions and substitutions. [2] is a generalized version of [1] that will match any /wiki/FirstName_LastName URL's and rewrite them as the first name only. This is an actual catch-all rule we applied when we rebuilt our website in September 2009 ( ).

:r301, :302

Calls to #r301 and #r302 have the same signature as #rewrite. The difference, however, is that these actually short-circuit the rack stack and send back 301's and 302's, respectively. See these examples:

r301 '/wiki/John_Trupiano', '/john'                # [1]
r301 '/wiki/(.*)', '$1'   # [2]

Recall that rules are interpreted from top to bottom. So you can install “default” rewrite rules if you like. [2] is a sample default rule that will redirect all other requests to the wiki to a google search.

:send_file, :x_send_file

Calls to #send_file and #x_send_file also have the same signature as #rewrite. If the rule matches, the 'to' parameter is interpreted as a path to a file to be rendered instead of passing the application call up the rack stack.

send_file /*/, 'public/spammers.htm', :if => { |rack_env|
  rack_env['HTTP_REFERER'] =~ ''
x_send_file /^blog\/.*/, 'public/blog_offline.htm', :if => { |rack_env|

Options Parameter

Each rewrite rule takes an optional options parameter. The following options are supported.


Using the :host option you can match requests to a specific hostname.

r301 "/features", "/facial_features", :host => ""

This rule will only match when the hostname is “”


Using the :headers option you can set custom response headers e.g. for HTTP caching instructions.

r301 "/features", "/facial_features", :headers => {'Cache-Control' => 'no-cache'}


Using the :method option you can restrict the matching of a rule by the HTTP method of a given request.

# redirect GET's one way
r301 "/players", "/current_players", :method => :get

# and redirect POST's another way
r302 "/players", "/no_longer_available.html?message=No&longer&supported", :method => :post


Using the :if option you can define arbitrary rule guards. Guards are any object responding to #call that return true or false indicating whether the rule matches. The following example demonstrates how the presence of a maintenance page on the filesystem can be utilized to take your site(s) offline.

maintenance_file = File.join(RAILS_ROOT, 'public', 'system', 'maintenance.html')
x_send_file /.*/, maintenance_file, :if => { |rack_env| 


Using the :not option you can negatively match against the path. This can be useful when writing a regular expression match is difficult.

rewrite %r{^\/features}, '/facial_features', :not => '/features'

This will not match the relative URL /features but would match /features.xml.


Keeping your querystring

When rewriting a URL, you may want to keep your querystring in tact (for example if you're tracking traffic sources). You will need to include a capture group and substitution pattern in your rewrite rule to achieve this.

rewrite %r{/wiki/John_Trupiano(\?.*)?}, '/john$1'

This rule will store the querystring in a capture group (via '(?.*)' ) and will substitute the querystring back into the rewritten URL (via $1).

Arbitrary Rewriting

All rules support passing a Proc as the second argument allowing you to perform arbitrary rewrites. The following rule will rewrite all requests received between 12AM and 8AM to an unavailable page.

rewrite %r{(.*)}, lambda { |match, rack_env| < 8 ? "/unavailable.html" : match[1]


Copyright © 2009-2011 John Trupiano. See LICENSE for details.

Something went wrong with that request. Please try again.