restforce-db 0.1.4

data/lib/restforce/db/mapping.rb

@@ -0,0 +1,106 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Mapping captures a set of mappings between database columns
+    # and Salesforce fields, providing utilities to transform hashes of
+    # attributes from one to the other.
+    class Mapping
+
+      attr_reader :mappings
+
+      # Public: Initialize a new Restforce::DB::Mapping.
+      #
+      # mappings - A Hash, with keys corresponding to the names of Ruby object
+      #            attributes, and the values of those keys corresponding to the
+      #            names of the related Salesforce fields.
+      def initialize(mappings = {})
+        @mappings = mappings
+      end
+
+      # Public: Append a new set of attribute mappings to the current set.
+      #
+      # mappings - A Hash, with keys corresponding to the names of Ruby object
+      #            attributes, and the values of those keys corresponding to the
+      #            names of the related Salesforce fields.
+      #
+      # Returns nothing.
+      def add_mappings(mappings = {})
+        @mappings.merge!(mappings)
+      end
+
+      # Public: Get a list of the relevant Salesforce field names for this
+      # mapping.
+      #
+      # Returns an Array.
+      def salesforce_fields
+        @mappings.values
+      end
+
+      # Public: Get a list of the relevant database column names for this
+      # mapping.
+      #
+      # Returns an Array.
+      def database_fields
+        @mappings.keys
+      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 Symbol reflecting the expected attribute list. Accepted
+      #             values are :database and :salesforce.
+      #
+      # Yields the attribute name.
+      # Returns a Hash.
+      def attributes(from_format)
+        use_mappings =
+          case from_format
+          when :salesforce
+            @mappings
+          when :database
+            # Generate a mapping of database column names to record attributes.
+            database_fields.zip(database_fields)
+          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 Symbol reflecting the expected format. Accepted values
+      #              are :database and :salesforce.
+      # attributes - A Hash, with keys corresponding to the attribute names in
+      #              the format to convert away from.
+      #
+      # Examples
+      #
+      #   mapping = Mapping.new(some_key: "Some_Field__c")
+      #   mapping.convert(:salesforce, some_key: "some value")
+      #   # => { "Some_Field__c" => "some value" }
+      #
+      #   mapping.convert(:database, some_key: "some other value")
+      #   # => { some_key: "some other value" }
+      #
+      # Returns a Hash.
+      def convert(to_format, attributes)
+        case to_format
+        when :database
+          attributes.dup
+        when :salesforce
+          @mappings.each_with_object({}) do |(attribute, mapping), converted|
+            next unless attributes.key?(attribute)
+            converted[mapping] = attributes[attribute]
+          end
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/model.rb

@@ -0,0 +1,50 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Model is a helper module which attaches some special
+    # DSL-style methods to an ActiveRecord class, allowing for easier mapping
+    # of the ActiveRecord class to an object type in Salesforce.
+    module Model
+
+      # :nodoc:
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      # :nodoc:
+      module ClassMethods
+
+        # Public: Initializes a Restforce::DB::RecordType defining this model's
+        # relationship to a Salesforce object type.
+        #
+        # salesforce_model - A String name of an object type in Salesforce.
+        # mappings         - A Hash of mappings between database columns and
+        #                    fields in Salesforce.
+        #
+        # Returns a Restforce::DB::RecordType.
+        def map_to(salesforce_model, **mappings)
+          RecordType.new(
+            self,
+            salesforce_model,
+            mappings,
+          )
+        end
+
+        # Public: Append the passed mappings to this model.
+        #
+        # mappings - A Hash of database column names mapped to Salesforce
+        #            fields.
+        #
+        # Returns nothing.
+        def add_mappings(mappings)
+          RecordType[self].add_mappings(mappings)
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/record_type.rb

