Serialization caching

Author: DavidMikeSimon

README.md

@@ -1920,7 +1920,7 @@ end
 Then, on each Resource you want to cache, call the `caching` method:
 
 ```ruby
-class PostResource << JSONAPI::Resource
+class PostResource < JSONAPI::Resource
   caching
 end
 ```
@@ -1933,7 +1933,8 @@ The default Rails timestamps handle this pretty well, and the default cache key
 You can use an alternate field (which you are then responsible for updating) by calling the `cache_field` method:
 
 ```ruby
-class PostResource << JSONAPI::Resource
+class PostResource < JSONAPI::Resource
+  caching
   cache_field :change_counter
 
   before_save do
@@ -1951,10 +1952,12 @@ 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, except that the value must be different if any relevant aspect of the context is different.
+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
+class PostResource < JSONAPI::Resource
+  caching
+
   attributes :title, :body, :secret_field
 
   def fetchable_fields
@@ -1984,14 +1987,14 @@ end
 * 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. 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. The simplest way to do this is to run `JSONAPI.configuration.resource_cache.clear` from the console.
+* 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
+class MySerializer < JSONAPI::ResourceSerializer
   def initialize(primary_resource_klass, options = {})
     @my_special_option = options.delete(:my_special_option)
     super

lib/jsonapi/request_parser.rb

@@ -339,6 +339,7 @@ def add_show_related_resources_operation(relationship_type)
         source_klass: @source_klass,
         source_id: @source_id,
         filters: @source_klass.verify_filters(@filters, @context),
+        include_directives: @include_directives,
         sort_criteria: @sort_criteria,
         paginator: @paginator,
         fields: @fields,

lib/jsonapi/resource.rb

@@ -1071,6 +1071,36 @@ def cached_resources_for(records, serializer, options)
         resources.values
       end
 
+      def find_records(filters, options = {})
+        context = options[:context]
+
+        records = filter_records(filters, options)
+
+        sort_criteria = options.fetch(:sort_criteria) { [] }
+        order_options = construct_order_options(sort_criteria)
+        records = sort_records(records, order_options, context)
+
+        records = apply_pagination(records, options[:paginator], order_options)
+
+        records
+      end
+
+      def cached_resources_for(records, serializer, options)
+        if records.is_a?(Array) && records.all?{|rec| rec.is_a?(JSONAPI::Resource)}
+          resources = records.map{|r| [r.id, r] }.to_h
+        elsif self.caching?
+          t = _model_class.arel_table
+          cache_ids = pluck_arel_attributes(records, t[_primary_key], t[_cache_field])
+          resources = CachedResourceFragment.fetch_fragments(self, serializer, options[:context], cache_ids)
+        else
+          resources = resources_for(records, options).map{|r| [r.id, r] }.to_h
+        end
+
+        preload_included_fragments(resources, records, serializer, options)
+
+        resources.values
+      end
+
       def check_reserved_resource_name(type, name)
         if [:ids, :types, :hrefs, :links].include?(type)
           warn "[NAME COLLISION] `#{name}` is a reserved resource name."