restforce-db 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ed593fdcf73e145f3957db532c939650f7112b77
-  data.tar.gz: 2a20acce1c5b9d85e717d6dc33d9c1e85a1c392d
+  metadata.gz: 008721b2ee67237a7bbcf0d8c8cdc9353fcbceb8
+  data.tar.gz: 25ddc50b58f134522817748ddbb36ba32dc57fa2
 SHA512:
-  metadata.gz: 2f875a2b2f3f88717e2fd3ef74d842f25fc7b0bbc11726ee33ed3e91ed26c0744f28d647aa5d04c4a5bf548665f19fdc102462a84474ef694687d0df26d7ad4e
-  data.tar.gz: 0fab5908d5a1ae144f8563c4a27fb02f03004a932ac4044316d17f442047b0f170529ccf457ee6600e3a87fb5b0acdb606a18d56dd78804a9448bd54ee389c9d
+  metadata.gz: 97eb6aea0ac0e2fd2d5a6e8b5f41b3f7b7600c5a0da646519dea32e957e556081edabb72e1eef7639ed7df7b31e747985d7c87a9425bdb383520fb081dae1f9d
+  data.tar.gz: ba0c3c6772e0d7b60b5403530008b492997b0cdc98b2fe53fb0dcd8fe0b248d6e8439c6dda2689f2b42c4c988e2296e37bd06107db331e643349a380875b0107

data/lib/restforce/db.rb

@@ -35,7 +35,9 @@ require "restforce/db/record_cache"
 require "restforce/db/timestamp_cache"
 require "restforce/db/runner"
 
+require "restforce/db/task"
 require "restforce/db/accumulator"
+require "restforce/db/attacher"
 require "restforce/db/adapter"
 require "restforce/db/associator"
 require "restforce/db/attribute_map"

data/lib/restforce/db/associator.rb

@@ -6,23 +6,14 @@ module Restforce
     # associations have been updated to point to a new Salesforce/database
     # record, and propagate the modification to the opposite system when this
     # occurs.
-    class Associator
-
-      # Public: Initialize a new Restforce::DB::Associator.
-      #
-      # mapping - A Restforce::DB::Mapping instance.
-      # runner  - A Restforce::DB::Runner instance.
-      def initialize(mapping, runner = Runner.new)
-        @mapping = mapping
-        @runner = runner
-      end
+    class Associator < Task
 
       # Public: Run the re-association process, pulling in records from
       # Salesforce and the database to determine the most recently attached
       # association, then propagating the change between systems.
       #
       # Returns nothing.
-      def run
+      def run(*_)
         return if belongs_to_associations.empty?
 
         @runner.run(@mapping) do |run|

data/lib/restforce/db/attacher.rb

@@ -0,0 +1,91 @@
+module Restforce
+
+  module DB
+
+    # Restforce::DB::Attacher is responsible for cleaning up any orphaned
+    # upserted Salesforce records with the database records that they were
+    # originally supposed to be attached to. This allows us to successfully
+    # handle cases where a request timeout or partial failure would otherwise
+    # leave an upserted Salesforce record stranded without a related database
+    # record.
+    class Attacher < Task
+
+      # Public: Run the re-attachment process for any unsynchronized Salesforce
+      # records which have an external upsert ID.
+      #
+      # Returns nothing.
+      def run(*_)
+        return if @mapping.strategy.passive?
+
+        @runner.run(@mapping) do |run|
+          run.salesforce_instances.each { |instance| attach(instance) }
+        end
+      end
+
+      private
+
+      # Internal: Attach the passed Salesforce instance to a related database
+      # record.
+      #
+      # instance - A Restforce::DB::Instances::Salesforce.
+      #
+      # Returns nothing.
+      def attach(instance)
+        synchronization_id = instance.record.SynchronizationId__c
+        return unless synchronization_id
+
+        database_model, record_id = parsed_uuid(synchronization_id)
+        return unless valid_model?(database_model)
+
+        # If the instance is already synchronized, then we just want to wipe the
+        # Synchronization ID and proceed to the next instance.
+        if instance.synced?
+          instance.update!("SynchronizationId__c" => nil)
+          return
+        end
+
+        record = @mapping.database_model.find_by(
+          id: record_id,
+          @mapping.lookup_column => nil,
+        )
+
+        if record
+          attach_to = Instances::ActiveRecord.new(@mapping.database_model, record, @mapping)
+          attach_to.update!(@mapping.lookup_column => instance.id)
+        end
+
+        instance.update!("SynchronizationId__c" => nil)
+      rescue Faraday::Error::ClientError => e
+        DB.logger.error(SynchronizationError.new(e, instance))
+      end
+
+      # Internal: Does the passed database model correspond to the model defined
+      # on the mapping?
+      #
+      # database_model - A String name of an ActiveRecord::Base subclass.
+      #
+      # Returns a Boolean.
+      def valid_model?(database_model)
+        database_model == @mapping.database_model.to_s
+      end
+
+      # Internal: Parse a UUID into a database model and corresponding record
+      # identifier.
+      #
+      # uuid - A String UUID, in the format "<Model>::<Id>"
+      #
+      # Returns an Array of two Strings.
+      def parsed_uuid(uuid)
+        components = uuid.split("::")
+
+        database_model = components[0..-2].join("::")
+        id = components.last
+
+        [database_model, id]
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/cleaner.rb

