COOKIES AND SESSIONS 435

redirect_to

Redirect to the referrer.

redirect_to(:back)

Redirects to the URL given by the HTTP_REFERER header in the current request.

def save_details

unless params[:are_you_sure] == 'Y' redirect_to(:back)

else

...

end end

By default all redirections are flagged as temporary (they will affect only the current request). When redirecting to a URL, it’s possible you might want to make the redirection permanent. In that case, set the status in the response header accordingly.

headers["Status" ] = "301 Moved Permanently" redirect_to("http://my.new.home")

Because redirect methods send responses to the browser, the same rules apply as for the rendering methods—you can issue only one per request.

21.2Cookies and Sessions

Cookies allow web applications to get hash-like functionality from browser sessions: you can store named strings on the client browser that are sent back to your application on subsequent requests.

This is significant because HTTP, the protocol used between browsers and web servers, is stateless. Cookies provide a means for overcoming this limitation, allowing web applications to maintain data between requests.

Rails abstracts cookies behind a convenient and simple interface. The controller attribute cookies is a hash-like object that wraps the cookie protocol. When a request is received, the cookies object will be initialized to the cookie names and values sent from the browser to the application. At any time the application can add new key/value pairs to the cookies object. These will be sent to the browser when the request finishes processing. These new values will be available to the application on subsequent requests (subject to various limitations, described in a moment).

Here’s a simple Rails controller that stores a cookie in the user’s browser and redirects to another action. Remember that the redirect involves a round-trip to the browser and that the subsequent call into the application will create a new controller object. The new action recovers the value of the cookie sent up from the browser and displays it.

Report erratum

COOKIES AND SESSIONS 436

Download e1/cookies/cookie1/app/controllers/cookies_controller.rb

class CookiesController < ApplicationController def action_one

cookies[:the_time] = Time.now.to_s redirect_to :action => "action_two"

end

def action_two

cookie_value = cookies[:the_time]

render(:text => "The cookie says it is #{cookie_value}") end

end

You must pass a string as the cookie value—no implicit conversion is performed. You’ll probably get an obscure error containing private method ‘gsub’ called... if you pass something else.

Browsers store a small set of options with each cookie: the expiry date and time, the paths that are relevant to the cookie, and the domain to which the cookie will be sent. If you create a cookie by assigning a value to cookies[name], you get a default set of these options: the cookie will apply to the whole site, it will expire when the browser is closed, and it will apply to the domain of the host doing the setting. However, these options can be overridden by passing in a hash of values, rather than a single string. (In this example, we use the groovy #days.from_now extension to Fixnum. This is described in Chapter 15,

Active Support, on page 247.)

cookies[:marsupial] = { :value

=> "wombat",

:expires => 30.days.from_now,

:path

=> "/store" }

The valid options are :domain, :expires, :path, :secure, and :value. The :domain and

:path options determine the relevance of a cookie—a browser will send a cookie back to the server if the cookie path matches the leading part of the request path and if the cookie’s domain matches the tail of the request’s domain. The :expires option sets a time limit for the life of the cookie. It can be an absolute time, in which case the browser will store the cookie on disk and delete it when that time passes,3 or an empty string, in which case the browser will store it in memory and delete it at the end of the browsing session. If no expiry time is given, it is treated as if it were an empty string. Finally, the :secure option tells the browser to send back the cookie only if the request uses https://.

The problem with using cookies is that some users don’t like them and disable cookie support in their browser. You’ll need to design your application to be

3. This time is absolute and is set when the cookie is created. If your application needs to set a cookie that expires so many minutes after the user last sent a request, you either need to reset the cookie on each request or (better yet) keep the session expiry time in session data in the server and update it there.

Report erratum

COOKIES AND SESSIONS 437

robust in the face of missing cookies. (It needn’t be fully functional; it just needs to be able to cope with missing data.)

Cookies are fine for storing small strings on a user’s browser but don’t work so well for larger amounts of more structured data. For that, you need sessions.

