AirBlog - Home

A Paper Trail For Your Models

2009-06-23T09:56:00Z

PaperTrail lets you track changes to your Rails app’s models’ data. It’s good for auditing or versioning. You can see how a model looked at any stage in its lifecycle and even undelete it after it’s been destroyed.

Features

Stores every create, update and destroy.
Does not store updates which don’t change anything.
Allows you to get at every version, including the original, even once destroyed.
Allows you to get at every version even if the schema has since changed.
Automatically records who was responsible if your controller has a current_user method.
Allows you to set who is responsible at model-level (useful for migrations).
Can be turned off/on (useful for migrations).
No configuration necessary.
Stores everything in a single database table (generates migration for you).
Thoroughly tested.

Rails Version

Known to work on Rails 2.3. Probably works on Rails 2.2 and 2.1.

Basic Usage

PaperTrail is simple to use. Just add 15 characters to a model to get a paper trail of every create, update, and destroy.


class Widget < ActiveRecord::Base
  has_paper_trail
end

This gives you a versions method which returns the paper trail of changes to your model.


>> widget = Widget.find 42
>> widget.versions             # [<Version>, <Version>, ...]

Once you have a version, you can find out what happened:


>> v = widget.versions.last
>> v.event                     # 'update' (or 'create' or 'destroy')
>> v.whodunnit                 # '153'  (if the update was via a controller and
                               #         the controller has a current_user method,
                               #         here returning the id of the current user)
>> v.created_at                # when the update occurred
>> widget = v.reify            # the widget as it was before the update;
                               # would be nil for a create event

PaperTrail stores the pre-change version of the model, unlike some other auditing/versioning plugins, so you can retrieve the original version. This is useful when you start keeping a paper trail for models that already have records in the database.


>> widget = Widget.find 153
>> widget.name                                 # 'Doobly'

# Add has_paper_trail to Widget model.

>> widget.versions                             # []
>> widget.update_attributes :name => 'Wotsit'
>> widget.versions.first.reify.name            # 'Doobly'
>> widget.versions.first.event                 # 'update'

This also means that PaperTrail does not waste space storing a version of the object as it currently stands. The versions method gives you previous versions; to get the current one just call a finder on your Widget model as usual.

Here’s a helpful table showing what PaperTrail stores:

Event	Model Before	Model After
create	nil	widget
update	widget	widget’
destroy	widget	nil

PaperTrail stores the values in the Model Before column. Most other auditing/versioning plugins store the After column.

Reverting Or Undeleting A Model

PaperTrail makes reverting to a previous version easy:


>> widget = Widget.find 42
>> widget.update_attributes :name => 'Blah blah'
# Time passes....
>> widget = Widget.find(42).versions.last.reify  # the widget as it was before the update
>> widget.save  # reverted to its previous version

Undeleting is just as simple:


>> widget = Widget.find 42
>> widget.destroy
# Time passes....
>> widget = Version.find(153).reify    # the widget as it was before it was destroyed
>> widget.save                         # the widget lives!

In fact you could use PaperTrail to implement an undo system, though I haven’t had the opportunity yet to do it myself.

Finding Out Who Was Responsible For A Change

If your ApplicationController has a current_user method, PaperTrail will store the value it returns in the version’s whodunnit column. Note that this column is a string so you will have to convert it to an integer if it’s an id and you want to look up the user later on:


>> last_change = Widget.versions.last
>> user_who_made_the_change = User.find last_change.whodunnit.to_i

In a migration or in script/console you can set who is responsible like this:


>> PaperTrail.whodunnit = 'Andy Stewart'
>> widget.update_attributes :name => 'Wibble'
>> widget.versions.last.whodunnit              # Andy Stewart

Turning PaperTrail Off/On

Sometimes you don’t want to store changes. Perhaps you are only interested in changes made by your users and don’t need to store changes you make yourself in, say, a migration.

If you are about change some widgets and you don’t want a paper trail of your changes, you can turn PaperTrail off like this:


>> Widget.paper_trail_off

And on again like this:


>> Widget.paper_trail_on

Installation

Install PaperTrail either as a gem or as a plugin:

