consyncful 0.3.2 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abe63339fd87ddbe4b2456fd22a333580d6865c5981b4b9c9a3660d11943a8e3
-  data.tar.gz: be20c90cef3dc401fb3ab55eaec17c68d8484cf475aace68d50aec7bb626092e
+  metadata.gz: 6a8f36ac50a10800cbce6e6b9d086e346b1e7362e422080d532a87bb981d8135
+  data.tar.gz: 6df1ea6cf1cb05f405938d83e09436927e21b7828424f33c79a105e4c11da127
 SHA512:
-  metadata.gz: c7f91c8cf381d8eb5be0990261d9344fe870648b5f0879290ae8defbfdbc79a51d61b0db227c21de4d8be2d734e655070882dfe2e44acf9983c099b0366e4654
-  data.tar.gz: e3000098bc7effd1432ebfabffc511e764bdf7e3e562544c50d66e390e3936a486c297b4c3fb88cf062f7512608ebfbc631a52623b0a1371f869e63d615a70f2
+  metadata.gz: bdebe27350c747d4d3d02e290c5971d2b295815741e887ad658a09248f0d7d0a798a4060d5500c99d2f18e4b7f920d98e32bc0f0d49bbdea488ded106bda53d7
+  data.tar.gz: 034ec0cbec2265225f48bbd52d6412fe238ee026b78827bfacec54e8a31c42f9786495709c7dcea1e4ecf261761897f99a8417e4bea09149296c6cc51c9f789b

data/.rubocop_todo.yml

@@ -1,22 +1,29 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2020-01-24 14:47:44 +1300 using RuboCop version 0.79.0.
+# on 2021-03-01 10:54:42 +1300 using RuboCop version 0.79.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
+# Offense count: 1
+# Cop supports --auto-correct.
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/consyncful/item_mapper.rb'
+
 # Offense count: 1
 Metrics/AbcSize:
   Max: 19
 
-# Offense count: 7
+# Offense count: 10
 # Configuration parameters: CountComments, ExcludedMethods.
 # ExcludedMethods: refine
 Metrics/BlockLength:
-  Max: 153
+  Max: 175
 
-# Offense count: 4
+# Offense count: 3
 # Cop supports --auto-correct.
 # Configuration parameters: AutoCorrect, EnforcedStyle.
 # SupportedStyles: nested, compact
@@ -24,21 +31,16 @@ Style/ClassAndModuleChildren:
   Exclude:
     - 'lib/consyncful/railtie.rb'
     - 'spec/consyncful/base_spec.rb'
-    - 'spec/consyncful/sync_spec.rb'
 
-# Offense count: 7
+# Offense count: 3
 Style/Documentation:
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
     - 'lib/consyncful.rb'
-    - 'lib/consyncful/base.rb'
-    - 'lib/consyncful/item_mapper.rb'
     - 'lib/consyncful/railtie.rb'
-    - 'lib/consyncful/stats.rb'
-    - 'lib/consyncful/sync.rb'
 
-# Offense count: 42
+# Offense count: 56
 # Cop supports --auto-correct.
 # Configuration parameters: AutoCorrect, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, IgnoredPatterns.
 # URISchemes: http, https

data/.ruby-version

@@ -1 +1 @@
-2.5.5
+2.7.1

data/.travis.yml

@@ -5,10 +5,10 @@ cache: bundler
 rvm:
   - 2.5.1
   - 2.6.5
-before_install: gem install bundler -v 2.1.0
+before_install: gem install bundler -v 2.1.4
 services:
   - mongodb
 
-script: 
+script:
   - bundle exec rake spec
   - bundle exec rubocop -P

data/Gemfile.lock

@@ -1,64 +1,67 @@
 PATH
   remote: .
   specs:
-    consyncful (0.3.2)
+    consyncful (0.6.1)
       contentful (>= 2.11.1, < 3.0.0)
