restforce-db 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 98a9d9a418a15a7b4ca5ab954bc95d3e831e3bca
-  data.tar.gz: 26effab90549afaecad3d7883ef6f0881c4e96d4
+  metadata.gz: 42506d7bec2c00a7c2161188ef2b238459942da8
+  data.tar.gz: ce83cb60cbfdbd48388189aef560b3257d86995c
 SHA512:
-  metadata.gz: 5b8140eb2811c5fad0e94d82bf255219eb15d95105581eb32d84ce3cf0fd504495c5b39251d436581eee8f1955355311484491b26571b0041cb38c50f0a2e269
-  data.tar.gz: 170e5593fe2cf93d1e2500927baaec31747d5670fd7bb4113619d6ba65e35fdabcbc48201cdc7213a696ea565772218111f95575945c3ad62e7b5554dda852c9
+  metadata.gz: 0b394e0887d9b4986320b8c1776f0098069aed032a0810c17465ab14d75ce57ac9bbc505cdbabe861b80a89fc7b559ba3f559954ae0beb2adfd398c5c5d502e9
+  data.tar.gz: 7821768fbd4a8da7e87ca397a9015059e9f81d1f08e064e63b4fd626705a58a2ee27a62e0c7499423f59843dfaf5d8d3d4b5b1b34f7697fc8d820b4336f67e8a

data/lib/file_daemon.rb

@@ -0,0 +1,42 @@
+# FileDaemon defines some standard hooks for forking processes which retain
+# file descriptors. Implementation derived from the Delayed::Job library:
+# https://github.com/collectiveidea/delayed_job/blob/master/lib/delayed/worker.rb#L77-L98.
+module FileDaemon
+
+  # Public: Extend the including class with before/after_fork hooks.
+  #
+  # base - The including class.
+  #
+  # Returns nothing.
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # :nodoc:
+  module ClassMethods
+
+    # Public: Store the list of currently open file descriptors so that they
+    # may be reopened when a new process is spawned.
+    #
+    # Returns nothing.
+    def before_fork
+      @files_to_reopen ||= ObjectSpace.each_object(File).reject(&:closed?)
+    end
+
+    # Public: Reopen all file descriptors that have been stored through the
+    # before_fork hook.
+    #
+    # Returns nothing.
+    def after_fork
+      @files_to_reopen.each do |file|
+        begin
+          file.reopen file.path, "a+"
+          file.sync = true
+        rescue ::IOError # rubocop:disable HandleExceptions
+        end
+      end
+    end
+
+  end
+
+end

data/lib/restforce/db/accumulator.rb

@@ -0,0 +1,41 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Accumulator is responsible for the accumulation of changes
+    # over the course of a single synchronization run. As we iterate over the
+    # various mappings, we build a set of changes for each Salesforce ID, which
+    # is then applied to all objects synchronized with that Salesforce object.
+    class Accumulator < Hash
+
+      # Public: Get the accumulated list of attributes after all changes have
+      # been applied.
+      #
+      # Returns a Hash.
+      def attributes
+        sort.reverse.each_with_object({}) do |(_, changeset), final|
+          changeset.each { |attribute, value| final[attribute] ||= value }
+        end
+      end
+
+      # Public: Get a Hash representing the changes that would need to be
+      # applied to make a passed Hash a subset of this Accumulator's derived
+      # attributes Hash.
+      #
+      # comparison - A Hash mapping of attributes to values.
+      #
+      # Returns a Hash.
+      def diff(comparison)
+        attributes.each_with_object({}) do |(attribute, value), diff|
+          next unless comparison.key?(attribute)
+          next if comparison[attribute] == value
+
+          diff[attribute] = value
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/attribute_map.rb