config.gem 'airblade-paper_trail', :lib => 'paper_trail', :source => 'http://gems.github.com'

or:

script/plugin install git://github.com/airblade/paper_trail.git
Generate a migration which will add a versions table to your database.

script/generate paper_trail
Run the migration.

rake db:migrate
Add has_paper_trail to the models you want to track.

Testing

PaperTrail has a thorough suite of tests. However they only run when PaperTrail is sitting in a Rails app’s vendor/plugins directory. If anyone can tell me how to get them to run outside of a Rails app, I’d love to hear it.

Problems

Please use GitHub’s issue tracker.

Inspirations

Intellectual Property

Going Back To Simple

2009-06-17T09:14:00Z

Every mistake we’ve made as a company has been because we tried to do too much, not because we didn’t do enough.

Jason Fried, founder of 37signals

Testing HTTP Digest Authentication With Shoulda

2009-06-09T11:30:00Z

I recently started writing a small Rails app where I’ll be the only administrative user. (It’s going to replace Mephisto, which runs this blog and regularly goes rogue on the CPU.) Anyway, my authentication requirements were simple: log in, log out. So I asked myself, “what’s the simplest thing that could possibly work?”

Well, HTTP authentication is supposed to be simpler than a form-based approach. In theory it’s trivial to code: just copy and paste the example from the Rails documentation. In practice there were a few catches which took me quite a while to resolve, not least the testing.

Once I had settled on HTTP authentication I had to choose between basic and digest. I picked digest because I thought basic and digest would be similarly easy to implement, so I might as well use the securer version.

Understanding Rails’ API

I hadn’t implemented HTTP authentication before. My first problem was finding Rails’ API confusing. There are three methods:


  authenticate_or_request_with_http_digest(realm = 'Application', &password_procedure)

  authenticate_with_http_digest(realm = 'Application', &password_procedure)

  request_http_digest_authentication(realm = 'Application', message = nil)

I found them easier to understand in reverse order.

The last one renders a 401 to the browser, along with headers saying ‘use HTTP digest authentication to authenticate’. It’s not actually making a request; it’s instructing the browser to request the resource again, but this time with the user’s name and password bundled up as per the HTTP-digest protocol. The method returns the message, which defaults to "HTTP Digest: Access denied.\n".

The browser sees the 401 and the ‘use HTTP digest authentication’ and pops up a dialog box for the user asking for a name and password. Once the user has typed these in, the browser sends a new request for the resource, but this time with the user’s log-in details too.

The middle one, authenticate_with_http_digest, checks whatever name and password the browser supplies to see if they’re legitimate. It simply returns true or false. It doesn’t know or care whether the browser has just asked the user to type in a name and password, or whether the browser cached whatever legitimate credentials the user typed in previously.

Now we know what those methods do, we can understand the first one. It simply wraps them:


  authenticate_with_http_digest(realm, &password_procedure) ||
  request_http_digest_authentication(realm)

So first it checks whether the user’s name and password, as sent by the browser, are legitimate. If the browser had these in a cache, it won’t have asked the user again. If the user’s credentials are good, the method returns true. Otherwise — either the browser didn’t send any credentials or it did but the credentials were bad — we send a 401 to the browser, causing it to ask the user for a name and password, and then to re-request the resource. In this case the method returns "HTTP Digest: Access denied.\n".

Storing the user in the session

Bearing in mind a gap in Rails 2.3.2’s implementation, we can store the user in the session like this:


def authenticate
  result = authenticate_or_request_with_http_digest do |name|
    @user = User.find_by_name(name)
    @user.try(:password) || false
  end
  session[:current_user] = @user.id unless result =~ /denied/
end

Log out with HTTP digest

Since the browser caches the user’s name and password, we need a way to force the browser to forget them. I use a flag which tells my authenticate method to make the authentication fail:


class SessionsController < ApplicationController
  def logout
    session[:current_user] = nil       # so the app knows
    session[:logout_requested] = true  # so the browser will know
    redirect_to root_path
  end
end