+      hooks (>= 0.4.1)
       mongoid (>= 7.0.2, < 8.0.0)
       rainbow
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (6.0.2.1)
-      activesupport (= 6.0.2.1)
-    activesupport (6.0.2.1)
+    activemodel (6.1.3.1)
+      activesupport (= 6.1.3.1)
+    activesupport (6.1.3.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+      zeitwerk (~> 2.3)
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.0)
-    bson (4.7.1)
-    concurrent-ruby (1.1.6)
-    contentful (2.15.2)
+    bson (4.12.0)
+    concurrent-ruby (1.1.8)
+    contentful (2.16.0)
       http (> 0.8, < 5.0)
       multi_json (~> 1)
     database_cleaner (1.8.3)
     diff-lcs (1.3)
     domain_name (0.5.20190701)
       unf (>= 0.0.5, < 1.0.0)
-    ffi (1.12.2)
+    ffi (1.15.0)
     ffi-compiler (1.0.1)
       ffi (>= 1.0.0)
       rake
-    http (4.3.0)
+    hooks (0.4.1)
+      uber (~> 0.0.14)
+    http (4.4.1)
       addressable (~> 2.3)
       http-cookie (~> 1.0)
       http-form_data (~> 2.2)
       http-parser (~> 1.2.0)
     http-cookie (1.0.3)
       domain_name (~> 0.5)
-    http-form_data (2.2.0)
-    http-parser (1.2.1)
+    http-form_data (2.3.0)
+    http-parser (1.2.3)
       ffi-compiler (>= 1.0, < 2.0)
-    i18n (1.8.2)
+    i18n (1.8.10)
       concurrent-ruby (~> 1.0)
     jaro_winkler (1.5.4)
-    minitest (5.14.0)
-    mongo (2.11.3)
-      bson (>= 4.4.2, < 5.0.0)
-    mongoid (7.0.5)
-      activemodel (>= 5.1, < 6.1)
-      mongo (>= 2.5.1, < 3.0.0)
-    multi_json (1.14.1)
+    minitest (5.14.4)
+    mongo (2.14.0)
+      bson (>= 4.8.2, < 5.0.0)
+    mongoid (7.2.2)
+      activemodel (>= 5.1, < 6.2)
+      mongo (>= 2.10.5, < 3.0.0)
+    multi_json (1.15.0)
     parallel (1.19.1)
     parser (2.7.0.2)
       ast (~> 2.4.0)
-    public_suffix (4.0.3)
+    public_suffix (4.0.6)
     rainbow (3.0.0)
-    rake (10.5.0)
+    rake (13.0.1)
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -80,14 +83,14 @@ GEM
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 1.4.0, < 1.7)
     ruby-progressbar (1.10.1)
-    thread_safe (0.3.6)
-    tzinfo (1.2.6)
-      thread_safe (~> 0.1)
+    tzinfo (2.0.4)
+      concurrent-ruby (~> 1.0)
+    uber (0.0.15)
     unf (0.1.4)
       unf_ext
-    unf_ext (0.0.7.6)
+    unf_ext (0.0.7.7)
     unicode-display_width (1.6.1)
-    zeitwerk (2.2.2)
+    zeitwerk (2.4.2)
 
 PLATFORMS
   ruby
@@ -96,9 +99,9 @@ DEPENDENCIES
   bundler (~> 2)
   consyncful!
   database_cleaner
-  rake (~> 10.0)
+  rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (= 0.79.0)
 
 BUNDLED WITH
-   2.1.0
+   2.1.4

data/README.md

@@ -2,19 +2,27 @@
 
 Contentful -> local database synchronisation for Rails
 