@@ -0,0 +1,77 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::RecordType is an abstraction for a two-way binding between
+    # an ActiveRecord class and a Salesforce object type. It provides an
+    # interface for mapping database columns to Salesforce fields.
+    class RecordType
+
+      class << self
+
+        include Enumerable
+        attr_accessor :collection
+
+        # Public: Get the Restforce::DB::RecordType entry for the specified
+        # database model.
+        #
+        # database_model - A Class compatible with ActiveRecord::Base.
+        #
+        # Returns a Restforce::DB::RecordType.
+        def [](database_model)
+          collection[database_model]
+        end
+
+        # Public: Iterate through all registered Restforce::DB::RecordTypes.
+        #
+        # Yields one RecordType for each database-to-Salesforce mapping.
+        # Returns nothing.
+        def each
+          collection.each do |database_model, record_type|
+            yield database_model.name, record_type
+          end
+        end
+
+      end
+
+      self.collection ||= {}
+      attr_reader :mapping, :synchronizer
+
+      # Public: Initialize and register a Restforce::DB::RecordType.
+      #
+      # database_model   - A Class compatible with ActiveRecord::Base.
+      # salesforce_model - A String name of an object type in Salesforce.
+      # mappings         - A Hash of mappings between database columns and
+      #                    fields in Salesforce.
+      def initialize(database_model, salesforce_model, **mappings)
+        @mapping = Mapping.new(mappings)
+        @database_record_type = RecordTypes::ActiveRecord.new(database_model, @mapping)
+        @salesforce_record_type = RecordTypes::Salesforce.new(salesforce_model, @mapping)
+        @synchronizer = Synchronizer.new(@database_record_type, @salesforce_record_type)
+
+        self.class.collection[database_model] = self
+      end
+
+      # Public: Append the passed mappings to this model.
+      #
+      # mappings - A Hash of database column names mapped to Salesforce fields.
+      #
+      # Returns nothing.
+      def add_mappings(mappings)
+        @mapping.add_mappings mappings
+      end
+
+      # Public: Synchronize the records between the database and Salesforce.
+      #
+      # options - A Hash of options to pass to the synchronizer.
+      #
+      # Returns nothing.
+      def synchronize(options = {})
+        @synchronizer.run(options)
+      end
+
+    end
+
+  end
+
+end

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

@@ -0,0 +1,80 @@
+module Restforce
+
+  module DB
+
+    module RecordTypes
+
+      # Restforce::DB::RecordTypes::ActiveRecord serves as a wrapper for a
+      # single ActiveRecord::Base-compatible class, allowing for standard record
+      # lookups and attribute mappings.
+      class ActiveRecord < Base
+
+        # Public: Create an instance of this ActiveRecord model for the passed
+        # Salesforce instance.
+        #
+        # from_record - A Restforce::DB::Instances::Salesforce instance.
+        #
+        # Returns a Restforce::DB::Instances::ActiveRecord instance.
+        # Raises on any validation or database error.
+        def create!(from_record)
+          attributes = @mapping.convert(:database, from_record.attributes)
+          record = @record_type.create!(
+            attributes.merge(salesforce_id: from_record.id),
+          )
+
+          Instances::ActiveRecord.new(record, @mapping)
+        end
+
+        # Public: Find the instance of this ActiveRecord model corresponding to
+        # the passed salesforce_id.
+        #
+        # salesforce_id - The id of the record in Salesforce.
+        #
+        # Returns nil or a Restforce::DB::Instances::ActiveRecord instance.
+        def find(id)
+          record = @record_type.find_by(salesforce_id: id)
+          return nil unless record
+
+          Instances::ActiveRecord.new(record, @mapping)
+        end
+
+        # Public: Iterate through all ActiveRecord records of this type.
+        #
+        # options - A Hash of options which should be applied to the set of
+        #           fetched records. Allowed options are:
+        #           :before - A Time object defining the most recent update
+        #                     timestamp for which records should be returned.
+        #           :after  - A Time object defining the least recent update
+        #                     timestamp for which records should be returned.
+        #
+        # Yields a series of Restforce::DB::Instances::ActiveRecord instances.
+        # Returns nothing.
+        def each(options = {})
+          scope = @record_type
+          scope = scope.where("updated_at > ?", options[:after]) if options[:after]
+          scope = scope.where("updated_at < ?", options[:before]) if options[:before]
+
+          scope.find_each do |record|
+            yield Instances::ActiveRecord.new(record, @mapping)
+          end
+        end
+
+        private
+
+        # Internal: Has this Salesforce record already been linked to a database
+        # record?
+        #
+        # record - A Restforce::DB::Instances::Salesforce instance.
+        #
+        # Returns a Boolean.
+        def synced?(record)
+          @record_type.exists?(salesforce_id: record.id)
+        end
+
+      end
+
+    end
+
+  end
+
+end

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

@@ -0,0 +1,44 @@
+module Restforce
+
+  module DB
+
+    module RecordTypes
+
+      # Restforce::DB::RecordTypes::Base defines common behavior for the other
+      # models defined in the Restforce::DB::RecordTypes namespace.
+      class Base
+
+        # Public: Initialize a new Restforce::DB::RecordTypes::Base.
+        #
+        # record_type - The name or class of the system record type.
+        # mapping     - An instance of Restforce::DB::Mapping.
+        def initialize(record_type, mapping = Mapping.new)
+          @record_type = record_type
+          @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)
+            record = find(from_record.id)
+            record.copy!(from_record)
+
+            record
+          else
+            create!(from_record)
+          end
+        end
+
+      end
+
+    end
+
+  end
+
+end

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

