synchronisable 0.0.2

data/lib/synchronizable/model/methods.rb

@@ -0,0 +1,55 @@
+require 'synchronizable/worker'
+require 'synchronizable/models/import'
+
+module Synchronizable
+  module Model
+    # Methods that will be attached to synchronizable model class.
+    module Methods
+      # Creates a new worker, that initiates synchronization
+      # for this particular model.
+      # If you have implemented `fetch` & `find` methods
+      # in your model synchronizer, than it will be used if no data supplied.
+      #
+      # @overload sync(data, options)
+      #   @param options [Hash] synchronization options
+      #   @option options [Hash] :include assocations to be synchronized.
+      #     Use this option to override `has_one` & `has_many` assocations
+      #     defined in model synchronizer.
+      # @overload sync(options)
+      # @overload sync(data)
+      # @overload sync
+      #
+      # @param data [Array<Hash>] array of hashes with remote attributes.
+      #
+      # @see Synchronizable::Worker
+      #
+      # @example Supplying array of hashes with remote attributes
+      #   FooModel.sync([
+      #     {
+      #       :id => '123',
+      #       :attr1 => 4,
+      #       :attr2 => 'blah'
+      #     },
+      #     ...
+      #   ])
+      #
+      # @example General usage
+      #   FooModel.sync(:include => {
+      #     :assocation_model => :nested_assocaiton_model
+      #   })
+      #
+      # @example Football domain use case
+      #   Match.sync(:include => {
+      #     :match_players => :player
+      #   })
+      def sync(*args)
+        Worker.run(self, *args)
+      end
+
+      # Count of import records for this model.
+      def imports_count
+        Import.where(synchronizable_type: self).count
+      end
+    end
+  end
+end

data/lib/synchronizable/models/import.rb

@@ -0,0 +1,24 @@
+module Synchronizable
+  class Import < ActiveRecord::Base
+    belongs_to :synchronizable, polymorphic: true
+
+    serialize :attrs, Hash
+
+    scope :with_synchronizable_type, ->(type) { where(synchronizable_type: type) }
+    scope :with_synchronizable_ids,  ->(ids)  { where(synchronizable_id: ids) }
+
+    scope :with_remote_id,  ->(id)  { where(remote_id: id.to_s) }
+    scope :with_remote_ids, ->(ids) { where(remote_id: ids.map(&:to_s)) }
+
+    def self.find_by_remote_id(id)
+      with_remote_id(id).first
+    end
+
+    def destroy_with_synchronizable
+      ActiveRecord::Base.transaction do
+        synchronizable.try :destroy
+        destroy
+      end
+    end
+  end
+end

data/lib/synchronizable/source.rb

@@ -0,0 +1,72 @@
+module Synchronizable
+  # Synchronization source.
+  class Source
+    attr_accessor :import_record
+    attr_reader :model, :remote_attrs,
+                :remote_id, :local_attrs, :associations
+
+    def initialize(model, parent, remote_attrs)
+      @model, @parent, @synchronizer = model, parent, model.synchronizer
+      @remote_attrs = remote_attrs.with_indifferent_access
+    end
+
+    # Extracts the `remote_id` from remote attributes, maps remote attirubtes
+    # to local attributes and tries to find import record for given model
+    # by extracted remote id.
+    #
+    # @api private
+    def build
+      @remote_id = @synchronizer.extract_remote_id(@remote_attrs)
+      @local_attrs = @synchronizer.map_attributes(@remote_attrs)
+      @associations = @synchronizer.associations_for(@local_attrs)
+
+      @local_attrs.delete_if do |key, _|
+        @associations.keys.any? { |a| a.key == key }
+      end
+
+      @import_record = Import.find_by(
+        :remote_id => @remote_id,
+        :synchronizable_type => @model
+      )
+
+      set_parent_attribute
+    end
+
+    def updatable?
+      @import_record.present? && local_record.present?
+    end
+
+    def local_record
+      @import_record.try(:synchronizable)
+    end
+
+    def dump_message
+      %Q(
+        remote_id: #{remote_id},
+        remote attributes: #{remote_attrs},
+        local attributes: #{local_attrs}
+      )
+    end
+
+    private
+
+    def set_parent_attribute
+      return unless @parent
+      name = parent_attribute_name
+      @local_attrs[name] = @parent.local_record.id if name
+    end
+
+    def parent_attribute_name
+      return nil unless parent_has_model_as_reflection?
+      parent_name = @parent.model.table_name.singularize
+      "#{parent_name}_id"
+    end
+
+    def parent_has_model_as_reflection?
+      @parent.model.reflections.values.any? do |reflection|
+        reflection.plural_name == @model.table_name &&
+        [:has_one, :has_many].include?(reflection.macro)
+      end
+    end
+  end
+end