Rails Sessions

A Rails session is a hash-like structure that persists across requests. Unlike raw cookies, sessions can hold any objects (as long as those objects can be marshaled), which makes them ideal for holding state information in web applications. For example, in our store application, we used a session to hold the shopping cart object between requests. The Cart object could be used in our application just like any other object. But Rails arranged things such that the cart was saved at the end of handling each request and, more important, that the correct cart for an incoming request was restored when Rails started to handle that request. Using sessions, we can pretend that our application stays around between requests.

There are two parts to this. First, Rails has to keep track of sessions. It does this by creating (by default) a 32 hex character key (which means there are 1632 possible combinations). This key is called the session id, and it’s effectively random. Rails arranges to store this session id as a cookie (with the key _session_id) on the user’s browser. As subsequent requests come into the application from this browser, Rails can recover the session id.

Second, Rails keeps a persistent store of session data on the server, indexed by the session id. When a request comes in, Rails looks up the data store using the session id. The data that it finds there is a serialized Ruby object. It deserializes this and stores the result in the controller’s session attribute, where the data is available to our application code. The application can add to and modify this data to its heart’s content. When it finishes processing each request, Rails writes the session data back into the data store. There it sits until the next request from this browser comes along.

What should you store in a session? You can store anything you want, subject to a few restrictions and caveats.

•There are some restrictions on what kinds of object you can store in a session. The details depend on the storage mechanism you choose (which

we’ll look at shortly). In the general case, objects in a session must be serializable (using Ruby’s Marshal functions). This means, for example, that you cannot store an I/O object in a session.

•If you store any Rails model objects in a session, you’ll have to add model declarations for them. This causes Rails to preload the model class so that its definition is available when Ruby comes to deserialize it from the

marshal

֒→ page 641

serialize

֒→ page 641

Report erratum

COOKIES AND SESSIONS 438

session store. If the use of the session is restricted to just one controller, this declaration can go at the top of that controller.

class BlogController < ApplicationController

model :user_preferences

# . . .

However, if the session might get read by another controller (which is likely in any application with multiple controllers), you’ll probably want to add the declaration to application_controller.rb in app/controllers.

•You probably don’t want to store massive objects in session data—put them in the database, and reference them from the session.

•You probably don’t want to store volatile objects in session data. For example, you might want to keep a tally of the number of articles in a blog and store that in the session for performance reasons. But, if you do that, the count won’t get updated if some other user adds an article.

It is tempting to store objects representing the current logged-in user in session data. This might not be wise if your application needs to be able to invalidate users. Even if a user is disabled in the database, their session data will still reflect a valid status.

Store volatile data in the database, and reference it from the session instead.

•You probably don’t want to store critical information solely in session data. For example, if your application generates an order confirmation number in one request and stores it in session data so that it can be saved to the database when the next request is handled, you risk losing that number if the user deletes the cookie from their browser. Critical information needs to be in the database.

There’s one more caveat, and it’s a big one. If you store an object in session data, then the next time you come back to that browser your application will end up retrieving that object. However, if in the meantime you’ve updated your application, the object in session data may not agree with the definition of that object’s class in your application, and the application will fail while processing the request. There are three options here. One is to store the object in the database using conventional models and keep just the id of the row in the session. Model objects are far more forgiving of schema changes than the Ruby marshaling library. The second option is to manually delete all the session data stored on your server whenever you change the definition of a class stored in that data.

Report erratum

COOKIES AND SESSIONS 439

The third option is slightly more complex. If you add a version number to your session keys and change that number whenever you update the stored data, you’ll only ever load data that corresponds with the current version of the application. You can potentially version the classes whose objects are stored in the session and use the appropriate classes depending on the session keys associated with each request. This last idea can be a lot of work, so you’ll need to decide whether it’s worth the effort.

