parse-stack-next 5.1.1 → 5.2.0

data/lib/parse/model/core/indexing.rb

@@ -56,6 +56,15 @@ module Parse
         _perishable_token _password_history authData _auth_data
       ].freeze
 
+      # Guards the check-then-append in the index registration helpers. Index
+      # declarations happen at class-load time, but an app server that eager-
+      # loads models across multiple threads can otherwise have two threads
+      # both pass the idempotency check on the same (still-empty) array and
+      # append duplicate declarations — producing duplicate `createIndex`
+      # calls at migration time. A single shared mutex is sufficient: this is
+      # not a hot path, so coarse locking trades nothing for correctness.
+      INDEX_REGISTRY_MUTEX = Mutex.new
+
       # Storage for declared indexes. Each entry is a frozen Hash with
       # the keys `:keys`, `:options`, `:declared_for` (the source-of-truth
       # symbol list from the `mongo_index` call, for diagnostics).
@@ -89,6 +98,78 @@ module Parse
                        partial: partial, expire_after: expire_after, name: name)
       end
 
+      # Declare a UNIQUE index on the exact dedup tuple that
+      # `first_or_create!` / `create_or_update!` key on. This is the
+      # *correctness floor* for the synchronize-create race.
+      #
+      # The Redis-backed `synchronize:` lock (see {#first_or_create!}) is a
+      # latency optimization: in the common path it collapses concurrent
+      # callers so only one issues the create. But a lock can be bypassed —
+      # a Redis outage, a TTL expiring between the existence check and the
+      # write, a caller passing `synchronize: false`, or two app servers
+      # whose lock secrets disagree. When that happens, the *database* is the
+      # last line of defense. A unique index guarantees, unconditionally, that
+      # two racing inserts can't both land: the loser fails with DuplicateValue
+      # (Parse error 137), which `first_or_create!` rescues and resolves to the
+      # winning row via `_recover_from_duplicate_value`. Lock + index together
+      # make the net invariant "exactly one row, every caller sees the same id"
+      # hold under any race, not just the happy path.
+      #
+      # This is thin sugar over `mongo_index(*fields, unique: true, ...)` —
+      # it shares the same registration, validation (sensitive-field guard,
+      # pointer auto-rewrite, parallel-array / relation / `_id` rejection),
+      # and `IndexMigrator` apply path. The name states the intent: these
+      # fields form the dedup identity for create-or-update.
+      #
+      # Defaults match `mongo_index`: **non-sparse**. The index key is kept
+      # identical to the query `first_or_create!` re-runs on recovery, so a
+      # 137 always corresponds to a row the recovery query (`_scoped_first`
+      # on the same `query_attrs`) can find. A sparse or partial index that
+      # fires on a condition the recovery query doesn't reproduce would
+      # surface a 137 the rescue can't resolve, and the error would re-raise.
+      # `sparse:` is meaningful only when a document is missing *every* field
+      # in the tuple (a compound sparse index indexes a doc when it has at
+      # least one key); since `first_or_create!` always writes the full tuple,
+      # it never produces such a row, so sparse does not weaken the floor —
+      # leave it off unless out-of-band writers create tuple-less rows you
+      # want excluded.
+      #
+      # @example Single-field dedup floor
+      #   class Account < Parse::Object
+      #     property :email, :string
+      #     unique_index_on :email
+      #   end
+      #   Account.apply_indexes!   # provisions { email: 1 } unique via the writer
+      #
+      # @example Compound tuple with a pointer component
+      #   class Subscription < Parse::Object
+      #     property :email, :string
+      #     belongs_to :tenant, as: :user
+      #     unique_index_on :email, :tenant   # key: { email: 1, _p_tenant: 1 } unique
+      #   end
+      #
+      # @example Unique within a subset (partial filter escape hatch)
+      #   # Unique email per tenant, but rows with no tenant may repeat. You
+      #   # own the filter's lifecycle and must keep first_or_create!'s
+      #   # recovery query consistent with it.
+      #   unique_index_on :email, :tenant,
+      #                   partial: { "_p_tenant" => { "$exists" => true } }
+      #
+      # @param fields [Array<Symbol>] the dedup tuple, in declaration order.
+      #   Pointer fields auto-rewrite to `_p_<field>` like `mongo_index`.
+      # @param sparse [Boolean] default `false`; see the note above on why
+      #   it does not weaken the floor and when it actually changes behavior.
+      # @param partial [Hash, nil] partial-index filter for "unique within a
+      #   subset". Owner-managed; keep it consistent with the recovery query.
+      # @param name [String, nil] explicit index name; defaults to MongoDB
+      #   auto-naming.
+      # @return [Hash] the registered declaration (frozen)
+      # @raise [ArgumentError] same guards as `mongo_index`.
+      # @see #first_or_create!
+      def unique_index_on(*fields, sparse: false, partial: nil, name: nil)
+        mongo_index(*fields, unique: true, sparse: sparse, partial: partial, name: name)
+      end
+
       # Sugar for a 2dsphere geospatial index. Geopoint columns are
       # stored in Mongo as GeoJSON `{ type: "Point", coordinates: [lng, lat] }`
       # which `2dsphere` indexes natively.