@@ -5,27 +5,17 @@ module Restforce
     # Restforce::DB::Cleaner is responsible for culling the matching database
     # records when a Salesforce record is no longer available to synchronize
     # for a specific mapping.
-    class Cleaner
+    class Cleaner < Task
 
       # Salesforce can take a few minutes to register record deletion. This
       # buffer gives us a window of time (in seconds) to look back and see
       # records which may not have been visible in previous runs.
       DELETION_READ_BUFFER = 3 * 60
 
-      # Public: Initialize a Restforce::DB::Cleaner.
-      #
-      # mapping - A Restforce::DB::Mapping.
-      # runner  - A Restforce::DB::Runner.
-      def initialize(mapping, runner = Runner.new)
-        @mapping = mapping
-        @strategy = mapping.strategy
-        @runner = runner
-      end
-
       # Public: Run the database culling loop for this mapping.
       #
       # Returns nothing.
-      def run
+      def run(*_)
         @mapping.database_record_type.destroy_all(dropped_salesforce_ids)
       end
 
@@ -61,7 +51,7 @@ module Restforce
       #
       # Returns an Array of IDs.
       def invalid_salesforce_ids
-        return [] if @mapping.conditions.empty? || @strategy.passive?
+        return [] if @mapping.conditions.empty? || @mapping.strategy.passive?
 
         all_salesforce_ids - valid_salesforce_ids
       end

data/lib/restforce/db/collector.rb

@@ -6,16 +6,7 @@ module Restforce
     # 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
-
-      # 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
+    class Collector < Task
 
       # Public: Run the collection process, pulling in records from Salesforce
       # and the database to determine the lists of attributes to apply to all

data/lib/restforce/db/field_processor.rb

@@ -6,6 +6,10 @@ module Restforce
     # information for unwriteable fields from being submitted to Salesforce.
     class FieldProcessor
 
+      # This token indicates that a relationship is being accessed for a
+      # specific field.
+      RELATIONSHIP_MATCHER = /(.+)__r\./.freeze
+
       # Internal: Get a global cache with which to store/fetch the writable
       # fields for each Salesforce SObject Type.
       #
@@ -21,52 +25,84 @@ module Restforce
         @field_cache = {}
       end
 
-      # Public: Get a restricted version of the passed attributes Hash, with
-      # unwritable fields stripped out.
+      # Public: Get a list of valid fields for a specific action from the passed
+      # list of proposed fields. Allows access to related object fields on a
+      # read-only basis.
       #
       # sobject_type - A String name of an SObject Type in Salesforce.
       # attributes   - A Hash with keys corresponding to Salesforce field names.
-      # write_type   - A Symbol reflecting the type of write operation. Accepted
-      #                values are :create and :update. Defaults to :update.
+      # action       - A Symbol reflecting the action to perform. Accepted
+      #                values are :read, :create, and :update.
       #
       # Returns a Hash.
