diff options
Diffstat (limited to 'guides')
| -rw-r--r-- | guides/source/5_2_release_notes.md | 223 | ||||
| -rw-r--r-- | guides/source/action_controller_overview.md | 2 | ||||
| -rw-r--r-- | guides/source/action_mailer_basics.md | 28 | ||||
| -rw-r--r-- | guides/source/active_job_basics.md | 2 | ||||
| -rw-r--r-- | guides/source/active_storage_overview.md | 7 | ||||
| -rw-r--r-- | guides/source/caching_with_rails.md | 48 | ||||
| -rw-r--r-- | guides/source/configuring.md | 12 | ||||
| -rw-r--r-- | guides/source/getting_started.md | 8 | ||||
| -rw-r--r-- | guides/source/security.md | 106 | ||||
| -rw-r--r-- | guides/source/upgrading_ruby_on_rails.md | 10 |
10 files changed, 193 insertions, 253 deletions
diff --git a/guides/source/5_2_release_notes.md b/guides/source/5_2_release_notes.md index 1136f3303c..541c025fac 100644 --- a/guides/source/5_2_release_notes.md +++ b/guides/source/5_2_release_notes.md @@ -85,69 +85,9 @@ Rails 5.2 ships with a new DSL that allows you to configure a for your application. You can configure a global default policy and then override it on a per-resource basis and even use lambdas to inject per-request values into the header such as account subdomains in a multi-tenant application. - -Example global policy: - -```ruby -# config/initializers/content_security_policy.rb -Rails.application.config.content_security_policy do |policy| - policy.default_src :self, :https - policy.font_src :self, :https, :data - policy.img_src :self, :https, :data - policy.object_src :none - policy.script_src :self, :https - policy.style_src :self, :https - - # Specify URI for violation reports - policy.report_uri "/csp-violation-report-endpoint" -end -``` - -Example controller overrides: - -```ruby -# Override policy inline -class PostsController < ApplicationController - content_security_policy do |p| - p.upgrade_insecure_requests true - end -end - -# Using literal values -class PostsController < ApplicationController - content_security_policy do |p| - p.base_uri "https://www.example.com" - end -end - -# Using mixed static and dynamic values -class PostsController < ApplicationController - content_security_policy do |p| - p.base_uri :self, -> { "https://#{current_user.domain}.example.com" } - end -end - -# Disabling the global CSP -class LegacyPagesController < ApplicationController - content_security_policy false, only: :index -end -``` - -To report only content violations for migrating -legacy content using the `content_security_policy_report_only` -configuration attribute: - -```ruby -# config/initializers/content_security_policy.rb -Rails.application.config.content_security_policy_report_only = true -``` - -```ruby -# Controller override -class PostsController < ApplicationController - content_security_policy_report_only only: :index -end -``` +You can read more about this in the +[Securing Rails Applications](security.html#content-security-policy) +guide. Railties -------- @@ -172,29 +112,16 @@ Please refer to the [Changelog][railties] for detailed changes. ### Notable changes -* Namespace error pages' CSS selectors to stop the styles from bleeding - into other pages when using Turbolinks. - ([Pull Request](https://github.com/rails/rails/pull/28814)) - * Added a shared section to `config/database.yml` that will be loaded for all environments. ([Pull Request](https://github.com/rails/rails/pull/28896)) -* Allow irb options to be passed from `rails console` command. - ([Pull Request](https://github.com/rails/rails/pull/29010)) - * Add `railtie.rb` to the plugin generator. ([Pull Request](https://github.com/rails/rails/pull/29576)) * Clear screenshot files in `tmp:clear` task. ([Pull Request](https://github.com/rails/rails/pull/29534)) -* Allow mounting the same engine several times in different locations. - ([Pull Request](https://github.com/rails/rails/pull/29662)) - -* Load environment file in `dbconsole` command. - ([Pull Request](https://github.com/rails/rails/pull/29725)) - * Skip unused components when running `bin/rails app:update`. If the initial app generation skipped Action Cable, Active Record etc., the update task honors those skips too. @@ -249,19 +176,11 @@ Please refer to the [Changelog][railties] for detailed changes. * Add `mini_magick` to default `Gemfile` as comment. ([Pull Request](https://github.com/rails/rails/pull/30633)) -* Gemfile for new apps: upgrade redis-rb from ~> 3.0 to 4.0. - ([Pull Request](https://github.com/rails/rails/pull/30748)) - * `rails new` and `rails plugin new` get `Active Storage` by default. Add ability to skip `Active Storage` with `--skip-active-storage` and do so automatically when `--skip-active-record` is used. ([Pull Request](https://github.com/rails/rails/pull/30101)) -* Fix minitest rails plugin. - The custom reporters are added only if needed. - This will fix conflicts with others plugins. - ([Commit](https://github.com/rails/rails/commit/ac99916fcf7bf27bb1519d4f7387c6b4c5f0463d)) - Action Cable ------------ @@ -280,9 +199,6 @@ Please refer to the [Changelog][action-cable] for detailed changes. * Hash long stream identifiers when using PostgreSQL adapter. ([Pull Request](https://github.com/rails/rails/pull/29297)) -* Add support for compatibility with redis-rb gem for 4.0 version. - ([Pull Request](https://github.com/rails/rails/pull/30748)) - Action Pack ----------- @@ -301,10 +217,6 @@ Please refer to the [Changelog][action-pack] for detailed changes. ### Notable changes -* Add `action_controller_api` and `action_controller_base` load hooks to be - called in `ActiveSupport.on_load`. - ([Pull Request](https://github.com/rails/rails/pull/28402)) - * Add support for recyclable cache keys with fragment caching. ([Pull Request](https://github.com/rails/rails/pull/29092)) @@ -315,18 +227,9 @@ Please refer to the [Changelog][action-pack] for detailed changes. * AEAD encrypted cookies and sessions with GCM. ([Pull Request](https://github.com/rails/rails/pull/28132)) -* `driven_by` now registers poltergeist and capybara-webkit. - ([Pull Request](https://github.com/rails/rails/pull/29315)) - -* Fallback `ActionController::Parameters#to_s` to `Hash#to_s`. - ([Pull Request](https://github.com/rails/rails/pull/29630)) - * Protect from forgery by default. ([Pull Request](https://github.com/rails/rails/pull/29742)) -* Make `take_failed_screenshot` work within engine. - ([Pull Request](https://github.com/rails/rails/pull/30421)) - * Enforce signed/encrypted cookie expiry server side. ([Pull Request](https://github.com/rails/rails/pull/30121)) @@ -356,9 +259,6 @@ Please refer to the [Changelog][action-pack] for detailed changes. [Commit](https://github.com/rails/rails/commit/619b1b6353a65e1635d10b8f8c6630723a5a6f1a), [Commit](https://github.com/rails/rails/commit/4ec8bf68ff92f35e79232fbd605012ce1f4e1e6e)) -* Fix optimized url helpers when using relative url root. - ([Pull Request](https://github.com/rails/rails/pull/31261)) - * Register most popular audio/video/font mime types supported by modern browsers. ([Pull Request](https://github.com/rails/rails/pull/31251)) @@ -412,21 +312,10 @@ Please refer to the [Changelog][action-view] for detailed changes. ### Notable changes -* Update `distance_of_time_in_words` helper to display better error messages - for bad input. - ([Pull Request](https://github.com/rails/rails/pull/20701)) - * Add `:json` type to `auto_discovery_link_tag` to support [JSON Feeds](https://jsonfeed.org/version/1). ([Pull Request](https://github.com/rails/rails/pull/29158)) -* Generate field ids in `collection_check_boxes` and - `collection_radio_buttons`. - ([Pull Request](https://github.com/rails/rails/pull/29412)) - -* Fix issues with scopes and engine on `current_page?` method. - ([Pull Request](https://github.com/rails/rails/pull/29503)) - * Add `srcset` option to `image_tag` helper. ([Pull Request](https://github.com/rails/rails/pull/29349)) @@ -456,10 +345,6 @@ Please refer to the [Changelog][action-mailer] for detailed changes. * Add `assert_enqueued_email_with` test helper. ([Pull Request](https://github.com/rails/rails/pull/30695)) -* Bring back proc with arity of 1 in `ActionMailer::Base.default` proc - since it was supported in Rails 5.0 but not deprecated. - ([Pull Request](https://github.com/rails/rails/pull/30391)) - Active Record ------------- @@ -549,9 +434,6 @@ Please refer to the [Changelog][active-record] for detailed changes. when the current migration does not exist. ([Commit](https://github.com/rails/rails/commit/bb9d6eb094f29bb94ef1f26aa44f145f17b973fe)) -* Add type caster to `RuntimeReflection#alias_name`. - ([Pull Request](https://github.com/rails/rails/pull/28961)) - * Respect `SchemaDumper.ignore_tables` in rake tasks for databases structure dump. ([Pull Request](https://github.com/rails/rails/pull/29077)) @@ -562,39 +444,16 @@ Please refer to the [Changelog][active-record] for detailed changes. does not include a timestamp any more. ([Pull Request](https://github.com/rails/rails/pull/29092)) -* Loading model schema from database is now thread-safe. - ([Pull Request](https://github.com/rails/rails/pull/29216)) - * Prevent creation of bind param if casted value is nil. ([Pull Request](https://github.com/rails/rails/pull/29282)) * Use bulk INSERT to insert fixtures for better performance. ([Pull Request](https://github.com/rails/rails/pull/29504)) -* Fix destroying existing object does not work well when optimistic locking - enabled and `locking_column` is null in the database. - ([Pull Request](https://github.com/rails/rails/pull/28926)) - -* `ActiveRecord::Persistence#touch` does not work well - when optimistic locking enabled and `locking_column`, - without default value, is null in the database. - ([Pull Request](https://github.com/rails/rails/pull/28914)) - * Merging two relations representing nested joins no longer transforms the joins of the merged relation into LEFT OUTER JOIN. ([Pull Request](https://github.com/rails/rails/pull/27063)) -* Previously, when building records using a `has_many :through` association, - if the child records were deleted before the parent was saved, - they would still be persisted. Now, if child records are deleted - before the parent is saved on a `has_many :through` association, - the child records will not be persisted. - ([Pull Request](https://github.com/rails/rails/pull/29593)) - -* Query cache was unavailable when entering the `ActiveRecord::Base.cache` - block without being connected. - ([Pull Request](https://github.com/rails/rails/pull/29609)) - * Fix transactions to apply state to child transactions. Previously, if you had a nested transaction and the outer transaction was rolledback, the record from the inner transaction would still be marked @@ -620,26 +479,10 @@ Please refer to the [Changelog][active-record] for detailed changes. recognize 't' and 'f' as was previously serialized. ([Pull Request](https://github.com/rails/rails/pull/29699)) -* `Relation#joins` is no longer affected by the target model's - `current_scope`, with the exception of `unscoped`. - ([Commit](https://github.com/rails/rails/commit/5c71000d086cc42516934415b79380c2224e1614)) - * Values constructed using multi-parameter assignment will now use the post-type-cast value for rendering in single-field form inputs. ([Commit](https://github.com/rails/rails/commit/1519e976b224871c7f7dd476351930d5d0d7faf6)) -* Fix `unscoped(where: [columns])` removing the wrong bind values. - ([Pull Request](https://github.com/rails/rails/pull/29780)) - -* When a `has_one` association is destroyed by `dependent: destroy`, - `destroyed_by_association` will now be set to the reflection, matching the - behaviour of `has_many` associations. - ([Pull Request](https://github.com/rails/rails/pull/29855)) - -* Fix `COUNT(DISTINCT ...)` with `ORDER BY` and `LIMIT` - to keep the existing select list. - ([Pull Request](https://github.com/rails/rails/pull/29848)) - * `ApplicationRecord` is no longer generated when generating models. If you need to generate it, it can be created with `rails g application_record`. ([Pull Request](https://github.com/rails/rails/pull/29916)) @@ -655,9 +498,6 @@ Please refer to the [Changelog][active-record] for detailed changes. * Add `binary` fixture helper method. ([Pull Request](https://github.com/rails/rails/pull/30073)) -* Ensure `sum` honors `distinct` on `has_many :through` associations. - ([Commit](https://github.com/rails/rails/commit/566f1fd068711dfe557bef63406f8dd6d41d473d)) - * Automatically guess the inverse associations for STI. ([Pull Request](https://github.com/rails/rails/pull/23425)) @@ -679,19 +519,6 @@ Please refer to the [Changelog][active-record] for detailed changes. * PostgreSQL `tsrange` now preserves subsecond precision. ([Pull Request](https://github.com/rails/rails/pull/30725)) -* Fix `COUNT(DISTINCT ...)` for `GROUP BY` with `ORDER BY` and `LIMIT`. - ([Commit](https://github.com/rails/rails/commit/5668dc6b1863ef43be8f8ef0fb1d5db913085fb3)) - -* MySQL: Don't lose `auto_increment: true` in the `db/schema.rb`. - ([Commit](https://github.com/rails/rails/commit/9493d4553569118b2a85da84fd3a8ba2b5b2de76)) - -* Fix longer sequence name detection for serial columns. - ([Pull Request](https://github.com/rails/rails/pull/28339)) - -* Fix `bin/rails db:setup` and `bin/rails db:test:prepare` create wrong - ar_internal_metadata's data for a test database. - ([Pull Request](https://github.com/rails/rails/pull/30579)) - * Raises when calling `lock!` in a dirty record. ([Commit](https://github.com/rails/rails/commit/63cf15877bae859ff7b4ebaf05186f3ca79c1863)) @@ -735,9 +562,6 @@ Please refer to the [Changelog][active-record] for detailed changes. * Add support for PostgreSQL operator classes to `add_index`. ([Pull Request](https://github.com/rails/rails/pull/19090)) -* Fix conflicts `counter_cache` with `touch: true` by optimistic locking. - ([Pull Request](https://github.com/rails/rails/pull/31405)) - * Log database query callers. ([Pull Request](https://github.com/rails/rails/pull/26815), [Pull Request](https://github.com/rails/rails/pull/31519), @@ -749,16 +573,6 @@ Please refer to the [Changelog][active-record] for detailed changes. * Using subselect for `delete_all` with `limit` or `offset`. ([Commit](https://github.com/rails/rails/commit/9e7260da1bdc0770cf4ac547120c85ab93ff3d48)) -* Fix `count(:all)` to correctly work `distinct` with custom SELECT list. - ([Commit](https://github.com/rails/rails/commit/c6cd9a59f200863ccfe8ad1d9c5a8876c39b9c5c)) - -* Fix to invoke callbacks when using `update_attribute`. - ([Commit](https://github.com/rails/rails/commit/732aa34b6e6459ad66a3d3ad107cfff75cc45160)) - -* Use `count(:all)` in `HasManyAssociation#count_records` to prevent invalid - SQL queries for association counting. - ([Pull Request](https://github.com/rails/rails/pull/27561)) - * Fixed inconsistency with `first(n)` when used with `limit()`. The `first(n)` finder now respects the `limit()`, making it consistent with `relation.to_a.first(n)`, and also with the behavior of `last(n)`. @@ -782,17 +596,10 @@ Please refer to the [Changelog][active-record] for detailed changes. * Clear the transaction state when an Active Record object is duped. ([Pull Request](https://github.com/rails/rails/pull/31751)) -* Fix `count(:all)` with eager loading and having an order other than - the driving table. - ([Commit](https://github.com/rails/rails/commit/ebc09ed9ad9a04338138739226a1a92c7a2707ee)) - * Fix not expanded problem when passing an Array object as argument to the where method using `composed_of` column. ([Pull Request](https://github.com/rails/rails/pull/31724)) -* PostgreSQL: Allow pg-1.0 gem to be used with Active Record. - ([Pull Request](https://github.com/rails/rails/pull/31671)) - * Make `reflection.klass` raise if `polymorphic?` not to be misused. ([Commit](https://github.com/rails/rails/commit/63fc1100ce054e3e11c04a547cdb9387cd79571a)) @@ -801,10 +608,6 @@ Please refer to the [Changelog][active-record] for detailed changes. even if `ORDER BY` columns include other table's primary key. ([Commit](https://github.com/rails/rails/commit/851618c15750979a75635530200665b543561a44)) -* Fix that after commit callbacks on update does not triggered - when optimistic locking is enabled. - ([Commit](https://github.com/rails/rails/commit/7f9bd034c485c2425ae0164ff5d6374834e3aa1d)) - * Fix `dependent: :destroy` issue for has_one/belongs_to relationship where the parent class was getting deleted when the child was not. ([Commit](https://github.com/rails/rails/commit/b0fc04aa3af338d5a90608bf37248668d59fc881)) @@ -821,10 +624,6 @@ Please refer to the [Changelog][active-model] for detailed changes. Change `#values` to only return the not empty values. ([Pull Request](https://github.com/rails/rails/pull/28584)) -* Fix regression in numericality validator when comparing Decimal and Float - input values with more scale than the schema. - ([Pull Request](https://github.com/rails/rails/pull/28584)) - * Add method `#merge!` for `ActiveModel::Errors`. ([Pull Request](https://github.com/rails/rails/pull/29714)) @@ -835,9 +634,6 @@ Please refer to the [Changelog][active-model] for detailed changes. is `false`. ([Pull Request](https://github.com/rails/rails/pull/31058)) -* Fix to working before/after validation callbacks on multiple contexts. - ([Pull Request](https://github.com/rails/rails/pull/31483)) - * Models using the attributes API with a proc default can now be marshalled. ([Commit](https://github.com/rails/rails/commit/0af36c62a5710e023402e37b019ad9982e69de4b)) @@ -886,10 +682,6 @@ Please refer to the [Changelog][active-support] for detailed changes. in Active Record and its use in Action Pack's fragment caching. ([Pull Request](https://github.com/rails/rails/pull/29092)) -* Fix implicit coercion calculations with scalars and durations. - ([Pull Request](https://github.com/rails/rails/pull/29163), - [Pull Request](https://github.com/rails/rails/pull/29971)) - * Add `ActiveSupport::CurrentAttributes` to provide a thread-isolated attributes singleton. Primary use case is keeping all the per-request attributes easily available to the whole system. @@ -926,9 +718,6 @@ Please refer to the [Changelog][active-support] for detailed changes. `ActiveSupport::MessageEncryptor`. ([Pull Request](https://github.com/rails/rails/pull/29892)) -* Fix modulo operations involving durations. - ([Commit](https://github.com/rails/rails/commit/a54e13bd2e8fb4d6aa0aebe59271699a2d62567b)) - * Update `String#camelize` to provide feedback when wrong option is passed. ([Pull Request](https://github.com/rails/rails/pull/30039)) @@ -1019,9 +808,6 @@ Please refer to the [Changelog][active-support] for detailed changes. This allows to specify multiple numeric differences in the same assertion. ([Pull Request](https://github.com/rails/rails/pull/31600)) -* Return all mappings for a timezone identifier in `country_zones`. - ([Commit](https://github.com/rails/rails/commit/cdce6a709e1cbc98fff009effc3b1b3ce4c7e8db)) - * Caching: MemCache and Redis `read_multi` and `fetch_multi` speedup. Read from the local in-memory cache before consulting the backend. ([Commit](https://github.com/rails/rails/commit/a2b97e4ffef971607a1be8fc7909f099b6840f36)) @@ -1033,9 +819,6 @@ Please refer to the [Changelog][active-job] for detailed changes. ### Notable changes -* Add support for compatibility with redis-rb gem for 4.0 version. - ([Pull Request](https://github.com/rails/rails/pull/30748)) - * Allow block to be passed to `ActiveJob::Base.discard_on` to allow custom handling of discard jobs. ([Pull Request](https://github.com/rails/rails/pull/30622)) diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md index eadd517f07..5b421756e8 100644 --- a/guides/source/action_controller_overview.md +++ b/guides/source/action_controller_overview.md @@ -51,7 +51,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 call its `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`: +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 call its `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. By creating a new `Client`, the `new` method can make a `@client` instance variable accessible in the view: ```ruby def new diff --git a/guides/source/action_mailer_basics.md b/guides/source/action_mailer_basics.md index 9f239da90f..662f9ea38a 100644 --- a/guides/source/action_mailer_basics.md +++ b/guides/source/action_mailer_basics.md @@ -20,9 +20,18 @@ Introduction ------------ Action Mailer allows you to send emails from your application using mailer classes -and views. Mailers work very similarly to controllers. They inherit from -`ActionMailer::Base` and live in `app/mailers`, and they have associated views -that appear in `app/views`. +and views. + +#### Mailers are similar to controllers + +They inherit from `ActionMailer::Base` and live in `app/mailers`. Mailers also work +very similarly to controllers. Some examples of similarities are enumerated below. +Mailers have: + +* Actions, and also, associated views that appear in `app/views`. +* Instance variables that are accessible in views. +* The ability to utilise layouts and partials. +* The ability to access a params hash. Sending Emails -------------- @@ -60,8 +69,7 @@ end ``` As you can see, you can generate mailers just like you use other generators with -Rails. Mailers are conceptually similar to controllers, and so we get a mailer, -a directory for views, and a test. +Rails. If you didn't want to use a generator, you could create your own file inside of `app/mailers`, just make sure that it inherits from `ActionMailer::Base`: @@ -73,10 +81,9 @@ end #### Edit the Mailer -Mailers are very similar to Rails controllers. They also have methods called -"actions" and use views to structure the content. Where a controller generates -content like HTML to send back to the client, a Mailer creates a message to be -delivered via email. +Mailers have methods called "actions" and they use views to structure their content. +Where a controller generates content like HTML to send back to the client, a Mailer +creates a message to be delivered via email. `app/mailers/user_mailer.rb` contains an empty mailer: @@ -110,9 +117,6 @@ messages in this class. This can be overridden on a per-email basis. * `mail` - The actual email message, we are passing the `:to` and `:subject` headers in. -Just like controllers, any instance variables we define in the method become -available for use in the views. - #### Create a Mailer View Create a file called `welcome_email.html.erb` in `app/views/user_mailer/`. This diff --git a/guides/source/active_job_basics.md b/guides/source/active_job_basics.md index 9d911d4ee4..6d52ac0a99 100644 --- a/guides/source/active_job_basics.md +++ b/guides/source/active_job_basics.md @@ -147,7 +147,7 @@ class GuestsCleanupJob < ApplicationJob #.... end -# Now your job will use `resque` as it's backend queue adapter overriding what +# Now your job will use `resque` as its backend queue adapter overriding what # was configured in `config.active_job.queue_adapter`. ``` diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md index 831a02a9a1..d67f65e88a 100644 --- a/guides/source/active_storage_overview.md +++ b/guides/source/active_storage_overview.md @@ -114,6 +114,13 @@ gem "aws-sdk-s3", require: false NOTE: The core features of Active Storage require the following permissions: `s3:ListBucket`, `s3:PutObject`, `s3:GetObject`, and `s3:DeleteObject`. If you have additional upload options configured such as setting ACLs then additional permissions may be required. +NOTE: If you want to use environment variables, standard SDK configuration files, profiles, +IAM instance profiles or task roles, you can omit the `access_key_id`, `secret_access_key`, +and `region` keys in the example above. The Amazon S3 Service supports all of the +authentication options described in the [AWS SDK documentation] +(https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html). + + ### Microsoft Azure Storage Service Declare an Azure Storage service in `config/storage.yml`: diff --git a/guides/source/caching_with_rails.md b/guides/source/caching_with_rails.md index 5dde6f34fa..3f357b532b 100644 --- a/guides/source/caching_with_rails.md +++ b/guides/source/caching_with_rails.md @@ -446,30 +446,28 @@ config.cache_store = :mem_cache_store, "cache-1.example.com", "cache-2.example.c ### ActiveSupport::Cache::RedisCacheStore -The Redis cache store takes advantage of Redis support for least-recently-used -and least-frequently-used key eviction when it reaches max memory, allowing it -to behave much like a Memcached cache server. +The Redis cache store takes advantage of Redis support for automatic eviction +when it reaches max memory, allowing it to behave much like a Memcached cache server. Deployment note: Redis doesn't expire keys by default, so take care to use a dedicated Redis cache server. Don't fill up your persistent-Redis server with volatile cache data! Read the [Redis cache server setup guide](https://redis.io/topics/lru-cache) in detail. -For an all-cache Redis server, set `maxmemory-policy` to an `allkeys` policy. -Redis 4+ support least-frequently-used (`allkeys-lfu`) eviction, an excellent -default choice. Redis 3 and earlier should use `allkeys-lru` for -least-recently-used eviction. +For a cache-only Redis server, set `maxmemory-policy` to one of the variants of allkeys. +Redis 4+ supports least-frequently-used eviction (`allkeys-lfu`), an excellent +default choice. Redis 3 and earlier should use least-recently-used eviction (`allkeys-lru`). Set cache read and write timeouts relatively low. Regenerating a cached value is often faster than waiting more than a second to retrieve it. Both read and write timeouts default to 1 second, but may be set lower if your network is -consistently low latency. +consistently low-latency. By default, the cache store will not attempt to reconnect to Redis if the connection fails during a request. If you experience frequent disconnects you may wish to enable reconnect attempts. -Cache reads and writes never raise exceptions. They just return `nil` instead, +Cache reads and writes never raise exceptions; they just return `nil` instead, behaving as if there was nothing in the cache. To gauge whether your cache is hitting exceptions, you may provide an `error_handler` to report to an exception gathering service. It must accept three keyword arguments: `method`, @@ -477,12 +475,33 @@ the cache store method that was originally called; `returning`, the value that was returned to the user, typically `nil`; and `exception`, the exception that was rescued. -Putting it all together, a production Redis cache store may look something -like this: +To get started, add the redis gem to your Gemfile: ```ruby -cache_servers = %w[ "redis://cache-01:6379/0", "redis://cache-02:6379/0", … ], -config.cache_store = :redis_cache_store, url: cache_servers, +gem 'redis' +``` + +You can enable support for the faster [hiredis](https://github.com/redis/hiredis) +connection library by additionally adding its ruby wrapper to your Gemfile: + +```ruby +gem 'hiredis' +``` + +Redis cache store will automatically require & use hiredis if available. No further +configuration is needed. + +Finally, add the configuration in the relevant `config/environments/*.rb` file: + +```ruby +config.cache_store = :redis_cache_store, { url: ENV['REDIS_URL'] } +``` + +A more complex, production Redis cache store may look something like this: + +```ruby +cache_servers = %w(redis://cache-01:6379/0 redis://cache-02:6379/0) +config.cache_store = :redis_cache_store, { url: cache_servers, connect_timeout: 30, # Defaults to 20 seconds read_timeout: 0.2, # Defaults to 1 second @@ -491,9 +510,10 @@ config.cache_store = :redis_cache_store, url: cache_servers, error_handler: -> (method:, returning:, exception:) { # Report errors to Sentry as warnings - Raven.capture_exception exception, level: 'warning", + Raven.capture_exception exception, level: 'warning', tags: { method: method, returning: returning } } +} ``` ### ActiveSupport::Cache::NullStore diff --git a/guides/source/configuring.md b/guides/source/configuring.md index a87b8a2f48..8bdba4b3de 100644 --- a/guides/source/configuring.md +++ b/guides/source/configuring.md @@ -400,10 +400,16 @@ by adding the following to your `application.rb` file: Rails.application.config.active_record.sqlite3.represent_boolean_as_integer = true ``` -The schema dumper adds one additional configuration option: +The schema dumper adds two additional configuration options: * `ActiveRecord::SchemaDumper.ignore_tables` accepts an array of tables that should _not_ be included in any generated schema file. +* `ActiveRecord::SchemaDumper.fk_ignore_pattern` allows setting a different regular + expression that will be used to decide whether a foreign key's name should be + dumped to db/schema.rb or not. By default, foreign key names starting with + `fk_rails_` are not exported to the database schema dump. + Defaults to `/^fk_rails_[0-9a-f]{10}$/`. + ### Configuring Action Controller `config.action_controller` includes a number of configuration settings: @@ -502,6 +508,10 @@ Defaults to `'signed cookie'`. * `config.action_dispatch.cookies_rotations` allows rotating secrets, ciphers, and digests for encrypted and signed cookies. +* `config.action_dispatch.use_authenticated_cookie_encryption` controls whether + signed and encrypted cookies use the AES-256-GCM cipher or + the older AES-256-CBC cipher. It defaults to `true`. + * `config.action_dispatch.perform_deep_munge` configures whether `deep_munge` method should be performed on the parameters. See [Security Guide](security.html#unsafe-query-generation) for more information. It defaults to `true`. diff --git a/guides/source/getting_started.md b/guides/source/getting_started.md index f545b90103..5b6cfe6659 100644 --- a/guides/source/getting_started.md +++ b/guides/source/getting_started.md @@ -1125,7 +1125,7 @@ TIP: Rails automatically wraps fields that contain an error with a div with class `field_with_errors`. You can define a CSS rule to make them standout. -Now you'll get a nice error message when saving an article without title when +Now you'll get a nice error message when saving an article without a title when you attempt to do just that on the new article form <http://localhost:3000/articles/new>: @@ -1522,7 +1522,7 @@ comments on articles. ### Generating a Model We're going to see the same generator that we used before when creating -the `Article` model. This time we'll create a `Comment` model to hold +the `Article` model. This time we'll create a `Comment` model to hold a reference to an article. Run this command in your terminal: ```bash @@ -1857,7 +1857,7 @@ This will now render the partial in `app/views/comments/_comment.html.erb` once for each comment that is in the `@article.comments` collection. As the `render` method iterates over the `@article.comments` collection, it assigns each comment to a local variable named the same as the partial, in this case -`comment` which is then available in the partial for us to show. +`comment`, which is then available in the partial for us to show. ### Rendering a Partial Form @@ -2060,7 +2060,7 @@ What's Next? Now that you've seen your first Rails application, you should feel free to update it and experiment on your own. -Remember you don't have to do everything without help. As you need assistance +Remember, you don't have to do everything without help. As you need assistance getting up and running with Rails, feel free to consult these support resources: diff --git a/guides/source/security.md b/guides/source/security.md index 4cf6c06f2d..b419f7b48d 100644 --- a/guides/source/security.md +++ b/guides/source/security.md @@ -1089,6 +1089,112 @@ Here is a list of common headers: * **Access-Control-Allow-Origin:** Used to control which sites are allowed to bypass same origin policies and send cross-origin requests. * **Strict-Transport-Security:** [Used to control if the browser is allowed to only access a site over a secure connection](https://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security) +### Content Security Policy + +Rails provides a DSL that allows you to configure a +[Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) +for your application. You can configure a global default policy and then +override it on a per-resource basis and even use lambdas to inject per-request +values into the header such as account subdomains in a multi-tenant application. + +Example global policy: + +```ruby +# config/initializers/content_security_policy.rb +Rails.application.config.content_security_policy do |policy| + policy.default_src :self, :https + policy.font_src :self, :https, :data + policy.img_src :self, :https, :data + policy.object_src :none + policy.script_src :self, :https + policy.style_src :self, :https + + # Specify URI for violation reports + policy.report_uri "/csp-violation-report-endpoint" +end +``` + +Example controller overrides: + +```ruby +# Override policy inline +class PostsController < ApplicationController + content_security_policy do |p| + p.upgrade_insecure_requests true + end +end + +# Using literal values +class PostsController < ApplicationController + content_security_policy do |p| + p.base_uri "https://www.example.com" + end +end + +# Using mixed static and dynamic values +class PostsController < ApplicationController + content_security_policy do |p| + p.base_uri :self, -> { "https://#{current_user.domain}.example.com" } + end +end + +# Disabling the global CSP +class LegacyPagesController < ApplicationController + content_security_policy false, only: :index +end +``` + +Use the `content_security_policy_report_only` +configuration attribute to set +[Content-Security-Policy-Report-Only](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy-Report-Only) +in order to report only content violations for migrating +legacy content + +```ruby +# config/initializers/content_security_policy.rb +Rails.application.config.content_security_policy_report_only = true +``` + +```ruby +# Controller override +class PostsController < ApplicationController + content_security_policy_report_only only: :index +end +``` + +You can enable automatic nonce generation: + +```ruby +# config/initializers/content_security_policy.rb +Rails.application.config.content_security_policy do |policy| + policy.script_src :self, :https +end + +Rails.application.config.content_security_policy_nonce_generator = -> request { SecureRandom.base64(16) } +``` + +Then you can add an automatic nonce value by passing `nonce: true` +as part of `html_options`. Example: + +```html+erb +<%= javascript_tag nonce: true do -%> + alert('Hello, World!'); +<% end -%> +``` + +Use [`csp_meta_tag`](http://api.rubyonrails.org/classes/ActionView/Helpers/CspHelper.html#method-i-csp_meta_tag) +helper to create a meta tag "csp-nonce" with the per-session nonce value +for allowing inline `<script>` tags. + +```html+erb +<head> + <%= csp_meta_tag %> +</head> +``` + +This is used by the Rails UJS helper to create dynamically +loaded inline `<script>` elements. + Environmental Security ---------------------- diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md index a72bc64926..d5dfaef591 100644 --- a/guides/source/upgrading_ruby_on_rails.md +++ b/guides/source/upgrading_ruby_on_rails.md @@ -77,6 +77,16 @@ Rails 5.2 adds bootsnap gem in the [newly generated app's Gemfile](https://githu The `app:update` task sets it up in `boot.rb`. If you want to use it, then add it in the Gemfile, otherwise change the `boot.rb` to not use bootsnap. +### Expiry in signed or encrypted cookie is now embedded in the cookies values + +To improve security, Rails now embeds the expiry information also in encrypted or signed cookies value. + +This new embed information make those cookies incompatible with versions of Rails older than 5.2. + +If you require your cookies to be read by 5.1 and older, or you are still validating your 5.2 deploy and want +to allow you to rollback set +`Rails.application.config.action_dispatch.use_authenticated_cookie_encryption` to `false`. + Upgrading from Rails 5.0 to Rails 5.1 ------------------------------------- |