Because the session store is hash-like, you can save multiple objects in it, each with its own key. In the following code, we store the id of the logged-in user in the session. We use this later in the index action to create a customized menu for that user. We also record the id of the last menu item selected and use that id to highlight the selection on the index page. When the user logs off, we reset all session data.

Download e1/cookies/cookie1/app/controllers/session_controller.rb

class SessionController < ApplicationController def login

user = User.find_by_name_and_password(params[:user], params[:password]) if user

session[:user_id] = user.id redirect_to :action => "index"

else reset_session

flash[:note] = "Invalid user name/password" end

end

def index

@menu = create_menu_for(session[:user_id]) @menu.highlight(session[:last_selection])

end

def select_item

@item = Item.find(params[:id]) session[:last_selection] = params[:id]

end

def logout reset_session

end end

As is usual with Rails, session defaults are convenient, but we can override them if necessary. In the case of sessions, the options are global, so you’ll typically set them in your environment files (config/environment.rb or one of the files in config/environments).4 You access the session options in the hash ActionController::Base.session_options. For example, if you want to change the cookie

4. There’s one exception to this—you can’t set the session expiry time this way.

Report erratum

COOKIES AND SESSIONS 440

name used by your application (which is pretty much mandatory if you plan on running more than one Rails application from the same host), you could add the following to the environment file.

ActionController::Base.session_options[:session_key] = 'my_app'

The available session options are

:session_domain

The domain of the cookie used to store the session id on the browser. Defaults to the application’s host name.

:session_id

Overrides the default session id. If not set, new sessions automatically have a 32-character id created for them. This id is then used in subsequent requests.

:session_key

The name of the cookie used to store the session id. You’ll want to override this in your application, as shown previously.

:session_path

The request path to which this session applies (it’s actually the path of the cookie). The default is /, so it applies to all applications in this domain.

:session_secure

If true, sessions will be enabled only over https://. The default is false.

:new_session

Directly maps to the underlying cookie’s new_session option. However, this option is unlikely to work the way you need it to under Rails, and we’ll discuss an alternative in Section 21.5, Time-Based Expiry of Cached Pages, on page 461.

:session_expires

The absolute time of the expiry of this session. Like :new_session, this option should probably not be used under Rails.

Session Storage

Rails has a number of options when it comes to storing your session data. Each has good and bad points. We’ll start by listing the options and then compare them at the end.

The session_store attribute of ActiveRecord::Base determines the session storage mechanism—set this attribute to a class that implements the storage strategy.

Report erratum

COOKIES AND SESSIONS 441

This class must be defined in the CGI::Session module.5 With the exception of PStore, you use symbols to name the session storage strategy; the symbol is converted into a CamelCase class name.

session_store = CGI::Session::PStore

This is the default session storage mechanism used by Rails. Data for each session is stored in a flat file in PStore format. This format keeps objects in their marshaled form, which allows any serializable data to be stored in sessions. This mechanism supports the additional configuration options :prefix and :tmpdir. The following code in the file environment.rb in the config directory might be used to configure PStore sessions.

Rails::Initializer.run do |config| config.action_controller.session_store = CGI::Session::PStore config.action_controller.session_options[:tmpdir] = "/Users/dave/tmp" config.action_controller.session_options[:prefix] = "myapp_session_"

# ...

session_store = :active_record_store

You can store your session data in your application’s database using ActiveRecordStore. You can generate a migration that creates the sessions table using Rake.

depot> rake db:sessions:create

Run rake db:migrate to create the actual table.

If you look at the migration file, you’ll see that Rails creates an index on the session_id column, because it is used to look up session data. Rails also defines a column called updated_at so Active Record will automatically time stamp the rows in the session table—we’ll see later why this is a good idea.

session_store = :drb_store

DRb is a protocol that allows Ruby processes to share objects over a network connection. Using the DRbStore database manager, Rails stores session data on a DRb server (which you manage outside the web application). Multiple instances of your application, potentially running on distributed servers, can access the same DRb store. A simple DRb server that works with Rails is included in the Rails source.6 DRb uses Marshal to serialize objects.

