parse-stack-next 5.2.1 → 5.4.0

data/lib/parse/embeddings/spend_cap.rb

@@ -0,0 +1,255 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "thread"
+
+module Parse
+  module Embeddings
+    # Per-tenant cumulative embedding spend cap.
+    #
+    # The agent `semantic_search` tool embeds attacker-controlled text
+    # (chat queries) on every call. Without a cap, a tenant — or an
+    # adversary driving an agent — can run up unbounded embedding-provider
+    # cost. {SpendCap} tracks the cumulative number of *tokens* embedded
+    # per tenant inside a sliding time window and HARD-REFUSES (raises
+    # {Exceeded}) once a tenant would exceed its limit. This is distinct
+    # from {Parse::Agent::RateLimiter}, which bounds request *count* per
+    # window; the spend cap bounds embedding *volume* (a proxy for cost).
+    #
+    # == Disabled by default
+    #
+    # With no configured limit the cap is a no-op — {.charge!} records
+    # nothing and never raises. Operators opt in:
+    #
+    #   Parse::Embeddings::SpendCap.configure(limit_tokens: 1_000_000, window: 3600)
+    #   Parse::Embeddings::SpendCap.configure(:acme_tenant, limit_tokens: 50_000)
+    #
+    # A per-tenant limit (second form) overrides the default for that
+    # tenant. The reserved key {DEFAULT_KEY} sets the fallback applied to
+    # every tenant without an explicit limit.
+    #
+    # == Token estimation
+    #
+    # Callers pass an explicit token count, or use {.estimate_tokens} (a
+    # chars/4 heuristic — the same approximation the agent layer uses for
+    # its context-token budgets). The cap is intentionally an estimate: it
+    # exists to bound runaway cost, not to bill precisely.
+    #
+    # Thread-safe: all state lives behind a single mutex.
+    module SpendCap
+      # Raised when a tenant would exceed its token cap. Carries the
+      # limit, the already-used count (within the window), and a
+      # `retry_after` hint (seconds until enough of the window rolls off
+      # to admit the rejected charge — `nil` if the charge can never fit).
+      class Exceeded < StandardError
+        attr_reader :tenant_id, :limit, :used, :requested, :window, :retry_after
+
+        def initialize(tenant_id:, limit:, used:, requested:, window:, retry_after:)
+          @tenant_id = tenant_id
+          @limit = limit
+          @used = used
+          @requested = requested
+          @window = window
+          @retry_after = retry_after
+          super(
+            "Embedding spend cap exceeded for tenant #{tenant_id.inspect}: " \
+            "#{used}+#{requested} tokens would exceed #{limit}/#{window}s." \
+            "#{retry_after ? " Retry after #{retry_after.round(1)}s." : " Request exceeds the cap outright."}"
+          )
+        end
+      end
+
+      # Fallback bucket key for charges with no tenant identity, and the
+      # key under which {.configure} (with no explicit tenant) sets the
+      # default limit applied to every tenant lacking an override.
+      DEFAULT_KEY = :__default__
+
+      # Default sliding window (seconds) when none is configured.
+      DEFAULT_WINDOW = 3600
+
+      class << self
+        # Configure the cap. Two forms:
+        #
+        #   configure(limit_tokens:, window:)            # default for all tenants
+        #   configure(tenant_id, limit_tokens:, window:) # override one tenant
+        #
+        # `limit_tokens: nil` disables the cap for that scope (the default
+        # scope when no tenant is given).
+        #
+        # @param tenant_id [Object, nil] tenant to override, or nil for
+        #   the global default.
+        # @param limit_tokens [Integer, nil] token ceiling per window.
+        # @param window [Integer] sliding window length in seconds.
+        # @return [void]
+        def configure(tenant_id = nil, limit_tokens:, window: DEFAULT_WINDOW)
+          key = tenant_id.nil? ? DEFAULT_KEY : tenant_id
+          unless limit_tokens.nil?
+            li = Integer(limit_tokens)
+            raise ArgumentError, "SpendCap: limit_tokens must be positive (got #{li})." if li <= 0
+          end
+          w = Integer(window)
+          raise ArgumentError, "SpendCap: window must be positive (got #{w})." if w <= 0
+          mutex.synchronize do
+            limits[key] = limit_tokens.nil? ? nil : { limit: Integer(limit_tokens), window: w }
+          end
+          nil
+        end
+
+        # Charge `tokens` against `tenant_id`'s budget. HARD-REFUSES by
+        # raising {Exceeded} when the charge would push the tenant over
+        # its limit within the window; otherwise records the charge and
+        # returns the new in-window total.
+        #
+        # No-op (returns nil) when no limit applies to the tenant.
+        #
+        # @param tenant_id [Object, nil] tenant identity (nil → {DEFAULT_KEY}).
+        # @param tokens [Integer] tokens to charge (>= 0).
+        # @return [Integer, nil] new in-window total, or nil if uncapped.
+        # @raise [Exceeded]
+        def charge!(tenant_id:, tokens:)
+          t = Integer(tokens)
+          raise ArgumentError, "SpendCap: tokens must be >= 0 (got #{t})." if t.negative?
+          key = tenant_id.nil? ? DEFAULT_KEY : tenant_id
+
+          mutex.synchronize do
+            cfg = limit_for(key)
+            return nil if cfg.nil? # uncapped
+
+            window = cfg[:window]
+            limit = cfg[:limit]
+            now = monotonic
+            entries = prune(key, now, window)
+            used = entries.sum { |e| e[1] }
+
+            if used + t > limit
+              raise Exceeded.new(
+                tenant_id: key, limit: limit, used: used, requested: t,
+                window: window, retry_after: retry_after_for(entries, t, limit, window, now),
+              )
+            end
+            entries << [now, t] if t.positive?
+            used + t
+          end
+        end
+
+        # Current in-window token usage for a tenant (0 when uncapped or
+        # idle). Does not mutate.
+        #
+        # @param tenant_id [Object, nil]
+        # @return [Integer]
+        def usage(tenant_id: nil)
+          key = tenant_id.nil? ? DEFAULT_KEY : tenant_id
+          mutex.synchronize do
+            cfg = limit_for(key)
+            return 0 if cfg.nil?
+            prune(key, monotonic, cfg[:window]).sum { |e| e[1] }
+          end
+        end
+
+        # Estimate token count from a String.
+        #
+        # The familiar "~4 characters per token" ratio only holds for
+        # ASCII. CJK, emoji, and other multibyte text run closer to one
+        # token per codepoint in a real tokenizer, so a pure
+        # `chars / 4` estimate undercounts such input by up to ~4x — and
+        # since this estimate is the sole basis for the hard-refuse
+        # decision, that lets a caller feeding multibyte text reach ~4x
+        # the real embedding volume before the cap trips. Take the larger
+        # of the char-based and byte-based estimates so multibyte input
+        # bills at least as much as its UTF-8 byte length implies.
+        #
+        # @param text [String]
+        # @return [Integer]
+        def estimate_tokens(text)
+          str = text.to_s
+          chars = (str.length / 4.0).ceil
+          bytes = (str.bytesize / 4.0).ceil
+          [chars, bytes].max
+        end
+
+        # Clear recorded usage (all tenants, or one). Limits are retained.
+        #
+        # @param tenant_id [Object, nil]
+        def reset!(tenant_id = nil)
+          mutex.synchronize do
+            if tenant_id.nil?
+              @buckets = {}
+            else
+              buckets.delete(tenant_id)
+            end
+          end
+          nil
+        end
+
+        # Remove all configured limits AND recorded usage. Mainly for
+        # tests — returns the cap to its disabled-by-default state.
+        def reset_all!
+          mutex.synchronize do
+            @limits = {}
+            @buckets = {}
+          end
+          nil
+        end
+
+        private
+
+        MUTEX_INIT = Mutex.new
+        private_constant :MUTEX_INIT
+
+        def mutex
+          @mutex ||= MUTEX_INIT.synchronize { @mutex ||= Mutex.new }
+        end
+
+        def limits
+          @limits ||= {}
+        end
+
+        def buckets
+          @buckets ||= {}
+        end
+
+        # Resolve the effective limit config for a key: an explicit
+        # per-tenant entry wins; otherwise the DEFAULT_KEY entry; nil when
+        # neither is set (uncapped). A key explicitly set to nil disables
+        # the cap for that tenant even if a default exists.
+        def limit_for(key)
+          if limits.key?(key)
+            limits[key]
+          else
+            limits[DEFAULT_KEY]
+          end
+        end
+
+        # Drop entries older than the window; returns the (mutated) live
+        # entry list for the key.
+        def prune(key, now, window)
+          entries = (buckets[key] ||= [])
+          cutoff = now - window
+          entries.reject! { |e| e[0] <= cutoff }
+          entries
+        end
+
+        # Seconds until enough in-window tokens roll off to admit a charge
+        # of `requested` tokens. nil when the request alone exceeds the
+        # limit (it can never fit).
+        def retry_after_for(entries, requested, limit, window, now)
+          return nil if requested > limit
+          need_to_free = (entries.sum { |e| e[1] } + requested) - limit
+          return 0.0 if need_to_free <= 0
+          freed = 0
+          entries.sort_by { |e| e[0] }.each do |ts, tok|
+            freed += tok
+            if freed >= need_to_free
+              return [(ts + window) - now, 0.0].max
+            end
+          end
+          nil
+        end
+
+        def monotonic
+          Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/parse/embeddings.rb

