wcc-contentful 0.2.2 → 0.3.0.pre.rc

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 58ee6d756754247484bf90a993340caf891a7471
-  data.tar.gz: 947b949744aacf47612a91237e70807e91c53664
+  metadata.gz: '08ab30632430c1a52ed10b696480397ac53fc682'
+  data.tar.gz: be04ea6c9ce005456b08cf87770b70c466dadcff
 SHA512:
-  metadata.gz: b89c3971ea984941b7f6dcba32cf1b9942417236a8074224304716379bccc9e8a7e10cfb646cece2d4989b514ee8ada7e55bc65f03668d8686482418d2699dc9
-  data.tar.gz: 47ebcda216d33570a8a99018131c84411bbc42c3dead50c47632bc3b2e1d516d3af18447b31e2c17dc003e7805423e4bef891545c3302fd6fa1792504cf4d6bd
+  metadata.gz: 1f0c325803a5b8c5f0a228401fea6634e9498c21cf50ac929d8881d5772a70732e8e4a7346fcd8e13e0434b0a42d3687480818750fe0008ff4cc2bfef76169d3
+  data.tar.gz: 90f7524d0bdbbbc5b40db0f060e6e631dabaeff0ee5fb8142eeadde3117cf6b6add58dec68914454fe9ef28db608b3e29af2ae5f6b616460842b31662677b257

data/.rspec

@@ -1,4 +1,3 @@
 --format documentation
 --color
---require spec_helper
 --order rand

data/README.md