5.You’ll probably use one of Rails built-in session storage strategies, but you can implement your own storage mechanism if your circumstances require it. The interface for doing this is beyond the scope of this book—have a look at the various Rails implementations in the directory actionpack/lib/actioncontroller/session of the Rails source.

6.If you install from gems, you’ll find it in {RUBYBASE}/lib/ruby/gems/1.8/gems/actionpack-

x.y/lib/action_controller/session/drb_server.rb.

Report erratum

COOKIES AND SESSIONS 442

session_store = :mem_cache_store

memcached is a freely available, distributed object caching system from Danga Interactive.7 The Rails MemCacheStore uses Michael Granger’s Ruby interface8 to memcached to store sessions. memcached is more complex to use than the other alternatives and is probably interesting only if you are already using it for other reasons at your site.

:session_store = :memory_store

This option stores the session data locally in the application’s memory. As no serialization is involved, any object can be stored in an in-memory session. As we’ll see in a minute, this generally is not a good idea for Rails applications.

:database_manager => CGI::Session::FileStore

Session data is stored in flat files. It’s pretty much useless for Rails applications, because the contents must be strings. This mechanism supports the additional configuration options :prefix, :suffix, and :tmpdir.

You can enable or disable session storage for your entire application, for a particular controller, or for certain actions. This is done with the session declaration.

To disable sessions for an entire application, add the following line to your application.rb file in the app/controllers directory.

class ApplicationController < ActionController::Base session :off

# ...

If you put the same declaration inside a particular controller, you localize the effect to that controller.

class RssController < ActionController::Base session :off

# ...

Finally, the session declaration supports the :only, :except, and :if options. The first two take the name or an action or an array containing action names. The last takes a block that is called to determine whether the session directive should be honored. Here are some examples of session directives you could put in a controller.

#Disable sessions for the rss action session :off, :only => :rss

#Disable sessions for the show and list actions session :off, :only => [ :show, :list ]

7. http://www.danga.com/memcached

8. Available from http://www.deveiate.org/projects/RMemCache

Report erratum

COOKIES AND SESSIONS 443

#Enable sessions for all actions except show and list session :except => [ :show, :list ]

#Disable sessions on Sundays :)

session :off, :if => proc { Time.now.wday == 0 }

Comparing Session Storage Options

With all these session options to choose from, which should you use in your application? As always, the answer is “It depends.”

If we rule out memory store as being too simplistic, file store as too restrictive, and memcached as overkill, the choice boils down to PStore, Active Record store, and DRb-based storage. We can compare performance and functionality across these options.

Scott Barron has performed a fascinating analysis of the performance of these storage options.9 His findings are somewhat surprising. For low numbers of sessions, PStore and DRb are roughly equal. As the number of sessions rises, PStore performance starts to drop. This is probably because the host operating system struggles to maintain a directory that contains tens of thousands of session data files. DRb performance stays relatively flat. Performance using Active Record as the backing storage is lower but stays flat as the number of sessions rises.

What does this mean for you? Reviewer Bill Katz summed it up in the following paragraph.

If you expect to be a large web site, the big issue is scalability, and you can address it either by “scaling up” (enhancing your existing servers with additional CPUs, memory, etc.) or “scaling out” (adding new servers). The current philosophy, popularized by companies such as Google, is scaling out by adding cheap, commodity servers. Ideally, each of these servers should be able to handle any incoming request. Because the requests in a single session might be handled on multiple servers, we need our session storage to be accessible across the whole server farm. The session storage option you choose should reflect your plans for optimizing the whole system of servers. Given the wealth of possibilities in hardware and software, you could optimize along any number of axes that impacts your session storage choice. For example, you could use the new MySQL cluster database with extremely fast in-memory transactions; this would work quite nicely with an Active Record approach. You could also have a high-performance storage area network that might work well with PStore. memcached approaches are used behind high-traffic web sites such as LiveJournal, Slashdot, and Wikipedia. Optimization works best when you

