Blog Archives

Sharing code in FactoryGirl

Posted in Code, Inside TFG, Ruby on Rails, Tips and Tricks

Sharing Code

Sharing code between factories in FactoryGirl takes a little bit of effort. Here’s one way of accomplishing it, which I patched together from reading this GitHub Issue:

Sharing code in FactoryGirl

First, we create a module with the shared code. Then we include it into the FactoryGirl::SyntaxRunner. To keep your code organized I’d recommend you put all your shared modules for FactoryGirl in a single folder.

You can put it under something like spec/factories/support/ or spec/support/factory_girl_support/. In the following examples I’m going to use the latter.

So you might have a file like below:

# spec/support/factory_girl_support/user_support.rb

# I use a namespace here so there's no chance of overriding any other class or module.
module FactoryGirlSupport
  module UserSupport
    def some_shared_method
      "whatever you want to return!"
    end
  end
end

# This will make the methods in the FactoryGirlSupport::UserSupport available in your factories
FactoryGirl::SyntaxRunner.send(:include, FactoryGirlSupport::UserSupport)

Now you just need to require these files in your rails_helper.rb. You can do that with:

Dir[Rails.root.join("spec/support/factory_girl_support/**/*.rb")].each { |file| require file }

Now you can use the method in the module above in your factories like this:

FactoryGirl.define do
  factory :user do
    email { some_shared_method }
    name  { some_shared_method }
  end
end

That’s all there is to it.

Refactoring rails controllers the right way

Posted in Code, Inside TFG, Ruby on Rails, Tips and Tricks

Rails developers will often live by the mantra “Skinny Controller, Fat Model” when writing Rails controller code.

At first it can seem like a fairly reasonable practice. The examples in Darcy Laycock’s SitePoint article “10 Ruby on Rails Best Practices” are a great example of this. Another good example is Jamis Buck’s 2006 article “Skinny Controller, Fat Model”.

However, the name of the pattern is misleading and reinforces the noxious idea that any class should be “fat”.

In this article I will discuss ways that we can refactor Rails controllers that will not cause bloat in any models.

Skinny Controller, Fat Model

The “Skinny Controller, Fat Model” practice often results in code in controllers being moved into a model. This reduces the complexity of the controller and moves the responsibility of managing instances of the model back into the model itself. For example, if we have the following controller:

class EventsController < ApplicationController
  before_action :authenticate_user!
  after_action :verify_authorized

  def approve
    @event = Event.find(params[:id])
    @event.state = :approved
    @event.approved_at = Time.now
    @event.approved_by = current_user
    @event.save!

    redirect_to(root_path)
  end
end

The specs for the controller might look a bit like:

require 'rails_helper'

describe EventsController do
  describe 'PATCH approve' do
    subject { patch :approve, id: event.id }

    let(:event) { FactoryGirl.create(:event, approved: false) }

    context "when authenticated && authorized to approve the Event" do
      sign_in_as(:administrator)

      describe "approving the Event" do
        let(:current_time) { Time.now }

        before { Timecop.freeze(Time.local(1990)) }
        after  { Timecop.return }

        specify { expect { subject }.to change { event.reload.approved? }.to(true) }
        specify { expect { subject }.to change { event.reload.approved_by }.to(current_user) }
        specify { expect { subject }.to change { event.reload.approved_at }.to(current_time) }
      end

      it { should redirect_to(root_path) }
    end

    context "when not authenticated to approve the Event" do
      it_behaves_like "a controller action that has failed an authentication check"
    end

    context "when not authorized to approve the Event" do
      sign_in_as(:public_user)

      it_behaves_like "a controller action that has failed an authorization check"
    end
  end
end

The “Skinny Controller, Fat Model” practice might be followed by moving the approval code into the model, leaving the controller looking something like:

class EventsController < ApplicationController
  before_action :authenticate_user!
  after_action :verify_authorized

  def approve
    @event = Event.find(params[:id])
    @event.approve!(current_user)

    redirect_to(root_path)
  end
end

The process of approving an Event has been abstracted and defined in the Event model. Not only is our controller easier to understand, but the approval process is now re-usable and our tests for the controller are easier to write. For example, we could stub out the approve! method rather than having to check all the side effects of approving an Event. Here’s what our controller specs might look like now:

require 'rails_helper'