@@ -1,3 +1,8 @@
+[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://badge.fury.io/rb/wcc-contentful)
+[![CircleCI](https://circleci.com/gh/watermarkchurch/wcc-contentful.svg?style=svg)](https://circleci.com/gh/watermarkchurch/wcc-contentful)
+
+Full documentation: https://www.rubydoc.info/github/watermarkchurch/wcc-contentful
+
 # WCC::Contentful
 
 ## Installation
@@ -21,20 +26,188 @@ Or install it yourself as:
 ```ruby
 WCC::Contentful.configure do |config|
   config.access_token = <CONTENTFUL_ACCESS_TOKEN>
-  config.preview_token = <CONTENTFUL_PREVIEW_TOKEN>
   config.space = <CONTENTFUL_SPACE_ID>
-  config.default_locale = "en-US"
 end
+
+WCC::Contentful.init!
 ```
 
 ## Usage
 
-```ruby
-redirect_object = WCC::Contentful::Model::Redirect.find_by({slug: 'published-redirect'}, preview: false)
-redirect_object.href
+### WCC::Contentful::Model API
+
+The WCC::Contentful::Model API exposes Contentful data as a set of dynamically
+generated Ruby objects.  These objects are based on the content types in your
+Contentful space.  All these objects are generated by WCC::Contentful.init!
+
+The following examples show how to use this API to find entries of the `page`
+content type:
 
-preview_redirect_object = WCC::Contentful::Model::Redirect.find_by({slug: 'draft-redirect'}, preview: true)
+```ruby
+# Find objects by id
+WCC::Contentful::Model::Page.find('1E2ucWSdacxxf233sfa3')
+# => #<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>
+
+# Find objects by field
+WCC::Contentful::Model::Page.find_by(slug: '/some-slug')
+# => #<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>
+
+# Use operators to filter by a field
+# must use full notation for sys attributes (except ID)
+WCC::Contentful::Model::Page.find_all('sys.created_at' => { lte: Date.today })
+# => [#<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>, ... ]
+
+# Nest queries to mimick joins
+WCC::Contentful::Model::Page.find_by(subpages: { slug: '/some-slug' })
+# => #<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>
+
+# Pass the preview flag to use the preview client (must have set preview_token config param)
+preview_redirect = WCC::Contentful::Model::Redirect.find_by({ slug: 'draft-redirect' }, preview: true)
+# => #<WCC::Contentful::Model::Redirect:0x0000000005d879ad @created_at=2018-04-16 18:41:17 UTC...>
 preview_redirect_object.href
+# => 'http://www.somesite.com/slug-for-redirect'
+```
+
+See the {WCC::Contentful::Model} documentation for more details.
+
+### 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.
+
+The following examples show how to use the Store API to retrieve raw data from
+the store:
+
+```ruby
+store = WCC::Contentful::Services.instance.store
+# => #<WCC::Contentful::Store::CDNAdapter:0x00007fb92a221498
+
+store.find('5FsqsbMECsM62e04U8sY4Y')
+# => {"sys"=>
+#  ...
+# "fields"=>
+# ...}
+
+store.find_by(content_type: 'page', filter: { slug: '/some-slug' })
+# => {"sys"=>
+#  ...
+# "fields"=>
+# ...}
+
+query = store.find_all(content_type: 'page').eq('group', 'some-group')
+# => #<WCC::Contentful::Store::CDNAdapter::Query:0x00007fa3d40b84f0
+query.first
+# => {"sys"=>
+#  ...
+# "fields"=>
+# ...}
+query.result
+# => #<Enumerator::Lazy: ...>
+query.result.force
+# => [{"sys"=> ...}, {"sys"=> ...}, ...]
+```
+
+See the {WCC::Contentful::Store} documentation for more details.
+
+### Direct CDN API (SimpleClient)
+
+The SimpleClient is the bottom layer, and is used to get raw data directly from
+the Contentful CDN.  It handles response parsing and paging, but does not resolve
+links or transform the result into a Model class.
+
+The following examples show how to use the SimpleClient to retrieve data directly
+from the Contentful CDN:
+
+```ruby
+client = WCC::Contentful::Services.instance.client
+# => #<WCC::Contentful::SimpleClient::Cdn:0x00007fa3cde89310
+
+response = client.entry('5FsqsbMECsM62e04U8sY4Y')
+# => #<WCC::Contentful::SimpleClient::Response:0x00007fa3d103a4e0
+response.body
+# => "{\n  \"sys\": {\n ...
+response.raw
+# => {"sys"=>
+#  ...
+# "fields"=>
+# ...}
+
+client.asset('5FsqsbMECsM62e04U8sY4Y').raw
+# => {"sys"=>
+#  ...
+# "fields"=>
+# ...}
+
+response = client.entries('fields.group' => 'some-group', 'limit' => 5)
+# => #<WCC::Contentful::SimpleClient::Response:0x00007fa3d103a4e0
+response.count
+# => 99
+response.first
+# => {"sys"=>
+#  ...
+# "fields"=>
+# ...}
+response.items
+=> #<Enumerator::Lazy: ...>
+response.items.count  # Careful! This evaluates the lazy iterator and gets all pages
+# => 99
+
+response.includes
+# => {"4xNnFJ77egkSMEogE2yISa"=>
+#   {"sys"=> ...}
+#  "6Fwukxxkxa6qQCC04WCaqg"=>
+#   {"sys"=> ...}
+#   ...}
+```
+
+The client handles Paging automatically within the lazy iterator returned by #items.
+This lazy iterator does not respect the `limit` param - that param is only passed
+through to the API to set the page size.
+
+Entries included via the `include` parameter are made available on the #includes
+field.  This is a hash of `<entry ID> => <raw entry>` and makes it easy to grab
+links.  This hash is added to lazily as you enumerate the pages.
+
+See the {WCC::Contentful::SimpleClient} documentation for more details.
+
+### Accessing the APIs within application code
+
+The Model API is best exposed by defining your own model classes in the `app/models`
+directory which inherit from the WCC::Contentful models.
+
+```ruby
+# app/models/page.rb
+class Page < WCC::Contentful::Model::Page
+
+  # You can add additional methods here
+end
+
+# app/controllers/pages_controller.rb
+class PagesController < ApplicationController
+  def show
+    @page = Page.find_by(slug: params[:slug])
+    raise Exceptions::PageNotFoundError, params[:slug] unless @page
+  end
+end
+```
+
+The {WCC::Contentful::Services} singleton gives access to the other configured services.
+You can also include the {WCC::Contentful::ServiceAccessors} concern to define these
+services as attributes in a class.
+
+```ruby
+class MyJob < ApplicationJob
+  include WCC::Contentful::ServiceAccessors
+
+  def perform
+    Page.find(...)
+
+    store.find(...)
+
+    client.entries(...)
+  end
+end
 ```
 
 ## Development
@@ -45,7 +218,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/wcc-contentful. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/watermarkchurch/wcc-contentful. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 ## License
 
@@ -53,4 +226,4 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## Code of Conduct
 
-Everyone interacting in the WCC::Contentful project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/wcc-contentful/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the WCC::Contentful project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/watermarkchurch/wcc-contentful/blob/master/CODE_OF_CONDUCT.md).

data/app/controllers/wcc/contentful/webhook_controller.rb

@@ -3,13 +3,45 @@
 require_dependency 'wcc/contentful/application_controller'
 
 module WCC::Contentful
+  # The WebhookController is mounted by the WCC::Contentful::Engine to receive
+  # webhook events from Contentful.  It passes these webhook events to
+  # the jobs configured in {WCC::Contentful::Configuration WCC::Contentful::Configuration#webhook_jobs}
   class WebhookController < ApplicationController
+    include WCC::Contentful::ServiceAccessors
+
     before_action :authorize_contentful
+    protect_from_forgery unless: -> { request.format.json? }
+
+    rescue_from ActionController::ParameterMissing do |_e|
+      render json: { msg: 'The request must conform to Contentful webhook structure' }, status: 400
+    end
 
     def receive
-      WCC::Contentful.sync!(up_to_id: params.dig('sys', 'id'))
+      event = params.require('webhook').permit!
+      event.require('sys').require(%w[id type])
+      event = event.to_h
+
+      # Immediately update the store, we may update again later using DelayedSyncJob.
+      store.index(event) if store.respond_to?(:index)
+
+      jobs.each do |job|
+        begin
+          if job.respond_to?(:perform_later)
+            job.perform_later(event)
+          elsif job.respond_to?(:call)
+            job.call(event)
+          else
+            Rails.logger.error "Misconfigured webhook job: #{job} does not respond to " \
+              ':perform_later or :call'
+          end
+        rescue StandardError => e
+          Rails.logger.error "Error in job #{job}: #{e}"
+        end
+      end
     end
 
+    private
+
     def authorize_contentful
       config = WCC::Contentful.configuration
 
@@ -23,8 +55,16 @@ module WCC::Contentful
         end
       end
 
-      return if request.content_type == 'application/vnd.contentful.management.v1+json'
+      # 'application/vnd.contentful.management.v1+json' is an alias for the 'application/json'
+      # content-type, so 'request.content_type' will give 'application/json'
+      return if request.headers['Content-Type'] == 'application/vnd.contentful.management.v1+json'
+
       render json: { msg: 'This endpoint only responds to webhooks from Contentful' }, status: 406
     end
+
+    def jobs
+      jobs = [WCC::Contentful::DelayedSyncJob]
+      jobs.push(*WCC::Contentful.configuration.webhook_jobs)
+    end
   end
 end

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

@@ -3,12 +3,61 @@
 require 'active_job'
 
 module WCC::Contentful
+  # This job uses the Contentful Sync API to update the configured store with
+  # the latest data from Contentful.
   class DelayedSyncJob < ActiveJob::Base
+    include WCC::Contentful::ServiceAccessors
+
+    self.queue_adapter = :async
     queue_as :default
 
-    def perform(*args)
-      sync_options = args.first || {}
-      WCC::Contentful.sync!(**sync_options)
+    def self.mutex
+      @mutex ||= Mutex.new
+    end
+
+    def perform(event = nil)
+      up_to_id = nil
+      up_to_id = event[:up_to_id] || event.dig('sys', 'id') if event
+      sync!(up_to_id: up_to_id)
+    end
+
+    # Calls the Contentful Sync API and updates the configured store with the returned
+    # data.
+    #
+    # @param [String] up_to_id
+    #  An ID that we know has changed and should come back from the sync.
+    #  If we don't find this ID in the sync data, then drop a job to try
+    #  the sync again after a few minutes.
+    #
+    def sync!(up_to_id: nil)
+      return unless store.respond_to?(:index)
+
+      self.class.mutex.synchronize do
+        next_sync_token = store.find('sync:token')&.fetch('token')
+        sync_resp = client.sync(sync_token: next_sync_token)
+
+        id_found = up_to_id.nil?
+
+        count = 0
+        sync_resp.items.each do |item|
+          id = item.dig('sys', 'id')
+          id_found ||= id == up_to_id
+          store.index(item)
+          count += 1
+        end
+        store.set('sync:token', token: sync_resp.next_sync_token)
+
+        logger.info "Synced #{count} entries.  Next sync token:\n  #{sync_resp.next_sync_token}"
+        sync_later!(up_to_id: up_to_id) unless id_found
+        sync_resp.next_sync_token
+      end
+    end
+
+    # Drops an ActiveJob job to invoke WCC::Contentful.sync! after a given amount
+    # of time.
+    def sync_later!(up_to_id: nil, wait: 10.minutes)
+      WCC::Contentful::DelayedSyncJob.set(wait: wait)
+        .perform_later(up_to_id: up_to_id)
     end
   end
 end

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

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'active_job'
+
+module WCC::Contentful
+  class WebhookEnableJob < ActiveJob::Base
+    self.queue_adapter = :async
+    queue_as :default
+
+    def perform(args)
+      client = WCC::Contentful::SimpleClient::Management.new(
+        args
+      )
+      enable_webhook(client, args.slice(:app_url, :webhook_username, :webhook_password))
+    end
+
+    def enable_webhook(client, app_url:, webhook_username: nil, webhook_password: nil)
+      expected_url = URI.join(app_url, 'webhook/receive').to_s
+      webhook = client.webhook_definitions.items.find { |w| w['url'] == expected_url }
+      logger.debug "existing webhook: #{webhook.inspect}" if webhook
+      return if webhook
+
+      body = {
+        'name' => 'WCC::Contentful webhook',
+        'url' => expected_url,
+        'topics' => [
+          '*.publish',
+          '*.unpublish'
+        ]
+      }
+      body['httpBasicUsername'] = webhook_username if webhook_username.present?
+      body['httpBasicPassword'] = webhook_password if webhook_password.present?
+
+      begin
+        resp = client.post_webhook_definition(body)
+        logger.info "Created webhook: #{resp.raw.dig('sys', 'id')}"
+      rescue WCC::Contentful::SimpleClient::ApiError => e
+        logger.error "#{e.response.code}: #{e.response.raw}" if e.response
+        raise
+      end
+    end
+  end
+end

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "wcc/contentful"
+require 'bundler/setup'
+require 'wcc/contentful'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "wcc/contentful"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/bin/rails

@@ -1,4 +1,6 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
+
 # This command will automatically be run when you run "rails" with Rails gems
 # installed from the root of your application.
 

data/config/initializers/mime_types.rb

@@ -1,3 +1,12 @@
 # frozen_string_literal: true
 
-Mime::Type.register 'application/vnd.contentful.management.v1+json', :json
+# https://www.contentful.com/developers/docs/references/content-management-api/
+Mime::Type.register 'application/vnd.contentful.management.v1+json', :json_mgmt
+# https://www.contentful.com/developers/docs/references/content-delivery-api/
+Mime::Type.register 'application/vnd.contentful.delivery.v1+json',   :json_cda
+
+Mime::Type.register 'application/json', :json, [
+  'application/vnd.contentful.management.v1+json',
+  'application/vnd.contentful.delivery.v1+json',
+  'application/json'
+]