@@ -232,13 +313,10 @@ module Parse
           collection:    nil, # nil sentinel means "use the model's parse_class"
         }.freeze
 
-        if mongo_index_declarations.any? { |d| d[:keys] == declaration[:keys] && d[:options] == declaration[:options] && d[:collection] == declaration[:collection] }
-          # Idempotent redeclaration — same class re-opened or sub-class
-          # inherited; don't accumulate duplicates.
-          return declaration
-        end
-        mongo_index_declarations << declaration
-        declaration
+        # Idempotent redeclaration (same class re-opened or sub-class
+        # inherited) is dropped inside the locked append so a duplicate can't
+        # slip through under concurrent class loading.
+        append_index_declaration(declaration)
       end
 
       # Register one direction of a relation index. The declaration
@@ -252,11 +330,7 @@ module Parse
           declared_for: [source].freeze,
           collection:   collection,
         }.freeze
-        if mongo_index_declarations.any? { |d| d[:keys] == decl[:keys] && d[:collection] == collection }
-          return decl
-        end
-        mongo_index_declarations << decl
-        decl
+        append_index_declaration(decl)
       end
 
       # Register the compound `{owningId: 1, relatedId: 1}` unique index
@@ -274,11 +348,29 @@ module Parse
           declared_for: [source].freeze,
           collection:   collection,
         }.freeze
-        if mongo_index_declarations.any? { |d| d[:keys] == decl[:keys] && d[:options] == decl[:options] && d[:collection] == collection }
-          return decl
+        append_index_declaration(decl)
+      end
+
+      # Append an index declaration, dropping an exact-duplicate redeclaration,
+      # under {INDEX_REGISTRY_MUTEX} so concurrent class loading can't race a
+      # duplicate past the idempotency check. Two declarations are duplicates
+      # when their `:keys`, `:options`, and `:collection` all match (relation
+      # declarations carry a frozen `{}` options hash, so this is equivalent to
+      # the prior keys+collection check for those paths).
+      # @return [Hash] the declaration passed in (whether newly stored or a
+      #   dropped duplicate), preserving the previous return contract.
+      def append_index_declaration(declaration)
+        Parse::Core::Indexing::INDEX_REGISTRY_MUTEX.synchronize do
+          decls = (@mongo_index_declarations ||= [])
+          unless decls.any? { |d|
+            d[:keys] == declaration[:keys] &&
+              d[:options] == declaration[:options] &&
+              d[:collection] == declaration[:collection]
+          }
+            decls << declaration
+          end
         end
-        mongo_index_declarations << decl
-        decl
+        declaration
       end
 
       # Translate a property symbol to the wire-format column name a

data/lib/parse/model/core/querying.rb

@@ -368,6 +368,35 @@ module Parse
         query(constraints).distinct(field)
       end
 
