wcc-jsonapi 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a0508ec8a9f9a06c3e595e95fc0858fb223c5d5d
-  data.tar.gz: eb6da7214a9f625b6a59e6f04a7873f46f762ce5
+SHA256:
+  metadata.gz: 8ab4f51035684c2eefb583873f49cf69d673db91aafce6e79ba1f43c63c7610c
+  data.tar.gz: ba7ba67c456819a916e83385521c4a3a7d8114ce905618c42a1b78f0528ec2ce
 SHA512:
-  metadata.gz: 7bdf2b4539b048ba97d79f462c8752dcff1974b3863e38b5569cfce071b33d9cb5e677cbf184ed973ba33d4fb2cf7d68e78d7f69af01d577f9e27ea59ec126b4
-  data.tar.gz: 25aca96f9d68022dd7fa2e244d6fde81e4c42492e70fabfd02f5c135314870988c22df21127f764c4f99b9ea54661201b41f76105d0b58cb8a1d4791f5be9c65
+  metadata.gz: 33568cdb950b83cbf2c8aae18a34b1a9df0351be15ed4e363b8f383f2217385793d75f9319c349ec4e9b7d8f11e056e56c09aee1b96e830279b29f68b5bb66c6
+  data.tar.gz: 78a811e119d17f7b0691ba7793f22ecad55fff7d522bf4971a77494b4fffecfe1f9c9b24f7d1254a15c6f67060c932e0e5288e29269647d9c81c4b85f67850d3

data/README.md

@@ -0,0 +1,14 @@
+# wcc-jsonapi
+
+This gem includes common utilities for writing APIs in Rails that conform to
+the JsonAPI standard.
+
+Included modules:
+* PaginationHelper
+    A controller concern for help generating pagination links
+* ApiActionCaching
+    A controller concern which checks the ETag/Last-Modified for freshness,
+    skipping the action if so.
+* SerializerWithCaching
+    A serializer concern to generate ETag/Last-Modified metadata based on
+    inclusion params.  Used with [JSONAPI::Serializer](https://github.com/jsonapi-serializer/jsonapi-serializer)

data/Rakefile

@@ -1,3 +1,10 @@
-# frozen_string_literal: true
+require "bundler/gem_tasks"
 
-require 'bundler/gem_tasks'
+begin
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec)
+  task default: :spec
+rescue LoadError
+  # no rspec available
+end