describe EventsController do
  describe 'PATCH approve' do
    subject(:approve_event) { patch :approve, id: event.id }

    let(:event) { FactoryGirl.create(:event, approved: false) }

    context "when authenticated && authorized to approve the Event" do
      sign_in_as(:administrator)

      it "approves the Event" do
        expect(event).to receive(:approve!).with(current_user)
        approve_event
      end

      it { should redirect_to(root_path) }
    end

    context "when not authenticated to approve the Event" do
      it_behaves_like "a controller action that has failed an authentication check"
    end

    context "when not authorized to approve the Event" do
      sign_in_as(:public_user)

      it_behaves_like "a controller action that has failed an authorization check"
    end
  end
end

However, there is a cost. The Event model has grown larger and the number of responsibilities in the Event model has increased. This makes the class harder to understand, which in turn means that:

  • The risk of defects being introduced is increased
  • Refactoring the class is more difficult
  • Tests are harder to read and write. When tests are hard to write, lazy developers sometimes “forget” to write them.
  • Most importantly: The code becomes a pain in the ass to work on

To prevent bloating our model, this workflow needs to be encapsulated in another class.

Encapsulating the workflow in a model

My preference for encapsulating such a workflow is to create another class. I just think of this class as another model, but some folk prefer to call them domain objects. Here’s a decent explanation from StackOverflow.

In the example above, I’d create a model called Event::Approver to encapsulate approving an Event.

I nest Event::Approver under Event because it is a subset of the workflows in the application that are related to the Event model.

Due to the way that Rails loads files, the file will need to be in the folder app/models/event. This is convenient since I can now look in this folder to find any workflows related to the Event model.

The Event::Approver model will look like:

class Event::Approver

  attr_reader :approver, :event

  def initialize(event, approver)
    @approver = approver
    @event = event
  end

  def approve!
    event.status = :approved
    event.approved_at = Time.now
    event.approved_by = approver
    event.save!
  end

end

The specs for this model will be equally concise, looking something like:

describe Event::Approver do
  describe "#approve!" do
    subject { Event::Approver.new(event, user).approve! }

    let(:event) { FactoryGirl.create(:event, approved: false) }
    let(:user)  { FactoryGirl.create(:user) }
    let(:current_time) { Time.now }

    before { Timecop.freeze(Time.local(1990)) }
    after  { Timecop.return }

    specify { expect { subject }.to change { event.reload.approved? }.to(true) }
    specify { expect { subject }.to change { event.reload.approved_by }.to(user) }
    specify { expect { subject }.to change { event.reload.approved_at }.to(current_time) }
  end
end

The implementation of this class is not especially important. For example, some developers will prefer not to use an initializer and will pass the event and approver directly into the approve! method.

This class is easy to understand as it has a single responsibility. The class is small enough that I can read it and understand it in only a few seconds. I don’t need to search in some 800 line of code Event model for this single method.

Similarly, the tests for the class are straight forward and easy to read and understand. The test file will be quite small, as opposed to the colossal test file that exists for the Event model.

One of the less thought about features of composing classes this way is that if I need to look at the git history for this class, 100% of the commits will be related to this single piece of functionality. I recently found out that is invaluable for when you need to work out why a process has changed. Imagine sifting through all the commits on the Event model trying to work out where function X changed (yeah, I know you can use grep – but what if the method name changed? A pain in the ass, for sure).

With our new model the controller would now look slightly different than before, but is just as skinny:

class EventsController < ApplicationController
  before_action :authenticate_user!
  after_action :verify_authorized

  def approve
    @event = Event.find(params[:id])
    Event::Approver.new(@event, current_user).approve!

    redirect_to(root_path)
  end
end

In defence of “Skinny Controller, Fat Model”

To be perfectly honest, I doubt the intention of “Skinny Controller, Fat Model” is to just blindly jam all your controller code into ActiveRecord models. I suspect it’s more likely that it means “Skinny Controllers, Fat Model Layer”.

That being said – I think it is all too easy for inexperienced developers to take the phrase literally and do just that. In fact, I have six years of experience working with developers who have zealously bloated ActiveRecord models to prevent controllers from having more responsibilities. Including myself for a time.

In summary…

When it comes to refactoring, cleaning up a controller doesn’t really benefit the health of your application if it causes a model to get dirtier.

