wcc-contentful 0.3.0 → 1.0.0.pre.rc2

data/lib/wcc/contentful/indexed_representation.rb

@@ -29,8 +29,8 @@ module WCC::Contentful
       ret
     end
 
-    def to_json
-      @types.to_json
+    def to_json(*args)
+      @types.to_json(*args)
     end
 
     def deep_dup

data/lib/wcc/contentful/instrumentation.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module WCC::Contentful
+  module Instrumentation
+    extend ActiveSupport::Concern
+
+    def _instrumentation_event_prefix
+      @_instrumentation_event_prefix ||=
+        # WCC::Contentful => contentful.wcc
+        '.' + (is_a?(Class) || is_a?(Module) ? self : self.class)
+          .name.parameterize.split('-').reverse.join('.')
+    end
+
+    included do
+      protected
+
+      def _instrument(name, payload = {}, &block)
+        name += _instrumentation_event_prefix
+        (@_instrumentation ||= WCC::Contentful::Services.instance.instrumentation)
+          .instrument(name, payload, &block)
+      end
+    end
+
+    class << self
+      def instrument(name, payload = {}, &block)
+        WCC::Contentful::Services.instance
+          .instrumentation.instrument(name, payload, &block)
+      end
+    end
+  end
+end

data/lib/wcc/contentful/link.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+class WCC::Contentful::Link
+  attr_reader :id
+  attr_reader :link_type
+  attr_reader :raw
+
+  LINK_TYPES = {
+    Asset: 'Asset',
+    Link: 'Entry'
+  }.freeze
+
+  def initialize(model, link_type = nil)
+    @id = model.try(:id) || model
+    @link_type = link_type
+    @link_type ||= model.is_a?(WCC::Contentful::Model::Asset) ? :Asset : :Link
+    @raw =
+      {
+        'sys' => {
+          'type' => 'Link',
+          'linkType' => LINK_TYPES[@link_type] || link_type,
+          'id' => @id
+        }
+      }
+  end
+
+  alias_method :to_h, :raw
+end

data/lib/wcc/contentful/link_visitor.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# The LinkVisitor is a utility class for walking trees of linked entries.
+# It is used internally by the Store layer to compose the resulting resolved hashes.
+# But you can use it too!
+class WCC::Contentful::LinkVisitor
+  attr_reader :entry
+  attr_reader :type
+  attr_reader :fields
+  attr_reader :depth
+
+  # @param [Hash] entry The entry hash (resolved or unresolved) to walk
+  # @param [Array<String, Symbol>] The fields to select from the entry tree.
+  #         Use `:Link` to select only links, or `'slug'` to select all slugs in the tree.
+  # @param [Fixnum] depth (optional) How far to walk down the tree of links.  Be careful of
+  #         recursive trees!
+  # @example
+  #   entry = store.find_by(id: id, include: 3)
+  #   WCC::Contentful::LinkVisitor.new(entry, 'slug', depth: 3)
+  #     .map { |slug| 'https://mirror-site' + slug }
+  def initialize(entry, *fields, depth: 0)
+    unless entry.is_a?(Hash) && entry.dig('sys', 'id')
+      raise ArgumentError, "Please provide an entry as a hash value (got #{entry})"
+    end
+    unless ct = entry.dig('sys', 'contentType', 'sys', 'id')
+      raise ArgumentError, 'Entry has no content type!'
+    end
+
+    @type = WCC::Contentful.types[ct]
+    raise ArgumentError, "Unknown content type '#{ct}'" unless @type
+
+    @entry = entry
+    @fields = fields
+    @depth = depth
+  end
+
+  # Walks an entry and its resolved links, without transforming the entry.
+  # @yield [value, field, locale]
+  # @yieldparam [Object] value The value of the selected field.
+  # @yieldparam [WCC::Contentful::IndexedRepresentation::Field] field The type of the selected field
+  # @yieldparam [String] locale The locale of the current field value
+  # @returns nil
+  def each(&block)
+    _each do |val, field, locale, index|
+      yield(val, field, locale, index) if should_yield_field?(field)
+
+      next unless should_walk_link?(field, val)
+
+      self.class.new(val, *fields, depth: depth - 1).each(&block)
+    end
+
+    nil
+  end
+
+  def map!(&block)
+    _each do |val, field, locale, index|
+      if should_yield_field?(field)
+        val = yield(val, field, locale, index)
+        set_field(field, locale, index, val)
+      end
+
+      next unless should_walk_link?(field, val)
+
+      self.class.new(val, *fields, depth: depth - 1).map!(&block)
+    end
+
+    entry
+  end
+
+  private
+
+  def _each(&block)
+    type.fields.each_value do |f|
+      each_field(f, &block)
+    end
+  end
+
+  def each_field(field)
+    each_locale(field) do |val, locale|
+      if field.array
+        val&.each_with_index do |v, index|
+          yield(v, field, locale, index) unless v.nil?
+        end
+      else
+        yield(val, field, locale) unless val.nil?
+      end
+    end
+  end
+
+  def each_locale(field)
+    raw_value = entry.dig('fields', field.name)
+    if locale = entry.dig('sys', 'locale')
+      if raw_value.is_a?(Hash) && raw_value[locale]
+        # it's a locale=* entry, but they've added sys.locale to those now
+        raw_value = raw_value[locale]
+      end
+      yield(raw_value, locale)
+    else
+      raw_value&.each_with_object({}) do |(l, val), h|
+        h[l] = yield(val, l)
+      end
+    end
+  end
+
+  def should_yield_field?(field)
+    fields.empty? || fields.include?(field.type) || fields.include?(field.name)
+  end
+
+  def should_walk_link?(field, val, dep = depth)
+    dep > 0 && field.type == :Link && val.dig('sys', 'type') == 'Entry'
+  end
+
+  def set_field(field, locale, index, val)
+    current_field = (entry['fields'][field.name] ||= {})
+
+    if field.array
+      (current_field[locale] ||= [])[index] = val
+    else
+      current_field[locale] = val
+    end
+  end
+end

