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

data/app/jobs/wcc/contentful/webhook_enable_job.rb

@@ -7,7 +7,9 @@ module WCC::Contentful
     self.queue_adapter = :async
     queue_as :default
 
-    def perform(args)
+    def perform(args = {})
+      args = default_configuration.merge!(args)
+
       client = WCC::Contentful::SimpleClient::Management.new(
         args
       )
@@ -26,7 +28,8 @@ module WCC::Contentful
         'topics' => [
           '*.publish',
           '*.unpublish'
-        ]
+        ],
+        'filters' => webhook_filters
       }
       body['httpBasicUsername'] = webhook_username if webhook_username.present?
       body['httpBasicPassword'] = webhook_password if webhook_password.present?
@@ -39,5 +42,36 @@ module WCC::Contentful
         raise
       end
     end
+
+    private
+
+    def default_configuration
+      return {} unless config = WCC::Contentful&.configuration
+
+      {
+        management_token: config.management_token,
+        app_url: config.app_url,
+        space: config.space,
+        environment: config.environment,
+        default_locale: config.default_locale,
+        connection: config.connection,
+        webhook_username: config.webhook_username,
+        webhook_password: config.webhook_password
+      }
+    end
+
+    def webhook_filters
+      filters = []
+
+      if (environment_id = WCC::Contentful.configuration&.environment).present?
+        filters << {
+          'equals' => [
+            { 'doc' => 'sys.environment.sys.id' },
+            environment_id
+          ]
+        }
+      end
+      filters
+    end
   end
 end

data/config/routes.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 WCC::Contentful::Engine.routes.draw do
-  post 'webhook/receive', to: 'webhook#receive'
+  post 'webhook/receive', to: 'wcc/contentful/webhook#receive'
 end

data/doc

@@ -0,0 +1 @@
+./../doc/wcc-contentful

data/lib/tasks/download_schema.rake

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'wcc/contentful'
+require 'wcc/contentful/downloads_schema'
+
+namespace :wcc_contentful do
+  desc 'Downloads the schema from the currently configured space and stores it in ' \
+    'db/contentful-schema.json'
+  task download_schema: :environment do
+    WCC::Contentful::DownloadsSchema.call
+  end
+end

data/lib/wcc/contentful.rb

@@ -5,9 +5,12 @@ require 'wcc/contentful/version'
 require 'active_support'
 require 'active_support/core_ext/object'
 
+require 'wcc/contentful/active_record_shim'
 require 'wcc/contentful/configuration'
+require 'wcc/contentful/downloads_schema'
 require 'wcc/contentful/exceptions'
 require 'wcc/contentful/helpers'
+require 'wcc/contentful/link_visitor'
 require 'wcc/contentful/services'
 require 'wcc/contentful/simple_client'
 require 'wcc/contentful/store'
@@ -16,6 +19,9 @@ require 'wcc/contentful/model'
 require 'wcc/contentful/model_methods'
 require 'wcc/contentful/model_singleton_methods'
 require 'wcc/contentful/model_builder'
+require 'wcc/contentful/sync_engine'
+require 'wcc/contentful/events'
+require 'wcc/contentful/middleware'
 
 # The root namespace of the wcc-contentful gem
 #
@@ -23,16 +29,33 @@ require 'wcc/contentful/model_builder'
 # initializer.
 module WCC::Contentful
   class << self
+    attr_reader :initialized
+
     # Gets the current configuration, after calling WCC::Contentful.configure
     attr_reader :configuration
 
     attr_reader :types
+
+    # Gets all queryable locales.
+    # Reserved for future use.
+    def locales
+      @locales ||= { 'en-US' => {} }.freeze
+    end
+
+    def logger
+      return Rails.logger if defined?(Rails)
+
+      @logger ||= Logger.new(STDERR)
+    end
   end
 
   # Configures the WCC::Contentful gem to talk to a Contentful space.
   # This must be called first in your initializer, before #init! or accessing the
   # client.
