wcc-contentful 0.1.0 → 0.2.0

data/lib/wcc/contentful/configuration.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'http'
-
 class WCC::Contentful::Configuration
   ATTRIBUTES = %i[
     access_token
@@ -9,47 +7,79 @@ class WCC::Contentful::Configuration
     space
     default_locale
     content_delivery
-    override_get_http
+    http_adapter
+    sync_cache_store
+    webhook_username
+    webhook_password
   ].freeze
   attr_accessor(*ATTRIBUTES)
 
-  CDN_METHODS = [
-    :eager_sync,
-    # TODO: :lazy_sync
-    :direct
-  ].freeze
+  ##
+  # Defines the method by which content is downloaded from the Contentful CDN.
+  #
+  # [:direct] `config.content_delivery = :direct`
+  #           with the `:direct` method, all queries result in web requests to
+  #           'https://cdn.contentful.com' via the
+  #           {SimpleClient}[rdoc-ref:WCC::Contentful::SimpleClient::Cdn]
+  #
+  # [:eager_sync] `config.content_delivery = :eager_sync, [sync_store], [options]`
+  #               with the `:eager_sync` method, the entire content of the Contentful
+  #               space is downloaded locally and stored in the
+  #               {Sync Store}[rdoc-ref:WCC::Contentful.store].  The application is responsible
+  #               to periodically call `WCC::Contentful.sync!` to keep the store updated.
+  #               Alternatively, the provided {Engine}[WCC::Contentful::Engine]
+  #               can be mounted to receive a webhook from the Contentful space
+  #               on publish events:
+  #                 mount WCC::Contentful::Engine, at: '/wcc/contentful'
+  #
+  # [:lazy_sync] `config.content_delivery = :lazy_sync, [cache]`
+  #              The `:lazy_sync` method is a hybrid between the other two methods.
+  #              Frequently accessed data is stored in an ActiveSupport::Cache implementation
+  #              and is kept up-to-date via the Sync API.  Any data that is not present
+  #              in the cache is fetched from the CDN like in the `:direct` method.
+  #              The application is still responsible to periodically call `sync!`
+  #              or to mount the provided Engine.
+  #
+  def content_delivery=(params)
+    cd, *cd_params = params
+    unless cd.is_a? Symbol
+      raise ArgumentError, 'content_delivery must be a symbol, use store= to '\
+        'directly set contentful CDN access adapter'
+    end
 
-  SYNC_STORES = {
-    memory: ->(_config) { WCC::Contentful::Store::MemoryStore.new },
-    postgres: ->(_config) {
-      require_relative 'store/postgres_store'
-      WCC::Contentful::Store::PostgresStore.new(ENV['POSTGRES_CONNECTION'])
-    }
-  }.freeze
+    WCC::Contentful::Store::Factory.new(
+      self,
+      cd,
+      cd_params
+    ).validate!
 
-  def content_delivery=(symbol)
-    raise ArgumentError, "Please set one of #{CDN_METHODS}" unless CDN_METHODS.include?(symbol)
-    @content_delivery = symbol
+    @content_delivery = cd
+    @content_delivery_params = cd_params
   end
 
-  def sync_store=(symbol)
-    if symbol.is_a? Symbol
-      unless SYNC_STORES.keys.include?(symbol)
-        raise ArgumentError, "Please use one of #{SYNC_STORES.keys}"
-      end
-    end
-    @sync_store = symbol
+  ##
+  # Initializes the configured Sync Store.
+  def store
+    @store ||= WCC::Contentful::Store::Factory.new(
+      self,
+      @content_delivery,
+      @content_delivery_params
+    ).build_sync_store
   end
 
-  def sync_store
-    @sync_store = SYNC_STORES[@sync_store].call(self) if @sync_store.is_a? Symbol
-    @sync_store ||= Store::MemoryStore.new
+  ##
+  # Directly sets the adapter layer for communicating with Contentful
+  def store=(value)
+    @content_delivery = :custom
+    @store = value
   end
 
