wcc-contentful 0.3.0 → 1.0.0.pre.rc2

data/lib/wcc/contentful/simple_client/typhoeus_adapter.rb

@@ -3,15 +3,15 @@
 gem 'typhoeus'
 require 'typhoeus'
 
-class TyphoeusAdapter
-  def call(url, query, headers = {}, proxy = {})
-    raise NotImplementedError, 'Proxying Not Yet Implemented' if proxy[:host]
-
-    TyphoeusAdapter::Response.new(
+class WCC::Contentful::SimpleClient::TyphoeusAdapter
+  def get(url, params = {}, headers = {})
+    req = OpenStruct.new(params: params, headers: headers)
+    yield req if block_given?
+    Response.new(
       Typhoeus.get(
         url,
-        params: query,
-        headers: headers
+        params: req.params,
+        headers: req.headers
       )
     )
   end
@@ -19,7 +19,7 @@ class TyphoeusAdapter
   def post(url, body, headers = {}, proxy = {})
     raise NotImplementedError, 'Proxying Not Yet Implemented' if proxy[:host]
 
-    TyphoeusAdapter::Response.new(
+    Response.new(
       Typhoeus.post(
         url,
         body: body.to_json,
@@ -28,15 +28,15 @@ class TyphoeusAdapter
     )
   end
 
-  Response =
-    Struct.new(:raw) do
-      delegate :body, to: :raw
-      delegate :to_s, to: :body
-      delegate :code, to: :raw
-      delegate :headers, to: :raw
+  class Response < SimpleDelegator
+    delegate :to_s, to: :body
 
-      def status
-        raw.code
-      end
+    def raw
+      __getobj__
     end
+
+    def status
+      code
+    end
+  end
 end

data/lib/wcc/contentful/store.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-require_relative 'store/base'
-require_relative 'store/memory_store'
-require_relative 'store/cdn_adapter'
-require_relative 'store/lazy_cache_store'
+require_relative 'store/factory'
 
 # The "Store" is the middle layer in the WCC::Contentful gem.  It exposes an API
 # that implements the configured content delivery strategy.
@@ -18,84 +15,28 @@ require_relative 'store/lazy_cache_store'
 #
 # lazy_sync:: Uses the Contentful CDN in combination with an ActiveSupport::Cache
 #             implementation in order to respond with the cached data where possible,
-#             saving your CDN quota.  The cache is kept up-to-date via the Sync API
-#             and the WCC::Contentful::DelayedSyncJob.  It is correct, but not complete.
+#             saving your CDN quota.  The cache is kept up-to-date via the Sync Engine
+#             and the WCC::Contentful::SyncEngine::Job.  It is correct, but not complete.
 #
 # eager_sync:: Uses one of the full store implementations to store the entirety
 #              of the Contentful space locally.  All queries are run against this
-#              local copy, which is kept up to date via the Sync API and the
-#              WCC::Contentful::DelayedSyncJob.  The local store is correct and complete.
+#              local copy, which is kept up to date via the Sync Engine and the
+#              WCC::Contentful::SyncEngine::Job.  The local store is correct and complete.
 #
 # The currently configured store is available on WCC::Contentful::Services.instance.store
 module WCC::Contentful::Store
   SYNC_STORES = {
-    memory: ->(_config) { WCC::Contentful::Store::MemoryStore.new },
+    memory: ->(_config, *_options) { WCC::Contentful::Store::MemoryStore.new },
     postgres: ->(config, *options) {
       require_relative 'store/postgres_store'
       WCC::Contentful::Store::PostgresStore.new(config, *options)
     }
   }.freeze
 
-  CDN_METHODS = %i[
+  PRESETS = %i[
     eager_sync
     lazy_sync
     direct
     custom
   ].freeze
-
-  Factory =
-    Struct.new(:config, :services, :cdn_method, :content_delivery_params) do
-      def build_sync_store
-        unless respond_to?("build_#{cdn_method}")
-          raise ArgumentError, "Don't know how to build content delivery method #{cdn_method}"
-        end
-
-        public_send("build_#{cdn_method}", config, *content_delivery_params)
-      end
-
-      def validate!
-        unless CDN_METHODS.include?(cdn_method)
-          raise ArgumentError, "Please use one of #{CDN_METHODS} instead of #{cdn_method}"
-        end
-
-        return unless respond_to?("validate_#{cdn_method}")
-
-        public_send("validate_#{cdn_method}", config, *content_delivery_params)
-      end
-
-      def build_eager_sync(config, store = nil, *options)
-        store = SYNC_STORES[store].call(config, *options) if store.is_a?(Symbol)
-        store || MemoryStore.new
-      end
-
-      def build_lazy_sync(_config, *options)
-        WCC::Contentful::Store::LazyCacheStore.new(
-          services.client,
-          cache: ActiveSupport::Cache.lookup_store(*options)
-        )
-      end
-
-      def build_direct(_config, *options)
-        if options.find { |array| array[:preview] == true }
-          CDNAdapter.new(services.preview_client)
-        else
-          CDNAdapter.new(services.client)
-        end
-      end
-
-      def build_custom(config, *options)
-        store = config.store
-        return store unless store&.respond_to?(:new)
-
-        store.new(config, options)
-      end
-
-      def validate_eager_sync(_config, store = nil, *_options)
-        return unless store.is_a?(Symbol)
-
-        return if SYNC_STORES.key?(store)
-
-        raise ArgumentError, "Please use one of #{SYNC_STORES.keys}"
-      end
-    end
 end

data/lib/wcc/contentful/store/README.md

@@ -0,0 +1,85 @@
+# Store API
+
+The Store layer is used by the Model API to access Contentful data in a raw form.
+The Store layer returns entries as hashes parsed from JSON, conforming to the
+object structure returned from the Contentful CDN.
+
+## Public Interface
+
+See WCC::Contentful::Store::Interface in wcc/contentful/store/interface.rb
+
+This is the interface consumed by higher layers, such as the Model and GraphQL
+APIs.  It implements the following methods:
+
+* `index?` - Returns boolean true if the SyncEngine should call the store's `index(json)`
+  method with the results of a Sync.
+* `index(json)` - Updates the store with the latest data.  The JSON can be an Entry,
+  Asset, DeletedEntry, or DeletedAsset.
+* `find(id)` - Finds an entry or asset by it's ID.
+* `find_all(content_type:, options: nil)` - Returns a query object that can be
+  enumerated to lazily iterate over all values of a content type.  Query conditions
+  can be applied on the query object before it is enumerated to restrict the result
+  set.
+* `find_by(content_type:, filter: nil, options: nil)` - Returns the first entry 
+  of the given content type which matches the filter.  
+  Note: assets have the special content
+    type of `Asset` (capital A)
+
+## Implementing your own store
+
+The most straightforward way to implement a store is to include the
+WCC::Contentful::Store::Interface module and then override all the defined
+methods.  The easiest way however, is to inherit from WCC::Contentful::Store::Base
+and override the `set`, `delete`, `find`, and `execute` methods.
+
+Let's take a look at the MemoryStore for a simplistic example.  The MemoryStore
+stores entries in a simple Ruby hash keyed by entry ID.  `set` is simply
+assigning to the key in the hash and returning the old value. `delete` and `find`
+are likewise simple.  The only complex method is `execute`, because it powers the
+`find_by` and `find_all` query methods.
+
+The query passed in to `execute` is an instance of WCC::Contentful::Store::Query.
+This object contains a set of WCC::Contentful::Store::Query::Condition structs.
+Each struct is a tuple of `path`, `op`, and `expected`.  `op` is one of
+WCC::Contentful::Store::Query::Interface::OPERATORS, `path` is an array of fields
+pointing to a value in the JSON representation of an entry, and `expected` is the
+expected value that should be compared to the value selected by `path`.
+
+Since the MemoryStore only implements the equality operator, it simply digs
+out the value at the given path using `val = entry.dig(*condition.path)`
+and compares it using Contentful's definition of equality:
+```rb
+# For arrays, equality is defined as does the array include the expected value.
+# See https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters/array-equality-inequality
+if val.is_a? Array
+  val.include?(condition.expected)
+else
+  val == condition.expected
+end
+```
+
+### RSpec shared examples
+
+To ensure you have implemented all the appropriate behavior, there
+are a set of rspec shared examples in wcc/contentful/store/rspec_examples.rb which
+you can include in your specs for your store implementation.  Let's look at
+spec/wcc/contentful/store/memory_store_spec.rb to see how it's used:
+
+```rb
+require 'wcc/contentful/store/rspec_examples'
+
+RSpec.describe WCC::Contentful::Store::MemoryStore do
+  subject { WCC::Contentful::Store::MemoryStore.new }
+
+  it_behaves_like 'contentful store', {
+    # memory store does not support JOINs like `Player.find_by(team: { slug: 'dallas-cowboys' })
+    nested_queries: false,
+    # Memory store supports resolving includes, but it does so in the most naiive
+    # way possible (by recursing down the entry's links and calling #find on every one)
+    include_param: 0
+  }
+```
+
+The hash passed to the shared examples describes the features that the store
+supports.  Any key not provided causes the specs to be given the 'pending'
+attribute.  You can disable a set of specs by providing `false` for that key.

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

@@ -1,20 +1,21 @@
 # frozen_string_literal: true
 
+require_relative './interface'
+
 # @api Store
 module WCC::Contentful::Store
   # This is the base class for stores which implement #index, and therefore
   # must be kept up-to-date via the Sync API.
-  # @abstract At a minimum subclasses should override {#find}, {#find_all}, {#set},
+  # @abstract At a minimum subclasses should override {#find}, {#execute}, {#set},
   #   and #{delete}. As an alternative to overriding set and delete, the subclass
   #   can override {#index}.  Index is called when a webhook triggers a sync, to
   #   update the store.
+  #
+  # To implement a new store, you should include the rspec_examples in your rspec
+  # tests for the store.  See spec/wcc/contentful/store/memory_store_spec.rb for
+  # an example.
   class Base
-    # Finds an entry by it's ID.  The returned entry is a JSON hash
-    # @abstract Subclasses should implement this at a minimum to provide data
-    #   to the WCC::Contentful::Model API.
-    def find(_id)
-      raise NotImplementedError, "#{self.class} does not implement #find"
-    end
+    include WCC::Contentful::Store::Interface
 
     # Sets the value of the entry with the given ID in the store.
     # @abstract
@@ -28,6 +29,22 @@ module WCC::Contentful::Store
       raise NotImplementedError, "#{self.class} does not implement #delete"
     end
 
+    # Executes a WCC::Contentful::Store::Query object created by {#find_all} or
+    # {#find_by}.  Implementations should override this to translate the query's
+    # conditions into a query against the datastore.
+    #
+    # For a very naiive implementation see WCC::Contentful::Store::MemoryStore#execute
+    # @abstract
+    def execute(_query)
+      raise NotImplementedError, "#{self.class} does not implement #execute"
+    end
+
+    # Returns true if this store can persist entries and assets which are
+    # retrieved from the sync API.
+    def index?
+      true
+    end
+
     # Processes a data point received via the Sync API.  This can be a published
     # entry or asset, or a 'DeletedEntry' or 'DeletedAsset'.  The default
     # implementation calls into #set and #delete to perform the appropriate
@@ -76,17 +93,19 @@ module WCC::Contentful::Store
 
     # Finds all entries of the given content type.  A content type is required.
     #
-    # @abstract Subclasses should implement this at a minimum to provide data
-    #   to the {WCC::Contentful::Model} API.
+    # Subclasses may override this to provide their own query implementation,
+    #  or else override #execute to run the query after it has been parsed.
     # @param [String] content_type The ID of the content type to search for.
     # @param [Hash] options An optional set of additional parameters to the query
     #  defining for example include depth.  Not all store implementations respect all options.
     # @return [Query] A query object that exposes methods to apply filters
-    # rubocop:disable Lint/UnusedMethodArgument
     def find_all(content_type:, options: nil)
-      raise NotImplementedError, "#{self.class} does not implement find_all"
+      Query.new(
+        self,
+        content_type: content_type,
+        options: options
+      )
     end
-    # rubocop:enable Lint/UnusedMethodArgument
 
     def initialize
       @mutex = Concurrent::ReentrantReadWriteLock.new
@@ -96,114 +115,10 @@ module WCC::Contentful::Store
       raise ArgumentError, 'Value must be a Hash' unless val.is_a?(Hash)
     end
 
-    protected
+    private
 
     attr_reader :mutex
-
-    # The base class for query objects returned by find_all.  Subclasses should
-    # override the #result method to return an array-like containing the query
-    # results.
-    class Query
-      delegate :first, to: :result
-      delegate :map, to: :result
-      delegate :count, to: :result
-
-      OPERATORS = %i[
-        eq
-        ne
-        all
-        in
-        nin
-        exists
-        lt
-        lte
-        gt
-        gte
-        query
-        match
-      ].freeze
-
-      # @abstract Subclasses should provide this in order to fetch the results
-      #   of the query.
-      def result
-        raise NotImplementedError
-      end
-
-      def initialize(store)
-        @store = store
-      end
-
-      # @abstract Subclasses can either override this method to properly respond
-      #   to find_by query objects, or they can define a method for each supported
-      #   operator.  Ex. `#eq`, `#ne`, `#gt`.
-      def apply_operator(operator, field, expected, context = nil)
-        respond_to?(operator) ||
-          raise(ArgumentError, "Operator not implemented: #{operator}")
-
-        public_send(operator, field, expected, context)
-      end
-
-      # Called with a filter object by {Base#find_by} in order to apply the filter.
-      def apply(filter, context = nil)
-        filter.reduce(self) do |query, (field, value)|
-          if value.is_a?(Hash)
-            if op?(k = value.keys.first)
-              query.apply_operator(k.to_sym, field.to_s, value[k], context)
-            else
-              query.nested_conditions(field, value, context)
-            end
-          else
-            query.apply_operator(:eq, field.to_s, value)
-          end
-        end
-      end
-
-      protected
-
-      # naive implementation recursively descends the graph to turns links into
-      # the actual entry data.  This calls {Base#find} for each link and so it is
-      # very inefficient.
-      #
-      # @abstract Override this to provide a more efficient implementation for
-      #   a given store.
-      def resolve_includes(entry, depth)
-        return entry unless entry && depth && depth > 0 && fields = entry['fields']
-
-        fields.each do |(_name, locales)|
-          # TODO: handle non-* locale
-          locales.each do |(locale, val)|
-            locales[locale] =
-              if val.is_a? Array
-                val.map { |e| resolve_link(e, depth) }
-              else
-                resolve_link(val, depth)
-              end
-          end
-        end
-
-        entry
-      end
-
-      def resolve_link(val, depth)
-        return val unless val.is_a?(Hash) && val.dig('sys', 'type') == 'Link'
-        return val unless included = @store.find(val.dig('sys', 'id'))
-
-        resolve_includes(included, depth - 1)
-      end
-
-      private
-
-      def op?(key)
-        OPERATORS.include?(key.to_sym)
-      end
-
-      def sys?(field)
-        field.to_s =~ /sys\./
-      end
-
-      def id?(field)
-        field.to_sym == :id
-      end
-    end
   end
 end
+
+require_relative './query'

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

@@ -2,13 +2,30 @@
 
 module WCC::Contentful::Store
   class CDNAdapter
-    attr_reader :client
+    include WCC::Contentful::Store::Interface
+    # Note: CDNAdapter should not instrument store events cause it's not a store.
+
+    attr_writer :client, :preview_client
+
+    def client
+      @preview ? @preview_client : @client
+    end
+
+    # The CDNAdapter cannot index data coming back from the Sync API.
+    def index?
+      false
+    end
+
+    def index
+      raise NotImplementedError, 'Cannot put data to the CDN!'
+    end
 
     # Intentionally not implementing write methods
 
-    def initialize(client)
+    def initialize(client = nil, preview: false)
       super()
       @client = client
+      @preview = preview
     end
 
     def find(key, hint: nil, **options)
@@ -37,39 +54,61 @@ module WCC::Contentful::Store
 
     def find_all(content_type:, options: nil)
       Query.new(
-        store: self,
-        client: @client,
+        self,
+        client: client,
         relation: { content_type: content_type },
         options: options
       )
     end
 
-    class Query < Base::Query
+    class Query
+      include WCC::Contentful::Store::Query::Interface
+      include Enumerable
+
+      # by default all enumerable methods delegated to the lazy enumerable
+      delegate(*(Enumerable.instance_methods - Module.instance_methods), to: :to_enum)
+
+      # response.count gets the number of items
       delegate :count, to: :response
 
-      def result
+      def to_enum
         return response.items unless @options[:include]
 
         response.items.map { |e| resolve_includes(e, @options[:include]) }
       end
 
-      def initialize(store:, client:, relation:, options: nil, **extra)
+      def initialize(store, client:, relation:, options: nil, **extra)
         raise ArgumentError, 'Client cannot be nil' unless client.present?
         raise ArgumentError, 'content_type must be provided' unless relation[:content_type].present?
 
-        super(store)
+        @store = store
         @client = client
         @relation = relation
         @options = options || {}
         @extra = extra || {}
       end
 
+      # Called with a filter object by {Base#find_by} in order to apply the filter.
+      def apply(filter, context = nil)
+        filter.reduce(self) do |query, (field, value)|
+          if value.is_a?(Hash)
+            if op?(k = value.keys.first)
+              query.apply_operator(k.to_sym, field.to_s, value[k], context)
+            else
+              query.nested_conditions(field, value, context)
+            end
+          else
+            query.apply_operator(:eq, field.to_s, value)
+          end
+        end
+      end
+
       def apply_operator(operator, field, expected, context = nil)
         op = operator == :eq ? nil : operator
         param = parameter(field, operator: op, context: context, locale: true)
 
         self.class.new(
-          store: @store,
+          @store,
           client: @client,
           relation: @relation.merge(param => expected),
           options: @options,
@@ -85,7 +124,7 @@ module WCC::Contentful::Store
         end
       end
 
-      Base::Query::OPERATORS.each do |op|
+      WCC::Contentful::Store::Query::Interface::OPERATORS.each do |op|
         define_method(op) do |field, expected, context = nil|
           apply_operator(op, field, expected, context)
         end
@@ -93,6 +132,18 @@ module WCC::Contentful::Store
 
       private
 
+      def op?(key)
+        WCC::Contentful::Store::Query::Interface::OPERATORS.include?(key.to_sym)
+      end
+
+      def sys?(field)
+        field.to_s =~ /sys\./
+      end
+
+      def id?(field)
+        field.to_sym == :id
+      end
+
       def response
         @response ||=
           if @relation[:content_type] == 'Asset'
@@ -104,11 +155,19 @@ module WCC::Contentful::Store
           end
       end
 
-      def resolve_link(val, depth)
+      def resolve_includes(entry, depth)
+        return entry unless entry && depth && depth > 0
+
+        WCC::Contentful::LinkVisitor.new(entry, :Link, :Asset, depth: depth - 1).map! do |val|
+          resolve_link(val)
+        end
+      end
+
+      def resolve_link(val)
         return val unless val.is_a?(Hash) && val.dig('sys', 'type') == 'Link'
         return val unless included = response.includes[val.dig('sys', 'id')]
 
-        resolve_includes(included, depth - 1)
+        included
       end
 
       def parameter(field, operator: nil, context: nil, locale: false)