parse-stack-next 4.5.0 → 5.0.1

data/lib/parse/model/vector.rb

@@ -0,0 +1,102 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require_relative "model"
+
+module Parse
+  # Wraps a dense numeric embedding stored on a Parse object. Backs the
+  # `:vector` property data type and the `embed` DSL. The value is just
+  # an array of Floats — `Parse::Vector` adds dimension awareness,
+  # finite-value validation, and JSON serialization helpers so the
+  # provider/index plumbing can rely on a single concrete shape.
+  #
+  # @example
+  #   class Document < Parse::Object
+  #     property :embedding, :vector, dimensions: 1536,
+  #                                   provider: :openai,
+  #                                   model: "text-embedding-3-small",
+  #                                   similarity: :cosine
+  #   end
+  #
+  #   doc = Document.new(embedding: Array.new(1536) { rand })
+  #   doc.embedding         # => #<Parse::Vector dims=1536>
+  #   doc.embedding.to_a    # => [0.123, 0.456, ...]
+  class Vector
+    include Enumerable
+
+    # Maximum dimensions a Parse::Vector will accept. Atlas Vector Search
+    # caps individual vector indexes at 8192 dims as of MongoDB 7.0; we
+    # keep some headroom but still refuse pathological inputs that would
+    # blow up memory.
+    MAX_DIMENSIONS = 16384
+
+    # @return [Array<Float>] the underlying float array
+    attr_reader :values
+
+    # @param values [Array, Parse::Vector] dense numeric vector
+    # @raise [ArgumentError] if any element is not finite numeric
+    def initialize(values)
+      values = values.values if values.is_a?(Parse::Vector)
+      unless values.is_a?(Array)
+        raise ArgumentError, "[Parse::Vector] expected Array, got #{values.class}."
+      end
+      if values.length > MAX_DIMENSIONS
+        raise ArgumentError,
+              "[Parse::Vector] refusing #{values.length}-dim vector; max #{MAX_DIMENSIONS}."
+      end
+      @values = values.map do |x|
+        unless x.is_a?(Numeric) && x.respond_to?(:finite?) && x.finite?
+          raise ArgumentError,
+                "[Parse::Vector] all elements must be finite Numeric (got #{x.inspect})."
+        end
+        x.to_f
+      end.freeze
+    end
+
+    # @return [Integer] number of dimensions
+    def dimensions
+      @values.length
+    end
+    alias_method :length, :dimensions
+    alias_method :size, :dimensions
+
+    # @return [Array<Float>] the underlying float array
+    def to_a
+      @values.dup
+    end
+
+    # @return [Array<Float>] passes the float array through as JSON
+    # MongoDB / Parse server store this as a plain BSON array.
+    def as_json(*)
+      @values
+    end
+
+    # @return [String] JSON representation
+    def to_json(*opts)
+      @values.to_json(*opts)
+    end
+
+    def each(&block)
+      @values.each(&block)
+    end
+
+    # @return [Boolean] equality by element-wise comparison
+    def ==(other)
+      case other
+      when Parse::Vector then @values == other.values
+      when Array         then @values == other
+      else false
+      end
+    end
+    alias_method :eql?, :==
+
+    def hash
+      @values.hash
+    end
+
+    # @!visibility private
+    def inspect
+      "#<Parse::Vector dims=#{dimensions}>"
+    end
+  end
+end

data/lib/parse/mongodb.rb

@@ -384,6 +384,7 @@ module Parse
         @enabled = false
         @uri = nil
         @database = nil
+        remove_instance_variable(:@gem_available) if defined?(@gem_available)
         reset_writer!
       end
 
@@ -974,7 +975,7 @@ module Parse
       ROLE_GRAPH_ID_RE = /\A[A-Za-z0-9_\-]{1,64}\z/
 
       # Resolve every role name a user inherits via a single
-      # `$graphLookup` aggregation against the Parse role-membership and
+      # `$graphLookup` aggregation against the Parse role-subscription and
       # role-inheritance join tables.
       #
       # This is the mongo-direct fast path that {Parse::Role.all_for_user}
@@ -995,7 +996,7 @@ module Parse
       # If `_Join:roles:_Role` doesn't exist (the app uses flat roles
       # without inheritance), MongoDB treats the missing collection as
       # empty and `$graphLookup` returns no parents — the result collapses
