parse-stack-next 5.6.0 → 5.7.0

data/lib/parse/client.rb

@@ -32,6 +32,8 @@ require_relative "client/body_builder"
 require_relative "client/authentication"
 require_relative "client/caching"
 require_relative "cache/redis"
+require_relative "cache/invalidation"
+require_relative "authorization"
 require_relative "client/logging"
 require_relative "client/profiling"
 require_relative "api/all"
@@ -219,7 +221,22 @@ module Parse
   # @return [Moneta::Transformer,Moneta::Expires] the cache instance
   # @see Parse::Client#cache
   def self.cache
-    @shared_cache ||= Parse::Client.client(:default).cache
+    # Deliberately NOT memoized. `@shared_cache ||=` pinned the first default
+    # client's store for the life of the process, so a later `Parse.setup`
+    # (a re-configuration, or a test suite swapping clients between cases)
+    # kept handing back the previous client's cache with no way to reset it.
+    Parse::Client.client(:default).cache
+  end
+
+  # The SDK-owned store for the default client: the response cache, the
+  # identity and role planes, and what {Parse::Client#clear_cache!} clears.
+  #
+  # Prefer {.cache} for application keys. This exists so the SDK's own slice
+  # is reachable and inspectable, not as a place to put application data.
+  # @return [Object]
+  # @see Parse::Client#sdk_cache
+  def self.sdk_cache
+    Parse::Client.client(:default).sdk_cache
   end
 
   # This class is the core and low level API for the Parse SDK REST interface that
@@ -337,6 +354,38 @@ module Parse
     attr_reader :session_token
     alias_method :app_id, :application_id
 
+    # The store the SDK itself reads and writes: the response cache, the
+    # identity and role planes, and {#clear_cache!}.
+    #
+    # With `cache_keyspace: true` this is a {Parse::Cache::ScopedView} (or a
+    # {Parse::Cache::KeyspacedStore} for a store that cannot produce one)
+    # confined to this client's keyspace. Without it, this IS {#cache}, so
+    # nothing about an existing deployment changes.
+    #
+    # Kept separate from {#cache} because the two answer different questions.
+    # `cache` is the store the application configured and may still use for
+    # its own keys, under their original physical names. `sdk_cache` is the
+    # SDK's slice of it, and clearing that slice must not reach application
+    # data.
+    #
+    # @return [Object] the SDK-owned store.
+    def sdk_cache
+      @sdk_cache || self.cache
+    end
+
+    # This client's authorization context: the identity and role caches, and
+    # the session-token resolver that feeds every mongo-direct ACL decision.
+    #
+    # One context per client, created lazily and never shared. That is the
+    # point of it living here rather than in module-level state: two clients
+    # pointed at two Parse applications must not resolve a token against each
+    # other's caches, nor validate it against each other's `/users/me`.
+    #
+    # @return [Parse::Authorization::Context]
+    def authorization
+      @authorization ||= Parse::Authorization::Context.new(client: self)
+    end
+
     # Redacted inspection. The default Ruby `#inspect` would dump every ivar,
     # exposing the master key and any bound session token in cleartext wherever
     # a client is logged or surfaced in an error reporter. Show only the
@@ -411,6 +460,7 @@ module Parse
       raise ArgumentError, "Parse::Client#with_session requires a client with a bound session_token" if @session_token.nil?
       Parse.with_session(@session_token, &block)
     end
+
     # The client can support multiple sessions. The first session created, will be placed
     # under the default session tag. The :default session will be the default client to be used
     # by the other classes including Parse::Query and Parse::Objects
@@ -586,10 +636,10 @@ module Parse
       # explicit-nil case, putting a "non-master" client back into master mode
       # in any deployment that exports PARSE_SERVER_MASTER_KEY / PARSE_MASTER_KEY.
       @master_key = if opts.key?(:master_key)
-                      opts[:master_key]
-                    else
-                      ENV["PARSE_SERVER_MASTER_KEY"] || ENV["PARSE_MASTER_KEY"]
-                    end
+          opts[:master_key]
+        else
+          ENV["PARSE_SERVER_MASTER_KEY"] || ENV["PARSE_MASTER_KEY"]
+        end
       # Optional token bound to this client; applied per request as the
       # lowest-priority auth fallback (see #request). Normalize blank/whitespace
       # to nil so it never trips the "token present" branch at request time