+      # Groups records by a field and returns a GroupBy (or SortableGroupBy)
+      # aggregation object you can call .count, .sum, .average, etc. on.
+      # @example
+      #  Post.group_by(:category).count
+      #  Post.group_by(:category, sortable: true).count.sort_by_value_desc
+      # @param field [Symbol, String] the field to group by.
+      # @param opts keyword arguments forwarded to Parse::Query#group_by
+      #   (flatten_arrays:, sortable:, return_pointers:, mongo_direct:).
+      # @return [Parse::GroupBy, Parse::SortableGroupBy]
+      # @see Parse::Query#group_by
+      def group_by(field, **opts)
+        query.group_by(field, **opts)
+      end
+
+      # Groups records by a date field truncated to the given interval and
+      # returns a GroupByDate (or SortableGroupByDate) aggregation object.
+      # @example
+      #  Post.group_by_date(:created_at, :month).count
+      #  Post.group_by_date(:created_at, :day, sortable: true).count.sort_by_value_desc
+      # @param field [Symbol, String] the date field to group by.
+      # @param interval [Symbol] one of :year, :month, :week, :day, :hour, :minute, :second.
+      # @param opts keyword arguments forwarded to Parse::Query#group_by_date
+      #   (sortable:, return_pointers:, timezone:, mongo_direct:).
+      # @return [Parse::GroupByDate, Parse::SortableGroupByDate]
+      # @see Parse::Query#group_by_date
+      def group_by_date(field, interval, **opts)
+        query.group_by_date(field, interval, **opts)
+      end
+
       # Find objects matching the constraint ordered by the descending created_at date.
       # @param constraints (see #all)
       # @return [Array<Parse::Object>]

data/lib/parse/model/model.rb

@@ -77,6 +77,33 @@ module Parse
     CLASS_JOB_SCHEDULE = "_JobSchedule"
     # The internal schema collection in Parse. Managed by Parse Server.
     CLASS_SCHEMA = "_SCHEMA"
+    # Maps the camelized bare name of a Parse Server built-in class to its
+    # leading-underscore storage form. Consulted by {String#to_parse_class}
+    # ONLY as a fallback when {find_class} cannot resolve the name — which
+    # happens at class-declaration time for a built-in whose Ruby class is not
+    # yet registered (e.g. +Parse::Installation+ declares +belongs_to :user+
+    # before +Parse::User+ is loaded). Without this fallback the conversion
+    # froze the wrong literal (+"User"+) into the association +references+ map
+    # and pushed it to the server schema as the pointer +targetClass+, which
+    # Parse Server then rejected (+Pointer<User>+ vs +Pointer<_User>+). A
+    # genuinely-registered class still wins via {find_class}, so a custom
+    # +parse_class+ table mapping is never overridden by this map.
+    # Keys are the camelized bare names (the form {String#to_parse_class}
+    # computes before lookup); only +User+ is actually targeted by a built-in
+    # association before its class registers, the rest are hygiene so an app
+    # that declares a pointer/relation to any built-in resolves correctly
+    # regardless of load order.
+    SYSTEM_CLASS_MAP = {
+      "User" => CLASS_USER,
+      "Role" => CLASS_ROLE,
+      "Session" => CLASS_SESSION,
+      "Installation" => CLASS_INSTALLATION,
+      "Product" => CLASS_PRODUCT,
+      "Audience" => CLASS_AUDIENCE,
+      "PushStatus" => CLASS_PUSH_STATUS,
+      "JobStatus" => CLASS_JOB_STATUS,
+      "JobSchedule" => CLASS_JOB_SCHEDULE,
+    }.freeze
     # The type label for hashes containing file data. Used by Parse::File.
     TYPE_FILE = "File"
     # The type label for hashes containing geopoints. Used by Parse::GeoPoint.
@@ -286,9 +313,13 @@ class String
   def to_parse_class(singularize: false)
     final_class = singularize ? self.singularize.camelize : self.camelize
     klass = Parse::Model.find_class(final_class) || Parse::Model.find_class(self)
-    #handles the case that a class has a custom parse table
-    final_class = klass.parse_class if klass.present?
-    final_class
+    # A registered class wins (handles a custom parse_class table mapping).
+    return klass.parse_class if klass.present?
+    # Fallback: resolve a built-in system class by name even when its Ruby
+    # class is not yet registered (declaration-time load-order). This keeps a
+    # `belongs_to :user` declared before Parse::User loads from freezing the
+    # literal "User" instead of "_User" into the schema targetClass.
+    Parse::Model::SYSTEM_CLASS_MAP[final_class] || final_class
   end
 end
 

