wcc-contentful 0.4.0.pre.alpha → 1.0.0.pre.rc3

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)

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

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'memory_store'
+require_relative 'cdn_adapter'
+require_relative '../middleware/store'
+require_relative '../middleware/store/caching_middleware'
+
+module WCC::Contentful::Store
+  # This factory presents a DSL for configuring the store stack.  The store stack
+  # sits in between the Model layer and the datastore, which can be Contentful
+  # or something else like Postgres.
+  #
+  # A set of "presets" are available to get pre-configured stacks based on what
+  # we've found most useful.
+  class Factory
+    attr_reader :preset, :options, :config
+
+    # Set the base store instance.
+    attr_accessor :store
+
+    # An array of tuples that set up and configure a Store middleware.
+    def middleware
+      @middleware ||= self.class.default_middleware.dup
+    end
+
+    def initialize(config = WCC::Contentful.configuration, preset = :direct, options = nil)
+      @config = config
+      @preset = preset || :custom
+      @options = [*options] || []
+
+      # Infer whether they passed in a store implementation object or class
+      if class_implements_store_interface?(@preset) ||
+          object_implements_store_interface?(@preset)
+        @options.unshift(@preset)
+        @preset = :custom
+      end
+
+      configure_preset(@preset)
+    end
+
+    # Adds a middleware to the chain.  Use a block here to configure the middleware
+    # after it has been created.
+    def use(middleware, *middleware_params, &block)
+      configure_proc = block_given? ? Proc.new(&block) : nil
+      self.middleware << [middleware, middleware_params, configure_proc]
+    end
+
+    def replace(middleware, *middleware_params, &block)
+      idx = self.middleware.find_index { |m| m[0] == middleware }
+      raise ArgumentError, "Middleware #{middleware} not present" if idx.nil?
+
+      configure_proc = block_given? ? Proc.new(&block) : nil
+      self.middleware[idx] = [middleware, middleware_params, configure_proc]
+    end
+
+    def unuse(middleware)
+      idx = self.middleware.find_index { |m| m[0] == middleware }
+      return if idx.nil?
+
+      self.middleware.delete_at idx
+    end
+
+    def build(services = WCC::Contentful::Services.instance)
+      store_instance = build_store(services)
+      options = {
+        config: config,
+        services: services
+      }
+      middleware.reverse
+        .reduce(store_instance) do |memo, middleware_config|
+          # May have added a middleware with `middleware << MyMiddleware.new`
+          middleware_config = [middleware_config] unless middleware_config.is_a? Array
+
+          middleware, params, configure_proc = middleware_config
+          middleware_options = options.merge((params || []).extract_options!)
+          middleware = middleware.call(memo, *params, **middleware_options)
+          middleware&.instance_exec(&configure_proc) if configure_proc
+          middleware || memo
+        end
+    end
+
+    def validate!
+      unless preset.nil? || PRESETS.include?(preset)
+        raise ArgumentError, "Please use one of #{PRESETS} instead of #{preset}"
+      end
+
+      middleware.each do |m|
+        next if m[0].respond_to?(:call)
+
+        raise ArgumentError, "The middleware '#{m[0]&.try(:name) || m[0]}' cannot be applied!  " \
+          'It must respond to :call'
+      end
+
+      validate_store!(store)
+    end
+
+    # Sets the "eager sync" preset using one of the preregistered stores like :postgres
+    def preset_eager_sync
+      store = options.shift || :memory
+      store = SYNC_STORES[store]&.call(config, *options) if store.is_a?(Symbol)
+      self.store = store
+    end
+
+    # Configures a "lazy sync" preset which caches direct lookups but hits Contentful
+    # for any missing information.  The cache is kept up to date by the sync engine.
+    def preset_lazy_sync
+      preset_direct
+      use(WCC::Contentful::Middleware::Store::CachingMiddleware,
+        ActiveSupport::Cache.lookup_store(*options))
+    end
+
+    # Configures the default "direct" preset which passes everything through to
+    # Contentful CDN
+    def preset_direct
+      self.store = CDNAdapter.new(preview: options.include?(:preview))
+    end
+
+    def preset_custom
+      self.store = options.shift
+    end
+
+    private
+
+    def validate_store!(store)
+      raise ArgumentError, 'No store provided' unless store
+
+      return true if class_implements_store_interface?(store) ||
+        object_implements_store_interface?(store)
+
+      methods = [*store.try(:instance_methods), *store.try(:methods)]
+      WCC::Contentful::Store::Interface::INTERFACE_METHODS.each do |method|
+        next if methods.include?(method)
+
+        raise ArgumentError, "Custom store '#{store}' must respond to the #{method} method"
+      end
+    end
+
+    def configure_preset(preset)
+      unless respond_to?("preset_#{preset}")
+        raise ArgumentError, "Don't know how to build content delivery method '#{preset}'"
+      end
+
+      public_send("preset_#{preset}")
+    end
+
+    def build_store(services)
+      store_class = store
+      store =
+        if object_implements_store_interface?(store_class)
+          store_class
+        else
+          store_class.new(config, *options - [store_class])
+        end
+
+      # Inject services into the custom store class
+      (WCC::Contentful::SERVICES - %i[store preview_store]).each do |s|
+        next unless store.respond_to?("#{s}=")
+
+        store.public_send("#{s}=",
+          services.public_send(s))
+      end
+
+      store
+    end
+
+    def class_implements_store_interface?(klass)
+      (WCC::Contentful::Store::Interface::INTERFACE_METHODS -
+          (klass.try(:instance_methods) || [])).empty?
+    end
+
+    def object_implements_store_interface?(object)
+      (WCC::Contentful::Store::Interface::INTERFACE_METHODS -
+          (object.try(:methods) || [])).empty?
+    end
+
+    class << self
+      # The middleware that by default lives at the top of the middleware stack.
+      def default_middleware
+        [
+          [WCC::Contentful::Store::InstrumentationMiddleware]
+        ].freeze
+      end
+    end
+  end
+end