-Requesting complicated models from the Contentful Delivery API in Rails applications is often
-too slow, and makes testing applications painful. Consyncful uses Contentful's syncronisation API 
-to keep a local copy of the entire content in a Mongo database up to date.
-
-Once the content is availble locally, finding and interact with contentful data is as easy as 
-using [Mongoid](https://docs.mongodb.com/mongoid/current/tutorials/mongoid-documents/) ODM. 
-
-This gem doesn't provide any intergration with the management api or any way to update contentful models from the local store. It is strictly read only.
-
-## Why do I have to use MongoDB?
-
-Consyncful currently only supports Mongoid ODM because models have dynamic schemas. And that's all we've had a chance to work out so far. :) 
-The same pattern might be able to be extended to work with ActiveRecord, but having to migrate the local database as well as your contentful content type's seems tedious.
+Requesting complicated models from the Contentful Delivery API in Rails applications is often too slow, and makes testing applications painful. Consyncful uses Contentful's synchronisation API to keep a local, up-to-date copy of the entire content in a Mongo database.
+
+Once the content is available locally, finding and interact with contentful data is as easy as using [Mongoid](https://docs.mongodb.com/mongoid/current/tutorials/mongoid-documents/) ODM.
+
+This gem doesn't provide any integration with the management API, or any way to update Contentful models from the local store. It is strictly read only.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Creating contentful models in your Rails app](#creating-contentful-models-in-your-rails-app)
+  - [Synchronizing contentful data](#synchronizing-contentful-data)
+  - [Finding and interacting with models](#finding-and-interacting-with-models)
+    - [Querying](#querying)
+    - [References](#references)
+    - [Finding entries from different content types](#finding-entries-from-different-content-types)
+  - [Sync callbacks](#sync-callbacks)
+  - [Using Locales for specific fields](#using-locales-for-specific-fields)
+  - [Configuring what Mongo database Consyncful uses](#configuring-what-mongo-database-consyncful-uses)
+  - [Why do I have to use MongoDB?](#why-do-i-have-to-use-mongodb)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
 
 ## Installation
 
@@ -28,28 +36,29 @@ And then execute:
 
     $ bundle
 
-If you don't already use mongoid, generate a mongoid.yml by running:
+If you don't already use Mongoid, generate a mongoid.yml by running:
 
     $ rake g mongoid:config
 
 Add an initializer:
-Consyncful uses [contentful.rb](https://github.com/contentful/contentful.rb) so client options are as documented there.
-```ruby
-  Consyncful.configure do |config|
-    config.locale = 'en-NZ'
-    config.contentful_client_options = {
-      api_url: 'cdn.contentful.com',
-      space: 'space_id',
-      access_token: 'ACCESS TOKEN',
-      environment: 'master',        # optional
-      logger: Logger.new(STDOUT)    # optional for debugging
-    }
-  end
+
+Consyncful uses [contentful.rb](https://github.com/contentful/contentful.rb); client options are as documented there.
+```rb
+Consyncful.configure do |config|
+  config.locale = 'en-NZ'
+  config.contentful_client_options = {
+    api_url: 'cdn.contentful.com',
+    space: 'space_id',
+    access_token: 'ACCESS TOKEN',
+    environment: 'master',        # optional
+    logger: Logger.new(STDOUT)    # optional for debugging
+  }
+end
 ```
 
 ## Usage
 
-### Creating contentful models in your rails app
+### Creating contentful models in your Rails app
 
 Create models by inheriting from `Consyncful::Base`
 
@@ -59,9 +68,9 @@ class ModelName < Consyncful::Base
 end
 ```
 
-Model fields will be dynamicly assigned, but mongoid dynamic fields are not accessible if the entry has an empty field. If you want the accessor methods to be reliably available for fields it is recommended to define the fields in the model:
+Model fields will be dynamically assigned, but Mongoid dynamic fields are not accessible if the entry has an empty field. If you want the accessor methods to be reliably available for fields it is recommended to define the fields in the model:
 
-```ruby 
+```ruby
 class ModelName < Consyncful::Base
   contentful_model_name 'contentfulTypeName'
 
@@ -70,9 +79,9 @@ class ModelName < Consyncful::Base
 end
 ```
 
-Contentful reference fields are a bit special compared with standard mongoid associations, Consyncful provides the following helpers to set up the correct relationships:
+Contentful reference fields are a bit special compared with standard Mongoid associations. Consyncful provides the following helpers to set up the correct relationships:
 
-```ruby 
+```ruby
 class ModelWithReferences < Consyncful::Base
   contentful_model_name 'contentfulTypeName'
 
@@ -81,26 +90,26 @@ class ModelWithReferences < Consyncful::Base
 end
 ```
 
-### Syncronizing contentful data
+### Synchronizing contentful data
 
-To run a syncronization process run:
+To run a synchronization process run:
 
     $ rake consyncful:sync
 
-The first time you run this it will download all the contentful content, it will then check every 15 seconds for changes to the content and update/delete records in the database when changes are made in contentful.
+The first time you run this it will download all the Contentful content. It will then check every 15 seconds for changes to the content and update/delete records in the database when changes are made in Contentful.
 
-If you want to syncronise from scratch run:
+If you want to synchronise from scratch, run:
 
     $ rake consyncful:refresh
 
 It is recommended to refresh your data if you change model names.
 
-Now you've synced your data, it is all available via your rails models
+Now you've synced your data, it is all available via your Rails models.
 
 ### Finding and interacting with models
 
 #### Querying
-Models are available using standard mongoid [queries](https://docs.mongodb.com/mongoid/current/tutorials/mongoid-queries/).
+Models are available using standard Mongoid [queries](https://docs.mongodb.com/mongoid/current/tutorials/mongoid-queries/).
 
 ```ruby
 instance = ModelName.find_by(instance: 'foo')
@@ -109,7 +118,7 @@ instance.is_awesome # true
 ```
 
 #### References
-References work like you woule expect:
+References work like you would expect:
 
 ```ruby
 
@@ -120,25 +129,56 @@ instance.other_things # all the referenced things, polymorphic, so might be diff
 ```
 
 **Except**:
-`references_many` associations return objects in a different order from how they are ordered in contentful. If you want them in the order they appare in contentful, use the `.in_order` helper:
+`references_many` associations return objects in a different order from how they are ordered in Contentful. If you want them in the order they appear in Contentful, use the `.in_order` helper:
+
+```ruby
+instance.other_things.in_order # ordered the same as in Contentful
+```
+
+#### Finding entries from different content types
+
+Because all Contentful models are stored as polymorphic subtypes of `Consyncful::Base`, you can query all entries without knowing what type you are looking for:
 
 ```ruby
-instance.other_things.in_order # ordered the same as in contentful
+Consyncful::Base.where(title: 'a title') # [ #<ModelName>, #<OtherModelName> ]
 ```
 
-#### Finding entrys from different content types
+### Sync callbacks
+
+You may want to attach some application logic to happen before or after a sync run, for example to update caches.
 
-Because all contentful models are stored as polymorphic subtypes of Consyncful::Base, you can query all entries without knowing what type you are looking for:
+Callbacks can be registered using:
 
 ```ruby
-  Consyncful::Base.where(title: 'a title') # [ #<ModelName>, #<OtherModelName> ]
+Consyncful::Sync.before_run do
+  # do something before the run
+end
+```
+
+```ruby
+Consyncful::Sync.after_run do |updated_ids|
+  # invalidate cache for updated_ids, or something
+end
 ```
 
-## Limitations
+### Using Locales for specific fields
+
+If fields have multiple locales then the default locale will be mapped to the field name. Additional locales will have a suffix (lower snake case) on the field name. e.g title (default), title_mi_nz (New Zealand Maori mi-NZ)
+
+### Configuring what Mongo database Consyncful uses
+
+You can also configure what Mongoid client Consyncful uses and the name of the collection the entries are stored under. This is useful if you want to have your consyncful data hosted in a different mongo database than your application-specific mongo database.
+
+```rb
+Consyncful.configure do |config|
+  config.mongo_client = :consyncful # defaults to :default (referencing the clients in mongoid.yml)
+  config.mongo_collection = 'contentful_models' # this is the default
+end
+```
 
-### Locales
+### Why do I have to use MongoDB?
 
-Current Consyncful only uses one globally configured locale to map the data to the database.
+Consyncful currently only supports Mongoid ODM because models have dynamic schemas. And that's all we've had a chance to work out so far. The same pattern might be able to be extended to work with ActiveRecord, but having to migrate the local database as well as your contentful content type's seems tedious.
 
 ## Development
 

data/consyncful.gemspec

@@ -7,8 +7,8 @@ require 'consyncful/version'
 Gem::Specification.new do |spec|
   spec.name          = 'consyncful'
   spec.version       = Consyncful::VERSION
-  spec.authors       = ['Andy Anastasiadis-Gray', 'Montgomery Anderson']
-  spec.email         = ['andy@boost.co.nz', 'montgomery@boost.co.nz']
+  spec.authors       = ['Andy Anastasiadis-Gray', 'Montgomery Anderson', 'Greg Rogan']
+  spec.email         = ['andy@boost.co.nz', 'montgomery@boost.co.nz', 'greg@boost.co.nz']
 
   spec.summary       = 'Contentful to local database synchronisation for Rails'
   spec.homepage      = 'https://github.com/boost/consyncful'
@@ -32,11 +32,12 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler', '~> 2'
   spec.add_development_dependency 'database_cleaner'
-  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
   spec.add_development_dependency 'rubocop', '0.79.0'
 
   spec.add_dependency 'contentful', ['>=2.11.1', '<3.0.0']
+  spec.add_dependency 'hooks', '>=0.4.1'
   spec.add_dependency 'mongoid', ['>=7.0.2', '<8.0.0']
   spec.add_dependency 'rainbow'
 end

data/lib/consyncful.rb

@@ -11,23 +11,18 @@ require 'consyncful/sync'
 require 'consyncful/railtie' if defined?(Rails)
 
 module Consyncful
-  class << self
-    attr_accessor :configuration
-  end
-
-  def self.configure
-    self.configuration ||= Configuration.new
-    yield(configuration)
-  end
-
+  # Handles Rails configurations for Consynful
   class Configuration
-    attr_accessor :contentful_client_options, :locale
+    attr_accessor :contentful_client_options, :locale,
+                  :mongo_client, :mongo_collection
 
     def initialize
       @contentful_client_options = {
         api_url: 'cdn.contentful.com'
       }
-      @locale = 'en-US'
+      @locale = 'en-NZ'
+      @mongo_client = :default
+      @mongo_collection = 'contentful_models'
     end
   end
 
@@ -36,11 +31,21 @@ module Consyncful
     api_url: 'cdn.contentful.com'
   }.freeze
 
-  def self.client
-    @client ||= begin
-      options = Consyncful.configuration.contentful_client_options
-      options.reverse_merge!(DEFAULT_CLIENT_OPTIONS)
-      Contentful::Client.new(options)
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+    end
+
+    def client
+      @client ||= begin
+        options = Consyncful.configuration.contentful_client_options
+        options.reverse_merge!(DEFAULT_CLIENT_OPTIONS)
+        Contentful::Client.new(options)
+      end
     end
   end
 end

data/lib/consyncful/base.rb

@@ -1,14 +1,18 @@
 # frozen_string_literal: true
 
 module Consyncful
+  ##
+  # Provides common functionality of Mongoid models created from contentful
+  # entries
   class Base
     include Mongoid::Document
     include Mongoid::Attributes::Dynamic
 
-    store_in collection: 'contentful_models'
-
     cattr_accessor :model_map
 
+    store_in collection: -> { Consyncful.configuration.mongo_collection },
+             client: -> { Consyncful.configuration.mongo_client }
+
     def self.contentful_model_name(name)
       self.model_map ||= {}
 
@@ -19,7 +23,9 @@ module Consyncful
     def self.references_many(name)
       has_and_belongs_to_many name.to_sym, class_name: 'Consyncful::Base', inverse_of: nil do
         def in_order
-          _target.to_a.sort_by { |a| _base[foreign_key].index(a.id) }
+          _target.to_a.sort_by do |reference|
+            _base[foreign_key].index(reference.id)
+          end
         end
       end
     end

data/lib/consyncful/item_mapper.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
 module Consyncful
+  ##
+  # Responsible for mapping an update received from Contentful's syncronisation API
+  # into useful fields for Consyncful::PersistedItem to store in the database.
   class ItemMapper
     def initialize(item)
       @item = item
@@ -11,10 +14,9 @@ module Consyncful
     end
 
     def type
-      if @item.type == 'Entry'
-        @item.content_type.id
-      elsif @item.type == 'Asset'
-        'asset'
+      case @item.type
+      when 'Entry' then @item.content_type.id
+      when 'Asset' then 'asset'
       end
     end
 
@@ -22,17 +24,11 @@ module Consyncful
       @item.id
     end
 
-    def mapped_fields(locale)
+    def mapped_fields(default_locale)
       fields = generic_fields
 
-      @item.fields_with_locales.each do |field, value_with_locales|
-        value = value_with_locales[locale.to_sym]
-        next if value.is_a? Contentful::File # it is special
-
-        assign_field(fields, field, value)
-      end
-
-      fields[:file] = raw_file(locale) if type == 'asset'
+      fields.merge!(localized_fields(default_locale))
+      fields.merge!(localized_asset_fields(default_locale)) if type == 'asset'
 
       fields
     end
@@ -40,18 +36,46 @@ module Consyncful
     private
 
     def generic_fields
+      { created_at: @item.created_at,
+        updated_at: @item.updated_at,
+        revision: @item.revision,
+        contentful_type: type,
+        synced_at: Time.current }
+    end
+
+    def localized_fields(default_locale)
       fields = {}
-      fields[:created_at] = @item.created_at
-      fields[:updated_at] = @item.updated_at
-      fields[:revision] = @item.revision
-      fields[:contentful_type] = type
-      fields[:synced_at] = Time.current
+
+      @item.fields_with_locales.each do |field, value_with_locales|
+        value_with_locales.each do |locale_code, value|
+          next if value.is_a? Contentful::File # assets are handeled below
+
+          field_name = localized_field_name(field, locale_code, default_locale)
+          field_name, value = mapped_field_entry_for(field_name, value)
+          fields[field_name] = value
+        end
+      end
+
       fields
     end
 
-    def raw_file(locale)
-      file_json = @item.raw.fetch('fields', {}).fetch('file', nil)
-      file_json[locale] unless file_json.nil?
+    def localized_asset_fields(default_locale)
+      fields = {}
+      files_by_locale = @item.raw.dig('fields', 'file') || {}
+
+      files_by_locale.each do |locale_code, details|
+        field_name = localized_field_name('file', locale_code, default_locale)
+        fields[field_name.to_sym] = details
+      end
+
+      fields
+    end
+
+    # Suffixes the field with the locale unless it's the default locale.
+    def localized_field_name(field, locale_code, default_locale)
+      return field if locale_code.to_s == default_locale.to_s
+
+      "#{field}_#{locale_code.to_s.underscore}".to_sym
     end
 
     def reference_value?(value)
@@ -66,14 +90,14 @@ module Consyncful
       value.is_a?(Array) && single_reference?(value.first)
     end
 
-    def assign_field(hash, field, value)
+    def mapped_field_entry_for(field, value)
       if single_reference?(value)
-        hash[ActiveSupport::Inflector.foreign_key(field).to_sym] = value.id
+        [ActiveSupport::Inflector.foreign_key(field).to_sym, value.id]
       elsif many_reference?(value)
         ids_field_name = field.to_s.singularize + '_ids' # fk field name
-        hash[ids_field_name.to_sym] = value.map(&:id)
+        [ids_field_name.to_sym, value.map(&:id)]
       else
-        hash[field] = value
+        [field, value]
       end
     end
   end

data/lib/consyncful/persisted_item.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Consyncful
+  ##
+  # Takes a mapped item from Contentful and creates/updates/deletes
+  # the relevant model in the local database.
+  class PersistedItem
+    DEFAULT_LOCALE = 'en-NZ'
+
+    def initialize(item, sync_id, stats)
+      @item = item
+      @sync_id = sync_id
+      @stats = stats
+    end
+
+    def persist
+      puts Rainbow("syncing: #{@item.id}").yellow
+      if @item.deletion?
+        delete_model(@item.id, @stats)
+      else
+        create_or_update_model(@item, @sync_id, @stats)
+      end
+    end
+
+    private
+
+    def delete_model(id, stats)
+      Base.find_by(id: id).destroy
+      stats.record_deleted
+    rescue Mongoid::Errors::DocumentNotFound
+      puts Rainbow("Deleted record not found: #{id}").yellow
+      nil
+    end
+
+    def create_or_update_model(item, sync_id, stats)
+      return if item.type.nil?
+
+      instance = find_or_initialize_item(item)
+      update_stats(instance, stats)
+
+      reset_fields(instance)
+
+      item.mapped_fields(DEFAULT_LOCALE).each do |field, value|
+        instance[field] = value
+      end
+
+      instance[:sync_id] = sync_id
+
+      instance.save
+    end
+
+    def find_or_initialize_item(item)
+      model_class(item.type).find_or_initialize_by(id: item.id)
+    end
+
+    def update_stats(instance, stats)
+      if instance.persisted?
+        stats.record_updated
+      else
+        stats.record_added
+      end
+    end
+
+    def model_class(type)
+      Base.model_map[type] || Base
+    end
+
+    def reset_fields(instance)
+      instance.attributes.each do |field_name, _value|
+        next if field_name.in? %w[_id _type]
+
+        instance[field_name] = nil
+      end
+    end
+  end
+end

data/lib/consyncful/railtie.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Adds Consyncful task to Rails
 class Consyncful::Railtie < Rails::Railtie
   rake_tasks do
     load 'consyncful/tasks/consyncful.rake'

data/lib/consyncful/stats.rb

@@ -3,6 +3,8 @@
 require 'rainbow'
 
 module Consyncful
+  ##
+  # Responsible for recording changes during a sync for outputting in logs
   class Stats
     def initialize
       @stats = {

data/lib/consyncful/sync.rb

@@ -2,13 +2,27 @@
 
 require 'rainbow'
 require 'consyncful/item_mapper'
+require 'consyncful/persisted_item'
 require 'consyncful/stats'
+require 'hooks'
 
 module Consyncful
+  ##
+  # A mongoid model that stores the state of a syncronisation feed. Stores the
+  # next URL provided by Contentfuls Sync API.
+  #
+  # Sync's are affectivly singletons,
+  # there should only ever be one in the database
+  #
+  # Is also the entrypoint of a Syncronization run
   class Sync
     include Mongoid::Document
+    include Hooks
 
-    DEFAULT_LOCALE = 'en-NZ'
+    store_in client: -> { Consyncful.configuration.mongo_client }
+
+    define_hook :before_run
+    define_hook :after_run
 
     field :next_url
     field :last_run_at, type: DateTime
@@ -17,31 +31,41 @@ module Consyncful
       last || new
     end
 
+    ##
+    # Delete the previous sync chains from database and create a fresh one.
+    # Used to completely resync all items from Contentful.
     def self.fresh
       destroy_all
       latest
     end
 
+    ##
+    # Makes sure that the database contains only records that have been provided
+    # during this chain of syncronisation.
     def drop_stale
       stale = Base.where(:sync_id.ne => id, :sync_id.exists => true)
       puts Rainbow("Dropping #{stale.count} records that haven't been touched in this sync").red
       stale.destroy
     end
 
+    ##
+    # Entry point to a syncronization run. Is responsible for updating Sync state
     def run
+      run_hook :before_run
+
       stats = Consyncful::Stats.new
       load_all_models
 
       sync = start_sync
 
-      sync_items(sync, stats)
+      changed_ids = sync_items(sync, stats)
 
       drop_stale
 
-      self.next_url = sync.next_sync_url
-      self.last_run_at = Time.current
-      save
+      update_run(sync.next_sync_url)
       stats.print_stats
+
+      run_hook :after_run, changed_ids
     end
 
     private
@@ -52,6 +76,12 @@ module Consyncful
       Rails.application.eager_load!
     end
 
+    def update_run(next_url)
+      self.next_url = next_url
+      self.last_run_at = Time.current
+      save
+    end
+
     def start_sync
       if next_url.present?
         puts Rainbow("Starting update, last update: #{last_run_at} (#{(Time.current - last_run_at).round(3)}s ago)").blue
@@ -63,69 +93,19 @@ module Consyncful
     end
 
     def sync_items(sync, stats)
+      ids = []
       sync.each_page do |page|
         page.items.each do |item|
-          sync_item(ItemMapper.new(item), stats)
+          ids << sync_item(ItemMapper.new(item), stats)
         end
       end
+      ids
     end
 
     def sync_item(item, stats)
       puts Rainbow("syncing: #{item.id}").yellow
-      if item.deletion?
-        delete_model(item.id, stats)
-      else
-        create_or_update_model(item, stats)
-      end
-    end
-
-    def delete_model(id, stats)
-      Base.find_by(id: id).destroy
-      stats.record_deleted
-    rescue Mongoid::Errors::DocumentNotFound
-      puts Rainbow("Deleted record not found: #{id}").yellow
-      nil
-    end
-
-    def create_or_update_model(item, stats)
-      return if item.type.nil?
-
-      instance = find_or_initialize_item(item)
-      update_stats(instance, stats)
-
-      reset_fields(instance)
-
-      item.mapped_fields(DEFAULT_LOCALE).each do |field, value|
-        instance[field] = value
-      end
-
-      instance[:sync_id] = id
-
-      instance.save
-    end
-
-    def find_or_initialize_item(item)
-      model_class(item.type).find_or_initialize_by(id: item.id)
-    end
-
-    def update_stats(instance, stats)
-      if instance.persisted?
-        stats.record_updated
-      else
-        stats.record_added
-      end
-    end
-
-    def model_class(type)
-      Base.model_map[type] || Base
-    end
-
-    def reset_fields(instance)
-      instance.attributes.each do |field_name, _value|
-        next if field_name.in? %w[_id _type]
-
-        instance[field_name] = nil
-      end
+      PersistedItem.new(item, id, stats).persist
+      item.id
     end
   end
 end

data/lib/consyncful/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Consyncful
-  VERSION = '0.3.2'
+  VERSION = '0.6.1'
 end

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: consyncful
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.6.1
 platform: ruby
 authors:
 - Andy Anastasiadis-Gray
 - Montgomery Anderson
+- Greg Rogan
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-02-26 00:00:00.000000000 Z
+date: 2021-04-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -45,14 +46,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -101,6 +102,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: hooks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.1
 - !ruby/object:Gem::Dependency
   name: mongoid
   requirement: !ruby/object:Gem::Requirement
@@ -139,6 +154,7 @@ description:
 email:
 - andy@boost.co.nz
 - montgomery@boost.co.nz
+- greg@boost.co.nz
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -162,6 +178,7 @@ files:
 - lib/consyncful.rb
 - lib/consyncful/base.rb
 - lib/consyncful/item_mapper.rb
+- lib/consyncful/persisted_item.rb
 - lib/consyncful/railtie.rb
 - lib/consyncful/stats.rb
 - lib/consyncful/sync.rb
@@ -186,8 +203,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6.2
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: Contentful to local database synchronisation for Rails