-      # to direct memberships only, matching the Parse-Server-backed walk.
+      # to direct subscriptions only, matching the Parse-Server-backed walk.
       #
       # ## Authorization contract
       #
@@ -1019,7 +1020,7 @@ module Parse
       #
       # ## Return-value contract
       # - `Set<String>` on success (possibly empty if the user has no
-      #   direct memberships).
+      #   direct subscriptions).
       # - `nil` when the fast path is unavailable (mongo gem missing,
       #   {Parse::MongoDB.available?} false). Callers fall back to the
       #   Parse-Server N+1 walk.
@@ -1367,11 +1368,11 @@ module Parse
               "from" => "_Join:users:_Role",
               "localField" => "ids",
               "foreignField" => "owningId",
-              "as" => "memberships",
+              "as" => "subscriptions",
           } },
           { "$project" => {
               "_id" => 0,
-              "user_id_candidates" => "$memberships.relatedId",
+              "user_id_candidates" => "$subscriptions.relatedId",
           } },
           # Filter tombstoned _User rows AND project only `_id` server-side
           # via pipeline-form $lookup (3.6+). Without this, a role with N
@@ -1480,7 +1481,7 @@ module Parse
       #   keep the default +false+ so attacker-controlled or user-supplied
       #   aggregate stages cannot reach internal columns.
       # @param session_token [String, nil] when provided, the SDK
-      #   resolves the token to the requesting user + role membership
+      #   resolves the token to the requesting user + role subscription
       #   (via {Parse::AtlasSearch::Session}) and prepends an
       #   `_rperm` `$match` stage to the pipeline so the result set
       #   simulates Parse Server's row-level ACL enforcement. This
@@ -1499,6 +1500,28 @@ module Parse
       #   `session_token:` nor `master: true` is supplied and
       #   {Parse::ACLScope.require_session_token} is enabled.
       def aggregate(collection_name, pipeline, max_time_ms: nil, rewrite_lookups: nil, allow_internal_fields: false, session_token: nil, master: nil, acl_user: nil, acl_role: nil, read_preference: nil)
+        # AS::N envelope. Payload is intentionally metadata-only —
+        # `stage_count`, `stage_types`, `collection`, `scope`,
+        # `result_count`, `max_time_ms`, `read_preference`. Pipeline
+        # bodies are NOT included: they routinely embed user-id
+        # strings, tenant identifiers, search terms, and other PII
+        # that has no business in a log line or an APM span. The
+        # `parse.mongodb.role_graph` notification (emitted lower in
+        # this module) nests as a child event when role expansion
+        # runs inside the surrounding aggregate. `result_count` and
+        # `scope` are seeded nil so subscribers see a stable key set
+        # even on the raise path (where the block exits before either
+        # is written).
+        instrument_payload = {
+          collection: collection_name,
+          stage_count: pipeline.is_a?(Array) ? pipeline.size : 0,
+          stage_types: __extract_stage_types(pipeline),
+          max_time_ms: max_time_ms,
+          read_preference: read_preference&.to_s,
+          scope: nil,
+          result_count: nil,
+        }
+        ActiveSupport::Notifications.instrument("parse.mongodb.aggregate", instrument_payload) do |payload|
         # Resolve auth kwargs into a Parse::ACLScope::Resolution. The
         # call MUTATES the temporary kwargs hash (popping the auth
         # entries) before the resolution; we package them into a hash
@@ -1511,6 +1534,7 @@ module Parse
           acl_role: acl_role,
         }.compact
         resolution = Parse::ACLScope.resolve!(auth_kwargs, method_name: :aggregate)
+        payload[:scope] = __scope_label(resolution)
 
         # Validate BEFORE rewrite so the security denylist is applied to the
         # caller's original pipeline (which an attacker controls), not to
@@ -1624,7 +1648,9 @@ module Parse
           Parse::CLPScope.redact_protected_fields!(results, strip_set) if strip_set.any?
         end
 
+        payload[:result_count] = results.size
         results
+        end
       rescue => e
         raise_if_timeout!(e, collection_name, max_time_ms)
         raise