data/lib/wcc/jsonapi/concerns/api_action_caching.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require 'action_controller/action_caching'
+
+# This concern enables ActionCaching for our JsonAPI endpoints.  It improves on
+# the standard actionpack-action_caching gem for our specific use case.  More
+# specifically, it accomplishes the following:
+# * If the incoming request is a conditional GET with ETag or Last-Modified, it
+#    returns 304 not modified without invoking the controller or loading the resource
+# * If the incoming request is stale, it will load the rendered JSON and caching
+#    headers from the cache store without invoking the action
+# * If the incoming request is stale AND the CacheVersion for the specified key is old,
+#    it invokes the action and saves both the rendered JSON response and the caching headers.
+#
+# It is very important to use `stale?` or `fresh_when?` to set the caching headers
+# inside the action, otherwise this concern cannot respond to conditional GET requests.
+#
+# The controller must also include ActionController::Caching
+# (or extend from Api::V1::BaseController which includes it)
+#
+# Example:
+# class Api::V1::MyController < Api::V1::BaseController
+#  include Api::V1::ApiActionCaching
+#
+#  caches_api_action :show, version_key: :my_resource # see CacheVersion::KEY_MAPPING
+#
+#  def show
+#   @resource = load_resource
+#   @page = Api::V1::MyResourceSerializer.new(@person)
+#
+#   render json: @page if stale?(
+#    strong_etag: @page.etag, last_modified: @page.last_modified, public: true,
+#   )
+#  end
+#
+# Modeled after https://github.com/rails/actionpack-action_caching/blob/v1.2.0/lib/action_controller/caching/actions.rb
+module WCC::JsonAPI::ApiActionCaching
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # This applies the action-caching filter around the action
+    def caches_api_action(*actions)
+      return unless cache_configured?
+
+      options = actions.extract_options!
+      filter_options = options.slice!(:cache_path, :cache_version)
+      filter_options.merge!(only: actions) if actions.present?
+      around_action ApiActionCacheFilter.new(options), **filter_options
+    end
+  end
+
+  class ApiActionCacheFilter
+    def initialize(options)
+      @options = options
+    end
+
+    def cache_path(controller)
+      cp = @options[:cache_path]
+      case cp
+      when Symbol
+        controller.__send__(cp)
+      when Proc
+        controller.instance_exec(&cp)
+      else
+        cp
+      end
+    end
+
+    def cache_version(controller)
+      version = @options[:cache_version]
+      case version
+      when Symbol
+        controller.__send__(version)
+      when Proc
+        controller.instance_exec(&version)
+      else
+        raise ArgumentError, 'cache_version must be method name or proc'
+      end
+    end
+
+    def around(controller)
+      # cache path is the standardized request URL
+      cache_path = self.cache_path(controller) ||
+        controller.url_for(controller.params.permit!.merge(only_path: true))
+      unless cache_version = self.cache_version(controller)
+        raise StandardError, 'No cache_version specified'
+      end
+
+      # If we have run the action previously, our caching headers will be stored in the cache.
+      # Use those cached headers to check our incoming request for freshness
+      # (i.e. pretend that the action has already set ETag and Last-Modified then check freshness)
+      status, headers = controller.cache_store.read(
+        [:api_action_caching_headers, cache_path, cache_version],
+      )
+      controller.headers.merge!(headers) if headers
+
+      if controller.request.fresh?(controller.response)
+        # render 304 not modified
+        return
+      end
+
+      # Cache permanent redirects
+      if status == 301 && controller.headers['Location'].present?
+        controller.response.status = status
+        return
+      end
+
+      body = controller.read_fragment([cache_path, cache_version], nil)
+      unless body && headers
+        # The cache_version has been updated - rerun the action
+        yield
+
+        # Save the results of the action in the controller's Fragment Cache
+        body = controller._save_fragment([cache_path, cache_version], nil)
+
+        status, headers = controller.response.to_a
+        controller.cache_store.write(
+          [:api_action_caching_headers, cache_path, cache_version],
+          [status, headers],
+        )
+      end
+
+      # Assign the response body if we skipped running the action
+      controller.response_body = body
+      controller.response.status = status if status
+    end
+  end
+end

data/lib/wcc/jsonapi/concerns/pagination_helper.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module WCC::JsonAPI::PaginationHelper
+  def limit
+    @limit ||= [
+      params[:limit]&.to_i || 100,
+      100,
+    ].min
+  end
+
+  def skip
+    @skip ||= params[:skip]&.to_i || 0
+  end
+
+  def index_meta(total)
+    {
+      total: total,
+      limit: limit,
+      skip: skip,
+    }
+  end
+
+  # Gets the pagination links for the current skip and limit.
+  # This method is inherently complex due to the math involved.  Better to
+  # encapsulate the complexity here.
+  def pagination_links(total)
+    prev_skip = skip == 0 ? nil : [skip - limit, 0].max
+    next_skip = (skip + limit) > total ? nil : skip + limit
+    last_skip = (total / limit).floor * limit
+
+    options = permitted_params.merge(only_path: true)
+
+    {
+      self: url_for(options.merge(limit: limit, skip: skip)),
+      first: url_for(options.merge(limit: limit, skip: 0)),
+      prev: prev_skip && url_for(options.merge(limit: limit, skip: prev_skip)),
+      next: next_skip && url_for(options.merge(limit: limit, skip: next_skip)),
+      last: url_for(options.merge(limit: limit, skip: last_skip)),
+    }
+  end
+
+  def index_serializer_options(total)
+    {
+      is_collection: true,
+      meta: index_meta(total),
+      links: pagination_links(total),
+    }.merge(serializer_options)
+  end
+end

