parse-stack-next 5.1.1 → 5.2.0

data/lib/parse/client/request.rb

@@ -46,12 +46,38 @@ module Parse
       # @!attribute [rw] idempotent_methods
       #   @return [Array<Symbol>] HTTP methods that should include request IDs
       attr_accessor :idempotent_methods
+
+      # @!attribute [rw] assume_server_idempotency
+      #   @return [Boolean] operator assertion that the Parse Server is
+      #     configured with `idempotencyOptions` covering the write paths the
+      #     SDK targets. When true, a request that carries a stable
+      #     `X-Parse-Request-Id` header becomes safe for {Parse::Client} to
+      #     transparently RETRY on an ambiguous failure (500/503/dropped
+      #     connection) even when it is a POST or an atomic-op write — Parse
+      #     Server deduplicates the replay server-side, so the write applies AT
+      #     MOST ONCE.
+      #
+      #     The replay does NOT transparently return the original response,
+      #     though: Parse Server rejects the duplicate with error 159, which the
+      #     SDK raises as {Parse::Error::DuplicateRequestError}. A caller relying
+      #     on this retry must rescue that error (the original write already
+      #     landed) and re-fetch by its own key if it needs the result.
+      #
+      #     Default false. Sending the `X-Parse-Request-Id` header is harmless
+      #     on its own, but ASSUMING the server deduplicates when it does not
+      #     would double-apply the write on retry. Only set this true when
+      #     Parse Server's `idempotencyOptions` is actually configured to cover
+      #     those paths (it is OFF by default on Parse Server).
+      attr_accessor :assume_server_idempotency
     end
 
     # Default configuration
     self.enable_request_id = true  # Enabled by default for production safety
     self.request_id_header = "X-Parse-Request-Id"  # Standard Parse header
     self.idempotent_methods = [:post, :put, :patch]  # Methods that can benefit from idempotency
+    # OFF by default: the client cannot know whether the server deduplicates,
+    # so it never assumes retry-safety for writes unless the operator opts in.
+    self.assume_server_idempotency = false
 
     # Creates a new request
     # @param method [String] the HTTP method
@@ -121,11 +147,23 @@ module Parse
 
       return unless should_use_request_id
 
+      header_name = self.class.request_id_header
+
+      # If a request id is already on the headers — e.g. a retry re-builds the
+      # Request with the same headers hash carried over from the first attempt
+      # — adopt it so the `request_id` ivar matches the value actually on the
+      # wire. Generating a fresh UUID here while the `||=` below leaves the old
+      # header in place would silently diverge the ivar from the sent header.
+      existing = @headers[header_name]
+      if existing && !existing.to_s.empty?
+        @request_id = existing
+        return
+      end
+
       # Use custom request ID if provided, otherwise generate one
       @request_id = @opts[:request_id] || generate_request_id
 
       # Add request ID to headers if not already present
-      header_name = self.class.request_id_header
       @headers[header_name] ||= @request_id
     end
 
@@ -209,25 +247,38 @@ module Parse
     # Enables request ID generation globally
     # @param methods [Array<Symbol>] HTTP methods to apply idempotency to
     # @param header [String] header name to use for request IDs
-    def self.enable_idempotency!(methods: [:post, :put, :patch], header: "X-Parse-Request-Id")
+    # @param assume_server_dedup [Boolean, nil] when non-nil, also sets
+    #   {assume_server_idempotency} — pass `true` ONLY when Parse Server's
+    #   `idempotencyOptions` is configured, to additionally make writes
+    #   retry-safe. Leave nil (default) to send the header without changing
+    #   the retry posture.
+    def self.enable_idempotency!(methods: [:post, :put, :patch], header: "X-Parse-Request-Id", assume_server_dedup: nil)
       self.enable_request_id = true
       self.idempotent_methods = methods
       self.request_id_header = header
+      self.assume_server_idempotency = assume_server_dedup unless assume_server_dedup.nil?
     end
 
