Controllers are often the eyesore of a Rails application. Controller actions are bloated despite our attempts to keep them skinny, and even when they look skinny, it is often an illusion. We move the complexity to various before_actions, without reducing said complexity. In fact, it often requires significant digging around and mental compilation to get a feel for the control flow of a particular action. 

After using service objects for a while in the Tuts+ dev team, it became apparent that we may be able to apply some of the same principles to controller actions. We eventually came up with a pattern that worked well and pushed it into Aldous. Today I will look at Aldous controller actions and the benefits they can bring to your Rails application.

The Case for Breaking Out Every Controller Action Into a Class

Breaking out each action into a separate class was the first thing we thought of. Some of the newer frameworks such as Lotus do this out of the box, and with a little bit of work Rails could also take advantage of this.

Controller actions that are a single if..else statement are a straw man. Even modest-sized apps have a lot more stuff than that, creeping into the controller domain. There is authentication, authorization, and various controller-level business rules (e.g. if a person goes here and they are not logged in, take them to the sign in page). Some controller actions can get quite complex, and all the complexity is firmly in the realm of the controller layer.

Given how much a controller action can be responsible for, it seems only natural that we encapsulate all of that into a class. We can then test the logic much more easily, as we would hopefully have more control of the lifecycle of that class. It would also allow us to make these controller action classes much more cohesive (complex RESTful controllers with a full complement of actions tend to lose cohesion quite rapidly). 

There are other problems with Rails controllers, such as the proliferation of state on controller objects via instance variables, the tendency for complex inheritance hierarchies to form, etc. Pushing controller actions into their own classes can help us address some of those as well.

What to Do With the Actual Rails Controller

Without a lot of complex hacking on the Rails code, we can't really get rid of controllers in their current form. What we can do is turn them into boilerplate with a tiny amount of code to delegate to the controller action classes. In Aldous, controllers look like this:

class TodosController < ApplicationController
  include Aldous::Controller

  controller_actions :index, :new, :create, :edit, :update, :destroy
end

We include a module so that we have access to the controller_actions method, and we then state which actions the controller should have. Internally, Aldous will map these actions to correspondingly named classes in the controller_actions/todos_controller folder. This is not configurable just yet, but can easily be made so, and it is a sensible default.

A Basic Aldous Controller Action