@@ -554,3 +554,4 @@ require_relative "embeddings/voyage"
 require_relative "embeddings/jina"
 require_relative "embeddings/qwen"
 require_relative "embeddings/local_http"
+require_relative "embeddings/spend_cap"

data/lib/parse/live_query/client.rb

@@ -363,7 +363,7 @@ module Parse
       #   events can arrive. Optional — callers may still capture the
       #   returned subscription and register callbacks later.
       # @return [Subscription]
-      def subscribe(class_name, where: {}, fields: nil, session_token: nil,
+      def subscribe(class_name, where: {}, fields: nil, keys: nil, watch: nil, session_token: nil,
                     use_master_key: false, &block)
         # Handle Parse::Object subclass
         if class_name.is_a?(Class) && class_name < Parse::Object
@@ -396,6 +396,8 @@ module Parse
           class_name: class_name,
           query: where,
           fields: fields,
+          keys: keys,
+          watch: watch,
           session_token: session_token,
           use_master_key: use_master_key,
         )

data/lib/parse/live_query/subscription.rb

@@ -62,12 +62,22 @@ module Parse
       # @return [Parse::LiveQuery::Client] the LiveQuery client
       attr_reader :client
 
-      # @return [Array<String>] fields to watch for changes (nil = all fields)
+      # @return [Array<String>] field projection for returned events
+      #   (nil = all fields). Parse Server 7.0 renamed this subscription
+      #   option from `fields` to `keys`; {#keys} is the canonical alias.
       attr_reader :fields