-    # Disables request ID generation globally
+    # Disables request ID generation globally. Also clears
+    # {assume_server_idempotency} so writes are never treated as retry-safe
+    # once the header is no longer sent.
     def self.disable_idempotency!
       self.enable_request_id = false
+      self.assume_server_idempotency = false
     end
 
     # Configures idempotency settings
     # @param enabled [Boolean] whether to enable idempotency
     # @param methods [Array<Symbol>] HTTP methods to apply idempotency to
     # @param header [String] header name to use for request IDs
-    def self.configure_idempotency(enabled: true, methods: [:post, :put, :patch], header: "X-Parse-Request-Id")
+    # @param assume_server_dedup [Boolean] sets {assume_server_idempotency}
+    #   (default false). Pass true ONLY when Parse Server `idempotencyOptions`
+    #   is configured for the targeted paths.
+    def self.configure_idempotency(enabled: true, methods: [:post, :put, :patch], header: "X-Parse-Request-Id", assume_server_dedup: false)
       self.enable_request_id = enabled
       self.idempotent_methods = methods
       self.request_id_header = header
+      self.assume_server_idempotency = assume_server_dedup
     end
   end
 end

data/lib/parse/client/response.rb

@@ -19,6 +19,10 @@ module Parse
     ERROR_TIMEOUT = 124
     # Code when the requests per second limit as been exceeded.
     ERROR_EXCEEDED_BURST_LIMIT = 155
+    # Code when a request carrying a previously-seen `X-Parse-Request-Id` is
+    # rejected by Parse Server's idempotency layer (the request was already
+    # applied). Surfaced as {Parse::Error::DuplicateRequestError}.
+    ERROR_DUPLICATE_REQUEST = 159
     # Code when a requested record is not found.
     ERROR_OBJECT_NOT_FOUND = 101
     # Code when the username is missing in request.

data/lib/parse/client.rb

@@ -62,6 +62,17 @@ module Parse
     # An error when the session token provided in the request is invalid.
     class InvalidSessionTokenError < Error; end
 
+    # Raised when Parse Server's request-id idempotency layer rejects a request
+    # carrying a previously-seen `X-Parse-Request-Id` (Parse error code
+    # {Parse::Response::ERROR_DUPLICATE_REQUEST}, 159). The duplicate was NOT
+    # applied a second time — the original request already succeeded. The SDK
+    # reuses the same request id across transparent retries, so a retried write
+    # that lands but loses its response will surface THIS error on the replay:
+    # treat it as "the write already applied" (re-fetch by your own key if you
+    # need the resulting object — Parse Server does not echo the original
+    # response on a duplicate).
+    class DuplicateRequestError < Error; end
+
     # An error raised when a cloud function or job returns an error response
     # (e.g. when the cloud code calls error!()). Carries the function name,
     # Parse error code, HTTP status, and the underlying Response for debugging.
@@ -167,6 +178,40 @@ module Parse
     Parse::Client.client(conn)
   end
 
+  # Check that the Parse Server is reachable via the health endpoint.
+  # This is a no-credentials liveness probe — it does NOT validate the
+  # 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+
+  #   if the server is unreachable or returned an unexpected response.
+  def self.reachable?(conn = :default)
+    client(conn).reachable?
+  rescue StandardError
+    false
+  end
+
+  # 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
+  # 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+.
+  # @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
+  #   is given, the credentials are accepted).
+  def self.connected?(conn = :default, endpoint = nil)
+    client(conn).connected?(endpoint)
+  rescue StandardError
+    false
+  end
+
   # The shared cache for the default client connection. This is useful if you want to
   # also utilize the same cache store for other purposes in your application.
   # This should normally be a {https://github.com/minad/moneta Moneta} unified
@@ -784,6 +829,50 @@ module Parse
       self.cache.clear if self.cache.present?
     end
 