+  # See WCC::Contentful::Configuration for all configuration options.
   def self.configure
+    raise InitializationError, 'Cannot configure after initialization' if @initialized
+
     @configuration ||= Configuration.new
     yield(configuration)
 
@@ -51,29 +74,60 @@ module WCC::Contentful
   #   class Page < WCC::Contentful::Model::Page; end
   #   Page.find_by(slug: 'about-us')
   def self.init!
-    raise ArgumentError, 'Please first call WCC:Contentful.configure' if configuration.nil?
+    raise InitializationError, 'Please first call WCC:Contentful.configure' if configuration.nil?
+    raise InitializationError, 'Already Initialized' if @initialized
 
-    # we want as much as possible the raw JSON from the API so use the management
-    # client if possible
-    client = Services.instance.management_client ||
-      Services.instance.client
+    if configuration.update_schema_file == :always ||
+        (configuration.update_schema_file == :if_possible && Services.instance.management_client) ||
+        configuration.update_schema_file == :if_missing && !File.exist?(configuration.schema_file)
 
-    @content_types = client.content_types(limit: 1000).items
+      begin
+        downloader = WCC::Contentful::DownloadsSchema.new
+        downloader.update! if configuration.update_schema_file == :always || downloader.needs_update?
+      rescue WCC::Contentful::SimpleClient::ApiError => e
+        raise InitializationError, e if configuration.update_schema_file == :always
 
-    indexer =
-      ContentTypeIndexer.new.tap do |ixr|
-        @content_types.each { |type| ixr.index(type) }
+        WCC::Contentful.logger.warn("Unable to download schema from management API - #{e.message}")
       end
-    @types = indexer.types
+    end
 
-    store = Services.instance.store
-    if store.respond_to?(:index)
-      # Drop an initial sync
-      WCC::Contentful::DelayedSyncJob.perform_later
+    @content_types =
+      begin
+        if File.exist?(configuration.schema_file)
+          JSON.parse(File.read(configuration.schema_file))['contentTypes']
+        end
+      rescue JSON::ParserError
+        WCC::Contentful.logger.warn("Schema file invalid, ignoring it: #{configuration.schema_file}")
+        nil
+      end
+
+    if !@content_types && %i[if_possible never].include?(configuration.update_schema_file)
+      # Final fallback - try to grab content types from CDN.  We can't update the file
+      # because the CDN doesn't have all the field validation info, but we can at least
+      # build the WCC::Contentful::Model instances.
+      client = Services.instance.management_client ||
+        Services.instance.client
+      begin
+        @content_types = client.content_types(limit: 1000).items if client
+      rescue WCC::Contentful::SimpleClient::ApiError => e
+        # indicates bad credentials
+        WCC::Contentful.logger.warn("Unable to load content types from API - #{e.message}")
+      end
     end
 
-    WCC::Contentful::ModelBuilder.new(@types).build_models
+    unless @content_types
+      raise InitializationError, 'Unable to load content types from schema file or API!' \
+        ' Check your access token and space ID.'
+    end
 
-    require_relative 'contentful/client_ext' if defined?(::Contentful)
+    indexer = ContentTypeIndexer.from_json_schema(@content_types)
+    @types = indexer.types
+
+    # Drop an initial sync
+    WCC::Contentful::SyncEngine::Job.perform_later if defined?(WCC::Contentful::SyncEngine::Job)
+
+    WCC::Contentful::ModelBuilder.new(@types).build_models
+    @configuration = @configuration.freeze
+    @initialized = true
   end
 end

