parse-stack-next 5.7.6 → 5.8.1

data/lib/parse/client.rb

@@ -53,8 +53,22 @@ module Parse
     # An error when the Parse server returned invalid code.
     class ServerError < Error; end
 
-    # An error when a Parse server responds with HTTP 500.
-    class ServiceUnavailableError < Error; end
+    # An error when a Parse server (or a gateway in front of it) responds
+    # with HTTP 500, 502, 503, or 504.
+    class ServiceUnavailableError < Error
+      # @return [Parse::Response, nil] the response that raised the error.
+      attr_reader :response
+
+      def initialize(message = nil)
+        @response = message if message.is_a?(Parse::Response)
+        super
+      end
+
+      # @return [Integer, nil] the HTTP status of the response, when known.
+      def http_status
+        @response&.http_status&.to_i
+      end
+    end
 
     # An error when the authentication credentials in the request are invalid.
     class AuthenticationError < Error; end
@@ -269,6 +283,14 @@ module Parse
     DEFAULT_RETRIES = 2
     # The wait time in seconds between retries
     RETRY_DELAY = 1.5
+    # SDK-internal value for the `metadata_master:` request option. A request
+    # that passes it together with `use_master_key: true` reads metadata (a
+    # class schema, the role graph) and keeps the master key inside
+    # {Parse.without_master_key}. Only this exact object turns it on.
+    # @!visibility private
+    METADATA_MASTER_REQUEST = Object.new.tap do |o|
+      def o.inspect = "#<Parse::Client::METADATA_MASTER_REQUEST>"
+    end.freeze
 
     # An error when a general response error occurs when communicating with Parse server.
     class ResponseError < Parse::Error; end
@@ -446,12 +468,10 @@ module Parse
     #
     #   total = Parse::User.login(u, p).with_session { Post.count }   # readable Posts only
     #
-    # Scopes REST-routed operations (`find` / `get` / `count` / `save`). It does
-    # NOT scope mongo-direct queries (`results_direct`, `aggregate`, Atlas
-    # search): those resolve auth from the query's own `session_token:` /
-    # `acl_user:` and, absent that, run in MASTER mode — so a mongo-direct read
-    # inside this block is a full master read, not anonymous. Scope mongo-direct
-    # explicitly with a per-query `session_token:` or a scoped {Parse::Agent}.
+    # Scopes REST-routed operations (`find` / `get` / `count` / `save`) and
+    # mongo-direct reads (`results_direct`, `count_direct`, Atlas Search), which
+    # resolve the same ambient token when the query carries no explicit
+    # `session_token:`, `acl_user:`, or `use_master_key: true`.
     #
     # @raise [ArgumentError] if this client has no bound session token (scoping
     #   would be a no-op and almost certainly a mistake).
@@ -1098,6 +1118,22 @@ module Parse
       @retry_limit
     end
 
+    # The longest one request through {#request} can take, in seconds,
+    # counting every retry attempt at its full open and read timeout plus
+    # the largest retry backoff. A server-supplied Retry-After is not
+    # included. Used to size locks that must be held across a request.
+    # @return [Float]
+    def request_time_budget
+      options = @conn.respond_to?(:options) ? @conn.options : nil
+      read = options.respond_to?(:timeout) ? options.timeout.to_f : 0.0
+      open = options.respond_to?(:open_timeout) ? options.open_timeout.to_f : 0.0
+      read = 30.0 if read <= 0
+      open = 5.0 if open <= 0
+      retries = [retry_limit.to_i, 0].max
+      backoff = (1..retries).sum { |attempt| RETRY_DELAY * attempt * 1.25 }
+      (open + read) * (retries + 1) + backoff
+    end
+
     # @return [String] the url prefix of the Parse Server url.
     def url_prefix
       @conn.url_prefix
@@ -1221,6 +1257,15 @@ module Parse
       _retry_count = nil
       _retry_delay = nil
       _request = nil