-      def process(sobject_type, attributes, write_type = :update)
-        attributes.each_with_object({}) do |(field, value), processed|
-          next unless writable?(sobject_type, field, write_type)
-          processed[field] = value
+      def available_fields(sobject_type, fields, action = :read)
+        fields.select do |field|
+          known_field = available?(sobject_type, field, action)
+          relationship = action == :read && relationship?(field)
+
+          known_field || relationship
         end
       end
 
+      # Public: Get a restricted version of the passed attributes Hash, with
+      # inaccessible fields for the specified action stripped out.
+      #
+      # sobject_type - A String name of an SObject Type in Salesforce.
+      # attributes   - A Hash with keys corresponding to Salesforce field names.
+      # action       - A Symbol reflecting the action to perform. Accepted
+      #                values are :create and :update.
+      #
+      # Returns a Hash.
+      def process(sobject_type, attributes, action)
+        attributes.select { |field, _| available?(sobject_type, field, action) }
+      end
+
       private
 
-      # Internal: Is the passed attribute writable for the passed SObject Type?
+      # Internal: Is the passed attribute available for the specified action on
+      # the passed SObject Type?
       #
       # sobject_type - A String name of an SObject Type in Salesforce.
       # field        - A String Salesforce field API name.
-      # write_type   - A Symbol reflecting the type of write operation. Accepted
-      #                values are :create and :update.
+      # action       - A Symbol reflecting the requested action. Accepted values
+      #                are :read, :create, and :update.
       #
       # Returns a Boolean.
-      def writable?(sobject_type, field, write_type)
-        permissions = field_permissions(sobject_type)[field]
+      def available?(sobject_type, field, action)
+        permissions = field_metadata(sobject_type)[field]
         return false unless permissions
 
-        permissions[write_type]
+        permissions[action]
+      end
+
+      # Internal: Does the passed field description reference an attribute
+      # through an associated object?
+      #
+      # NOTE: It's not worth the trouble to validate that this relationship
+      # actually exists, or that the requested field exists on the related
+      # model. If a bad lookup is specified, the API will throw an error.
+      #
+      # field - A String Salesforce field API name.
+      #
+      # Rturns a Boolean.
+      def relationship?(field)
+        field =~ RELATIONSHIP_MATCHER
       end
 
       # Internal: Get a collection of all fields for the passed Salesforce
-      # SObject Type, with an indication of whether or not they are writable for
-      # both create and update actions.
+      # SObject Type, with an indication of whether or not they are readable and
+      # writable for both create and update actions.
       #
       # sobject_type - A String name of an SObject Type in Salesforce.
       #
       # Returns a Hash.
-      def field_permissions(sobject_type)
+      def field_metadata(sobject_type)
         self.class.field_cache[sobject_type] ||= begin
           fields = Restforce::DB.client.describe(sobject_type).fields
 
           fields.each_with_object({}) do |field, permissions|
             permissions[field["name"]] = {
+              read:   true,
               create: field["createable"],
               update: field["updateable"],
             }

data/lib/restforce/db/initializer.rb

@@ -6,23 +6,13 @@ module Restforce
     # 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
-        @strategy = mapping.strategy
-        @runner = runner
-      end
+    class Initializer < Task
 
       # Public: Run the initialization loop for this mapping.
       #
       # Returns nothing.
-      def run
-        return if @strategy.passive?
+      def run(*_)
+        return if @mapping.strategy.passive?
 
         @runner.run(@mapping) do |run|
           run.salesforce_instances.each { |instance| create_in_database(instance) }
@@ -40,7 +30,8 @@ module Restforce
       #
       # Returns nothing.
       def create_in_database(instance)
-        return unless @strategy.build?(instance)
+        return unless @mapping.strategy.build?(instance)
+
         created = @mapping.database_record_type.create!(instance)
         @runner.cache_timestamp created
       rescue ActiveRecord::ActiveRecordError => e
@@ -56,6 +47,7 @@ module Restforce
       # Returns nothing.
       def create_in_salesforce(instance)
         return if instance.synced?
+
         created = @mapping.salesforce_record_type.create!(instance)
         @runner.cache_timestamp created
       rescue Faraday::Error::ClientError => e

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

