This was a partial post I was working on before I stopped the project, I might as well post it.

In the last post we wrote our Game model. In this post we will modify the games controller and views so players can create games.

Players need to be able to create games, delete games (forfeit), and display games but there they won’t ever update them. Let’s drop the functional tests for updating since that feature isn’t needed. When a user makes a move we could call that editing a game, but I prefer to think of it as creating a move (we’ll do the Move model later).

Let’s remove the following tests from test/functional/games_controller_test.rb:

   def test_should_get_edit
    get :edit, :id => 1
    assert_response :success
  end

  def test_should_update_game
    put :update, :id => 1, :game => { }
    assert_redirected_to game_path(assigns(:game))
  end

Now we can trim the edit, update actions from the app/controllers/games_controller.rb, and delete app/views/games/edit.rhtml.

Let’s require login to access the games controller, first add a test in test/functional/games_controller.rb:

  def setup
    @controller = GamesController.new
    @request    = ActionController::TestRequest.new
    @response   = ActionController::TestResponse.new
    login_as 'quentin'
  end
... snip ...
  def test_index_should_require_authenticated
    assert_requires_login {|c| c.get :index}
  end

  def test_new_should_require_authenticated
    assert_requires_login {|c| c.get :new}
  end

Now we add the code to make it pass in app/controllers/games_controller.rb:

  before_filter :login_required

We need to add some attributes to the Game model

So I’m working at Intentional Software now. I guess the previous post I made got their attention. I’m not planning any more work on this project, but I used Pente to learn C# for the new job. My work on that is more complete and is at http://mono-pente.sf.net — oh and it’s actually in C++ now.

I apologize for the long delay in posts, my parents were in town last week, and this week I’m catching up on homework. In the meantime I discovered an interesting programming paradigm that I’d been thinking about for awhile now, but didn’t know it had a name. It’s called intentional programming.

I really like the idea of allowing flexible levels of code abstraction. Wouldn’t it be great if software engineers could work the abstraction levels up from raw assembly to C-Style to Ruby style to DSL style using the same “language”? Then domain experts could work at the DSL level. Imagine being able to read the code at DSL level, and to “zoom in” on trouble parts to see what’s going on. Comments and external documentation shouldn’t even be necessary anymore. Instead you can just zoom out until it’s clear what the block you’re looking at does. This is already almost going on, but the abstraction levels are almost completely separated. We have assemblers, compilers, interpreters, and libraries. Putting all this into an integrated stack could be really powerful.

I also really like the idea of separating code source storage and presentation. Why are we all still working with ASCII fixed width text files? Source code should be stored as XML (or something like it) and the editor should present and allow us to edit it any way the programmer chooses. To one programmer the file looks like a standard text file w/ tabs and fixed width font, to another maybe it looks like a bunch of balloons connected with arrows. Maybe the first programmer is a software engineer and needs to be able to dig deeper down the abstraction layers, and the latter is the domain expert.

I’d like to see a “language” that has as close to zero primitives as possible. It should simply be able to translate one layer of abstraction to another. The terminal layer being assembly/machine code (or maybe even bytecode?). The programmer would be able to build as many abstraction layers on top as were needed. It wouldn’t have an if statement primitive, but in a library would have some “code” describing how to translate “if (true) then i = 1 + 0″ to the appropriate machine code. Instead of including “if”, “for”, “while”, etc as primitives in the language they should be in libraries. Then it would be possible to extend the syntax of the language. You could include a library that would let you write ANSI compliant C with for_each support on arrays perhaps. This last bit reminds me a bit of the .NET stuff where you can write code using different languages. I think it’s a bit different though as I believe .NET is just a collection of separate compilers that generate CLR code that can be interlinked. I’d like to see the “primitives” or even syntax of a language defined as much as possible in libraries that can be extended.

If the compiler were able to understand the mathematical properties of the machine code (like adding or subtracting 0 doesn’t change the number) then it could know that “i = 1 + 0″ is the same as “i = 1″. It could figure out on the fly what could be done statically at compile time and what needs to be done dynamically at runtime. It’s all still pretty rough in my mind, but I think there is a ton of potential for optimization. I think a lot of the ideas of generic programming fit in very well here.

I can’t really put it into concrete examples yet, but it’s really interesting as a dual-major hardware/software engineering student to see the differences between “programming” hardware and software. I think the software engineering community could really take some lessons from the hardware community. I love how I can describe how I want a block of logic to work using if’s/cases/boolean logic and the compiler will break down all the barriers I’ve set up to keep the code modular and optimize it down to a minimal set of logic equations. That seems pretty close to intentional programming. I’m writing what my intention is, and the compiler figures out how best to do it. When I write C I feel like I’m just using shorthand for assembly. I need to study how optimization works in today’s compilers, maybe it’s more like hardware than I think, but today’s programming languages are still based heavily on the principles of C which was initially intended to map quite directly to machine code.

Well this turned out to be a longer, and less organized post than I intended it to be. I really think there’s some great potential in a combination of this Intentional Programming idea and Generic Programming. I really need to read up on some of these ideas when I get a chance to see what work is already being done.

Update: There’s a great paper from the company Intentional Software that goes into really good detail on some of these ideas. If you find these ideas interesting, or don’t quite understand what the ideas mean I would highly recommend reading it.

In the last post we implemented a welcome controller that lets us sign up, in and out. Now we’re going to add a RESTful games resource to the project so users can manage games.

