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

Timecop is a RubyGem providing “time travel” and “time freezing” capabilities, making it dead simple to test time-dependent code. It provides a unified method to mock Time.now, Date.today, and DateTime.now in a single call.

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

Updates include:

Maintenance

• Fix various timezone-related issues. Notably, when traveling to a DateTime
  instance specified in a non-local timezone, convert provided DateTime
  instance to a local instance and return that from DateTime.now.
  Code contributed by Michaël Witrant [piglop]
• Fix bug that would not allow Timecop to be used when Ruby’s ‘date’
  library had not been previously loaded.
  Code contributed by Tuomas Kareinen [tuomas]
• Fix bug when traveling to a DateTime across a DST boundary that
  resulted in DateTime’s being off by an hour.
• Migrate argument parsing into Timecop::TimeStackItem to reduce the
  responsibility of the Timecop class.

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)
  }

Timecop is a RubyGem providing “time travel” and “time freezing” capabilities, making it dead simple to test time-dependent code. It provides a unified method to mock Time.now, Date.today, and DateTime.now in a single call.

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

Updates include:

API

• Completely remove Timecop#unset_all (deprecated by Timecop#return in 0.2.0)
• Return Time.now from #freeze, #travel and #return — code contributed by Keith Bennett (keithrbennett)

Maintenance

• Fix bug that left Time#mock_time set in some instances
• Upped build dependency to jeweler ~> 1.2.1
• Don’t pollute top-level namespace with classes/constants

Documentation

• Clearer examples in the README, better description in the gemspec
• Improve RDoc

• Replacing your current ruby installation with a patched version
• Installing a gem to patch the code and then updating your application to load the patch.

The latter approach only postpones the inevitable, so I opted for the former. If you’re using the debian packages, it’s a simple call to aptitude update. However, if you’ve installed from source, this presents a few challenges.

The upgrade is actually quite straightforward. According to the REE Documentation, you simply need to run the new installer over top of your previous installation. This includes specifying the exact same directory name that you used to install the previous version.

As you may know, REE installs by default into /opt/ruby-enterprise-1.8.6-<year_month_day_release>. However, after completing this, you’re left with a directory name that doesn’t reflect what’s actually installed in there. If you’ve a little neurotic like I am, you’re going to want to rename that directory. However, be careful. Your Passenger configuration is likely pointing to the directory that you want to rename, so you’ll have to remember to update your apache/nginx configuration to reflect this.

When we install REE we create a symlink at /opt/ruby which points to the version of ruby that we want passenger to run. This allows us to quickly swap in/out different versions of ruby for testing/upgrading/etc.

Considering we have dozens of client applications running on distinct servers each with their own versions of REE installed, I decided to write a script to minimize the manual effort required to upgrade several production servers.

#!/bin/sh
# Author: John Trupiano
# Script to upgrade an REE installation on a hot server and maintain sane directory names
 
if [ "$(whoami)" != "root" ]; then
  echo "You need to be root to run this!"
  exit 2
fi
 
RF_RELEASE=58677
REE_VERSION=20090610
REE=ruby-enterprise-1.8.6-$REE_VERSION
URL=http://rubyforge.org/frs/download.php/$RF_RELEASE/$REE.tar.gz
 
# Determine what the most recent version of REE is that is installed
MOST_RECENT_REE_VERSION=`ls /opt | awk -F"-" '$4 > max && $2 == "enterprise" { max=$4; maxline=$0 }; END { print max }'`
MOST_RECENT_REE=ruby-enterprise-1.8.6-$MOST_RECENT_REE_VERSION
 
WORKING_DIR=/root/src
 
echo "Going to update $MOST_RECENT_REE to $REE"
 
echo "Back up previous release"
cp -R /opt/$MOST_RECENT_REE /opt/$MOST_RECENT_REE.bak
 
echo "Download new release"
mkdir -p $WORKING_DIR
cd $WORKING_DIR && wget $URL
 