@@ -0,0 +1,132 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::AttributeMap encapsulates the logic for converting between
+    # various representations of attribute hashes.
+    class AttributeMap
+
+      # Public: Initialize a Restforce::DB::AttributeMap.
+      #
+      # database_model   - A Class compatible with ActiveRecord::Base.
+      # salesforce_model - A String name of an object type in Salesforce.
+      # fields           - A Hash of mappings between database columns and
+      #                    fields in Salesforce.
+      def initialize(database_model, salesforce_model, fields = {})
+        @database_model = database_model
+        @salesforce_model = salesforce_model
+        @fields = fields
+
+        @types = {
+          database_model   => :database,
+          salesforce_model => :salesforce,
+        }
+      end
+
+      # Public: Build a normalized Hash of attributes from the appropriate set
+      # of mappings. The keys of the resulting mapping Hash will correspond to
+      # the database column names.
+      #
+      # from_format - A String or Class reflecting the record type from which
+      #               the attribute Hash is being compiled.
+      #
+      # Yields a series of attribute names.
+      # Returns a Hash.
+      def attributes(from_format)
+        use_mappings =
+          case @types[from_format]
+          when :salesforce
+            @fields
+          when :database
+            # Generate a mapping of database column names to record attributes.
+            @fields.keys.zip(@fields.keys)
+          else
+            raise ArgumentError
+          end
+
+        use_mappings.each_with_object({}) do |(attribute, mapping), values|
+          values[attribute] = yield(mapping)
+        end
+      end
+
+      # Public: Convert a Hash of normalized attributes to a format compatible
+      # with a specific platform.
+      #
+      # to_format  - A String or Class reflecting the record type for which the
+      #              attribute Hash is being compiled.
+      # attributes - A Hash of attributes, with keys corresponding to the
+      #              normalized attribute names.
+      #
+      # Examples
+      #
+      #   mapping = Mapping.new(MyClass, "Object__c", some_key: "SomeField__c")
+      #
+      #   mapping.convert("Object__c", some_key: "some value")
+      #   # => { "Some_Field__c" => "some value" }
+      #
+      #   mapping.convert(MyClass, some_key: "some other value")
+      #   # => { some_key: "some other value" }
+      #
+      # Returns a Hash.
+      def convert(to_format, attributes)
+        case @types[to_format]
+        when :database
+          attributes.dup
+        when :salesforce
+          @fields.each_with_object({}) do |(attribute, mapping), converted|
+            next unless attributes.key?(attribute)
+            converted[mapping] = attributes[attribute]
+          end
+        else
+          raise ArgumentError
+        end
+      end
+
+      # Public: Convert a Hash of Salesforce attributes to a format compatible
+      # with a specific platform.
+      #
+      # to_format  - A String or Class reflecting the record type for which the
+      #              attribute Hash is being compiled.
+      # attributes - A Hash of attributes, with keys corresponding to the
+      #              Salesforce attribute names.
+      #
+      # Examples
+      #
+      #   map = AttributeMap.new(
+      #     MyClass,
+      #     "Object__c",
+      #     some_key: "SomeField__c",
+      #   )
+      #
+      #   map.convert_from_salesforce(
+      #     "Object__c",
+      #     "Some_Field__c" => "some value",
+      #   )
+      #   # => { "Some_Field__c" => "some value" }
+      #
+      #   map.convert_from_salesforce(
+      #     MyClass,
+      #     "Some_Field__c" => "some other value",
+      #   )
+      #   # => { some_key: "some other value" }
+      #
+      # Returns a Hash.
+      def convert_from_salesforce(to_format, attributes)
+        case @types[to_format]
+        when :database
+          @fields.each_with_object({}) do |(attribute, mapping), converted|
+            next unless attributes.key?(mapping)
+            converted[attribute] = attributes[mapping]
+          end
+        when :salesforce
+          attributes.dup
+        else
+          raise ArgumentError
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/collector.rb