data/lib/synchronizable/synchronizer.rb

@@ -0,0 +1,177 @@
+require 'synchronizable/dsl/macro'
+require 'synchronizable/dsl/associations'
+require 'synchronizable/exceptions'
+
+module Synchronizable
+  # @abstract Subclass to create your model specific synchronizer class to
+  #   setup synchronization attributes and behavior.
+  #
+  # @see Synchronizable::DSL::Macro
+  # @see Synchronizable::SynchronizerDefault
+  class Synchronizer
+    include Synchronizable::DSL::Macro
+    include Synchronizable::DSL::Associations
+
+    SYMBOL_ARRAY_CONVERTER = ->(source) { (source || []).map(&:to_s) }
+
+    # The name of remote `id` attribute.
+    attribute :remote_id, default: :id
+
+    # Mapping configuration between local model attributes and
+    # its remote counterpart (including id attribute).
+    attribute :mappings, converter: ->(source) {
+      source.try(:with_indifferent_access)
+    }
+
+    # Attributes that will be ignored.
+    attribute :except, converter: SYMBOL_ARRAY_CONVERTER
+
+    # The only attributes that will be used.
+    attribute :only, converter: SYMBOL_ARRAY_CONVERTER
+
+    # If set to `true` than all local records that
+    # don't have corresponding remote counterpart will be destroyed.
+    attribute :destroy_missed, default: false
+
+    # Logger that will be used during synchronization
+    # of this particular model.
+    # Fallbacks to `Rails.logger` if available, otherwise
+    # `STDOUT` will be used for output.
+    attribute :logger, default: -> {
+      defined?(Rails) ? Rails.logger : Logger.new(STDOUT)
+    }
+
+    # Lambda that returns array of hashes with remote attributes.
+    method :fetch, default: -> { [] }
+
+    # Lambda that returns a hash with remote attributes by id.
+    #
+    # @example Common use case
+    #   class FooSynchronizer < Synchronizable::Synchronizer
+    #     find do |id|
+    #       remote_source.find { |h| h[:foo_id] == id } }
+    #     end
+    #   end
+    method :find
+
+    # Lambda, that will be called before synchronization
+    # of each record and its assocations.
+    #
+    # @param source [Synchronizable::Source] synchronization source
+    #
+    # @return [Boolean] `true` to continue sync, `false` to cancel
+    method :before_sync
+    # Lambda, that will be called every time
+    # after record and its associations is synchronized.
+    #
+    # @param source [Synchronizable::Source] synchronization source
+    method :after_sync
+
+    # Lambda, that will be called before synchronization of each record.
+    #
+    # @param source [Synchronizable::Source] synchronization source
+    #
+    # @return [Boolean] `true` to continue sync, `false` to cancel
+    method :before_record_sync
+
+    # Lambda, that will be called every time after record is synchronized.
+    #
+    # @param source [Synchronizable::Source] synchronization source
+    method :after_record_sync
+
+    # Lambda, that will be called before each association sync.
+    #
+    # @param source [Synchronizable::Source] synchronization source
+    # @param id association remote id
+    # @param association [Synchronizable::DSL::Associations::Association]
+    #   association builder
+    #
+    # @return [Boolean] `true` to continue sync, `false` to cancel
+    method :before_association_sync
+
+    # Lambda, that will be called every time after association if synchronized.
+    #
+    # @param source [Synchronizable::Source] synchronization source
+    # @param id association remote id
+    # @param association [Synchronizable::DSL::Associations::Association]
+    #   association builder
+    method :after_association_sync
+
+    class << self
+      # Extracts remote id from given attribute hash.
+      #
+      # @param attrs [Hash] remote attributes
+      # @return remote id value
+      #
+      # @raise [MissedRemoteIdError] raised when data doesn't contain remote id
+      # @see #ensure_remote_id
+      #
+      # @api private
+      def extract_remote_id(attrs)
+        id = attrs.delete(remote_id)
+        ensure_remote_id(id)
+        id
+      end
+
+      # Maps the remote attributes to local model attributes.
+      #
+      # @param attrs [Hash] remote attributes
+      # @return [Hash] local mapped attributes
+      #
+      # @api private
+      def map_attributes(attrs)
+        result = attrs.dup
+        apply_mappings(result) if mappings.present?
+        apply_only_filter(result) if only.present?
+        apply_except_filter(result) if except.present?
+        result
+      end
+
+      %w(sync record_sync association_sync).each do |method|
+        define_method(:"with_#{method}_callbacks") do |*args, &block|
+          run_callbacks(method, args, block)
+        end
+      end
+
+      private
+
+      def apply_mappings(attrs)
+        attrs.transform_keys! { |key| mappings[key] || key }
+      end
+
+      def apply_only_filter(attrs)
+        attrs.keep_if do |key|
+          only.include?(key) ||
+          associations.keys.include?(key)
+        end
+      end
+
+      def apply_except_filter(attrs)
+        attrs.delete_if { |key| key.nil? || except.include?(key) }
+      end
+
+      def run_callbacks(method, args, block)
+        before = send(:"before_#{method}")
+        after  = send(:"after_#{method}")
+
+        return unless before.(*args) if before
+        block.()
+        after.(*args) if after
+      end
+
+      # Throws the {Synchronizable::MissedRemoteIdError} if given id isn't present.
+      #
+      # @param id id to check
+      #
+      # @raise [MissedRemoteIdError] raised when data doesn't contain remote id
+      def ensure_remote_id(id)
+        if id.blank?
+          raise MissedRemoteIdError, I18n.t(
+            'errors.missed_remote_id',
+            remote_id: remote_id
+          )
+        end
+      end
+    end
+  end
+end

