parse-stack-next 4.5.0 → 5.0.1

data/lib/parse/atlas_search.rb

@@ -243,6 +243,18 @@ module Parse
       # @option options [Hash] :sort sort specification (default: by relevance score)
       # @option options [Boolean] :raw return raw MongoDB documents (default: false)
       # @option options [String] :class_name Parse class name for object conversion
+      # @option options [String] :session_token Parse session token used to scope
+      #   ACL/CLP enforcement to the owning user.
+      # @option options [Boolean] :master run with master-key semantics and bypass
+      #   ACL/CLP enforcement (default: false).
+      # @option options [Parse::User, Parse::Pointer] :acl_user act as the given
+      #   user pointer for ACL evaluation (no REST equivalent; mongo-direct only).
+      # @option options [String, Parse::Role] :acl_role act as the given role for
+      #   ACL evaluation (no REST equivalent; mongo-direct only).
+      # @option options [Symbol] :read_preference MongoDB read preference applied
+      #   to the underlying collection (e.g. +:secondary+).
+      # @option options [Integer] :max_time_ms maximum server-side execution time
+      #   in milliseconds for the aggregate command.
       #
       # @return [Parse::AtlasSearch::SearchResult] search result object
       #
@@ -393,6 +405,19 @@ module Parse
       # @option options [Integer] :limit max suggestions to return (default: 10)
       # @option options [Hash] :filter additional constraints
       # @option options [Boolean] :raw return raw documents (default: false)
+      # @option options [String] :class_name Parse class name for object conversion.
+      # @option options [String] :session_token Parse session token used to scope
+      #   ACL/CLP enforcement to the owning user.
+      # @option options [Boolean] :master run with master-key semantics and bypass
+      #   ACL/CLP enforcement (default: false).
+      # @option options [Parse::User, Parse::Pointer] :acl_user act as the given
+      #   user pointer for ACL evaluation (no REST equivalent; mongo-direct only).
+      # @option options [String, Parse::Role] :acl_role act as the given role for
+      #   ACL evaluation (no REST equivalent; mongo-direct only).
+      # @option options [Symbol] :read_preference MongoDB read preference applied
+      #   to the underlying collection (e.g. +:secondary+).
+      # @option options [Integer] :max_time_ms maximum server-side execution time
+      #   in milliseconds for the aggregate command.
       #
       # @return [Parse::AtlasSearch::AutocompleteResult] autocomplete result
       #
@@ -509,7 +534,14 @@ module Parse
       # @param collection_name [String] the Parse collection name
       # @param query [String, nil] the search query text (nil for match-all)
       # @param facets [Hash] facet definitions
-      # @param options [Hash] search options (same as #search)
+      # @param options [Hash] search options (same as {#search}; see that
+      #   method for the full list of accepted +@option+ entries including
+      #   +:index+, +:fields+, +:fuzzy+, +:limit+, +:filter+, +:read_preference+,
+      #   +:max_time_ms+, and the scoping kwargs +:master+, +:session_token+,
+      #   +:acl_user+, +:acl_role+). Note: scoped identity kwargs require
+      #   +master: true+ to be passed explicitly — $searchMeta bucket counts
+      #   cannot be filtered by ACL after the fact, so the method refuses
+      #   to silently downgrade.
       #
       # @return [Parse::AtlasSearch::FacetedResult] faceted result
       #
@@ -944,19 +976,15 @@ module Parse
           objects = parse_results.each_with_index.map do |doc, idx|
             obj = build_parse_object(doc, class_name)
             raw_doc = raw_results[idx]
-            # Attach search metadata from original raw document (scores are stripped during conversion)
+            # Attach search metadata from original raw document. `search_score`
+            # and `search_highlights` readers are defined once on Parse::Object
+            # (see lib/parse/model/object.rb) so we only set the ivars here —
+            # no per-row singleton method definition.
             if obj && raw_doc["_score"]
               obj.instance_variable_set(:@_search_score, raw_doc["_score"])