+      # A Parse::Request carries its own per-request options (session_token,
+      # use_master_key, cache, retry, ...). Merge them in before anything
+      # below reads `opts`, or the auth resolution never sees them and a
+      # request built for a session with `use_master_key: false` still goes
+      # out with the configured master key. Options passed to this call
+      # directly win over the request's own.
+      if method.is_a?(Request) && method.opts.is_a?(Hash) && !method.opts.empty?
+        opts = method.opts.merge(opts.is_a?(Hash) ? opts : {})
+      end
       # Kwarg-absorption guard. The `**opts` splat in API helper methods
       # (lib/parse/api/*.rb) absorbs a caller-passed `opts: { ... }`
       # keyword as a key named `:opts` rather than as the request options
@@ -1244,10 +1289,12 @@ module Parse
       # attempt, turning a transient 500/503/429 into an infinite retry loop.
       _retry_count ||= self.retry_limit
 
+      # `retry: false` and `retry: 0` both disable retries; a positive
+      # Integer sets the budget. Anything else keeps the client default.
       if opts[:retry] == false
         _retry_count = 0
-      elsif opts[:retry].to_i > 0
-        _retry_count = opts[:retry]
+      elsif opts[:retry].is_a?(Numeric)
+        _retry_count = [opts[:retry].to_i, 0].max
       end
 
       # The effective starting budget, captured ONCE after the opts override
@@ -1259,6 +1306,15 @@ module Parse
       # silently disabling the backoff (every retry firing at zero delay).
       _retry_max ||= _retry_count
 
+      # Work on a copy of the caller's headers. The request id header is
+      # written into this hash, and it must survive the `retry` keyword (so
+      # it is set above the `begin`) without leaking into a hash the caller
+      # reuses for its next request.
+      headers = headers ? headers.dup : {}
+      # Set once a request is re-sent after an ambiguous failure, so a
+      # replayed DELETE that finds the object already gone can be recognized.
+      _replayed = false
+
       begin
         headers ||= {}
         # if the first argument is a Parse::Request object, then construct it
@@ -1271,7 +1327,13 @@ module Parse
           body ||= _request.body
           headers.merge! _request.headers
         else
-          _request = Parse::Request.new(method, uri, body: body, headers: headers, opts: opts)
+          # The metadata-master sentinel stays off the stored request: a
+          # caller replaying `response.request` later must not inherit it.
+          _request = Parse::Request.new(method, uri, body: body, headers: headers,
+                                                     opts: opts.except(:metadata_master))
+          # Request copies the headers it is given, so carry its request id
+          # back onto the outgoing headers.
+          headers.merge!(_request.headers)
         end
 
         # http method
@@ -1297,6 +1359,14 @@ module Parse
         #      never sent unless the caller explicitly passed `use_master_key: true`
         explicit_master = opts.key?(:use_master_key)
 
+        # SDK metadata reads (class schemas, the role graph) keep the master
+        # key inside `Parse.without_master_key`. Only the internal sentinel
+        # turns this on; a `true` or any other value from a caller does not.
+        # The marker goes on a per-attempt copy of the headers handed to the
+        # connection (below), never on `headers` or the stored request, so a
+        # retry, `response.request`, or an error reporter never carries it.
+        metadata_master = opts[:metadata_master].equal?(METADATA_MASTER_REQUEST) && opts[:use_master_key] == true
+
         if opts[:use_master_key] == false
           headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
         elsif Parse.client_mode && opts[:use_master_key] != true
@@ -1305,7 +1375,18 @@ module Parse
         end
 
         raw_token = opts[:session_token]
-        # SEC-02: an EXPLICITLY-supplied session_token that is a blank /
+        # A session token the caller put in the request headers directly
+        # (`current_user(token)`, `fetch_session(token)`, `logout(token)`)
+        # is as explicit as `session_token:`. Treat it as the per-call token
+        # so the ambient `with_session` token or this client's bound token
+        # cannot overwrite it: otherwise `User.session(token_a)` inside
+        # `with_session(token_b)` resolved user B, and the identity cache
+        # then mapped token A (or a garbage token) to user B for its TTL.
+        if raw_token.nil?
+          header_token = headers[Parse::Protocol::SESSION_TOKEN]
+          raw_token = header_token if header_token.is_a?(String)
+        end
+        # 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
@@ -1325,7 +1406,15 @@ 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_blank_token && !(explicit_master && opts[:use_master_key] == true)
+        # Inside `Parse.with_session(nil)` (or a token-less user) the block is
+        # anonymous: no ambient, no bound token, and no master key, unless
+        # this call passed a token or `use_master_key: true` itself.
+        anonymous_block = token.nil? && !explicit_blank_token &&
+                          !(explicit_master && opts[:use_master_key] == true) &&
+                          Parse.respond_to?(:anonymous_session?) && Parse.anonymous_session?
+        if anonymous_block
+          headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
+        elsif 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
@@ -1336,6 +1425,7 @@ module Parse
         if explicit_blank_token
           # Fail closed: never send the master key for an unusable explicit token.
           headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
