synced 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7216624feb81567456dd5c0d2468da9d36232efe
-  data.tar.gz: b2ac5bb712039e8ddedb5713960a5a68785545a4
+  metadata.gz: 129cd901e2a89c56c4854ebc844b1f37f57833e3
+  data.tar.gz: c52f215a8f82e22919adfc6925db0e9fbde894f4
 SHA512:
-  metadata.gz: bec0c589e63b7ff64d901a3d3e9172a032c7b1ba8bd9466122011d0dc9d127510294daa0d8597a95fbe60214c99c8feef96cfe9d598b63beb511cf7a6884832b
-  data.tar.gz: 955521df6291cc240e6ddd38e6643a0ebf79685fadd4a6285d585bdcee1b2445080635200e585b9cfd6daed47b2a295950a75120e53e2a0e116c8ae9a26573c5
+  metadata.gz: 59b45c2d36ed714e375e2d34eabe2d57ba62453aad252a4a8c6cec61f134fc692c8692476bfa5c530334ad536a48199edbde2cf372f2ca3b746aa4ffbf1b75eb
+  data.tar.gz: 77a485f2007ce67c0f01be365622a770b41c01f96b240212fa87985e495cb0e2fbba594ca146c38cf0199d6e7ccc86a681ee58307684064512578f3e3cb30398

data/README.md

@@ -1,12 +1,17 @@
 # Synced
 
-Synced is a Rails Engine that helps you keep local models synchronized with their BookingSync representation.
+Synced is a Rails Engine that helps you keep local models synchronized with
+their BookingSync representation.
 