data/lib/wcc/jsonapi/concerns/serializer_with_caching.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+# This is a really complex module that is trying to cover a lot of different
+# edge cases related to generating cache headers.  It is complex.  It tries to
+# generate a consistent ETag for a serialized JSONApi response.  When that response
+# has includes, those included models are included in the ETag.  When that response
+# is a collection, all collection items' cache keys are included in the ETag.
+#
+# To use this module, include it in a JSONAPI::Serializer definition.  Then,
+# in your controller, use the `stale?` or `fresh_when` methods to set ETag and
+# Last-Modified HTTP headers and respond to conditional GETs.
+#
+# The module attempts to conform to Rails' Recyclable Cache Keys specification,
+# allowing serializers to be used as cache keys in the Rails cache as well.
+#
+# rubocop:disable Metrics/LineLength
+module WCC::JsonAPI::SerializerWithCaching
+  extend ActiveSupport::Concern
+
+  included do
+    # ensure "model_name" exists on the serializer
+    extend ActiveModel::Naming
+
+    meta do |record|
+      # intentionally don't use includes here -
+      # etag and lm in the meta should represent only this record
+      serializer = new(record)
+      {
+        'ETag' => generate_strong_etag([serializer.etag]),
+        'Last-Modified' => serializer.last_modified.httpdate,
+      }
+    end
+
+    def etag
+      @etag ||= cache_key_with_version
+    end
+
+    def last_modified
+      @last_modified ||= Time.at(updated_at).utc unless updated_at.nil?
+    end
+
+    # If the cache store is using cache versioning, then it will combine the
+    # cache_key with the cache_version like this:
+    #  cache.fetch(item.cache_key, version: item.cache_version) do ...
+    #
+    # If the cace store does not support cache versioning, the cache store will
+    # not use the cache_version so for backwards compatibility we have to combine
+    # it into the cache key.
+    # https://www.bigbinary.com/blog/rails-adds-support-for-recyclable-cache-keys
+    def cache_key
+      return cache_key_with_version unless ActiveRecord::Base.try(:cache_versioning) == true
+
+      cache_key_without_version
+    end
+
+    def cache_key_with_version
+      "#{cache_key_without_version}-#{cache_version}"
+    end
+
+    # updated_at is the max of all the related objects
+    def updated_at
+      all_resources.map { |r| r&.updated_at&.to_i }.compact.max
+    end
+
+    # The base of a recyclable cache key.  This is a unique identifier of a single
+    # model or a set of models in the system.
+    #
+    # If the response is a single model without includes, the cache_key_without_version
+    # format is "#{serializer model name}/#{resource ID}"
+    #
+    # If the response is a collection or has includes, the cache_key_without_version
+    # is a sha1 hexdigest representing the unique identifiers of all included models.
+    def cache_key_without_version
+      # Use a simple cache_key_without_version if possible
+      @cache_key_without_version ||=
+        if @includes.blank? && !self.class.is_collection?(@resource)
+          "#{self.class.model_name}/#{@resource.id}"
+        else
+          sha1 = Digest::SHA1.new
+          all_resources.each do |r|
+            sha1.update(r.cache_key_without_version)
+          end
+          "#{self.class.model_name}/#{sha1.hexdigest}"
+        end
+    end
+
+    # This is the variant part of a recyclable cache key.  It is a version number
+    # base on the updated_at, which is the max updated_at of all the
+    # embedded and included resources.
+    def cache_version
+      updated_at.to_i.to_s
+    end
+
+    private
+
+    # An array of all the Models that go into making this serialized representation
+    # of a resource.  If the include: param was not set, this is just the @resource
+    # and its embedded resources.  If the include: param was set, this also includes
+    # all the Models that would go in the "included" section of the response.
+    def all_resources
+      @all_resources ||=
+        if self.class.is_collection?(@resource)
+          known_included_objects = Set.new
+          @resource.each_with_object([]) do |r, all|
+            # This resource
+            all << r
+
+            # Plus each item in the collection's included resources, deduplicated.
+            next if @includes.blank?
+
+            all.concat(self.class.get_included_resources(r, @includes, known_included_objects, @fieldsets, @params)) # rubocop:disable Metrics/LineLength
+          end
+        elsif @includes.present?
+          # Single item with includes
+          [@resource] +
+            self.class.get_included_resources(@resource, @includes, Set.new, @fieldsets, @params)
+        else
+          # No includes and not a collection, simple: only this resource.
+          [@resource]
+        end
+    end
+  end
+
+  class_methods do
+    # copied from https://github.com/rails/rails/blob/v5.2.3/actionpack/lib/action_dispatch/http/cache.rb
+    def generate_strong_etag(validators)
+      %("#{ActiveSupport::Digest.hexdigest(ActiveSupport::Cache.expand_cache_key(validators))}")
+    end
+
+    # Gets a list of resources, one for each included object.
+    # Used to delegate calculating ETags.
+    # adapted from https://github.com/jsonapi-serializer/jsonapi-serializer/blob/v2.2.0/lib/fast_jsonapi/serialization_core.rb
+    def get_included_resources(record, includes_list, known_included_objects, fieldsets, params = {})
+      return if includes_list.blank?
+      return [] unless relationships_to_serialize
+
+      includes_list = parse_includes_list(includes_list)
+
+      includes_list.each_with_object([]) do |include_item, included_resources|
+        relationship_item = relationships_to_serialize[include_item.first]
+
+        next unless relationship_item&.include_relationship?(record, params)
+
+        included_objects = Array(relationship_item.fetch_associated_object(record, params))
+        next if included_objects.empty?
+
+        static_serializer = relationship_item.static_serializer
+        static_record_type = relationship_item.static_record_type
+
+        included_objects.each do |inc_obj|
+          serializer = static_serializer || relationship_item.serializer_for(inc_obj, params)
+          record_type = static_record_type || serializer.record_type
+
+          if include_item.last.any?
+            resources = serializer.get_included_resources(inc_obj, include_item.last, known_included_objects,
+              fieldsets, params)
+            included_resources.concat(resources) unless resources.empty?
+          end
+
+          code = "#{record_type}_#{serializer.id_from_record(inc_obj, params)}"
+          next if known_included_objects.include?(code)
+
+          known_included_objects << code
+
+          included_resources << inc_obj
+        end
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/LineLength