Rather than adding more and more responsibilities to ActiveRecord models, we can create new single-purpose classes (domain objects, if you like) to encapsulate these workflows.

By doing this we make smaller classes that are easier to understand, easier to maintain, and easier to test.

Further Reading:

  1. “”Fat model, skinny controller” is a load of rubbish” by Jon Cairns
  2. “Skinny Controllers, Skinny Models” by Joe Ferris

Handling race conditions with Rails’ pessimistic locking

Posted in Code, Ruby on Rails, Tips and Tricks

I recently worked on a Rails application where race conditions were causing issues in the background tasks operating on my ActiveRecord objects. In this article I will explain how I used pessimistic locking to get around these issues.

Defining an example

Firstly, consider a sample Rails application with the following features/rules:

  1. Administrator can see a list of clients;
  2. Administrator can visit the client’s profile page and send an SMS to the client;
  3. Administrator cannot send more than one SMS to each client per day;

Let’s keep the implementation as simple as possible. Consider a Client model with an attribute last_sms_sent_on and the following class (which can be used by a controller or a Sidekiq task):

class ClientSMSSender
  def self.perform(client, message)
    client.transaction do
      if client.last_sms_sent_on.blank? || !client.last_sms_sent_on.today?
        client.last_sms_sent_on = Date.today
        client.save
        SMSGateway.send(client.phone_number, message)
      end
    end
  end
end

Analysing the race condition issue

Imagine that there are some external issues and SMSGateway.send hangs for an average of 30 seconds. In this meantime another administrator makes a new request to send an SMS to the client. Due to race conditions we’ll end up sending more than one message to the client on the same day.

This is what will happen:

  1. Administrator A makes a request (Request A) to send an SMS to the client
  2. Client has not received any messages today
  3. Request A is hanging due to external issues
  4. Administrator B make a new request (Request B) to send the same SMS to the client
  5. Client has not received any messages today (the Request A still hanging)
  6. Request B is hanging due to external issues as well
  7. Request A finishes and client.last_sms_sent_on is updated
  8. Request B still holding the previous state of the client object
  9. Request B finishes, send the SMS again and re-update client.last_sms_sent_on

Work around

In order to work around that issue, you can make use of the method with_lock from ActiveRecord::Locking::Pessimistic.

Have a look at the code below:

class ClientSMSSender
  def self.perform(client, message)
    client.with_lock do
      if client.last_sms_sent_on.blank? || !client.last_sms_sent_on.today?
        client.last_sms_sent_on = Date.today
        client.save
        SMSGateway.send(client.phone_number, message)
      end
    end
  end
end

Under the hood, with_lock:

  1. opens up a database transaction
  2. reloads the record (in order to obtain the last state of the record)
  3. requests exclusive access to the record from the database

When using with_lock: 

  1. Administrator A makes a request (Request A) to send an SMS to the client
  2. Request A locks the client record in database
  3. Client has not received any messages today
  4. Request A is hanging due to external issues
  5. Administrator B make a new request (Request B) to send the same SMS to the client
  6. As the client is currently locked by Request A, the Request B hangs until the database releases the record
  7. Request A finishes and client.last_sms_sent_on is updated
  8. Database releases the client record
  9. Request B (was hanging and waiting for database) now starts the execution
  10. Request B locks the client record
  11. Request B reloads the client record in order to obtain the latest state of the object
  12. Client has already received a message today
  13. Request B finishes without sending a new SMS.

If you’re still confused about that, here’s an easy way to see how with_lock works from your Rails console:

  1. Grab any existing Rails project and open up two Rails consoles
  2. In the first console execute the following:
    u = User.first
    u.with_lock do
      u.email = "test@thefrontiergroup.com.au"
      u.save
      sleep 40 # emulates a very slow external process
    end
    
  3. In the second console execute:
    u = User.first
    u.email = "test2@thefrontiergroup.com.au"
    u.save
    

You’ll notice in the second console that the execution of u.save will hang until the first console finishes the whole process.  You should be careful not to lock your entire app unnecessarily, otherwise you’re likely to introduce a new bottleneck.

Conclusion

The method with_lock is handy, but use it sparingly. Sticking with_lock everywhere might bring you good business logic consistency, but it can come at the expense of performance.