The first thing we need to do is to tell Rails where to find our controller action (as I've mentioned above), so we modify our app/config/application.rb like so:

config.autoload_paths += %W(
  #{config.root}/app/controller_action
)

config.eager_load_paths += %W(
  #{config.root}/app/controller_action
)

We're now ready to write Aldous controller actions. A simple one might look like this:

class TodosController::Index < BaseAction
  def perform
    build_view(Todos::IndexView)
  end
end

As you can see it looks somewhat similar to a service object, which is by design. Conceptually an action is basically a service, so it makes sense for them to have a similar interface.

There are, however, two things that are immediately non-obvious:

• where BaseAction comes from and what's in it
• what build_view is

We will cover BaseAction shortly. But this action is also using Aldous view objects, which is where build_view comes from. We're not covering Aldous view objects here and you don't have to use them (although you should seriously consider it). Your action can easily look like this instead:

class TodosController::Index < BaseAction
  def perform
    controller.render template: 'todos/index', locals: {}
  end
end

This is more familiar and we'll stick to this from now on, so as not to muddy the waters with view-related stuff. But where does the controller variable come from?

What the Constructor for an Action Looks Like

Let's talk about the BaseAction that we saw above. It is the Aldous equivalent of ApplicationController, so it is strongly recommended you have one. A bare-bones BaseAction is:

class BaseAction < ::Aldous::ControllerAction
end

It inherits from ::Aldous::ControllerAction and one of the things that it inherits is a constructor. All Aldous controller actions have the same constructor signature:

attr_reader :controller

def initialize(controller)
  @controller = controller
end

What Data is Directly Available From the Controller Instance

Being what they are, we've tightly coupled Aldous actions to a controller and so they can do just about everything a Rails controller can do. Obviously you have access to the controller instance and can pull whatever data you want from there. But you don't want to be calling everything on the controller instance—that would be a drag for common things like params, headers, etc. So, via a little bit of Aldous magic, the following things are available on the action directly:

• params
• headers
• request
• response
• cookies

And you can also make more things available in the same way via an initializer config/initializers/aldous.rb:

Aldous.configuration do |aldous|
  aldous.controller_methods_exposed_to_action += [:current_user]
end

More on Aldous Views or Not

Aldous controller actions are designed to work well with Aldous view objects, but you can opt not to use the view objects if you follow a few simple rules.

Aldous controller actions are not controllers, so you have to always provide the full path to a view. You can't do:

controller.render :index

Instead you have to do:

controller.render template: 'todos/index'

Also, since Aldous actions are not controllers, you won't be able to have instance variables from these actions automatically be available in the view templates, so you have to provide all data as locals, e.g.:

controller.render template: 'todos/index', locals: {todos: Todo.all}

Not sharing state via instance variables can only improve your view code, and more explicit rendering won't hurt too much either.

A More Complex Aldous Controller Action

Let's look at a more complex Aldous controller action and talk about some of the other things Aldous gives us, as well as some of the best practices to writing Aldous controller actions.

class TodosController::Update < BaseAction
  def default_view_data
    super.merge(todo: todo)
  end

  def perform
    controller.render(template: 'home/show',            locals: default_view_data) and return unless current user
    controller.render(template: 'defaults/bad_request', locals: {errors: [todo_params.error_message]}) and return unless todo_params.fetch
    controller.render(template: 'todos/not_found',      locals: default_view_data.merge(todo_id: params[:id])) and return unless todo
    controller.render(template: 'default/forbidden',    locals: default_view_data) and return unless current_ability.can?(:update, todo)


    if todo.update_attributes(todo_params.fetch)
      controller.redirect_to controller.todos_path
    else
      controller.render(template: 'todos/edit', locals: default_view_data)
    end
  end

  private

  def todo
    @todo ||= Todo.where(id: params[:id]).first
  end

  def todo_params
    TodosController::TodoParams.build(params)
  end
end

The key here is for the perform method to contain all or most of the relevant controller-level logic. First we have a few lines to handle the local preconditions (i.e. things that need to be true in order for the action to even have a chance of succeeding). These should all be one-liners similar to what you see above. The only unsightly thing is the 'and return' which we have to keep adding. This would not be an issue if we were to use Aldous views, but for now we're stuck with it. 

If the conditional logic for the local precondition gets too complex, it should be extracted into another object, which I call a predicate object—this way the complex logic can easily be shared and tested. Predicate objects may become a concept within Aldous at some point.

After the local preconditions are handled, we need to perform the core logic of the action. There are two ways to go about this. If your logic is simple, as it is above, just execute it right there. If it is more complex, push it into a service object and then execute the service. 

Most of the time our action's perform method should be similar to the one above, or even less complex depending on how many local preconditions you have and the possibility of failure.

Handling Strong Params

Another thing you see in the above action class is:

TodosController::TodoParams.build(params)

This is another object that inherits from an Aldous base class, and these are here in order for multiple actions to be able to share strong params logic. It looks like so:

class TodosController::TodoParams < Aldous::Params
  def permitted_params
    params.require(:todo).permit(:description, :user_id)
  end

  def error_message
    'Missing param :todo'
  end
end

You supply your params logic in one method and an error message in another. You then simply instantiate the object and call fetch on it to get the permitted params. It will return nil in the event of error.

Passing Data to Views

Another interesting method in the action class above is:

def default_view_data
  super.merge(todo: todo)
end

When you use Aldous view objects there is some magic that uses this method, but we're not using them, so we need to simply pass it as a locals hash to any view that we render. The base action also overrides this method:

class BaseAction < ::Aldous::ControllerAction
  def default_view_data
    {
      current_user: current_user,
      current_ability: current_ability,
    }
  end

  def current_user
    @current_user ||= FindCurrentUserService.perform(session).user
  end

  def current_ability
    @current_ability ||= Ability.new(current_user)
  end
end

This is why we need to make sure to use super when we override it again in child actions.

Handling Before Actions via Precondition Objects

All of the above stuff is great, but sometimes you have global preconditions, which need to affect all or most of the actions in the system (e.g. we want to do something with the session before executing any action, etc.). How do we handle that?

This is a good part of the reason for having a BaseAction. Aldous has a concept of precondition objects—these are basically controller actions in everything but name. You configure which action classes should be executed before every action in a method on the BaseAction, and Aldous will automatically do this for you. Let's have a look:

class BaseAction < ::Aldous::ControllerAction
  def preconditions
    [Shared::EnsureUserNotDisabledPrecondition]
  end

  def current_user
    @current_user ||= FindCurrentUserService.perform(session).user
  end

  def current_ability
    @current_ability ||= Ability.new(current_user)
  end
end

We override the preconditions method and supply the class of our precondition object. This object might be:

class Shared::EnsureUserNotDisabledPrecondition < BasePrecondition
  delegate :current_user, :current_ability, to: :action

  def perform
    if current_user && current_user.disabled && !current_ability.can?(:manage, :all)
      controller.render template: 'default/forbidden', 
        status: :forbidden, 
        locals: {errors: ['Your account has been disabled']}
    end
  end
end

The above precondition inherits from BasePrecondition, which is simply:

class BasePrecondition < ::Aldous::Controller::Action::Precondition
end

You don't really need this unless all your preconditions will need to share some code. We simply create it because writing BasePrecondition is easier than ::Aldous::Controller::Action::Precondition.

The above precondition terminates the execution of the action since it renders a view—Aldous will do this for you. If your precondition doesn't render or redirect anything (e.g. you simply set a variable in the session) then the action code will execute after all the preconditions are done. 

If you want a particular action to be unaffected by a particular precondition, we use basic Ruby to accomplish this. Override the precondition method in your action and reject whichever preconditions you like:

def preconditions
  super.reject{|klass| klass == Shared::EnsureUserNotDisabledPrecondition}
end

Not that dissimilar to regular Rails before_actions, but wrapped in a nice 'objecty' shell.

Error-Free Actions

The last thing to be aware of is that controller actions are error-free, just like service objects. You never need to rescue any code in the controller action perform method—Aldous will handle this for you. If an error occurs, Aldous will rescue it and utilise the default_error_handler to handle the situation.

The default_error_handler is a method you can override on your BaseAction. When using Aldous view objects it looks like this:

def default_error_handler(error)
  Defaults::ServerErrorView
end

But since we're not, you can do this instead:

def default_error_handler(error)
  controller.render(
    template: 'defaults/server_error',
    status: :internal_server_error,
    locals: {errors: [error]}
  )
end

So you handle the non-fatal errors for your action as local preconditions, and let Aldous worry about the unexpected errors.

Conclusion

Using Aldous you can replace your Rails controllers with smaller, more cohesive objects which are a lot less of a black box and are much easier to test. As a side-effect you can reduce coupling throughout your whole application, improve how you work with views, and promote reuse of logic in your controller layer via composition.

Better yet, Aldous controller actions can co-exist with vanilla Rails controllers without too much code duplication, so you can start using them in any existing app you are working with. You can also use Aldous controller actions without committing to using either view objects or services unless you want to. 

Aldous has allowed us to decouple our development speed from the size of the application we're working on, while giving us a better, more organised codebase in the long run. Hopefully it can do the same for you.