actionpack-page_caching 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bcc463b295ac09cfa6b0ca15557d7e00da2bf92b
-  data.tar.gz: 1ca39e53842cb9446214249e47cfe791596e763e
+  metadata.gz: 4a8baf2e26a08aa06aabc67d4783382223dbef4c
+  data.tar.gz: '081b862c7762f68baa7ca15a9358689773616bb0'
 SHA512:
-  metadata.gz: cd19ec3f9214460795607de16e4d66769b7621cac4caa329ada8ec810b9414a6f1e5280b8132d683adcba70343b85750356c8d0d3d017f7d98ed199384ad1b14
-  data.tar.gz: afa5b80f7c9ce7c54e284fa35bc3c484d7c0552aff051999dd668edd99827059570b019a01e00da544d23c68a78e9427354f68e5b36981221fc808f38f283912
+  metadata.gz: 62aca2629984d4538f10ed0cad44265e91238f231cdd071fb36875a35e6607f547ab69aa33cf7e45c87b05677db69f777682cd2324de6c4a3de133e922fe8aa6
+  data.tar.gz: 7b354f5a3fc117733b5f92228bae747730dda7c70293aa60e7ea8e337c449897f5fa3e2a36179f8b8b409ebd5ff40ee360ba9a7ffb147bd46c71e2431089a15f

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 1.1.1 (September 25, 2018)
+
+*   Fixes handling of several forward slashes as root path.
+
+    *Xavier Noria*
+
+*   Documentation overhaul.
+
+    *Xavier Noria*
+
+
 ## 1.1.0 (January 23, 2017)
 
 *   Support dynamic `page_cache_directory` using a Proc, Symbol or callable

data/README.md

@@ -1,12 +1,41 @@
-actionpack-page_caching
-=======================
+# actionpack-page_caching
 
 Static page caching for Action Pack (removed from core in Rails 4.0).
 
-Installation
-------------
+## Introduction
+
+Page caching is an approach to caching in which response bodies are stored in
+files that the web server can serve directly:
+
+1. A request to endpoint _E_ arrives.
+2. Its response is calculated and stored in a file _F_.
+3. Next time _E_ is requested, the web server sends _F_ directly.
+
+That applies only to GET or HEAD requests whose reponse code is 200, the rest
+are ignored.
+
+Unlike caching proxies or other more sophisticated setups, page caching results
+in a dramatic speed up while being dead simple at the same time. Awesome
+cost/benefit.
+
+The reason for such performance boost is that cached endpoints are
+short-circuited by the web server, which is very efficient at serving static
+files. Requests to cached endpoints do not even reach your Rails application.
 
