parse-stack-next 5.7.5 → 5.8.0

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

@@ -621,6 +621,13 @@ module Parse
           ambient = Parse.current_session_token
           client_opts[:session_token] = ambient if ambient.is_a?(String) && !ambient.empty?
         end
+        # Inside `Parse.with_session(nil)` the caller is anonymous. A worker
+        # thread may not see that fiber state, so carry it explicitly rather
+        # than letting the worker fall back to the master key.
+        if !client_opts.key?(:session_token) && !client_opts.key?(:use_master_key) &&
+           Parse.respond_to?(:anonymous_session?) && Parse.anonymous_session?
+          client_opts[:use_master_key] = false
+        end
 
         if type == :batch
           # use a .in query with the given id as a list

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

@@ -21,7 +21,7 @@ module Parse
           result = { type: v.to_s.camelize }
           # if it is a basic column property, find the right datatype
           case v
-          when :integer, :float
+          when :integer, :float, :number
             result[:type] = Parse::Model::TYPE_NUMBER
           when :geopoint, :geo_point
             result[:type] = Parse::Model::TYPE_GEOPOINT
@@ -31,8 +31,10 @@ module Parse
             result = { type: Parse::Model::TYPE_POINTER, targetClass: references[k] }
           when :acl
             result[:type] = Parse::Model::ACL
-          when :timezone, :time_zone
-            result[:type] = "String" # no TimeZone native in Parse
+          when :timezone, :time_zone, :phone, :email
+            result[:type] = "String" # no native Parse column type
+          when :vector
+            result[:type] = "Array" # embeddings are stored as a number array
           else
             result[:type] = v.to_s.camelize
           end

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

@@ -104,6 +104,12 @@ module Parse
           type: type_str,
         }.freeze
 
+        if generated_vector_search_indexes.any? { |e| e[:name] == name_str }
+          raise ArgumentError,
+                "#{self}.mongo_search_index #{name_str.inspect} is already declared by " \
+                "vector_search_index. Each name may have one declaration per class."
+        end
+
         existing = mongo_search_index_declarations.find { |d| d[:name] == name_str }
         if existing
           # Idempotent redeclaration with identical content — common in
@@ -123,6 +129,63 @@ module Parse
         declaration
       end
 
+      # Declare a vectorSearch index whose definition is GENERATED from the
+      # model's declarations by {Parse::VectorSearch::IndexDefinition.build}
+      # (vector path, dimensions, similarity, quantization, agent_searchable
+      # filter fields, agent_tenant_scope field), instead of written by hand.
+      #
+      # The definition is computed when the migrator plans, not at class
+      # load, so `agent_searchable` / `agent_tenant_scope` may be declared in
+      # any order. Nothing is applied until {#apply_search_indexes!} runs.
+      #
+      # @param name [String] the search index name ({INDEX_NAME_PATTERN}).
+      # @param field [Symbol, nil] the `:vector` property; may be omitted
+      #   when the class has exactly one searchable vector.
+      # @return [Hash] the registered `{ name:, field: }` entry (frozen).
+      # @raise [ArgumentError] on a bad name, or a name already declared
+      #   with a different field or via {#mongo_search_index}.
+      def vector_search_index(name, field: nil)
+        name_str = name.to_s
+        unless name_str.match?(INDEX_NAME_PATTERN)
+          raise ArgumentError,
+                "#{self}.vector_search_index name #{name.inspect} must match #{INDEX_NAME_PATTERN.inspect}"
+        end
+        if mongo_search_index_declarations.any? { |d| d[:name] == name_str }
+          raise ArgumentError,
+                "#{self}.vector_search_index #{name_str.inspect} is already declared by " \
+                "mongo_search_index. Each name may have one declaration per class."
+        end
+        entry = { name: name_str, field: field&.to_sym }.freeze
+        existing = generated_vector_search_indexes.find { |e| e[:name] == name_str }
+        if existing
+          return existing if existing == entry
+          raise ArgumentError,
+                "#{self}.vector_search_index #{name_str.inspect} re-declared for a different field."
+        end
+        generated_vector_search_indexes << entry
+        entry
+      end
+
+      # @return [Array<Hash>] `{ name:, field: }` entries registered by
+      #   {#vector_search_index}.
+      def generated_vector_search_indexes
+        @generated_vector_search_indexes ||= []
+      end
+
+      # Materialize {#generated_vector_search_indexes} into migrator
+      # declarations (`{ name:, definition:, type: "vectorSearch" }`),
+      # generating each definition from the current model declarations.
+      # @return [Array<Hash>]
+      def generated_vector_search_index_declarations
+        generated_vector_search_indexes.map do |entry|
+          {
+            name: entry[:name],
+            definition: Parse::VectorSearch::IndexDefinition.build(self, field: entry[:field]),
+            type: "vectorSearch",
+          }.freeze
+        end
+      end
+
       # Dry-run reconciliation between declared search indexes and what
       # exists on Atlas. Delegates to {Parse::Schema::SearchIndexMigrator}.
       # @return [Hash] see {Parse::Schema::SearchIndexMigrator#plan}

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