@@ -11,6 +11,7 @@ module Restforce
 
         INTERNAL_ATTRIBUTES = %w(
           Id
+          SynchronizationId__c
           SystemModstamp
           LastModifiedById
         ).freeze
@@ -29,7 +30,7 @@ module Restforce
         # Returns self.
         # Raises if the update fails for any reason.
         def update!(attributes)
-          super FieldProcessor.new.process(@record_type, attributes)
+          super FieldProcessor.new.process(@record_type, attributes, :update)
         end
 
         # Public: Get the time of the last update to this record.

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

@@ -9,6 +9,8 @@ module Restforce
       # attribute mappings.
       class Salesforce < Base
 
+        ALREADY_EXISTS_MESSAGE = /INVALID_FIELD_FOR_INSERT_UPDATE|DUPLICATE_VALUE/.freeze
+
         # Public: Create an instance of this Salesforce model for the passed
         # database record.
         #
@@ -17,24 +19,19 @@ module Restforce
         # Returns a Restforce::DB::Instances::Salesforce instance.
         # Raises on any error from Salesforce.
         def create!(from_record)
-          from_attributes = FieldProcessor.new.process(@record_type, from_record.attributes, :create)
-          record_id = DB.client.upsert!(
-            @record_type,
-            "SynchronizationId__c",
-            from_attributes.merge("SynchronizationId__c" => from_record.uuid),
-          )
+          record_id = upsert!(from_record)
 
           # NOTE: #upsert! returns a String Salesforce ID when a record is
-          # created, or returns `true` when an existing record was found and
-          # updated.
-          if record_id.is_a?(String)
-            from_record.update!(@mapping.lookup_column => record_id).after_sync
-            find(record_id)
-          else
-            instance = first("SynchronizationId__c = '#{from_record.uuid}'")
-            from_record.update!(@mapping.lookup_column => instance.id).after_sync
-            instance
-          end
+          # created, and returns `true` when an existing record was found.
+          instance =
+            if record_id.is_a?(String)
+              find(record_id)
+            else
+              first("SynchronizationId__c = '#{from_record.uuid}'")
+            end
+
+          from_record.update!(@mapping.lookup_column => instance.id)
+          instance.update!("SynchronizationId__c" => nil)
         end
 
         # Public: Find the first Salesforce record which meets the passed
@@ -88,13 +85,43 @@ module Restforce
 
         private
 
-        # Internal: Get a String of values to look up when the record is
+        # Internal: Get a list of fields 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.
+        # Returns an Array of Strings.
         def lookups
-          (Instances::Salesforce::INTERNAL_ATTRIBUTES + @mapping.salesforce_fields).uniq.join(", ")
+          FieldProcessor.new.available_fields(
+            @record_type,
+            (Instances::Salesforce::INTERNAL_ATTRIBUTES + @mapping.salesforce_fields).uniq,
+          )
+        end
+
+        # Internal: Attempt to create a record in Salesforce from the passed
+        # database instance.
+        #
+        # Returns a String or Boolean.
+        def upsert!(from_record)
+          from_attributes = FieldProcessor.new.process(
+            @record_type,
+            from_record.attributes,
+            :create,
+          )
+
+          DB.client.upsert!(
+            @record_type,
+            "SynchronizationId__c",
+            from_attributes.merge("SynchronizationId__c" => from_record.uuid),
+          )
+        rescue Faraday::Error::ClientError => e
+          # If the error is complaining about attempting to update create-only
+          # fields, we've confirmed that the record already exists, and can
+          # safely resolve our object creation.
+          if e.message =~ ALREADY_EXISTS_MESSAGE
+            true
+          else
+            raise e
+          end
         end
 
         # Internal: Has this database record already been linked to a Salesforce
@@ -116,7 +143,7 @@ module Restforce
           filters = (conditions + @mapping.conditions).compact.join(" and ")
           filters = " where #{filters}" unless filters.empty?
 
-          "select #{lookups} from #{@record_type}#{filters}"
+          "select #{lookups.join(', ')} from #{@record_type}#{filters}"
         end
 
       end