9. Mirrored at http://media.pragprog.com/ror/sessions

Report erratum

COOKIES AND SESSIONS 444

analyze the specific application you’re trying to scale and run benchmarks to tune your approach. In short, “It depends.”

There are few absolutes when it comes to performance, and everyone’s context is different. Your hardware, network latencies, database choices, and possibly even the weather will impact how all the components of session storage interact. Our best advice is to start with the simplest workable solution and then monitor it. If it starts to slow you down, find out why before jumping out of the frying pan.

We recommend you start with an Active Record solution. If, as your application grows, you find this becoming a bottleneck, you can migrate to a DRb-based solution.

Session Expiry and Cleanup

One problem with all the solutions is that session data is stored on the server. Each new session adds something to the session store. You’ll eventually need to do some housekeeping, or you’ll run out of server resources.

There’s another reason to tidy up sessions. Many applications don’t want a session to last forever. Once a user has logged in from a particular browser, the application might want to enforce a rule that the user stays logged in only as long as they are active; when they log out, or some fixed time after they last use the application, their session should be terminated.

You can sometimes achieve this effect by expiring the cookie holding the session id. However, this is open to end-user abuse. Worse, it is hard to synchronize the expiry of a cookie on the browser with the tidying up of the session data on the server.

We therefore suggest that you expire sessions by simply removing their serverside session data. Should a browser request subsequently arrive containing a session id for data that has been deleted, the application will receive no session data; the session will effectively not be there.

Implementing this expiration depends on the storage mechanism being used.

For PStore-based sessions, the easiest approach is to run a sweeper task periodically (for example using cron(1) under Unix-like systems). This task should inspect the last modification times of the files in the session data directory, deleting those older than a given time.

For Active Record–based session storage, use the updated_at columns in the sessions table. You can delete all sessions that have not been modified in the last hour (ignoring daylight saving time changes) by having your sweeper task issue SQL such as

Report erratum

FLASH—COMMUNICATING BETWEEN ACTIONS 445

delete from sessions

where now() - updated_at > 3600;

For DRb-based solutions, expiry takes place within the DRb server process. You’ll probably want to record time stamps alongside the entries in the session data hash. You can run a separate thread (or even a separate process) that periodically deletes the entries in this hash.

In all cases, your application can help this process by calling reset_session to delete sessions when they are no longer needed (for example, when a user logs out).

21.3Flash—Communicating between Actions

When we use redirect_to to transfer control to another action, the browser generates a separate request to invoke that action. That request will be handled by our application in a fresh instance of a controller object—instance variables that were set in the original action are not available to the code handling the redirected action. But sometimes we need to communicate between these two instances. We can do this using a facility called the flash.

The flash is a temporary scratchpad for values. It is organized like a hash and stored in the session data, so you can store values associated with keys and later retrieve them. It has one special property. By default, values stored into the flash during the processing of a request will be available during the processing of the immediately following request. Once that second request has been processed, those values are removed from the flash.10

Probably the most common use of the flash is to pass error and informational strings from one action to the next. The intent here is that the first action notices some condition, creates a message describing that condition, and redirects to a separate action. By storing the message in the flash, the second action is able to access the message text and use it in a view.

class BlogController def display

@article = Article.find(params[:id]) end

def add_comment

@article = Article.find(params[:id]) comment = Comment.new(params[:comment]) @article.comments << comment

if @article.save

flash[:notice] = "Thank you for your valuable comment"

10. If you read the RDoc for the flash functionality, you’ll see that it talks about values being made available just to the next action. This isn’t strictly accurate: the flash is cleared out at the end of handling the next request, not on an action-by-action basis.

Report erratum

FLASH—COMMUNICATING BETWEEN ACTIONS 446

else

flash[:notice] = "We threw your worthless comment away" end