@@ -1768,9 +1794,33 @@ module Parse
       #   $where, $function, or $accumulator at any depth.
       # @raise [Parse::MongoDB::ExecutionTimeout] if the query exceeds max_time_ms
       def find(collection_name, filter = {}, **options)
+        max_time_ms = options.delete(:max_time_ms)
+        # Metadata-only AS::N payload: collection, presence-of-filter
+        # (NOT body), projection keys (column names, not values), limit,
+        # max_time_ms, result_count. Filter / projection bodies are
+        # excluded because they routinely embed user-id strings,
+        # tenant IDs, and other PII that has no business in a log line
+        # or a span. The `find` payload deliberately has no `:scope`
+        # field — `Parse::MongoDB.find` takes no ACL kwargs, so there
+        # is no resolution to label. Shared subscribers that handle
+        # both event names must treat `payload[:scope]` as optional.
+        # `result_count` is seeded nil so subscribers see a stable key
+        # set even on the raise path.
+        projection_keys =
+          if options[:projection].is_a?(Hash)
+            options[:projection].keys.map(&:to_s)
+          end
+        instrument_payload = {
+          collection: collection_name,
+          has_filter: filter.is_a?(Hash) && !filter.empty?,
+          projection_keys: projection_keys,
+          limit: options[:limit],
+          max_time_ms: max_time_ms,
+          result_count: nil,
+        }
+        ActiveSupport::Notifications.instrument("parse.mongodb.find", instrument_payload) do |payload|
         allow_internal_fields = options.delete(:allow_internal_fields) || false
         assert_no_denied_operators!(filter, allow_internal_fields: allow_internal_fields)
-        max_time_ms = options.delete(:max_time_ms)
         cursor = collection(collection_name).find(filter)
         explicit_limit = options.key?(:limit)
         applied_default_limit = false
@@ -1801,7 +1851,9 @@ module Parse
                "unbounded behavior."
         end
 
+        payload[:result_count] = results.size
         results
+        end
       rescue => e
         raise_if_timeout!(e, collection_name, max_time_ms)
         raise
@@ -1981,7 +2033,7 @@ module Parse
       # dates, nested documents) but preserving all field names including +_id+.
       # Unlike {.convert_document_to_parse}, this does NOT rename +_id+ to
       # +objectId+, because aggregation +$group+ stages reuse +_id+ as the
-      # group key (e.g. a pointer string like +"Team$abc"+) rather than as a
+      # group key (e.g. a pointer string like +"Workspace$abc"+) rather than as a
       # Parse object identifier.
       #
       # @param doc [Hash] a raw MongoDB aggregation result row
@@ -2060,6 +2112,36 @@ module Parse
 
       private
 
+      # Cardinality cap on the `stage_types` payload field. A
+      # pathological caller sending a 10k-stage pipeline shouldn't
+      # be able to bloat every AS::N subscriber's log line.
+      INSTRUMENT_STAGE_TYPES_LIMIT = 32
+
+      # Extract the top-level operator name from each pipeline stage
+      # (e.g. `["$match", "$lookup", "$project"]`). Returns an empty
+      # array on anything non-Array; non-Hash entries become `nil`
+      # and are pruned. Capped at {INSTRUMENT_STAGE_TYPES_LIMIT}.
+      def __extract_stage_types(pipeline)
+        return [] unless pipeline.is_a?(Array)
+        types = pipeline.first(INSTRUMENT_STAGE_TYPES_LIMIT).map do |stage|
+          stage.is_a?(Hash) ? stage.keys.first.to_s : nil
+        end
+        types.compact
+      end
+
+      # Map a {Parse::ACLScope::Resolution} to a stable, low-cardinality
+      # scope label for the AS::N payload. Four values:
+      # `:master` (master-key path), `:user` (session-token with a
+      # resolved user_id, OR `acl_user:`), `:role` (`acl_role:` —
+      # session mode but no user_id), `:anon` (public — neither
+      # token nor master supplied).
+      def __scope_label(resolution)
+        return :anon if resolution.nil?
+        return :master if resolution.master?
+        return :anon if resolution.public?
+        resolution.user_id ? :user : :role
+      end
+
       # MongoDB error code for MaxTimeMSExpired
       MONGO_MAX_TIME_MS_EXPIRED_CODE = 50
 

data/lib/parse/pipeline_security.rb

