Add partial fetch controls and error handling

Introduces methods to disable, enable, and check autofetch on Parse objects, and adds UnfetchedFieldAccessError for unfetched field access when autofetch is disabled. Improves partial fetch state management, deepens nested key parsing, and adds extensive unit tests for partial fetch functionality.

Author: AdrianCurtin

CHANGELOG.md

@@ -16,6 +16,23 @@
 - **IMPROVED**: Before-save hooks can now reliably access unfetched fields (triggers autofetch)
 - **IMPROVED**: Saving partially fetched objects only updates actually changed fields, not default values
 
+#### Code Quality & Security Improvements
+- **NEW**: `disable_autofetch!` method to prevent automatic network requests on an instance
+- **NEW**: `enable_autofetch!` method to re-enable autofetch
+- **NEW**: `autofetch_disabled?` method to check if autofetch is disabled
+- **NEW**: `clear_partial_fetch_state!` public method for clearing partial fetch tracking
+- **NEW**: `Parse::UnfetchedFieldAccessError` raised when accessing unfetched fields with autofetch disabled
+- **FIXED**: Inconsistent state in `build` - both `nested_fetched_keys` and `fetched_keys` now set before `initialize`
+- **FIXED**: Deep nesting support - `parse_includes_to_nested_keys` now handles arbitrary depth (e.g., `a.b.c.d`)
+- **FIXED**: String/symbol mismatch in `field_was_fetched?` - remote_key now converted to symbol
+- **IMPROVED**: `fetched_keys` getter returns frozen duplicate to prevent external mutation
+- **IMPROVED**: Autofetch prevented during `apply_defaults!` when object is partially fetched
+- **IMPROVED**: Info-level logging when autofetch is triggered (shows class, id, and field that triggered fetch)
+
+#### Testing
+- **NEW**: 34 unit tests for partial fetch functionality (no Docker required)
+- **NEW**: 18 integration tests for partial fetch with real Parse Server
+
 ### 2.0.9
 
 - **FIXED**: `Query#where` method now routes through `conditions` to properly handle special keywords like `keys:`, `include:`, `limit:`, etc. when chaining (e.g., `Model.query.where(keys: [...])`)

lib/parse/model/core/actions.rb

@@ -723,11 +723,13 @@ def save(session: nil, autoraise: false, force: false)
               success = update_relations
               if success
                 changes_applied!
+                clear_partial_fetch_state!
               elsif self.class.raise_on_save_failure || autoraise.present?
                 raise Parse::RecordNotSaved.new(self), "Failed updating relations. #{self.parse_class} partially saved."
               end
             else
               changes_applied!
+              clear_partial_fetch_state!
             end
           elsif self.class.raise_on_save_failure || autoraise.present?
             raise Parse::RecordNotSaved.new(self), "Failed to create or save attributes. #{self.parse_class} was not saved."

lib/parse/model/core/errors.rb

@@ -5,4 +5,17 @@
 module Parse
   # An abstract parent class for all Parse::Error types.
   class Error < StandardError; end
+
+  # Raised when attempting to access a field that was not fetched on a partially
+  # fetched object when autofetch has been disabled.
+  class UnfetchedFieldAccessError < Error
+    attr_reader :field_name, :object_class
+
+    def initialize(field_name, object_class)
+      @field_name = field_name
+      @object_class = object_class
+      super("Attempted to access unfetched field '#{field_name}' on #{object_class} with autofetch disabled. " \
+            "Either fetch the object first, include this field in the keys parameter, or enable autofetch.")
+    end
+  end
 end

lib/parse/model/core/fetching.rb

@@ -91,9 +91,16 @@ def autofetch!(key)
         key = key.to_sym
         @fetch_lock ||= false
         # Autofetch if object is a pointer OR was partially fetched
+        # Skip if autofetch is disabled for this instance
         needs_fetch = pointer? || partially_fetched?
