Long story short: Ruby on Rails session handling does have some concurrency problems. Especially with AJAX requests this is a very potential scenario:

1. Request 1 loads user session
2. Request 2 loads user session
3. Request 1 stores something to the session
4. Request 2 stores something to the session
5. Request 1 writes its session data to the database
6. Request 2 writes its session data to the database

Now, of course whatever request 1 wrote there is pretty much lost. These bugs are hard to find, and in my case the site had been in production use for 18 months before this really became a problem.

I soon found out that Frederick Cheung had already written a plugin called Smart Session Store to handle these race conditions by locking the session row when needed. However, it didn’t work with the latest PostgreSQL drivers.

I’ve fixed this to work with combinations of the pg/postgers driver and Rails 2.2/2.3 in my smart_session_store fork. The tests are also now actually testing something. I’ve sent a pull request, so everyone should be able to enjoy it soon.

It’s really a good practice to somehow handle session concurrency even before it’s a problem, because these kinds of bugs tend to appear when you least expect it.

We can test this by adding two actions to our controller. They should both write something to the session, and the other one should sleep a while to make sure that its changes are likely to be lost.

The Firefox plugin, Ubiquity, is an awesome extendable Swiss knife command line of the web. The other day I noticed that Jack Dempsey had written a Ubiquity command for searching the Ruby documentation from APIdock. After quick googling, I found out that different people had done the same for Rails and RSpec as well, based on Jack’s command. Talk about community effort! Here are links to the Ubiquity commands (you need to have Ubiquity installed):

• Rails
• Ruby
• RSpec

I must not be the only one who occasionally wants to stop a Ruby on Rails application. There are long-running and risky database schema migrations and data migrations, and you don’t want users fiddling the system in the middle of the deployment.

With a Mongrel-based setup it was easy to set up a 503 (Service unavailable) error page and then just shut down all the Mongrels, so that Apache could give users a maintenance page. Using mod_rails (Phusion Passenger), only restart is supported out-of-the-box.

However, it’s possible to use mod_rewrite to prevent users from accessing your site during the deployment. Try this in your Apache virtual host configuration file:

# This option is not needed with Passenger >=2.1.1.
RailsAllowModRewrite on

ErrorDocument 503 /503.html

RewriteEngine on

RewriteCond %{DOCUMENT_ROOT}/../tmp/stop.txt -f
RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ /$1 [R=503,L]

Basically the last three lines mean:

1. If there is a tmp/stop.txt file
2. and user is requesting a file that does not directly exist in the file system
3. then return error 503 and render the appropriate maintenance page

It doesn’t actually stop your Rails processes, though. They will die when Passenger times out.

Now it’s also easy to incorporate this to your Capistrano configuration:

namespace :passenger do
  desc "Restart Passenger"
  task :restart, :roles => :app do
    run "touch #{current_path}/tmp/restart.txt"
  end

  desc "Stop Passenger"
  task :stop, :roles => :app do
    run "touch #{current_path}/tmp/stop.txt"
  end

  desc "Start (or un-stop) Passenger"
  task :start, :roles => :app do
    run "rm -f #{current_path}/tmp/stop.txt"
  end
end

After this it’s safe to deploy big new releases without completely taking down your Apache.

In addition to all kinds of general Ruby fame, Dr. Nic is the creator and maintainer of the Ruby on Rails Textmate bundle. Now, it seems that just a few hours ago he noticed that our Ville Lautanala aka Lautis had written a few good bugfixes and changes to the bundle. He then went ahead and merged them to the master branch.  And the real kicker here is, that among those changes was the change that adds APIdock-powered documentation macros. Let’s hope that this change sticks so all Rails codin’ Textmate users will be able to enjoy the rich documentation browsing that APIdock provides.

Will the Ruby bundle, which is also maintained by Dr. Nic, follow next?

Update: Origin of the bundle can be changed using following commands:

% cd ~/Library/Application\ Support/Textmate/Bundles/Ruby\ On\ Rails.tmbundle
% git remote rm origin
% git remote add -f -t master -m master origin git://github.com/drnic/ruby-on-rails-tmbundle.git

First came Vim, and next Gaizka added APIdock integration to Emacs. Now perhaps the biggest favorite of most Ruby and Rails developers, myself included: Textmate! Courtesy of one of Nodeta’s own, Ville Lautanala aka Lautis, you can get the Textmate bundles with APIdock goodness for Ruby and Rails from github with just a couple of simple git commands:

Now, the keyboard shortcut

gets you the page for the current word from APIdock.

As the Rails documentation discourse is really bubbling, our schedule has given us the sweet chance of taking a few steps back and let us concentrate on the first release of APIdock.

APIdock will be deployed today and we’ll import different versions of the included projects slowly for the next couple of days. The app will be completely usable during the version roll-out. Here are some of the most important changes from Rails-Doc.

Multiple projects

The most important difference of APIdock in relation to Rails-doc is of course multiple projects. You will be able to surf your way to APIdock.com and search and browse Ruby and RSpec documentation (in addition to Rails) with the same (except for the improvements that we’ve made) interface that you have been able to use in Rails-Doc. To begin with, the newest patch level of Ruby 1.8.6 will be included as we slowly roll older versions in. Ruby 1.9 will follow later if there proves to be a demand for it. Users wont yet be able to add their own projects, but we’ll provide an easy way to suggest new ones to be added.