+          headers.delete(Parse::Protocol::SESSION_TOKEN)
         elsif token.present?
           token = token.session_token if token.respond_to?(:session_token)
           headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
@@ -1346,7 +1436,12 @@ module Parse
         params = (method == :get ? query : body) || {}
         # if the path does not start with the '/1/' prefix, then add it to be nice.
         # actually send the request and return the body
-        response_env = @conn.send(method, uri, params, headers)
+        send_headers = headers
+        if metadata_master
+          send_headers = headers.merge(Parse::Middleware::Authentication::METADATA_MASTER =>
+                                         Parse::Middleware::Authentication::METADATA_MASTER_TOKEN)
+        end
+        response_env = @conn.send(method, uri, params, send_headers)
         response = response_env.body
         response.request = _request
 
@@ -1355,11 +1450,25 @@ module Parse
           Parse::Client._safe_warn("AuthenticationError", response)
           raise Parse::Error::AuthenticationError, response
         when 400, 408
-          if response.code == Parse::Response::ERROR_TIMEOUT || response.code == 143 #"net/http: timeout awaiting response headers"
+          # Only Parse's timeout code maps here. Code 143 is Parse Server's
+          # WEBHOOK_ERROR (for example "no function named: foo is defined"),
+          # not a timeout.
+          if response.code == Parse::Response::ERROR_TIMEOUT
             Parse::Client._safe_warn("TimeoutError", response)
             raise Parse::Error::TimeoutError, response
           end
         when 404
+          if response.object_not_found? && _replayed && method == :delete
+            # An earlier attempt of this DELETE failed ambiguously and was
+            # re-sent. "Object not found" on the replay means the first
+            # attempt removed it, so report the delete as applied.
+            warn "[Parse:Retry] #{_request} : object already deleted by an earlier attempt"
+            applied = Parse::Response.new({})
+            applied.http_status = 200
+            applied.headers = response.headers
+            applied.request = _request
+            return applied
+          end
           unless response.object_not_found?
             Parse::Client._safe_warn("ConnectionError", response)
             raise Parse::Error::ConnectionError, response
@@ -1370,12 +1479,24 @@ module Parse
         when 429 # Request over the throttle limit
           Parse::Client._safe_warn("RequestLimitExceededError", response)
           raise Parse::Error::RequestLimitExceededError, response
-        when 500, 503
+        when 500, 502, 503, 504
+          # 502 and 504 come from a gateway or load balancer in front of
+          # Parse Server. Like 500/503, the request may or may not have been
+          # applied, so they are retried only when the request is idempotent.
           Parse::Client._safe_warn("ServiceUnavailableError", response)
           raise Parse::Error::ServiceUnavailableError, response
         end
 
         if response.error?
+          if response.code == -1 && response.error.to_s.start_with?("Missing additional authData mfa")
+            # Parse Server's OTHER_CAUSE (-1) for a password login on an
+            # account with MFA enabled and no token supplied. It is a 400, not
+            # an outage: without this branch the `<= 2` check below mapped it
+            # to ServiceUnavailableError and retried the login. Surface the
+            # typed error callers are documented to rescue to prompt for a code.
+            Parse::Client._safe_warn("MFA::RequiredError", response)
+            raise Parse::MFA::RequiredError
+          end
           if response.code <= Parse::Response::ERROR_SERVICE_UNAVAILABLE
             Parse::Client._safe_warn("ServiceUnavailableError", response)
             raise Parse::Error::ServiceUnavailableError, response
@@ -1404,10 +1525,11 @@ module Parse
         # re-sending is safe for any method. 500/503 (ServiceUnavailable) is
         # ambiguous — a write may have applied before the error — so only
         # re-send when the request is idempotent (see #idempotent_retry?).