@@ -754,13 +804,89 @@ module Parse
             end
 
             self.cache = opts[:cache]
-            conn.use Parse::Middleware::Caching, self.cache, {
+
+            # Build one keyspace from the effective namespace and install it on
+            # both the middleware and the store, so key generation and eviction
+            # can never disagree. Previously the middleware could hold a
+            # `cache_namespace:` the store knew nothing about, and
+            # `clear_cache!` scoped using only the store's own namespace, so a
+            # namespaced client cleared every SDK key on the database.
+            #
+            # Opt-in: without `cache_keyspace: true` the legacy key shape is
+            # kept, so an upgrade changes nothing until an operator asks for it.
+            #
+            # `scoped` derives an immutable, per-client view rather than
+            # mutating the store in place. This matters when one backend
+            # (e.g. a `Parse::Cache::Redis` connection pool) is shared across
+            # more than one `Parse::Client`: mutating a shared store's
+            # keyspace would rebind it out from under whichever client
+            # configured it first, so this client's own `sdk_cache` becomes
+            # the view while `cache` stays the store that was configured, and
+            # the shared backend itself is never touched.
+            cache_keyspace = nil
+            if opts[:cache_keyspace]
+              cache_keyspace = Parse::Cache::Keyspace.new(
+                app_id: @application_id,
+                server_url: @server_url,
+                namespace: opts[:cache_namespace],
+              )
+              # Derive an immutable per-client view rather than mutating the
+              # backend, so two clients can share a connection pool without
+              # sharing ownership of the keyspace. There is deliberately no
+              # `keyspace=` fallback here, since reintroducing a mutable
+              # binding at the call site would restore the cross-client
+              # rebinding this replaces.
+              #
+              # A store that cannot produce a view is wrapped rather than left
+              # alone. Leaving it bare still composed keys correctly, because
+              # the middleware below receives the keyspace directly, so the
+              # deployment looked keyspaced; but `clear_cache!` then called the
+              # store's own unrestricted `clear`, which on a plain
+              # `Moneta.new(:Redis)` is FLUSHDB. Opting into keyspacing and
+              # getting a database-wide flush is the exact inversion of the
+              # option: it deletes other applications' entries and any
+              # `parse-stack:foc:v1:*` create-locks sharing the database.
+              #
+              # The view is assigned to `sdk_cache`, NOT over `cache`. An
+              # earlier version replaced `cache` outright, which meant the
+              # store an application configured and passed in was no longer
+              # reachable through the accessor documented for reaching it,
+              # and application reads and writes silently moved inside the
+              # SDK's keyspace. A scoped view also cannot honestly stand in
+              # for a complete Moneta store: `clear`, `each_key`, and `close`
+              # either break scope isolation or quietly change meaning.
+              @sdk_cache = if self.cache.respond_to?(:scoped)
+                  self.cache.scoped(cache_keyspace)
+                else
+                  Parse::Cache::KeyspacedStore.new(store: self.cache, keyspace: cache_keyspace)
+                end
+            end
+
+            # Register the invalidation triggers once a keyspace exists, so
+            # role and identity staleness is bounded by webhook rather than by
+            # application discipline. Opt-in with the keyspace, since without
+            # planes there is nothing to invalidate.
+            if cache_keyspace && sdk_cache.respond_to?(:roles) &&
+               opts.fetch(:cache_invalidation_hooks, true)
+              begin
+                Parse::Cache::Invalidation.install!(sdk_cache)
+              rescue StandardError => e
+                warn "[Parse::Client] cache invalidation hooks not installed: #{e.class}"
+              end
+            end
+
+            conn.use Parse::Middleware::Caching, sdk_cache, {
               expires: opts[:expires].to_i,
               # Optional `cache_namespace:` prefixes every key so two Parse
               # apps sharing one Redis don't collide on `mk:/classes/Song/abc`.
               # Explicit only — we do NOT auto-derive from app_id to keep
               # existing single-app deployments backward-compatible.
               namespace: opts[:cache_namespace],
+              keyspace: cache_keyspace,
+              # During a rolling deploy, new workers write keyspaced keys while
+              # old workers still read the legacy shape, so invalidation has to
+              # hit both until every old worker is drained.
+              delete_legacy_variants: opts.fetch(:cache_delete_legacy_variants, true),
             }
 
             # Inform about opt-in cache behavior
@@ -843,6 +969,7 @@ module Parse
       # env-proxy autodiscovery.
       faraday_opts[:proxy] = nil unless @allow_faraday_proxy
     end
+
     private :validate_faraday_opts!
 
     # Hosts considered "loopback" for the cleartext-ws:// guard in
@@ -927,10 +1054,10 @@ module Parse
       return if unknown.empty?
 
       warn "[Parse::Client] Ignoring unknown live_query option(s): " \
-           "#{unknown.inspect}. Valid keys are Parse::LiveQuery::Configuration " \
-           "setters (url, application_id, client_key, master_key, ping_interval, " \
-           "pong_timeout, allow_insecure, ssl_min_version, ssl_max_version, " \
-           "logging_enabled, log_level, ...). Check for typos."
+        "#{unknown.inspect}. Valid keys are Parse::LiveQuery::Configuration " \
+        "setters (url, application_id, client_key, master_key, ping_interval, " \
+        "pong_timeout, allow_insecure, ssl_min_version, ssl_max_version, " \
+        "logging_enabled, log_level, ...). Check for typos."
     end
 
     # If set, returns the current retry count for this instance. Otherwise,
@@ -946,9 +1073,20 @@ module Parse
       @conn.url_prefix
     end
 
-    # Clear the client cache
+    # Clear the SDK's own cached entries.
+    #
+    # Operates on {#sdk_cache}, so with `cache_keyspace: true` this removes
+    # only keys under this client's keyspace and leaves application keys in
+    # the same store untouched. Without a keyspace `sdk_cache` IS `cache`,
+    # and the call has its historical whole-store meaning.
+    #
+    # To clear the underlying store outright, call `client.cache.clear`
+    # explicitly. On a Redis-backed store that is `FLUSHDB` and takes
+    # everything on the database with it, including other applications and
+    # any `parse-stack:foc:v1:*` create-locks.
     def clear_cache!
-      self.cache.clear if self.cache.present?
+      target = sdk_cache
+      target.clear if target.present?
     end
 
     # No-credentials liveness probe. Hits the Parse Server health endpoint and
@@ -1049,10 +1187,10 @@ module Parse
       # Pre-declare locals referenced inside rescue blocks so CodeQL's
       # uninitialized-variable analysis is satisfied even if an exception
       # raises before the natural assignment site.
-      response     = nil
+      response = nil
       _retry_count = nil
       _retry_delay = nil
-      _request     = nil
+      _request = nil
       # 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
@@ -1092,193 +1230,193 @@ module Parse
       _retry_max ||= _retry_count
 
       begin
-      headers ||= {}
-      # if the first argument is a Parse::Request object, then construct it
-      _request = nil
-      if method.is_a?(Request)
-        _request = method
-        method = _request.method
-        uri ||= _request.path
-        query ||= _request.query
-        body ||= _request.body
-        headers.merge! _request.headers
-      else
-        _request = Parse::Request.new(method, uri, body: body, headers: headers, opts: opts)
-      end
-
-      # http method
-      method = method.downcase.to_sym
-      # set the User-Agent
-      headers[USER_AGENT_HEADER] = USER_AGENT_VERSION
-
-      if opts[:cache] == false
-        headers[Parse::Middleware::Caching::CACHE_CONTROL] = "no-cache"
-      elsif opts[:cache] == :write_only
-        # Write-only mode: skip reading from cache, but still write to cache
-        # Useful for fetch!/reload! which want fresh data but should update cache
-        headers[Parse::Middleware::Caching::CACHE_WRITE_ONLY] = "true"
-      elsif opts[:cache].is_a?(Numeric)
-        # specify the cache duration of this request
-        headers[Parse::Middleware::Caching::CACHE_EXPIRES_DURATION] = opts[:cache].to_s
-      end
+        headers ||= {}
+        # if the first argument is a Parse::Request object, then construct it
+        _request = nil
+        if method.is_a?(Request)
+          _request = method
+          method = _request.method
+          uri ||= _request.path
+          query ||= _request.query
+          body ||= _request.body
+          headers.merge! _request.headers
+        else
+          _request = Parse::Request.new(method, uri, body: body, headers: headers, opts: opts)
+        end
 
-      # Resolve the auth context in three layers:
-      #   1. explicit per-call `use_master_key:` and `session_token:`
-      #   2. ambient session set by `Parse.with_session { ... }` (fiber-local)
-      #   3. process-wide `Parse.client_mode` flag — when true, master key is
-      #      never sent unless the caller explicitly passed `use_master_key: true`
-      explicit_master = opts.key?(:use_master_key)
-
-      if opts[:use_master_key] == false
-        headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
-      elsif Parse.client_mode && opts[:use_master_key] != true
-        # client mode defaults master key OFF unless explicitly opted in
-        headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
-      end
+        # http method
+        method = method.downcase.to_sym
+        # set the User-Agent
+        headers[USER_AGENT_HEADER] = USER_AGENT_VERSION
+
+        if opts[:cache] == false
+          headers[Parse::Middleware::Caching::CACHE_CONTROL] = "no-cache"
+        elsif opts[:cache] == :write_only
+          # Write-only mode: skip reading from cache, but still write to cache
+          # Useful for fetch!/reload! which want fresh data but should update cache
+          headers[Parse::Middleware::Caching::CACHE_WRITE_ONLY] = "true"
+        elsif opts[:cache].is_a?(Numeric)
+          # specify the cache duration of this request
+          headers[Parse::Middleware::Caching::CACHE_EXPIRES_DURATION] = opts[:cache].to_s
+        end
 
-      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`.
-      # Explicit `use_master_key: true` is treated as a deliberate admin call
-      # and skips both — otherwise an `admin.do_thing(use_master_key: true)`
-      # 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)
-        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
-        # `token.present?` check, silently sending the master key instead.
-        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 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
-      end
+        # Resolve the auth context in three layers:
+        #   1. explicit per-call `use_master_key:` and `session_token:`
+        #   2. ambient session set by `Parse.with_session { ... }` (fiber-local)
+        #   3. process-wide `Parse.client_mode` flag — when true, master key is
+        #      never sent unless the caller explicitly passed `use_master_key: true`
+        explicit_master = opts.key?(:use_master_key)
+
+        if opts[:use_master_key] == false
+          headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
+        elsif Parse.client_mode && opts[:use_master_key] != true
+          # client mode defaults master key OFF unless explicitly opted in
+          headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
+        end
 
-      #if it is a :get request, then use query params, otherwise body.
-      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)
-      response = response_env.body
-      response.request = _request
-
-      case response.http_status
-      when 401, 403
-        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"
-          Parse::Client._safe_warn("TimeoutError", response)
-          raise Parse::Error::TimeoutError, response
+        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`.
+        # Explicit `use_master_key: true` is treated as a deliberate admin call
+        # and skips both — otherwise an `admin.do_thing(use_master_key: true)`
+        # 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)
+          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
+          # `token.present?` check, silently sending the master key instead.
+          token = ambient if ambient.is_a?(String) && !ambient.strip.empty?
+          token = @session_token if (token.nil? || token.to_s.strip.empty?) && @session_token
         end
-      when 404
-        unless response.object_not_found?
-          Parse::Client._safe_warn("ConnectionError", response)
-          raise Parse::Error::ConnectionError, response
+        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
         end
-      when 405, 406
-        Parse::Client._safe_warn("ProtocolError", response)
-        raise Parse::Error::ProtocolError, response
-      when 429 # Request over the throttle limit
-        Parse::Client._safe_warn("RequestLimitExceededError", response)
-        raise Parse::Error::RequestLimitExceededError, response
-      when 500, 503
-        Parse::Client._safe_warn("ServiceUnavailableError", response)
-        raise Parse::Error::ServiceUnavailableError, response
-      end
 
-      if response.error?
-        if response.code <= Parse::Response::ERROR_SERVICE_UNAVAILABLE
-          Parse::Client._safe_warn("ServiceUnavailableError", response)
-          raise Parse::Error::ServiceUnavailableError, response
-        elsif response.code <= 100
-          Parse::Client._safe_warn("ServerError", response)
-          raise Parse::Error::ServerError, response
-        elsif response.code == Parse::Response::ERROR_EXCEEDED_BURST_LIMIT
+        #if it is a :get request, then use query params, otherwise body.
+        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)
+        response = response_env.body
+        response.request = _request
+
+        case response.http_status
+        when 401, 403
+          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"
+            Parse::Client._safe_warn("TimeoutError", response)
+            raise Parse::Error::TimeoutError, response
+          end
+        when 404
+          unless response.object_not_found?
+            Parse::Client._safe_warn("ConnectionError", response)
+            raise Parse::Error::ConnectionError, response
+          end
+        when 405, 406
+          Parse::Client._safe_warn("ProtocolError", response)
+          raise Parse::Error::ProtocolError, response
+        when 429 # Request over the throttle limit
           Parse::Client._safe_warn("RequestLimitExceededError", response)
           raise Parse::Error::RequestLimitExceededError, response