-              # Define accessor if not already defined
-              unless obj.respond_to?(:search_score)
-                obj.define_singleton_method(:search_score) { @_search_score }
-              end
             end
             if obj && raw_doc["_highlights"]
               obj.instance_variable_set(:@_search_highlights, raw_doc["_highlights"])
-              unless obj.respond_to?(:search_highlights)
-                obj.define_singleton_method(:search_highlights) { @_search_highlights }
-              end
             end
             obj
           end.compact

data/lib/parse/cache/pool.rb

@@ -0,0 +1,88 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "connection_pool"
+require "moneta"
+
+module Parse
+  module Cache
+    # Moneta-compatible facade over a ConnectionPool of Moneta stores. The
+    # Faraday caching middleware only calls four methods on its store
+    # (`[]`, `key?`, `delete`, `store`); this class checks out a backend
+    # for each of them via `@pool.with`.
+    #
+    # Why a pool: a single Moneta-Redis store wraps one Redis connection.
+    # Under a multi-threaded Puma worker (or any concurrent caller), threads
+    # serialize on that connection's mutex. A pool of N stores lets up to N
+    # cache calls run in parallel.
+    #
+    # Note that a cache hit costs two checkouts (`key?` then `[]`). That is
+    # accepted to keep behavior identical to a plain Moneta store; callers
+    # should size the pool with that in mind (default 5, which matches the
+    # Puma default thread count).
+    class Pool
+      # The wrapped ConnectionPool instance.
+      attr_reader :pool
+
+      # @param size [Integer] number of pooled backend stores.
+      # @param timeout [Numeric] seconds to wait for a checkout before
+      #   raising `ConnectionPool::TimeoutError`.
+      # @yield Block invoked to build a single backend store. Must return a
+      #   Moneta store responding to `[]`, `key?`, `delete`, `store`.
+      def initialize(size: 5, timeout: 5, &block)
+        raise ArgumentError, "Parse::Cache::Pool requires a block that builds a Moneta store" unless block_given?
+        @pool = ConnectionPool.new(size: size, timeout: timeout, &block)
+        @closed = false
+      end
+
+      def [](key)
+        @pool.with { |store| store[key] }
+      end
+
+      def key?(key)
+        @pool.with { |store| store.key?(key) }
+      end
+
+      def delete(key)
+        @pool.with { |store| store.delete(key) }
+      end
+
+      def store(key, value, options = {})
+        @pool.with { |store| store.store(key, value, options) }
+      end
+
+      # Atomic SETNX-style write. Required by `Parse::CreateLock` to acquire
+      # cross-process locks against Redis-backed stores. Forwards to the
+      # underlying Moneta store's `#create`, which returns `true` only if
+      # the key was absent and is now set.
+      def create(key, value, options = {})
+        @pool.with { |store| store.create(key, value, options) }
+      end
+
+      # Atomic counter increment. Forwarded for parity with Moneta so
+      # callers expecting the full Moneta surface (counters, rate limits)
+      # work transparently through the pool.
+      def increment(key, amount = 1, options = {})
+        @pool.with { |store| store.increment(key, amount, options) }
+      end
+
+      # Clear the underlying backend. Pooled Moneta stores all point at the
+      # same Redis DB, so a single checkout suffices — issuing `clear` on
+      # one connection flushes the DB for every connection.
+      def clear
+        @pool.with { |store| store.clear if store.respond_to?(:clear) }
+        self
+      end
+
+      # Close all pooled backends. Safe to call multiple times — repeat
+      # calls are no-ops. `ConnectionPool#shutdown` raises
+      # `ConnectionPool::PoolShuttingDownError` on a second invocation,
+      # so we gate it with a `@closed` flag.
+      def close
+        return if @closed
+        @closed = true
+        @pool.shutdown { |store| store.close if store.respond_to?(:close) }
+      end
+    end
+  end
+end

data/lib/parse/cache/redis.rb