@@ -0,0 +1,79 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Collector is responsible for grabbing the attributes from
+    # recently-updated records for purposes of synchronization. It relies on the
+    # mappings configured in instances of Restforce::DB::RecordTypes::Base to
+    # locate recently-updated records and fetch their attributes.
+    class Collector
+
+      attr_reader :last_run
+
+      # Public: Initialize a new Restforce::DB::Collector.
+      #
+      # mapping - A Restforce::DB::Mapping instance.
+      # runner  - A Restforce::DB::Runner instance.
+      def initialize(mapping, runner = Runner.new)
+        @mapping = mapping
+        @runner = runner
+      end
+
+      # Public: Run the collection process, pulling in records from Salesforce
+      # and the database to determine the lists of attributes to apply to all
+      # mapped records.
+      #
+      # accumulator - A Hash-like accumulator object.
+      #
+      # Returns a Hash mapping Salesforce ID/type combinations to accumulators.
+      def run(accumulator = nil)
+        @accumulated_changes = accumulator || accumulated_changes
+
+        @runner.run(@mapping) do |run|
+          run.salesforce_records { |record| accumulate(record) }
+          run.database_records { |record| accumulate(record) }
+        end
+
+        accumulated_changes
+      ensure
+        # Clear out the results of this run so we start fresh next time.
+        @accumulated_changes = nil
+      end
+
+      private
+
+      # Internal: Get a Hash to collect accumulated changes.
+      #
+      # Returns a Hash of Hashes.
+      def accumulated_changes
+        @accumulated_changes ||= Hash.new { |h, k| h[k] = {} }
+      end
+
+      # Internal: Append the passed record's attributes to its accumulated list
+      # of changesets.
+      #
+      # record - A Restforce::DB::Instances::Base.
+      #
+      # Returns nothing.
+      def accumulate(record)
+        accumulated_changes[key_for(record)].store(
+          record.last_update,
+          @mapping.convert(@mapping.salesforce_model, record.attributes),
+        )
+      end
+
+      # Internal: Get a unique key with enough information to look up the passed
+      # record in Salesforce.
+      #
+      # record - A Restforce::DB::Instances::Base.
+      #
+      # Returns an Object.
+      def key_for(record)
+        [record.id, record.mapping.salesforce_model]
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/initializer.rb

@@ -0,0 +1,62 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Initializer is responsible for ensuring that both systems
+    # are populated with the same records at the root level. It iterates through
+    # recently added or updated records in each system for a mapping, and
+    # creates a matching record in the other system, when necessary.
+    class Initializer
+
+      # Public: Initialize a Restforce::DB::Initializer.
+      #
+      # mapping - A Restforce::DB::Mapping.
+      # runner  - A Restforce::DB::Runner.
+      def initialize(mapping, runner = Runner.new)
+        @mapping = mapping
+        @runner = runner
+      end
+
+      # Public: Run the initialization loop for this mapping.
+      #
+      # Returns nothing.
+      def run
+        return unless @mapping.root?
+
+        @runner.run(@mapping) do |run|
+          run.salesforce_records { |record| create_in_database(record) }
+          run.database_records { |record| create_in_salesforce(record) }
+        end
+      end
+
+      private
+
+      # Internal: Attempt to create a partner record in the database for the
+      # passed Salesforce record. Does nothing if the Salesforce record has
+      # already been synchronized into the system at least once.
+      #
+      # record - A Restforce::DB::Instances::Salesforce.
+      #
+      # Returns nothing.
+      def create_in_database(record)
+        return if record.synced?
+        @mapping.database_record_type.create!(record)
+      end
+
+      # Internal: Attempt to create a partner record in Salesforce for the
+      # passed database record. Does nothing if the database record already has
+      # an associated Salesforce record.
+      #
+      # record - A Restforce::DB::Instances::ActiveRecord.
+      #
+      # Returns nothing.
+      def create_in_salesforce(record)
+        return if record.synced?
+        @mapping.salesforce_record_type.create!(record)
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/instances/base.rb

@@ -8,7 +8,7 @@ module Restforce
       # models defined in the Restforce::DB::Instances namespace.
       class Base
 
-        attr_reader :record
+        attr_reader :record, :record_type, :mapping
 
         # Public: Initialize a new Restforce::DB::Instances::Base instance.
         #
@@ -32,19 +32,6 @@ module Restforce
           after_sync
         end
 
-        # Public: Update the instance with attributes copied from the passed
-        # record.
-        #
-        # record - An object responding to `#attributes`. Must return a Hash of
-        #          attributes corresponding to the configured mappings for this
-        #          instance.
-        #
-        # Returns self.
-        # Raises if the update fails for any reason.
-        def copy!(from_record)
-          update! @mapping.convert(@record_type, from_record.attributes)
-        end
-
         # Public: Get a Hash mapping the configured attributes names to their
         # values for this instance.
         #

