parse-stack-next 5.5.3 → 5.5.5

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

@@ -31,13 +31,13 @@ module Parse
 
     # Error code 205 (Parse::Response::ERROR_EMAIL_NOT_FOUND) raised by
     # {Parse::User.login!} and {Parse::User#verify_password} when Parse Server
-    # returns code 205 because +preventLoginWithUnverifiedEmail+ is enabled and
+    # returns code 205 because `preventLoginWithUnverifiedEmail` is enabled and
     # the account's email address has not been verified.
     #
     # It is a SUBCLASS of {AuthenticationError} on purpose: before this typed
     # error existed, the unverified-email rejection raised a plain
-    # +AuthenticationError+, so existing callers wrapping {Parse::User.login!}
-    # in +rescue AuthenticationError+ must keep catching it (subclassing keeps
+    # `AuthenticationError`, so existing callers wrapping {Parse::User.login!}
+    # in `rescue AuthenticationError` must keep catching it (subclassing keeps
     # that contract — making it a sibling would be a silent breaking change).
     # Callers who want to special-case the unverified-email path just rescue
     # this narrower subclass FIRST.
@@ -62,12 +62,12 @@ module Parse
     # <tt>rescue Parse::Error::AuthenticationError</tt> handler covers both
     # wrong-credential failures and lockout situations. Callers that need to
     # distinguish the lockout case just rescue this narrower subclass first.
-    # Because the previous implementation raised a plain +RuntimeError+, there
-    # is no prior +AuthenticationError+ rescue contract to preserve — this is
+    # Because the previous implementation raised a plain `RuntimeError`, there
+    # is no prior `AuthenticationError` rescue contract to preserve — this is
     # a new typed entry in the login-failure taxonomy.
     #
-    # Note that +Parse::Error < StandardError+, so a bare +rescue+ or
-    # +rescue StandardError+ still catches this error.
+    # Note that `Parse::Error < StandardError`, so a bare `rescue` or
+    # `rescue StandardError` still catches this error.
     #
     # @example
     #   begin
@@ -266,7 +266,7 @@ module Parse
     # when the user follows the verification link delivered by the email
     # adapter, and applied to the in-memory object by {#signup!} / signup-on-save
     # when the server includes it in the signup response (see
-    # +SIGNUP_RESPONSE_APPLY_KEYS+).
+    # `SIGNUP_RESPONSE_APPLY_KEYS`).
     # @return [Boolean]
     property :email_verified, :boolean
 
@@ -322,16 +322,16 @@ module Parse
     # Thread-local key used by {.with_authdata_trust} to mark the
     # current hydration as a legitimate self-fetch (login/signup/MFA/
     # `/users/me`). Outside that scope, {#apply_attributes!} strips
-    # +authData+ from incoming server JSON so a `_User` query/find that
+    # `authData` from incoming server JSON so a `_User` query/find that
     # crosses ACL boundaries cannot leak another user's federated-identity
     # tokens into the in-memory object.
     AUTHDATA_TRUST_KEY = :__parse_stack_user_authdata_trusted
 
     class << self
       # @!visibility private
-      # Run +block+ in a scope where the next {Parse::User#apply_attributes!}
-      # call is permitted to hydrate +authData+ from the response. Used by
-      # +login+/+login!+/+session!+/+create+/+link_auth_data!+/MFA paths
+      # Run `block` in a scope where the next {Parse::User#apply_attributes!}
+      # call is permitted to hydrate `authData` from the response. Used by
+      # `login`/`login!`/`session!`/`create`/`link_auth_data!`/MFA paths
       # where the row being hydrated is provably the authenticating user.
       def with_authdata_trust
         prior = Thread.current[AUTHDATA_TRUST_KEY]
@@ -538,20 +538,20 @@ module Parse
     end
 
     # @!visibility private
-    # Defense-in-depth strip of +authData+ on the way into the in-memory
-    # User. Parse Server returns +authData+ on +GET /users/:id+ to any
-    # caller with ACL read on the row, and the default +_User+ ACL is
+    # Defense-in-depth strip of `authData` on the way into the in-memory
+    # User. Parse Server returns `authData` on `GET /users/:id` to any
+    # caller with ACL read on the row, and the default `_User` ACL is
     # permissive in many deployments — without this filter, fetching a