redirect_to :action => 'display' end

In this example, the add_comment method stores one of two different messages in the flash using the key :notice. It redirects to the display action.

The display action doesn’t seem to make use of this information. To see what’s going on, we’ll have to dig deeper and look at the template file that defines the layout for the blog controller. This will be in the file blog.rhtml in the app/views/layouts directory.

<head>

<title>My Blog</title>

<%= stylesheet_link_tag("blog") %>

</head>

<body>

<div id="main">

<% if flash[:notice] -%>

<div id="notice"><%= flash[:notice] %></div> <% end -%>

<%= yield :layout %>

</div>

</body>

</html>

In this example, our layout generated the appropriate <div> if the flash contained a :notice key.

It is sometimes convenient to use the flash as a way of passing messages into a template in the current action. For example, our display method might want to output a cheery banner if there isn’t another, more pressing note. It doesn’t need that message to be passed to the next action—it’s for use in the current request only. To do this, it could use flash.now, which updates the flash but does not add to the session data.

class BlogController def display

flash.now[:notice] = "Welcome to my blog" unless flash[:notice] @article = Article.find(params[:id])

end end

While flash.now creates a transient flash entry, flash.keep does the opposite, making entries that are currently in the flash stick around for another request cycle.

class SillyController def one

flash[:notice] = "Hello"

Report erratum

FILTERS AND VERIFICATION 447

flash[:error] = "Boom!" redirect_to :action => "two"

end

def two flash.keep(:notice) flash[:warning] = "Mewl"

redirect_to :action => "three" end

def	three
#	At this point,
#	flash[:notice]	=> "Hello"

#flash[:warning] => "Mewl"

#and flash[:error] is unset render

end end

If you pass no parameters to flash.keep, all the flash contents are preserved.

Flashes can store more than just text messages—you can use them to pass all kinds of information between actions. Obviously for longer-term information you’d want to use the session (probably in conjunction with your database) to store the data, but the flash is great if you want to pass parameters from one request to the next.

Because the flash data is stored in the session, all the usual rules apply. In particular, every object must be serializable, and if you store models, you need a model declaration in your controller.

21.4Filters and Verification

Filters enable you to write code in your controllers that wrap the processing performed by actions—you can write a chunk of code once and have it be called before or after any number of actions in your controller (or your controller’s subclasses). This turns out to be a powerful facility. Using filters, we can implement authentication schemes, logging, response compression, and even response customization.

Rails supports three types of filter: before, after, and around. Filters are called just prior to and/or just after the execution of actions. Depending on how you define them, they either run as methods inside the controller or are passed the controller object when they are run. Either way, they get access to details of the request and response objects, along with the other controller attributes.

Before and After Filters

As their names suggest, before and after filters are invoked before or after an action. Rails maintains two chains of filters for each controller. When a

Report erratum

FILTERS AND VERIFICATION 448

controller is about to run an action, it executes all the filters on the before chain. It executes the action before running the filters on the after chain.

Filters can be passive, monitoring activity performed by a controller. They can also take a more active part in request handling. If a before filter returns false, processing of the filter chain terminates, and the action is not run. A filter may also render output or redirect requests, in which case the original action never gets invoked.

We saw an example of using filters for authorization in the administration part of our store example on page 166. We defined an authorization method that redirected to a login screen if the current session didn’t have a logged-in user.

Download depot_r/app/controllers/application.rb

class ApplicationController < ActionController::Base

private

def authorize

unless User.find_by_id(session[:user_id]) flash[:notice] = "Please log in"

redirect_to(:controller => "login", :action => "login") end

end

end

We then made this method a before filter for all the actions in the administration controller.

Download depot_r/app/controllers/admin_controller.rb

class AdminController < ApplicationController

before_filter :authorize

# ....

This is an example of having a method act as a filter; we passed the name of the method as a symbol to before_filter. The filter declarations also accept blocks and the names of classes. If a block is specified, it will be called with the current controller as a parameter. If a class is given, its filter class method will be called with the controller as a parameter.