-        retryable = e.is_a?(Parse::Error::RequestLimitExceededError) || idempotent_retry?(method, body, headers)
+        retryable = e.is_a?(Parse::Error::RequestLimitExceededError) || idempotent_retry?(method, body, headers, uri)
         if _retry_count > 0 && retryable
-          warn "[Parse:Retry] Retries remaining #{_retry_count} : #{response.request}"
+          warn "[Parse:Retry] Retries remaining #{_retry_count} : #{response&.request || _request}"
           _retry_count -= 1
+          _replayed = true unless e.is_a?(Parse::Error::RequestLimitExceededError)
           # Use Retry-After header if available, otherwise use linear backoff
           retry_after = response.retry_after if response.respond_to?(:retry_after)
           if retry_after && retry_after > 0
@@ -1443,8 +1565,9 @@ module Parse
         #     Retrying only adds backoff latency and `[Parse:Retry]` noise
         #     before the inevitable error, so it propagates raw and fast.
         raise unless connection_reset_error?(e)
-        if _retry_count > 0 && idempotent_retry?(method, body, headers)
+        if _retry_count > 0 && idempotent_retry?(method, body, headers, uri)
           _retry_count = consume_retry_with_backoff(_retry_count, _retry_max, _request)
+          _replayed = true
           retry
         end
         raise Parse::Error::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
@@ -1458,8 +1581,9 @@ module Parse
         # not `ClientError`, so it must be listed explicitly to be caught.
         # `Faraday::ConnectionFailed` is handled in its own rescue above,
         # split into retry-reset / fail-fast-refused.
-        if _retry_count > 0 && idempotent_retry?(method, body, headers)
+        if _retry_count > 0 && idempotent_retry?(method, body, headers, uri)
           _retry_count = consume_retry_with_backoff(_retry_count, _retry_max, _request)
+          _replayed = true
           retry
         end
         raise Parse::Error::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
@@ -1547,9 +1671,12 @@ module Parse
     # @param body [Hash, Object, nil] the request body.
     # @param headers [Hash, nil] the outgoing request headers (consulted for
     #   the request-id header on the server-dedup fast path).
+    # @param uri [String, nil] the request path, used to confirm the
+    #   endpoint is one Parse Server deduplicates. Without it the
+    #   server-dedup fast path does not apply.
     # @return [Boolean]
-    def idempotent_retry?(method, body, headers = nil)
-      return true if server_deduped_request?(headers)
+    def idempotent_retry?(method, body, headers = nil, uri = nil)
+      return true if server_deduped_request?(headers, method, uri)
       case method
       when :get, :delete then true
       when :put then !body_carries_atomic_op?(body)
@@ -1557,34 +1684,90 @@ module Parse
       end
     end
 
+    # Routes on which Parse Server runs its request-id deduplication
+    # (`promiseEnsureIdempotency`), by HTTP method. Paths are relative to the
+    # mount point. Every other endpoint (notably `POST /batch`, files, push,
+    # login, logout, schemas, config, and hooks) applies a replay again, so
+    # a request to one of them is never treated as server-deduplicated.
+    SERVER_DEDUP_ROUTES = {
+      post: [
+        %r{\Aclasses/[^/]+\z},
+        %r{\Ausers\z},
+        %r{\Ainstallations\z},
+        %r{\Afunctions/[^/]+\z},
+        %r{\Ajobs/[^/]+\z},
+      ].freeze,
+      put: [
+        %r{\Aclasses/[^/]+/[^/]+\z},
+        %r{\Ausers/[^/]+\z},
+        %r{\Ainstallations/[^/]+\z},
+      ].freeze,
+    }.freeze
+
     # Whether this request is covered by Parse Server's server-side request-id
     # deduplication, making a replay a no-op. True only when the operator has
-    # opted in via {Parse::Request.assume_server_idempotency} AND the request
-    # actually carries a non-blank request-id header (writes to inherently
-    # non-idempotent paths — sessions, logout, functions, push, jobs — never
-    # get a request id, so they correctly fail this check).
+    # opted in via {Parse::Request.assume_server_idempotency}, the request
+    # carries a non-blank request-id header, AND it targets a route Parse
+    # Server deduplicates (see {SERVER_DEDUP_ROUTES}).
     # @param headers [Hash, nil] the outgoing request headers.