Using CanCan to implement an “Agree to Terms” workflow

Posted in Code, Inside TFG, Ruby on Rails

Terms & Conditions
Recently in a Rails application I was tasked with adding in a basic “terms and conditions” page.

There was nothing special about the feature, but I was really happy with my solution so I decided to write about it briefly.

Thinking about a solution

So, my initial plan was:

  1. Add a agreed_to_term_and_conditions_at datetime field to the User model. Use a datetime here so that if we change the conditions later we can check against the time.
  2. Perform checks in the app to prevent users that haven’t agreed to the terms and conditions will be redirected to the T&C workflow

Step 1 was straight forward, but step 2 got me thinking.

Initially I had considered implementing a before_filter in ApplicationController that would check whether the User had agreed to the T&Cs and redirect them to the T&Cs page if they hadn’t.

After thinking for a moment I decided that it was really a question of authorization, and as a result should be managed by an Ability file.

The reasoning I used is that I would say a user should not be able to access the site until they had agreed to the terms. That sounds suspiciously like a cannot statement in CanCanCan.

Implementing a solution with CanCanCan

Once I had decided to use CanCanCan to implement the solution, it was just a matter of getting all the parts together.

Firstly, I had my abilities split into separate files in the way I have suggested in this post. I had an Ability::Factory that would take a User (or nil) and return the appropriate ability file. It looks something like:

class Ability::Factory

  def self.build_ability_for(user)
    return Ability::Anonymous.new if user.nil?

    case user.role
    when :admin
      Ability::Admin.new(user)
    when :supervisor
      Ability::Supervisor.new(user)
    when :doctor
      Ability::Doctor.new(user)
    when :patient
      Ability::Patient.new(user)
    else
      raise(Ability::UnknownRoleError, "Unknown role passed through: #{user.role}")
    end
  end

end

My initial idea was to do some checks for each role and basically say something like:

if user.has_agreed_to_terms_and_conditions?
  # Implement abilities as per usual
else
  cannot :manage, :all
end

But that would lead to a lot of duplication in both implementation and tests. Plus, just a lot of code in general, which I despise.

Thinking further, I decided that a User who hadn’t agreed to the terms and conditions had a set of abilities of their own, independently to their role. I created a new Ability for such a condition: Ability::PendingAgreementToTermsAndConditions. The class was implemented like:

class Ability::PendingAgreementToTermsAndConditions < Ability

  def initialize(user)
    cannot :manage, :all
    can :agree_to_terms_and_conditions, User, id: user.id
  end

end

I amended my Ability::Factory so that it would return the pending ability in the right conditions:

class Ability::Factory

  def self.build_ability_for(user)
    return Ability::Anonymous.new if user.nil?

    if user.has_agreed_to_terms_and_conditions?
      ability_class_for(user.role).new(user)
    else
      Ability::PendingAgreementToTermsAndConditions.new(user)
    end
  end

private

  def ability_class_for(role)
    case role
    when :admin
      Ability::Admin
    when :supervisor
      Ability::Supervisor
    when :doctor
      Ability::Doctor
    when :patient
      Ability::Patient
    else
      raise(Ability::UnknownRoleError, "Unknown role passed through: #{user.role}")
    end
  end

end

Great, so now I had all the abilities I needed. It was time to incorporate the logic into my controller so the application would handle users who hadn’t agreed to the T&Cs.

I had to ensure two things:

  1. Users can’t access other pages in the app that aren’t the T&Cs. When they do, they will be redirected to the T&Cs page.
  2. When a user who hasn’t agreed to the T&Cs signs in, they are redirected to the T&Cs page.

Handling access to pages when terms and conditions aren’t agreed to

Regarding the first objective: Anyone who has used CanCan or CanCanCan will know that since the ability file prohibits users from accessing other pages (cannot :manage, :all), a CanCan::AccessDenied exception will be raised if those pages are hit.

That means that I just had to handle that exception, and redirect the user to the T&Cs page. The CanCanCan README explains how to catch this exception in detail, but I’ll post the code I used anyway:

class ApplicationController < ActionController::Base

  rescue_from CanCan::AccessDenied do |exception|
    if current_user.present?
      # You could also do: current_ability.can?(:agree_to_terms_and_conditions, current_user)
      # but I think the following reads better
      if current_user.has_agreed_to_terms_and_conditions?
        # Redirect as usual
      else
        # Redirect to the terms page
      end
    else
      # Do whatever for unauthed users
    end
  end