class AuditFilter

def self.filter(controller)

AuditLog.create(:action => controller.action_name) end

end

# ...

Report erratum

FILTERS AND VERIFICATION 449

class SomeController < ApplicationController

before_filter do |controller|

logger.info("Processing #{controller.action_name}") end

after_filter AuditFilter

# ...

end

By default, filters apply to all actions in a controller (and any subclasses of that controller). You can modify this with the :only option, which takes one or more actions to be filtered, and the :except option, which lists actions to be excluded from filtering.

class BlogController < ApplicationController

before_filter :authorize, :only => [ :delete, :edit_comment ]

after_filter :log_access, :except => :rss

# ...

The before_filter and after_filter declarations append to the controller’s chain of filters. Use the variants prepend_before_filter and prepend_after_filter to put filters at the front of the chain.

After Filters and Response Munging

After filters can be used to modify the outbound response, changing the headers and content if required. Some applications use this technique to perform global replacements in the content generated by the controller’s templates (for example, substituting a customer’s name for the string <customer/> in the response body). Another use might be compressing the response if the user’s browser supports it.

The following code is an example of how this might work.11 The controller declares the compress method as an after filter. The method looks at the request header to see whether the browser accepts compressed responses. If so, it uses the Zlib library to compress the response body into a string.12 If the result is shorter than the original body, it substitutes in the compressed version and updates the response’s encoding type.

11.This code is not a complete implementation of compression. In particular, it won’t compress streamed data downloaded to the client using send_file.

12.Note that the Zlib Ruby extension might not be available on your platform—it relies on the

presence of the underlying libzlib.a library.

Report erratum

FILTERS AND VERIFICATION 450

Download e1/filter/app/controllers/compress_controller.rb

require 'zlib' require 'stringio'

class CompressController < ApplicationController

after_filter :compress

def index

render(:text => "<pre>" + File.read("/etc/motd" ) + "</pre>") end

protected

def compress

accepts = request.env['HTTP_ACCEPT_ENCODING'] return unless accepts && accepts =~ /(x-gzip|gzip)/ encoding = $1

output = StringIO.new

def output.close # Zlib does a close. Bad Zlib...

rewind end

gz = Zlib::GzipWriter.new(output) gz.write(response.body)

gz.close

if output.length < response.body.length response.body = output.string response.headers['Content-encoding' ] = encoding

end end

end

Around Filters

Around filters wrap the execution of actions. You can write an around filter in two different styles. In the first, the filter is a single chunk of code. That code is called before the action is executed. If the filter code invokes yield, the action is executed. When the action completes, the filter code continues executing. Thus, the code before the yield is like a before filter, and the code after the yield is the after filter. If the filter code never invokes yield, the action is not run—this is the same as having a before filter return false.

The benefit of around filters is that they can retain context across the invocation of the action. For example, the listing on the next page is a simple around filter that logs how long an action takes to execute.

Report erratum

FILTERS AND VERIFICATION 451

	Download e1/filter/app/controllers/blog_controller.rb
Line 1	class BlogController < ApplicationController
-

-around_filter :time_an_action

-

5def index

-# ...

-render :text => "hello"

-end

-

10 def bye

-# ...

-render :text => "goodbye"

-end

-

15 private

-

-def time_an_action

-started = Time.now

-yield

20 elapsed = Time.now - started

-logger.info("#{action_name} took #{elapsed} seconds")

-end

-

-end

We pass the around_filter declaration the name of a method, time_an_action. Whenever an action is about to be invoked in this controller, this filter method is called. It records the time, and then the yield statement on line 19 invokes the original action. When this returns, it calculates and logs the time spent in the action.

As well as passing around_filter the name of a method, you can pass it a block or a filter class.

If you use a block as a filter, it will be passed two parameters: the controller object and a proxy for the action. Use call on this second parameter to invoke the original action. For example, the following is the block version of the previous filter.