In this first release, all the included projects will be listed in tabs, but later on when more projects are added, the idea is that users will be able to choose their “favorite” projects that will be shown as tabs. This way the app will be custom-made for each user.

We’ve added some project specific stuff like extensive project details and version history of the added versions. Behind the curtains the importing of new versions is done with a web interface.

Cross-project searching

When developing Rails applications, you are often faced with situations where you can’t be completely sure, whether a certain method comes from Ruby or Rails or somewhere else (like RSpec when writing tests). To help with this situation, in APIdock, after you have filled in a search term, you can simply click on another project to get the results for that same search term from that other project.

Moderators

We have also made our ACL more complex under the hood. We can now have moderators that have some extra rights like editing other users’ notes. This way we can give moderator rights to other people including some of our most active collaborators. If you’re interested in becoming a moderator, please contact us at team@apidock.com.

Rails-Doc => APIdock migration

Your Rails-Doc accounts will be preserved in APIdock, the notes will be where you wrote them and the thanks you’ve got won’t disappear either. Any URIs to the rails-doc.org domain will redirect to the correct page under apidock.com. There aren’t any drawbacks to the migration – no functionality is lost. The app was designed to support multiple projects right from the get-go and now that decision is paying off.

APIdock: what’s to come?

Rails-doc and APIdock has been our first Summer on Rails project, something we hope to be an annual feat. The general idea behind SOR is to hire young
talented developers to develop something cool and not-too-business-critical over the summer under the mentorship of some senior developers. We think
APIdock is a pretty awesome result and huge thanks go to our team of emerging Rails superstars:

• Hannu Pelkonen
• Jyri Tuulos
• Ville Lautanala

who did a great job even when the so-called mentors were often nowhere to be found. :)

The summer is starting to be over and that means the super-active development cycle of APIdock will slow down. We will continue to maintain the app, fix any bugs that are found and concentrate only on absolute key features.

Hopefully you’ll enjoy this first installment of APIdock. In any case, let us know what you think.

Our planned schedule and features held! Rails API documentation with versions support! Full search! OpenId support! Gravatarrrrs! Check it out!

Or install the Firefox Search plugin rrrright here and fire up that cracker!

Seriously though, the deployment was delayed by a small surge of bugs found right before the intended deployment window, so we are about 20 hours late. It took about four hours because of all the version-specific documentation generation. We are sorry for any inconveniences you may have experienced and we hope you’ll enjoy this installment of Rails-doc.

Today it’s become clear that Rails-doc 2.0 will be released in under two weeks, the current target being on 17 July. We’ve got a lot of stabilizing work ahead of us, all planned out for the next two weeks. The 2.0 release will include some vital features, the most important of them being…

Versions!

That’s right. It’s the feature that makes or breaks an app like Rails-doc. It’s the feature that has broken most apps like Rails-doc and it’s the feature that will make Rails-doc. In Rails-doc, you won’t have to choose which version’s documentation you want to browse or search, but instead you can view an older version of a certain method or class simply by clicking your favored version from our version time line. The time line features a visualization of the changes that have been made to that specific class or method. You can still find stuff that has been removed in newer versions and in fact we indicate deprecated methods and classes everywhere we list them.

Full text search and Firefox search plugin

We have implemented a full text search to complement our current lightning fast keyword search. If the keyword search runs dry, or if you simply prefer to, you can use the full text search that searches from the entire documentation plus notes that all of You have posted.

We’ve also wrapped up an awesome Firefox search plugin that uses both searches and produces a real power search. It’s a combined I’m-feeling-lucky and keyword search. What it does, is it puts you to the page that was retrieved as a first hit from the full text search and also fills your query to the keyword search so you get the best hit and the hits from the keyword search at once. If the first hit was the one you wanted you can just start browsing – a click anywhere on the page will hide the keyword search results. If you didn’t get lucky, check out the keyword results. And if they don’t have what you’re looking for, a simple press of the return key will take you to the full search results. This power search can be used by simple URLs so you can even link to them.

Other new features

• A dashboard for logged in users
• OpenId support
• Gravatars!
• Included In list for modules
• Tons of minor improvements

Probably the number one feature request we’ve gotten is that we would do to the Ruby API what Rails-doc has done to Rails API. We are not going to mix Ruby into Rails-doc, but we’ll be using Ruby as the primary pilot project when we first begin with APIdock.

Rails-doc.org 1.1 has just been deployed. It features:

• a revised front page with latest good notes
• search improvements
• fixes to some cache problems
• other minor fixes

We had a good first weekend and we are now getting a steady few thousand daily users. However, we still need more registered users to post more notes. I want to again thank Fabio Cevasco, who interviewed me and wrote an early review on Rails-doc. We also got noticed on Rails Inside and a dozen other blogs. Thanks to all who posted about us!

We got loads of nice and encouraging e-mails from users. We try to answer them as quickly as we can. Thanks for all the feedback!

Here is some proof to back up our overly lengthy tagline, Rails-doc is the first Rails documentation app that wasn’t developed by one guy in his underpants. Rails-doc.org has an actual team behind it – a team that employs an agile development process.

There’s hardly a better visualization of Scrum than a timelapse video! It shows the progress of our second sprint.