-        if @fetch_lock != true && needs_fetch && key != :acl && Parse::Properties::BASE_KEYS.include?(key) == false && respond_to?(:fetch)
-          #puts "AutoFetching Triggerd by: #{self.class}.#{key} (#{id})"
+        can_fetch = @fetch_lock != true && !autofetch_disabled? && needs_fetch && key != :acl && Parse::Properties::BASE_KEYS.include?(key) == false && respond_to?(:fetch)
+        if can_fetch
+          # Log info about autofetch being triggered
+          if partially_fetched?
+            puts "[Parse::Autofetch] Fetching #{self.class}##{id} - field :#{key} was not included in partial fetch"
+          else
+            puts "[Parse::Autofetch] Fetching #{self.class}##{id} - pointer accessed field :#{key}"
+          end
           @fetch_lock = true
           send :fetch
           @fetch_lock = false

lib/parse/model/core/properties.rb

@@ -277,6 +277,11 @@ def property(key, data_type = :string, **opts)
           # Also autofetch if object was partially fetched and this field wasn't included.
           should_autofetch = value.nil? && (pointer? || (partially_fetched? && !field_was_fetched?(key)))
           if should_autofetch
+            # If autofetch is disabled and we're accessing an unfetched field on a
+            # partially fetched object, raise an error to make the issue explicit
+            if autofetch_disabled? && partially_fetched? && !field_was_fetched?(key)
+              raise Parse::UnfetchedFieldAccessError.new(key, self.class.name)
+            end
             # call autofetch to fetch the entire record
             # and then get the ivar again cause it might have been updated.
             autofetch!(key)

lib/parse/model/object.rb

@@ -313,7 +313,12 @@ def initialize(opts = {})
 
       # do not apply defaults on a pointer because it will stop it from being
       # a pointer and will cause its field to be autofetched (for sync)
-      apply_defaults! unless pointer?
+      # Use fetch_lock to prevent autofetch during default application when partially fetched
+      if !pointer?
+        @fetch_lock = true if partially_fetched?
+        apply_defaults!
+        @fetch_lock = false
+      end
 
       # clear changes AFTER applying defaults, so fields set by defaults
       # are not marked dirty when fetching with specific keys
@@ -388,14 +393,34 @@ def existed?
     # When partially fetched, accessing unfetched fields will trigger an autofetch.
     # @return [Boolean] true if the object was fetched with specific keys.
     def partially_fetched?
-      @_fetched_keys.present? && @_fetched_keys.any?
+      @_fetched_keys&.any? || false
     end
 
     # Returns the array of keys that were fetched for this object.
     # Empty array means the object was fully fetched.
+    # Returns a frozen duplicate to prevent external mutation.
     # @return [Array<Symbol>] the keys that were fetched.
     def fetched_keys
-      @_fetched_keys || []
+      (@_fetched_keys || []).dup.freeze
+    end
+
+    # Disables autofetch for this object instance.
+    # Useful for preventing automatic network requests.
+    # @return [void]
+    def disable_autofetch!
+      @_autofetch_disabled = true
+    end
+
+    # Enables autofetch for this object instance (default behavior).
+    # @return [void]
+    def enable_autofetch!
+      @_autofetch_disabled = false
+    end
+
+    # Returns whether autofetch is disabled for this instance.
+    # @return [Boolean] true if autofetch is disabled
+    def autofetch_disabled?
+      @_autofetch_disabled == true
     end
 
     # Sets the fetched keys for this object. Used internally when building
@@ -429,8 +454,9 @@ def field_was_fetched?(key)
       return true if key == :acl || key == :ACL
 
       # Check both local key and remote field name
-      remote_key = self.field_map[key]
-      fetched_keys.include?(key) || (remote_key && fetched_keys.include?(remote_key))
+      # Convert remote_key to symbol for consistent comparison
+      remote_key = self.field_map[key]&.to_sym
+      @_fetched_keys.include?(key) || (remote_key && @_fetched_keys.include?(remote_key))
     end
 
     # Returns the nested fetched keys map for building nested objects.