-    # different user (or iterating a +Parse::Query.new(User)+ result set)
-    # would expose their OAuth +access_token+ / +id_token+ to anyone who
+    # different user (or iterating a `Parse::Query.new(User)` result set)
+    # would expose their OAuth `access_token` / `id_token` to anyone who
     # JSON-renders the result (Rails views, agent tool output, logging).
     #
     # The strip runs unconditionally unless the caller is inside a
     # {.with_authdata_trust} scope, which is set by the self-fetch
     # paths in this file (login/login!/session!/create/link_auth_data!/
     # unlink_auth_data!) and by the MFA login extension. Trusted callers
-    # pass through to +super+ with the hash untouched. The PROTECTED
-    # mass-assignment filter that runs inside +super+ is unaffected.
+    # pass through to `super` with the hash untouched. The PROTECTED
+    # mass-assignment filter that runs inside `super` is unaffected.
     def apply_attributes!(hash, dirty_track: false, filter_protected: nil, protected_set: nil)
       if hash.is_a?(Hash) && !self.class.authdata_trusted?
         if hash.key?(:authData) || hash.key?("authData") ||
@@ -576,12 +576,12 @@ module Parse
     end
 
     # @!visibility private
-    # Reduce a server-returned +authData+ hash to a leak-safe MFA status.
-    # Parse Server returns +authData.mfa+ as +{ "secret" => ..., "recovery" =>
+    # Reduce a server-returned `authData` hash to a leak-safe MFA status.
+    # Parse Server returns `authData.mfa` as +{ "secret" => ..., "recovery" =>
     # [...] }+ (the raw TOTP secret and one-time recovery codes) even on a
     # user's own session-token read, so the value itself must never be retained.
-    # This keeps only +{ "mfa" => { "status" => "enabled" } }+ when MFA is
-    # configured, and returns +nil+ otherwise (preserving the prior
+    # This keeps only `{ "mfa" => { "status" => "enabled" } }` when MFA is
+    # configured, and returns `nil` otherwise (preserving the prior
     # strip-to-nil behavior for OAuth-only / non-MFA authData).
     # @return [Hash, nil]
     def sanitized_mfa_authdata(raw)
@@ -607,7 +607,7 @@ module Parse
     end
 
     # @return [Boolean] true if this user is anonymous (i.e. created
-    #   via the +authData.anonymous+ provider rather than via signup
+    #   via the `authData.anonymous` provider rather than via signup
     #   with a username/password or a real OAuth provider).
     def anonymous?
       !anonymous_id.nil?
@@ -640,15 +640,15 @@ module Parse
       self.class.with_authdata_trust { apply_attributes!(response.result) }
     end
 
-    # Upgrade an anonymous user (one created via the +authData.anonymous+
+    # Upgrade an anonymous user (one created via the `authData.anonymous`
     # provider) into a full username/password account. This is the
     # SDK-side counterpart of the Parse JS SDK's
-    # +_linkWith('username', ...)+ flow — it sends a single
-    # +PUT /users/:id+ with the new credentials and an explicit
-    # +authData: { anonymous: nil }+ unlink in the same body, then
+    # `_linkWith('username', ...)` flow — it sends a single
+    # `PUT /users/:id` with the new credentials and an explicit
+    # `authData: { anonymous: nil }` unlink in the same body, then
     # narrowly applies the server's response to the in-memory user.
     #
-    # The +authData.anonymous+ unlink is essential: leaving the anonymous
+    # The `authData.anonymous` unlink is essential: leaving the anonymous
     # provider attached after assigning a username would let anyone else
     # who somehow learned the (random) anonymous id silently log in as
     # the freshly-named account, a documented Parse foot-gun.
@@ -658,9 +658,9 @@ module Parse
     # @param email [String, nil] optional email address. Must be unique
     #   if provided.
     # @raise [Parse::Error::AuthenticationError] when this instance has
-    #   no attached +@session_token+, no objectId, or is not anonymous.
-    # @raise [Parse::Error::UsernameMissingError] when +username+ is blank.
-    # @raise [Parse::Error::PasswordMissingError] when +password+ is blank.
+    #   no attached `@session_token`, no objectId, or is not anonymous.
+    # @raise [Parse::Error::UsernameMissingError] when `username` is blank.
+    # @raise [Parse::Error::PasswordMissingError] when `password` is blank.
     # @raise [Parse::Error::UsernameTakenError] when Parse Server reports
     #   the username already exists.
     # @raise [Parse::Error::EmailTakenError] when Parse Server reports