data/lib/parse/model/object.rb

@@ -38,6 +38,7 @@ require_relative "core/search_indexing"
 require_relative "core/properties"
 require_relative "core/vector_searchable"
 require_relative "core/embed_managed"
+require_relative "../retrieval"
 require_relative "core/errors"
 require_relative "core/builder"
 require_relative "core/enhanced_change_tracking"

data/lib/parse/query.rb

@@ -69,19 +69,46 @@ module Parse
     include Parse::Client::Connectable
     include Enumerable
 
-    # Known Parse classes for fast validation - dynamically loaded from schema
+    # Built-in Parse classes always considered known, independent of the
+    # server schema. Used both as the seed for the dynamic list and as the
+    # transient fallback when the schema fetch fails.
+    BUILT_IN_PARSE_CLASSES = %w[
+      _User _Role _Session _Installation _Audience
+      User Role Session Installation Audience
+    ].freeze
+
+    # Mutex guarding lazy memoization of {known_parse_classes} so concurrent
+    # first-callers don't each fire a `schemas` request and clobber the cache.
+    @known_parse_classes_mutex = Mutex.new
+
+    # Known Parse classes for fast validation - dynamically loaded from schema.
+    #
+    # The successful result is memoized; a failed schema fetch is NOT cached —
+    # it returns the built-in fallback for this call only, so a transient
+    # server outage during boot doesn't permanently strip every application-
+    # defined class from the known set (which would make class-accessibility
+    # checks reject custom classes for the process lifetime). The narrowed
+    # rescue logs the failure instead of swallowing it silently.
     def self.known_parse_classes
-      @known_parse_classes ||= begin
-          # Get all classes from Parse schema
+      cached = @known_parse_classes
+      return cached if cached
+
+      @known_parse_classes_mutex.synchronize do
+        # Re-check under the lock: a racing caller may have populated it.
+        return @known_parse_classes if @known_parse_classes
+
+        begin
           response = Parse.client.schemas
-          schema_classes = response.success? ? response.result.dig("results")&.map { |cls| cls["className"] } || [] : []
-          # Add built-in Parse classes
-          built_in_classes = %w[_User _Role _Session _Installation _Audience User Role Session Installation Audience]
-          (built_in_classes + schema_classes).uniq.freeze
-        rescue
-          # Fallback to built-in classes if schema query fails (e.g., during testing without server)
-          %w[_User _Role _Session _Installation _Audience User Role Session Installation Audience].freeze
+          schema_classes = response.success? ? response.results.map { |cls| cls["className"] } : []
+          @known_parse_classes = (BUILT_IN_PARSE_CLASSES + schema_classes).uniq.freeze
+        rescue Parse::Error, Faraday::Error => e
+          # Don't cache the fallback — let the next call retry the fetch once
+          # the server is reachable again.
+          warn "[Parse::Query] schema fetch failed (#{e.class}: #{e.message}); " \
+               "falling back to built-in classes for this check only."
+          BUILT_IN_PARSE_CLASSES
         end
+      end
     end
 
     # Allow resetting the cached known classes (useful for testing)
@@ -2564,6 +2591,26 @@ module Parse
     def convert_constraints_for_direct_mongodb(constraints)
       return constraints unless constraints.is_a?(Hash)
 