echo "Untar and install over the previous release for 'upgrade' according to REE manual"
tar xzf $REE.tar.gz
./$REE/installer --auto /opt/$MOST_RECENT_REE
 
echo "Shuffle folder names to remain sane"
mv /opt/$MOST_RECENT_REE /opt/$REE && mv /opt/$MOST_RECENT_REE.bak /opt/$MOST_RECENT_REE
 
echo "Actually symlink in the new version of REE"
rm /opt/ruby && ln -s /opt/$REE /opt/ruby
 
echo "Clean up after ourselves"
rm -f $WORKING_DIR/$REE

Simply upload this script to your server, su – up to root and run it. Then restart apache/nginx so that passenger will pick up the new version of ruby. All of your gems will be maintained, and your most recent version of REE will remain in tact at /opt/ruby-enterprise-1.8.6-<old_version> in case you need it again.

View the script on github

require 'lib/some_rake_file' # or require 'lib/some_rake_file.rake'

=> rake aborted!
no such file to load — /home/your_project/lib/some_rake_file

Rake assumes the ‘require’d files end in .rb, so it won’t find your .rake files. You need to import rake files:

import 'lib/some_rake_file'

This is fine for individual files, but I wanted to include all files that end in .rake in my tasks dir:

Dir.glob('tasks/*.rake').each { |r| import r }

…and there you go. While dead simple, this exemplifies an important distinction between require and import that I found to be poorly documented. Keep your rake tasks organized and remember that Rake isn’t just for rails apps!

Slow-Actions is great tool for determining the slow areas of a rails application. Since it is built on a rails log parser, it can be used for many other things. For example, here is some standard output from slow-actions when you want to know the speed of different user sessions within a specific date range:

slow-actions log/development.log --sessions --start-date=2009-03-01 --end-date=2009-04-01
           Cost    Average Max
+ ece0e17b48a5fe0fc766fa42f199fb66 (51 entries, 58% Error)
| Total:   2883.262 732.948 3100.00
| Render:  0.00000 0.00000 0.00000
| DB:      55.8220 14.1900 99.0000 

+ e1181ad94b34b41aff2a74ee62d5fb57 (10 entries, 30% Error)
| Total:   1563.912 676.276 1426.00
| Render:  0.00000 0.00000 0.00000
| DB:      14.5350 6.28500 19.0000 

+ 867bc340e6d65e673f29c57189feaf2b (133 entries, 0% Error)
| Total:   1083.138 221.450 386.000
| Render:  0.00000 0.00000 0.00000
| DB:      44.2030 9.03700 90.0000 

Etc...

Now, if we grep for “entries” we get a line for each session:

slow-actions log/development.log --sessions --start-date=2009-03-01 --end-date=2009-04-01 | grep entries
+ ece0e17b48a5fe0fc766fa42f199fb66 (51 entries, 58% Error)
+ e1181ad94b34b41aff2a74ee62d5fb57 (10 entries, 30% Error)
+ 867bc340e6d65e673f29c57189feaf2b (133 entries, 0% Error)
+ 99b39c7a9af55fc01056b5f127dc4c98 (75 entries, 0% Error)
+ 6ee15c4f3bc804ac68e9e868d9c3f7e6 (14 entries, 0% Error)
+ 80928c25c83590c4f89b91f8d4c8896d (9 entries, 0% Error)
+ c78cfa1cb086b3f473015b212ca3da11 (12 entries, 0% Error)
+ 48cd02cf6544493077c84eb16821bda2 (3 entries, 66% Error)
+ ac027817dcf87d473efb54cd737b2a80 (2 entries, 0% Error)
+ dff2ca2678852b06bbb6c7ca0a85b0a9 (1 entries, 0% Error)
+ 08ed3bc031c23bd3b2572ef7ce60d066 (1 entries, 0% Error)

Pipe that to word count, and we have the number of unique sessions within a specified time period:

slow-actions log/development.log --sessions --start-date=2009-03-01 --end-date=2009-04-01 | grep entries | wc -l
11

On a 54m log file, that takes only 0.761s!