@@ -0,0 +1,249 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "moneta"
+require_relative "pool"
+
+module Parse
+  module Cache
+    # Ergonomic Redis cache builder for Parse Stack. Composes a
+    # ConnectionPool of Moneta-Redis stores and carries an optional
+    # `namespace` that `Parse::Client` will pick up automatically — there
+    # is no need to also pass `cache_namespace:` to `Parse.setup` when
+    # using this wrapper.
+    #
+    # Usage:
+    #   Parse.setup(
+    #     cache: Parse::Cache::Redis.new(
+    #       url: "redis://localhost:6379/0",
+    #       namespace: "app_x",
+    #       pool_size: 10,
+    #     ),
+    #     expires: 60,
+    #     ...
+    #   )
+    #
+    # The instance is a Moneta-compatible store (it delegates the four
+    # methods the Faraday caching middleware uses — `[]`, `key?`,
+    # `delete`, `store` — to a pooled backend), so it can be passed
+    # directly to `Parse.setup(cache:)` / `Parse::Client.new(cache:)`.
+    class Redis
+      # @return [String, nil] cache key namespace prefix (or nil if not set).
+      attr_reader :namespace
+
+      # @return [Integer] pool size.
+      attr_reader :pool_size
+
+      # @return [String] Redis connection URL.
+      attr_reader :url
+
+      # @param url [String] Redis URL (e.g. `"redis://localhost:6379/0"`).
+      # @param namespace [String, nil] optional key prefix so multiple Parse
+      #   apps can share one Redis without colliding. When non-nil, the
+      #   namespace is automatically forwarded to the caching middleware
+      #   as `cache_namespace:`.
+      # @param pool_size [Integer] number of pooled Moneta-Redis stores.
+      #   Defaults to 5 (the Puma default thread count).
+      #
+      #   **Sizing math (per Faraday request):**
+      #   - cache hit: `key?` + `[]` = **2 checkouts**
+      #   - GET miss + successful store: `key?` + 3 variant deletes
+      #     (anonymous + master-key sibling + final key) + 1 `store` in
+      #     `on_complete` = **up to 5 checkouts**
+      #   - non-GET write (POST/PUT/DELETE): 3 variant deletes =
+      #     **3 checkouts**
+      #
+      #   The worst case (5) is on the write-through-after-miss path, not
+      #   the hit path. Rule of thumb: start at `pool_size = RAILS_MAX_THREADS`,
+      #   then bump it up if you observe `ConnectionPool::TimeoutError` in
+      #   `parse.cache.error` notifications (the middleware swallows that
+      #   error into a passthrough request rather than raising to the caller).
+      # @param pool_timeout [Numeric] seconds to wait for a backend
+      #   checkout before raising `ConnectionPool::TimeoutError`. Defaults
+      #   to 5s. The caching middleware catches that error and falls back
+      #   to a passthrough request rather than raising to the caller.
+      # @param moneta_options [Hash] extra options passed through to
+      #   `Moneta.new(:Redis, ...)` (e.g. `:db`, `:connect_timeout`).
+      #   `expires: true` is set automatically so per-key TTLs supplied
+      #   by the caching middleware (the `:expires` Faraday option) are
+      #   honored by Redis. Pass `expires: false` here to opt out — but
+      #   note that doing so causes cached responses to live forever,
+      #   which is rarely what you want for a session-token-scoped
+      #   response cache.
+      def initialize(url:, namespace: nil, pool_size: 5, pool_timeout: 5, **moneta_options)
+        @url = url
+        @namespace = normalize_namespace(namespace)
+        @pool_size = pool_size
+        @pool_timeout = pool_timeout
+        # Default expires: true so per-call `expires:` (the TTL the
+        # Faraday caching middleware passes on store) is honored. The
+        # Moneta-Redis adapter ignores per-call expires unless the
+        # store was constructed with this flag. Without it, cached
+        # session-scoped REST responses outlive their token's
+        # validity. Callers can still pass `expires: false` to opt out.
+        merged_options = { expires: true }.merge(moneta_options)
+        @moneta_options = merged_options
+        @closed = false
+        @pool = Pool.new(size: pool_size, timeout: pool_timeout) do
+          Moneta.new(:Redis, { url: url }.merge(merged_options))
+        end
+      end
+
+      def [](key)
+        @pool[key]
+      end
+
+      def key?(key)
+        @pool.key?(key)
+      end
+
+      def delete(key)
+        @pool.delete(key)
+      end
+
+      def store(key, value, options = {})
+        @pool.store(key, value, options)
+      end
+
+      # Atomic SETNX. Required so `Parse::CreateLock` can acquire
+      # cross-process locks when this wrapper is the configured cache /
+      # `synchronize_create_store`. Returns `true` only when the key did
+      # not already exist.
+      def create(key, value, options = {})
+        @pool.create(key, value, options)
+      end
+
+      # Atomic counter increment. Forwarded for Moneta surface parity.
+      def increment(key, amount = 1, options = {})
+        @pool.increment(key, amount, options)
+      end
+
+      # Clear cached entries belonging to this wrapper. Required for
+      # `Parse::Client#clear_cache!` compatibility.
+      #
+      # **Namespace-scoped when a namespace is set:** the wrapper walks
+      # `<namespace>:*` via Redis SCAN and DELs the matching keys,
+      # leaving other tenants on the same DB untouched. When no
+      # namespace is configured the wrapper falls back to `FLUSHDB` on
+      # the backing DB — same blast radius as previous versions, but
+      # only for unnamespaced deployments. To opt into the wide
+      # FLUSHDB explicitly (e.g. ops tooling), call {#flush_db!}.
+      #
+      # @param scope [String, nil] explicit namespace prefix to scan-delete.
+      #   When provided, overrides the wrapper's configured `@namespace` and
+      #   SCAN-deletes `<scope>:*` regardless of how the wrapper was built.
+      #   This is the safe escape hatch for tenants that share a non-
+      #   namespaced wrapper but still want to evict only their own keys
+      #   without `FLUSHDB`-ing siblings (and without wiping
+      #   `parse-stack:foc:v1:*` create-lock keys that live on the same DB).
+      #   The scope must be a non-empty String; the trailing `:` is added
+      #   automatically and any trailing `:` in the input is stripped so
+      #   `"tenant_x"` and `"tenant_x:"` are equivalent.
+      def clear(scope: nil)
+        if scope
+          prefix = validate_scope!(scope)
+          delete_keys_matching!("#{prefix}:*")
+        elsif @namespace
+          delete_keys_matching!("#{@namespace}:*")
+        else
+          @pool.clear
+        end
+        self
+      end
+
+      # Issue `FLUSHDB` on the backing Redis DB, regardless of whether a
+      # namespace is configured. Evicts every key on the selected DB,
+      # including unrelated tenants — use only for ops tooling that
+      # owns the whole DB.
+      def flush_db!
+        @pool.clear
+        self
+      end
+
+      # Close all pooled connections. Safe to call multiple times.
+      def close
+        return if @closed
+        @closed = true
+        @pool.close
+      end
+
+      private
+
+      def delete_keys_matching!(pattern)
+        @pool.pool.with do |store|
+          redis = backend_client(store)
+          # SCAN-DEL loop. `count:` is a hint to the server; the actual
+          # batch size returned varies. Loop until the cursor wraps back
+          # to "0".
+          cursor = "0"
+          loop do
+            cursor, keys = redis.scan(cursor, match: pattern, count: 1000)
+            redis.del(*keys) unless keys.empty?
+            break if cursor == "0"
+          end
+        end
+      end
+
+      def backend_client(moneta_store)
+        # Walk down the Moneta proxy chain (Expires → Adapter → redis-rb)
+        # until we reach an object that quacks like the redis-rb client
+        # (i.e. responds to #scan). Moneta wraps the actual adapter when
+        # `expires: true` is passed, and the adapter then exposes the
+        # underlying redis-rb client via `#backend` (modern releases) or
+        # the `@backend` ivar (older releases).
+        node = moneta_store
+        12.times do
+          return node if node.respond_to?(:scan)
+          if node.respond_to?(:backend)
+            node = node.backend
+          elsif node.instance_variable_defined?(:@backend)
+            node = node.instance_variable_get(:@backend)
+          elsif node.instance_variable_defined?(:@adapter)
+            node = node.instance_variable_get(:@adapter)
+          else
+            break
+          end
+          break if node.nil?
+        end
+        node
+      end
+
+      def normalize_namespace(ns)
+        s = ns.to_s.chomp(":")
+        s.empty? ? nil : s
+      end
+
+      # Validate a caller-supplied `scope:` for `clear(scope:)`. Returns the
+      # normalized prefix or raises ArgumentError. We enforce:
+      #
+      # - must be a String (Symbol / Integer / nil would silently `.to_s`
+      #   under `normalize_namespace` and expand the deletion target —
+      #   `scope: 0` would clear `0:*`)
+      # - must be non-empty after trimming a trailing `:`
+      # - must not contain Redis SCAN glob metacharacters (`*`, `?`, `[`,
+      #   `]`, `\`) — otherwise `scope: "*"` would SCAN-delete the whole
+      #   DB, defeating the whole point of having `flush_db!` as the
+      #   explicit wide-blast-radius escape hatch
+      # - must not contain a null byte (defense-in-depth against keys
+      #   crafted to terminate early in some Redis client paths)
+      GLOB_METACHARS = /[\*\?\[\]\\\x00]/.freeze
+      private_constant :GLOB_METACHARS
+
+      def validate_scope!(scope)
+        unless scope.is_a?(String)
+          raise ArgumentError, "scope: must be a String (got #{scope.class})"
+        end
+        prefix = scope.chomp(":")
+        if prefix.empty?
+          raise ArgumentError, "scope: must be a non-empty namespace string"
+        end
+        if prefix.match?(GLOB_METACHARS)
+          raise ArgumentError,
+                "scope: must not contain Redis SCAN glob characters (*, ?, [, ], \\, or NUL); " \
+                "use flush_db! for a full-DB flush"
+        end
+        prefix
+      end
+    end
+  end
+end