-Note: This synchronization is in one way only, from BookingSync to your application. If you want to do a 2 way synchronization, you will need to implement it yourself using [BookingSync-API](https://github.com/BookingSync/bookingsync-api)
+Note: This synchronization is in one way only, from BookingSync to your
+application. If you want to do a 2 way synchronization, you will need to
+implement it yourself using
+[BookingSync-API](https://github.com/BookingSync/bookingsync-api)
 
 ## Requirements
 
-This engine requires BookingSync API `>= 0.0.17`, Rails `>= 4.0.0` and Ruby `>= 2.0.0`.
+This engine requires BookingSync API `>= 0.0.17`, Rails `>= 4.0.0` and
+Ruby `>= 2.0.0`.
 
 ## Documentation
 
@@ -14,24 +19,19 @@ This engine requires BookingSync API `>= 0.0.17`, Rails `>= 4.0.0` and Ruby `>=
 
 ## Installation
 
-Synced works with BookingSync API 0.0.17 onwards, Rails 4.0 onwards and Ruby 2.0 onwards. To get started, add it to your Gemfile with:
+Synced works with BookingSync API 0.0.17 onwards, Rails 4.0 onwards and Ruby
+2.0 onwards. To get started, add it to your Gemfile with:
 
 ```ruby
 gem 'synced'
 ```
 
-Then run the installer to copy the migrations,
-
-```console
-rake synced:install:migrations
-```
-
-Then, generate a migration to add Synced fields for the model you want to synchronize:
+Generate a migration to add Synced fields for the model you want to synchronize:
 
 Example:
 ```console
-rails g migration AddSyncedFieldsToRentals synced_id:integer:index synced_data:text \
-  synced_updated_at:datetime
+rails g migration AddSyncedFieldsToRentals synced_id:integer:index \
+  synced_data:text synced_updated_at:datetime
 ```
 
 and migrate:
@@ -40,11 +40,103 @@ and migrate:
 rake db:migrate
 ```
 
-And include `Synced::HasSyncedData` in the model you want to keep in sync:
+And `synced` statement to the model you want to keep in sync.
+
+Example:
+
+```ruby
+class Rental < ActiveRecord::Base
+  synced
+end
+```
+
+Run synchronization with given remote rentals
+
+Example:
+
+```ruby
+Rental.synchronize(remote: remote_rentals)
+```
+
+Run rentals synchronization in website scope
 
 Example:
+
 ```ruby
+Rental.synchronize(remote: remote_rentals, scope: website)
+```
+
+## Custom fields for storing remote object data.
+
+By default synced stores remote object in the following db columns.
+
+    `synced_id` - ID of the remote object
+    `synced_data` - Whole remote object is serialized into this attribute
+    `synced_all_at` - Synchronization time of the local object when using
+                      updated_since param
+
+You can configure your own fields in `synced` declaration in your model.
+
+```
 class Rental < ActiveRecord::Base
-  include Synced::HasSyncedData
+  synced id_key: :remote_id, data_key: :remote_data, synced_all_at_key: :remote_all_synced_at
 end
 ```
+
+## Local attributes
+
+All remote data is stored in `synced_data`, however sometimes it's useful to have some attributes directly in your model. You can use `local_attributes` for that.
+
+```
+class Rental < ActiveRecord::Base
+  synced local_attributes: [:name, :size]
+end
+```
+
+This assumes that model has name and size attributes. On every sychronization these two attributes will be assigned with value of `remote_object.name` and `remote_object.size` appropriately.
+
+## Disabling synchronization for selected fields.
+
+In some cases you only need one attribute to be synchronized and nothing more.
+By default even when using local_attributes, whole remote object will be
+saved in the `synced_data` and its updated_at in the `synced_all_at`.
+This may take additonal space in the database.
+In order to disable synchronizing these fields, set their names in the `synced` declaration to nil, as in the below example:
+
+```
+class Rental < ActiveRecord::Base
+  synced data_key: nil, synced_all_at_key: nil
+end
+```
+
+You cannot disable synchronizing `synced_id` as it's required to match local
+objects with the remote ones.
+
+## Associations
+
+It's possible to synchronize objects together with it's associations. For that
+you need to
+
+  1. Specify associations you want to synchronize within `synced`
+    declaration of the parent model
+  2. Add `synced` declaration to the associated model
+
+```ruby
+class Location < ActiveRecord::Base
+  synced associations: :photos
+  has_many :photos
+end
+
+class Photo < ActiveRecord::Base
+  synced
+  belongs_to :location
+end
+```
+
+Then run synchronization of the parent objects. Every of the remote_locations
+objects needs to respond to `remote_location[:photos]` from where data for
+photos association will be taken.
+
+```ruby
+Location.synchronize(remote: remote_locations)
+```

data/lib/synced/engine.rb

@@ -7,7 +7,13 @@ module Synced
     end
 
     config.to_prepare do
-      require "synced/engine/lib/has_synced_data"
+      require "synced/engine/has_synced_data"
+    end
+
+    ActiveSupport.on_load :active_record do
+      extend Synced::Engine::Model
     end
   end
 end
+
+require "synced/engine/model"

data/lib/synced/engine/has_synced_data.rb

@@ -0,0 +1,41 @@
+require 'hashie'
+
+# Provide a serialized attribute for models. This attribute is `synced_data_key`
+# which by default is `:synced_data`. This is a friendlier alternative to
+# `serialize` with respect to dirty attributes.
+module Synced::Engine::HasSyncedData
+  extend ActiveSupport::Concern
+  class SyncedData < Hashie::Mash; end
+
+  included do
+    if synced_data_key
+      define_method "#{synced_data_key}=" do |object|
+        write_attribute synced_data_key, dump(object)
+      end
+
+      define_method synced_data_key do
+        instance_variable_get("@#{synced_data_key}") ||
+          instance_variable_set("@#{synced_data_key}",
+            SyncedData.new(loaded_synced_data))
+      end
+    end
+  end
+
+  private
+
+  def loaded_synced_data
+    if data = read_attribute(synced_data_key)
+      load data
+    else
+      {}
+    end
+  end
+
+  def dump(object)
+    JSON.dump object
+  end
+
+  def load(source)
+    JSON.load source
+  end
+end

data/lib/synced/engine/model.rb

@@ -0,0 +1,74 @@
+require "synced/engine/synchronizer"
+
+module Synced::Engine::Model
+  # Enables synced for ActiveRecord model.
+  #
+  # @param options [Hash] Configuration options for synced. They are inherited
+  #   by subclasses, but can be overwritten in the subclass.
+  # @option options [Symbol] id_key: attribute name under which
+  #   remote object's ID is stored, default is :synced_id.
+  # @option options [Symbol] synced_all_at_key: attribute name under which
+  #   last synchronization time is stored, default is :synced_all_at. It's only
+  #   used when only_updated option is enabled.
+  # @option options [Boolean] only_updated: If true requests to API will take
+  #   advantage of updated_since param and fetch only created/changed/deleted
+  #   remote objects
+  # @option options [Symbol] data_key: attribute name under which remote
+  #   object's data is stored.
+  # @option options [Array] local_attributes: Array of attributes in the remote
+  #   object which will be mapped to local object attributes.
+  def synced(options = {})
+    class_attribute :synced_id_key, :synced_all_at_key, :synced_data_key,
+      :synced_local_attributes, :synced_associations, :synced_only_updated
+    self.synced_id_key           = options.fetch(:id_key, :synced_id)
+    self.synced_all_at_key       = options.fetch(:synced_all_at_key,
+      :synced_all_at)
+    self.synced_data_key         = options.fetch(:data_key, :synced_data)
+    self.synced_local_attributes = options.fetch(:local_attributes, [])
+    self.synced_associations     = options.fetch(:associations, [])
+    self.synced_only_updated     = options.fetch(:only_updated, false)
+    include Synced::Engine::HasSyncedData
+  end
+
+  # Performs synchronization of given remote objects to local database.
+  #
+  # @param remote [Array] - Remote objects to be synchronized with local db. If
+  #   it's nil then synchronizer will make request on it's own.
+  # @param model_class [Class] - ActiveRecord model class to which remote objects
+  #   will be synchronized.
+  # @param scope [ActiveRecord::Base] - Within this object scope local objects
+  #   will be synchronized. By default it's model_class.
+  # @param remove [Boolean] - If it's true all local objects within
+  #   current scope which are not present in the remote array will be destroyed.
+  #   If only_updated is enabled, ids of objects to be deleted will be taken
+  #   from the meta part. By default if cancel_at column is present, all
+  #   missing local objects will be canceled with cancel_all,
+  #   if it's missing, all will be destroyed with destroy_all.
+  #   You can also force method to remove local objects by passing it
+  #   to remove: :mark_as_missing.
+  # @example Synchronizing amenities
+  #
+  #   Amenity.synchronize(remote: [remote_amenity1, remote_amenity2])
+  #
+  # @example Synchronizing rentals within given website. This will
+  #   create/remove/update rentals only within website.
+  #   It requires relation website.rentals to exist.
+  #
+  #  Rental.synchronize(remote: remote_rentals, scope: website)
+  #
+  def synchronize(remote: nil, model_class: self, scope: nil, remove: false)
+    options = {
+      scope: scope,
+      id_key: synced_id_key,
+      synced_all_at_key: synced_all_at_key,
+      data_key: synced_data_key,
+      remove: remove,
+      local_attributes: synced_local_attributes,
+      associations: synced_associations,
+      only_updated: synced_only_updated
+    }
+    synchronizer = Synced::Engine::Synchronizer.new(remote, model_class,
+      options)
+    synchronizer.perform
+  end
+end

data/lib/synced/engine/synchronizer.rb

@@ -0,0 +1,188 @@
+# Synchronizer class which performs actual synchronization between
+# local database and given array of remote objects
+class Synced::Engine::Synchronizer
+  attr_reader :id_key
+
+  # Initializes a new Synchronizer
+  #
+  # @param remote_objects [Array|NilClass] Array of objects to be synchronized
+  #   with local database. Objects need to respond to at least :id message.
+  #   If it's nil, then synchronizer will fetch the remote objects on it's own.
+  # @param model_class [Class] ActiveRecord model class from which local objects
+  #   will be created.
+  # @param options [Hash]
+  # @option options [Symbol] scope: Within this object scope local objects
+  #   will be synchronized. By default it's model_class.
+  # @option options [Symbol] id_key: attribute name under which
+  #   remote object's ID is stored, default is :synced_id.
+  # @option options [Symbol] synced_all_at_key: attribute name under which
+  #   remote object's sync time is stored, default is :synced_all_at
+  # @option options [Symbol] data_key: attribute name under which remote
+  #   object's data is stored.
+  # @option options [Array] local_attributes: Array of attributes in the remote
+  #   object which will be mapped to local object attributes.
+  # @option options [Boolean] remove: If it's true all local objects within
+  #   current scope which are not present in the remote array will be destroyed.
+  #   If only_updated is enabled, ids of objects to be deleted will be taken
+  #   from the meta part. By default if cancel_at column is present, all
+  #   missing local objects will be canceled with cancel_all,
+  #   if it's missing, all will be destroyed with destroy_all.
+  #   You can also force method to remove local objects by passing it
+  #   to remove: :mark_as_missing.
+  # @option options [Boolean] only_updated: If true requests to API will take
+  #   advantage of updated_since param and fetch only created/changed/deleted
+  #   remote objects
+  def initialize(remote_objects, model_class, options = {})
+    @model_class       = model_class
+    @scope             = options[:scope]
+    @id_key            = options[:id_key]
+    @synced_all_at_key = options[:synced_all_at_key]
+    @data_key          = options[:data_key]
+    @remove            = options[:remove]
+    @only_updated      = options[:only_updated]
+    @local_attributes  = Array(options[:local_attributes])
+    @associations      = Array(options[:associations])
+    @remote_objects    = Array(remote_objects) if remote_objects
+    @request_performed = false
+  end
+
+  def perform
+    relation_scope.transaction do
+      remove_relation.send(remove_strategy) if @remove
+
+      remote_objects.map do |remote|
+        local_object = local_object_by_remote_id(remote.id) || relation_scope.new
+        local_object.attributes = default_attributes_mapping(remote)
+        local_object.attributes = local_attributes_mapping(remote)
+        local_object.save! if local_object.changed?
+        local_object.tap do |local_object|
+          @associations.each do |association|
+            klass = association.to_s.classify.constantize
+            klass.synchronize(remote: remote[association], scope: local_object,
+              remove: @remove)
+          end
+        end
+      end.tap do |local_objects|
+        if updated_since_enabled? && @request_performed
+          relation_scope.update_all(@synced_all_at_key => Time.now)
+        end
+      end
+    end
+  end
+
+  private
+
+  def local_attributes_mapping(remote)
+    Hash[@local_attributes.map { |k| [k, remote[k]] }]
+  end
+
+  def default_attributes_mapping(remote)
+    {}.tap do |attributes|
+      attributes[@id_key] = remote.id
+      attributes[@data_key] = remote if @data_key
+    end
+  end
+
+  # Returns relation within which local objects are created/edited and removed
+  # If no scope is provided, the relation_scope will be class on which
+  # .synchronize method is called.
+  # If scope is provided, like: account, then relation_scope will be a relation
+  # account.rentals (given we run .synchronize on Rental class)
+  #
+  # @return [ActiveRecord::Relation|Class]
+  def relation_scope
+    @scope ? @scope.send(resource_name) : @model_class
+  end
+
+  # Returns api client from the closest possible source.
+  #
+  # @raise [BookingSync::API::Unauthorized] - On unauthorized user
+  # @return [BookingSync::API::Client] BookingSync API client
+  def api
+    closest = [@scope, @scope.class, @model_class].detect do |o|
+                o.respond_to?(:api)
+              end
+    closest && closest.api || raise(MissingAPIClient.new(@scope, @model_class))
+  end
+
+  def local_object_by_remote_id(remote_id)
+    local_objects.find { |l| l.attributes[id_key.to_s] == remote_id }
+  end
+
+  def local_objects
+    @local_objects ||= relation_scope.where(id_key => remote_objects_ids).to_a
+  end
+
+  def remote_objects_ids
+    @remote_objects_ids ||= remote_objects.map(&:id)
+  end
+
+  def remote_objects
+    @remote_objects ||= fetch_remote_objects
+  end
+
+  def deleted_remote_objects_ids
+    api.last_response.meta[:deleted_ids]
+  end
+
+  def fetch_remote_objects
+    api.get("/#{resource_name}", api_request_options).tap do
+      @request_performed = true
+    end
+  end
+
+  def api_request_options
+    {}.tap do |options|
+      options[:include] = @associations if @associations.present?
+      options[:updated_since] = minimum_updated_at if updated_since_enabled?
+    end
+  end
+
+  def minimum_updated_at
+    relation_scope.minimum(@synced_all_at_key)
+  end
+
+  def updated_since_enabled?
+    @only_updated && @synced_all_at_key
+  end
+
+  def resource_name
+    @model_class.to_s.tableize
+  end
+
+  def remove_strategy
+    @remove == true ? default_remove_strategy : @remove
+  end
+
+  def default_remove_strategy
+    if @model_class.column_names.include?("canceled_at")
+      :cancel_all
+    else
+      :destroy_all
+    end
+  end
+
+  def remove_relation
+    if @only_updated
+      relation_scope.where(id_key => deleted_remote_objects_ids)
+    else
+      relation_scope.where.not(id_key => remote_objects_ids)
+    end
+  end
+
+  class MissingAPIClient < StandardError
+    def initialize(scope, model_class)
+      @scope = scope
+      @model_class = model_class
+    end
+
+    def message
+      if @scope
+        %Q{Missing BookingSync API client in #{@scope} object or
+#{@scope.class} class}
+      else
+        %Q{Missing BookingSync API client in #{@model_class} class}
+      end
+    end
+  end
+end

data/lib/synced/version.rb

@@ -1,3 +1,3 @@
 module Synced
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: synced
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Sebastien Grosjean
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-06-21 00:00:00.000000000 Z
+date: 2014-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -94,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Keep your BookingSync Application synced with BookingSync.
 email:
 - dev@bookingsync.com
@@ -104,12 +118,12 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- app/models/synced/synchronization.rb
 - config/routes.rb
-- db/migrate/20140621143737_create_synced_synchronizations.rb
 - lib/synced.rb
 - lib/synced/engine.rb
-- lib/synced/engine/lib/has_synced_data.rb
+- lib/synced/engine/has_synced_data.rb
+- lib/synced/engine/model.rb
+- lib/synced/engine/synchronizer.rb
 - lib/synced/version.rb
 homepage: https://github.com/BookingSync/synced
 licenses:

data/app/models/synced/synchronization.rb

@@ -1,4 +0,0 @@
-module Synced
-  class Synchronization < ActiveRecord::Base
-  end
-end

data/db/migrate/20140621143737_create_synced_synchronizations.rb

@@ -1,10 +0,0 @@
-class CreateSyncedSynchronizations < ActiveRecord::Migration
-  def change
-    create_table :synced_synchronizations do |t|
-      t.string :model
-      t.datetime :synchronized_at
-
-      t.timestamps
-    end
-  end
-end

data/lib/synced/engine/lib/has_synced_data.rb

@@ -1,37 +0,0 @@
-require 'hashie'
-
-module Synced
-  # Provide a serialized `bs_data` attribute for models. This is a friendlier
-  # alternative to `serialize` with respect to dirty attributes.
-  module HasSyncedData
-    class SyncedData < Hashie::Mash; end
-
-    # Serialize and set remote data from `object`.
-    def synced_data=(object)
-      write_attribute :synced_data, dump(object)
-    ensure
-      @synced_data = nil
-    end
-
-    # Return remote data as a cached instance.
-    def synced_data
-      @synced_data ||= SyncedData.new loaded_synced_data
-    end
-
-    private
-
-    def loaded_synced_data
-      load read_attribute(:synced_data)
-    rescue
-      {}
-    end
-
-    def dump(object)
-      JSON.dump object
-    end
-
-    def load(source)
-      JSON.load source
-    end
-  end
-end