+    # @param method [Symbol, nil] the HTTP method.
+    # @param uri [String, nil] the request path.
     # @return [Boolean]
-    def server_deduped_request?(headers)
+    def server_deduped_request?(headers, method = nil, uri = nil)
       return false unless Parse::Request.assume_server_idempotency
       return false unless headers.is_a?(Hash)
       rid = headers[Parse::Request.request_id_header]
-      rid.is_a?(String) && !rid.strip.empty?
+      return false unless rid.is_a?(String) && !rid.strip.empty?
+      routes = SERVER_DEDUP_ROUTES[method.to_s.downcase.to_sym] if method
+      return false if routes.nil?
+      path = api_relative_path(uri)
+      return false if path.nil?
+      routes.any? { |route| path.match?(route) }
     end
 
-    # Whether a request body carries a Parse atomic operation, i.e. any field
-    # whose value is a Hash with an `__op` key (Increment, Add, AddUnique,
-    # Remove, AddRelation, RemoveRelation, Delete). Such ops are not idempotent
-    # and must not be replayed on an ambiguous failure. Assumes the body is a
-    # Ruby Hash, which the SDK's normal save/update path always provides; a
-    # pre-serialized String body is treated as op-free (and therefore
-    # retryable), so callers handing `request` a raw JSON string for a
-    # PUT-with-op would bypass this guard.
+    # The request path relative to the Parse mount point, without a query
+    # string or surrounding slashes. Accepts relative paths (`classes/Post`)
+    # and absolute ones that include the mount prefix (`/parse/classes/Post`).
+    # @param uri [String, nil]
+    # @return [String, nil]
+    def api_relative_path(uri)
+      return nil if uri.nil?
+      path = uri.to_s.split("?", 2).first.to_s
+      prefix = url_prefix.path.to_s rescue ""
+      prefix = prefix.chomp("/")
+      if !prefix.empty? && path.start_with?("#{prefix}/")
+        path = path.delete_prefix(prefix)
+      end
+      # Trim slashes with string operations rather than an end-anchored
+      # regex, which backtracks polynomially on long runs of "/".
+      path = path.delete_prefix("/") while path.start_with?("/")
+      path = path.delete_suffix("/") while path.end_with?("/")
+      path
+    end
+
+    # Whether a request body carries a Parse operation: an `__op` key at any
+    # depth, including the top level. That covers field ops (Increment, Add,
+    # AddUnique, Remove, AddRelation, RemoveRelation, Delete), nested ops such
+    # as a schema update's `fields: { name: { __op: "Delete" } }`, and
+    # whole-body ops such as a hook delete's `{ __op: "Delete" }`. Replaying
+    # any of them after the first attempt applied turns a landed write into a
+    # reported failure, or applies it twice. A pre-serialized String body is
+    # scanned for the literal `"__op"` key.
     # @param body [Object] the request body.
     # @return [Boolean]
-    def body_carries_atomic_op?(body)
-      return false unless body.is_a?(Hash)
-      body.any? { |_k, v| v.is_a?(Hash) && (v.key?("__op") || v.key?(:__op)) }
+    def body_carries_atomic_op?(body, depth = 0)
+      return false if depth > 32
+      case body
+      when Hash
+        body.key?("__op") || body.key?(:__op) ||
+          body.each_value.any? { |v| body_carries_atomic_op?(v, depth + 1) }
+      when Array
+        body.any? { |v| body_carries_atomic_op?(v, depth + 1) }
+      when String
+        depth.zero? && body.include?('"__op"')
+      else
+        false
+      end
     end
 
     # Send a GET request.
@@ -1629,7 +1812,11 @@ module Parse
     # @return (see #request)
     def send_request(req) #Parse::Request object
       raise ArgumentError, "Object not of Parse::Request type." unless req.is_a?(Parse::Request)
-      request req.method, req.path, req.body, req.headers
+      # Forward the request's own options so its session token, master-key
+      # opt-out, cache directive and retry budget reach the auth resolution.
+      # {#request} also merges them; passing them here keeps the contract
+      # explicit at the public entry point.
+      request req, opts: (req.opts || {})
     end
 
     # The connectable  module adds methods to objects so that they can get a default