data/lib/parse/client/body_builder.rb

@@ -48,6 +48,26 @@ module Parse
       SENSITIVE_FIELDS_SET = SENSITIVE_FIELDS.map(&:downcase).to_set.freeze
       # Placeholder used in place of redacted values.
       REDACTED_PLACEHOLDER = "[FILTERED]"
+      # Minimum length at which a numeric-only Array in a logged JSON
+      # body is compacted to a single placeholder string instead of
+      # printed verbatim. Two concerns drive this:
+      #
+      # 1. **Noise.** A 1536-float OpenAI embedding inlines as ~25 KB of
+      #    JSON per logged row. Aggregation pipelines with
+      #    `$vectorSearch.queryVector` and any save/fetch carrying a
+      #    `:vector` field would otherwise drown operator logs.
+      # 2. **Sensitivity.** Embeddings are reversible-by-similarity:
+      #    an attacker who scrapes operator logs can reconstruct
+      #    high-level features of the source text (topic, sentiment,
+      #    sometimes near-verbatim phrases for short inputs) by
+      #    nearest-neighbor lookup against a public model.
+      #
+      # Threshold rationale: 32 is well below every common embedding
+      # width (BGE-small 384, Cohere 1024, OpenAI small 1536, OpenAI
+      # large 3072) and well above any normal Parse Array property
+      # (tags, role lists, etc.). Numeric-only check additionally
+      # protects normal long arrays of strings/objects.
+      LOG_VECTOR_COMPACT_THRESHOLD = 32
       # Request headers that must never be printed verbatim in debug logs.
       # Matched case-insensitively against Faraday header keys.
       REDACTED_HEADERS = [
@@ -57,6 +77,31 @@ module Parse
         "X-Parse-JavaScript-Key",
         "Authorization",
         "Cookie",
+        # Embedding-provider credentials (Parse::Embeddings::OpenAI and
+        # forthcoming Cohere/Voyage adapters). These never touch Parse
+        # Server itself, but they share the same Faraday log path when a
+        # caller mounts the embeddings connection through Parse logging.
+        # OpenAI's official auth header is `Authorization: Bearer …`
+        # (already covered above); Organization/Project are listed here
+        # since they're account-identifying metadata operators may not
+        # want to publish. `X-Api-Key` and `Anthropic-Api-Key` are
+        # reserved for forthcoming non-OpenAI providers.
+        "X-Api-Key",
+        "OpenAI-Organization",
+        "OpenAI-Project",
+        "Anthropic-Api-Key",
+        # Cohere, Voyage, Jina, and DashScope (Qwen) use Bearer auth
+        # (covered by "Authorization" above), but some operators front
+        # them with a proxy that rewrites to a vendor-specific header.
+        # These are listed defensively so a future header-form switch
+        # doesn't silently leak keys into Faraday logs. `Api-Key` is the
+        # bare form some vendor SDKs and proxies use; covered for parity.
+        "Cohere-Api-Key",
+        "Voyage-Api-Key",
+        "Jina-Api-Key",
+        "Api-Key",
+        "X-DashScope-Api-Key",
+        "DashScope-Api-Key",
       ].map(&:downcase).freeze
 
       class << self