+    # No-credentials liveness probe. Hits the Parse Server health endpoint and
+    # 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.
+    def reachable?
+      response = request(:get, Parse::API::Server::SERVER_HEALTH_PATH, opts: { cache: false })
+      response.success?
+    rescue Parse::Error, Faraday::Error
+      false
+    end
+
+    # Connectivity probe. By default hits the Parse Server health endpoint —
+    # 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
+    # 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
+    # avoids any data class.
+    #
+    # To ALSO validate credentials, pass `endpoint:` a path to a class the
+    # configured key is allowed to read (e.g. `"classes/_User"` on a default
+    # 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.
+    # @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
+    #   is given, the credentials are accepted).
+    def connected?(endpoint = nil)
+      path = endpoint || Parse::API::Server::SERVER_HEALTH_PATH
+      response = request(:get, path, query: { limit: 0 }, opts: { cache: false })
+      response.success?
+    rescue Parse::Error, Faraday::Error
+      false
+    end
+
     # Send a REST API request to the server. This is the low-level API used for all requests
     # to the Parse server with the provided options. Every request sent to Parse through
     # the client goes through the configured set of middleware that can be modified by applying
@@ -824,6 +913,9 @@ module Parse
     #   - This usually means you have exceeded the burst limit on requests, which will mean you will be throttled for the
     #     next 60 seconds.
     # @raise Parse::Error::InvalidSessionTokenError when the Parse response code is 209.
+    # @raise Parse::Error::DuplicateRequestError when the Parse response code is
+    #   {Parse::Response::ERROR_DUPLICATE_REQUEST} (159) — request-id idempotency
+    #   rejected a duplicate; the original write already applied.
     #   - This means the session token that was sent in the request seems to be invalid.
     # @return [Parse::Response] the response for this request.
     # @see Parse::Middleware::BodyBuilder
@@ -855,6 +947,11 @@ module Parse
                              "Good: Parse.client.create_object('X', body, session_token: t, use_master_key: false)"
       end
 
+      # Retry budget. Initialized ONCE here, ABOVE the `begin` below, so the
+      # `retry` keyword in the rescue clauses (which re-runs only the begin
+      # block, not the whole method) preserves the countdown across attempts.
+      # If this initialization ran inside the begin it would reset on every
+      # attempt, turning a transient 500/503/429 into an infinite retry loop.
       _retry_count ||= self.retry_limit
 
       if opts[:retry] == false
@@ -863,6 +960,16 @@ module Parse
         _retry_count = opts[:retry]
       end
 
+      # The effective starting budget, captured ONCE after the opts override
+      # (and, like `_retry_count`, above the `begin` so `retry` doesn't reset
+      # it). The backoff multiplier is `(_retry_max - _retry_count)`, which
+      # grows 1, 2, 3, … as attempts are consumed. Deriving it from
+      # `self.retry_limit` instead would go to zero or negative whenever a
+      # caller passes `opts: { retry: N }` with N above the instance default,
+      # silently disabling the backoff (every retry firing at zero delay).
+      _retry_max ||= _retry_count
+
+      begin
       headers ||= {}
       # if the first argument is a Parse::Request object, then construct it
       _request = nil
@@ -970,39 +1077,130 @@ module Parse
         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