class ApplicationController < ActionController::Base
  def authenticate
    result = authenticate_or_request_with_http_digest do |name|
      if session[:logout_requested]
        session[:logout_requested] = nil   # reset flag
        false
      else
        @user = User.find_by_name(name)
        @user.try(:password) || false
      end
    end
    session[:current_user] = @user.id unless result =~ /denied/
  end
end

I got this idea from Eden Development.

Alternative implementation

Given our triumvirate of HTTP digest authentication methods above, we could rewrite our authenticate method in terms of the two lower-level methods like this:


class ApplicationController < ActionController::Base
  def authenticate
    success = authenticate_with_http_digest do |name|
      if session[:logout_requested]
        session[:logout_requested] = nil   # reset flag
        false
      else
        @user = User.find_by_name(name)
        @user.try(:password) || false
      end
    end

    if success
      session[:current_user] = @user.id
    else
      request_http_digest_authentication
    end
  end
end

The Tests

Testing HTTP digest authentication is not easy. Fortunately Steve Madsen figured it out . I incorporated his code into this Shoulda macro:


# test/shoulda_macros/security.rb:

module AirWeb
  module Shoulda

    def should_be_unauthorized(http_method, action, options = {})
      context "on #{http_method} to #{action}" do
        setup do
          options.each{ |k,v| options[k] = instance_eval(v) }
          send http_method, action, options
        end
        should_respond_with :unauthorized
      end
    end

  end
end

module AirWeb
  module Shoulda
    module Helpers

      def log_in
        # Any user will do.
        authenticate_with_http_digest(User.first.name, User.first.password)
        @request.session[:current_user] = User.first.id
        @request.session[:logout_requested ] = false
      end

      def log_out
        @request.session[:current_user] = nil
        @request.session[:logout_requested ] = true
      end

    end
  end
end

ActiveSupport::TestCase.send :include, AirWeb::Shoulda::Helpers
ActiveSupport::TestCase.extend AirWeb::Shoulda

require 'digest/md5'

class ActionController::TestCase
  def authenticate_with_http_digest(user = 'admin', password = 'admin', realm = 'Application')
    unless ActionController::Base < ActionController::ProcessWithTest
      ActionController::Base.class_eval { include ActionController::ProcessWithTest }
    end

    @controller.instance_eval %Q(
      alias real_process_with_test process_with_test

      def process_with_test(request, response)
        credentials = {
          :uri => request.env['REQUEST_URI'],
          :realm => "#{realm}",
          :username => "#{user}",
          :nonce => ActionController::HttpAuthentication::Digest.nonce,
          :opaque => ActionController::HttpAuthentication::Digest.opaque,
        }
        request.env['HTTP_AUTHORIZATION'] = ActionController::HttpAuthentication::Digest.encode_credentials(
          request.request_method, credentials, "#{password}", false
        )
        real_process_with_test(request, response)
      end
    )
  end
end

This allows me to write test code like:


  context 'The public' do
    setup { log_out }
    should_be_unauthorized :get, :new
    should_be_unauthorized :create, :new
    should_be_unauthorized :update, 'Article.first.id'
  end

It took me a while to realise that Article is not visible in the context’s scope. You have to pass a string to your custom should method, then instance_eval it in the setup block. (Or you could pass an instance variable.)

PUT and DELETE problem with HTTP digest

In the course of all this, I realised that my app wouldn’t allow me to update (via PUT) or destroy (via DELETE). It turns out there was a bug but it has been fixed in commit dbb025 by Steve Madsen. This is on the 2-3-stable branch but not in the gems, so you’ll have to vendor Rails.

Conclusion

I rather wish I had stuck with form-based authentication! However that’s because I hadn’t looked at HTTP authentication before. Now I have, the next time I come to implement authentication, HTTP authentication actually will be the simplest thing that could work.

The Rails Toolbox

2009-06-05T17:44:00Z

The Goal

Inspired by The Ruby Toolbox, I wanted to construct a Rails Toolbox. The Ruby Toolbox mines GitHub, rating the tools by the number of watchers and forks; how to do something similar for Rails?

The Method

First of all we need to define what counts as a Rails tool. I’m saying plugins and gems.