data/lib/wcc/contentful/active_record_shim.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module WCC::Contentful::ActiveRecordShim
+  extend ActiveSupport::Concern
+
+  def attributes
+    @attributes ||= to_h['fields'].tap { |fields| fields['id'] = id }
+  end
+
+  def cache_key
+    return cache_key_with_version unless ActiveRecord::Base.try(:cache_versioning) == true
+
+    "#{self.class.model_name}/#{id}"
+  end
+
+  def cache_key_with_version
+    "#{self.class.model_name}/#{id}-#{cache_version}"
+  end
+
+  def cache_version
+    sys.revision.to_s
+  end
+
+  included do
+    unless defined?(ActiveRecord)
+      raise NotImplementedError, 'WCC::Contentful::ActiveRecordShim requires ActiveRecord to be loaded'
+    end
+  end
+
+  class_methods do
+    def model_name
+      WCC::Contentful::Helpers.constant_from_content_type(content_type)
+    end
+
+    def const_get(name)
+      # Because our pattern is `class MyModel < WCC::Contentful::Model::MyModel`
+      # if you do MyModel.const_get('MyModel') Algolia expects you to return
+      # ::MyModel not WCC::Contentful::Model::MyModel
+      return self if name == model_name
+
+      super
+    end
+
+    def table_name
+      model_name.tableize
+    end
+
+    def unscoped
+      yield
+    end
+
+    def find_in_batches(options, &block)
+      options ||= {}
+      batch_size = options.delete(:batch_size) || 1000
+      filter = {
+        options: {
+          limit: batch_size,
+          skip: options.delete(:start) || 0,
+          include: options.delete(:include) || 1
+        }
+      }
+
+      find_all(filter).each_slice(batch_size, &block)
+    end
+
+    def where(**conditions)
+      # TODO: return a Query object that implements more of the ActiveRecord query interface
+      # https://guides.rubyonrails.org/active_record_querying.html#conditions
+      find_all(conditions)
+    end
+  end
+end

data/lib/wcc/contentful/configuration.rb

@@ -1,22 +1,61 @@
 # frozen_string_literal: true
 
+# This object contains all the configuration options for the `wcc-contentful` gem.
 class WCC::Contentful::Configuration
   ATTRIBUTES = %i[
+    space
     access_token
     app_url
     management_token
-    space
     environment
     default_locale
-    content_delivery
     preview_token
-    http_adapter
-    sync_cache_store
     webhook_username
     webhook_password
     webhook_jobs
+    connection
+    connection_options
+    update_schema_file
+    schema_file
+    store
+    instrumentation_adapter
   ].freeze
-  attr_accessor(*ATTRIBUTES)
+
+  # (required) Sets the Contentful Space ID.
+  attr_accessor :space
+  # (required) Sets the Content Delivery API access token.
+  attr_accessor :access_token
+
+  # Sets the app's root URL for a Rails app.  Used by the WCC::Contentful::Engine
+  # to automatically set up webhooks to point at the WCC::Contentful::WebhookController
+  attr_accessor :app_url
+  # Sets the Content Management Token used to communicate with the Management API.
+  # This is required for automatically setting up webhooks, and to create the
+  # WCC::Contentful::Services#management_client.
+  attr_accessor :management_token
+  # Sets the Environment ID.  Leave blank to use master.
+  attr_accessor :environment
+  # Sets the default locale.  Defaults to 'en-US'.
+  attr_accessor :default_locale
+  # Sets the Content Preview API access token.  Only required if you use the
+  # preview flag.
+  attr_accessor :preview_token
+  # Sets an optional basic auth username that will be validated by the webhook controller.
+  # You must ensure the configured webhook sets the "HTTP Basic Auth username"
+  attr_accessor :webhook_username
+  # Sets an optional basic auth password that will be validated by the webhook controller.
+  # You must ensure the configured webhook sets the "HTTP Basic Auth password"
+  attr_accessor :webhook_password
+  # An array of jobs that are run whenever a webhook is received by the webhook controller.
+  # The job can be an ActiveJob class which responds to `:perform_later`, or a lambda or
+  # other object that responds to `:call`.
+  # Example:
+  #  config.webhook_jobs << MyJobClass
+  #  config.webhook_jobs << ->(event) { ... }
+  #
+  # See the source code for WCC::Contentful::SyncEngine::Job for an example of how
+  # to implement a webhook job.
+  attr_accessor :webhook_jobs
 
   # Returns true if the currently configured environment is pointing at `master`.
   def master?