data/lib/synchronizable/synchronizers/synchronizer_default.rb

@@ -0,0 +1,10 @@
+require 'synchronizable/synchronizer'
+
+module Synchronizable
+  # Default synchronizer to be used when
+  # model specific synchronizer is not defined.
+  #
+  # @api private
+  class SynchronizerDefault < Synchronizer
+  end
+end

data/lib/synchronizable/version.rb

@@ -0,0 +1,10 @@
+module Synchronizable
+  module VERSION
+    MAJOR = 0
+    MINOR = 0
+    PATCH = 2
+    SUFFIX = nil
+
+    STRING = [MAJOR, MINOR, PATCH, SUFFIX].compact.join('.')
+  end
+end

data/lib/synchronizable/worker.rb

@@ -0,0 +1,191 @@
+require 'synchronizable/error_handler'
+require 'synchronizable/context'
+require 'synchronizable/source'
+require 'synchronizable/models/import'
+
+module Synchronizable
+  # Responsible for model synchronization.
+  #
+  # @api private
+  class Worker
+    class << self
+      # Creates a new instance of worker and initiates model synchronization.
+      #
+      # @overload run(model, data, options)
+      #   @param model [Class] model class to be synchronized
+      #   @param options [Hash] synchronization options
+      #   @option options [Hash] :include assocations to be synchronized.
+      #     Use this option to override `has_one` & `has_many` assocations
+      #     defined in model synchronizer.
+      # @overload run(model, data)
+      # @overload run(model)
+      #
+      # @return [Synchronizable::Context] synchronization context
+      def run(model, *args)
+        options = args.extract_options!
+        data = args.first
+
+        new(model, options).run(data)
+      end
+    end
+
+    # Initiates model synchronization.
+    #
+    # @param data [Array<Hash>] array of hashes with remote attriutes.
+    #   If not specified worker will try to get the data
+    #   using `fetch` lambda/proc defined in corresponding synchronizer
+    #
+    # @return [Synchronizable::Context] synchronization context
+    def run(data)
+      sync do |context|
+        error_handler = ErrorHandler.new(@logger, context)
+        context.before = @model.imports_count
+
+        data = @synchronizer.fetch.() if data.blank?
+        data.each do |attrs|
+          # TODO: Handle case when only array of ids is given
+          # What to do with associations?
+
+          source = Source.new(@model, @parent, attrs)
+          error_handler.handle(source) do
+            @synchronizer.with_sync_callbacks(source) do
+              sync_record(source)
+              sync_associations(source)
+              set_record_foreign_keys(source)
+            end
+          end
+        end
+
+        context.after = @model.imports_count
+        context.deleted = 0
+      end
+    end
+
+    private
+
+    def initialize(model, options)
+      @model, @synchronizer = model, model.synchronizer
+      @logger = @synchronizer.logger
+      @parent = options[:parent]
+    end
+
+    def sync
+      @logger.progname = "#{@model} synchronization"
+      @logger.info 'starting'
+
+      context = Context.new(@model, @parent.try(:model))
+      yield context
+
+      @logger.info 'done'
+      @logger.info(context.summary_message)
+      @logger.progname = nil
+
+      context
+    end
+
+    # TODO: Think about how to move it from here to Source or some other place
+
+    # Method called by {#run} for each remote model attribute hash
+    #
+    # @param source [Synchronizable::Source] synchronization source
+    #
+    # @return [Boolean] `true` if synchronization was completed
+    #   without errors, `false` otherwise
+    def sync_record(source)
+      @synchronizer.with_record_sync_callbacks(source) do
+        source.build
+
+        @logger.info(source.dump_message) if verbose_logging?
+
+        if source.updatable?
+          update_record(source)
+        else
+          create_record_pair(source)
+        end
+      end
+    end
+
+    def update_record(source)
+      if verbose_logging?
+        @logger.info "updating #{@model}: #{source.local_record.id}"
+      end
+
+      # TODO: Напрашивается, да?
+      source.local_record.update_attributes!(source.local_attrs)
+    end
+
+    def create_record_pair(source)
+      local_record = @model.create!(source.local_attrs)
+      import_record = Import.create!(
+        :synchronizable_id    => local_record.id,
+        :synchronizable_type  => @model.to_s,
+        :remote_id            => source.remote_id,
+        :attrs                => source.local_attrs
+      )
+
+      source.import_record = import_record
+
+      if verbose_logging?
+        @logger.info "#{@model}: #{local_record.id} was created"
+        @logger.info "#{import_record.class}: #{import_record.id} was created"
+      end
+    end
+
+    def set_record_foreign_keys(source)
+      reflection = belongs_to_parent_reflection
+      return unless reflection
+
+      belongs_to_key = "#{reflection.plural_name.singularize}_id"
+      source.local_record.update_attributes!(
+        belongs_to_key => @parent.local_record.id
+      )
+    end
+
+    # Synchronizes associations.
+    #
+    # @param source [Synchronizable::Source] synchronization source
+    #
+    # @see Synchronizable::DSL::Associations
+    # @see Synchronizable::DSL::Associations::Association
+    def sync_associations(source)
+      if verbose_logging? && source.associations.present?
+        @logger.info "starting associations sync"
+      end
+
+      source.associations.each do |association, ids|
+        ids.each { |id| sync_association(source, id, association) }
+      end
+    end
+
+    def sync_association(source, id, association)
+      if verbose_logging?
+        @logger.info "synchronizing association with id: #{id}"
+      end
+
+      @synchronizer.with_association_sync_callbacks(source, id, association) do
+        attrs = association.model.synchronizer.find.(id)
+        Worker.run(association.model, [attrs], { :parent => source })
+      end
+    end
+
+    # Finds a `belongs_to` reflection to the parent model.
+    #
+    # @see ActiveRecord::Reflection::AssociationReflection
+    def belongs_to_parent_reflection
+      return unless @parent
+
+      model_reflections.find do |r|
+        r.macro == :belongs_to &&
+        r.plural_name == @parent.model.table_name
+      end
+    end
+
+    def model_reflections
+      @model.reflections.values
+    end
+
+    def verbose_logging?
+      Synchronizable.logging[:verbose]
+    end
+  end
+end