parse-stack-next 5.5.4 → 5.5.5

data/lib/parse/client/url_redaction.rb

@@ -0,0 +1,94 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  module Middleware
+    # Shared query-string credential redactor for the logging and
+    # profiling middlewares. Kept in ONE place so the two sanitizers
+    # cannot drift — a credential that leaks through one but not the
+    # other is exactly the failure mode this consolidation prevents.
+    #
+    # The previous per-middleware sanitizer only redacted three exact
+    # param names (`sessionToken` / `masterKey` / `apiKey`). A credential
+    # carried under any other name — `token`, `access_token`,
+    # `client_secret`, `password`, a CloudFront `Signature` /
+    # `Key-Pair-Id`, an S3 `X-Amz-Signature`, etc. — sailed through into
+    # logs and `Parse.recent_profiles`. This redacts the VALUE of any
+    # query param whose name looks credential-bearing, while leaving the
+    # known-safe Parse query params (and other non-sensitive params)
+    # visible for debuggability.
+    module URLRedaction
+      # Parse (and a couple of CloudFront) query params that contain a
+      # sensitive-looking substring but are NOT secrets — protect them
+      # from over-redaction. Compared case-insensitively.
+      SAFE_QUERY_PARAMS = %w[
+        keys
+        excludekeys
+        redirectclassnameforkey
+      ].freeze
+
+      # A query param whose (case-insensitive) name matches this is
+      # treated as credential-bearing and has its value replaced with
+      # +[FILTERED]+, unless the name is in {SAFE_QUERY_PARAMS}.
+      SENSITIVE_NAME = /(?:token|key|secret|password|passwd|pwd|signature|\bsig\b|auth|credential|policy)/i
+
+      REDACTED = "[FILTERED]"
+
+      module_function
+
+      # @param url [String, #to_s] a request URL (with or without a query string)
+      # @return [String] the URL with credential-bearing query values redacted
+      def sanitize(url)
+        str = url.to_s
+        # Possessive quantifiers (`++` / `*+`) so the param-name and value
+        # runs never backtrack: on a pathological URL (a long run of
+        # non-delimiter chars with no `=`) the greedy form would rescan
+        # super-linearly (polynomial ReDoS on caller-supplied URLs flowing
+        # into log/profile redaction). The excluded-delimiter classes make
+        # the match unambiguous, so possessive matching is identical to the
+        # greedy match for every real query string.
+        str.gsub(/([?&])([^=&#]++)=([^&#]*+)/) do
+          sep = Regexp.last_match(1)
+          name = Regexp.last_match(2)
+          value = Regexp.last_match(3)
+          if sensitive?(name)
+            "#{sep}#{name}=#{REDACTED}"
+          else
+            "#{sep}#{name}=#{value}"
+          end
+        end
+      end
+
+      # @param name [String] a raw (possibly percent-encoded) query-param name
+      # @return [Boolean]
+      def sensitive?(name)
+        decoded = decode_name(name)
+        return false if SAFE_QUERY_PARAMS.include?(decoded.downcase)
+        !SENSITIVE_NAME.match(decoded).nil?
+      end
+
+      # Percent-decode a query-param NAME so a credential carried under an
+      # encoded name is matched by its decoded spelling. Servers decode
+      # `session%54oken` to `sessionToken` before reading it, so matching
+      # the raw name alone lets an encoded credential name slip past
+      # redaction.
+      #
+      # ONLY ASCII escapes (`%00`–`%7F`, i.e. first hex digit 0–7) are
+      # decoded. Credential keywords are ASCII, so that is sufficient — and
+      # decoding a high byte (`%C3`, `%FF`) would splice a lone
+      # continuation/lead byte into the (UTF-8) name and yield an
+      # invalid-encoding string that raises in the downstream `#downcase` /
+      # `#match`. High-byte escapes are therefore left literal. `+` and
+      # other bytes are untouched (param names don't use form-encoding).
+      # The decoded form is used ONLY for the sensitivity decision;
+      # {.sanitize} still emits the original spelling.
+      #
+      # @param name [String] a raw query-param name
+      # @return [String] the ASCII-percent-decoded name (always valid if
+      #   +name+ was)
+      def decode_name(name)
+        name.gsub(/%([0-7][0-9A-Fa-f])/) { Regexp.last_match(1).to_i(16).chr }
+      end
+    end
+  end
+end

data/lib/parse/client.rb

@@ -183,7 +183,7 @@ module Parse
   # application_id or REST key. A server with a mistyped app_id still returns
   # `true` here; use {.connected?} when you also need to validate credentials.
   # @param conn [Symbol] the named client connection to probe. Defaults to :default.
-  # @return [Boolean] +true+ if the server responded with status "ok", +false+
+  # @return [Boolean] `true` if the server responded with status "ok", `false`
   #   if the server is unreachable or returned an unexpected response.
   def self.reachable?(conn = :default)
     client(conn).reachable?
@@ -193,18 +193,18 @@ module Parse
 
   # Check that the Parse Server is reachable and responding.
   # By default this probes the credential-less health endpoint, so it returns
-  # +true+ whenever the server is up (it does NOT, by itself, validate the
+  # `true` whenever the server is up (it does NOT, by itself, validate the
   # application_id or REST key — see {Parse::Client#connected?} for why a
   # data-class probe is unreliable on a hardened server). Pass an `endpoint`
   # (e.g. `"classes/_User"`) to additionally exercise the auth stack against a
   # class you know the configured key can read; a bad key then surfaces as an
   # {Parse::Error::AuthenticationError} at the instance level, which the
-  # instance method converts to +false+. Any other failure is caught by this
-  # module-boundary rescue and converted to +false+.
+  # instance method converts to `false`. Any other failure is caught by this
+  # module-boundary rescue and converted to `false`.
   # @param conn [Symbol] the named client connection to probe. Defaults to :default.
   # @param endpoint [String, nil] optional path to probe instead of the health
   #   endpoint, to validate credentials against a readable class.
-  # @return [Boolean] +true+ if the server is reachable (and, when an endpoint
+  # @return [Boolean] `true` if the server is reachable (and, when an endpoint
   #   is given, the credentials are accepted).
   def self.connected?(conn = :default, endpoint = nil)
     client(conn).connected?(endpoint)
@@ -349,7 +349,7 @@ module Parse
 
     # A NEW non-master {Parse::Client} that mirrors THIS client's connection
     # settings (`server_url` / `application_id` / `api_key`) but carries no
-    # master key and binds +session_token+, so it acts on the server as that
+    # master key and binds `session_token`, so it acts on the server as that
     # user (ACL / CLP / `protectedFields` enforced, no master-key fallback).
     # This is the general primitive behind {Parse::Webhooks::Payload#user_client}
     # and {Parse::User#session_client}: derive a user-scoped client from a
@@ -952,11 +952,11 @@ module Parse
     end
 
     # No-credentials liveness probe. Hits the Parse Server health endpoint and
-    # returns +true+ when the server responds with status "ok". No application
+    # returns `true` when the server responds with status "ok". No application
     # credentials are required, so this passes even when the configured
     # application_id or REST key is wrong. Use {#connected?} to also validate
     # credentials.
-    # @return [Boolean] +true+ if the server is up and returned a healthy status.
+    # @return [Boolean] `true` if the server is up and returned a healthy status.
     def reachable?
       response = request(:get, Parse::API::Server::SERVER_HEALTH_PATH, opts: { cache: false })
       response.success?
@@ -965,11 +965,11 @@ module Parse
     end
 
     # Connectivity probe. By default hits the Parse Server health endpoint —
-    # the same target as {#reachable?} — so it returns +true+ whenever the
+    # the same target as {#reachable?} — so it returns `true` whenever the
     # server is up, regardless of CLP configuration.
     #
-    # Why not a `_User` find? A limit-0 find against +_User+ exercises the auth
-    # stack, but locking +_User+ finds to the master key via a Class-Level
+    # Why not a `_User` find? A limit-0 find against `_User` exercises the auth
+    # stack, but locking `_User` finds to the master key via a Class-Level
     # Permission is standard production hardening — on such a server the probe
     # gets a permission error and (wrongly) reports "not connected" for a
     # perfectly healthy, correctly-configured deployment. The default therefore
@@ -980,12 +980,12 @@ module Parse
     # server, or one of your own readable classes). The probe runs `limit: 0`
     # so it never pulls rows, and routes through the auth middleware, so a wrong
     # application_id / REST key surfaces as an {Parse::Error::AuthenticationError}
-    # and is converted to +false+. Any connection, timeout, or API error returns
-    # +false+ rather than raising; genuine programming errors (e.g.
-    # +NoMethodError+) still propagate.
+    # and is converted to `false`. Any connection, timeout, or API error returns
+    # `false` rather than raising; genuine programming errors (e.g.
+    # `NoMethodError`) still propagate.
     # @param endpoint [String, nil] optional path to probe instead of the
     #   health endpoint, to validate credentials against a readable class.
-    # @return [Boolean] +true+ if the server is reachable (and, when an endpoint
+    # @return [Boolean] `true` if the server is reachable (and, when an endpoint
     #   is given, the credentials are accepted).
     def connected?(endpoint = nil)
       path = endpoint || Parse::API::Server::SERVER_HEALTH_PATH
@@ -1136,7 +1136,19 @@ module Parse
         headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
       end
 
-      token = opts[:session_token]
+      raw_token = opts[:session_token]
+      # SEC-02: an EXPLICITLY-supplied session_token that is a blank /
+      # whitespace-only string is an unusable credential — NOT an invitation
+      # to fall back to the master key. Treat it as "no credential"
+      # (anonymous) and fail closed: suppress the master key and send no
+      # session header, so Parse Server applies public ACL/CLP instead of
+      # silently executing with master authority. The caller passed a token
+      # explicitly, so we also do NOT fall through to the ambient / bound
+      # token — that was their stated (empty) scope. `session_token: nil`
+      # (value literally nil) is unchanged: it means "not set", and still
+      # resolves via the ambient / bound fallback below.
+      explicit_blank_token = raw_token.is_a?(String) && raw_token.strip.empty?
+      token = explicit_blank_token ? nil : raw_token
       # When no explicit token was passed AND the caller didn't ask to send
       # the master key, fall through to (in order) the fiber-local ambient set
       # by `Parse.with_session`, then this client's own bound `@session_token`.
@@ -1145,7 +1157,7 @@ module Parse
       # nested inside a `with_session(user)` block (or on a token-bound client)
       # would silently downgrade. The ambient wins over the bound token so a
       # `with_session` override inside a user-scoped client still takes effect.
-      if token.nil? && !(explicit_master && opts[:use_master_key] == true)
+      if token.nil? && !explicit_blank_token && !(explicit_master && opts[:use_master_key] == true)
         ambient = Parse.current_session_token
         # A whitespace-only ambient must not count as present: otherwise it
         # blocks the bound-token fallback below and then fails the later
@@ -1153,7 +1165,10 @@ module Parse
         token = ambient if ambient.is_a?(String) && !ambient.strip.empty?
         token = @session_token if (token.nil? || token.to_s.strip.empty?) && @session_token
       end
-      if token.present?
+      if explicit_blank_token
+        # Fail closed: never send the master key for an unusable explicit token.
+        headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
+      elsif token.present?
         token = token.session_token if token.respond_to?(:session_token)
         headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
         headers[Parse::Protocol::SESSION_TOKEN] = token
@@ -1444,18 +1459,18 @@ module Parse
   #
   # SECURITY — cloud results are treated as server-authoritative. The
   # `__type:"Object"` decode in {._decode_cloud_value} routes through
-  # +Parse::Object.build+, which hydrates with trusted-init — the SAME path
-  # used to decode every query / +.fetch+ result. Trusted-init skips the
-  # +PROTECTED_INITIALIZE_KEYS+ filter, so credential-shaped keys
-  # (+sessionToken+, +authData+, +_rperm+, +_wperm+, +roles+, …) present in a
+  # `Parse::Object.build`, which hydrates with trusted-init — the SAME path
+  # used to decode every query / `.fetch` result. Trusted-init skips the
+  # `PROTECTED_INITIALIZE_KEYS` filter, so credential-shaped keys
+  # (`sessionToken`, `authData`, `_rperm`, `_wperm`, `roles`, …) present in a
   # cloud function's return value populate the in-memory object, exactly as they
   # do for any other server response. This is by design: the payload is authored
   # by your Cloud Code and the request is caller-authenticated, and making cloud
   # results filter these keys would make them inconsistent with (and stricter
-  # than) query/+.fetch+ hydration — e.g. a cloud function returning
-  # +request.user+ would come back missing its +sessionToken+. If a cloud
+  # than) query/`.fetch` hydration — e.g. a cloud function returning
+  # `request.user` would come back missing its `sessionToken`. If a cloud
   # function is expected to echo back third-party-influenced data, call it with
-  # +raw: true+ (+Parse.call_function(name, body, raw: true)+) to receive the
+  # `raw: true` (`Parse.call_function(name, body, raw: true)`) to receive the
   # undecoded response and sanitize it yourself before building objects.
   def self._extract_cloud_result(response)
     r = response.result
@@ -1568,7 +1583,7 @@ module Parse
   # @option opts [Boolean] :raw Whether to return the raw response object.
   # @option opts [Boolean] :master_key Whether to use the master key for this request.
   # @option opts [Hash, nil] :context An optional caller context forwarded as the
-  #   +X-Parse-Cloud-Context+ header. Parse Server maps it to +req.info.context+
+  #   `X-Parse-Cloud-Context` header. Parse Server maps it to `req.info.context`
   #   in the function handler and flows it through beforeSave/afterSave triggers.
   # @return [Object] the result data of the response. nil if there was an error.
   def self.call_function(name, body = {}, **opts)
@@ -1600,8 +1615,8 @@ module Parse
   # specific {Parse::Error} subclasses as the underlying client does.
   # @param name (see Parse.call_function)
   # @param body (see Parse.call_function)
-  # @param opts (see Parse.call_function) — +:raw+ has no effect; this method
-  #   always decodes the result. Use {Parse.call_function} with +raw: true+ if
+  # @param opts (see Parse.call_function) — `:raw` has no effect; this method
+  #   always decodes the result. Use {Parse.call_function} with `raw: true` if
   #   you need the undecoded response.
   # @raise [Parse::Error::CloudCodeError] when the response indicates a cloud-code error.
   # @return [Object] the result data of the response.

data/lib/parse/embeddings/image_fetch.rb

@@ -141,7 +141,12 @@ module Parse
         canonical = Parse::Embeddings.validate_image_url!(
           url, allow_insecure: allow_insecure, mode: :fetch,
         )
-        io = Parse::File.safe_open_url(canonical)
+        # Push `max_bytes` INTO the fetch so the download aborts mid-stream
+        # once the cap is exceeded, rather than buffering the whole
+        # (globally-capped) body first and rejecting after. The post-read
+        # check below is retained as belt-and-suspenders for transports
+        # that can't enforce the streaming cap.
+        io = Parse::File.safe_open_url(canonical, max_bytes: max_bytes)
         begin
           bytes = io.read
         ensure

data/lib/parse/embeddings/voyage.rb

@@ -10,8 +10,8 @@ module Parse
   module Embeddings
     # Voyage AI embeddings provider. Wraps `POST /v1/embeddings` for
     # text-only models and `POST /v1/multimodalembeddings` for the
-    # multimodal text+image models (text-input path only in v5.0; the
-    # image-input path lands with {Provider#embed_image} in v5.1).
+    # multimodal text+image models (text via {#embed_text}, images via
+    # {#embed_image}).
     #
     # Supported models:
     #
@@ -23,13 +23,13 @@ module Parse
     #   `voyage-code-3`.
     # * **domain models** — `voyage-finance-2`, `voyage-law-2`.
     # * **multimodal** — `voyage-multimodal-3` (1024-dim). Unified
-    #   text+image vector space at the network boundary. This provider
-    #   exposes the text-input path only: routes to
-    #   `/v1/multimodalembeddings` with a `{ inputs: [{ content:
-    #   [{ type: "text", text: … }] }] }` envelope. The same model will
-    #   accept image inputs in v5.1 when the `embed_image` hook ships;
-    #   text vectors stored today will sit in the same space as the
-    #   eventual image vectors (no re-embed required).
+    #   text+image vector space at the network boundary. Text inputs
+    #   route to `/v1/multimodalembeddings` with a `{ inputs: [{ content:
+    #   [{ type: "text", text: … }] }] }` envelope; image inputs go
+    #   through {#embed_image} as `image_url` rows (provider-side fetch,
+    #   v5.1) or `image_base64` rows (SDK-fetched bytes, v5.5). Text and
+    #   image vectors share the same space, so stored text vectors are
+    #   comparable against image vectors without re-embedding.
     #
     # @example registration
     #   Parse::Embeddings.register(:voyage,
@@ -336,8 +336,8 @@ module Parse
         # Voyage caps multimodal requests at the same per-request size
         # as the text endpoint. The text path goes through
         # `embed_text_batched` which chunks automatically; the image
-        # path has no chunker yet (every directive is a single URL in
-        # v5.1), so guard the direct-API caller against a silent 400.
+        # path has no chunker yet (every directive is a single image
+        # source), so guard the direct-API caller against a silent 400.
         if sources.length > @embed_batch_size
           raise ArgumentError,
                 "Parse::Embeddings::Voyage#embed_image: batch size #{sources.length} exceeds " \
@@ -432,12 +432,11 @@ module Parse
         body
       end
 
-      # Build the wire body for `/v1/multimodalembeddings`. The text
-      # path wraps each input string as a single `{type: "text", text:}`
-      # content row. Image inputs will land in v5.1 alongside
-      # {Provider#embed_image}; for now the provider is text-only and
-      # the multimodal envelope's `content` array always contains a
-      # single text row per input.
+      # Build the wire body for `/v1/multimodalembeddings` for TEXT
+      # inputs: each string wraps as a single `{type: "text", text:}`
+      # content row. Image inputs build their content rows inline in
+      # {#embed_image} (`image_url` / `image_base64`) and do not pass
+      # through here.
       def build_multimodal_body(strings, wire_input_type)
         body = {
           inputs: strings.map { |s| { content: [{ type: "text", text: s }] } },

data/lib/parse/live_query/client.rb

@@ -608,11 +608,11 @@ module Parse
         end
       end
 
-      # RFC 6455 §1.3 magic GUID used to derive +Sec-WebSocket-Accept+
-      # from the client-supplied +Sec-WebSocket-Key+. Server proves it
+      # RFC 6455 §1.3 magic GUID used to derive `Sec-WebSocket-Accept`
+      # from the client-supplied `Sec-WebSocket-Key`. Server proves it
       # spoke WebSocket (and not e.g. a confused HTTP/1.1 server that
-      # happens to return +HTTP/1.1 101+) by echoing
-      # +Base64(SHA1(key || GUID))+ back to the client.
+      # happens to return `HTTP/1.1 101`) by echoing
+      # `Base64(SHA1(key || GUID))` back to the client.
       WEBSOCKET_GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11".freeze
 
       # @!visibility private
@@ -625,7 +625,7 @@ module Parse
       HANDSHAKE_PER_LINE_BYTES = 8 * 1024
 
       # Perform WebSocket handshake. Verifies the server's
-      # +Sec-WebSocket-Accept+ matches the SHA-1 of the random key +
+      # `Sec-WebSocket-Accept` matches the SHA-1 of the random key +
       # the WebSocket magic GUID, preventing cross-protocol acceptance
       # of any HTTP/1.1 101 response from a non-WebSocket server.
       def perform_handshake(host, path)
@@ -668,8 +668,8 @@ module Parse
       # @!visibility private
       # Parses and validates the server handshake response per RFC 6455 §4.1.
       # Refuses any response that does not (a) start with HTTP/1.1 101,
-      # (b) carry +Upgrade: websocket+, (c) carry +Connection: Upgrade+,
-      # and (d) carry +Sec-WebSocket-Accept: <expected>+ matching the
+      # (b) carry `Upgrade: websocket`, (c) carry `Connection: Upgrade`,
+      # and (d) carry `Sec-WebSocket-Accept: <expected>` matching the
       # client-derived value.
       def validate_handshake_response!(response, expected_accept)
         if response.empty?

data/lib/parse/live_query/subscription.rb

@@ -74,7 +74,7 @@ module Parse
       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
+      #   changed (PS 7.0+ `watch` option). `nil` means all field changes trigger
       #   update events.
       attr_reader :watch
 

data/lib/parse/lock.rb

@@ -237,7 +237,7 @@ module Parse
           # signature across the Redis and degraded paths. There is no
           # cross-process owner here — the Mutex IS the exclusion — so a
           # fresh UUID is purely for signature parity / local fencing.
-          return Parse::LockBackend.process_mutex(store_key).synchronize do
+          return Parse::LockBackend.synchronize_process_mutex(store_key) do
             yield SecureRandom.uuid
           end
         end

data/lib/parse/lock_backend.rb

@@ -40,6 +40,14 @@ module Parse
     # acquisitions are silent.
     DEGRADED_WARNING_THROTTLE_SECONDS = 60
 
+    # Upper bound on the in-process Mutex registry (degraded fallback
+    # path). Without a cap, every distinct lock key leaks a permanent
+    # Mutex — a memory-exhaustion vector when keys are high-cardinality
+    # or attacker-influenced. Real deployments use a handful of lock
+    # keys, so this ceiling is far above normal use and only bites a
+    # runaway/abusive caller.
+    PROCESS_MUTEX_REGISTRY_MAX = 4096
+
     class << self
       # Find the Moneta store the lock should write through. Resolved
       # at call time (not memoized) so a test or an operator can swap
@@ -182,22 +190,129 @@ module Parse
         DEFAULT_POLL_BASE + (rand * 2 - 1) * DEFAULT_POLL_JITTER
       end
 
+      # Run `block` while holding the per-key in-process Mutex for the
+      # degraded fallback path, safe against registry eviction. This is
+      # the API callers should use — NOT the bare {.process_mutex}
+      # accessor.
+      #
+      # {.process_mutex} returns an *unlocked* Mutex; there is a window
+      # between the accessor returning and the caller reaching
+      # `Mutex#synchronize`. Under registry saturation the approximate-LRU
+      # eviction could observe that Mutex as unlocked and reclaim it, after
+      # which a second caller mints a DISTINCT Mutex for the same key —
+      # splitting mutual exclusion. This method closes the window by
+      # registering the caller as a *pending acquirer* inside the same
+      # critical section that hands out the Mutex, and eviction never
+      # reclaims a key with pending acquirers (or a locked Mutex).
+      #
+      # @param key [String] cache key.
+      # @yield executed while holding the per-key Mutex.
+      # @return the block's return value.
+      def synchronize_process_mutex(key, &block)
+        mutex = checkout_process_mutex(key)
+        begin
+          mutex.synchronize(&block)
+        ensure
+          checkin_process_mutex(key)
+        end
+      end
+
       # Per-key in-process Mutex registry for the degraded fallback
       # path. The first acquisition for a given key creates the
       # Mutex; subsequent acquisitions reuse it. Registry itself is
       # guarded by a tiny outer Mutex so two threads racing the
       # first acquisition of the same key get the same Mutex.
       #
+      # The registry is bounded at {PROCESS_MUTEX_REGISTRY_MAX} entries
+      # via approximate-LRU eviction: reused keys move to the MRU end,
+      # and when a new key would overflow the cap the oldest evictable
+      # mutexes are dropped first. A Mutex is evictable only when it is
+      # neither locked NOR reserved by a pending acquirer (see
+      # {.synchronize_process_mutex}); dropping either would let a
+      # concurrent acquisition mint a fresh Mutex for the same key and
+      # split mutual exclusion. Under pathological all-in-use saturation
+      # the registry may briefly exceed the cap rather than break
+      # correctness.
+      #
+      # NOTE: a Mutex handed back here is eligible for eviction until it is
+      # locked. Callers that lock it later (rather than immediately) must
+      # go through {.synchronize_process_mutex}, which reserves the key.
+      #
       # @param key [String] cache key.
       # @return [Mutex]
       def process_mutex(key)
+        @process_mutex_registry_lock ||= Mutex.new
+        @process_mutex_registry_lock.synchronize { registry_get_or_create(key) }
+      end
+
+      # @api private
+      # Atomically get-or-create the per-key Mutex AND reserve it for the
+      # caller (pending-acquirer count += 1) so eviction cannot reclaim it
+      # before the caller locks it. MUST be balanced by
+      # {.checkin_process_mutex} in an `ensure`.
+      #
+      # @param key [String] cache key.
+      # @return [Mutex]
+      def checkout_process_mutex(key)
         @process_mutex_registry_lock ||= Mutex.new
         @process_mutex_registry_lock.synchronize do
-          @process_mutex_registry ||= {}
-          @process_mutex_registry[key] ||= Mutex.new
+          mutex = registry_get_or_create(key)
+          pending = (@process_mutex_pending ||= Hash.new(0))
+          pending[key] += 1
+          mutex
         end
       end
 
+      # @api private
+      # Release a pending-acquirer reservation taken by
+      # {.checkout_process_mutex}.
+      #
+      # @param key [String] cache key.
+      # @return [void]
+      def checkin_process_mutex(key)
+        @process_mutex_registry_lock ||= Mutex.new
+        @process_mutex_registry_lock.synchronize do
+          pending = (@process_mutex_pending ||= Hash.new(0))
+          if pending.key?(key)
+            pending[key] -= 1
+            pending.delete(key) if pending[key] <= 0
+          end
+        end
+      end
+
+      # @api private
+      # Get-or-create + approximate-LRU eviction. MUST be called with
+      # `@process_mutex_registry_lock` already held (all three public
+      # entry points synchronize on it before calling in).
+      #
+      # @param key [String] cache key.
+      # @return [Mutex]
+      def registry_get_or_create(key)
+        reg = (@process_mutex_registry ||= {})
+
+        if (existing = reg[key])
+          # Move to the MRU end so the eviction scan treats it as
+          # recently used (Ruby Hashes preserve insertion order).
+          reg.delete(key)
+          reg[key] = existing
+          return existing
+        end
+
+        if reg.size >= PROCESS_MUTEX_REGISTRY_MAX
+          pending = (@process_mutex_pending ||= Hash.new(0))
+          reg.keys.each do |k|
+            break if reg.size < PROCESS_MUTEX_REGISTRY_MAX
+            m = reg[k]
+            # Evict only Mutexes that are neither locked nor reserved by a
+            # pending acquirer — either state means a caller is (about to
+            # be) inside it, and reclaiming would split mutual exclusion.
+            reg.delete(k) unless m.locked? || pending[k] > 0
+          end
+        end
+
+        reg[key] = Mutex.new
+      end
+
       # @return [Float] CLOCK_MONOTONIC seconds.
       def monotonic_now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -211,6 +326,7 @@ module Parse
         @degraded_warned_at = nil
         @process_mutex_registry = nil
         @process_mutex_registry_lock = nil
+        @process_mutex_pending = nil
         @auto_secret = nil
         @plain_sha_warned = nil
       end

data/lib/parse/model/acl.rb

@@ -178,8 +178,8 @@ module Parse
       ACL::Permission.new(read, write)
     end
 
-    # Build a MongoDB +$match+-shaped predicate that matches documents
-    # readable by any of +permissions+. The canonical shape Parse
+    # Build a MongoDB `$match`-shaped predicate that matches documents
+    # readable by any of `permissions`. The canonical shape Parse
     # Server enforces at the REST/SDK layer:
     #
     #   { "$or" => [
@@ -187,27 +187,27 @@ module Parse
     #       { "_rperm" => { "$exists" => false } }
     #   ]}
     #
-    # The +$exists: false+ branch is mandatory. Parse Server treats a
-    # missing +_rperm+ field as publicly readable (the field is only
+    # The `$exists: false` branch is mandatory. Parse Server treats a
+    # missing `_rperm` field as publicly readable (the field is only
     # written when an ACL exists), so dropping that branch silently
     # hides every public document.
     #
     # Used by:
     #   * {Parse::Query::ACLReadableByConstraint} and
     #     {Parse::Query::ACLReadableByRoleConstraint} to compile
-    #     +:ACL.readable_by+ / +:ACL.readable_by_role+ query
+    #     `:ACL.readable_by` / `:ACL.readable_by_role` query
     #     constraints into aggregation pipelines.
-    #   * {Parse::AtlasSearch} to enforce ACL on +$search+ pipelines
+    #   * {Parse::AtlasSearch} to enforce ACL on `$search` pipelines
     #     that bypass Parse Server and query MongoDB directly.
     #
     # @param permissions [Array<String>] permission strings — user
-    #   objectIds, +"role:RoleName"+, or +"*"+ for public.
-    # @param include_public [Boolean] when +true+ (default), +"*"+ is
-    #   appended to +permissions+ if missing. Set +false+ for a
-    #   strict-permissions check (e.g., +:ACL.readable_by => "none"+
+    #   objectIds, `"role:RoleName"`, or `"*"` for public.
+    # @param include_public [Boolean] when `true` (default), `"*"` is
+    #   appended to `permissions` if missing. Set `false` for a
+    #   strict-permissions check (e.g., `:ACL.readable_by => "none"`
     #   semantics).
-    # @return [Hash] a MongoDB +$or+ subexpression suitable for use
-    #   inside a +$match+ stage.
+    # @return [Hash] a MongoDB `$or` subexpression suitable for use
+    #   inside a `$match` stage.
     # @example
     #   permissions = ["*", user.id] + user.acl_roles.to_a.map { |n| "role:#{n}" }
     #   pipeline << { "$match" => Parse::ACL.read_predicate(permissions) }
@@ -215,13 +215,13 @@ module Parse
       permission_predicate("_rperm", permissions, include_public: include_public, include_missing: include_missing)
     end
 
-    # Build a MongoDB +$match+-shaped predicate that matches documents
-    # writable by any of +permissions+. Mirrors {.read_predicate} on
-    # the +_wperm+ field. See {.read_predicate} for the shape and the
-    # significance of the +$exists: false+ branch.
+    # Build a MongoDB `$match`-shaped predicate that matches documents
+    # writable by any of `permissions`. Mirrors {.read_predicate} on
+    # the `_wperm` field. See {.read_predicate} for the shape and the
+    # significance of the `$exists: false` branch.
     # @param permissions [Array<String>] permission strings.
-    # @param include_public [Boolean] whether to append +"*"+.
-    # @return [Hash] a MongoDB +$or+ subexpression.
+    # @param include_public [Boolean] whether to append `"*"`.
+    # @return [Hash] a MongoDB `$or` subexpression.
     def self.write_predicate(permissions, include_public: true, include_missing: true)
       permission_predicate("_wperm", permissions, include_public: include_public, include_missing: include_missing)
     end
@@ -229,15 +229,15 @@ module Parse
     # @!visibility private
     # Shared implementation for {.read_predicate} and {.write_predicate}.
     # Normalizes the permissions array (string-coerced, deduplicated,
-    # +"*"+ appended when +include_public+) and returns the +$or+
+    # `"*"` appended when `include_public`) and returns the `$or`
     # subexpression.
     # @param include_missing [Boolean] when true (default), append the
-    #   +{ field => { "$exists" => false } }+ branch so a missing
-    #   +_rperm+/+_wperm+ (treated as public by Parse Server) also matches.
+    #   `{ field => { "$exists" => false } }` branch so a missing
+    #   `_rperm`/`_wperm` (treated as public by Parse Server) also matches.
     #   Set false for an EXACT match that requires the column to be present
-    #   and to contain one of +permissions+ (the strict/`readable_by_exact`
-    #   surface). When false and only the +$in+ branch remains, the +$or+
-    #   wrapper is dropped for a cleaner +{ field => { "$in" => perms } }+.
+    #   and to contain one of `permissions` (the strict/`readable_by_exact`
+    #   surface). When false and only the `$in` branch remains, the `$or`
+    #   wrapper is dropped for a cleaner `{ field => { "$in" => perms } }`.
     def self.permission_predicate(field, permissions, include_public: true, include_missing: true)
       perms = Array(permissions).map(&:to_s).reject(&:empty?).uniq
       perms << "*" if include_public && !perms.include?("*")