@@ -91,6 +136,7 @@ module Parse
         after_structural = s
         if (parsed = try_parse_json(s))
           scrubbed = scrub_sensitive!(parsed)
+          compact_vectors!(scrubbed)
           begin
             after_structural = scrubbed.to_json
           rescue StandardError
@@ -160,12 +206,60 @@ module Parse
         node
       end
 
+      # @!visibility private
+      # Recursively walk a parsed JSON structure replacing any
+      # numeric-only Array of length >= +LOG_VECTOR_COMPACT_THRESHOLD+
+      # with a compact placeholder string ("<vector dims=N>"). Mutates
+      # Hashes/Arrays in place; returns the node for chaining. Distinct
+      # pass from {scrub_sensitive!} because the criterion is shape
+      # (numeric array width), not key name.
+      #
+      # The walker does NOT descend into the replaced array — once a
+      # node is recognised as a vector its inner Numerics aren't of
+      # interest. Nested vectors (Array<Array<Numeric>>, e.g. a batched
+      # embedding response in a logged HTTP body) are caught at the
+      # inner array level on the next recursion.
+      def self.compact_vectors!(node)
+        case node
+        when Hash
+          node.each do |key, value|
+            if vector_shape?(value)
+              node[key] = "<vector dims=#{value.length}>"
+            elsif value.is_a?(Hash) || value.is_a?(Array)
+              compact_vectors!(value)
+            end
+          end
+        when Array
+          node.each_with_index do |item, i|
+            if vector_shape?(item)
+              node[i] = "<vector dims=#{item.length}>"
+            elsif item.is_a?(Hash) || item.is_a?(Array)
+              compact_vectors!(item)
+            end
+          end
+        end
+        node
+      end
+
+      # @!visibility private
+      # An Array is "vector-shaped" if it meets the compaction threshold
+      # AND every element is Numeric. The numeric check prevents long
+      # tag arrays / role lists / mixed-type arrays from being mangled.
+      # Boolean is not Numeric in Ruby, so an array of booleans (rare
+      # but possible) is left alone — also fine.
+      def self.vector_shape?(val)
+        return false unless val.is_a?(Array)
+        return false if val.length < LOG_VECTOR_COMPACT_THRESHOLD
+        val.all? { |x| x.is_a?(Numeric) }
+      end
+
       # @!visibility private
       # If +str+ parses as JSON (object or array), scrub structurally and
       # re-encode. Otherwise return the original string unchanged.
       def self.maybe_scrub_embedded_json(str)
         return str unless (inner = try_parse_json(str))
         scrub_sensitive!(inner)
+        compact_vectors!(inner)
         begin
           inner.to_json
         rescue StandardError