@@ -225,7 +225,7 @@ module Parse
 
         raw_hits = Parse::VectorSearch.search(
           parse_class,
-          field: resolved_field,
+          field: vector_storage_path(resolved_field),
           query_vector: query_vector,
           k: k,
           num_candidates: num_candidates,
@@ -318,7 +318,7 @@ module Parse
             filter: lex[:filter], fuzzy: lex[:fuzzy],
           },
           vector: {
-            query_vector: qv, field: field_sym, index: vector_index,
+            query_vector: qv, field: vector_storage_path(field_sym), index: vector_index,
             num_candidates: vec[:num_candidates], filter: vec[:filter],
             vector_filter: vec[:vector_filter],
             candidate_limit: vec[:candidate_limit],
@@ -332,6 +332,22 @@ module Parse
         build_hybrid_hits(fused)
       end
 
+      # The column a `:vector` property is stored under, which is what an
+      # Atlas index path and a `$vectorSearch` path must name: the property's
+      # `field_map` entry (an explicit `field:` alias, or the lowerCamelCase
+      # form of the Ruby name). `property :body_embedding, :vector` is saved
+      # as `bodyEmbedding`. Before 5.8 the SDK searched, discovered, and
+      # drift-checked indexes by the Ruby name, so a multi-word vector
+      # property matched no vectors.
+      #
+      # @param field [Symbol, String] the `:vector` property's Ruby name.
+      # @return [String]
+      def vector_storage_path(field)
+        sym = field.to_sym
+        fmap = respond_to?(:field_map) ? field_map : {}
+        (fmap[sym] || sym.to_s.columnize).to_s
+      end
+
       private
 
       def resolve_vector_field!(field)
@@ -450,7 +466,7 @@ module Parse
                 "#{self}.find_similar: no index: given and Parse::AtlasSearch " \
                 "could not be loaded; pass an explicit index: kwarg."
         end
-        idx = Parse::AtlasSearch::IndexCatalog.find_vector_index(parse_class, field: field)
+        idx = Parse::AtlasSearch::IndexCatalog.find_vector_index(parse_class, field: vector_storage_path(field))
         if idx.nil?
           raise IndexNotResolved,
                 "#{self}.find_similar: no vectorSearch index found covering " \
@@ -473,7 +489,7 @@ module Parse
         return if Parse::VectorSearch.index_drift_policy == :ignore
         begin
           require_relative "../../atlas_search"
-          idx = Parse::AtlasSearch::IndexCatalog.find_vector_index(parse_class, field: field)
+          idx = Parse::AtlasSearch::IndexCatalog.find_vector_index(parse_class, field: vector_storage_path(field))
         rescue StandardError, LoadError
           return
         end
@@ -497,7 +513,9 @@ module Parse
       #    property's declared `dimensions:`.
       # 2. `similarity` vs the property's declared `similarity:` (only
       #    when both sides declare one).
-      # 3. When the class registers an `agent_tenant_scope`, the scope
+      # 3. `quantization` vs the property's declared `quantization:`
+      #    (absent on either side means none).
+      # 4. When the class registers an `agent_tenant_scope`, the scope
       #    field must appear among the index's `type: "filter"` paths —
       #    otherwise the tenant pre-filter that
       #    {Parse::Retrieval.retrieve} folds into `$vectorSearch.filter`
@@ -530,7 +548,7 @@ module Parse
       def vector_index_drift_findings(field, idx)
         defn = idx["latestDefinition"] || idx[:latestDefinition] || {}
         entries = defn["fields"] || defn[:fields] || []
-        field_str = field.to_s
+        field_str = vector_storage_path(field)
         vector_entry = entries.find do |f|
           (f["type"] || f[:type]).to_s == "vector" && (f["path"] || f[:path]).to_s == field_str
         end
@@ -552,6 +570,17 @@ module Parse
                       "similarity: #{declared_sim.inspect}"
         end
 
+        # Quantization is compared both ways: an index quantized without a
+        # declaration, or a declaration the index does not carry, is drift.
+        # An absent value means none on either side.
+        declared_q = vector_properties.dig(field.to_sym, :quantization)&.to_s || "none"
+        index_q = (vector_entry["quantization"] || vector_entry[:quantization]).to_s
+        index_q = "none" if index_q.empty?
+        if declared_q != index_q
+          findings << "index quantization=#{index_q.inspect} but property declares " \
+                      "quantization: #{declared_q == "none" ? "none" : declared_q.inspect}"
+        end
+
         scope_field = registered_tenant_scope_field
         if scope_field
           filter_paths = entries.select { |f| (f["type"] || f[:type]).to_s == "filter" }

data/lib/parse/model/file.rb

@@ -703,7 +703,13 @@ module Parse
     # @param contents [Object]
     # @param mime_type [String] Default see default_mime_type
     def initialize(name, contents = nil, mime_type = nil)
-      mime_type ||= Parse::File.default_mime_type
+      # The default mime type applies only to content this instance will
+      # upload. A file hydrated from a server hash or copied from another
+      # Parse::File describes an existing upload whose type is not known
+      # here, so it keeps an explicit mime_type or the source's, never a
+      # guessed "image/jpeg".
+      hydrated = name.is_a?(Hash) || name.is_a?(Parse::File)
+      mime_type ||= hydrated ? nil : Parse::File.default_mime_type
 
       if name.is_a?(String) && name.start_with?("http") #could be url string
         file = Parse::File.safe_open_url(name)
@@ -717,6 +723,7 @@ module Parse
         @name = File.basename name.to_path
       elsif name.is_a?(Parse::File)
         @name = name.name
+        @mime_type = name.mime_type
         # Route through the single URL normalization point so the copy
         # gets the same strip + stash treatment as a caller-side
         # `url=`. Preserve the source's presigned-URL stash
@@ -1088,7 +1095,7 @@ module Parse
     def inspect
       url_state = @url.present? ? "set" : "blank"
       "<Parse::File @name=#{@name.inspect} @mime_type=#{@mime_type.inspect} " \
-      "@contents=#{@contents.nil?} @url=#{url_state}>"
+      "@contents=#{!@contents.nil?} @url=#{url_state}>"
     end
 
     # @return [String] the url

data/lib/parse/model/geopoint.rb

@@ -53,29 +53,68 @@ module Parse
 
     alias_method :__type, :parse_class
 
-    # The initializer can create a GeoPoint with a hash, array or values.
+    # The initializer can create a GeoPoint with a hash, array, keyword
+    # arguments or values.
     # @example
     #  san_diego = Parse::GeoPoint.new(32.8233, -117.6542)
     #  san_diego = Parse::GeoPoint.new [32.8233, -117.6542]
-    #  san_diego = Parse::GeoPoint.new { latitude: 32.8233, longitude: -117.6542}
+    #  san_diego = Parse::GeoPoint.new({ latitude: 32.8233, longitude: -117.6542 })
+    #  san_diego = Parse::GeoPoint.new(lat: 32.8233, lng: -117.6542)
+    #  san_diego = Parse::GeoPoint.new(latitude: 32.8233, longitude: -117.6542)
+    #
+    # Coordinates may be Numerics or numeric Strings. A value that is not a
+    # finite number (for example `"abc"`, `nil` inside a pair, NaN) raises
+    # ArgumentError rather than silently becoming 0.0, which would place the
+    # point at (0, 0) and corrupt geo queries.
     #
     # @param latitude [Numeric] The latitude value between LAT_MIN and LAT_MAX.
     # @param longitude [Numeric] The longitude value between LNG_MIN and LNG_MAX.
-    def initialize(latitude = nil, longitude = nil)
+    # @param coords [Hash] keyword form: `lat:`/`lng:` or `latitude:`/`longitude:`.
+    # @raise ArgumentError if a coordinate is not a finite number.
+    def initialize(latitude = nil, longitude = nil, **coords)
       @latitude = @longitude = 0.0
-      if latitude.is_a?(Hash) || latitude.is_a?(Array)
+      if coords.any?
+        unless latitude.nil? && longitude.nil?
+          raise ArgumentError, "[Parse::GeoPoint] pass either positional or keyword coordinates, not both."
+        end
+        self.attributes = coords
+      elsif latitude.is_a?(Hash) || latitude.is_a?(Array)
         self.attributes = latitude
-      elsif latitude.is_a?(Numeric) && longitude.is_a?(Numeric)
-        @latitude = latitude
-        @longitude = longitude
       elsif latitude.is_a?(GeoPoint)
         @latitude = latitude.latitude
         @longitude = latitude.longitude
+      elsif latitude.is_a?(String) && longitude.nil?
+        # "lat,lng" string form.
+        parts = latitude.split(",")
+        unless parts.length == 2
+          raise ArgumentError, "[Parse::GeoPoint] cannot build a GeoPoint from #{latitude.inspect}."
+        end
+        self.attributes = parts
+      elsif !latitude.nil? || !longitude.nil?
+        @latitude = self.class.coerce_coordinate(latitude, :latitude)
+        @longitude = self.class.coerce_coordinate(longitude, :longitude)
       end
 
       _validate_point
     end
 
+    # Convert a single coordinate to a Float.
+    # @param value [Numeric, String] the coordinate.
+    # @param name [Symbol] the coordinate name, for the error message.
+    # @return [Float]
+    # @raise ArgumentError when the value is not a finite number.
+    # @!visibility private
+    def self.coerce_coordinate(value, name)
+      num = case value
+            when Numeric then value.to_f
+            when String then Float(value.strip, exception: false)
+            end
+      unless num.is_a?(Float) && num.finite?
+        raise ArgumentError, "[Parse::GeoPoint] #{name} must be a finite number (got #{value.inspect})."
+      end
+      num
+    end
+
     # @!visibility private
     def _validate_point
       unless @latitude.nil? || @latitude.between?(LAT_MIN, LAT_MAX)
@@ -134,15 +173,24 @@ module Parse
     end
 
     # Setting lat and lng for an GeoPoint can be done using a hash with the attributes set
-    # or with an array of two items where the first is the lat and the second is the lng (ex. [32.22,-118.81])
+    # or with an array of two items where the first is the lat and the second is the lng (ex. [32.22,-118.81]).
+    # Hash keys may be `latitude`/`longitude` or `lat`/`lng`, as Symbols or
+    # Strings. A coordinate missing from the hash keeps its current value.
+    # @raise ArgumentError when a supplied coordinate is not a finite number,
+    #   or an Array does not hold exactly two coordinates.
     def attributes=(h)
       if h.is_a?(Hash)
         h = h.symbolize_keys
-        @latitude = h[:latitude].to_f || h[:lat].to_f || @latitude
-        @longitude = h[:longitude].to_f || h[:lng].to_f || @longitude
-      elsif h.is_a?(Array) && h.count == 2
-        @latitude = h.first.to_f
-        @longitude = h.last.to_f
+        lat = h.key?(:latitude) ? h[:latitude] : h[:lat]
+        lng = h.key?(:longitude) ? h[:longitude] : h[:lng]
+        @latitude = self.class.coerce_coordinate(lat, :latitude) unless lat.nil?
+        @longitude = self.class.coerce_coordinate(lng, :longitude) unless lng.nil?
+      elsif h.is_a?(Array)
+        unless h.count == 2
+          raise ArgumentError, "[Parse::GeoPoint] expects [latitude, longitude] (got #{h.inspect})."
+        end
+        @latitude = self.class.coerce_coordinate(h.first, :latitude)
+        @longitude = self.class.coerce_coordinate(h.last, :longitude)
       end
       _validate_point
     end

data/lib/parse/model/model.rb

@@ -136,10 +136,124 @@ module Parse
     # the SDK (see Parse::ACLScope `@no_acl_warned`).
     @model_cache = {}
     @model_cache_mutex = Mutex.new
+    # Class names {find_class} looked up and did not find. A miss otherwise
+    # rescans every descendant on each call (a query on a class with no Ruby
+    # model hits this on every build). Cleared by {model_registry_changed!}.
+    @model_cache_misses = {}
+    MODEL_CACHE_MISSES_MAX = 10_000
+    # Bumped whenever the set of models, a model's `parse_class`, or a model's
+    # declared fields change, so derived per-class caches (such as the
+    # query field-alias cache) know to rebuild.
+    @model_generation = 0
 
     class << self
       # @!visibility private
-      attr_reader :model_cache, :model_cache_mutex
+      attr_reader :model_cache, :model_cache_mutex, :model_cache_misses
+      # @!visibility private
+      # Anonymous Parse::Object descendants seen by the last missed
+      # {find_class} scan. Guarded by {model_cache_mutex}.
+      attr_accessor :model_anonymous_descendants
+      # @!visibility private
+      # @return [Integer] the current model registry generation.
+      attr_reader :model_generation
+
+      # @!visibility private
+      # Record that a model was defined, renamed with `parse_class`, or had a
+      # field declared. Clears the {find_class} miss cache and advances
+      # {model_generation}.
+      def model_registry_changed!
+        model_cache_mutex.synchronize do
+          # Hits are cleared too: a model redefined after `remove_const`
+          # (a code reload, or a test) must replace the old class, whose
+          # field_map and references no longer describe the table.
+          @model_cache = {}
+          @model_cache_misses = {}
+          @model_anonymous_descendants = nil
+          @model_generation += 1
+        end
+      end
+
+      # @!visibility private
+      # Whether `klass` is the class its name currently resolves to. A class
+      # left behind by `remove_const` (or one whose `name` is overridden to a
+      # constant that does not exist) is not live. Never triggers autoload.
+      #
+      # @param klass [Class]
+      # @return [Boolean]
+      def live_model?(klass)
+        name = klass.name
+        return false unless name.is_a?(String) && !name.empty?
+        scope = Object
+        name.split("::").each do |part|
+          return false if scope.autoload?(part)
+          return false unless scope.const_defined?(part, false)
+          scope = scope.const_get(part, false)
+          return false unless scope.is_a?(Module)
+        end
+        scope.equal?(klass)
+      rescue StandardError
+        false
+      end
+
+      # @!visibility private
+      # The one rule that turns a field name into its column for `klass`.
+      # Used by query compilation ({Parse::Query.format_field}) and by the
+      # agent field allowlist ({Parse::Agent::MetadataRegistry.wire_field_names}),
+      # so the name a policy check approves is the column a query addresses.
+      #
+      # Precedence:
+      # 1. A Ruby property name maps to its declared column (`field_map`).
+      # 2. Otherwise a name that is exactly a declared column stays as is.
+      # 3. Otherwise nil: the caller applies its default formatting.
+      #
+      # So with `property :email, field: "contactEmail"` and
+      # `property :legacy_email, field: "email"`, the name `email` resolves to
+      # `contactEmail`. Model code writes Ruby names (`Klass.query(email: x)`),
+      # and the Ruby name must not be redirected to another property's column.
+      #
+      # @param klass [Class] a model class (anything responding to field_map).
+      # @param name [String, Symbol]
+      # @return [String, nil] the declared column, or nil when undeclared.
+      def wire_name_for(klass, name)
+        return nil unless klass.respond_to?(:field_map)
+        field_resolution(klass)[name.to_s]
+      end
+
+      # @!visibility private
+      # Every name {wire_name_for} resolves for `klass`, as a frozen
+      # `{name => column}` Hash. Cached on the class and rebuilt when the
+      # model registry generation or the field_map size changes.
+      #
+      # @param klass [Class]
+      # @return [Hash{String => String}]
+      def field_resolution(klass)
+        fmap = klass.field_map
+        cached = klass.instance_variable_get(:@_parse_field_resolution)
+        generation = @model_generation
+        if cached && cached[0] == generation && cached[1] == fmap.size
+          return cached[2]
+        end
+        map = field_resolution_map(fmap)
+        klass.instance_variable_set(:@_parse_field_resolution, [generation, fmap.size, map].freeze)
+        map
+      end
+
+      # @!visibility private
+      # Build the {wire_name_for} table from a field_map. Declared columns map
+      # to themselves; Ruby property names map to their column and win over a
+      # declared column spelled the same.
+      #
+      # @param fmap [Hash{Symbol => Symbol, String}]
+      # @return [Hash{String => String}] frozen.
+      def field_resolution_map(fmap)
+        map = {}
+        fmap.each_value do |remote|
+          wire = remote.to_s
+          map[wire] = wire
+        end
+        fmap.each { |ruby_name, remote| map[ruby_name.to_s] = remote.to_s }
+        map.freeze
+      end
       # @!attribute self.raise_on_save_failure
       # By default, we return `true` or `false` for save and destroy operations.
       # If you prefer to have `Parse::Object` raise an exception instead, you
@@ -215,21 +329,58 @@ module Parse
       # subclasses (e.g. Parse::Object.find_class), so a bare `@model_cache`
       # would resolve on the subclass singleton — which has no cache. The
       # cache lives on Parse::Model itself.
+      generation = nil
       Parse::Model.model_cache_mutex.synchronize do
         cached = Parse::Model.model_cache[str]
         return cached if cached
+        if Parse::Model.model_cache_misses.key?(str)
+          # A recorded miss holds until the registry changes, unless an
+          # anonymous model seen by the last scan has since been named
+          # (`Foo = Class.new(Parse::Object)` fires no hook when the
+          # constant is assigned). Without anonymous models this is free.
+          anonymous = Parse::Model.model_anonymous_descendants
+          return nil if anonymous.nil? || anonymous.none? { |k| (k.name rescue nil) }
+          Parse::Model.model_cache_misses.clear
+        end
+        generation = Parse::Model.model_generation
+      end
+
+      # Scan outside the lock: the liveness check reads constants, and a
+      # constant read must never run a model definition (whose `inherited`
+      # hook takes this lock) while the lock is held.
+      matches = []
+      anonymous = []
+      Parse::Object.descendants.each do |f|
+        anonymous << f if (f.name rescue nil).nil?
+        begin
+          cls = f.parse_class
+        rescue StandardError
+          next
+        end
+        matches << f if cls == str || cls == "_#{str}"
+      end
+      # Prefer the class the constant currently names over one left behind by
+      # `remove_const`; keep descendant order otherwise.
+      result = if matches.size > 1
+          matches.find { |m| Parse::Model.live_model?(m) } || matches.first
+        else
+          matches.first
+        end
 
-        result = Parse::Object.descendants.find do |f|
-          begin
-            cls = f.parse_class
-          rescue StandardError
-            next false
+      Parse::Model.model_cache_mutex.synchronize do
+        # Cache only when no model was defined or renamed during the scan.
+        if generation == Parse::Model.model_generation
+          if result
+            Parse::Model.model_cache[str] = result
+          else
+            misses = Parse::Model.model_cache_misses
+            misses.clear if misses.size >= MODEL_CACHE_MISSES_MAX
+            misses[str] = true
+            Parse::Model.model_anonymous_descendants = anonymous.freeze
           end
-          cls == str || cls == "_#{str}"
         end
-        Parse::Model.model_cache[str] = result if result
-        result
       end
+      result
     end
 
     # Whether two Parse class-name strings denote the same class. This is the