Download e1/filter/app/controllers/blog_controller.rb

around_filter do |controller, action| started = Time.now

action.call

elapsed = Time.now - started controller.logger.info("#{controller.action_name} took #{elapsed} seconds")

end

A third form allows you to pass an object as a filter. This object should implement a method called filter. This method will be passed the controller object. It

Report erratum

FILTERS AND VERIFICATION 452

yields to invoke the action. For example, the following implements our timing filter as a class.

Download e1/filter/app/controllers/blog_controller.rb

class BlogController < ApplicationController

class TimingFilter

def filter(controller) started = Time.now yield

elapsed = Time.now - started controller.logger.info("#{controller.action_name} took #{elapsed} seconds")

end end

around_filter TimingFilter.new end

There is an alternative form of around filter where you pass an object that implements the methods before and after. This form is mildly deprecated.

Like before and after filters, around filters take :only and :except parameters.

Around filters are (by default) added to the filter chain differently: the first around filter added executes first. Subsequently added around filters will be nested within existing around filters.13 Thus given

around_filter :one, :two

def one

logger.info("start one") yield

logger.info("end one") end

def two

logger.info("start two") yield

logger.info("end two") end

the sequence of log messages will be

start one start two

. . .

end two end one

13. Note that at the time of writing the Rails API documentation is incorrect when describing this sequencing.

Report erratum

FILTERS AND VERIFICATION 453

Filter inheritance

If you subclass a controller containing filters, the filters will be run on the child objects as well as in the parent. However, filters defined in the children will not run in the parent.

If you don’t want a particular filter to run in a child controller, you can override the default processing with the skip_before_filter and skip_after_filter declarations. These accept the :only and :except parameters.

You can use skip_filter to skip any filter (before, after, and around). However, it works only for filters that were specified as the (symbol) name of a method.

For example, we might enforce authentication globally by adding the following to our application controller.

class ApplicationController < ActionController::Base before_filter :validate_user

private

def validate_user

# ...

end end

We don’t want this filter run for the login action.

class UserController < ApplicationController skip_before_filter :validate_user, :only => :login

def login

# ...

end end

Verification

A common use of before filters is verifying that certain conditions are met before an action is attempted. The Rails verify mechanism is an abstraction that might help you express these preconditions more concisely than you could in explicit filter code.

For example, we might require that the session contains a valid user before our blog allows comments to be posted. We could express this using a verification such as

class BlogController < ApplicationController

verify :only => :post_comment, :session => :user_id,

:add_flash => { :note => "You must log in to comment"}, :redirect_to => :index

# ...

Report erratum

FILTERS AND VERIFICATION 454

This declaration applies the verification to the post_comment action. If the session does not contain the key :user_id, a note is added to the flash and the request is redirected to the index action.

The parameters to verify can be split into three categories.

Applicability

These options select which actions have the verification applied.

:only =>:name or [ :name, ... ]

Verify only the listed action or actions.

:except =>:name or [ :name, ... ]

Verify all actions except those listed.

Tests

These options describe the tests to be performed on the request. If more than one of these is given, all must be true for the verification to succeed.

:flash =>:key or [ :key, ... ]

The flash must include the given key or keys.

:method =>:symbol or [ :symbol, ... ]

The request method (:get, :post, :head, or :delete) must match one of the given symbols.

:params =>:key or [ :key, ... ]

The request parameters must include the given key or keys.

:session =>:key or [ :key, ... ]

The session must include the given key or keys.

:xhr => trueor false

The request must (must not) come from an AJAX call.

Actions

These options describe what should happen if a verification fails. If no actions are specified, the verification returns an empty response to the browser on failure.

:add_flash =>hash

Merges the given hash of key/value pairs into the flash. This can be used to generate error responses to users.

:add_headers =>hash

Merges the given hash of key/value pairs into the response headers.

Report erratum