Second, we need to find out which plugins and gems people have installed in their Rails apps. Here we make use of a handy feature introduced in Rails 2.3: Rails Application Templates. These templates are scripts which let you customise a new Rails application, and crucially they have these three attributes:

They specify which plugins to install in the new Rails app.
They specify which gems to install in the new Rails app.
People tend to pop them on GitHub even if their apps aren’t open-source.

So all we need to do is mine GitHub for these templates, hammer through them, and tot up the plugins and gems they use.

The Code

I wrote some code to do this. It uses John Nunemaker’s HTTParty to wrap GitHub’s API, or at least the parts I needed.

This was the first time I’ve used HTTParty and I liked it a lot. I haven’t got up and running with someone else’s code so quickly for ages. As an aside, I think it’s supposed to be “HTTP-party” but I prefer “HTTP-arty”.

The Results

I would love to build a website for you as shiny as The Ruby Toolbox’s. But not quite enough to actually do it. You’ll have to settle for two lists.

There’s also one small caveat to bear in mind but I’ll come to that later.

Top 33 Gems

thoughtbot-factory_girl (6)
RedCloth (6)
mislav-will_paginate (5)
ruby-openid (5)
thoughtbot-shoulda (5)
hpricot (3)
mocha (3)
haml (2)
rspec (2)
rubyist-aasm (2)
sqlite3-ruby (2)
rspec-rails (2)
stefanpenner-my_scaffold (2)
dm-validations (1)
sevenwire-attr_encrypted (1)
datamapper4rail (1)
dm-timestamps (1)
mislav-will-paginate (1)
rcov (1)
authlogic (1)
chriseppstein-compass (1)
addressable (1)
quietbacktrace (1)
yfactorial-utility_scopes (1)
rdiscount (1)
jchris-couchrest (1)
bj (1)
do_sqlite3 (1)
thoughtbot-quietbacktrace (1)
sevenwire-forgery (1)
sevenwire-configatron (1)
aws-s3 (1)
faker (1)

Top 40 Plugins

rspec (8)
rspec-rails (8)
exception_notifier (6)
open_id_authentication (5)
restful-authentication (4)
asset_packager (4)
role_requirement (3)
hoptoad_notifier (3)
acts_as_taggable_redux (3)
aasm (2)
active_scaffold (2)
will_paginate (2)
squirrel (2)
cucumber (2)
year_after_year (1)
semantic_form_builder (1)
acl_system2 (1)
factory_girl (1)
basic_model (1)
restful_authentication (1)
permanent_records (1)
webrat (1)
dataset (1)
make_resourceful (1)
machinist (1)
bootstrapper (1)
ssl_requirement (1)
authlogic (1)
mile_marker (1)
flash-message-conductor (1)
active_presenter (1)
shoulda (1)
quietbacktrace (1)
forgery (1)
newrelic_rpm (1)
limerick_rake (1)
action_mailer_tls (1)
facebooker (1)
in_place_editing (1)
rr (1)

Caveat

These results are based on the first 30 repositories returned by GitHub’s API; The GUI returns 243 results. If anyone know hows to get the next 30 (and the 30 after, etc), please let me know in the comments. Thanks ;)

Update: this is a known shortcoming. There’s not much we can do until it’s fixed.

Discussion

We can’t reach any statistically significant conclusions about the popularity of Rails plugins and gems: with only 30 repositories out of 243 we do not have a sufficiently powerful sample. Also none of mine are showing up in the results so the data must be incomplete.

We can mine all the data we need to build a complete recommendation system. Rails’ plugin installer and gem-installing Rake task could be beefed up like this:


  $ script/plugin install git://github.com/technoweenie/restful-authentication.git
  [...Git stuff...]
  People who installed restful-authentication were also interested in authlogic.
  Would you like to try authlogic instead (y/n)?
  $ y
  Uninstalling restful-authentication...
  Installing authlogic...
  [...Git stuff...]

Of course not all Rails app template creators are going to choose the same plugins and gems as you. The recommendation system could incorporate some Bayesian mathematics or a neural network to learn your predilections and adapt. I see a great future for this. Somebody should get right on it.

Conclusion