@@ -25,22 +64,23 @@ class WCC::Contentful::Configuration
 
   # Defines the method by which content is downloaded from the Contentful CDN.
   #
-  # [:direct] `config.content_delivery = :direct`
+  # [:direct] `config.store :direct`
   #           with the `:direct` method, all queries result in web requests to
   #           'https://cdn.contentful.com' via the
   #           {WCC::Contentful::SimpleClient::Cdn SimpleClient}
   #
-  # [:eager_sync] `config.content_delivery = :eager_sync, [sync_store], [options]`
+  # [:eager_sync] `config.store :eager_sync, [sync_store], [options]`
   #               with the `:eager_sync` method, the entire content of the Contentful
   #               space is downloaded locally and stored in the
   #               {WCC::Contentful::Services#store configured store}.  The application is
-  #               responsible to periodically call `WCC::Contentful.sync!` to keep the store
-  #               updated. Alternatively, the provided {WCC::Contentful::Engine Engine}
-  #               can be mounted to receive a webhook from the Contentful space
-  #               on publish events:
-  #                 mount WCC::Contentful::Engine, at: '/wcc/contentful'
+  #               responsible to periodically call the WCC::Contentful::SyncEngine#next to
+  #               keep the store updated. Alternatively, the provided {WCC::Contentful::Engine Engine}
+  #               can be mounted to automatically call WCC::Contentful::SyncEngine#next on
+  #               webhook events.
+  #               In `routes.rb` add the following:
+  #                 mount WCC::Contentful::Engine, at: '/'
   #
-  # [:lazy_sync] `config.content_delivery = :lazy_sync, [cache]`
+  # [:lazy_sync] `config.store :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
@@ -48,62 +88,153 @@ class WCC::Contentful::Configuration
   #              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'
+  # [:custom] `config.store :custom, do ... end`
+  #           The block is executed in the context of a WCC::Contentful::Store::Factory.
+  #           this can be used to apply middleware, etc.
+  def store(*params, &block)
+    type, *params = params
+    if type
+      @store_factory = WCC::Contentful::Store::Factory.new(
+        self,
+        type,
+        params
+      )
     end
 
-    WCC::Contentful::Store::Factory.new(
-      self,
-      nil,
-      cd,
-      cd_params
-    ).validate!
+    @store_factory.instance_exec(&block) if block_given?
+    @store_factory
+  end
 
-    @content_delivery = cd
-    @content_delivery_params = cd_params
+  # Convenience for setting store without a block
+  def store=(param_array)
+    store(*param_array)
   end
 
-  attr_reader :content_delivery_params
+  # Explicitly read the store factory
+  attr_reader :store_factory
+
+  # Sets the connection which is used to make HTTP requests.
+  # If left unset, the gem attempts to load 'faraday' or 'typhoeus'.
+  # You can pass your own adapter which responds to 'get' and 'post', and returns
+  # a response that quacks like Faraday.
+  attr_accessor :connection
+
+  # Sets the connection options which are given to the client.  This can include
+  # an alternative Cdn API URL, timeouts, etc.
+  # See WCC::Contentful::SimpleClient constructor for details.
+  attr_accessor :connection_options
 