@@ -929,9 +929,9 @@ module Parse
     def session
       if @session.blank? && @session_token.present?
         response = client.fetch_session(@session_token)
-        # Trusted hydration: +response.result+ is the server-side
-        # _Session row, which legitimately includes +sessionToken+,
-        # +createdAt+, +updatedAt+, and other protected keys. Route
+        # Trusted hydration: `response.result` is the server-side
+        # _Session row, which legitimately includes `sessionToken`,
+        # `createdAt`, `updatedAt`, and other protected keys. Route
         # through {Parse::Object.build} which handles the trusted-init
         # signalling.
         @session ||= Parse::Object.build(response.result, Parse::Model::CLASS_SESSION)
@@ -940,9 +940,9 @@ module Parse
     end
 
     # A non-master {Parse::Client} bound to this user's session token, for
-    # acting on the server *as this user* with full ACL / CLP / +protectedFields+
+    # acting on the server *as this user* with full ACL / CLP / `protectedFields`
     # enforcement and no master-key fallback. It mirrors the connection settings
-    # of +base+ (the configured client by default) but carries no master key and
+    # of `base` (the configured client by default) but carries no master key and
     # binds {#session_token}, so even raw REST calls through it are authorized as
     # the user with no per-call ceremony. The web-counterpart of
     # {Parse::Webhooks::Payload#user_client}; the typical client-side entry point
@@ -952,7 +952,7 @@ module Parse
     #   Parse::Query.new("Post", client: client).results   # scoped to the user
     #
     # @param base [Parse::Client] the client whose connection settings to mirror.
-    # @return [Parse::Client, nil] +nil+ when the user has no session token
+    # @return [Parse::Client, nil] `nil` when the user has no session token
     #   (e.g. fetched/saved under the master key rather than logged in).
     def session_client(base = self.client)
       return nil if @session_token.nil? || @session_token.to_s.strip.empty?
@@ -960,23 +960,23 @@ module Parse
     end
 
     # @!visibility private
-    # Keys that must never flow through +Parse::User.create+ from a
-    # mass-assigned hash. +authData+ on the user-signup endpoint causes
+    # Keys that must never flow through `Parse::User.create` from a
+    # mass-assigned hash. `authData` on the user-signup endpoint causes
     # Parse Server to silently log into the existing account that matches
     # that auth_data and return ITS sessionToken — full account takeover
     # if the caller blindly forwards client-supplied parameters.
-    # +objectId+ allows the caller to pick the user's identifier on
+    # `objectId` allows the caller to pick the user's identifier on
     # creation, sometimes targetable depending on Parse Server config.
     UNSAFE_CREATE_KEYS = %i[authData auth_data objectId id].freeze
 
     # @!visibility private
     # Fields that are server-controlled and must be stripped from any body
-    # that the SDK sends to the signup endpoint or +Parse::User.create+,
+    # that the SDK sends to the signup endpoint or `Parse::User.create`,
     # regardless of who supplied them. Unlike {UNSAFE_CREATE_KEYS}, passing
     # one of these is not refused (no exception is raised); the field is
     # silently dropped before wire transit.
     #
-    # +emailVerified+ is the canonical case: Parse Server's default `_User`
+    # `emailVerified` is the canonical case: Parse Server's default `_User`
     # CLP restricts writes to the master key, so a caller-supplied value
     # would normally be rejected anyway — but the SDK strips it as
     # defense-in-depth so signup with mass-assigned attributes cannot
@@ -1008,7 +1008,7 @@ module Parse
 
     # Creates a new Parse::User given a hash that maps to the fields defined in your Parse::User collection.
     #
-    # Mass-assignment of +authData+/+auth_data+/+objectId+ is refused. If you
+    # Mass-assignment of `authData`/`auth_data`/`objectId` is refused. If you
     # intend to create-or-login a user via federated identity, use
     # {.autologin_service} or {.link_or_create_with_auth_data}. Passing
     # those keys directly bypasses the SDK's federated-identity wrapper