+      # $relatedTo resolves a Parse Relation, which is stored in the
+      # `_Join:<key>:<ParentClass>` collection — a join the SDK does NOT
+      # translate on the mongo-direct path. Passed through verbatim it reaches
+      # MongoDB as an unknown `$match` operator and fails with an opaque error;
+      # and any future attempt to rewrite it into a `$lookup` would have to
+      # re-implement the `_rperm` / protectedFields enforcement that the rest of
+      # this path applies post-fetch. Parse Server's own `$relatedTo` was found
+      # to bypass exactly that enforcement (GHSA-wmwx-jr2p-4j4r), so fail closed
+      # here with a clear message rather than risk a silent leak: this query
+      # must run via REST (the default), where Parse Server resolves the
+      # relation under its own ACL / CLP enforcement.
+      if constraints.key?("$relatedTo") || constraints.key?(:"$relatedTo")
+        raise ArgumentError,
+          "[Parse::Query] $relatedTo cannot run on the mongo-direct path; a " \
+          "Parse Relation is resolved server-side via its join collection. Run " \
+          "this query via REST (omit `mongo_direct:` / `.results_direct` and any " \
+          "direct-only constraint), or express the membership as an `$inQuery` " \
+          "against the relation's join collection."
+      end
+
       result = {}
       constraints.each do |field, value|
         field_str = field.to_s
@@ -6284,8 +6331,10 @@ module Parse
     include Enumerable
 
     # @param results [Hash] the grouped results hash
-    def initialize(results)
+    # @param operation [String, nil] the aggregation operation (e.g. "count", "sum", "average", "min", "max", "list")
+    def initialize(results, operation = nil)
       @results = results
+      @operation = operation
     end
 
     # Return the raw hash results
@@ -6332,12 +6381,15 @@ module Parse
 
     # Convert grouped results to a formatted table.
     # @param format [Symbol] output format (:ascii, :csv, :json)
-    # @param headers [Array<String>] custom headers (default: ["Group", "Count"])
+    # @param headers [Array<String>, nil] custom headers; if nil, defaults to ["Group", <op-derived header>]
+    #   where the second header reflects the aggregation operation (e.g. "Average" for avg/average,
+    #   "Sum" for sum, "Min"/"Max" for min/max, "Items" for list, "Count" otherwise).
     # @return [String] formatted table
     # @example
     #   Document.group_by(:category, sortable: true).count.to_table
     #   Document.group_by(:category).sum(:file_size).to_table(headers: ["Category", "Total Size"])
-    def to_table(format: :ascii, headers: ["Group", "Count"])
+    def to_table(format: :ascii, headers: nil)
+      headers ||= ["Group", default_value_header]
       pairs = @results.to_a
 
       # Build table data
@@ -6361,6 +6413,20 @@ module Parse
 
     private
 
+    # Derive a human-readable column header from the aggregation operation.
+    # @return [String] the default second-column header
+    def default_value_header
+      case @operation&.to_s
+      when "count"    then "Count"
+      when "sum"      then "Sum"
+      when "average", "avg" then "Average"
+      when "min"      then "Min"
+      when "max"      then "Max"
+      when "list"     then "Items"
+      else                 "Count"
+      end
+    end
+
     # Format group key for display
     def format_group_key(key)
       case key
@@ -6453,7 +6519,7 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def count
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "count")
     end
 
     # Sum a field for each group.
@@ -6461,7 +6527,7 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def sum(field)
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "sum")
     end
 
     # Calculate average of a field for each group.
@@ -6469,7 +6535,7 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def average(field)
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "average")
     end
 
     alias_method :avg, :average
@@ -6479,7 +6545,7 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def min(field)
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "min")
     end
 
     # Find maximum value of a field for each group.
@@ -6487,14 +6553,14 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def max(field)
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "max")
     end
 
     # Collect Parse::Object instances per group.
     # @return [GroupedResult] a sortable result object.
     def list
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "list")
     end
   end
 
@@ -7091,7 +7157,7 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def count
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "count")
     end
 
     # Sum a field for each time period.
@@ -7099,7 +7165,7 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def sum(field)
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "sum")
     end
 
     # Calculate average of a field for each time period.
@@ -7107,7 +7173,7 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def average(field)
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "average")
     end
 
     alias_method :avg, :average
@@ -7117,7 +7183,7 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def min(field)
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "min")
     end
 
     # Find maximum value of a field for each time period.
@@ -7125,7 +7191,7 @@ module Parse
     # @return [GroupedResult] a sortable result object.
     def max(field)
       results = super
-      GroupedResult.new(results)
+      GroupedResult.new(results, "max")
     end
   end
 end # Parse