-  # Directly sets the adapter layer for communicating with Contentful
-  def store=(value)
-    @content_delivery = :custom
-    store, *cd_params = value
-    @store = store
-    @content_delivery_params = cd_params
+  # Indicates whether to update the contentful-schema.json file for building models.
+  # The schema can also be updated with `rake wcc_contentful:download_schema`
+  # Valid values are:
+  #
+  # [:never] wcc-contentful will not update the schema even if a management token is available.
+  #          If your schema file is out of date this could cause null-reference errors or
+  #          not found errors at runtime.  If your schema file does not exist or is invalid,
+  #          WCC::Contentful.init! will raise a WCC::Contentful::InitializitionError
+  #
+  # [:if_missing] wcc-contentful will only download the schema if the schema file
+  #               doesn't exist.
+  #
+  # [:if_possible] wcc-contentful will attempt to reach out to the management API for
+  #                content types, and will fall back to the schema file if the API
+  #                cannot be reached.  This is the default.
+  #
+  # [:always] wcc-contentful will check either the management API or the CDN for the
+  #           most up-to-date content types and will raise a
+  #           WCC::Contentful::InitializationError if the API cannot be reached.
+  def update_schema_file=(sym)
+    valid_syms = %i[never if_possible if_missing always]
+    unless valid_syms.include?(sym)
+      raise ArgumentError, "update_schema_file must be one of #{valid_syms}"
+    end
+
+    @update_schema_file = sym
   end
+  attr_reader :update_schema_file
 
-  attr_reader :store
+  # The file to store the Contentful schema in.  You should check this into source
+  # control, similar to `db/schema.rb`.  This filename is relative to the rails root.
+  # Defaults to 'db/contentful-schema.json
+  attr_writer :schema_file
+
+  def schema_file
+    if defined?(Rails)
+      Rails.root.join(@schema_file)
+    else
+      @schema_file
+    end
+  end
 
-  # 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
+  # Overrides the use of ActiveSupport::Notifications throughout this library to
+  # emit instrumentation events.  The object or module provided here must respond
+  # to :instrument like ActiveSupport::Notifications.instrument
+  attr_accessor :instrumentation_adapter
 
   def initialize
-    @access_token = ''
+    @access_token = ENV['CONTENTFUL_ACCESS_TOKEN']
     @app_url = ENV['APP_URL']
-    @management_token = ''
-    @preview_token = ''
-    @space = ''
+    @connection_options = {
+      api_url: 'https://cdn.contentful.com/',
+      preview_api_url: 'https://preview.contentful.com/',
+      management_api_url: 'https://api.contentful.com'
+    }
+    @management_token = ENV['CONTENTFUL_MANAGEMENT_TOKEN']
+    @preview_token = ENV['CONTENTFUL_PREVIEW_TOKEN']
+    @space = ENV['CONTENTFUL_SPACE_ID']
     @default_locale = nil
-    @content_delivery = :direct
+    @middleware = []
+    @update_schema_file = :if_possible
+    @schema_file = 'db/contentful-schema.json'
     @webhook_jobs = []
+    @store_factory = WCC::Contentful::Store::Factory.new(self, :direct)
   end
 
+  # Validates the configuration, raising ArgumentError if anything is wrong.  This
+  # is called by WCC::Contentful.init!
   def validate!
     raise ArgumentError, 'Please provide "space"' unless space.present?
     raise ArgumentError, 'Please provide "access_token"' unless access_token.present?
 
-    webhook_jobs&.each do |job|
+    store_factory.validate!
+
+    if update_schema_file == :always && management_token.blank?
+      raise ArgumentError, 'A management_token is required in order to update the schema file.'
+    end
+
+    webhook_jobs.each do |job|
       next if job.respond_to?(:call) || job.respond_to?(:perform_later)
 
       raise ArgumentError, "The job '#{job}' must be an instance of ActiveJob::Base or respond to :call"
     end
   end
+
+  def frozen?
+    false
+  end
+
+  def freeze
+    FrozenConfiguration.new(self)
+  end
+
+  class FrozenConfiguration
+    attr_reader(*ATTRIBUTES)
+
+    def initialize(configuration)
+      ATTRIBUTES.each do |att|
+        val = configuration.public_send(att)
+        val.freeze if val.is_a?(Hash) || val.is_a?(Array)
+        instance_variable_set("@#{att}", val)
+      end
+    end
+
+    # Returns true if the currently configured environment is pointing at `master`.
+    def master?
+      !environment.present?
+    end
+
+    def frozen?
+      true
+    end
+  end
 end