@@ -1017,7 +1017,7 @@ module Parse
     #
     # @param body [Hash] The hash containing the Parse::User fields. The field `username` and `password` are required.
     # @option opts [Boolean] :master_key Whether the master key should be used for this request.
-    # @raise [ArgumentError] If +body+ contains +authData+/+auth_data+/+objectId+ — use {.autologin_service} for federated flows.
+    # @raise [ArgumentError] If `body` contains `authData`/`auth_data`/`objectId` — use {.autologin_service} for federated flows.
     # @raise [Parse::Error::UsernameMissingError] If username is missing.
     # @raise [Parse::Error::PasswordMissingError] If password is missing.
     # @raise [Parse::Error::UsernameTakenError] If the username has already been taken.
@@ -1057,11 +1057,11 @@ module Parse
     end
 
     # @!visibility private
-    # Silently strips {SERVER_CONTROLLED_KEYS} from +body+ in place. Used
+    # Silently strips {SERVER_CONTROLLED_KEYS} from `body` in place. Used
     # by {.create}, {#signup!}, and {#signup_create} as defense-in-depth so
     # caller-supplied values for fields that Parse Server is meant to
-    # control (currently just +emailVerified+) never reach the wire.
-    # @return [Hash, Object] the same +body+ object, mutated.
+    # control (currently just `emailVerified`) never reach the wire.
+    # @return [Hash, Object] the same `body` object, mutated.
     def self.strip_server_controlled_keys!(body)
       return body unless body.is_a?(Hash)
       SERVER_CONTROLLED_KEYS.each do |k|
@@ -1072,10 +1072,10 @@ module Parse
     end
 
     # @!visibility private
-    # Raises +ArgumentError+ if +body+ carries keys that would let an
-    # attacker turn +Parse::User.create+ into an account-takeover sink.
+    # Raises `ArgumentError` if `body` carries keys that would let an
+    # attacker turn `Parse::User.create` into an account-takeover sink.
     # Skipped when called through the SDK's federated-identity wrapper
-    # ({.autologin_service}), which deliberately supplies +authData+ and
+    # ({.autologin_service}), which deliberately supplies `authData` and
     # is responsible for its provenance.
     def self.assert_create_body_safe!(body)
       return unless body.is_a?(Hash)
@@ -1102,7 +1102,7 @@ module Parse
     # @see User.create
     def self.autologin_service(service_name, auth_data, body: {})
       # Trust-mark this call so {.assert_create_body_safe!} permits the
