diff options
Diffstat (limited to 'guides/source/action_controller_overview.md')
| -rw-r--r-- | guides/source/action_controller_overview.md | 453 |
1 files changed, 360 insertions, 93 deletions
diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index 824ffb5d7a..cd4a1a0792 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -1,15 +1,18 @@ Action Controller Overview ========================== -In this guide you will learn how controllers work and how they fit into the request cycle in your application. After reading this guide, you will be able to: +In this guide you will learn how controllers work and how they fit into the request cycle in your application. -* Follow the flow of a request through a controller -* Understand why and how to store data in the session or cookies -* Work with filters to execute code during request processing -* Use Action Controller's built-in HTTP authentication -* Stream data directly to the user's browser -* Filter sensitive parameters so they do not appear in the application's log -* Deal with exceptions that may be raised during request processing +After reading this guide, you will know: + +* How to follow the flow of a request through a controller. +* How to restrict parameters passed to your controller. +* Why and how to store data in the session or cookies. +* How to work with filters to execute code during request processing. +* How to use Action Controller's built-in HTTP authentication. +* How to stream data directly to the user's browser. +* How to filter sensitive parameters so they do not appear in the application's log. +* How to deal with exceptions that may be raised during request processing. -------------------------------------------------------------------------------- @@ -24,6 +27,16 @@ A controller can thus be thought of as a middle man between models and views. It NOTE: For more details on the routing process, see [Rails Routing from the Outside In](routing.html). +Controller Naming Convention +---------------------------- + +The naming convention of controllers in Rails favors pluralization of the last word in the controller's name, although it is not strictly required (e.g. `ApplicationController`). For example, `ClientsController` is preferable to `ClientController`, `SiteAdminsController` is preferable to `SiteAdminController` or `SitesAdminsController`, and so on. + +Following this convention will allow you to use the default route generators (e.g. `resources`, etc) without needing to qualify each `:path` or `:controller`, and keeps URL and path helpers' usage consistent throughout your application. See [Layouts & Rendering Guide](layouts_and_rendering.html) for more details. + +NOTE: The controller naming convention differs from the naming convention of models, which expected to be named in singular form. + + Methods and Actions ------------------- @@ -36,7 +49,7 @@ class ClientsController < ApplicationController end ``` -As an example, if a user goes to `/clients/new` in your application to add a new client, Rails will create an instance of `ClientsController` and run the `new` method. Note that the empty method from the example above could work just fine because Rails will by default render the `new.html.erb` view unless the action says otherwise. The `new` method could make available to the view a `@client` instance variable by creating a new `Client`: +As an example, if a user goes to `/clients/new` in your application to add a new client, Rails will create an instance of `ClientsController` and run the `new` method. Note that the empty method from the example above would work just fine because Rails will by default render the `new.html.erb` view unless the action says otherwise. The `new` method could make available to the view a `@client` instance variable by creating a new `Client`: ```ruby def new @@ -56,7 +69,7 @@ Parameters You will probably want to access data sent in by the user or other parameters in your controller actions. There are two kinds of parameters possible in a web application. The first are parameters that are sent as part of the URL, called query string parameters. The query string is everything after "?" in the URL. The second type of parameter is usually referred to as POST data. This information usually comes from an HTML form which has been filled in by the user. It's called POST data because it can only be sent as part of an HTTP POST request. Rails does not make any distinction between query string parameters and POST parameters, and both are available in the `params` hash in your controller: ```ruby -class ClientsController < ActionController::Base +class ClientsController < ApplicationController # This action uses query string parameters because it gets run # by an HTTP GET request, but this does not make any difference # to the way in which the parameters are accessed. The URL for @@ -66,7 +79,7 @@ class ClientsController < ActionController::Base if params[:status] == "activated" @clients = Client.activated else - @clients = Client.unactivated + @clients = Client.inactivated end end @@ -81,7 +94,7 @@ class ClientsController < ActionController::Base else # This line overrides the default rendering behavior, which # would have been to render the "create" view. - render action: "new" + render "new" end end end @@ -110,23 +123,23 @@ To send a hash you include the key name inside the brackets: </form> ``` -When this form is submitted, the value of `params[:client]` will be `{"name" => "Acme", "phone" => "12345", "address" => {"postcode" => "12345", "city" => "Carrot City"}}`. Note the nested hash in `params[:client][:address]`. +When this form is submitted, the value of `params[:client]` will be `{ "name" => "Acme", "phone" => "12345", "address" => { "postcode" => "12345", "city" => "Carrot City" } }`. Note the nested hash in `params[:client][:address]`. -Note that the `params` hash is actually an instance of `HashWithIndifferentAccess` from Active Support, which acts like a hash that lets you use symbols and strings interchangeably as keys. +Note that the `params` hash is actually an instance of `ActiveSupport::HashWithIndifferentAccess`, which acts like a hash but lets you use symbols and strings interchangeably as keys. -### JSON/XML parameters +### JSON parameters -If you're writing a web service application, you might find yourself more comfortable on accepting parameters in JSON or XML format. Rails will automatically convert your parameters into `params` hash, which you'll be able to access like you would normally do with form data. +If you're writing a web service application, you might find yourself more comfortable accepting parameters in JSON format. If the "Content-Type" header of your request is set to "application/json", Rails will automatically convert your parameters into the `params` hash, which you can access as you would normally. -So for example, if you are sending this JSON parameter: +So for example, if you are sending this JSON content: ```json { "company": { "name": "acme", "address": "123 Carrot Street" } } ``` -You'll get `params[:company]` as `{ :name => "acme", "address" => "123 Carrot Street" }`. +You'll get `params[:company]` as `{ "name" => "acme", "address" => "123 Carrot Street" }`. -Also, if you've turned on `config.wrap_parameters` in your initializer or calling `wrap_parameters` in your controller, you can safely omit the root element in the JSON/XML parameter. The parameters will be cloned and wrapped in the key according to your controller's name by default. So the above parameter can be written as: +Also, if you've turned on `config.wrap_parameters` in your initializer or calling `wrap_parameters` in your controller, you can safely omit the root element in the JSON parameter. The parameters will be cloned and wrapped in the key according to your controller's name by default. So the above parameter can be written as: ```json { "name": "acme", "address": "123 Carrot Street" } @@ -135,17 +148,19 @@ Also, if you've turned on `config.wrap_parameters` in your initializer or callin And assume that you're sending the data to `CompaniesController`, it would then be wrapped in `:company` key like this: ```ruby -{ :name => "acme", :address => "123 Carrot Street", :company => { :name => "acme", :address => "123 Carrot Street" }} +{ name: "acme", address: "123 Carrot Street", company: { name: "acme", address: "123 Carrot Street" } } ``` You can customize the name of the key or specific parameters you want to wrap by consulting the [API documentation](http://api.rubyonrails.org/classes/ActionController/ParamsWrapper.html) +NOTE: Support for parsing XML parameters has been extracted into a gem named `actionpack-xml_parser` + ### Routing Parameters The `params` hash will always contain the `:controller` and `:action` keys, but you should use the methods `controller_name` and `action_name` instead to access these values. Any other parameters defined by the routing, such as `:id` will also be available. As an example, consider a listing of clients where the list can show either active or inactive clients. We can add a route which captures the `:status` parameter in a "pretty" URL: ```ruby -match '/clients/:status' => 'clients#index', foo: "bar" +get '/clients/:status' => 'clients#index', foo: 'bar' ``` In this case, when a user opens the URL `/clients/active`, `params[:status]` will be set to "active". When this route is used, `params[:foo]` will also be set to "bar" just like it was passed in the query string. In the same way `params[:action]` will contain "index". @@ -166,22 +181,174 @@ These options will be used as a starting point when generating URLs, so it's pos If you define `default_url_options` in `ApplicationController`, as in the example above, it would be used for all URL generation. The method can also be defined in one specific controller, in which case it only affects URLs generated there. +### Strong Parameters + +With strong parameters, Action Controller parameters are forbidden to +be used in Active Model mass assignments until they have been +whitelisted. This means you'll have to make a conscious choice about +which attributes to allow for mass updating and thus prevent +accidentally exposing that which shouldn't be exposed. + +In addition, parameters can be marked as required and flow through a +predefined raise/rescue flow to end up as a 400 Bad Request with no +effort. + +```ruby +class PeopleController < ActionController::Base + # This will raise an ActiveModel::ForbiddenAttributes exception + # because it's using mass assignment without an explicit permit + # step. + def create + Person.create(params[:person]) + end + + # This will pass with flying colors as long as there's a person key + # in the parameters, otherwise it'll raise a + # ActionController::ParameterMissing exception, which will get + # caught by ActionController::Base and turned into that 400 Bad + # Request reply. + def update + person = current_account.people.find(params[:id]) + person.update!(person_params) + redirect_to person + end + + private + # Using a private method to encapsulate the permissible parameters + # is just a good pattern since you'll be able to reuse the same + # permit list between create and update. Also, you can specialize + # this method with per-user checking of permissible attributes. + def person_params + params.require(:person).permit(:name, :age) + end +end +``` + +#### Permitted Scalar Values + +Given + +```ruby +params.permit(:id) +``` + +the key `:id` will pass the whitelisting if it appears in `params` and +it has a permitted scalar value associated. Otherwise the key is going +to be filtered out, so arrays, hashes, or any other objects cannot be +injected. + +The permitted scalar types are `String`, `Symbol`, `NilClass`, +`Numeric`, `TrueClass`, `FalseClass`, `Date`, `Time`, `DateTime`, +`StringIO`, `IO`, `ActionDispatch::Http::UploadedFile` and +`Rack::Test::UploadedFile`. + +To declare that the value in `params` must be an array of permitted +scalar values map the key to an empty array: + +```ruby +params.permit(id: []) +``` + +To whitelist an entire hash of parameters, the `permit!` method can be +used: + +```ruby +params.require(:log_entry).permit! +``` + +This will mark the `:log_entry` parameters hash and any subhash of it +permitted. Extreme care should be taken when using `permit!` as it +will allow all current and future model attributes to be +mass-assigned. + +#### Nested Parameters + +You can also use permit on nested parameters, like: + +```ruby +params.permit(:name, { emails: [] }, + friends: [ :name, + { family: [ :name ], hobbies: [] }]) +``` + +This declaration whitelists the `name`, `emails` and `friends` +attributes. It is expected that `emails` will be an array of permitted +scalar values and that `friends` will be an array of resources with +specific attributes : they should have a `name` attribute (any +permitted scalar values allowed), a `hobbies` attribute as an array of +permitted scalar values, and a `family` attribute which is restricted +to having a `name` (any permitted scalar values allowed, too). + +#### More Examples + +You want to also use the permitted attributes in the `new` +action. This raises the problem that you can't use `require` on the +root key because normally it does not exist when calling `new`: + +```ruby +# using `fetch` you can supply a default and use +# the Strong Parameters API from there. +params.fetch(:blog, {}).permit(:title, :author) +``` + +`accepts_nested_attributes_for` allows you to update and destroy +associated records. This is based on the `id` and `_destroy` +parameters: + +```ruby +# permit :id and :_destroy +params.require(:author).permit(:name, books_attributes: [:title, :id, :_destroy]) +``` + +Hashes with integer keys are treated differently and you can declare +the attributes as if they were direct children. You get these kinds of +parameters when you use `accepts_nested_attributes_for` in combination +with a `has_many` association: + +```ruby +# To whitelist the following data: +# {"book" => {"title" => "Some Book", +# "chapters_attributes" => { "1" => {"title" => "First Chapter"}, +# "2" => {"title" => "Second Chapter"}}}} + +params.require(:book).permit(:title, chapters_attributes: [:title]) +``` + +#### Outside the Scope of Strong Parameters + +The strong parameter API was designed with the most common use cases +in mind. It is not meant as a silver bullet to handle all your +whitelisting problems. However you can easily mix the API with your +own code to adapt to your situation. + +Imagine a scenario where you want to whitelist an attribute +containing a hash with any keys. Using strong parameters you can't +allow a hash with any keys but you can use a simple assignment to get +the job done: + +```ruby +def product_params + params.require(:product).permit(:name).tap do |whitelisted| + whitelisted[:data] = params[:product][:data] + end +end +``` Session ------- Your application has a session for each user in which you can store small amounts of data that will be persisted between requests. The session is only available in the controller and the view and can use one of a number of different storage mechanisms: -* ActionDispatch::Session::CookieStore - Stores everything on the client. -* ActionDispatch::Session::CacheStore - Stores the data in the Rails cache. -* @ActionDispatch::Session::ActiveRecordStore@ - Stores the data in a database using Active Record. (require `activerecord-session_store` gem). -* @ActionDispatch::Session::MemCacheStore@ - Stores the data in a memcached cluster (this is a legacy implementation; consider using CacheStore instead). +* `ActionDispatch::Session::CookieStore` - Stores everything on the client. +* `ActionDispatch::Session::CacheStore` - Stores the data in the Rails cache. +* `ActionDispatch::Session::ActiveRecordStore` - Stores the data in a database using Active Record. (require `activerecord-session_store` gem). +* `ActionDispatch::Session::MemCacheStore` - Stores the data in a memcached cluster (this is a legacy implementation; consider using CacheStore instead). All session stores use a cookie to store a unique ID for each session (you must use a cookie, Rails will not allow you to pass the session ID in the URL as this is less secure). -For most stores this ID is used to look up the session data on the server, e.g. in a database table. There is one exception, and that is the default and recommended session store - the CookieStore - which stores all session data in the cookie itself (the ID is still available to you if you need it). This has the advantage of being very lightweight and it requires zero setup in a new application in order to use the session. The cookie data is cryptographically signed to make it tamper-proof, but it is not encrypted, so anyone with access to it can read its contents but not edit it (Rails will not accept it if it has been edited). +For most stores, this ID is used to look up the session data on the server, e.g. in a database table. There is one exception, and that is the default and recommended session store - the CookieStore - which stores all session data in the cookie itself (the ID is still available to you if you need it). This has the advantage of being very lightweight and it requires zero setup in a new application in order to use the session. The cookie data is cryptographically signed to make it tamper-proof. And it is also encrypted so anyone with access to it can't read its contents. (Rails will not accept it if it has been edited). -The CookieStore can store around 4kB of data -- much less than the others -- but this is usually enough. Storing large amounts of data in the session is discouraged no matter which session store your application uses. You should especially avoid storing complex objects (anything other than basic Ruby objects, the most common example being model instances) in the session, as the server might not be able to reassemble them between requests, which will result in an error. +The CookieStore can store around 4kB of data - much less than the others - but this is usually enough. Storing large amounts of data in the session is discouraged no matter which session store your application uses. You should especially avoid storing complex objects (anything other than basic Ruby objects, the most common example being model instances) in the session, as the server might not be able to reassemble them between requests, which will result in an error. If your user sessions don't store critical data or don't need to be around for long periods (for instance if you just use the flash for messaging), you can consider using ActionDispatch::Session::CacheStore. This will store sessions using the cache implementation you have configured for your application. The advantage of this is that you can use your existing cache infrastructure for storing sessions without requiring any additional setup or administration. The downside, of course, is that the sessions will be ephemeral and could disappear at any time. @@ -192,7 +359,7 @@ If you need a different session storage mechanism, you can change it in the `con ```ruby # Use the database for sessions instead of the cookie-based default, # which shouldn't be used to store highly confidential information -# (create the session table with "script/rails g active_record:session_migration") +# (create the session table with "rails g active_record:session_migration") # YourApp::Application.config.session_store :active_record_store ``` @@ -219,7 +386,7 @@ Rails sets up (for the CookieStore) a secret key used for signing the session da # If you change this key, all old signed cookies will become invalid! # Make sure the secret is at least 30 characters and all random, # no regular words or you'll be exposed to dictionary attacks. -YourApp::Application.config.secret_token = '49d3f3de9ed86c74b94ad6bd0...' +YourApp::Application.config.secret_key_base = '49d3f3de9ed86c74b94ad6bd0...' ``` NOTE: Changing the secret when using the `CookieStore` will invalidate all existing sessions. @@ -243,7 +410,7 @@ class ApplicationController < ActionController::Base # logging out removes it. def current_user @_current_user ||= session[:current_user_id] && - User.find_by_id(session[:current_user_id]) + User.find_by(id: session[:current_user_id]) end end ``` @@ -371,13 +538,13 @@ end Cookies ------- -Your application can store small amounts of data on the client -- called cookies -- that will be persisted across requests and even sessions. Rails provides easy access to cookies via the `cookies` method, which -- much like the `session` -- works like a hash: +Your application can store small amounts of data on the client - called cookies - that will be persisted across requests and even sessions. Rails provides easy access to cookies via the `cookies` method, which - much like the `session` - works like a hash: ```ruby class CommentsController < ApplicationController def new # Auto-fill the commenter's name if it has been stored in a cookie - @comment = Comment.new(name: cookies[:commenter_name]) + @comment = Comment.new(author: cookies[:commenter_name]) end def create @@ -386,7 +553,7 @@ class CommentsController < ApplicationController flash[:notice] = "Thanks for your comment!" if params[:remember_name] # Remember the commenter's name. - cookies[:commenter_name] = @comment.name + cookies[:commenter_name] = @comment.author else # Delete cookie for the commenter's name cookie, if any. cookies.delete(:commenter_name) @@ -401,10 +568,10 @@ end Note that while for session values you set the key to `nil`, to delete a cookie value you should use `cookies.delete(:key)`. -Rendering xml and json data +Rendering XML and JSON data --------------------------- -ActionController makes it extremely easy to render `xml` or `json` data. If you generate a controller using scaffold then your controller would look something like this. +ActionController makes it extremely easy to render `XML` or `JSON` data. If you've generated a controller using scaffolding, it would look something like this: ```ruby class UsersController < ApplicationController @@ -419,7 +586,7 @@ class UsersController < ApplicationController end ``` -Notice that in the above case code is `render xml: @users` and not `render xml: @users.to_xml`. That is because if the input is not string then rails automatically invokes `to_xml` . +You may notice in the above code that we're using `render xml: @users`, not `render xml: @users.to_xml`. If the object is not a String, then Rails will automatically invoke `to_xml` for us. Filters ------- @@ -428,11 +595,11 @@ Filters are methods that are run before, after or "around" a controller action. Filters are inherited, so if you set a filter on `ApplicationController`, it will be run on every controller in your application. -Before filters may halt the request cycle. A common before filter is one which requires that a user is logged in for an action to be run. You can define the filter method this way: +"Before" filters may halt the request cycle. A common "before" filter is one which requires that a user is logged in for an action to be run. You can define the filter method this way: ```ruby class ApplicationController < ActionController::Base - before_filter :require_login + before_action :require_login private @@ -442,25 +609,16 @@ class ApplicationController < ActionController::Base redirect_to new_login_url # halts request cycle end end - - # The logged_in? method simply returns true if the user is logged - # in and false otherwise. It does this by "booleanizing" the - # current_user method we created previously using a double ! operator. - # Note that this is not common in Ruby and is discouraged unless you - # really mean to convert something into true or false. - def logged_in? - !!current_user - end end ``` -The method simply stores an error message in the flash and redirects to the login form if the user is not logged in. If a before filter renders or redirects, the action will not run. If there are additional filters scheduled to run after that filter they are also cancelled. +The method simply stores an error message in the flash and redirects to the login form if the user is not logged in. If a "before" filter renders or redirects, the action will not run. If there are additional filters scheduled to run after that filter, they are also cancelled. -In this example the filter is added to `ApplicationController` and thus all controllers in the application inherit it. This will make everything in the application require the user to be logged in in order to use it. For obvious reasons (the user wouldn't be able to log in in the first place!), not all controllers or actions should require this. You can prevent this filter from running before particular actions with `skip_before_filter`: +In this example the filter is added to `ApplicationController` and thus all controllers in the application inherit it. This will make everything in the application require the user to be logged in in order to use it. For obvious reasons (the user wouldn't be able to log in in the first place!), not all controllers or actions should require this. You can prevent this filter from running before particular actions with `skip_before_action`: ```ruby class LoginsController < ApplicationController - skip_before_filter :require_login, only: [:new, :create] + skip_before_action :require_login, only: [:new, :create] end ``` @@ -468,17 +626,17 @@ Now, the `LoginsController`'s `new` and `create` actions will work as before wit ### After Filters and Around Filters -In addition to before filters, you can also run filters after an action has been executed, or both before and after. +In addition to "before" filters, you can also run filters after an action has been executed, or both before and after. -After filters are similar to before filters, but because the action has already been run they have access to the response data that's about to be sent to the client. Obviously, after filters cannot stop the action from running. +"After" filters are similar to "before" filters, but because the action has already been run they have access to the response data that's about to be sent to the client. Obviously, "after" filters cannot stop the action from running. -Around filters are responsible for running their associated actions by yielding, similar to how Rack middlewares work. +"Around" filters are responsible for running their associated actions by yielding, similar to how Rack middlewares work. For example, in a website where changes have an approval workflow an administrator could be able to preview them easily, just apply them within a transaction: ```ruby -class ChangesController < ActionController::Base - around_filter :wrap_in_transaction, only: :show +class ChangesController < ApplicationController + around_action :wrap_in_transaction, only: :show private @@ -494,19 +652,19 @@ class ChangesController < ActionController::Base end ``` -Note that an around filter also wraps rendering. In particular, if in the example above, the view itself reads from the database (e.g. via a scope), it will do so within the transaction and thus present the data to preview. +Note that an "around" filter also wraps rendering. In particular, if in the example above, the view itself reads from the database (e.g. via a scope), it will do so within the transaction and thus present the data to preview. You can choose not to yield and build the response yourself, in which case the action will not be run. ### Other Ways to Use Filters -While the most common way to use filters is by creating private methods and using *_filter to add them, there are two other ways to do the same thing. +While the most common way to use filters is by creating private methods and using *_action to add them, there are two other ways to do the same thing. -The first is to use a block directly with the *_filter methods. The block receives the controller as an argument, and the `require_login` filter from above could be rewritten to use a block: +The first is to use a block directly with the *_action methods. The block receives the controller as an argument, and the `require_login` filter from above could be rewritten to use a block: ```ruby class ApplicationController < ActionController::Base - before_filter do |controller| + before_action do |controller| redirect_to new_login_url unless controller.send(:logged_in?) end end @@ -518,7 +676,7 @@ The second way is to use a class (actually, any object that responds to the righ ```ruby class ApplicationController < ActionController::Base - before_filter LoginFilter + before_action LoginFilter end class LoginFilter @@ -616,6 +774,8 @@ If you want to set custom headers for a response then `response.headers` is the response.headers["Content-Type"] = "application/pdf" ``` +Note: in the above case it would make more sense to use the `content_type` setter directly. + HTTP Authentications -------------------- @@ -629,7 +789,7 @@ Rails comes with two built-in HTTP authentication mechanisms: HTTP basic authentication is an authentication scheme that is supported by the majority of browsers and other HTTP clients. As an example, consider an administration section which will only be available by entering a username and a password into the browser's HTTP basic dialog window. Using the built-in authentication is quite easy and only requires you to use one method, `http_basic_authenticate_with`. ```ruby -class AdminController < ApplicationController +class AdminsController < ApplicationController http_basic_authenticate_with name: "humbaba", password: "5baa61e4" end ``` @@ -641,18 +801,18 @@ With this in place, you can create namespaced controllers that inherit from `Adm HTTP digest authentication is superior to the basic authentication as it does not require the client to send an unencrypted password over the network (though HTTP basic authentication is safe over HTTPS). Using digest authentication with Rails is quite easy and only requires using one method, `authenticate_or_request_with_http_digest`. ```ruby -class AdminController < ApplicationController +class AdminsController < ApplicationController USERS = { "lifo" => "world" } - before_filter :authenticate + before_action :authenticate private - def authenticate - authenticate_or_request_with_http_digest do |username| - USERS[username] + def authenticate + authenticate_or_request_with_http_digest do |username| + USERS[username] + end end - end end ``` @@ -679,13 +839,13 @@ class ClientsController < ApplicationController private - def generate_pdf(client) - Prawn::Document.new do - text client.name, align: :center - text "Address: #{client.address}" - text "Email: #{client.email}" - end.render - end + def generate_pdf(client) + Prawn::Document.new do + text client.name, align: :center + text "Address: #{client.address}" + text "Email: #{client.email}" + end.render + end end ``` @@ -711,7 +871,7 @@ This will read and stream the file 4kB at the time, avoiding loading the entire If `:type` is not specified, it will be guessed from the file extension specified in `:filename`. If the content type is not registered for the extension, `application/octet-stream` will be used. -WARNING: Be careful when using data coming from the client (params, cookies, etc.) to locate the file on disk, as this is a security risk that might allow someone to gain access to files they are not meant to see. +WARNING: Be careful when using data coming from the client (params, cookies, etc.) to locate the file on disk, as this is a security risk that might allow someone to gain access to files they are not meant to. TIP: It is not recommended that you stream static files through Rails if you can instead keep them in a public folder on your web server. It is much more efficient to let the user download the file directly using Apache or another web server, keeping the request from unnecessarily going through the whole Rails stack. @@ -747,15 +907,122 @@ Now the user can request to get a PDF version of a client just by adding ".pdf" GET /clients/1.pdf ``` -Parameter Filtering -------------------- +### Live Streaming of Arbitrary Data + +Rails allows you to stream more than just files. In fact, you can stream anything +you would like in a response object. The `ActionController::Live` module allows +you to create a persistent connection with a browser. Using this module, you will +be able to send arbitrary data to the browser at specific points in time. + +#### Incorporating Live Streaming + +Including `ActionController::Live` inside of your controller class will provide +all actions inside of the controller the ability to stream data. You can mix in +the module like so: + +```ruby +class MyController < ActionController::Base + include ActionController::Live + + def stream + response.headers['Content-Type'] = 'text/event-stream' + 100.times { + response.stream.write "hello world\n" + sleep 1 + } + ensure + response.stream.close + end +end +``` + +The above code will keep a persistent connection with the browser and send 100 +messages of `"hello world\n"`, each one second apart. + +There are a couple of things to notice in the above example. We need to make +sure to close the response stream. Forgetting to close the stream will leave +the socket open forever. We also have to set the content type to `text/event-stream` +before we write to the response stream. This is because headers cannot be written +after the response has been committed (when `response.committed` returns a truthy +value), which occurs when you `write` or `commit` the response stream. + +#### Example Usage + +Let's suppose that you were making a Karaoke machine and a user wants to get the +lyrics for a particular song. Each `Song` has a particular number of lines and +each line takes time `num_beats` to finish singing. + +If we wanted to return the lyrics in Karaoke fashion (only sending the line when +the singer has finished the previous line), then we could use `ActionController::Live` +as follows: + +```ruby +class LyricsController < ActionController::Base + include ActionController::Live -Rails keeps a log file for each environment in the `log` folder. These are extremely useful when debugging what's actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. You can filter certain request parameters from your log files by appending them to `config.filter_parameters` in the application configuration. These parameters will be marked [FILTERED] in the log. + def show + response.headers['Content-Type'] = 'text/event-stream' + song = Song.find(params[:id]) + + song.each do |line| + response.stream.write line.lyrics + sleep line.num_beats + end + ensure + response.stream.close + end +end +``` + +The above code sends the next line only after the singer has completed the previous +line. + +#### Streaming Considerations + +Streaming arbitrary data is an extremely powerful tool. As shown in the previous +examples, you can choose when and what to send across a response stream. However, +you should also note the following things: + +* Each response stream creates a new thread and copies over the thread local + variables from the original thread. Having too many thread local variables can + negatively impact performance. Similarly, a large number of threads can also + hinder performance. +* Failing to close the response stream will leave the corresponding socket open + forever. Make sure to call `close` whenever you are using a response stream. +* WEBrick servers buffer all responses, and so including `ActionController::Live` + will not work. You must use a web server which does not automatically buffer + responses. + +Log Filtering +------------- + +Rails keeps a log file for each environment in the `log` folder. These are extremely useful when debugging what's actually going on in your application, but in a live application you may not want every bit of information to be stored in the log file. + +### Parameters Filtering + +You can filter certain request parameters from your log files by appending them to `config.filter_parameters` in the application configuration. These parameters will be marked [FILTERED] in the log. ```ruby config.filter_parameters << :password ``` +### Redirects Filtering + +Sometimes it's desirable to filter out from log files some sensible locations your application is redirecting to. +You can do that by using the `config.filter_redirect` configuration option: + +```ruby +config.filter_redirect << 's3.amazonaws.com' +``` + +You can set it to a String, a Regexp, or an array of both. + +```ruby +config.filter_redirect.concat ['s3.amazonaws.com', /private_path/] +``` + +Matching URLs will be marked as '[FILTERED]'. + Rescue ------ @@ -781,9 +1048,9 @@ class ApplicationController < ActionController::Base private - def record_not_found - render text: "404 Not Found", status: 404 - end + def record_not_found + render text: "404 Not Found", status: 404 + end end ``` @@ -795,15 +1062,15 @@ class ApplicationController < ActionController::Base private - def user_not_authorized - flash[:error] = "You don't have access to this section." - redirect_to :back - end + def user_not_authorized + flash[:error] = "You don't have access to this section." + redirect_to :back + end end class ClientsController < ApplicationController # Check that the user has the right authorization to access clients. - before_filter :check_authorization + before_action :check_authorization # Note how the actions don't have to worry about all the auth stuff. def edit @@ -812,10 +1079,10 @@ class ClientsController < ApplicationController private - # If the user is not authorized, just throw the exception. - def check_authorization - raise User::NotAuthorized unless current_user.admin? - end + # If the user is not authorized, just throw the exception. + def check_authorization + raise User::NotAuthorized unless current_user.admin? + end end ``` @@ -824,7 +1091,7 @@ NOTE: Certain exceptions are only rescuable from the `ApplicationController` cla Force HTTPS protocol -------------------- -Sometime you might want to force a particular controller to only be accessible via an HTTPS protocol for security reasons. Since Rails 3.1 you can now use `force_ssl` method in your controller to enforce that: +Sometime you might want to force a particular controller to only be accessible via an HTTPS protocol for security reasons. You can use the `force_ssl` method in your controller to enforce that: ```ruby class DinnerController @@ -832,7 +1099,7 @@ class DinnerController end ``` -Just like the filter, you could also passing `:only` and `:except` to enforce the secure connection only to specific actions. +Just like the filter, you could also pass `:only` and `:except` to enforce the secure connection only to specific actions: ```ruby class DinnerController @@ -842,4 +1109,4 @@ class DinnerController end ``` -Please note that if you found yourself adding `force_ssl` to many controllers, you may found yourself wanting to force the whole application to use HTTPS instead. In that case, you can set the `config.force_ssl` in your environment file. +Please note that if you find yourself adding `force_ssl` to many controllers, you may want to force the whole application to use HTTPS instead. In that case, you can set the `config.force_ssl` in your environment file. |