data/lib/wcc/jsonapi/rspec/api_cache_control_examples.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples 'API cache-control headers request specs' do |act, vary, options|
+  include ActiveSupport::Testing::TimeHelpers
+
+  time_diff = options && options[:time_diff]
+
+  before do
+    # Touch all our models 1 hour ago to set updated_at
+    travel_to((time_diff || 1.hour).ago) do
+      vary.each do |key|
+        update_action = nil
+        key, update_action = key if key.is_a? Array
+
+        run_update(key, update_action)
+      end
+    end
+  end
+
+  it 'renders the same body 2x' do
+    instance_exec(&act)
+    body1 = response.body
+
+    instance_exec(&act)
+    body2 = response.body
+
+    expect(body1).to eq(body2)
+  end
+
+  it 'renders the same etag 2x' do
+    instance_exec(&act)
+    headers1 = response.headers
+
+    instance_exec(&act)
+    headers2 = response.headers
+
+    expect(headers1['ETag']).not_to be_blank
+    expect(headers2['ETag']).to eq(headers1['ETag'])
+  end
+
+  it 'renders the same last-modified 2x' do
+    instance_exec(&act)
+    headers1 = response.headers
+
+    instance_exec(&act)
+    headers2 = response.headers
+
+    expect(headers1['Last-Modified']).not_to be_blank
+    expect(headers2['Last-Modified']).to eq(headers1['Last-Modified'])
+  end
+
+  vary.each do |key|
+    update_action = nil
+    key, update_action = key if key.is_a? Array
+
+    context "when #{key} is varied" do
+      it 'changes etag and last modified' do
+        instance_exec(&act)
+        headers1 = response.headers
+
+        # Act
+        run_update(key, update_action)
+
+        instance_exec(&act)
+        headers2 = response.headers
+
+        expect(headers1['Last-Modified']).not_to be_blank
+        expect(headers2['Last-Modified']).not_to be_blank
+        expect(headers2['Last-Modified']).not_to eq(headers1['Last-Modified'])
+
+        expect(headers1['ETag']).not_to be_blank
+        expect(headers2['ETag']).not_to be_blank
+        expect(headers2['ETag']).not_to eq(headers1['ETag'])
+      end
+    end
+  end
+
+  private
+
+  def run_update(key, update_action)
+    return instance_exec(&update_action) if update_action.respond_to?(:call)
+
+    model = public_send(key)
+    raise ArgumentError, "#{key} is nil!" unless model
+
+    if model.respond_to?(:update!)
+      # use update! not touch b/c we want to run model callbacks
+      model.update!(updated_at: Time.zone.now)
+    elsif model.is_a?(Hash) && model['sys']
+      # contentful fixture
+      model['sys']['updatedAt'] = Time.zone.now.iso8601
+    else
+      allow(model).to receive(:updated_at)
+        .and_return(Time.zone.now)
+    end
+  end
+end