First let’s use the generator to give us a resource scaffold:

jake@jake-laptop:~/src/pente$ script/generate scaffold_resource game
      exists  app/models/
      exists  app/controllers/
      exists  app/helpers/
      create  app/views/games
      exists  test/functional/
      exists  test/unit/
      create  app/views/games/index.rhtml
      create  app/views/games/show.rhtml
      create  app/views/games/new.rhtml
      create  app/views/games/edit.rhtml
      create  app/views/layouts/games.rhtml
      create  public/stylesheets/scaffold.css
      create  app/models/game.rb
      create  app/controllers/games_controller.rb
      create  test/functional/games_controller_test.rb
      create  app/helpers/games_helper.rb
      create  test/unit/game_test.rb
      create  test/fixtures/games.yml
      exists  db/migrate
      create  db/migrate/002_create_games.rb
       route  map.resources :games
jake@jake-laptop:~/src/pente$

Now let’s define the columns for the games table in edit db/migrate/002_create_games.rb:

class CreateGames < ActiveRecord::Migration

  def self.up
    create_table :games do |t|
      t.column :black_player_id, :integer
      t.column :white_player_id, :integer
      t.column :current_player_id, :integer
      t.column :winning_player_id, :integer
      t.column :created_at, :datetime
      t.column :updated_at, :datetime
      t.column :ended_at, :datetime
    end
  end

  def self.down
    drop_table :games
  end

end

And migrate:

jake@jake-laptop:~/src/pente$ rake db:migrate
(in /home/jake/src/pente)
== CreateGames: migrating =====================================================
-- create_table(:games)
   -> 0.0163s
== CreateGames: migrated (0.0165s) ============================================

jake@jake-laptop:~/src/pente$

Let’s add in a couple fixtures to work with in our tests:

one:
  id: 1
  black_player_id: 1
  white_player_id: 2
  current_player_id: 1
  created_at: <%= 1.days.ago.to_s :db %>
  updated_at: <%= 12.hours.ago.to_s :db %>

two:
  id: 2
  black_player_id: 2
  white_player_id: 1
  winning_player_id: 2
  created_at: <%= 5.days.ago.to_s :db %>
  updated_at: <%= 2.days.ago.to_s :db %>
  ended_at: <%= 2.days.ago.to_s :db %>

Let’s associate it with players first defining some tests in test/unit/game_test.rb:

require File.dirname(__FILE__) + '/../test_helper'

class GameTest < Test::Unit::TestCase
  fixtures :games, :players

  def test_should_associate_with_players
    assert_equal 1, games(:one).black_player.id
    assert_equal 2, games(:one).white_player.id
    assert_equal 1, games(:one).current_player.id
    assert_equal 2, games(:two).winning_player.id
  end

end

Your tests will now fail so let’s add some code to app/models/game.rb:

class Game < ActiveRecord::Base
  belongs_to :black_player, :class_name => 'Player', :foreign_key => :black_player_id
  belongs_to :white_player, :class_name => 'Player', :foreign_key => :white_player_id
  belongs_to :current_player, :class_name => 'Player', :foreign_key => :current_player_id
  belongs_to :winning_player, :class_name => 'Player', :foreign_key => :winning_player_id
end

Let’s add associations to the player side starting with the tests in test/unit/player_test.rb:

... snip ...
  fixtures :players, :games
... snip ...
  def test_should_associate_with_games
    assert players(:aaron).black_games
    assert players(:aaron).white_games
    assert players(:quentin).current_games
    assert players(:aaron).won_games
  end
... snip ...

And to make it pass by adding to app/models/player.rb:

... snip ...
  has_many :black_games, :class_name => 'Game', :foreign_key => :black_player_id
  has_many :white_games, :class_name => 'Game', :foreign_key => :white_player_id
  has_many :current_games, :class_name => 'Game', :foreign_key => :current_player_id
  has_many :won_games, :class_name => 'Game', :foreign_key => :winning_player_id
... snip ...

Now I’m going to go through and add several tests and show the code required to make it pass.

test/unit/game_test.rb:

... snip ...
  def test_should_validate_presence_of_players
    g = games(:one)
    g.black_player_id = nil
    assert !g.valid?
    assert g.errors.on(:black_player_id)
    g = games(:one)
    g.white_player_id = nil
    assert !g.valid?
  end
... snip ...

app/model/game.rb

... snip ...
  validates_presence_of :black_player_id, :white_player_id
... snip ...

When you run your tests now the test we just wrote is passing, but we’ve broken another one! The generated functional test case contains a test that checks create. When we add validations to the model that won’t allow a model to be created with all of its attributes set to nil that test will break. We’ve got to modify the test to create a valid player.

test/functional/games_controller_test.rb:

... snip ...
  def test_should_create_game
    old_count = Game.count
    post :create, :game => { :black_player_id => 1, :white_player_id => 2 }
    assert_equal old_count+1, Game.count

    assert_redirected_to game_path(assigns(:game))
  end
... snip ...

Back to creating more tests:

test/unit/game_test.rb:

... snip ...
  def test_should_validate_players_different
    g = games(:one)
    g.black_player_id = g.white_player_id
    assert !g.valid?
    assert g.errors.on_base
  end
... snip ...

app/model/game.rb

... snip ...
  validate :players_different