-Add this line to your application's Gemfile:
+This technique, however, is only suitable for pages that do not need to go
+through your Rails stack, precisely. For example, content management systems
+like wikis have typically many pages that are a great fit for this approach, but
+account-based systems where people log in and manipulate their own data are
+often less likely candidates. As a use case you can check, [Rails
+Contributors](https://contributors.rubyonrails.org/) makes heavy use of page
+caching. Its source code is [here](https://github.com/rails/rails-contributors).
+
+It is not all or nothing, though, in HTML cached pages JavaScript can still
+tweak details here and there dynamically as a trade-off.
+
+## Installation
+
+Add this line to your application's `Gemfile`:
 
 ``` ruby
 gem "actionpack-page_caching"
@@ -14,39 +43,71 @@ gem "actionpack-page_caching"
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
+
+## Usage
+
+### Enable Caching
+
+Page caching needs caching enabled:
+
+```ruby
+config.action_controller.perform_caching = true
+```
+
+That goes typically in `config/environments/production.rb`, but you can activate
+that flag in any mode.
+
+Since Rails 5 there is a special toggler to easily enable/disable caching in
+`development` mode without editing its configuration file. Just execute
+
+```
+$ bin/rails dev:cache
+```
+
+to enable/disable caching in `development` mode.
+
+### Configure the Cache Directory
 
-Or install it yourself as:
+#### Default Cache Directory
 
-    $ gem install actionpack-page_caching
+By default, files are stored below the `public` directory of your Rails
+application, with a path that matches the one in the URL.
 
-Usage
------
+For example, a page-cached request to `/posts/what-is-new-in-rails-6` would be
+stored by default in the file `public/posts/what-is-new-in-rails-6.html`, and
+the web server would be configured to check that path in the file system before
+falling back to Rails. More on this later.
 
-Page caching is an approach to caching where the entire action output is
-stored as a HTML file that the web server can serve without going through
-Action Pack. This is the fastest way to cache your content as opposed to going
-dynamically through the process of generating the content. Unfortunately, this
-incredible speed-up is only available to stateless pages where all visitors are
-treated the same. Content management systems -- including weblogs and wikis --
-have many pages that are a great fit for this approach, but account-based systems
-where people log in and manipulate their own data are often less likely candidates.
+#### Custom Cache Directory
 
-First you need to set `page_cache_directory` in your configuration file:
+The default page caching directory can be overridden:
 
 ``` ruby
-config.action_controller.page_cache_directory = "#{Rails.root}/public/cached_pages"
+config.action_controller.page_cache_directory = Rails.root.join("public", "cached_pages")
 ```
 
-The `page_cache_directory` setting can be used with a Proc:
+There is no need to ensure the directory exists when the application boots,
+whenever a page has to be cached, the page cache directory is created if needed.
+
+#### Custom Cache Directory per Controller
+
+The globally configured cache directory, default or custom, can be overridden in
+each controller. There are three ways of doing this.
+
+With a lambda:
 
 ``` ruby
 class WeblogController < ApplicationController
-  self.page_cache_directory = -> { Rails.root.join("public", request.domain) }
+  self.page_cache_directory = -> {
+    Rails.root.join("public", request.domain)
+  }
 end
 ```
 
-a Symbol:
+a symbol:
 
 ``` ruby
 class WeblogController < ApplicationController
@@ -73,7 +134,11 @@ class WeblogController < ApplicationController
 end
 ```
 
-Specifying which actions to cache is done through the `caches_page` class method:
+Intermediate directories are created as needed also in this case.
+
+### Specify Actions to be Cached
+
+Specifying which actions have to be cached is done through the `caches_page` class method:
 
 ``` ruby
 class WeblogController < ActionController::Base
@@ -81,17 +146,44 @@ class WeblogController < ActionController::Base
 end
 ```
 
-This will generate cache files such as `weblog/show/5.html` and
-`weblog/new.html`, which match the URLs used that would normally trigger
-dynamic page generation. Page caching works by configuring a web server to first
-check for the existence of files on disk, and to serve them directly when found,
-without passing the request through to Action Pack. This is much faster than
-handling the full dynamic request in the usual way.
+### Configure The Web Server
+
+The [wiki](https://github.com/rails/actionpack-page_caching/wiki) of the project
+has some examples of web server configuration.
+
+### Cache Expiration
+
+Expiration of the cache is handled by deleting the cached files, which results
+in a lazy regeneration approach in which the content is stored again as cached
+endpoints are hit.
 
-Expiration of the cache is handled by deleting the cached file, which results
-in a lazy regeneration approach where the cache is not restored before another
-hit is made against it. The API for doing so mimics the options from `url_for`
-and friends:
+#### Full Cache Expiration
+
+If the cache is stored in a separate directory like `public/cached_pages`, you
+can easily expire the whole thing by removing said directory.
+
+Removing a directory recursively with something like `rm -rf` is unreliable
+because that operation is not atomic and can mess up with concurrent page cache
+generation.
+
+In POSIX systems moving a file is atomic, so the recommended approach would be
+to move the directory first out of the way, and then recursively delete that
+one. Something like
+
+```bash
+#!/bin/bash
+
+tmp=public/cached_pages-$(date +%s)
+mv public/cached_pages $tmp
+rm -rf $tmp
+```
+
+As noted before, the page cache directory is created if it does not exist, so
+moving the directory is enough to have a clean cache, no need to recreate.
+
+#### Fine-grained Cache Expiration
+
+The API for doing so mimics the options from `url_for` and friends:
 
 ``` ruby
 class WeblogController < ActionController::Base
@@ -103,12 +195,10 @@ class WeblogController < ActionController::Base
 end
 ```
 
-Additionally, you can expire caches using [Sweepers](https://github.com/rails/rails-observers#action-controller-sweeper)
-that act on changes in the model to determine when a cache is supposed to be expired.
-
-Finally, configure your web server to serve these static pages when they are present
-rather than the original files. See the [project wiki][1] for example configurations.
-[1]: https://github.com/rails/actionpack-page_caching/wiki
+Additionally, you can expire caches using
+[Sweepers](https://github.com/rails/rails-observers#action-controller-sweeper)
+that act on changes in the model to determine when a cache is supposed to be
+expired.
 
 Contributing
 ------------

data/actionpack-page_caching.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |gem|
   gem.name          = "actionpack-page_caching"
-  gem.version       = "1.1.0"
+  gem.version       = "1.1.1"
   gem.author        = "David Heinemeier Hansson"
   gem.email         = "david@loudthinking.com"
   gem.description   = "Static page caching for Action Pack (removed from core in Rails 4.0)"

data/lib/action_controller/caching/pages.rb

@@ -141,7 +141,7 @@ module ActionController
           end
 
           def cache_file(path, extension)
-            if path.empty? || path == "/"
+            if path.empty? || path =~ %r{\A/+\z}
               name = "/index"
             else
               name = URI.parser.unescape(path.chomp("/"))

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: actionpack-page_caching
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - David Heinemeier Hansson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-01-23 00:00:00.000000000 Z
+date: 2018-09-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -92,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.8
+rubygems_version: 2.6.11
 signing_key: 
 specification_version: 4
 summary: Static page caching for Action Pack (removed from core in Rails 4.0)