end

Moving on, let’s ensure the user isn’t sent straight to another redirect when they sign in.

Redirecting users to the terms and conditions page when they sign in

This is a problem for your authentication system. I use devise, so I was able to override the after_sign_in_path_for method in my ApplicationController as outlined in the documentation. The code looks like:

class ApplicationController < ActionController::Base

  # Override: Devise method
  def after_sign_in_path_for(user)
    # You could also do: current_ability.can?(:agree_to_terms_and_conditions, current_user)
    # but I think the following reads better
    if user.agreed_to_terms_and_conditions_at.present?
      # Redirect as usual
    else
      # Redirect to the terms page
    end
  end

end

Now the user will get one redirect, instead of being redirected to a page they can’t access.

Conclusion

So that’s my solution. About 20 extra lines of code (plus tests) and now you’ve got all the logic for implementing a terms and conditions workflow.

I really enjoyed implementing that solution. It was easy to write and has had no maintenance cost.

Separating abilities in CanCan

Posted in Code, Inside TFG, Ruby on Rails

Users and Authorization
Authorization is simple to implement in Rails thanks to gems like CanCan and its chubby cheeked offspring CanCanCan. When getting started with CanCanCan, the documentation suggests that you use the generator to create a single Ability file to store your abilities in. This is a great starting point, but in my experience few projects using CanCanCan ever evolve past the use of a single Ability file – much to their detriment.

In this post I’ll have a look at an example Ability file and enumerate some flaws in such a system. Following that I’ll discuss a way to improve it by breaking the Ability file out into multiple Ability files.

Defining a real-world example

Let’s imagine a somewhat complicated application that has:

4 different roles, that may have the ability to perform up to 50 different actions.

For some context, let’s say the application stores medical imaging scans (ultrasounds and so forth) and has the following roles:

  1. Patients that sign in and view information about their scans, and can grant access to their scans to doctors.
  2. Doctors that sign in and add notes and attach dictations to these scans, and can look over all their patients’ scans.
  3. Supervisors that sign in and manage the doctors, assigning them to hospitals and medical practices. Assigning patients to doctors.
  4. Admins that sign in and manage all the above user accounts, and perform basic CRUD for hospitals and medical practices.

An Ability file for such an application might look like:

class Ability
  include CanCan::Ability

  def initialize(user)
    # Anonymous users don't have access to anything
    return if user.nil?

    case user.role
    when :admin
      can :manage, :all
    when :supervisor
      # Between 1-50 can/cannot statements
    when :doctor
      # Between 1-50 can/cannot statements
    when :patient
      # Between 1-50 can/cannot statements
    else
      raise(Ability::UnknownRoleError, "Unknown role passed through: #{user.role}")
    end
  end

end

 

The problems with a single Ability file

As you can see, if we have many different abilities per user this file will get quite large.

Let’s say that there are very few shared abilities and that for each of the supervisor, doctor, and patient roles we have 50 lines of ability declarations. That equates to roughly 170 lines of code in the file. Historically, I’ve found that spec to implementation ratio is about 2:1, so let’s imagine there’s a 340 line spec file that corresponds to this implementation.

There are many problems with an Ability file of this size.

  1. Larger files are harder to understand, maintain, and debug. There are just too many different concepts for a developer to deal with in one location, many of which will be irrelevant for whatever their task at hand is.
  2. Spec files becomes even harder to maintain for larger implementations. Since spec:code ratio can bloat in excess of 2:1, it will be even harder to maintain the specs.
  3. The Ability file will have far too many responsibilities, violating the Single Responsibility Principle and suffering from the drawbacks of such behaviour. This boils down to a higher maintenance cost and defect rate. If you don’t like OO sophistry, let me put it another way: The file tries to do too much. The class answers the question “what can every user in the system conceivably do?”. Whereas, we are far more likely to be interested in what just one of those users can do at any given time.
  4. In a similar vein, the Ability class becomes a god class for authorization. I feel like CanCan and CanCanCan only encourage this behaviour by having an opaque default for determining which Ability to use. By default, CanCanCan will assume that you have an Ability class in its current_ability function. There is a section in the GitHub wiki on changing this, though.
  5. Large classes and files suffer from the broken windows theory – that is: since the class is already so massive and bloated, new developers on the project will just pile more functionality on top of the existing mess – despite the cost in readability and maintainability. Further, the scope of the class starts to spread as more and more code is tacked on. You might hear such excuses from developers as “I’m just following the convention of the existing app” or “look, it’s already screwed so it’s not like I can make it any worse”. You may also hear my favourite “we don’t have budget to refactor”. Yeah, if you don’t have budget to refactor imagine how much budget you DON’T have for fixing defects all the time because you keep piling shit on more shit.