-      if _retry_count > 0
+      # 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 exponential backoff
+        # 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
-          # Deterministic exponential backoff with +/-25% jitter. Never zero —
+          # 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 * (self.retry_limit - _retry_count)
+          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, Net::OpenTimeout => e
-      if _retry_count > 0
+    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 * (self.retry_limit - _retry_count)
+        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}"
+      end
+    end
+
+    # Whether a request whose outcome is UNKNOWN (a 500/503 or a dropped
+    # connection) is safe to transparently re-send.
+    #
+    # Server-dedup fast path: when the operator has asserted Parse Server
+    # idempotency is configured ({Parse::Request.assume_server_idempotency})
+    # AND this request carries a stable `X-Parse-Request-Id` header, the
+    # server deduplicates a replay, so even a POST or an atomic-op write is
+    # safe to retry — the write applies at most once. The replay is NOT a
+    # transparent success, though: Parse Server rejects the duplicate with
+    # error 159, surfaced as a raised {Parse::Error::DuplicateRequestError}
+    # the caller must rescue (the original write already landed). The SDK sends
+    # the same request id on every retry (the header is set once and preserved
+    # across the `retry`), which is what makes the server-side dedup match.
+    #
+    # Otherwise the conservative method/body heuristic applies: GET and DELETE
+    # are idempotent; a full-object PUT update is idempotent ONLY when it
+    # carries no atomic `__op` mutation (Increment/Add/AddUnique/Remove/Relation
+    # would double-apply on replay); POST (object create / batch) is never
+    # auto-retried. 429 throttles are handled at the call site, since the
+    # server provably discarded the request and those re-send regardless.
+    # @param method [Symbol] the (downcased) HTTP method of the request.
+    # @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).
+    # @return [Boolean]
+    def idempotent_retry?(method, body, headers = nil)
+      return true if server_deduped_request?(headers)
+      case method
+      when :get, :delete then true
+      when :put then !body_carries_atomic_op?(body)
+      else false
+      end
+    end
+
+    # 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).
+    # @param headers [Hash, nil] the outgoing request headers.
+    # @return [Boolean]
+    def server_deduped_request?(headers)
+      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?
+    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.
+    # @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)) }
     end
 
     # Send a GET request.

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

@@ -85,22 +85,32 @@ module Parse
   class Installation < Parse::Object
     parse_class Parse::Model::CLASS_INSTALLATION
 
+    # The CLP operations Parse Server does NOT honor on `_Installation`:
+    # `find` and `delete` are hardcoded master-key-only at the REST layer,
+    # and `create`/`update` are gated on the `X-Parse-Installation-Id`
+    # header rather than CLP. Setting CLP for any of these either does
+    # nothing or breaks the SDK's device-registration flow, so the advisory
+    # fires only for them. `get`, `count`, `addField`, and `protectedFields`
+    # respond to CLP normally and are configured without a warning.
+    INEFFECTIVE_CLP_OPERATIONS = %i[find create update delete].freeze
+
     class << self
-      # Override {Parse::Object.set_clp} on `_Installation` so that any
-      # attempt to change CLP from the SDK emits a one-time advisory.
-      # Parse Server hardcodes `find` and `delete` on `_Installation` to
-      # master-key-only at the REST layer, and gates `create`/`update`
-      # on the `X-Parse-Installation-Id` header rather than CLP — so
-      # most CLP changes here either do nothing or break the SDK's
-      # device-registration flow. Behavior is otherwise unchanged.
+      # Override {Parse::Object.set_clp} on `_Installation` so that an
+      # attempt to change CLP for an operation the server ignores emits a
+      # one-time advisory. CLP changes for `get` / `count` / `addField`
+      # take effect normally and are applied without a warning. Behavior is
+      # otherwise unchanged.
       def set_clp(operation, **opts)
-        _warn_about_installation_clp!(:set_clp, operation)
+        _warn_about_installation_clp!(:set_clp, operation) if _installation_clp_ineffective?(operation)
         super
       end
 
-      # Same advisory for the bulk-config DSL.
+      # Same advisory for the bulk-config DSL — warn only about the keys that
+      # name an ineffective operation, and stay silent when the caller only
+      # touches the operations CLP actually controls.
       def set_class_access(**ops_to_access)
-        _warn_about_installation_clp!(:set_class_access, ops_to_access.keys)
+        offending = ops_to_access.keys.select { |op| _installation_clp_ineffective?(op) }
+        _warn_about_installation_clp!(:set_class_access, offending) unless offending.empty?
         super
       end
 
@@ -127,6 +137,13 @@ module Parse
         super
       end
 
+      # @!visibility private
+      # Whether a CLP operation is one Parse Server ignores on `_Installation`
+      # (and therefore worth warning about). Normalizes Strings/Symbols.
+      def _installation_clp_ineffective?(operation)
+        INEFFECTIVE_CLP_OPERATIONS.include?(operation.to_s.to_sym)
+      end
+
       # @!visibility private
       def _warn_about_installation_clp!(method, detail)
         return if @_installation_clp_warned

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