+      # @return [Array<String>] alias for {#fields} under Parse Server's
+      #   post-7.0 `keys` name.
+      alias_method :keys, :fields
 
       # @return [String, nil] session token for ACL-aware subscriptions
       attr_reader :session_token
 
+      # @return [Array<String>, nil] field names that trigger update events when
+      #   changed (PS 7.0+ `watch` option). +nil+ means all field changes trigger
+      #   update events.
+      attr_reader :watch
+
       # Create a new subscription
       # @param client [Parse::LiveQuery::Client] the LiveQuery client
       # @param class_name [String] Parse class name
@@ -85,13 +95,16 @@ module Parse
       #   elevated; on a non-admin connection the client warns and the
       #   subscription stays ACL-scoped. For mixed scoped + admin needs,
       #   use two separate clients. Defaults to false.
-      def initialize(client:, class_name:, query: {}, fields: nil,
-                     session_token: nil, use_master_key: false)
+      def initialize(client:, class_name:, query: {}, fields: nil, keys: nil,
+                     session_token: nil, use_master_key: false, watch: nil)
         @monitor = Monitor.new
         @client = client
         @class_name = class_name
         @query = query
-        @fields = fields
+        # `keys` is the post-7.0 name; accept either and prefer the explicit
+        # `keys:` when both are supplied.
+        @fields = keys.nil? ? fields : keys
+        @watch = watch
         @session_token = session_token
         @use_master_key = use_master_key == true
         @request_id = generate_request_id