Deconstructing the monolithic Ability file

In order to resolve the issues above, we must break the Ability file apart. Usually, my first tactic is to identify the responsibilities of the class and break the code out into classes that represent each of these responsibilities.

Let’s review the responsibilities of the Ability class above:

  1. It defines what an anonymous user can do (EG: handling user.nil?)
  2. It defines what an admin can do
  3. It defines what a supervisor can do
  4. It defines what a doctor can do
  5. It defines what a patient can do
  6. It handles unknown roles

Now we create a class for each of those responsibilities. Which would leave us with classes like:

  1. AnonymousUserAbility – basically a null object for abilities.
  2. AdminAbility
  3. SupervisorAbility
  4. DoctorAbility
  5. PatientAbility, and
  6. UserAbilityFactory (or Ability::Factory if using namespaces), which takes a User (or nil) and returns the corresponding Ability class above. This class also handles roles without defined abilities by raising an exception.

You may also like to keep an Ability file that includes the CanCan::Ability module and contains some shared functions that will be used in the other ability files.

You should store these files in app/abilities. They are not models as defined by MVC, so they don’t belong in app/models, which is where CanCan and CanCanCan stash the Ability file by default.

You may also like to namespace these classes (EG: Ability::AnonymousUser), since namespaces can also improve the organisation of an application.

An example of one of the Ability files is:

class Ability::Patient < Ability

  def initialize(user)
    [:show, :invite_doctor].each do |ability|
      can ability, Result, patient_id: user.id
    end
    # etc
  end

end

Now I can have private methods that are specific to just the abilities of the Patient, rather than private methods being for all the different roles. I have a single function that can tell me the sum total of a Patient’s abilities. I can include some additional documentation in the class explaining the role of the Patient in our application for future developers.

Let’s have a look at the Ability::Factory now. I named this class after the factory pattern since its job is to take a User (or nil) and build us a corresponding Ability file. If you wanted, you could just put the function in Ability. I prefer the new class implementation, which would look like:

class Ability::Factory

  def self.build_ability_for(user)
    return Ability::Anonymous.new if user.nil?

    case user.role
    when :admin
      Ability::Admin.new(user)
    when :supervisor
      Ability::Supervisor.new(user)
    when :doctor
      Ability::Doctor.new(user)
    when :patient
      Ability::Patient.new(user)
    else
      raise(Ability::UnknownRoleError, "Unknown role passed through: #{user.role}")
    end
  end

end

The corresponding controller change to get CanCan or CanCanCan to play nice with your new Abilities would be:

class ApplicationController

  # Override CanCan method to provide custom Ability files
  def current_ability
    @current_ability ||= Ability::Factory.build_ability_for(user)
  end

end

Please note: If you are using an additional engine like RailsAdmin or ActiveAdmin, some more work might need to be done in order to get the engine to play nice. You will have to do some spelunking the engine’s codebase to determine how CanCan or CanCanCan is integrated.

Conclusion

Now our large Ability file is broken into smaller, more manageable files. Each file now has a single responsibility and is easier to test. If we need to add a new role it won’t be a nightmare to patch the Ability file. We just build a new file and ensure it is in the Ability::Factory. Luckily, since our factory handles unknown roles by raising an exception, we’ll find out pretty quickly if there’s no corresponding Ability file.

Having a single file per role increases the ease with which we can verify the responsibilities of that role. We can read a single file and determine exactly what the Patient does, for example. Before, it was hidden in the guts of the Ability file.

When it comes to authorization, you want as high a level of visibility as you can on roles, so you don’t have anyone doing things they shouldn’t be able to.

Search Posts

Featured Posts

Categories

Archives

View more archives