@@ -179,15 +179,42 @@ module Parse
     # Top-level pipeline stages permitted by the strict validator. The
     # set covers Parse-Stack's own aggregation use, plus Atlas Search
     # entry points (`$search`, `$searchMeta`, `$listSearchIndexes`) so
-    # that `Parse::AtlasSearch` calls do not break.
+    # that `Parse::AtlasSearch` calls do not break. `$vectorSearch` is
+    # included for `Parse::VectorSearch` — like `$search`, it is a
+    # read-only Atlas index stage and must be the FIRST stage of the
+    # pipeline (Atlas refuses it otherwise).
     ALLOWED_STAGES = %w[
       $match $group $sort $project $limit $skip $unwind $lookup
       $count $addFields $set $unset $bucket $bucketAuto $facet
       $sample $sortByCount $replaceRoot $replaceWith $redact
       $graphLookup $unionWith
-      $search $searchMeta $listSearchIndexes
+      $search $searchMeta $listSearchIndexes $vectorSearch
     ].freeze
 
+    # Atlas operators that are valid only as the FIRST stage of a
+    # pipeline (Atlas refuses them anywhere else). They are present in
+    # {ALLOWED_STAGES} so the SDK's own modules — `Parse::AtlasSearch`
+    # and `Parse::VectorSearch` — can emit them; both of those modules
+    # bypass {validate_pipeline!} and build their pipelines internally.
+    # Caller-supplied pipelines (e.g. through `Parse::Agent::Tools.aggregate`)
+    # must NOT include these stages: the Agent's tenant-scope `$match`
+    # prepend would push them off stage 0, and the proper agent surface
+    # for full-text and vector search is the dedicated
+    # `atlas_search` / `semantic_search` tools, not raw aggregate.
+    STAGE0_ONLY_ATLAS_STAGES = %w[
+      $search $searchMeta $vectorSearch $listSearchIndexes
+    ].freeze
+
+    # Cap on the length of a caller-supplied `$regex` (or the `regex:`
+    # field inside `$regexMatch` / `$regexFind` / `$regexFindAll`)
+    # pattern string. ReDoS protection: doesn't catch every pathological
+    # pattern (small patterns like `(a+)+$` can still backtrack
+    # catastrophically), but caps the worst class of caller-shipped
+    # patterns and stops the "1MB regex" denial-of-service shape that an
+    # attacker could send through `vector_filter:` / `filter:` /
+    # `where:`. Legitimate Parse-Server queries are well under this.
+    MAX_REGEX_PATTERN_LENGTH = 512
+
     # Cap on number of top-level stages in a strict-validated pipeline.
     MAX_PIPELINE_STAGES = 20
 
@@ -497,6 +524,36 @@ module Parse
               reason: :denied_internal_field,
             )
           end
+          # Cap caller-supplied regex pattern length. Catches the two
+          # shapes Mongo accepts: the find-form `{ field: { $regex: "..." } }`
+          # (key == "$regex", value a String), and the aggregation-form
+          # `{ $regexMatch: { input: ..., regex: "..." } }` (key ==
+          # "$regexMatch"/"$regexFind"/"$regexFindAll", value a Hash with
+          # a "regex"/"pattern" String inside). Stops a multi-KB pattern
+          # from reaching MongoDB regardless of where in the pipeline it
+          # appears.
+          if key_str == "$regex" && value.is_a?(String) && value.bytesize > MAX_REGEX_PATTERN_LENGTH
+            raise Error.new(
+              "SECURITY: $regex pattern exceeds #{MAX_REGEX_PATTERN_LENGTH} bytes " \
+              "(got #{value.bytesize}). Long caller-supplied regex patterns are a " \
+              "ReDoS vector; refuse caller-supplied regexes longer than this cap.",
+              stage: stage_idx,
+              operator: "$regex",
+              reason: :regex_pattern_too_long,
+            )
+          end
+          if %w[$regexMatch $regexFind $regexFindAll].include?(key_str) && value.is_a?(Hash)
+            pat = value["regex"] || value[:regex] || value["pattern"] || value[:pattern]
+            if pat.is_a?(String) && pat.bytesize > MAX_REGEX_PATTERN_LENGTH
+              raise Error.new(
+                "SECURITY: #{key_str} regex pattern exceeds #{MAX_REGEX_PATTERN_LENGTH} bytes " \
+                "(got #{pat.bytesize}). Refuse caller-supplied regexes longer than this cap.",
+                stage: stage_idx,
+                operator: key_str,
+                reason: :regex_pattern_too_long,
+              )
+            end
+          end
           child_inside_expr = inside_expr || key_str == "$expr"
           if child_inside_expr && FORENSIC_OPERATORS.include?(key_str)
             raise Error.new(

data/lib/parse/query/constraints.rb

@@ -1915,7 +1915,7 @@ module Parse
     end
 
     # Equivalent to the `$geoWithin` Parse query operation with `$centerSphere`
-    # subconstraint. Filters a {Parse::GeoPoint} column by membership in a
+    # subconstraint. Filters a {Parse::GeoPoint} column by subscription in a
     # circular region defined by a center point and a radius. Unlike
     # `:field.near => geopoint.max_*(N)`, this constraint does NOT order
     # results by distance, which makes it cheap and composable inside `$or`
@@ -2056,20 +2056,22 @@ module Parse
       ].freeze
 
       def coerce_to_geojson(value)