... snip ...
  protected

  def players_different
    errors.add_to_base('Players must be different') if self.black_player_id == self.white_player_id
  end
... snip ...

test/unit/game_test.rb:

... snip ...
  def test_should_make_white_current_on_create
    g = Game.create(:white_player_id => 1, :black_player_id => 2)
    assert_equal g.white_player_id, g.current_player_id
  end
... snip ...

app/model/game.rb

... snip ...
  before_create :make_white_player_current
... snip ...
  protected

  def make_white_player_current
    self.current_player_id = self.white_player_id
  end
... snip ...

test/unit/game_test.rb:

... snip ...
  def test_should_declare_winner
    g = games(:one)
    before = Time.now
    g.declare_winner!(g.black_player_id)
    assert_equal g.black_player_id, g.winning_player_id
    assert_nil g.current_player_id
    assert g.ended_at.between?(before, Time.now)
    assert g.save
  end

  def test_should_raise_on_invalid_winner
    g = games(:one)
    assert_raise(Game::InvalidWinner) { g.declare_winner!(999) }
  end
... snip ...

app/model/game.rb

... snip ...
  def declare_winner!(winner_id)
    raise InvalidWinner unless
      [self.black_player_id, self.white_player_id].include?(winner_id)
    self.winning_player_id = winner_id
    self.current_player_id = nil
    self.ended_at = Time.now
  end
... snip ...

These tests will already pass because this is done automatically, but let’s put them in anyway:
test/unit/game_test.rb:

... snip ...
  def test_should_set_created_at
    before = Time.now
    g = Game.create(:black_player_id => 1, :white_player_id => 2)
    assert g.created_at.between?(before, Time.now)
  end

  def test_should_set_updated_at
    before = Time.now
    g = games(:one)
    g.save
    assert g.updated_at.between?(before, Time.now)
  end
... snip ...

So we’ve written a pretty complete Game model now and have a full test suite for it! Isn’t TDD nice? I made it look easy by copy/pasting the working tests and code, but there was some finageling on my part to get things to work. It’s better to iron out all the problems now though rather than attempting to use the class and discovering problems while I’m trying to write other code.

In the next part we’ll write the controller and views to handle the new Game model.

In the last post we created the Rails project and added authentication. In this post we will add a welcome controller.

Our welcome controller will be very simple for now. It will just have links for the options available to the user depending on if they’re logged in or not.

Let’s go ahead and generate the controller:

jake@jake-laptop:~/src/pente$ script/generate controller welcome

      exists  app/controllers/

      exists  app/helpers/

      create  app/views/welcome

      exists  test/functional/

      create  app/controllers/welcome_controller.rb

      create  test/functional/welcome_controller_test.rb

      create  app/helpers/welcome_helper.rb

jake@jake-laptop:~/src/pente$

Let’s add an index action. Since we’re using TDD let’s add a functional test in test/functional/welcome_controller_test.rb that fails because we don’t have one:

require File.dirname(__FILE__) + '/../test_helper'

require 'welcome_controller'# Re-raise errors caught by the controller.

class WelcomeController; def rescue_action(e) raise e end; end

class WelcomeControllerTest < Test::Unit::TestCase

def setup

    @controller = WelcomeController.new

    @request    = ActionController::TestRequest.new

    @response   = ActionController::TestResponse.new

  end

def test_should_have_index

    get :index

    assert_response :success

  end

end

Run the test:

jake@jake-laptop:~/src/pente$ rake

(in /home/jake/src/pente)

/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader.rb" "test/unit/player_test.rb"

Loaded suite /var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader

Started

.............

Finished in 0.086673 seconds.13 tests, 26 assertions, 0 failures, 0 errors

/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader.rb" "test/functional/sessions_controller_test.rb" "test/functional/welcome_controller_test.rb" "test/functional/players_controller_test.rb"

Loaded suite /var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader

Started

..............E

Finished in 0.137953 seconds.

1) Error:

test_should_have_index(WelcomeControllerTest):

ActionController::UnknownAction: No action responded to index

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/filters.rb:632:in `call_filter'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/filters.rb:638:in `call_filter'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/filters.rb:438:in `call'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/filters.rb:637:in `call_filter'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/filters.rb:619:in `perform_action_without_benchmark'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/benchmarking.rb:66:in `perform_action_without_rescue'

    /usr/lib/ruby/1.8/benchmark.rb:293:in `measure'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/benchmarking.rb:66:in `perform_action_without_rescue'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/rescue.rb:83:in `perform_action'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/base.rb:430:in `send'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/base.rb:430:in `process_without_filters'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/filters.rb:624:in `process_without_session_management_support'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/session_management.rb:114:in `process_without_test'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/test_process.rb:15:in `process'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/test_process.rb:382:in `process'

    /var/lib/gems/1.8/gems/actionpack-1.13.3/lib/action_controller/test_process.rb:353:in `get'

    ./test/functional/welcome_controller_test.rb:16:in `test_should_have_index'

15 tests, 26 assertions, 0 failures, 1 errors

/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader.rb"

Command failed with status (1): [/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems...]

/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake.rb:719:in `sh'

/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake.rb:726:in `call'

... snip ...