@@ -0,0 +1,94 @@
+module Restforce
+
+  module DB
+
+    module RecordTypes
+
+      # Restforce::DB::RecordTypes::Salesforce serves as a wrapper for a single
+      # Salesforce object class, allowing for standard record lookups and
+      # attribute mappings.
+      class Salesforce < Base
+
+        # Public: Create an instance of this Salesforce model for the passed
+        # database record.
+        #
+        # from_record - A Restforce::DB::Instances::ActiveRecord instance.
+        #
+        # Returns a Restforce::DB::Instances::Salesforce instance.
+        # Raises on any error from Salesforce.
+        def create!(from_record)
+          attributes = @mapping.convert(:salesforce, from_record.attributes)
+          record_id = DB.client.create!(@record_type, attributes)
+          from_record.update!(salesforce_id: record_id)
+
+          find(record_id)
+        end
+
+        # Public: Find the Salesforce record corresponding to the passed id.
+        #
+        # id - The id of the record in Salesforce.
+        #
+        # Returns nil or a Restforce::DB::Instances::Salesforce instance.
+        def find(id)
+          record = DB.client.query(
+            "select #{lookups} from #{@record_type} where Id = '#{id}'",
+          ).first
+
+          return unless record
+
+          Instances::Salesforce.new(record, @mapping)
+        end
+
+        # Public: Iterate through all Salesforce records of this type.
+        #
+        # options - A Hash of options which should be applied to the set of
+        #           fetched records. Allowed options are:
+        #           :before - A Time object defining the most recent update
+        #                     timestamp for which records should be returned.
+        #           :after  - A Time object defining the least recent update
+        #                     timestamp for which records should be returned.
+        #
+        # Yields a series of Restforce::DB::Instances::Salesforce instances.
+        # Returns nothing.
+        def each(options = {})
+          constraints = [
+            ("SystemModstamp <= #{options[:before].utc.iso8601}" if options[:before]),
+            ("SystemModstamp > #{options[:after].utc.iso8601}" if options[:after]),
+          ].compact.join(" and ")
+          constraints = " where #{constraints}" unless constraints.empty?
+
+          query = "select #{lookups} from #{@record_type}#{constraints}"
+
+          DB.client.query(query).each do |record|
+            yield Instances::Salesforce.new(record, @mapping)
+          end
+        end
+
+        private
+
+        # Internal: Get a String of values to look up when the record is
+        # fetched from Salesforce. Includes all configured mappings and a
+        # handful of attributes for internal use.
+        #
+        # Returns a String.
+        def lookups
+          (Instances::Salesforce::INTERNAL_ATTRIBUTES + @mapping.salesforce_fields).join(", ")
+        end
+
+        # Internal: Has this database record already been linked to a Salesforce
+        # record?
+        #
+        # record - A Restforce::DB::Instances::Salesforce instance.
+        #
+        # Returns a Boolean.
+        def synced?(record)
+          record.synced?
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/synchronizer.rb

@@ -0,0 +1,57 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Synchronizer is responsible for synchronizing the records
+    # in Salesforce with the records in the database. It relies on the mappings
+    # configured in instances of Restforce::DB::RecordTypes::Base to create and
+    # update records with the appropriate values.
+    class Synchronizer
+
+      attr_reader :last_run
+
+      # Public: Initialize a new Restforce::DB::Synchronizer.
+      #
+      # database_record_type   - A Restforce::DB::RecordTypes::ActiveRecord
+      #                          instance.
+      # salesforce_record_type - A Restforce::DB::RecordTypes::Salesforce
+      #                          instance.
+      # last_run_time          - A Time object reflecting the time of the most
+      #                          recent synchronization run. Runs will only
+      #                          synchronize data more recent than this stamp.
+      def initialize(database_record_type, salesforce_record_type, last_run_time = nil)
+        @database_record_type = database_record_type
+        @salesforce_record_type = salesforce_record_type
+        @last_run = last_run_time
+      end
+
+      # Public: Run the synchronize process, pulling in records from Salesforce
+      # and the database to determine which records need to be created and/or
+      # updated.
+      #
+      # NOTE: We bootstrap our record lookups to the exact same timespan, and
+      # run the Salesforce sync into the database first. This has the effect of
+      # overwriting recent changes to the database, in the event that Salesforce
+      # has also been updated since the last sync.
+      #
+      # options - A Hash of options for configuring the run. Currently unused.
+      #
+      # Returns the Time the run was performed.
+      def run(_options = {})
+        run_time = Time.now
+
+        @salesforce_record_type.each(after: last_run, before: run_time) do |record|
+          @database_record_type.sync!(record)
+        end
+        @database_record_type.each(after: last_run, before: run_time) do |record|
+          @salesforce_record_type.sync!(record)
+        end
+
+        @last_run = run_time
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/version.rb