data/lib/wcc/contentful/middleware.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module WCC::Contentful::Middleware
+end
+
+require_relative './middleware/store'
+# someday: ./middleware/client & ./middleware/model ?

data/lib/wcc/contentful/middleware/store.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative '../middleware'
+
+# A Store middleware wraps the Store interface to perform any desired transformations
+# on the Contentful entries coming back from the store.  A Store middleware must
+# implement the Store interface as well as a `store=` attribute writer, which is
+# used to inject the next store or middleware in the chain.
+#
+# The Store interface can be seen on the WCC::Contentful::Store::Base class.  It
+# consists of the `#find, #find_by, #find_all, #set, #delete,` and `#index` methods.
+#
+# Including this concern will define those methods to pass through to the next store.
+# Any of those methods can be overridden on the implementing middleware.
+# It will also expose two overridable methods, `#select?` and `#transform`.  These
+# methods are applied when reading values out of the store, and can be used to
+# apply a filter or transformation to each entry in the store.
+module WCC::Contentful::Middleware::Store
+  extend ActiveSupport::Concern
+  include WCC::Contentful::Store::Interface
+
+  attr_accessor :store
+
+  delegate :index, :index?, to: :store
+
+  class_methods do
+    def call(store, *content_delivery_params, **_)
+      instance = new(*content_delivery_params)
+      instance.store = store
+      instance
+    end
+  end
+
+  def find(id, **options)
+    found = store.find(id, **options)
+    return transform(found) if found && (!has_select? || select?(found))
+  end
+
+  def find_by(options: nil, **args)
+    result = store.find_by(**args.merge(options: options))
+    return unless result && (!has_select? || select?(result))
+
+    result = resolve_includes(result, options[:include]) if options && options[:include]
+    transform(result)
+  end
+
+  def find_all(options: nil, **args)
+    DelegatingQuery.new(
+      store.find_all(**args.merge(options: options)),
+      middleware: self,
+      options: options
+    )
+  end
+
+  def resolve_includes(entry, depth)
+    return entry unless entry && depth && depth > 0
+
+    WCC::Contentful::LinkVisitor.new(entry, :Link, depth: depth).map! do |val|
+      resolve_link(val)
+    end
+  end
+
+  def resolve_link(val)
+    return val unless resolved_link?(val)
+
+    if !has_select? || select?(val)
+      transform(val)
+    else
+      # Pretend it's an unresolved link -
+      # matches the behavior of a store when the link cannot be retrieved
+      WCC::Contentful::Link.new(val.dig('sys', 'id'), val.dig('sys', 'type')).to_h
+    end
+  end
+
+  def resolved_link?(value)
+    value.is_a?(Hash) && value.dig('sys', 'type') == 'Entry'
+  end
+
+  def has_select? # rubocop:disable Naming/PredicateName
+    respond_to?(:select?)
+  end
+
+  # The default version of `#transform` just returns the entry.
+  # Override this with your own implementation.
+  def transform(entry)
+    entry
+  end
+
+  class DelegatingQuery
+    include WCC::Contentful::Store::Query::Interface
+    include Enumerable
+
+    # by default all enumerable methods delegated to the to_enum method
+    delegate(*(Enumerable.instance_methods - Module.instance_methods), to: :to_enum)
+
+    def count
+      if middleware.has_select?
+        raise NameError, "Count cannot be determined because the middleware '#{middleware}'" \
+          " implements the #select? method.  Please use '.to_a.count' to count entries that" \
+          ' pass the #select? method.'
+      end
+
+      # The wrapped query may get count from the "Total" field in the response,
+      # or apply a "COUNT(*)" to the query.
+      wrapped_query.count
+    end
+
+    attr_reader :wrapped_query, :middleware, :options
+
+    def to_enum
+      result = wrapped_query.to_enum
+      result = result.select { |x| middleware.select?(x) } if middleware.has_select?
+
+      if options && options[:include]
+        result = result.map { |x| middleware.resolve_includes(x, options[:include]) }
+      end
+
+      result.map { |x| middleware.transform(x) }
+    end
+
+    def apply(filter, context = nil)
+      self.class.new(
+        wrapped_query.apply(filter, context),
+        middleware: middleware,
+        options: options,
+        **@extra
+      )
+    end
+
+    def apply_operator(operator, field, expected, context = nil)
+      self.class.new(
+        wrapped_query.apply_operator(operator, field, expected, context),
+        middleware: middleware,
+        options: options,
+        **@extra
+      )
+    end
+
+    WCC::Contentful::Store::Query::Interface::OPERATORS.each do |op|
+      # @see #apply_operator
+      define_method(op) do |field, expected, context = nil|
+        self.class.new(
+          wrapped_query.public_send(op, field, expected, context),
+          middleware: middleware,
+          options: options,
+          **@extra
+        )
+      end
+    end
+
+    def initialize(wrapped_query, middleware:, options: nil, **extra)
+      @wrapped_query = wrapped_query
+      @middleware = middleware
+      @options = options
+      @extra = extra
+    end
+  end
+end

