URL Shortener implemented as a Rails Engine
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Yet Another URL Shortener implemented as a Rails Engine and some middleware. The Gem consists of three main parts:

  • ShortenedUrl model to track links and their corresponding shortened urls.
  • Rack Middleware to detect any requests for a short link and return an HTTP 301 redirect to the original link.
  • A view helper to create shortened links.


You can use the latest Rails 3 gem with the latest Tyrion gem. In your Gemfile:

gem 'tyrion', :git => 'git://github.com/johnthethird/tyrion.git'

Note: There is another Gem named Tyrion, so you have to install from Github. Yes, the other Gem has been around longer, but come on, this has got to be the best name ever for a URL shortener, right? So I'm standing my ground. :)

Use bundler to install the Gem:

bundle install

Then run the generator:

rails generate tyrion

This generator will create a migration to create the shortened_urls table where your shortened URLs will be stored.

Finally, rub the migration scripts against your database:

rake db:migrate


To generate a ShortenedUrl object for the URL "http://lannister.com?vassels=2323" within your controller / models do the following:


If you want your short urls to expire after a certain amount of time, you can add an expiration date. If a user clicks on an expired link they would receive an HTTP 404 Not Found error.

Tyrion::ShortenedUrl.generate("http://lannister.com?vassels=2323", Time.zone.now + 1.week)

To generate and display a shortened URL in your application use the helper method:


This will generate a shortened URL, store it in the db, and return a string representing the shortened URL. To specify an expiration date:

short_url("http://lannister.com?vassels=2323", Time.zone.now + 1.week)

By default, all short urls are routed through "/s/(unique_key)". If you want to change the "s" prefix to something else, you can do this in an initializer:

Tyrion.route_prefix = "z"
Tyrion.route_regex = %r(\A\/z\/(\w*)\z)

Note that route_regex should have a single capture group specified that captures the unique_key.

Shorten URLs in generated emails

You can register the included mail interceptor to shorten all links in the emails generated by your Rails app. For example, add to your mailer:

class MyMailer < ActionMailer::Base
  register_interceptor Tyrion::ShortenUrlInterceptor.new

This will replace all long URLs in the emails generated by MyMailer with shortened versions. The base URL for the shortener will be infered from the mailer's default_url_options. If you use a different hostname for your shortener, you can use:

class MyMailer < ActionMailer::Base
  register_interceptor Tyrion::ShortenUrlInterceptor.new :base_url => "http://shortener.host"

The interceptor supports a few more arguments, see the implementation for details.

Tracking Usage Metrics

By default, Tyrion will track a use_count for each short url. Every time the Rack middleware redirects to a shortened url, the use_count is incremented. You can turn this off in an initializer like so:

Tyrion.track = false


This Gem is based in large part on the Shortener Gem by James McGrath and Michael Reinsch. I removed the ability to tie shortened urls to other models, as we didn't need the added complexity. I also converted the controller which handled the redirect to a Rack middleware instead.

Future goals for this Gem include leveraging the TorqueBox messaging queue to handle the tracking of url metrics, as well as other features which will also depend entirely on TorqueBox, so a whole new Gem instead of a fork seemed appropriate.