Merge pull request #712 from DavidMikeSimon/caching

Resource serialization fragment caching

Author: lgebhardt

README.md

@@ -51,6 +51,8 @@ backed by ActiveRecord models or by custom objects.
   * [Routing] (#routing)
     * [Nested Routes] (#nested-routes)
   * [Authorization](#authorization)
+  * [Resource Caching] (#resource-caching)
+    * [Caching Caveats] (#caching-caveats)
 * [Configuration] (#configuration)
 * [Contributing] (#contributing)
 * [License] (#license)
@@ -1644,10 +1646,11 @@ class DefaultValueFormatter < JSONAPI::ValueFormatter
   class << self
     def format(raw_value)
       case raw_value
-        when String, Integer
-          return raw_value
+        when Date, Time, DateTime, ActiveSupport::TimeWithZone, BigDecimal
+          # Use the as_json methods added to various base classes by ActiveSupport
+          return raw_value.as_json
         else
-          return raw_value.to_s
+          return raw_value
       end
     end
   end
@@ -1680,16 +1683,14 @@ resource for a system wide change).
 and
 
 ```ruby
-class MyDefaultValueFormatter < JSONAPI::ValueFormatter
+class MyDefaultValueFormatter < DefaultValueFormatter
   class << self
     def format(raw_value)
       case raw_value
-        when String, Integer
-          return raw_value
         when DateTime
-          return raw_value.in_time_zone('UTC').to_s
+          return super(raw_value.in_time_zone('UTC'))
         else
-          return raw_value.to_s
+          return super
       end
     end
   end
@@ -1905,6 +1906,106 @@ Currently `json-api-resources` doesn't come with built-in primitives for authori
 
 Refer to the comments/discussion [here](https://github.com/cerebris/jsonapi-resources/issues/16#issuecomment-222438975) for the differences between approaches
 
+### Resource Caching
+
+To improve the response time of GET requests, JR can cache the generated JSON fragments for
+Resources which are suitable. First, set `config.resource_cache` to an ActiveSupport cache store:
+
+```ruby
+JSONAPI.configure do |config|
+  config.resource_cache = Rails.cache
+end
+```
+
+Then, on each Resource you want to cache, call the `caching` method:
+
+```ruby
+class PostResource < JSONAPI::Resource
+  caching
+end
+```
+
+See the caveats section below for situations where you might not want to enable caching on particular
+Resources.
+
+The Resource model must also have a field that is updated whenever any of the model's data changes.
+The default Rails timestamps handle this pretty well, and the default cache key field is `updated_at` for this reason.
+You can use an alternate field (which you are then responsible for updating) by calling the `cache_field` method:
+
+```ruby
+class PostResource < JSONAPI::Resource
+  caching
+  cache_field :change_counter
+
+  before_save do
+    if self.change_counter.nil?
+      self.change_counter = 1
+    elsif self.changed?
+      self.change_counter += 1
+    end
+  end
+
+  after_touch do
+    update_attribute(:change_counter, self.change_counter + 1)
+  end
+end
+```
+
+If context affects the content of the serialized result, you must define a class method `attribute_caching_context` on that Resource, which should return a different value for contexts that produce different results. In particular, if the `meta` or `fetchable_fields` methods, or any method providing the actual content of an attribute, changes depending on context, then you must provide `attribute_caching_context`. The actual value it
+returns isn't important, what matters is that the value must be different if any relevant part of the context is different.
+
+```ruby
+class PostResource < JSONAPI::Resource
+  caching
+
+  attributes :title, :body, :secret_field
+
+  def fetchable_fields
+    return super if context.user.superuser?
+    return super - [:secret_field]
+  end
+
+  def meta
+    if context.user.can_see_creation_dates?
+      return { created: _model.created_at }
+    else
+      return {}
+    end
+  end
+
+  def self.attribute_caching_context(context)
+    return {
+      admin: context.user.superuser?,
+      creation_date_viewer: context.user.can_see_creation_dates?
+    }
+  end
+end
+```
+
+#### Caching Caveats
+
+* Models for cached Resources must update a cache key field whenever their data changes. However, if you bypass Rails and e.g. alter the database row directly without changing the `updated_at` field, the cached entry for that resource will be inaccurate. Also, `updated_at` provides a narrow race condition window; if a resource is updated twice in the same second, it's possible that only the first update will be cached. If you're concerned about this, you will need to find a way to make sure your models' cache fields change on every update, e.g. by using a unique random value or a monotonic clock.
+* If an attribute's value is affected by related resources, e.g. the `spoken_languages` example above, then changes to the related resource must also touch the cache field on the resource that uses it. The `belongs_to` relation in ActiveRecord provides a `:touch` option for this purpose.
+* JR does not actively clean the cache, so you must use an ActiveSupport cache that automatically expires old entries, or you will leak resources. The MemoryCache built in to Rails does this by default, but other caches will have to be configured with an `:expires_in` option and/or a cache-specific clearing mechanism.
+* Similarly, if you make a substantial code change that affects a lot of serialized representations (i.e. changing the way an attribute is shown), you'll have to clear out all relevant cache entries yourself. The simplest way to do this is to run `JSONAPI.configuration.resource_cache.clear` from the console. You do not have to do this after merely adding or removing attributes; only changes that affect the actual content of attributes require manual cache clearing.
+* If resource caching is enabled at all, then custom relationship methods on any resource might not always be used, even resources that are not cached. For example, if you manually define a `comments` method or `records_for_comments` method on a Resource that `has_many :comments`, you cannot expect it to be used when caching is enabled, even if you never call `caching` on that particular Resource. Instead, you should use relationship name lambdas.
+* The above also applies to custom `find` or `find_by_key` methods. Instead, if you are using resource caching anywhere in your app, try overriding the `find_records` method to return an appropriate `ActiveRecord::Relation`.
+* Caching relies on ActiveRecord features; you cannot enable caching on resources based on non-AR models, e.g. PORO objects or singleton resources.
+* If you write a custom `ResourceSerializer` which takes new options, then you must define `config_description` to include those options if they might impact the serialized value:
+
+```ruby
+class MySerializer < JSONAPI::ResourceSerializer
+  def initialize(primary_resource_klass, options = {})
+    @my_special_option = options.delete(:my_special_option)
+    super
+  end
+
+  def config_description(resource_klass)
+    super.merge({my_special_option: @my_special_option})
+  end
+end
+```
+
 ## Configuration
 
 JR has a few configuration options. Some have already been mentioned above. To set configuration options create an
@@ -1983,7 +2084,30 @@ JSONAPI.configure do |config|
 
   # Formatter Caching
   # Set to false to disable caching of string operations on keys and links.
+  # Note that unlike the resource cache, formatter caching is always done
+  # internally in-memory and per-thread; no ActiveSupport::Cache is used.
   config.cache_formatters = true
+
+  # Resource cache
+  # An ActiveSupport::Cache::Store or similar, used by Resources with caching enabled.
+  # Set to `nil` (the default) to disable caching, or to `Rails.cache` to use the
+  # Rails cache store.
+  config.resource_cache = nil
+
+  # Default resource cache field
+  # On Resources with caching enabled, this field will be used to check for out-of-date
+  # cache entries, unless overridden on a specific Resource. Defaults to "updated_at".
+  config.default_resource_cache_field = :updated_at
+
+  # Resource cache digest function
+  # Provide a callable that returns a unique value for string inputs with
+  # low chance of collision. The default is SHA256 base64.
+  config.resource_cache_digest_function = Digest::SHA2.new.method(:base64digest)
+
+  # Resource cache usage reporting
+  # Optionally provide a callable which JSONAPI will call with information about cache
+  # performance. Should accept three arguments: resource name, hits count, misses count.
+  config.resource_cache_usage_report_function = nil
 end
 ```
 

lib/jsonapi-resources.rb

@@ -1,5 +1,7 @@
 require 'jsonapi/naive_cache'
+require 'jsonapi/compiled_json'
 require 'jsonapi/resource'
+require 'jsonapi/cached_resource_fragment'
 require 'jsonapi/response_document'
 require 'jsonapi/acts_as_resource_controller'
 require 'jsonapi/resource_controller'

lib/jsonapi/acts_as_resource_controller.rb

@@ -62,20 +62,24 @@ def process_request
       @request = JSONAPI::RequestParser.new(params, context: context,
                                             key_formatter: key_formatter,
                                             server_error_callbacks: (self.class.server_error_callbacks || []))
+
       unless @request.errors.empty?
         render_errors(@request.errors)
       else
-        process_operations
-        render_results(@operation_results)
+        operations = @request.operations
+        unless JSONAPI.configuration.resource_cache.nil?
+          operations.each {|op| op.options[:cache_serializer] = resource_serializer }
+        end
+        results = process_operations(operations)
+        render_results(results)
       end
-
     rescue => e
       handle_exceptions(e)
     end
 
-    def process_operations
+    def process_operations(operations)
       run_callbacks :process_operations do
-        @operation_results = operation_dispatcher.process(@request.operations)
+        operation_dispatcher.process(operations)
       end
     end
 
@@ -109,6 +113,19 @@ def resource_serializer_klass
       @resource_serializer_klass ||= JSONAPI::ResourceSerializer
     end
 
+    def resource_serializer
+      @resource_serializer ||= resource_serializer_klass.new(
+        resource_klass,
+        include_directives: @request ? @request.include_directives : nil,
+        fields: @request ? @request.fields : {},
+        base_url: base_url,
+        key_formatter: key_formatter,
+        route_formatter: route_formatter,
+        serialization_options: serialization_options
+      )
+      @resource_serializer
+    end
+
     def base_url
       @base_url ||= request.protocol + request.host_with_port
     end
@@ -198,34 +215,36 @@ def render_errors(errors)
 
     def render_results(operation_results)
       response_doc = create_response_document(operation_results)
+      content = response_doc.contents
 
-      render_options = {
-        status: response_doc.status,
-        json:   response_doc.contents,
-        content_type: JSONAPI::MEDIA_TYPE
-      }
+      render_options = {}
+      if operation_results.has_errors?
+        render_options[:json] = content
+      else
+        # Bypasing ActiveSupport allows us to use CompiledJson objects for cached response fragments
+        render_options[:body] = JSON.generate(content)
+      end
 
-      render_options[:location] = response_doc.contents[:data]["links"][:self] if (
-        response_doc.status == :created && response_doc.contents[:data].class != Array
+      render_options[:location] = content[:data]["links"][:self] if (
+        response_doc.status == :created && content[:data].class != Array
       )
 
+      # For whatever reason, `render` ignores :status and :content_type when :body is set.
+      # But, we can just set those values directly in the Response object instead.
+      response.status = response_doc.status
+      response.headers['Content-Type'] = JSONAPI::MEDIA_TYPE
+
       render(render_options)
     end
 
     def create_response_document(operation_results)
       JSONAPI::ResponseDocument.new(
         operation_results,
-        primary_resource_klass: resource_klass,
-        include_directives: @request ? @request.include_directives : nil,
-        fields: @request ? @request.fields : nil,
-        base_url: base_url,
+        operation_results.has_errors? ? nil : resource_serializer,
         key_formatter: key_formatter,
-        route_formatter: route_formatter,
         base_meta: base_meta,
         base_links: base_response_links,
-        resource_serializer_klass: resource_serializer_klass,
-        request: @request,
-        serialization_options: serialization_options
+        request: @request
       )
     end