Rails and Merb Merge: Plugin API (Part 3 of 6)

I started off this series on the Rails/Merb merge (aka Rails 3) talking about modularity, and then performance. Next up, plugins!

When we announced the Rails/Merb merge, we promised to bring a more stable plugin API to Rails 3. Merb had strong opinions about an explicitly exposed plugin API, so we hoped to end the complications of alias_method_chain in favor of exposed APIs which plugin authors could rely on across versions.

Dogfooding

By far the most important element in developing the plugin APIs for Rails 3 was to eliminate the “secret” APIs used in Rails itself. Instead, we wanted to build Rails on top of the same core components that we would ask plugin authors to build on. The focal point of this effort (because we already had experience doing this with Merb) was ActionPack, and specifically ActionController.

ActionController presented us with another excellent opportunity: because ActionMailer reused a lot of the controller functionality, we had a built-in opportunity to create components that could be used in both ActionController and ActionMailer. In a sense, ActionController and ActionMailer would become plugins of the core system we were creating.

We also took a second important conceptual step. In Rails 2.3, the idea of “metal” was that you could skip the entire ActionController chain and write raw Rack handlers where needed for performance. In Rails 3, we are exposing an incremental series of components that, in sum, make up ActionController::Base. These components include rendering, layouts, conditional get, respond_to, streaming, and others.

In Rails 3, ActionController::Metal is the simplest possible controller, with no additional components added in. ActionController::Base is simply a subclass of ActionController::Metal with all components included. Again, we are dog-fooding our componentized APIs, not simply giving you a watered down version of what we use internally.

Now, let’s dig into a few specific examples of new APIs.

ActionController::Renderers

One of the most common reasons people extend controllers is to expose additional renderers. For instance, you may want to render a PDF as well as HTML. The Rails 3 API that we expose to plugin authors for this purpose is identical to the one that we use internally. (As you probably know, in addition to being able to render templates, you can render :json, :xml, or :js in normal Rails controllers.)

If you take a look at the source for ActionController::Renderers, here’s how we do it:

add :json do |json, options|
  json = ActiveSupport::JSON.encode(json) unless json.respond_to?(:to_str)
  json = "#{options[:callback]}(#{json})" unless options[:callback].blank?
  self.content_type ||= Mime::JSON
  self.response_body  = json
end

This method is in ActionController::Renderers, so it’s like saying ActionController::Renderers.add(:json) do |json, options|. You can add additional renderers easily in Rails 3 plugins, and you don’‘t have to figure out how to hook into Rails at the appropriate time. Like other parts of the public API, we’re committing to keeping this API unchanged across multiple versions of Rails. If and when when the API DOES change, the change will be flagged for you first, via the normal Rails API deprecation process.

ActionController::Metal

In Rails 3, there’s a supported way to use a simple, stripped down controller, and opt into the functionality you want. The overhead of the completely stripped down controller is a mere 8 microseconds (not much more than the overhead for a pure Rack app), compared with 100 or so microseconds of overhead for the full ActionController::Base (as I said last time, this itself is significantly less than Rails 2.3).

Here’s an example of using ActionController::Metal:

class SimpleController < ActionController::Metal
  abstract!
end

class HelloController < SimpleController
  def index
    self.response_body = "Hello World"
  end
end

A few things to note here. First of all, you don’t need a superclass, but you can build one to re-use in multiple places. The abstract! declaration tells Rails 3 not to include public methods on the superclass as controller actions. It’s not strictly needed here (because there are no public methods), but it’s a good habit for custom ActionController::Metal subclasses. Second of all, because this is a controller, you can route to it through the normal Rails router. From the perspective of the rest of Rails, this is a perfectly normal controller.

Finally, the self.response_body usage is the simple, low-level API used in ActionController itself (for instance, during template rendering), but it’s now 100% first-class and available for your use. You can also set status, content_type and headers directly, regardless of whether you use the Request and Response helpers or not.

If you want to add rendering in, you can do something like this:

class SimpleController < ActionController::Metal
  abstract!
  include ActionController::Rendering
  append_view_path "#{Rails.root}/app/views"
end

class HelloController  "hello"
  end
end

You’ve now added in a new module, which provides rendering support. This keeps things simple by not including layout support, because you don’t need it in this case. With this capability, you can add the features that you want to add, leaving out what you don’t. This means that as a metal grows, you don’t need to completely rewrite it as a “normal” controller. Instead, you can pull in the specific features you need. This process is seamless, and again, you can route to it as a normal controller throughout.

If you look at the source for ActionController::Base, you can see that we aren’t doing anything particularly special anymore:

module ActionController
  class Base < Metal
    abstract!

    include AbstractController::Callbacks
    include AbstractController::Layouts

    include ActionController::Helpers
    helper :all # By default, all helpers should be included

    include ActionController::HideActions
    include ActionController::UrlFor
    include ActionController::Redirecting
    include ActionController::Rendering
    include ActionController::Renderers::All
    include ActionController::ConditionalGet
    include ActionController::RackDelegation
    include ActionController::Logger
    include ActionController::Configuration
    ...

Here, ActionController::Base inherits from Metal, and then proceeds to pull in all of the functionality not exposed as separate modules. Although Base pulls them all in, you don’t have to worry about dependencies between these modules; handling dependencies is built into the way these modules work.

View Contexts

As one last example, the way that ActionController communicates with ActionView itself has become a fully defined, exposed API. From the perspective of ActionController, a view implements three APIs:

• Context.for_controller(controller)
• Context#render_partial(options)
• Context#render_template(template, layout, options)

By implementing this API, you can drop in any object in place of ActionView. How would you use this? Well to date, I can think of two examples: rspec_rails is going to use this functionality to implement isolation tests, and you can use this to implement a Merb shim in which the controller and view are the same object (an implementation using an earlier version of the API).

In addition to the usefulness of exposing this functionality via a stable Public API, reducing the boundary between ActionController and ActionView significantly improved the architecture, and exposed areas of brittleness that benefited quite a bit from the definition.

Conclusion

The APIs provided here, while stable at this point, are not final. If you feel that they (or any other part of Rails 3) aren’t adequate for a plugin you’re building, please let us know by commenting.

This post is just a taste of the new ways you can extend Rails 3. In the weeks ahead, expect a lot more documentation and discussion about the exposed plugin hooks.