@@ -239,7 +252,21 @@ module Parse
           },
         }
 
-        msg[:query][:fields] = fields if fields&.any?
+        if fields&.any?
+          # Parse Server 7.0 (DEPPS9 / #8852) renamed the subscription field-
+          # projection option from `fields` to `keys`. PS 7+ reads `keys` and
+          # ignores `fields`; PS < 7 reads `fields`. Emit BOTH so projection is
+          # honored on every supported server — sending an extra key the server
+          # ignores is harmless, while sending only `fields` silently disables
+          # projection (events return all columns) on PS 7+.
+          msg[:query][:keys] = fields
+          msg[:query][:fields] = fields
+        end
+        # PS 7.0 (#8028) `watch`: fire update events only when the named fields
+        # change. Distinct from field projection (`keys`/`fields`): `watch`
+        # controls which field mutations generate an update event; `keys` controls
+        # which fields are returned in the event payload.
+        msg[:query][:watch] = watch if watch&.any?
         msg[:sessionToken] = session_token if session_token
         # The subscribe frame deliberately NEVER carries `masterKey`.
         # Parse Server's `_handleSubscribe` does not read it — master-key

data/lib/parse/model/acl.rb

@@ -91,8 +91,10 @@ module Parse
   #  artist.save
   #
   # You may also set default ACLs for your subclasses by using {Parse::Object.set_default_acl}.
-  # These will be get applied for newly created instances. All subclasses have
-  # public read and write enabled by default.
+  # These will get applied for newly created instances. Unless overridden, subclasses
+  # inherit the shipped `:owner_else_private` policy — records are private
+  # (master-only) until an owner is resolved at save time. Use {Parse::Object.set_default_acl}
+  # or {Parse::Object.acl_policy} to grant broader access.
   #
   #  class AdminData < Parse::Object
   #

data/lib/parse/model/associations/belongs_to.rb

@@ -119,6 +119,23 @@ module Parse
 
         # These items are added as attributes with the special data type of :pointer
         def belongs_to(key, opts = {})
+          # An explicitly-passed `as:` that names a scalar data type
+          # (`:string`, `:integer`, `:boolean`, …) is almost always a mistake —
+          # you cannot point at a scalar — and most often means a `property`
+          # was written with `as:` out of habit. Reject it at declaration time.
+          # This is the only association footgun decidable without all models
+          # loaded: an unresolved *class* name may simply be a forward
+          # reference (the target is required later), so that check is deferred
+          # to {Parse.validate_associations!}.
+          explicit_as = opts.key?(:as) ? opts[:as] : nil
+          if explicit_as && Parse::Properties::TYPES.include?(explicit_as.to_s.to_sym)
+            scalar = explicit_as.to_s.to_sym
+            raise ArgumentError,
+                  "#{self}##{key}: `as: #{explicit_as.inspect}` names the reserved data type " \
+                  ":#{scalar}, not a Parse class. For a scalar column write " \
+                  "`property #{key.inspect}, #{scalar.inspect}`; if you really mean a Parse class " \
+                  "named #{scalar.to_s.camelize.inspect}, pass `class_name: #{scalar.to_s.camelize.inspect}` instead."
+          end
           opts = { as: key, field: key.to_s.camelize(:lower), required: false }.merge(opts)
           # `opts[:class_name]` is the explicit target Parse class name; it takes
           # precedence over the legacy `as: :symbol` shorthand (where the
@@ -134,6 +151,22 @@ module Parse
           set_attribute_method = :"#{key}_set_attribute!"
 
           if self.fields[key].present? && Parse::Properties::BASE_FIELD_MAP[key].nil?