@@ -654,6 +654,10 @@ module Parse
 
     # Request a password reset for this user
     # @return [Boolean] true if it was successful requested. false otherwise.
+    # @raise [Parse::Error::ServiceUnavailableError] if Parse Server returns a
+    #   500/503 (e.g. no emailAdapter / publicServerURL configured). Callers that
+    #   branch on the Boolean should rescue this; `if request_password_reset(email)`
+    #   is not exception-safe on a misconfigured server.
     # @see Parse::User.request_password_reset
     def request_password_reset
       return false if email.nil?
@@ -1061,6 +1065,10 @@ module Parse
     #  Parse::User.request_password_reset("user@example.com")
     # @param email [String] The user's email address.
     # @return [Boolean] True/false if successful.
+    # @raise [Parse::Error::ServiceUnavailableError] if Parse Server returns a
+    #   500/503 (e.g. no emailAdapter / publicServerURL configured). Callers that
+    #   branch on the Boolean should rescue this; `if request_password_reset(email)`
+    #   is not exception-safe on a misconfigured server.
     def self.request_password_reset(email)
       email = email.email if email.is_a?(Parse::User)
       return false if email.blank?

data/lib/parse/model/core/actions.rb

@@ -409,6 +409,13 @@ module Parse
               winner = _recover_from_duplicate_value(e, query_attrs, session: session, master_key: master_key)
               raise unless winner
               winner
+            rescue Parse::Error::DuplicateRequestError
+              # A transparently-retried create landed but lost its response;
+              # server idempotency rejected the replay. Re-find the row the
+              # original attempt created and return it.
+              winner = _recover_from_duplicate_request(query_attrs, session: session, master_key: master_key)
+              raise unless winner
+              winner
             end
           end
         end
@@ -471,6 +478,12 @@ module Parse
                 winner = _recover_from_duplicate_value(e, query_attrs, session: session, master_key: master_key)
                 raise unless winner
                 obj = winner
+              rescue Parse::Error::DuplicateRequestError
+                # See #first_or_create! — recover the row a retried create
+                # already landed (it already carries resource_attrs).
+                winner = _recover_from_duplicate_request(query_attrs, session: session, master_key: master_key)
+                raise unless winner
+                obj = winner
               end
             end
 
@@ -480,7 +493,15 @@ module Parse
               end
               if has_changes
                 obj.apply_attributes!(resource_attrs, dirty_track: true)
-                session ? obj.save!(session: session) : obj.save!
+                begin
+                  session ? obj.save!(session: session) : obj.save!
+                rescue Parse::Error::DuplicateRequestError
+                  # A retried update (PUT) landed but lost its response; re-find
+                  # the now-updated row and return it.
+                  winner = _recover_from_duplicate_request(query_attrs, session: session, master_key: master_key)
+                  raise unless winner
+                  obj = winner
+                end
               end
             end
 
@@ -617,6 +638,21 @@ module Parse
           _scoped_first(query_attrs, session: session, master_key: master_key)
         end
 
+        # @!visibility private
+        # Recovery for a request-id idempotency duplicate
+        # ({Parse::Error::DuplicateRequestError}, Parse code 159): the create's
+        # POST was rejected as a duplicate, which means a prior — transparently
+        # retried — attempt already created the row but lost its response. Re-find
+        # the row by the identifying `query_attrs` and return it (the row was
+        # created with `query_attrs.merge(resource_attrs)`, so it already carries
+        # the resource attributes). Returns nil if it cannot be located, in which
+        # case the caller re-raises the original error. Relies on `query_attrs`
+        # actually identifying the row — the same assumption the duplicate-value
+        # recovery and `first_or_create!`'s own find already make.
+        def _recover_from_duplicate_request(query_attrs, session: nil, master_key: nil)
+          _scoped_first(query_attrs, session: session, master_key: master_key)
+        end
+
         # @!visibility private
         # The pre-synchronize behavior of `first_or_create!`, factored out so
         # the synchronize wrapper can short-circuit when disabled. Preserves