-  # A proc which overrides the "get_http" function in Contentful::Client.
-  # All interaction with Contentful will go through this function.
-  # Should be a lambda like: ->(url, query, headers = {}, proxy = {}) { ... }
-  attr_writer :override_get_http
+  # Sets the adapter which is used to make HTTP requests.
+  # If left unset, the gem attempts to load either 'http' or 'typhoeus'.
+  # You can pass your own adapter which responds to 'call', or even a lambda
+  # that accepts the following parameters:
+  #  ->(url, query, headers = {}, proxy = {}) { ... }
+  attr_writer :http_adapter
 
   def initialize
     @access_token = ''
@@ -57,12 +87,21 @@ class WCC::Contentful::Configuration
     @space = ''
     @default_locale = nil
     @content_delivery = :direct
-    @sync_store = :memory
   end
 
+  ##
+  # Gets a {CDN Client}[rdoc-ref:WCC::Contentful::SimpleClient::Cdn] which provides
+  # methods for getting and paging raw JSON data from the Contentful CDN.
   attr_reader :client
   attr_reader :management_client
 
+  ##
+  # Called by WCC::Contentful.init! to configure the
+  # Contentful clients.  This method can be called independently of `init!` if
+  # the application would prefer not to generate all the models.
+  #
+  # If the {contentful.rb}[https://github.com/contentful/contentful.rb] gem is
+  # loaded, it is extended to make use of the `http_adapter` lambda.
   def configure_contentful
     @client = nil
     @management_client = nil
@@ -81,13 +120,15 @@ class WCC::Contentful::Configuration
     @client = WCC::Contentful::SimpleClient::Cdn.new(
       access_token: access_token,
       space: space,
-      default_locale: default_locale
+      default_locale: default_locale,
+      adapter: http_adapter
     )
     return unless management_token.present?
     @management_client = WCC::Contentful::SimpleClient::Management.new(
       management_token: management_token,
       space: space,
-      default_locale: default_locale
+      default_locale: default_locale,
+      adapter: http_adapter
     )
   end
 end

data/lib/wcc/contentful/engine.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'wcc/rails'
+
+module WCC::Contentful
+  class Engine < ::Rails::Engine
+    isolate_namespace WCC::Contentful
+
+    config.generators do |g|
+      g.test_framework :rspec, fixture: false
+    end
+  end
+end

data/lib/wcc/contentful/exceptions.rb

@@ -31,4 +31,10 @@ module WCC::Contentful
       ret.flatten(1)
     end
   end
+
+  class SyncError < StandardError
+  end
+
+  class ContentTypeNotFoundError < NameError
+  end
 end

data/lib/wcc/contentful/graphql/builder.rb