+            existing_type = self.fields[key]
+            # A structural redeclaration that CHANGES the type to a pointer
+            # (e.g. a field first declared `property :owner, :string` and then
+            # `property :owner, as: :user` / `belongs_to :owner`) is almost
+            # always a bug — and, because `property … as:` now delegates here,
+            # it is the same silent-String failure mode this whole feature
+            # exists to fix. Honor the same `strict_property_redefinition`
+            # contract that `property` enforces so the conflict is not
+            # downgraded to a warning. A same-type reopen (existing :pointer)
+            # still just warns, matching the prior behavior.
+            if existing_type != :pointer && Parse.strict_property_redefinition
+              raise ArgumentError,
+                    "#{self}##{key} is already defined as :#{existing_type}; refusing to " \
+                    "redeclare it as a :pointer association (target #{klassName}). Set " \
+                    "Parse.strict_property_redefinition = false to fall back to warn-and-ignore."
+            end
             warn "Belongs relation #{self}##{key} already defined with type #{klassName}"
             return false
           end
@@ -151,6 +184,20 @@ module Parse
           # Mapping between local attribute name and the remote column name
           self.field_map.merge!(key => parse_field)
 
+          # Agent metadata: a belongs_to pointer can carry a semantic description
+          # (and per-value enum descriptions) just like a `property` can. This
+          # also lets `property :x, as: :user, _description: "..."` round-trip its
+          # metadata through the delegation in Parse::Properties#property.
+          if opts[:_description].present?
+            self.property_descriptions[key] = opts[:_description].to_s.freeze
+          end
+          if opts[:_enum].is_a?(Hash) && opts[:_enum].any?
+            normalized = opts[:_enum].each_with_object({}) do |(value, desc), h|
+              h[value.to_s] = desc.to_s.freeze
+            end
+            self.property_enum_descriptions[key] = normalized.freeze
+          end
+
           # used for dirty tracking
           define_attribute_methods key
 

data/lib/parse/model/classes/audience.rb

@@ -155,12 +155,60 @@ module Parse
     property :name
 
     # @!attribute query
-    # The query constraints that define which installations belong to this audience.
-    # This is stored as a hash matching the Installation query format.
-    # @return [Hash] The query constraint hash.
+    # The query constraints that define which installations belong to this
+    # audience, as a Hash matching the Installation query format.
+    #
+    # On the wire this is persisted as a JSON **string**, matching Parse
+    # Server's built-in `_Audience.query` column (typed `String`, not Object).
+    # Assigning a Hash and reading a Hash back is handled transparently. The
+    # previous `property :query, :object` emitted a JSON object, so every save
+    # of a hash query was rejected by the server with a schema mismatch
+    # ("expected String but got Object").
+    # @return [ActiveSupport::HashWithIndifferentAccess, nil] the query hash.
     # @example
     #   audience.query = { "deviceType" => "ios", "appVersion" => { "$gte" => "2.0" } }
-    property :query, :object
+    property :query_json, :string, field: :query
+
+    # JSON-encode a Hash/Array assigned to the query field before the `:string`
+    # property coercion runs. Every assignment path — `query=`,
+    # `query_constraint=`, mass-assignment via `new(query:)`, and server
+    # hydration — funnels through `format_value`, so intercepting here (rather
+    # than the public setter, which mass-assignment bypasses) is the single
+    # reliable place to keep the wire value valid JSON (`{"k":"v"}`) instead of
+    # Ruby's `Hash#to_s` (`{"k"=>"v"}`). A String passed in (e.g. a row loaded
+    # from the server) falls through to the normal string coercion untouched.
+    def format_value(key, val, data_type = nil)
+      if key == :query_json && (val.is_a?(Hash) || val.is_a?(Array))
+        return val.to_json
+      end
+      super
+    end
+
+    # The query constraints as a Hash (decoded from the stored JSON string).
+    # @return [ActiveSupport::HashWithIndifferentAccess, nil]
+    def query
+      raw = query_json
+      case raw
+      when nil, "" then nil
+      when Hash then raw.with_indifferent_access
+      when String
+        decoded = begin
+            JSON.parse(raw)
+          rescue JSON::ParserError
+            nil
+          end
+        decoded.is_a?(Hash) ? decoded.with_indifferent_access : decoded
+      else
+        raw
+      end
+    end
+
+    # Assign the audience query. Accepts a Hash (preferred) or a pre-encoded
+    # JSON String; either form is persisted as a JSON string.
+    # @param value [Hash, String, nil]
+    def query=(value)
+      self.query_json = value
+    end
 
     # Alias for query to match Parse Server naming conventions.
     # @return [Hash] The query constraint hash.