@@ -627,7 +663,13 @@ module Parse
             obj = self.new query_attrs.merge(resource_attrs)
           end
           if obj.new?
-            session ? obj.save!(session: session) : obj.save!
+            begin
+              session ? obj.save!(session: session) : obj.save!
+            rescue Parse::Error::DuplicateRequestError
+              winner = _recover_from_duplicate_request(query_attrs, session: session, master_key: master_key)
+              raise unless winner
+              obj = winner
+            end
           end
           obj
         end
@@ -637,14 +679,26 @@ module Parse
           obj = _scoped_first(query_attrs, session: session, master_key: master_key)
           if obj.nil?
             obj = self.new query_attrs.merge(resource_attrs)
-            session ? obj.save!(session: session) : obj.save!
+            begin
+              session ? obj.save!(session: session) : obj.save!
+            rescue Parse::Error::DuplicateRequestError
+              winner = _recover_from_duplicate_request(query_attrs, session: session, master_key: master_key)
+              raise unless winner
+              obj = winner
+            end
           elsif !resource_attrs.empty?
             has_changes = resource_attrs.any? do |key, value|
               obj.respond_to?(key) && obj.send(key) != value
             end
             if has_changes
               obj.apply_attributes!(resource_attrs, dirty_track: true)
-              session ? obj.save!(session: session) : obj.save!
+              begin
+                session ? obj.save!(session: session) : obj.save!
+              rescue Parse::Error::DuplicateRequestError
+                winner = _recover_from_duplicate_request(query_attrs, session: session, master_key: master_key)
+                raise unless winner
+                obj = winner
+              end
             end
           end
           obj

data/lib/parse/model/core/embed_managed.rb

@@ -47,27 +47,32 @@ module Parse
     # provider can happen any time before the first save. Declaration
     # never makes a network call.
     #
-    # == Single vector per record (v5.0)
+    # == Single vector per record
     #
     # `embed` produces exactly one vector per record. All declared
     # source fields are concatenated (joined with "\n\n", blank values
-    # skipped) and sent to the provider as a single string. There is
-    # no built-in chunker in v5.0: long source text whose concatenation
-    # exceeds the provider's per-call token budget will be truncated
-    # provider-side, and the resulting vector will represent only the
-    # leading portion of the document.
+    # skipped) and sent to the provider as a single string. This
+    # directive is one-vector-per-record by design: long source text
+    # whose concatenation exceeds the provider's per-call token budget
+    # is truncated provider-side, and the stored vector represents only
+    # the leading portion of the document.
     #
-    # If your source text is long-form (full articles, long
-    # transcripts, multi-page PDFs), you have two options in v5.0:
+    # Chunking happens at RETRIEVAL time, not embed time. As of v5.2 the
+    # SDK ships {Parse::Retrieval.retrieve} and the `semantic_search`
+    # agent tool, which fetch the top-k whole records and split each
+    # record's text field into overlapping chunks for presentation
+    # (every chunk inherits its parent record's single score). That is
+    # presentation chunking — it does not change how embeddings are
+    # computed here.
+    #
+    # If you instead want each passage to have its OWN embedding (true
+    # embed-time chunking), keep one of these patterns:
     #
     # 1. Pre-chunk client-side and write each chunk as its own
     #    Parse::Object record with its own `embed` declaration.
-    # 2. Maintain a dedicated `Chunk` subclass that belongs_to the
-    #    parent record, with `embed :content, into: :embedding` on the
-    #    chunk class itself.
-    #
-    # A built-in chunker + `semantic_search` agent tool are scheduled
-    # for v5.1.
+    # 2. Maintain a dedicated chunk subclass that belongs_to the parent
+    #    record, with `embed :content, into: :embedding` on the chunk
+    #    class itself.
     module EmbedManaged
       # Raised when user code tries to assign directly to a vector
       # property that's managed by an {.embed} declaration. The intent