@@ -46,7 +46,7 @@ module WCC::Contentful::Graphql
 
             resolve ->(_obj, args, _ctx) {
               if args['id'].nil?
-                store.find_by(content_type: content_type).first
+                store.find_by(content_type: content_type)
               else
                 store.find(args['id'])
               end
@@ -58,8 +58,13 @@ module WCC::Contentful::Graphql
             argument :filter, Types::FilterType
 
             resolve ->(_obj, args, ctx) {
-              relation = store.find_by(content_type: content_type)
-              relation = relation.apply(args[:filter], ctx) if args[:filter]
+              relation = store.find_all(content_type: content_type)
+              # TODO: improve this POC
+              if args[:filter]
+                filter = {}
+                filter[args[:filter]['field']] = { eq: args[:filter][:eq] }
+                relation = relation.apply(filter, ctx)
+              end
               relation.result
             }
           end

data/lib/wcc/contentful/helpers.rb

@@ -25,4 +25,10 @@ module WCC::Contentful::Helpers
       l
     end
   end
+
+  def content_type_from_constant(const)
+    return const.content_type if const.respond_to?(:content_type)
+    name = const.try(:name) || const.to_s
+    name.demodulize.camelize(:lower)
+  end
 end

data/lib/wcc/contentful/indexed_representation.rb

@@ -32,6 +32,16 @@ module WCC::Contentful
       @types.to_json
     end
 
+    def deep_dup
+      self.class.new(@types.deep_dup)
+    end
+
+    def ==(other)
+      my_keys = keys
+      return false unless my_keys == other.keys
+      my_keys.all? { |k| self[k] == other[k] }
+    end
+
     class ContentType
       ATTRIBUTES = %i[
         name
@@ -57,6 +67,18 @@ module WCC::Contentful
 
         hash_or_id.each { |k, v| public_send("#{k}=", v) }
       end
+
+      def deep_dup
+        dup_hash =
+          ATTRIBUTES.each_with_object({}) do |att, h|
+            h[att] = public_send(att)
+          end
+        self.class.new(dup_hash)
+      end
+
+      def ==(other)
+        ATTRIBUTES.all? { |att| public_send(att) == other.public_send(att) }
+      end
     end
 
     class Field
@@ -96,6 +118,11 @@ module WCC::Contentful
           return
         end
 
+        unless hash_or_id.is_a?(Hash)
+          ATTRIBUTES.each { |att| public_send("#{att}=", hash_or_id.public_send(att)) }
+          return
+        end
+
         if raw_type = hash_or_id.delete('type')
           raw_type = raw_type.to_sym
           unless TYPES.include?(raw_type)
@@ -106,6 +133,10 @@ module WCC::Contentful
 
         hash_or_id.each { |k, v| public_send("#{k}=", v) }
       end
+
+      def ==(other)
+        ATTRIBUTES.all? { |att| public_send(att) == other.public_send(att) }
+      end
     end
   end
 end

data/lib/wcc/contentful/model.rb

@@ -5,20 +5,101 @@ class WCC::Contentful::Model
   extend WCC::Contentful::Helpers
   extend WCC::Contentful::ModelValidators
 
+  # The Model base class maintains a registry which is best expressed as a
+  # class var.
+  # rubocop:disable Style/ClassVars
+
   class << self
+    ##
+    # The configured store which executes all model queries against either the
+    # Contentful CDN or a locally-downloaded copy.
+    #
+    # See the {sync_store}[rdoc-ref:WCC::Contentful::Configuration.sync_store] parameter
+    # on the WCC::Contentful::Configuration class.
     attr_accessor :store
+
+    def const_missing(name)
+      raise WCC::Contentful::ContentTypeNotFoundError,
+        "Content type '#{content_type_from_constant(name)}' does not exist in the space"
+    end
   end
 
+  @@registry = {}
+
   def self.all_models
+    # TODO: this needs to use the registry but it's OK for now cause we only
+    # use it in specs
     WCC::Contentful::Model.constants(false).map { |k| WCC::Contentful::Model.const_get(k) }
   end
 
+  ##
+  # Finds an Entry or Asset by ID in the configured contentful space
+  # and returns an initialized instance of the appropriate model type.
+  #
+  # Makes use of the configured {store}[rdoc-ref:WCC::Contentful::Model.store]
+  # to access the Contentful CDN.
   def self.find(id, context = nil)
     return unless raw = store.find(id)
 
     content_type = content_type_from_raw(raw)
 
-    const = WCC::Contentful::Model.const_get(constant_from_content_type(content_type))
+    unless const = @@registry[content_type]
+      begin
+        # The app may have defined a model and we haven't loaded it yet
+        const = Object.const_missing(constant_from_content_type(content_type).to_s)
+      rescue NameError
+        nil
+      end
+    end
+    unless const
+      # Autoloading couldn't find their model - we'll register our own.
+      const = WCC::Contentful::Model.const_get(constant_from_content_type(content_type))
+      register_for_content_type(content_type, klass: const)
+    end
+
     const.new(raw, context)
   end
+
+  ##
+  # Registers a class constant to be instantiated when resolving an instance
+  # of the given content type.  This automatically happens for the first subclass
+  # of a generated model type, example:
+  #
+  #   class MyMenu < WCC::Contentful::Model::Menu
+  #   end
+  #
+  # In the above case, instances of MyMenu will be instantiated whenever a 'menu'
+  # content type is resolved.
+  # The mapping can be made explicit with the optional parameters.  Example:
+  #
+  #   class MyFoo < WCC::Contentful::Model::Foo
+  #     register_for_content_type 'bar' # MyFoo is assumed
+  #   end
+  #
+  #   # in initializers/wcc_contentful.rb
+  #   WCC::Contentful::Model.register_for_content_type('bar', klass: MyFoo)
+  def self.register_for_content_type(content_type = nil, klass: nil)
+    klass ||= self
+    raise ArgumentError, "#{klass} must be a class constant!" unless klass.respond_to?(:new)
+    content_type ||= content_type_from_constant(klass)
+
+    @@registry[content_type] = klass
+  end
+
+  ##
+  # Returns the current registry of content type names to constants.
+  def self.registry
+    return {} unless @@registry
+    @@registry.dup.freeze
+  end
+
+  ##
+  # Checks if a content type has already been registered to a class and returns
+  # that class.  If nil, the generated WCC::Contentful::Model::{content_type} class
+  # will be resolved for this content type.
+  def self.registered?(content_type)
+    @@registry[content_type]
+  end
 end
+
+# rubocop:enable Style/ClassVars

data/lib/wcc/contentful/model_builder.rb

@@ -40,9 +40,16 @@ module WCC::Contentful
             new(raw, context) if raw.present?
           end
 
-          define_singleton_method(:find_all) do |context = nil|
-            raw = WCC::Contentful::Model.store.find_by(content_type: content_type)
-            raw.map { |r| new(r, context) }
+          define_singleton_method(:find_all) do |filter = nil, context = nil|
+            if filter
+              filter.transform_keys! { |k| k.to_s.camelize(:lower) }
+              bad_fields = filter.keys.reject { |k| fields.include?(k) }
+              raise ArgumentError, "These fields do not exist: #{bad_fields}" unless bad_fields.empty?
+            end
+
+            query = WCC::Contentful::Model.store.find_all(content_type: content_type)
+            query = query.apply(filter) if filter
+            query.map { |r| new(r, context) }
           end
 
           define_singleton_method(:find_by) do |filter, context = nil|
@@ -50,11 +57,14 @@ module WCC::Contentful
             bad_fields = filter.keys.reject { |k| fields.include?(k) }
             raise ArgumentError, "These fields do not exist: #{bad_fields}" unless bad_fields.empty?
 
-            query = WCC::Contentful::Model.store.find_by(content_type: content_type)
-            filter.each do |field, v|
-              query = query.eq(field, v, context)
-            end
-            query.map { |r| new(r, context) }
+            result = WCC::Contentful::Model.store.find_by(content_type: content_type, filter: filter)
+            new(result, context)
+          end
+
+          define_singleton_method(:inherited) do |subclass|
+            # only register if it's not already registered
+            return if WCC::Contentful::Model.registered?(typedef.content_type)
+            WCC::Contentful::Model.register_for_content_type(typedef.content_type, klass: subclass)
           end
 
           define_method(:initialize) do |raw, context = nil|

data/lib/wcc/contentful/model_validators.rb

@@ -6,43 +6,94 @@ require_relative 'model_validators/dsl'
 
 module WCC::Contentful::ModelValidators
   def schema
-    return if @field_validations.nil? || @field_validations.empty?
-    field_validations = @field_validations
+    return if validations.nil? || validations.empty?
 
-    # "page": {
-    #   "sys": { ... }
-    #   "fields": {
-    #     "title": { ... },
-    #     "sections": { ... },
-    #     ...
-    #   }
-    # }
+    all_field_validations =
+      validations.each_with_object({}) do |(content_type, procs), h|
+        next if procs.empty?
 
-    fields_schema =
-      Dry::Validation.Schema do
-        # Had to dig through the internals of Dry::Validation to find
-        # this magic incantation
-        field_validations.each { |dsl| instance_eval(&dsl.to_proc) }
+        # "page": {
+        #   "sys": { ... }
+        #   "fields": {
+        #     "title": { ... },
+        #     "sections": { ... },
+        #     ...
+        #   }
+        # }
+        h[content_type] =
+          Dry::Validation.Schema do
+            # Had to dig through the internals of Dry::Validation to find
+            # this magic incantation
+            procs.each { |dsl| instance_eval(&dsl.to_proc) }
+          end
       end
 
     Dry::Validation.Schema do
-      required('fields').schema(fields_schema)
+      all_field_validations.each do |content_type, fields_schema|
+        required(content_type).schema do
+          required('fields').schema(fields_schema)
+        end
+      end
     end
   end
 
+  def validations
+    # This needs to be a class variable so that subclasses defined in application
+    # code can add to the total package of model validations
+    # rubocop:disable Style/ClassVars
+    @@validations ||= {}
+    # rubocop:enable Style/ClassVars
+  end
+
+  ##
+  # Accepts a block which uses the {dry-validation DSL}[http://dry-rb.org/gems/dry-validation/]
+  # to validate the 'fields' object of a content type.
   def validate_fields(&block)
     raise ArgumentError, 'validate_fields requires a block' unless block_given?
     dsl = ProcDsl.new(Proc.new(&block))
 
-    (@field_validations ||= []) << dsl
+    ct = try(:content_type) || name.demodulize.camelize(:lower)
+    (validations[ct] ||= []) << dsl
   end
 
+  ##
+  # Validates a single field is of the expected type.
+  # Type expectations are one of:
+  #
+  # [:String]   the field type must be `Symbol` or `Text`
+  # [:Int]      the field type must be `Integer`
+  # [:Float]    the field type must be `Number`
+  # [:DateTime] the field type must be 'Date'
+  # [:Asset]    the field must be a link and the `linkType` must be `Asset`
+  # [:Link]     the field must be a link and the `linkType` must be `Entry`.
+  # [:Location] the field type must be `Location`
+  # [:Boolean]  the field type must be `Boolean`
+  # [:Json]     the field type must be `Json` - a json blob.
+  # [:Array]    the field must be a List.
+  #
+  # Additional validation options can be enforced:
+  #
+  # [:required] the 'Required Field' checkbox must be checked
+  # [:optional] the 'Required Field' checkbox must not be checked
+  # [:link_to]  (only `:Link` or `:Array` type) the given content type(s) must be
+  #             checked in the 'Accept only specified entry type' validations
+  #             Example:
+  #               validate_field :button, :Link, link_to: ['button', 'altButton']
+  #
+  # [:items]    (only `:Array` type) the items of the list must be of the given type.
+  #             Example:
+  #               validate_field :my_strings, :Array, items: :String
+  #
+  # Examples:
+  # see WCC::Contentful::Model::Menu and WCC::Contentful::Model::MenuButton
   def validate_field(field, type, *options)
     dsl = FieldDsl.new(field, type, options)
 
-    (@field_validations ||= []) << dsl
+    ct = try(:content_type) || name.demodulize.camelize(:lower)
+    (validations[ct] ||= []) << dsl
   end
 
+  ##
   # Accepts a content types response from the API and transforms it
   # to be acceptible for the validator.
   def self.transform_content_types_for_validation(content_types)

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+gem 'http'
+require 'http'
+
+class HttpAdapter
+  def call(url, query, headers = {}, proxy = {})
+    if proxy[:host]
+      HTTP[headers].via(proxy[:host], proxy[:port], proxy[:username], proxy[:password])
+        .get(url, params: query)
+    else
+      HTTP[headers].get(url, params: query)
+    end
+  end
+end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+gem 'typhoeus'
+require 'typhoeus'
+
+class TyphoeusAdapter
+  def call(url, query, headers = {}, proxy = {})
+    raise NotImplementedError, 'Proxying Not Yet Implemented' if proxy[:host]
+
+    TyphoeusAdapter::Response.new(
+      Typhoeus.get(
+        url,
+        params: query,
+        headers: headers
+      )
+    )
+  end
+
+  Response =
+    Struct.new(:raw) do
+      delegate :body, to: :raw
+      delegate :to_s, to: :body
+      delegate :code, to: :raw
+      delegate :headers, to: :raw
+
+      def status
+        raw.code
+      end
+    end
+end