data/lib/wcc/jsonapi/rspec/snapshot_helper.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require 'rspec/expectations'
+
+module WCC::JsonAPI::RSpec::SnapshotHelper
+  extend ActiveSupport::Concern
+  extend RSpec::Matchers::DSL
+
+  included do
+    after(:all) do
+      # we have to do this in an after block in case there's multiple
+      # writes in the same file, which would mess up our detected line numbers.
+      write_all_inline_snapshots
+    end
+  end
+
+  matcher :match_snapshot do |file_name|
+    match do |actual|
+      @expected = load_snapshot(file_name)
+      @actual = WCC::JsonAPI::RSpec::SnapshotHelper.parse_actual(actual)
+
+      if @expected.blank? || update_snapshots?
+        write_snapshot(file_name, @actual)
+        next true
+      end
+
+      values_match?(@expected, @actual)
+    end
+
+    failure_message do |_actual|
+      [
+        "Expected to match snapshot in file #{file_name}",
+        '(run with env var UPDATE_SNAPSHOTS=true to update snapshots)',
+        'Diff:' + differ.diff_as_string(@actual, @expected),
+      ].join("\n")
+    end
+  end
+
+  matcher :match_inline_snapshot do |inline_snapshot|
+    filename, line_num = WCC::JsonAPI::RSpec::SnapshotHelper
+      .find_inline_call_spot(caller)
+    raise StandardError, 'Could not find inline call spot' if line_num.blank?
+
+    match do |actual|
+      # we strip whitespace here because the heredoc causes leading & trailing newlines
+      @expected = inline_snapshot&.strip
+      @actual = WCC::JsonAPI::RSpec::SnapshotHelper
+        .parse_actual(actual)&.strip
+
+      if @expected.blank?
+        queue_write_inline_snapshot(filename, line_num, @actual)
+        next true
+      end
+
+      values_match?(@expected, @actual)
+    end
+
+    failure_message do |_actual|
+      [
+        'Expected to match inline snapshot',
+        '(delete inline snapshot heredoc including <<~SNAP and SNAP tags to regenerate)',
+        'Diff:' + differ.diff_as_string(@actual, @expected),
+      ].join("\n")
+    end
+  end
+
+  # https://stackoverflow.com/a/32479025/2192243
+  def differ
+    RSpec::Support::Differ.new(
+      object_preparer: ->(object) { RSpec::Matchers::Composable.surface_descriptions_in(object) },
+      color: RSpec::Matchers.configuration.color?,
+    )
+  end
+
+  def update_snapshots?
+    ActiveModel::Type::Boolean.new.cast(ENV['UPDATE_SNAPSHOTS'])
+  end
+
+  def snapshot_full_path(file_name)
+    File.join('spec/snapshots', file_name)
+  end
+
+  def load_snapshot(file_name)
+    file = snapshot_full_path(file_name)
+    return File.read(file) if File.exist?(file)
+  end
+
+  def write_snapshot(file_name, actual)
+    file = snapshot_full_path(file_name)
+    FileUtils.mkdir_p(File.dirname(file))
+
+    puts "SnapshotHelper: Writing new snapshot in #{file_name}"
+    File.write(file, actual)
+  end
+
+  MATCH_INLINE_SNAPSHOT_REGEXP = /match\_inline\_snapshot(\(([\'\"\s]+|<<~\w+)?\))?\s*$/
+
+  def queue_write_inline_snapshot(filename, line_num, actual)
+    to_insert = actual.split("\n")
+
+    # enqueue to the filename
+    (WCC::JsonAPI::RSpec::SnapshotHelper.write_queue[filename] ||= []) <<
+      [line_num, to_insert]
+  end
+
+  def write_all_inline_snapshots
+    WCC::JsonAPI::RSpec::SnapshotHelper.write_queue.each do |filename, queue|
+      # rewrite in reverse order to preserve correct line numbers
+      queue = queue.sort_by(&:first).reverse
+
+      lines = File.readlines(filename)
+      queue.each do |line_num, to_insert|
+        # rewrite the lines
+        idx = line_num - 1
+        lines[idx] = lines[idx].sub(MATCH_INLINE_SNAPSHOT_REGEXP, 'match_inline_snapshot <<~SNAP')
+        lines = lines[0..idx] + to_insert + ['SNAP'] + lines[line_num..-1]
+      end
+
+      puts "SnapshotHelper: Writing new inline snapshot in #{filename}"
+      File.open(filename, 'w') do |f|
+        lines.each { |line| f.puts(line) }
+      end
+    end
+
+    WCC::JsonAPI::RSpec::SnapshotHelper.clear_write_queue!
+  end
+
+  class << self
+    def write_queue
+      @write_queue ||= {}
+    end
+
+    def clear_write_queue!
+      @write_queue = {}
+    end
+
+    def find_inline_call_spot(called_from)
+      called_from.each do |line|
+        next unless /\_spec\.rb/.match?(line)
+
+        filename, line_num = line.split(':')
+        line_num = line_num&.to_i
+        next unless filename && line_num
+
+        return [filename, line_num]
+      end
+    end
+
+    def parse_actual(actual)
+      case actual
+      when String
+        actual
+      else
+        JSON.pretty_generate(actual).strip
+      end
+    end
+  end
+end

data/lib/wcc/jsonapi/rspec.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module WCC
+  module JsonAPI
+    module RSpec
+    end
+  end
+end
+
+require_relative './rspec/snapshot_helper'
+require_relative './rspec/api_cache_control_examples'

data/lib/wcc/{json_api → jsonapi}/version.rb

@@ -2,6 +2,6 @@
 
 module WCC
   module JsonAPI
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

data/lib/wcc/jsonapi.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative './jsonapi/version'
+require_relative './jsonapi/concerns/serializer_with_caching'
+require_relative './jsonapi/concerns/pagination_helper'
+require_relative './jsonapi/concerns/api_action_caching'
+
+module WCC::JsonAPI
+end

data/lib/wcc-jsonapi.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative './wcc/jsonapi'