data/lib/wcc/contentful/middleware/store/caching_middleware.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module WCC::Contentful::Middleware::Store
+  class CachingMiddleware
+    include WCC::Contentful::Middleware::Store
+    # include instrumentation, but not specifically store stack instrumentation
+    include WCC::Contentful::Instrumentation
+
+    attr_accessor :expires_in
+
+    def initialize(cache = nil)
+      @cache = cache || ActiveSupport::Cache::MemoryStore.new
+      @expires_in = nil
+    end
+
+    def find(key, **options)
+      event = 'fresh'
+      found =
+        @cache.fetch(key, expires_in: expires_in) do
+          event = 'miss'
+          # if it's not a contentful ID don't hit the API.
+          # Store a nil object if we can't find the object on the CDN.
+          (store.find(key, options) || nil_obj(key)) if key =~ /^\w+$/
+        end
+      _instrument(event, key: key, options: options)
+
+      case found.try(:dig, 'sys', 'type')
+      when 'Nil', 'DeletedEntry', 'DeletedAsset'
+        nil
+      else
+        found
+      end
+    end
+
+    # TODO: https://github.com/watermarkchurch/wcc-contentful/issues/18
+    #  figure out how to cache the results of a find_by query, ex:
+    #  `find_by('slug' => '/about')`
+    def find_by(content_type:, filter: nil, options: nil)
+      if filter&.keys == ['sys.id']
+        # Direct ID lookup, like what we do in `WCC::Contentful::ModelMethods.resolve`
+        # We can return just this item.  Stores are not required to implement :include option.
+        if found = @cache.read(filter['sys.id'])
+          return found
+        end
+      end
+
+      store.find_by(content_type: content_type, filter: filter, options: options)
+    end
+
+    delegate :find_all, to: :store
+
+    # #index is called whenever the sync API comes back with more data.
+    def index(json)
+      delegated_result = store.index(json) if store.index?
+      caching_result = _index(json)
+      # _index returns nil if we don't already have it cached - so use the store result.
+      # store result is nil if it doesn't index, so use the caching result if we have it.
+      # They ought to be the same thing if it's cached and the store also indexes.
+      caching_result || delegated_result
+    end
+
+    def index?
+      true
+    end
+
+    private
+
+    LAZILY_CACHEABLE_TYPES = %w[
+      Entry
+      Asset
+      DeletedEntry
+      DeletedAsset
+    ].freeze
+
+    def _index(json)
+      ensure_hash(json)
+      id = json.dig('sys', 'id')
+      type = json.dig('sys', 'type')
+      prev = @cache.read(id)
+      return if prev.nil? && LAZILY_CACHEABLE_TYPES.include?(type)
+
+      if (prev_rev = prev&.dig('sys', 'revision')) && (next_rev = json.dig('sys', 'revision'))
+        return prev if next_rev < prev_rev
+      end
+
+      # we also set DeletedEntry objects in the cache - no need to go hit the API when we know
+      # this is a nil object
+      @cache.write(id, json, expires_in: expires_in)
+
+      case type
+      when 'DeletedEntry', 'DeletedAsset'
+        _instrument 'delete', id: id
+        nil
+      else
+        _instrument 'set', id: id
+        json
+      end
+    end
+
+    def nil_obj(id)
+      {
+        'sys' => {
+          'id' => id,
+          'type' => 'Nil',
+          'revision' => 1
+        }
+      }
+    end
+
+    def ensure_hash(val)
+      raise ArgumentError, 'Value must be a Hash' unless val.is_a?(Hash)
+    end
+  end
+end