@@ -0,0 +1,10 @@
+module Restforce
+
+  # :nodoc:
+  module DB
+
+    VERSION = "0.1.4"
+
+  end
+
+end

data/lib/restforce/db/worker.rb

@@ -0,0 +1,156 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Worker represents the primary polling loop through which
+    # all record synchronization occurs.
+    class Worker
+
+      DEFAULT_INTERVAL = 5
+
+      class << self
+
+        attr_accessor :logger, :interval
+
+        # 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
+          return if @files_to_reopen
+
+          @files_to_reopen = []
+          ObjectSpace.each_object(File) do |file|
+            @files_to_reopen << file unless file.closed?
+          end
+        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 ::Exception # rubocop:disable HandleExceptions, RescueException
+            end
+          end
+        end
+
+      end
+
+      # Public: Initialize a new Restforce::DB::Worker.
+      #
+      # options - A Hash of options to configure the worker's run. Currently
+      #           supported options are:
+      #           interval - The maximum polling loop rest time.
+      #           config   - The path to a client configuration file.
+      #           verbose  - Display command line output? Defaults to false.
+      def initialize(options = {})
+        @verbose = options.fetch(:verbose) { false }
+        self.class.interval = options.fetch(:interval) { DEFAULT_INTERVAL }
+
+        Restforce::DB.configure { |config| config.parse(options[:config]) }
+      end
+
+      # Public: Start the polling loop for this Worker. Synchronizes all
+      # registered record types between the database and Salesforce, looping
+      # indefinitely until processing is interrupted by a signal.
+      #
+      # Returns nothing.
+      def start
+        trap("TERM") do
+          Thread.new { log "Exiting..." }
+          stop
+        end
+
+        trap("INT") do
+          Thread.new { log "Exiting..." }
+          stop
+        end
+
+        log "Starting synchronization..."
+
+        loop do
+          runtime = Benchmark.realtime do
+            Restforce::DB::RecordType.each do |name, record_type|
+              synchronize name, record_type
+            end
+          end
+
+          if runtime < self.class.interval && !stop?
+            sleep(self.class.interval - runtime)
+          end
+
+          break if stop?
+        end
+      end
+
+      # Public: Instruct the worker to stop running at the end of the current
+      # processing loop.
+      #
+      # Returns nothing.
+      def stop
+        @exit = true
+      end
+
+      private
+
+      # Internal: Synchronize the objects in the database and Salesforce
+      # corresponding to the passed record type.
+      #
+      # name        - The String name of the record type to synchronize.
+      # record_type - A Restforce::DB::RecordType.
+      #
+      # Returns a Boolean.
+      def synchronize(name, record_type)
+        log "(#{name}) SYNCHRONIZING"
+        runtime =  Benchmark.realtime { record_type.synchronize }
+        log format("(#{name}) COMPLETED after %.4f", runtime)
+
+        return true
+      rescue => e
+        error(e)
+
+        return false
+      end
+
+      # Internal: Has this worker been instructed to stop?
+      #
+      # Returns a boolean.
+      def stop?
+        @exit == true
+      end
+
+      # Internal: Log the passed text at the specified level.
+      #
+      # text  - The piece of text which should be logged for this worker.
+      # level - The level at which the text should be logged. Defaults to :info.
+      #
+      # Returns nothing.
+      def log(text, level = :info)
+        text = "[Restforce::DB] #{text}"
+        puts text if @verbose
+
+        return unless self.class.logger
+
+        self.class.logger.send(level, "#{Time.now.strftime('%FT%T%z')}: #{text}")
+      end
+
+      # Internal: Log an error for the worker, outputting the entire error
+      # stacktrace and applying the appropriate log level.
+      #
+      # exception - An Exception object.
+      #
+      # Returns nothing.
+      def error(exception)
+        log "#{exception.message}\n#{exception.backtrace.join("\n")}", :error
+      end
+
+    end
+
+  end
+
+end