The mining method seems sound, though, and the code works. All we need now is a shiny website!

Vertical Baseline Rhythm

2009-06-04T12:00:00Z

Why bother?

I spend my working life creating web apps. I do everything, but first and foremost I am a programmer. Although I like to think I have a good eye for web design — how things look — it’s “read only”: I know and appreciate a good design when I see it but I can’t create it myself.

Since I’m hopelessly out of my depth with every image editor on the market, including Acorn (“you don’t need a Ph.D in computer graphics”), I have been drawn increasingly to typography. Not in terms of designing typefaces but rather learning how to make text look better. You tend to use a calculator, not an image editor, so it’s more tractable for me.

Anyway, establishing a vertical baseline rhythm is one technique to improve the legibility of text. After reading Compose to a Vertical Rhythm, Designing for the Web, and Get Rhythm in Your Baseline, I thought I’d have a go on Girls in Football (in beta, so unfortunately you can’t see what I mean yet).

Helpful Tools

Sorting out the textual elements was straightforward. Two tools helped greatly: Slammer and DebugBar.

Slammer is an OS X app that floats a semi-transparent grid over other windows, allowing you to see at a glance whether your baselines are rhythmic. It does more, but this alone makes it indispensable.

DebugBar is an Internet Explorer plugin which comes closer to Firebug than anything else I’ve seen on IE. It has a DOM inspector, HTTP inspector, Javascript inspector and console, and more. I find it extremely useful for getting to the bottom of bizarre IE behaviour.

Stumbling Blocks

Once the textual elements are done, you are left with forms and images. Forms elements and buttons throw a spanner in the works because their sizes vary from browser to browser. Images disrupt the baseline rhythm unless their heights are an exact multiple of your line spacing — which generally they aren’t.

I haven’t tackled forms yet, but I did solve the image problem.

jQuery Plugin for Images

Geoffrey Grosenback mentioned a technique he had heard about for handling images: replace each image with a div of the same width and a height which is a multiple of the baseline rhythm, and set the image as the div’s background. Since the image is now in the background it won’t overflow the div and will therefore slot neatly into the baselines.

This avoids squashing the image, though it does mean chopping a little off if you round the height down to the nearest baseline.

Anyway, I made this into a jQuery plugin called rhythm which can be used like this:


  $(window).load(function() {
    $('img').rhythm();
  });

It works in Safari, Firefox and IE7.

You can see it in action on Girls in Football, or at least you will be able to when we come out of beta. For every image it calculates where the nearest baseline is and “rounds the image” up or down to it. When rounding down you lose a little bit of image, and when rounding up you gain a little whitespace.

It works really well, and it’s very satisfying to drop Slammer over the bottom of your page and find the vertical baseline rhythm still going strongly.

Now I need to apply everything I’ve learned to this site…

Managing Expectations

2009-05-27T15:12:00Z

The GUI is very limited, and I’m not really motivated to address that, or to give users the features they’re asking for. Similarly, I don’t take bug reports very seriously.

Paul Battley keeps it real

A Better Way To Import Legacy Data In Rails

2009-05-23T20:00:00Z

Do you have to run a Rails app alongside the legacy app it’s replacing? The legacy app remains the authority for some data, such as users, while the Rails app is the authority for other data.

I’m in this situation on one project. My Rails app is replacing a Mambo CMS piece by piece. Once the Mambo app is fully replaced the Rails app will be the authority for all data in the system. Until then, the Rails app must keep itself synchronised with the Mambo app’s data for those models where the Mambo app remains the authority.

In my Rails app eight models’ data must be imported from five legacy tables. Other models refer to those eight models so I need to maintain referential integrity.

Acts As Importable

My first effort at writing the import code was alright. It worked. Recently, though, I came across Tim Riley’s excellent acts_as_importable plugin and this has made all the difference. Before his plugin my code was a little ugly and its intent was obscure. Now, using his plugin, my code is clean, clear, and trivial to maintain.

Tim wrote a clear article explaining how to import legacy data into Rails. Two of his design decisions stood out for me:

The legacy models know how to turn themselves into non-legacy models, not vice-versa.
The legacy models don’t export themselves; a dedicated class has that responsibility.

I made three additions to Tim’s recipe.

First I made my legacy models read-only, using Jason Frame’s read_only_model plugin, just to be on the safe side. My client would be displeased if I accidentally wrote over any of his data.

Second I turned off Thinking Sphinx’s delta indexing before importing any data, turning it on again afterwards and re-indexing. Leaving the delta indexing on during the import would be a waste of resources and would significantly slow down the import.

Third I turned off auditing (using the acts_as_audited plugin) during the import process for a similar reason. The audit trail of who updated which record would become next to useless if swamped with tens of thousands of entries each night.

So my importer looks like this:


class Legacy::Importer
  def self.run
   disable_auditing
   disable_delta_indexing

   # The import (see Tim Riley's article)
   # ...

  ensure
    enable_auditing
    enable_delta_indexing
  end

  private

  def self.disable_delta_indexing
    ThinkingSphinx.deltas_enabled = false
  end

  def self.enable_delta_indexing
    ThinkingSphinx.deltas_enabled = true
  end

  @@audited_models = [ Member, Report ] # etc

  def self.disable_auditing
    @@audited_models.each { |m| m.disable_auditing }
  end

  def self.enable_auditing
    @@audited_models.each { |m| m.enable_auditing }
  end
end

Anyway, if you are in the same boat you should try out acts_as_importable. It certainly improved my import process.

Iceberg Development

2009-05-20T08:11:00Z

What I find personally frustrating is that for a lot of the most interesting projects, the hard work is the first 98%, after which there’s nothing “cool” to show. The final 2%, which is usually a day or two of work, produces the whiz-bang demos.

Yehuda Katz

How To Vendor Rails

2009-04-28T13:29:00Z