/var/lib/gems/1.8/bin/rake:18:in `load'

/var/lib/gems/1.8/bin/rake:18

rake aborted!

Test failures

(See full trace by running task with --trace)

jake@jake-laptop:~/src/pente$

Alright we’re in the red now so let’s implement the code:

app/controllers/welcome_controller.rb:

class WelcomeController < ApplicationController  def index

  end

end

app/views/welcome/index.rhtml:

Welcome!

Run the test agan and we’re in the green:

jake@jake-laptop:~/src/pente$ rake

(in /home/jake/src/pente)

/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader.rb" "test/unit/player_test.rb"

Loaded suite /var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader

Started

.............

Finished in 0.100943 seconds.13 tests, 26 assertions, 0 failures, 0 errors

/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader.rb" "test/functional/sessions_controller_test.rb" "test/functional/welcome_controller_test.rb" "test/functional/players_controller_test.rb"

Loaded suite /var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader

Started

...............

Finished in 0.145732 seconds.

15 tests, 27 assertions, 0 failures, 0 errors

/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader.rb"

jake@jake-laptop:~/src/pente$

Before we forget let’s get rid of the public/index.html file so when we use WEBrick we get the correct page. The file doesn’t hurt the tests, but this is a good time to remove it anyway, and while we’re at it we’ll map our welcome controller to ” so it shows up by default:

jake@jake-laptop:~/src/pente$ rm public/index.html

jake@jake-laptop:~/src/pente$

config/routes.rb:

ActionController::Routing::Routes.draw do |map|

  map.resource :players, :sessions

  map.connect '', :controller => "welcome"

  map.connect ':controller/:action/:id.:format'

  map.connect ':controller/:action/:id'

end

Now we want to add some useful links to the welcome page. So far the only think a user can do is signup, login and logout. Let’s add some tests to check for this functionality. I’m adding more than one test at a time here to speed things up since this is pretty basic:
test/functional/welcome_controller_test.rb:

require File.dirname(__FILE__) + '/../test_helper'

require 'welcome_controller'# Re-raise errors caught by the controller.

class WelcomeController; def rescue_action(e) raise e end; end

class WelcomeControllerTest  'a', :attributes => {'href' => x}

    end

  end

def test_should_have_links_when_logged_in

    login_as 'aaron'

    get :index

    ['/sessions/destroy'].each do |x|

      assert_tag :tag => 'a', :attributes => {'href' => x}

    end

  end

end

I’ve been doing a lot of thinking about REST and I think I’ve found a compromize that will keep all the main benefits of REST without any of the ugly javascript hacks. I will use RESTful URLs in links when it’s possible, but resort to classic Rails controller/action/id style links when it avoids an ugly Javascript hack. I still get the REST web API as I’m not disabling the REST interface, and the HTML doesn’t have the ugly hacks.

Now let’s make them pass by modifying app/views/welcome/index.rhtml:

<ul>

<% if logged_in? -%>

  <li><a href='/sessions/destroy'>Logout</a></li>

<% else -%>

  <li><a href='/sessions/new'>Login</a></li>

  <li><a href='/players/new'>Signup</a></li>

<% end -%>

</ul>

We’re now back in the green with a working welcome controller! From here on out I’m going to skip copy/pasting the test results when they all pass to save space and time. You might not be convinced the login controller is actually working because we haven’t actually seen it in the browser. That’s one of the great things about TDD. You don’t have to rely on randomly clicking links in a browser to make sure things are working. Go ahead and fire up WEBrick (scripts/server) and see for yourself!

I’m going to be saving all the HTML/CSS prettification for the end of the project and keep the interfaces plain for now.

In the next post I’ll add a games resource and tie it to the players resource.

I’ve introduced the concept of test driven development and REST and I’m finally ready to start writing some code on my Pente project. In this post I will setup the project, and generate and customize the player resource.

I’m going to assume that you’ve covered the basics already so I’ll go quickly over some of the basics.

Note: Since we’re using REST Rails must be at version 1.2 or better

The first step is to create your rails project:

jake@jake-laptop:~/src$ rails pente -d sqlite3
      create
      create  app/controllers
      create  app/helpers
      ... snip ...
      create  log/production.log
      create  log/development.log
      create  log/test.log
jake@jake-laptop:~/src$

I used “-d sqlite3″ so it would use sqlite3 for the databases. I find it much easier to develop using sqlite3 since you don’t need to setup mysql. When I deploy the app I’ll evaluate the different database options and might change the database then, but for now it’s sqlite3.

Next let’s install a plugin from Rick Olson called restful_authentication:

jake@jake-laptop:~/src/pente$ script/plugin install http://svn.techno-weenie.net/projects/plugins/restful_authentication/
+ ./restful_authentication/README
+ ./restful_authentication/Rakefile
... snip ...
+ ./restful_authentication/generators/authenticated/templates/unit_test.rb
+ ./restful_authentication/install.rb
Restful Authentication Generator
====

This is a basic restful authentication generator for rails, taken from acts as authenticated.  Currently it requires Rails 1.2 (or edge).

To use:

  ./script/generate authenticated user sessions --include-activation

The first parameter specifies the model that gets created in signup (typically a user or account model).  A model with migration is created, as well as a basic controller with the create method.

The second parameter specifies the sessions controller name.  This is the controller that handles the actual login/logout function on the site.

The third parameter (--include-activation) generates the code for a ActionMailer and its respective Activation Code through email.

You can pass --skip-migration to skip the user migration.

From here, you will need to add the resource routes in config/routes.rb.

  map.resources :users, :sessions

Also, add an observer to config/environment.rb if you chose the --include-activation option
  config.active_record.observers = :user_observer # or whatever you named your model

jake@jake-laptop:~/src/pente$

This plugin adds a generator for making RESTful authentication systems. Let’s use it to add a players resource using this generator:

jake@jake-laptop:~/src/pente$ script/generate authenticated player sessions -p

----------------------------------------------------------------------
Don't forget to:

  - add restful routes in config/routes.rb
    map.resources :players, :sessions
    map.activate '/activate/:activation_code', :controller => 'players', :action => 'activate'

Try these for some familiar login URLs if you like:

  map.signup '/signup', :controller => 'players', :action => 'new'
  map.login  '/login', :controller => 'sessions', :action => 'new'
  map.logout '/logout', :controller => 'sessions', :action => 'destroy'

----------------------------------------------------------------------

      exists  app/models/
      exists  app/controllers/
      ... snip ...
      create  db/migrate
      create  db/migrate/001_create_players.rb
jake@jake-laptop:~/src/pente$

It’s not hard to think of how to make players RESTful. Players map to resources quite easily. The authentication itself it a little trickier to think of RESTfully. Think about what you’re really doing when you login. You’re creating a login session. When you logout you’re destroying a login session. The login session itself is the REST resource.

Let’s add the REST resource to config/routes.rb, and while I’m at it I’ll clean it up a bit:

ActionController::Routing::Routes.draw do |map|
  map.resource :players, :sessions
  # map.connect '', :controller => "welcome"
  map.connect ':controller/:action/:id.:format'
  map.connect ':controller/:action/:id'
end

Now let’s run the players migration generated for us:

jake@jake-laptop:~/src/pente$ rake db:migrate
(in /home/jake/src/pente)
== CreatePlayers: migrating ===================================================
-- create_table("players", {:force=>true})
   -> 0.0072s
== CreatePlayers: migrated (0.0073s) ==========================================

jake@jake-laptop:~/src/pente$

And now let’s run the generated tests to make sure everything is working:

jake@jake-laptop:~/src/pente$ rake
(in /home/jake/src/pente)
/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader.rb" "test/unit/player_test.rb"
Loaded suite /var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader
Started
.............
Finished in 0.088721 seconds.

13 tests, 26 assertions, 0 failures, 0 errors
/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader.rb" "test/functional/sessions_controller_test.rb" "test/functional/players_controller_test.rb"
Loaded suite /var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader
Started
..............
Finished in 0.127973 seconds.

14 tests, 26 assertions, 0 failures, 0 errors
/usr/bin/ruby1.8 -Ilib:test "/var/lib/gems/1.8/gems/rake-0.7.3/lib/rake/rake_test_loader.rb"
jake@jake-laptop:~/src/pente$

And there it is. We’ve got a fully working authentication and signup mechanism! Let’s take a look at what was generated to understand what is really going on.

First Let’s look at the migration:

class CreatePlayers  true do |t|
      t.column :login,                     :string
      t.column :email,                     :string
      t.column :crypted_password,          :string, :limit => 40
      t.column :salt,                      :string, :limit => 40
      t.column :created_at,                :datetime
      t.column :updated_at,                :datetime
      t.column :remember_token,            :string
      t.column :remember_token_expires_at, :datetime

    end
  end

  def self.down
    drop_table "players"
  end
end

Some of the columns’ functions are pretty obvious (login, email, created_at, updated_at), but if you haven’t designed an authentication system before (I hadn’t really either) the other columns might be a bit of a puzzle.

• crypted_password – Well it’s not really encrypted, it’s a hash of the password. A hash cannot be directly decrypted back to the original password, but you can apply the same hash algorithm to the password given at login and determine if the hashes match. This way we don’t store the users’ actual passwords which makes for better security. Even if the hash database were stolen it would take a lot of processing power to determine even one user’s true password.
• salt – If the hashed password list is somehow stolen it is possible to use precomputed hash dictionaries to get weak passwords that are dictionary words or other obvious things. when the user picks or changes a password a random string is generated and stored in the salt column. Before the password hash is generated the salt is concatenated with the plaintext password. This means that even though two users might have the same password the randomly generated salt would mean they have different hashes. Therefore you can’t just calculate the hash for “password” and scan for matching hashes.
• remember_token – Instead of logging in every time the user visits the site a randomly generated token can be stored in a cookie in the user’s browser. This cookie is checked when the user visits the site and the user is automatically authenticated if the match.
• remember_token_expires_at – Whenever the token is checked this column is also checked to make sure that the token hasn’t expired. If it has then the user must be authenticated through standard means.

The generator adds a couple of files in lib for us. libs/authenticated_system.rb contains methods useful for inclusion in methods, controllers and views. lib/authenticated_test_helper.rb contains methods useful for testing controllers that require authentication.

Here are some of the highlights:

lib/authenticated_system.rb

    def logged_in?
      current_player != :false
    end
...
    def current_player
      @current_player ||= (session[:player] && Player.find_by_id(session[:player])) || :false
    end

The above methods are commonly referenced in the view and controller to determine if the user is logged in and if so who’s logged in.

lib/authenticated_system.rb

    def login_required
      username, passwd = get_auth_data
      self.current_player ||= Player.authenticate(username, passwd) || :false if username && passwd
      logged_in? && authorized? ? true : access_denied
    end
...
    def login_from_cookie
      return unless cookies[:auth_token] && !logged_in?
      user = Player.find_by_remember_token(cookies[:auth_token])
      if user && user.remember_token?
        user.remember_me
        self.current_player = user
        cookies[:auth_token] = { :value => self.current_player.remember_token , :expires => self.current_player.remember_token_expires_at }
        flash[:notice] = "Logged in successfully"
      end
    end

The above methods are intended to be used as before_filters for classes that need authentication.

module AuthenticatedTestHelper
  # Sets the current player in the session from the player fixtures.
  def login_as(player)
    @request.session[:player] = player ? players(player).id : nil
  end
...
  # Assert the block redirects to the login
  #
  #   assert_requires_login(:bob) { |c| c.get :edit, :id => 1 }
  #
  def assert_requires_login(login = nil)
    yield HttpLoginProxy.new(self, login)
  end

The above methods can be very useful when testing controllers that use authentication.

The generator gave us two resources. The sessions resource is a sort of “virtual” resource that doesn’t actually have a table in the database or a model but does have a controller and views. The players resource is more standard and has a table, model controller, and views.

We should move the includes from the two generated controllers to the application controller as shown. This way all controllers will have access to the helper methods:

class ApplicationController < ActionController::Base
  include AuthenticatedSystem
  before_filter :login_from_cookie

  # Pick a unique cookie name to distinguish our session data from others'
  session :session_key => '_pente_session_id'
end

We should also move the includes from the two generated controller functional tests to the test_helpers.rb so they will be available from all tests.

ENV["RAILS_ENV"] = "test"
require File.expand_path(File.dirname(__FILE__) + "/../config/environment")
require 'test_help'

class Test::Unit::TestCase
  ...snip...

  # Add more helper methods to be used by all tests here...
  include AuthenticatedTestHelper
end

The last thing the generator gave us was a set of tests and test fixtures to exercise the generated code. These are the tests we ran earlier.

We can experiment with signing up for accounts and logging in by starting WEBrick:

jake@jake-laptop:~/src/pente$ script/server
=> Booting WEBrick...
=> Rails application started on http://0.0.0.0:3000
=> Ctrl-C to shutdown server; call with --help for options
[2007-05-05 18:03:17] INFO  WEBrick 1.3.1
[2007-05-05 18:03:17] INFO  ruby 1.8.5 (2006-08-25) [i486-linux]
[2007-05-05 18:03:17] INFO  WEBrick::HTTPServer#start: pid=8278 port=3000

Open your browser and load http://localhost:3000/players/new and create an account. You can now log in at http://localhost:3000/sessions/new. There isn’t much to see yet when you log on. You will simply be redirected to the default Rails page. If you use an invalid account to login you will not be redirected.

I have decided to try and use REST design for my Pente project, and the purpose of this post is to ground readers on how I came to that decision.

There I was beginning to get comfortable with Rails. I was just starting to think I was hot stuff because I was learning the latest and greatest web framework on the tubes. Then I saw all this stuff about RESTful this and RESTful that. Well it turns out REST is yet another whole new can of worms.

ZZZZZZZZZZZZzzzz

No, RESTful Rails doesn’t involve closing your eyes while you program. REST stands for REpresentational State Transfer and was coined by Dr. Roy Fielding in his doctoral dissertation. Dr. Fielding is no slouch. Have you heard of the Apache webserver? He’s a co-founder. In his dissertation he essentially suggests we stick to the fundamental ideas in the HTTP standard when designing interactive web applications.

Most webpages today use two of the verbs HTTP defines: GET and POST. However, HTTP defines several others: HEAD, PUT, TRACE, DELETE, OPTIONS and CONNECT that aren’t supported by HTML forms and therefore not actively used in today’s web apps. REST design makes use of GET, POST, PUT and DELETE. REST also emphasizes the idea that the URI should not contain any verbs, only nouns and maybe some adjectives. The URI tells us what we’re doing something with and the HTTP verb tells us what to do with it.

Examples of non-RESTful URIs:

• /employees.php?id=5&action=delete
• /records/admin/create?documentid=45
• /users/1;edit
• /edit/users/1

Examples of RESTful URIs:

• /users
• /users/admins
• /users/1
• /users.php?id=1
• /posts/1/12/2007/my_day
• /posts/1/12/2007/my_day/comments
• /posts/1/12/2007/my_day/comments/5
• /posts/random

These RESTful URIs don’t really mean anything by themselves. For a webapp to service a request it needs to know what it should do something with and what to do with it. The URI tells you the former. With just the URI you cannot know what the client wants!

To get the complete story you also need to know the verb:

These should sound familiar to you. You’ve probably learned that Rails is designed around the idea of CRUD (Create, Read, Update, Destroy). Well these actions map quite well to the REST HTTP verbs.

Why?

Now you know what REST is, but so what? Why does it make a better app? There are many reasons. My favorite reason is that (at least in Rails) you get a nearly free web API by following RESTful techniques. Here’s a little bit of code generated for a games controller by Rails’ REST resource generator:

# GET /games/1
# GET /games/1.xmldef show @game = Game.find(params[:id])
respond_to do |format|
  format.html # show.rhtml
  format.xml  { render  ml => @game.to_xml }
end

The respond_to method make it easy to render the data in different ways. The RESTful generators automatically give you two formats: the standard HTML and a new XML format. Thanks to the .to_xml method we get built in on our models we just got a one line web API for this resource! REST is also just a good way to think about designing your app. If you use the REST design principles correctly it’s hard to end up with an ugly design. Finally by using the HTTP verbs as they are intended the browser and any proxies and routers that are relaying your HTTP between the client and server can do more intelligent caching with the data.

Just a minute here…

Remember how I said REST uses four HTTP verbs, but HTML only uses two? How can we write forms that delete or update resources if we can’t use the PUT and DELETE verbs? Well we really can’t be truly RESTful. Currently RAILS sort of sneaks the PUT and DELETE verbs in by assigning a “_method” parameter to fake it when setting up a form. My initial reaction to this was “yuck!”, and it still is, but I think it might be worth it. There is lots of ongoing discussion about the issue, but I’m not sure there will be a great solution until the HTML spec supports PUT and DELETE. In fact one of the URI’s I gave in the list of non-RESTful (/users/1;edit) is one that Rails uses when you generate a REST resource because nobody has come up with a perfect solution yet.

Don’t forget about one of REST’s big benefits. When used as a Web API you aren’t limited to GET and POST verbs. Any HTTP library worth its salt can make PUT and DELETE requests as well so there is no Javascript hackery involved. To experiment with a REST API you can use cURL (manpage) to generate pretty much any HTTP request you want.

Since it sounds like such a neat idea, and I’d like to have a web API for my Pente project I’m going to go ahead with REST design. I might get sick of all the javascript hacks and decide REST isn’t worth it, but I’m going to give it a shot.

Questions

• What do you think about REST?
• Do you think Dave’s RADAR is the correct answer to HTML’s failings?
• How would you get around HTML’s limitations to implement a REST design?

Want to Learn More about REST?

This post doesn’t cover the technical details of how to use REST in your rails application because there are already other resources that do a great job of that.

• Peepcode has a great screencast on REST I would highly recommend, the $9 is a steal.
• XML.com has a good article on RESTful Rails
• Topfunky has a good Cheetsheet for RESTful Rails development

Where to Next?

Look at my decision to use test driven development for Pente or follow along as I implement the project.

Software engineering has one big difference from all other engineering disciplines. If a civil engineer built a bridge without going through computer simulations, scale models, and rigorous review he would be jailed. If an aerospace engineer thought he found a new wing design and threw it on a passenger jet to see if it would work he and his grandchildren would be barred from engineering forever. Nobody thinks twice when a software engineer whips up a new function and runs it to see if it works. In this post I’ll introduce the concept of test driven development and explain why I will be using it for my Pente project.

Part of the agile/extreme programming movement is the notion of test driven development (TDD). The crux of the idea is that before you write any application code you should first write a test that fails because the code doesn’t exist. The big idea is Red, Green, Refactor. The official dogmatic TDD method is a bit more strict than I will demonstrate here, but this is how I have personally found the ideas of TDD to be useful.

This article assumes you are familiar with the basic Unit Testing features of Rails. There is a great resource on the Rails wiki that will help you learn what you need.

I highly recommend the book Test Driven Development by Example. It does a great job of introducing the need for test driven development and introducing the technique step by step.

1: Red

So you want your program to do something. Let’s say you want your Player model to validate the format of the email address. The first step is to write a test that fails because the Player model doesn’t validate the format of the email address.

def test_validate_email_invalid
  p = Player.new
  p.email = '@bedrock.com'
  assert !p.valid?
end

Run the test and watch it fail miserably. You’re now in the red! Don’t worry though, this is a good thing. You’re making progress. You’ve now defined how you want your code to work. You also know that your test fails properly. This is really important. If you write a test and never actually see it fail how do you know the test is working? The next step is to make it pass!

2: Green

The official dogmatic TDD approach is to write the dirtiest, ugliest, quickest code you can that will make your test pass. Personally I think that’s a bit much. One of the nice things about TDD is that if you are having trouble with a certain section of code, or want to be really sure that a piece of code is working perfectly you can always slow down and start doing really detailed tests, but if you’ve done a thing a thousand times and know it will probably work right away you can test in big chunks.

Let’s make our email validation test pass by adding this code to our model:

validates_format_of :email, :with => /.+@.+..+/

Run your test again and you’ll see that we’re passing! We’re back in the green!

3: Refactor

In the refactor phase you get the chance to make your code nicer. You can break out functions/classes and make your code look nicer. Since you’ve got all the things your code is supposed to do under test you’ll know you aren’t breaking any established functionality. Don’t forget to refactor the tests themselves too. Our example isn’t really complicated enough yet to require any refactoring, so let’s move on and dig ourselves back in the red.

4: Red

Our simple test got us some basic email validation, but there are still lots of bad addresses that will get through. Let’s improve it a bit:

def test_validate_email_invalid
  p = Player.new
  p.email = 'fl1nst0n3@bedr0ck.c0m'
  assert !p.valid?
  p.email = 'fflinstone@bedrock.theoffice'
  assert !p.valid?
  p.email = 'fflinstone'
  assert !p.valid?
  p.email = 'fflinstone@bedrock'
  assert !p.valid?
  p.email = '@bedrock.com'
  assert !p.valid?
  p.email = 'fflinstone@bedrock.c'
  assert !p.valid?
  p.email = 'fflin@stone@bedrock.com'
  assert !p.valid?
  p.email = 'fflinstone@bed_rock.com'
  assert !p.valid?
  p.email = 'fflinstone@bedrock..com'
  assert !p.valid?
  p.email = ''
  assert !p.valid?
  p.email = nil
  assert !p.valid?
end

def test_validate_email_valid
  p = Player.new
  p.email = 'fflinstone@bedrock.com'
  assert p.valid?
  p.email = 'fflinstone@bedrock.co.uk'
  assert p.valid?
  p.email = 'fflin_ston-e@bed-rock.com'
  assert p.valid?
  p.email = 'fflinstone@bedrock.museum'
  assert p.valid?
  p.email = 'fl1nst0n3@bedr0ck.com'
  assert p.valid?
  p.email = 'FLiN570nE@B3dR0ck.com'
  assert p.valid?
end

The modified test takes a big chunk out of our email validation problem by throwing in a whole bunch of possible problems with an email address. I took a bigger chunk because I have a regular expression that I’ve used before that I’m confident will solve this on the first try. If I didn’t I might just throw one problem in at a time and build a regular expression that would solve each new problem while not breaking old ones.

5: Green

Here’s the new code for the model:

validates_format_of :email, :with => /A[A-Z0-9._%-]+@(?:[A-Z0-9-]+.)+[A-Z]{2,6}Z/i

We should be passing all of our tests again, but the tests are a bit ugly, let’s move on.

6: Refactor

Now we can make our test code look a little nicer:

def test_validate_email_invalid
  p = Player.new
  ['fl1nst0n3@bedr0ck.c0m',
   'fflinstone@bedrock.theoffice',
   'fflinstone',
   'fflinstone@bedrock',
   '@bedrock.com',
   'fflinstone@bedrock.c',
   'fflin@stone@bedrock.com',
   'fflinstone@bed_rock.com',
   'fflinstone@bedrock..com',
   '',
   nil].each do |bad_email|
    p.email = bad_email
    assert !p.valid?
  end
end

def test_validate_email_valid
  p = Player.new
  ['fflinstone@bedrock.com',
   'fflinstone@bedrock.co.uk',
   'fflin_ston-e@bed-rock.com',
   'fflinstone@bedrock.museum',
   'fl1nst0n3@bedr0ck.com',
   'FLiN570nE@B3dR0ck.com'].each do |good_email|
    p.email = good_email
    assert p.valid?
  end
end

Now What?

Keep adding tests to express the desired behavior of your code, then make those tests pass. You’ll wind up with a fully tested codebase that makes adding new features and refactoring the code a dream because you can run the tests to know what functionality you’ve changed.

TDD is very hard at first, but if you stay committed and keep writing your tests before the code that makes them work it will become a natural process and writing untested code will start to give you the shivers.

Questions

• What do you think about TDD?
• If you’ve used TDD in a project how did it go?
• Have you ever had to refactor testless code?

Where to Next?

Read about my decision to use RESTful design or follow along as I implement the project.

I’m not going to try and recreate the wonderful getting started with Rails documents that exist all over the web. Instead I’m going to point you to the resources I found the most helpful when I started looking at Rails.

First: “Get Excited”!

Before we dig into the bowels of Ruby and Rails let’s get a taste of what it is we’re doing here. What’s so great about Rails? Does anybody actually use Rails?

1. Watch the official screencasts. They will give you a taste of what Rails is about quickly and visually.
2. One of the big questions I had when looking at Rails was: “Does this actually work in production?” The best way to answer this question is to show production websites that use Rails.

Next: Build a Solid Foundation

When I came to Rails I was mainly a C++ programmer. I had dabbled in PHP and other scripting languages, but Ruby was a completely new language to me. It was difficult to read some of the code in the Rails tutorials without knowing some of the unique Ruby syntax.

1. At this point it’s not necessary to completely learn Ruby before starting on Rails, but it is valuable to pick up on some of the basics. Luckily there is a fantastic interactive tutorial that has you covered.
2. Finally let’s get started with some basic Rails. There is a good list of tutorials at Top 12 Ruby on Rails Tutorials. My favorite is #3 Four Days on Rails, but your tastes may vary. Try a few and see what sticks.

Then: Getting Help

Once you’ve gone through the basic tutorials and understand the fundamentals of Ruby on Rails you’ll want to start writing code. At first it can be difficult to understand how to find the method you’re looking for, or what the error message you’re getting means, but there is help.

1. Though daunting at first, the API reference is extremely helpful once you learn to use it. Spend some time browsing through the classes and functions to get an idea of what is available.
2. The #rubyonrails IRC channel on irc.freenode.net is generally filled with friendly, helpful folks that are willing to answer stupid questions (don’t ask how I know). Even if you just spend some time lurking in the channel you’ll pick up all sorts of good tips.
3. If you’ve got a real stumper try the official group.

And Beyond: The Path to Enlightenment

Thirsty for more? Here’s some resources that will help you with your Rails fix.

1. Railscasts is a fantastic weekly screencast that gives a great tip every week with a high quality video.
2. Another very high quality Rails screencast site is Peepcode. They cost $9 each but go into good depth on the topics they cover and are well worth the price.
3. The Rails Podcast is a great way to get a sense of the Rails community. You get to hear prominent Rails developers talking about how they use Rails.
4. There are several great blogs about Rails that are quite worth reading.

Questions

• What’s your favorite Rails related resource?

Where to next?

You might want to look at some of the design decisions I made about my project or follow along as I implement the project.