data/lib/restforce/db/instances/salesforce.rb

@@ -36,6 +36,13 @@ module Restforce
           last_update
         end
 
+        # Public: Has this record been synced with Salesforce?
+        #
+        # Returns a Boolean.
+        def synced?
+          @mapping.database_model.exists?(@mapping.lookup_column => id)
+        end
+
       end
 
     end

data/lib/restforce/db/mapping.rb

@@ -14,14 +14,13 @@ module Restforce
         include Enumerable
         attr_accessor :collection
 
-        # Public: Get the Restforce::DB::Mapping entry for the specified
-        # database model.
+        # Public: Get the Restforce::DB::Mapping entry for the specified model.
         #
-        # database_model - A Class compatible with ActiveRecord::Base.
+        # model - A String or Class.
         #
         # Returns a Restforce::DB::Mapping.
-        def [](database_model)
-          collection[database_model]
+        def [](model)
+          collection[model]
         end
 
         # Public: Iterate through all registered Restforce::DB::Mappings.
@@ -29,17 +28,43 @@ module Restforce
         # Yields one Mapping for each database-to-Salesforce mapping.
         # Returns nothing.
         def each
-          collection.each do |_, mappings|
+          collection.each do |model, mappings|
+            # Since each mapping is inserted twice, we ignore the half which
+            # were inserted via Salesforce model names.
+            next unless model.is_a?(Class)
+
             mappings.each do |mapping|
               yield mapping
             end
           end
         end
 
+        # Public: Add a mapping to the overarching Mapping collection. Appends
+        # the mapping to the collection for both its database and salesforce
+        # object types.
+        #
+        # mapping - A Restforce::DB::Mapping.
+        #
+        # Returns nothing.
+        def <<(mapping)
+          [mapping.database_model, mapping.salesforce_model].each do |model|
+            collection[model] ||= []
+            collection[model] << mapping
+          end
+        end
+
       end
 
       self.collection ||= {}
 