Today I was bitten by the incompatibility of Rack 1.0.0, Passenger 2.2.1, and Rails 2.3.2.1:

  undefined method `new' for "Rack::Lock":String (NoMethodError)

Since I had already (inadvertently) upgraded Rack, the solution was to upgrade both Passenger and Rails.

Upgrading Passenger to 2.2.2 was straightforward. Just remember to update the paths in your passenger.conf to point to the 2.2.2 version.

Upgrading Rails wasn’t quite as straightforward because the compatibility fixes aren’t yet available in the Rails gem. Instead we have to run our application against the latest stable branch, 2-3-stable.

To do this I vendored Rails as a Git submodule. This is nothing new but it’s the first time I’ve needed to do it.


$ git submodule add git://github.com/rails/rails.git vendor/rails
$ git commit -m "Vendored Rails edge as a submodule."

This got me running on edge Rails. To run on the 2-3-stable branch I then did:


$ cd vendor/rails/
$ git checkout origin/2-3-stable
$ cd ../..
$ git add vendor/rails
$ git commit -m "Pinned Rails to branch 2-3-stable as of 4b68deb."

Thanks to Graeme Mathieson, Ariejan de Vroom, Daniel Morrison and August Lilleaas for their helpful articles.

Locally this all worked fine but on deployment the vendor/rails directory wasn’t populated due to the way submodules work. You have to initialise and update them each time; happily Capistrano supports this with:

set :git_enable_submodules, true

At this stage it’s a good idea to use a remote cache:

set :deploy_via, :remote_cache

As and when I go back to running Rails from gems, I’ll remove references to the submodule in .gitmodules and .git/config, and then do:

$ git rm --cached vendor/rails

Thanks to Jose Cedeno via GitHub Guides.

Finally my application ran again and I could return to working on it rather than the infrastructure…

Avoid Typing RAILS_ENV All The Time

2009-04-10T16:35:00Z

I often log into my staging or production servers to run a Rake task or fire up the Rails console. I got fed up long ago with specifying the environment in every command. For example:


$ rake --trace db:migrate:redo RAILS_ENV=production
$ script/console production
$ rake ts:in RAILS_ENV=production

It just occurred to me to set the environment variable in, er, the environment (~/.bashrc):


export RAILS_ENV=production

And now I can log in and type simply what I want to type:


$ rake --trace db:migrate:redo
$ script/console
$ rake ts:in

I am so embarrassed that I didn’t think of this three years ago.

Thinking Sphinx and (Declarative) Authorisation

2009-04-10T14:34:00Z

Thinking Sphinx makes it wonderfully easy to search across multiple models:


ThinkingSphinx::Search.search 'Your query'

But what happens if your user is only allowed to see some of the data? On my current project, a signed-in user may see everything but a public user may only see part of the site. I need to restrict the search to what the user is allowed to see.

Fortunately what the user is allowed to see, in this case, depends on the class. For example a public user can see all news stories but no members’ profiles. It would be harder were a public user allowed to see only some news stories or only some members’ profiles.

First Solution

My first solution was to restrict the classes which Thinking Sphinx searches, using the handy :classes option:


class SearchController < ApplicationController

  def search
    if params[:q].blank?
      @results = []
    else
      @results = ThinkingSphinx::Search.search \
        params[:q],
        :page    => params[:page] || 1,
        :classes => authorised_classes
    end
  end

  private

  def authorised_classes
    [Forum, Member, Post, Review, Story, Team, Topic].select do |klass|
      permitted_to? :read, klass.to_s.tableize.to_sym
    end
  end

end

The array of classes holds all the classes with indexes. (In reality my app has twice as many but I omitted some for legibility.)

The permitted_to? method comes from Steffen Bartsch’s excellent declarative_authorization plugin. There are many different ways to handle authorisation but this is my favourite. It has elegantly solved every authorisation requirement I have ever had; it just feels right.

As an aside, the authorisation rules are declared in config/authorization_rules.rb:


authorization do
  role :guest do
    has_permission_on :forums,  :to => :read
    has_permission_on :posts,   :to => :read
    # etc
  end

  role :member do
    has_permission_on :forums,  :to => :read
    has_permission_on :members, :to => :read
    has_permission_on :posts,   :to => :read
    # etc
  end
end

privileges do
  privilege :manage, :includes => [:create, :read, :update, :delete]
  privilege :read,   :includes => [:index, :show, :search]
  privilege :create, :includes => :new
  privilege :update, :includes => :edit
  privilege :delete, :includes => :destroy
end

You can see that a guest may search forums and posts, but not members; a member can search all of them.

Second Solution

My search controller’s authorised_classes method worked perfectly, but I knew I was setting myself up for a fall in a few months’ time: as and when I added a new class to the domain, I would probably forget to add it to this array of indexed classes.

Of course Thinking Sphinx knows which of my classes have indexes, so we can leave it to Thinking Sphinx:


def authorised_classes
  ThinkingSphinx::indexed_models.select do |model|
    permitted_to? :read, model.tableize.to_sym
  end.map { |model| model.classify.constantize }
end

I think this is a pretty elegant way to integrate search and authorisation. Thanks to Pat Allan and Steffen Bartsch for writing high quality library code that makes my application code much easier to produce!

Deploying Thinking Sphinx

2009-04-10T13:14:00Z

This is how I like to deploy Thinking Sphinx. In summary:

Install Sphinx on the server.
Decide where you want Sphinx’s PID file and indexes in production.
Ignore Sphinx’s configuration and indexes in development.
Configure Capistrano to work with Thinking Sphinx.
Set up cron on the server to re-index your data regularly.

Instructions

1. Install Sphinx on the server.

On server:


$ curl -O http://www.sphinxsearch.com/downloads/sphinx-0.9.8.1.tar.gz
$ gzip -d sphinx-0.9.8.1.tar.gz 
$ tar xvf sphinx-0.9.8.1.tar 
$ cd sphinx-0.9.8.1
$ ./configure
$ make
$ sudo make install

And to make sure it installed correctly:


$ search

Sphinx 0.9.8.1-release (r1533)
Copyright (c) 2001-2008, Andrew Aksyonoff

Usage: search [OPTIONS] <word1>
...

2. Decide where you want Sphinx’s PID file and indexes in production.

I like all my PID files in /var/run/<process>. We also want to preserve Sphinx’s indexes across deployments.

In your app create config/sphinx.yml:


production:
  pid_file: /var/run/sphinx/searchd.pid
  searchd_files: /path/to/your/app/shared/db/sphinx

On server:

$ sudo mkdir /var/run/sphinx
$ sudo chown deploy:deploy /var/run/sphinx
$ mkdir -p /path/to/your/app/shared/db/sphinx

Adjust the ownership to suit your needs.

3. Ignore Sphinx’s configuration and indexes in development.

This isn’t really a deployment step but it needs to be done.

Add to .gitignore:


config/development/sphinx.conf
db/sphinx/*

4. Configure Capistrano to work with Thinking Sphinx.

Add this to your config/deploy.rb:


# Thinking Sphinx
namespace :thinking_sphinx do
  task :configure, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:configure RAILS_ENV=#{rails_env}"
  end
  task :index, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:index RAILS_ENV=#{rails_env}"
  end
  task :start, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:start RAILS_ENV=#{rails_env}"
  end
  task :stop, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:stop RAILS_ENV=#{rails_env}"
  end
  task :restart, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:restart RAILS_ENV=#{rails_env}"
  end
end

# Thinking Sphinx typing shortcuts
namespace :ts do
  task :configure, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:configure RAILS_ENV=#{rails_env}"
  end
  task :in, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:index RAILS_ENV=#{rails_env}"
  end
  task :start, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:start RAILS_ENV=#{rails_env}"
  end
  task :stop, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:stop RAILS_ENV=#{rails_env}"
  end
  task :restart, :roles => [:app] do
    run "cd #{current_path}; rake thinking_sphinx:restart RAILS_ENV=#{rails_env}"
  end
end

# http://github.com/jamis/capistrano/blob/master/lib/capistrano/recipes/deploy.rb
# :default -> update, restart
# :update  -> update_code, symlink
namespace :deploy do
  task :before_update do
    # Stop Thinking Sphinx before the update so it finds its configuration file.
    thinking_sphinx.stop
  end

  task :after_update do
    symlink_sphinx_indexes
    thinking_sphinx.configure
    thinking_sphinx.start
  end

  desc "Link up Sphinx's indexes."
  task :symlink_sphinx_indexes, :roles => [:app] do
    run "ln -nfs #{shared_path}/db/sphinx #{current_path}/db/sphinx"
  end
end

5. Set up cron on the server to re-index your data regularly.

Edit your cron table (crontab -e) and add something along the lines of:


0 * * * * cd /path/to/your/app/current && /usr/local/bin/rake RAILS_ENV=production thinking_sphinx:index >> /path/to/your/app/current/log/cron.log 2>&1

Long live the individual useful resource

2009-03-28T16:04:00Z

I don’t think most people realize how little site navigation matters anymore. Your site’s navigation is google, topic sites, blogs, and feeds. The “website” is dead. Long live the individual useful resource.

Ryan Tomayko

Note to self: links in Atom feeds

2009-03-21T12:45:00Z

There are two ways to refer to a resource in an Atom feed.

If you are in a Person construct, use the <uri/> element.
Everywhere else, use the Link construct’s <link/> element.

So for example if you are using Rails’ atom_feed helper, author blocks should look like:


  entry.author do |author|
    author.name 'Andy Stewart'
    author.uri 'http://airbladesoftware.com'
  end

The helper will generate <link/> elements whenever you use the :url or :root_url options.

You can validate your Atom feeds with the Feed Validator. Your feed needs to be publicly available to use the web version of the validator. Alternatively you can run the validator locally if you have Python.

The Economics of Renewable Energy

2009-02-26T11:29:00Z

“Rather than spending the majority of our time — let alone the mind-numbing sums of taxpayers’ money which make every sum mentioned in this report seem trivial — on propping up our ill-managed banks, we should rapidly launch some infrastructure projects that will secure the nation’s future. There are renewable energy projects of all sizes that would be appropriate, and future generations would thank us for pursuing them, rather than wondering with dismay how we stumbled into blackouts and failed to meet our goals for reducing carbon dioxide.”

Lord Broers, House of Lords motion to take note of the Report of the Economic Affairs Committee on The Economics of Renewable Energy