@@ -455,6 +481,14 @@ def nested_keys_for(field_name)
       @_nested_fetched_keys[field_name]
     end
 
+    # Clears all partial fetch tracking state.
+    # Called after successful save since server returns updated object.
+    # @return [void]
+    def clear_partial_fetch_state!
+      @_fetched_keys = nil
+      @_nested_fetched_keys = nil
+    end
+
     # Run after_create callbacks for this object.
     # This method is called by webhook handlers when an object is created.
     # @return [Boolean] true if callbacks executed successfully
@@ -577,11 +611,20 @@ def self.build(json, table = nil, fetched_keys: nil, nested_fetched_keys: nil)
         # when creating objects from Parse JSON data, don't use dirty tracking since
         # we are considering these objects as "pristine"
         o = klass.allocate
-        # Set nested fetched keys BEFORE apply_attributes! so nested objects can use them
+
+        # Set BOTH nested_fetched_keys AND fetched_keys BEFORE initialize
+        # to ensure partially_fetched? returns correct value during attribute application
         o.instance_variable_set(:@_nested_fetched_keys, nested_fetched_keys) if nested_fetched_keys.present?
+        if fetched_keys.present?
+          # Process fetched_keys like the setter does - convert to symbols and include :id
+          processed_keys = fetched_keys.map { |k| Parse::Query.format_field(k).to_sym }
+          processed_keys << :id unless processed_keys.include?(:id)
+          processed_keys << :objectId unless processed_keys.include?(:objectId)
+          processed_keys.uniq!
+          o.instance_variable_set(:@_fetched_keys, processed_keys)
+        end
+
         o.send(:initialize, json)
-        # Set fetched keys for partial fetch tracking
-        o.fetched_keys = fetched_keys if fetched_keys.present?
       else
         o = Parse::Pointer.new className, (json[Parse::Model::OBJECT_ID] || json[:objectId])
       end

lib/parse/query.rb

@@ -1385,8 +1385,9 @@ def decode(list)
     end
 
     # Parses include patterns to build a map of nested fetched keys.
-    # For example, ["team.time_zone", "team.name", "author"] becomes:
-    # { team: [:time_zone, :name], author: [] }
+    # Handles arbitrary nesting depth (e.g., "a.b.c.d" creates entries for a, b, c).
+    # For example, ["team.time_zone", "team.name", "author", "team.manager.email"] becomes:
+    # { team: [:time_zone, :name, :manager], author: [], manager: [:email] }
     # @param includes [Array<Symbol>] the include patterns
     # @return [Hash] a map of nested field names to their fetched keys
     def parse_includes_to_nested_keys(includes)
@@ -1398,25 +1399,16 @@ def parse_includes_to_nested_keys(includes)
         parts = include_path.to_s.split('.')
         next if parts.empty?
 
-        # First part is the field name on the parent object
-        field_name = parts.first.to_sym
-
-        # Initialize the array for this field if not already
-        nested_map[field_name] ||= []
-
-        # If there are more parts, they are fields on the nested object
-        if parts.length > 1
-          nested_field = parts[1].to_sym
-          nested_map[field_name] << nested_field unless nested_map[field_name].include?(nested_field)
-
-          # Handle deeper nesting (e.g., team.manager.name)
-          if parts.length > 2
-            # For now, we'll create a key for the second level too
-            # This would need recursive handling for deeper nesting
-            second_level_field = parts[1].to_sym
-            nested_map[second_level_field] ||= []
-            nested_field = parts[2].to_sym
-            nested_map[second_level_field] << nested_field unless nested_map[second_level_field].include?(nested_field)
+        # Process each level of nesting
+        # For path "a.b.c.d": a gets b, b gets c, c gets d
+        parts.each_with_index do |part, index|
+          field_name = part.to_sym
+          nested_map[field_name] ||= []
+
+          # If there's a next part, add it to this field's nested keys
+          if index < parts.length - 1
+            next_field = parts[index + 1].to_sym
+            nested_map[field_name] << next_field unless nested_map[field_name].include?(next_field)
           end
         end
       end