+        # Ruby hash patterns only match symbol-keyed entries, so wire-shape
+        # hashes (which arrive with string keys from JSON) must be normalised
+        # before the inner case/in can deconstruct them.
         case value
-        when Parse::GeoJSON::Geometry then value.to_geojson
-        when Parse::Polygon then value.to_geojson
-        when Parse::GeoPoint then value.to_geojson
-        when Hash
-          h = value.respond_to?(:symbolize_keys) ? value.symbolize_keys : value
-          type = h[:type] || h["type"]
-          coords = h[:coordinates] || h["coordinates"]
-          unless type.is_a?(String) && ALLOWED_GEOJSON_TYPES.include?(type) && coords.is_a?(Array)
+        in Parse::GeoJSON::Geometry | Parse::Polygon | Parse::GeoPoint
+          value.to_geojson
+        in Hash => h
+          normalised = h.respond_to?(:symbolize_keys) ? h.symbolize_keys : h
+          case normalised
+          in { type: String => type, coordinates: Array => coords } if ALLOWED_GEOJSON_TYPES.include?(type)
+            { "type" => type, "coordinates" => coords }
+          else
             raise ArgumentError, "[Parse::Query] `geo_intersects` Hash must be a GeoJSON geometry " \
                                  "with one of the RFC 7946 types " \
                                  "(#{ALLOWED_GEOJSON_TYPES.join(", ")}) and an Array of coordinates."
           end
-          { "type" => type, "coordinates" => coords }
         else
           raise ArgumentError, "[Parse::Query] `geo_intersects` expects a Parse::GeoPoint, " \
                                "Parse::Polygon, Parse::GeoJSON::Geometry, or GeoJSON Hash."
@@ -2874,15 +2876,15 @@ module Parse
     # Uses MongoDB's $lookup to join collections and $expr with $ne to compare fields.
     #
     # Usage:
-    #   Asset.where(:project.does_not_equal_linked_pointer => { through: :capture, field: :project })
+    #   Document.where(:project.does_not_equal_linked_pointer => { through: :post, field: :project })
     #
     # This generates a MongoDB aggregation pipeline that:
     # 1. Uses $lookup to join the linked collection
     # 2. Uses $match with $expr and $ne to find records where fields do NOT match
     #
-    # @example Find assets where the project does not equal the capture's project
-    #   Asset.where(:project.does_not_equal_linked_pointer => {
-    #     through: :capture,
+    # @example Find assets where the project does not equal the post's project
+    #   Document.where(:project.does_not_equal_linked_pointer => {
+    #     through: :post,
     #     field: :project
     #   })
     class DoesNotEqualLinkedPointerConstraint < Constraint

data/lib/parse/query/ordering.rb

@@ -9,7 +9,7 @@ module Parse
   # special methods to the Symbol class. The developer can then pass one
   # or an array of fields (as symbols) and call the particular ordering
   # polarity (ex. _:name.asc_ would create a Parse::Order where we want
-  # things to be sortd by the name field in ascending order)
+  # things to be sorted by the name field in ascending order)
   # For more information about the query design pattern from DataMapper
   # that inspired this, see http://datamapper.org/docs/find.html'
   # @example