-      # +authData+ that we are explicitly responsible for here. The
+      # `authData` that we are explicitly responsible for here. The
       # marker is consumed inside {.create} before forwarding to the
       # server.
       body = body.merge({
@@ -1113,15 +1113,15 @@ module Parse
     end
 
     # Create and log in a new anonymous user via the
-    # +authData.anonymous+ provider. The returned user instance has a
-    # +session_token+ and an objectId, and {#anonymous?} returns true.
+    # `authData.anonymous` provider. The returned user instance has a
+    # `session_token` and an objectId, and {#anonymous?} returns true.
     # Later, after the user has chosen a username and password, upgrade
     # the account in-place with {#upgrade_anonymous!}.
     #
     # Parse Server requires the anonymous-provider payload to include a
-    # client-generated +id+; this helper produces one via
-    # +SecureRandom.uuid+ so callers don't have to hand-roll the
-    # +authData+ shape.
+    # client-generated `id`; this helper produces one via
+    # `SecureRandom.uuid` so callers don't have to hand-roll the
+    # `authData` shape.
     #
     # @return [User] a freshly-created, logged-in anonymous user.
     # @see #upgrade_anonymous!
@@ -1176,7 +1176,7 @@ module Parse
         case response.code
         when Parse::Response::ERROR_EMAIL_NOT_FOUND
           # Parse Server throws code 205 (EMAIL_NOT_FOUND) when
-          # +preventLoginWithUnverifiedEmail+ is set and the account's email
+          # `preventLoginWithUnverifiedEmail` is set and the account's email
           # address has not yet been verified. Raise the typed error so callers
           # can direct the user to verify their inbox without catching every
           # AuthenticationError.
@@ -1398,24 +1398,24 @@ module Parse
 
     # Verify this user's password without minting a session token.
     #
-    # Delegates to the +GET /parse/verifyPassword+ endpoint (Parse Server
-    # 7.1.0+) using this user's +username+ and the supplied +password+. The
+    # Delegates to the `GET /parse/verifyPassword` endpoint (Parse Server
+    # 7.1.0+) using this user's `username` and the supplied `password`. The
     # check is purely credential validation — no session is created on
     # success, and the user's existing sessions are unaffected.
     #
     # Use this as a step-up authentication gate: before allowing a sensitive
     # action (e.g. changing an email address or deleting an account), call
-    # +verify_password+ to confirm the caller still knows the password.
+    # `verify_password` to confirm the caller still knows the password.
     #
     # @param password [String] the password to verify.
-    # @return [Boolean] +true+ if the credentials are valid.
+    # @return [Boolean] `true` if the credentials are valid.
     # @raise [Parse::Error::EmailNotVerifiedError] when the account exists but
-    #   +preventLoginWithUnverifiedEmail+ is enabled and the email has not been
+    #   `preventLoginWithUnverifiedEmail` is enabled and the email has not been
     #   verified (Parse Server error code 205). The caller may want to prompt
     #   the user to check their inbox rather than treating this as a wrong-
     #   password failure.
     # @raise [Parse::Error::AuthenticationError] when the username does not
-    #   exist or the password is wrong (code 101, +OBJECT_NOT_FOUND+).
+    #   exist or the password is wrong (code 101, `OBJECT_NOT_FOUND`).
     # @return [Boolean]
     # @example
     #   # Step-up check before a destructive action
@@ -1472,7 +1472,7 @@ module Parse
     # use `master: true` for the previous behavior.
     #
     # @param max_depth [Integer] maximum BFS depth (default: 10).
-    # @param master [Boolean] when +true+, bypass `_Role` CLP and run
+    # @param master [Boolean] when `true`, bypass `_Role` CLP and run
     #   the role-graph lookup under master mode. Use for ACL-building
     #   code paths inside the SDK or in admin tooling.
     # @param as [Parse::User, Parse::Pointer, nil] caller-scope. When
@@ -1480,7 +1480,7 @@ module Parse
     #   case). Pass a different user to ask "what would this caller
     #   see when introspecting this user's roles?"; the scope's
     #   permission set is checked against `_Role` CLP.
-    # @return [Set<String>] role names (no +role:+ prefix). Empty set
+    # @return [Set<String>] role names (no `role:` prefix). Empty set
     #   when the user has no objectId yet or holds no roles.
     # @raise [Parse::CLPScope::Denied] when the scope cannot `find`
     #   on `_Role` under the current CLP.

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

@@ -19,8 +19,8 @@ module Parse
     end
   end
 
-  # Namespace where +Parse.auto_generate_models!+ installs dynamically
-  # generated +Parse::Object+ subclasses derived from server-side schema.
+  # Namespace where `Parse.auto_generate_models!` installs dynamically
+  # generated `Parse::Object` subclasses derived from server-side schema.
   # Isolating them here prevents server-returned className strings from
   # rebinding top-level constants like ::File, ::Logger, ::Process.
   module Generated
@@ -39,9 +39,9 @@ module Parse
       # Parse Server system classes that ship with the SDK as hand-written
       # subclasses (Parse::User, Parse::Role, etc.). Schema-driven builds
       # must NOT install additional fields or associations on these — a
-      # compromised Parse Server could otherwise inject an +is_admin+
-      # property onto the real +Parse::User+ class, or a +password_history+
-      # accessor onto +_Session+, by returning a poisoned schema.
+      # compromised Parse Server could otherwise inject an `is_admin`
+      # property onto the real `Parse::User` class, or a `password_history`
+      # accessor onto `_Session`, by returning a poisoned schema.
       PROTECTED_SYSTEM_CLASSES = %w[
         _User _Role _Session _Installation _Product _Audience _PushStatus
         _JobStatus _JobSchedule _Hooks _GlobalConfig _SCHEMA _GraphQLConfig
@@ -123,8 +123,8 @@ module Parse
       end
 
       # @!visibility private
-      # Validates a server-returned +targetClass+ string before forwarding
-      # it to +belongs_to+/+has_many+. Returns +nil+ for missing or
+      # Validates a server-returned `targetClass` string before forwarding
+      # it to `belongs_to`/`has_many`. Returns `nil` for missing or
       # invalid values so the association DSL falls back to its inferred
       # default rather than installing an attacker-controlled class name
       # (which could pivot a later type-confusion bypass).

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

@@ -78,7 +78,7 @@ module Parse
             source: "Parse::CreateLock",
             unavailable_error: Parse::CreateLockUnavailableError,
           )
-          return LockBackend.process_mutex(key).synchronize(&block)
+          return LockBackend.synchronize_process_mutex(key, &block)
         end
 
         owner = SecureRandom.uuid

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

@@ -708,13 +708,13 @@ module Parse
     #   writers when the caller is trusted.
     # @param filter_protected [Boolean, nil] whether to filter out
     #   {Parse::Properties::PROTECTED_MASS_ASSIGNMENT_KEYS}. Defaults to
-    #   +dirty_track+ for backwards-compat (the historical coupling). Callers
-    #   can pass +true+ explicitly to filter even on the trusted hydration
+    #   `dirty_track` for backwards-compat (the historical coupling). Callers
+    #   can pass `true` explicitly to filter even on the trusted hydration
     #   path (used by {Parse::Object#initialize} when constructed with
-    #   +trusted: false+ but an +objectId+ is in the hash). +false+ explicitly
+    #   `trusted: false` but an `objectId` is in the hash). `false` explicitly
     #   preserves the legacy "server response" semantics.
     # @param protected_set [Array<String>, nil] override which key list to
-    #   filter when +filter_protected+ is true. Defaults to the wider
+    #   filter when `filter_protected` is true. Defaults to the wider
     #   {Parse::Properties::PROTECTED_MASS_ASSIGNMENT_KEYS}.
     #   {Parse::Object#initialize} passes
     #   {Parse::Properties::PROTECTED_INITIALIZE_KEYS} here to allow

data/lib/parse/model/file.rb

@@ -69,7 +69,7 @@ module Parse
 
     # @!visibility private
     # Default cap on remote-fetched file size (50 MiB). Override via
-    # +Parse::File.max_remote_size+.
+    # `Parse::File.max_remote_size`.
     DEFAULT_MAX_REMOTE_SIZE = 50 * 1024 * 1024
     # @!visibility private
     # Default read/open timeout for remote fetches in seconds.
@@ -90,7 +90,7 @@ module Parse
     ].map { |c| IPAddr.new(c) }.freeze
     # Restrictive port allowlist for Parse::File URL fetches. By default
     # only the standard HTTP/HTTPS ports are permitted. Operators may
-    # extend +Parse::File.allowed_remote_ports+ for legitimate non-standard
+    # extend `Parse::File.allowed_remote_ports` for legitimate non-standard
     # CDN ports.
     DEFAULT_ALLOWED_REMOTE_PORTS = [80, 443, 8080, 8443].freeze
     # @return [String] the name of the file including extension (if any)
@@ -164,7 +164,7 @@ module Parse
       end
 
       # @return [Integer] Maximum byte size for a remote URL fetch via
-      #   +Parse::File.create+ / +Parse::File.new(url)+.
+      #   `Parse::File.create` / `Parse::File.new(url)`.
       attr_writer :max_remote_size
       def max_remote_size
         @max_remote_size ||= DEFAULT_MAX_REMOTE_SIZE
@@ -526,16 +526,22 @@ module Parse
       # the caller can read from.
       #
       # DNS rebinding mitigation: the host is resolved twice — once before
-      # the fetch and once via +URI.open+'s underlying resolver. The
-      # second-pass addresses are re-validated against +BLOCKED_CIDRS+;
-      # any new private/internal IP causes an +ArgumentError+ at progress
+      # the fetch and once via `URI.open`'s underlying resolver. The
+      # second-pass addresses are re-validated against `BLOCKED_CIDRS`;
+      # any new private/internal IP causes an `ArgumentError` at progress
       # time so the body cannot be streamed back. (Caveat: this is a
-      # best-effort defense — the TCP +connect()+ uses a third resolution
+      # best-effort defense — the TCP `connect()` uses a third resolution
       # that we cannot intercept without a custom socket factory. Operators
       # who need strict guarantees should also enforce egress allowlists
       # at the network layer.)
       # @raise [ArgumentError] on any disallowed input or unsafe target.
-      def safe_open_url(url_string)
+      def safe_open_url(url_string, max_bytes: nil)
+        # Validate the per-call streaming cap up front. A non-positive value is
+        # a caller error, not a "cap everything" instruction: 0 would reject any
+        # non-empty body, and a negative cap makes `max_bytes < size_cap` always
+        # true, driving size_cap negative so every non-empty response raises
+        # "exceeds". Fail fast with a clear message before any DNS/host work.
+        max_bytes = coerce_positive_max_bytes(max_bytes)
         uri = begin
           URI.parse(url_string)
         rescue URI::InvalidURIError => e
@@ -561,14 +567,22 @@ module Parse
         end
         resolved = assert_host_allowed!(host)
 
+        # The global cap always bounds the stream; a caller may pass a
+        # tighter `max_bytes:` to abort even earlier (e.g. image fetch with
+        # a per-request ceiling below Parse::File.max_remote_size). Only a
+        # smaller value takes effect — a caller cannot loosen the global cap.
+        # `max_bytes` is already a validated positive Integer (or nil) here.
+        # Only a value below the global cap takes effect — a caller cannot
+        # loosen the global ceiling.
         size_cap = max_remote_size
+        size_cap = max_bytes if max_bytes && max_bytes < size_cap
         timeout = remote_timeout
         uri.open(read_timeout: timeout,
                  open_timeout: timeout,
                  redirect: false,
                  content_length_proc: ->(len) {
                    if len && len > size_cap
-                     raise ArgumentError, "Remote file exceeds Parse::File.max_remote_size (#{size_cap} bytes)"
+                     raise ArgumentError, "Remote file exceeds the size cap (#{size_cap} bytes)"
                    end
                    # DNS-rebinding re-check: by the time content_length_proc
                    # fires, the connection has been established. Re-resolve
@@ -577,14 +591,33 @@ module Parse
                  },
                  progress_proc: ->(transferred) {
                    if transferred > size_cap
-                     raise ArgumentError, "Remote file exceeds Parse::File.max_remote_size (#{size_cap} bytes)"
+                     raise ArgumentError, "Remote file exceeds the size cap (#{size_cap} bytes)"
                    end
                  })
       end
 
       # @!visibility private
-      # Validates that +host+ resolves only to public, non-blocked addresses.
-      # When +Parse::File.allowed_remote_hosts+ is non-empty, host must also
+      # Coerce a caller-supplied `max_bytes:` to a positive Integer, or nil
+      # when unset. A non-numeric, zero, or negative value raises ArgumentError
+      # — the streaming cap is a positive byte ceiling, never a sentinel.
+      # @return [Integer, nil]
+      def coerce_positive_max_bytes(max_bytes)
+        return nil if max_bytes.nil?
+        requested =
+          begin
+            Integer(max_bytes)
+          rescue ArgumentError, TypeError
+            raise ArgumentError, "max_bytes must be a positive integer (got #{max_bytes.inspect})"
+          end
+        unless requested.positive?
+          raise ArgumentError, "max_bytes must be a positive integer (got #{requested})"
+        end
+        requested
+      end
+
+      # @!visibility private
+      # Validates that `host` resolves only to public, non-blocked addresses.
+      # When `Parse::File.allowed_remote_hosts` is non-empty, host must also
       # match an allowlist entry.
       # @return [Array<IPAddr>] the addresses that passed validation.
       def assert_host_allowed!(host)
@@ -614,10 +647,18 @@ module Parse
       end
 
       # @!visibility private
-      # DNS rebinding re-check. Resolves +host+ again and refuses if any
-      # currently-resolved address is private or differs from the first
-      # resolution. Best-effort: kernel resolver caches and a third
-      # resolution at connect-time are out of scope.
+      # DNS rebinding re-check, best-effort. After the connection is
+      # established, re-resolves `host` and refuses if any currently-resolved
+      # address is private/internal (in BLOCKED_CIDRS) — the SSRF shape where a
+      # host that first resolved to a public address later rebinds to an
+      # internal one. It deliberately does NOT require the re-resolved set to
+      # equal the first resolution (`prior_addrs`): legitimate round-robin / CDN
+      # hosts return different public IPs per lookup, and the HTTP client
+      # resolves the actual socket itself, so pinning to the first IPs here
+      # would add false positives without binding the real connection.
+      # `prior_addrs` only gates the check to the case where the initial
+      # resolution succeeded. Kernel resolver caches and a resolution at
+      # connect-time proper are out of scope.
       def assert_host_not_rebound!(host, prior_addrs)
         return if prior_addrs.nil? || prior_addrs.empty?
         current = resolve_addresses(host)

data/lib/parse/model/model.rb

@@ -81,15 +81,15 @@ module Parse
     # leading-underscore storage form. Consulted by {String#to_parse_class}
     # ONLY as a fallback when {find_class} cannot resolve the name — which
     # happens at class-declaration time for a built-in whose Ruby class is not
-    # yet registered (e.g. +Parse::Installation+ declares +belongs_to :user+
-    # before +Parse::User+ is loaded). Without this fallback the conversion
-    # froze the wrong literal (+"User"+) into the association +references+ map
-    # and pushed it to the server schema as the pointer +targetClass+, which
-    # Parse Server then rejected (+Pointer<User>+ vs +Pointer<_User>+). A
+    # yet registered (e.g. `Parse::Installation` declares `belongs_to :user`
+    # before `Parse::User` is loaded). Without this fallback the conversion
+    # froze the wrong literal (`"User"`) into the association `references` map
+    # and pushed it to the server schema as the pointer `targetClass`, which
+    # Parse Server then rejected (`Pointer<User>` vs `Pointer<_User>`). A
     # genuinely-registered class still wins via {find_class}, so a custom
-    # +parse_class+ table mapping is never overridden by this map.
+    # `parse_class` table mapping is never overridden by this map.
     # Keys are the camelized bare names (the form {String#to_parse_class}
-    # computes before lookup); only +User+ is actually targeted by a built-in
+    # computes before lookup); only `User` is actually targeted by a built-in
     # association before its class registers, the rest are hygiene so an app
     # that declares a pointer/relation to any built-in resolves correctly
     # regardless of load order.
@@ -235,27 +235,27 @@ module Parse
     # Whether two Parse class-name strings denote the same class. This is the
     # canonical equality used to suppress spurious className-mismatch warnings.
     # Two names are the same class when they are string-equal, when one is the
-    # leading-underscore system form of the other (+User+ <-> +_User+, +Role+
-    # <-> +_Role+, +Installation+ <-> +_Installation+, +Session+ <->
-    # +_Session+), or when both resolve to the same registered +Parse::Object+
-    # subclass (covers custom +parse_class+ table mappings).
+    # leading-underscore system form of the other (`User` <-> `_User`, `Role`
+    # <-> `_Role`, `Installation` <-> `_Installation`, `Session` <->
+    # `_Session`), or when both resolve to the same registered `Parse::Object`
+    # subclass (covers custom `parse_class` table mappings).
     #
     # The underscore rule is what makes the comparison correct independent of
     # autoload order — at declaration time {find_class} may not yet have
-    # +Parse::User+ registered (so a +belongs_to :user+ captures +"User"+
-    # rather than +"_User"+), but the server always emits the +_User+ storage
+    # `Parse::User` registered (so a `belongs_to :user` captures `"User"`
+    # rather than `"_User"`), but the server always emits the `_User` storage
     # form, and both denote the same class. The rule matches exactly one
-    # system prefix underscore, so a malformed +"__User"+ is not conflated
-    # with +"_User"+.
+    # system prefix underscore, so a malformed `"__User"` is not conflated
+    # with `"_User"`.
     #
     # These warnings are an ADVISORY type-confusion signal, not the
     # enforcement mechanism: every call site that consults this method builds
     # the resulting object from the declared/trusted class regardless of the
-    # incoming className (see +Parse::Object.build+, which always uses the
-    # +table+ argument the caller passes). A false-positive here can therefore
+    # incoming className (see `Parse::Object.build`, which always uses the
+    # `table` argument the caller passes). A false-positive here can therefore
     # only suppress a log line — it can never route a pointer of the wrong
-    # class into a typed slot. Distinct classes still compare unequal (+User+
-    # vs +_Session+, +User+ vs +_Role+, and +nil+), so a genuinely mismatched
+    # class into a typed slot. Distinct classes still compare unequal (`User`
+    # vs `_Session`, `User` vs `_Role`, and `nil`), so a genuinely mismatched
     # pointer still surfaces in logs.
     #
     # @param a [String, Symbol, nil] a Parse class name.