-        elsif response.code == 209 # Error 209: invalid session token
-          Parse::Client._safe_warn("InvalidSessionTokenError", response)
-          raise Parse::Error::InvalidSessionTokenError, response
-        elsif response.code == Parse::Response::ERROR_DUPLICATE_REQUEST # 159
-          # Request-id idempotency rejected a duplicate — the original write
-          # already applied (NOT a second time). Surface a typed, catchable
-          # signal rather than a generic error; this is what a transparently-
-          # retried write that landed-but-lost-its-response sees on the replay.
-          Parse::Client._safe_warn("DuplicateRequestError", response)
-          raise Parse::Error::DuplicateRequestError, response
+        when 500, 503
+          Parse::Client._safe_warn("ServiceUnavailableError", response)
+          raise Parse::Error::ServiceUnavailableError, response
         end
-      end
 
-      response
-    rescue Parse::Error::RequestLimitExceededError, Parse::Error::ServiceUnavailableError => e
-      # 429 (RequestLimitExceeded): the server threw the request away, so
-      # 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)
-      if _retry_count > 0 && retryable
-        warn "[Parse:Retry] Retries remaining #{_retry_count} : #{response.request}"
-        _retry_count -= 1
-        # 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
-          _retry_delay = retry_after
-          warn "[Parse:Retry] Using Retry-After header: #{_retry_delay}s"
-        else
-          # Linear backoff (RETRY_DELAY × attempt number) with +/-25% jitter.
-          # Never zero —
-          # zero-wait retries amplify DoS against upstream and stampede on 429.
+        if response.error?
+          if response.code <= Parse::Response::ERROR_SERVICE_UNAVAILABLE
+            Parse::Client._safe_warn("ServiceUnavailableError", response)
+            raise Parse::Error::ServiceUnavailableError, response
+          elsif response.code <= 100
+            Parse::Client._safe_warn("ServerError", response)
+            raise Parse::Error::ServerError, response
+          elsif response.code == Parse::Response::ERROR_EXCEEDED_BURST_LIMIT
+            Parse::Client._safe_warn("RequestLimitExceededError", response)
+            raise Parse::Error::RequestLimitExceededError, response
+          elsif response.code == 209 # Error 209: invalid session token
+            Parse::Client._safe_warn("InvalidSessionTokenError", response)
+            raise Parse::Error::InvalidSessionTokenError, response
+          elsif response.code == Parse::Response::ERROR_DUPLICATE_REQUEST # 159
+            # Request-id idempotency rejected a duplicate — the original write
+            # already applied (NOT a second time). Surface a typed, catchable
+            # signal rather than a generic error; this is what a transparently-
+            # retried write that landed-but-lost-its-response sees on the replay.
+            Parse::Client._safe_warn("DuplicateRequestError", response)
+            raise Parse::Error::DuplicateRequestError, response
+          end
+        end
+
+        response
+      rescue Parse::Error::RequestLimitExceededError, Parse::Error::ServiceUnavailableError => e
+        # 429 (RequestLimitExceeded): the server threw the request away, so
+        # 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)
+        if _retry_count > 0 && retryable
+          warn "[Parse:Retry] Retries remaining #{_retry_count} : #{response.request}"
+          _retry_count -= 1
+          # 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
+            _retry_delay = retry_after
+            warn "[Parse:Retry] Using Retry-After header: #{_retry_delay}s"
+          else
+            # Linear backoff (RETRY_DELAY × attempt number) with +/-25% jitter.
+            # Never zero —
+            # zero-wait retries amplify DoS against upstream and stampede on 429.
+            backoff_delay = RETRY_DELAY * (_retry_max - _retry_count)
+            _retry_delay = backoff_delay * (0.75 + rand * 0.5)
+          end
+          sleep _retry_delay if _retry_delay > 0
+          retry
+        end
+        raise
+      rescue Faraday::ClientError, Faraday::TimeoutError, Net::OpenTimeout => e
+        # Request timed out mid-flight: the outcome is unknown (the server may
+        # have received and applied the write but never answered), so only
+        # re-send idempotent requests to avoid double-applying.
+        #
+        # Faraday 2.x raises `Faraday::TimeoutError` for a read timeout
+        # (`Timeout::Error` / `Errno::ETIMEDOUT`); it subclasses `Faraday::Error`,
+        # not `ClientError`, so it must be listed explicitly to be caught. We
+        # deliberately do NOT catch `Faraday::ConnectionFailed` (connection
+        # refused/reset, plus the wrapped connect-timeout): refused is a
+        # non-transient "server down / misconfigured" failure, and auto-retrying
+        # it only adds backoff latency before the inevitable error. Broadening to
+        # reset connections safely (retry reset, fail fast on refused) is tracked
+        # as a follow-up.
+        if _retry_count > 0 && idempotent_retry?(method, body, headers)
+          warn "[Parse:Retry] Retries remaining #{_retry_count} : #{_request}"
+          _retry_count -= 1
           backoff_delay = RETRY_DELAY * (_retry_max - _retry_count)
           _retry_delay = backoff_delay * (0.75 + rand * 0.5)