+      extend Forwardable
+      def_delegators(
+        :@attribute_map,
+        :attributes,
+        :convert,
+        :convert_from_salesforce,
+      )
+
       attr_reader(
         :database_model,
         :salesforce_model,
@@ -78,13 +103,9 @@ module Restforce
         @conditions = options.fetch(:conditions) { [] }
         @through = options.fetch(:through) { nil }
 
-        @types = {
-          database_model   => :database,
-          salesforce_model => :salesforce,
-        }
+        @attribute_map = AttributeMap.new(database_model, salesforce_model, @fields)
 
-        self.class.collection[database_model] ||= []
-        self.class.collection[database_model] << self
+        self.class << self
       end
 
       # Public: Get a list of the relevant Salesforce field names for this
@@ -131,73 +152,6 @@ module Restforce
         @through.nil?
       end
 
-      # Public: Build a normalized Hash of attributes from the appropriate set
-      # of mappings. The keys of the resulting mapping Hash will correspond to
-      # the database column names.
-      #
-      # in_format - A String or Class reflecting the record type from which the
-      #             attribute Hash is being compiled.
-      #
-      # Yields the attribute name.
-      # Returns a Hash.
-      def attributes(from_format)
-        use_mappings =
-          case @types[from_format]
-          when :salesforce
-            @fields
-          when :database
-            # Generate a mapping of database column names to record attributes.
-            database_fields.zip(database_fields)
-          else
-            raise ArgumentError
-          end
-
-        use_mappings.each_with_object({}) do |(attribute, mapping), values|
-          values[attribute] = yield(mapping)
-        end
-      end
-
-      # Public: Convert a Hash of attributes to a format compatible with a
-      # specific platform.
-      #
-      # to_format  - A String or Class reflecting the record type for which the
-      #              attribute Hash is being compiled.
-      # attributes - A Hash of attributes, with keys corresponding to the
-      #              normalized attribute names.
-      #
-      # Examples
-      #
-      #   mapping = Mapping.new(MyClass, "Object__c", some_key: "SomeField__c")
-      #
-      #   mapping.convert("Object__c", some_key: "some value")
-      #   # => { "Some_Field__c" => "some value" }
-      #
-      #   mapping.convert(MyClass, some_key: "some other value")
-      #   # => { some_key: "some other value" }
-      #
-      # Returns a Hash.
-      def convert(to_format, attributes)
-        case @types[to_format]
-        when :database
-          attributes.dup
-        when :salesforce
-          @fields.each_with_object({}) do |(attribute, mapping), converted|
-            next unless attributes.key?(attribute)
-            converted[mapping] = attributes[attribute]
-          end
-        else
-          raise ArgumentError
-        end
-      end
-
-      # Public: Get a Synchronizer for the record types captured by this
-      # Mapping.
-      #
-      # Returns a Restforce::DB::Synchronizer.
-      def synchronizer
-        @synchronizer ||= Synchronizer.new(@database_record_type, @salesforce_record_type)
-      end
-
     end
 
   end

data/lib/restforce/db/record_types/base.rb

@@ -19,36 +19,6 @@ module Restforce
           @mapping = mapping
         end
 
-        # Public: Synchronize the passed record to the record type defined by
-        # this class.
-        #
-        # from_record - A Restforce::DB::Instances::Base instance.
-        #
-        # Returns a Restforce::DB::Instances::Base instance.
-        # Raises on any validation or external error.
-        def sync!(from_record)
-          if synced?(from_record)
-            update!(from_record)
-          elsif @mapping.root?
-            create!(from_record)
-          end
-        end
-
-        # Public: Update an existing record of this record type with the
-        # attributes from the passed record. Only applies changes if from_record
-        # has been more recently updated than the last record synchronization.
-        #
-        # from_record - A Restforce::DB::Instances::Base instance.
-        #
-        # Returns a Restforce::DB::Instances::Base instance.
-        # Raises on any validation or external error.
-        def update!(from_record)
-          record = find(from_record.id)
-          return record if from_record.last_update < record.last_synchronize
-
-          record.copy!(from_record)
-        end
-
       end
 
     end

data/lib/restforce/db/runner.rb

@@ -0,0 +1,80 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Runner provides an abstraction for lookup timing during the
+    # synchronization process. It provides methods for accessing only recently-
+    # modified records within the context of a specific Mapping.
+    class Runner
+
+      attr_reader :last_run, :before, :after
+
+      # Public: Initialize a new Restforce::DB::Runner.
+      #
+      # delay         - A Numeric offet to apply to all record lookups. Can be
+      #                 used to mitigate server timing issues.
+      # last_run_time - A Time indicating the point at which new runs should
+      #                 begin.
+      def initialize(delay = 0, last_run_time = DB.last_run)
+        @delay = delay
+        @last_run = last_run_time
+      end
+
+      # Public: Indicate that a new phase of the run is beginning. Updates the
+      # before/after timestamp to ensure that new lookups are properly filtered.
+      #
+      # Returns the new run Time.
+      def tick!
+        run_time = Time.now
+
+        @before = run_time - @delay
+        @after = last_run - @delay if @last_run
+
+        @last_run = run_time
+      end
+
+      # Public: Grant access to recently-updated records for a specific mapping.
+      #
+      # mapping - A Restforce::DB::Mapping instance.
+      #
+      # Yields self, in the context of the passed mapping.
+      # Returns nothing.
+      def run(mapping)
+        @mapping = mapping
+        yield self
+      ensure
+        @mapping = nil
+      end
+
+      # Public: Iterate through recently-updated records for the Salesforce
+      # record type defined by the current mapping.
+      #
+      # Yields a series of Restforce::DB::Instances::Salesforce objects.
+      # Returns nothing.
+      def salesforce_records
+        @mapping.salesforce_record_type.each(options) { |record| yield record }
+      end
+
+      # Public: Iterate through recently-updated records for the database model
+      # record type defined by the current mapping.
+      #
+      # Yields a series of Restforce::DB::Instances::ActiveRecord objects.
+      # Returns nothing.
+      def database_records
+        @mapping.database_record_type.each(options) { |record| yield record }
+      end
+
+      private
+
+      # Internal: Get a Hash of options to apply to record lookups.
+      #
+      # Returns a Hash.
+      def options
+        { after: after, before: before }
+      end
+
+    end
+
+  end
+
+end