+          sleep _retry_delay if _retry_delay > 0
+          retry
         end
-        sleep _retry_delay if _retry_delay > 0
-        retry
-      end
-      raise
-    rescue Faraday::ClientError, Faraday::TimeoutError, Net::OpenTimeout => e
-      # Request timed out mid-flight: the outcome is unknown (the server may
-      # have received and applied the write but never answered), so only
-      # re-send idempotent requests to avoid double-applying.
-      #
-      # Faraday 2.x raises `Faraday::TimeoutError` for a read timeout
-      # (`Timeout::Error` / `Errno::ETIMEDOUT`); it subclasses `Faraday::Error`,
-      # not `ClientError`, so it must be listed explicitly to be caught. We
-      # deliberately do NOT catch `Faraday::ConnectionFailed` (connection
-      # refused/reset, plus the wrapped connect-timeout): refused is a
-      # non-transient "server down / misconfigured" failure, and auto-retrying
-      # it only adds backoff latency before the inevitable error. Broadening to
-      # reset connections safely (retry reset, fail fast on refused) is tracked
-      # as a follow-up.
-      if _retry_count > 0 && idempotent_retry?(method, body, headers)
-        warn "[Parse:Retry] Retries remaining #{_retry_count} : #{_request}"
-        _retry_count -= 1
-        backoff_delay = RETRY_DELAY * (_retry_max - _retry_count)
-        _retry_delay = backoff_delay * (0.75 + rand * 0.5)
-        sleep _retry_delay if _retry_delay > 0
-        retry
-      end
-      raise Parse::Error::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
+        raise Parse::Error::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
       end
     end
 
@@ -1488,7 +1626,7 @@ module Parse
     when Hash
       type = value["__type"] || value[:__type]
       class_name = value["className"] || value[:className]
-      object_id  = value["objectId"] || value[:objectId]
+      object_id = value["objectId"] || value[:objectId]
       if type == Parse::Model::TYPE_POINTER && class_name && object_id
         # Pointers carry no attributes, so building one is lossless even for
         # an unregistered class (yields a Parse::Pointer).