parse-stack-next 5.7.0 → 5.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a554fcec1f40152e03956f033d593c1a4a98fa09ef22e033c270721c701d336
-  data.tar.gz: 10db25291fc3e2f1e61a36df7499f5b38af2e4e04f73f72f7adfaca8c55dd156
+  metadata.gz: b773e88a55f8771a7d898978652e9be673ec496627fcbaa0b0eb68b950486812
+  data.tar.gz: 7813d865cb6cc09b6c44070186dbf67383304d9407a5de58fdbb723cce4dc081
 SHA512:
-  metadata.gz: aa3333741642e2faea789f829e23c37f3b72dccba2a4c5ed85b3601d2a945a58767cc65cd55ab9eb385225cf6d61cccbe0e4fb824891c273bc735c3c792916e5
-  data.tar.gz: 572f5a1bd5683d2e9a7aad5293e279401680e268359e3d9f805875453a92ac4ca570ac9c4da9a7c85542b986b91544fcf6adffe223314af0aef7a3828071f7cf
+  metadata.gz: 1ffa5266044c369c673c8c5e4e57d4b37d882674eae6d8f7c79f3b1a8318a75dbd76d97036337d8a5416cfdcc022c1db3353e20de53857eaf8e37ac29913dfa7
+  data.tar.gz: e897bb63c7030751cbb2a9720e6fde91e23f6c118a6656e9063a84df4ec7305db1e3f8dd141e600f2e9765fb3660fdd26b0c36c2c321184c9743c6be976498c9

data/CHANGELOG.md

@@ -1,5 +1,171 @@
 ## parse-stack-next Changelog
 
+### 5.7.2
+
+#### `between` accepts Ruby Range values
+
+- **NEW**: The `between` constraint now accepts a Ruby `Range` in addition to
+  a 2-element array, so `Person.where(:age.between => 5..25)` and
+  `Record.where(:date.between => 5.days.ago...2.days.ago)` work directly. An
+  inclusive range (`..`) maps its upper bound to `$lte`, matching the existing
+  array form, while an exclusive range (`...`) maps it to `$lt` instead.
+  Beginless (`..25`) and endless (`5..`) ranges are also supported and
+  constrain only the side that is present, so `Person.where(:age.between =>
+  18..)` compiles to `{"$gte" => 18}` with no upper bound. The array form is
+  unchanged, and both forms produce identical output for the same bounds.
+
+#### `Query#where_not_between` for the negated form of a range
+
+- **NEW**: `Query#where_not_between(field, value)` adds the logical negation
+  of `between`: `Person.query.where_not_between(:age, 5..25)` compiles to
+  `age < 5 OR age > 25`, accepting the same Range and 2-element Array forms
+  as `between` (exclusive ranges flip the upper side to `$gte`, and a
+  beginless or endless Range negates to a single one-sided comparison with
+  no `$or` needed). It is not available as a `field.not_between => value`
+  symbol constraint: a range's negation is inherently an `$or` of two
+  comparisons, and only one `$or` group can be safely merged into a
+  compiled query, so a symbol constraint that unilaterally emitted one
+  could silently collide with an existing `$or` from `or_where`/`|`.
+  `where_not_between` instead composes the negation the way
+  `Parse::Query.and` already does, so it correctly nests inside a query's
+  other `.where` conditions instead of replacing them, and raises
+  `ArgumentError` if the query already has an `$or` group rather than
+  silently dropping part of it.
+
+#### `embed_image` forwards a presigned URL when the source file has one
+
+- **FIXED**: `embed_image` always sent the source file's bare `file.url` to
+  the embedding provider (or to the SDK's own `:bytes`-mode downloader). On a
+  private-bucket file adapter (S3/GCS configured with `presignedUrl: true`),
+  `file.url` is the canonical URL with its signature stripped, so the
+  provider's fetch (or the SDK's download) got a 403 instead of the image.
+  `Parse::File` already captures the signed variant in `file.presigned_url`
+  whenever Parse Server returns one, but `embed_image` never read it.
+  Recompute now forwards `file.presigned_url` when it is present and not yet
+  expired, and falls back to the bare URL otherwise, for both `source: :url`
+  and `source: :bytes`. The stored digest is still keyed on the bare
+  canonical URL, so a save that only rotates the file's signature does not
+  trigger a needless re-embed. The validity check ignores
+  `presigned_url_valid?`'s default 60-second safety buffer (meant for a
+  browser render, not an immediate server-side fetch), since on a
+  private-bucket adapter the fallback URL is not fetchable at all and would
+  otherwise 403 for the last minute of every signature's life.
+  `Parse::Embeddings::ImageFetch::FetchedImage#url` now stores the
+  query-stripped URL rather than the presigned one, since a live signature
+  has no reason to survive into that value object's `#inspect` output.
+  `source: :url` mode can now forward a presigned URL to the embedding
+  provider under the same `Parse::Embeddings.trust_provider_url_fetch`
+  consent already required to forward any URL; operators relying on private
+  buckets should confirm the provider's egress handling covers
+  credential-bearing URLs, not just public ones.
+
+#### `Query#get` now resolves aliased `parse_class` names correctly
+
+- **FIXED**: `Query#get` looked up the target class with a raw
+  `Object.const_get(@table)`, which only worked when the Parse class name
+  matched the Ruby constant name exactly. A model that renames its table via
+  `parse_class "SomeOtherName"` was never found by this lookup, so `get`
+  silently fell back to a generic `Parse::Object`/`Parse::Pointer` instead of
+  hydrating the declared model. `Query#get` now passes the table name through
+  to `Parse::Object.build` as a string, letting it run its own
+  `Parse::Model.find_class` resolution, which already understands
+  `parse_class` aliasing.
+
+#### `_safe_warn` now writes through a configured logger
+
+- **FIXED**: Internal warnings for authentication, timeout, and cloud-code
+  errors (`Parse::Client._safe_warn`) always wrote to STDERR, even when an
+  app had configured `Parse.logger = Rails.logger` (or any other logger) for
+  the rest of its Parse request/response logging. These warnings now route
+  through `Parse::Middleware::Logging.logger` when one is configured, so they
+  land in the same place as the app's other logs; STDERR remains the fallback
+  when no logger is configured, matching prior behavior. Every call site
+  raises the corresponding typed `Parse::Error` immediately after this
+  warning, so a configured logger that itself raises (a closed handle, a
+  full disk, a remote-aggregator client erroring on a socket) now falls back
+  to STDERR rather than propagating in place of the real error and masking
+  it.
+
+### 5.7.1
+
+#### Cache-invalidation webhooks no longer break every application hook for the same trigger
+
+- **FIXED**: `Parse::Cache::Invalidation` raised `NoMethodError: undefined
+  method 'guard'` on every `_User`, `_Role`, and `_Session` trigger it
+  registered, and the failure was not contained. A webhook handler block is
+  bound to the payload before it runs, so the bare `guard` / `bump_subject` /
+  `subject_id` calls in the handler bodies resolved against
+  `Parse::Webhooks::Payload`, which defines none of them. `guard`'s own
+  `rescue` never ran, because it lives inside the body that was never entered,
+  so the error escaped into the route dispatcher. The dispatcher folds a
+  trigger's handlers with `Array#map`, which abandons the collection on the
+  first raise, and these triggers install during `Parse.setup` and therefore
+  sit ahead of every application handler for the same trigger. One
+  unresolvable method name silently prevented an application's own
+  `after_save "_User"` hook from running at all, so any work downstream of it
+  stopped without a visible cause. The handlers now call the module on an
+  explicit receiver captured in a local, which is independent of whatever
+  `self` the dispatcher binds. Applications that set
+  `cache_invalidation_hooks: false` to work around this can remove it.
+- **FIXED**: The invalidation tests dispatched handlers with a plain
+  `Proc#call`, which leaves `self` bound to the module the block closed over,
+  so every one of them passed against handlers that could not run in
+  production. They now dispatch through the real handler invocation and fail
+  against the broken code.
+
+#### Whether one failing `after_*` handler stops the rest is now a setting
+
+- **NEW**: `Parse::Webhooks.abort_after_callbacks_on_error` decides whether an
+  exception raised by one `after_*` handler prevents the remaining handlers for
+  that trigger from running. It defaults to `true`, which is the existing
+  behavior, so nothing changes on upgrade. Set it to `false` to isolate
+  handlers from each other: each one runs regardless of what an earlier one
+  raised, and the failure is reported with a warning and a
+  `parse.webhooks.handler_error` notification instead of being swallowed
+  silently. This was previously not a decision at all but a side effect of
+  folding handlers with `Array#map`, which abandons the collection on the
+  first raise. Registration order is not fully under an application's control,
+  since the SDK's own cache-invalidation triggers install during `Parse.setup`
+  and therefore sit ahead of handlers registered by application files loaded
+  later, so a single raising handler could silently prevent an application's
+  own hooks from running with nothing logged to say they had been skipped.
+- **BEHAVIOR**: The setting governs only whether later handlers still run.
+  Neither mode reverts anything: an `after_*` trigger fires once the write has
+  already committed, so there is no version of this setting that can undo a
+  save. `before_*` dispatch is untouched, and only the accumulating,
+  non-rejectable triggers (`after_save`, `after_delete`, `after_logout`) can
+  hold more than one handler in the first place. A rejectable `before_*`
+  trigger must deny if any handler denies, so its raise must continue to
+  abort.
+
+#### Failed transactions restore the object they rolled back
+
+- **FIXED**: A failed `Parse::Object.transaction` left the in-memory object
+  holding its modified values. The rollback snapshotted `Parse::Object#attributes`
+  and restored it, but that method returns a schema map of field name to type
+  symbol rather than values, so nothing was ever restored. Property values
+  live in `@<field>` instance variables; those are now what the rollback
+  captures and restores, including values nested inside arrays and hashes,
+  relation operation queues, and properties whose ivar did not exist before
+  the transaction. State is captured when the object first enters the
+  transaction rather than at `batch.add`, so the documented pattern of
+  mutating an object and adding it afterwards rolls back correctly.
+- **FIXED**: A failed transaction also left the object with broken change
+  tracking. Restoring the schema map defined `@attributes`, which is the
+  instance variable `ActiveModel::Dirty` keys its behavior on: once defined it
+  builds an `AttributeMutationTracker` over that hash instead of the
+  `ForcedMutationTracker` a `Parse::Object` needs, and `clear_changes!` then
+  called `forgetting_assignment` on the `[key, value]` pairs `Hash#map`
+  yields. Both call sites rescue and warn, so every rollback quietly
+  downgraded the object rather than failing. The rollback no longer defines
+  `@attributes`.
+- **FIXED**: The mongo-direct role-graph integration test gated on
+  `ANALYTICS_DATABASE_URI`, a production variable name the test stack never
+  sets, so both of its traversal assertions skipped on every run while the
+  per-file reporter still reported the file as passing. It now reads
+  `PARSE_TEST_MONGO_URI` like every other mongo-direct integration file and
+  still honors `ANALYTICS_DATABASE_URI` as an override.
+
 ### 5.7.0
 
 #### Cache keys move into a reserved, app-scoped keyspace
@@ -205,7 +371,7 @@
   Server's self-access rules, and role-only checks cannot claim a concrete
   member's pointer or `_User` self permission. CLP cache entries are isolated
   by Parse application so identically named classes cannot leak policy across
-  clients. These helpers are advisory—the eventual Parse Server request is
+  clients. These helpers are advisory: the eventual Parse Server request is
   still authoritative.
 
 #### Test infrastructure

data/lib/parse/agent/mcp_dispatcher.rb

@@ -191,7 +191,7 @@ module Parse
 
         result_hash = dispatch(method, params, agent, id, logger, subscription_manager)
         { status: result_hash[:status], body: result_hash[:body] }
-      rescue Parse::Agent::Unauthorized => e
+      rescue Parse::Agent::Unauthorized
         { status: 401, body: jsonrpc_error(body.is_a?(Hash) ? body["id"] : nil, -32001, "Unauthorized") }
       rescue StandardError => e
         # Do not leak the exception class name (gem fingerprinting). Server-
@@ -295,7 +295,7 @@ module Parse
         else
           { status: 200, body: jsonrpc_envelope(id, result: result) }
         end
-      rescue Parse::Agent::Unauthorized => e
+      rescue Parse::Agent::Unauthorized
         { status: 401, body: jsonrpc_error(id, -32001, "Unauthorized") }
       rescue Parse::Agent::AccessDenied
         # Class-authorization denial (agent_hidden / classes: allowlist), e.g.

data/lib/parse/agent.rb

@@ -2475,7 +2475,6 @@ module Parse
       end
 
       ActiveSupport::Notifications.instrument("parse.agent.tool_call", payload) do
-        response = nil
         # Install a fresh embedding accumulator for this tool span. The
         # process-wide "parse.embeddings.embed" subscriber records each
         # embed into it; the ensure below reads + restores it so the

data/lib/parse/cache/invalidation.rb

@@ -52,26 +52,111 @@ module Parse
           registered
         end
 
+        # Run a role-trigger invalidation.
+        #
+        # Public because the registered webhook block calls it on an explicit
+        # receiver. See {handle_identity_trigger} for why that matters.
+        #
+        # @!visibility private
+        # @param cache [Parse::Cache::Redis] the keyspace-configured cache.
+        # @return [void]
+        def handle_role_trigger(cache)
+          guard do
+            # A role write does not say which users are affected: membership
+            # and hierarchy changes arrive as relation deltas on `users` and
+            # `roles`, and the cached value is a flattened transitive closure,
+            # so a parent-role change reaches the members of every child.
+            # Clearing the whole plane is both correct and cheap under a
+            # scoped SCAN. Parse Server does the same, for the same reason.
+            cache.roles.clear
+            # Stamp the epoch so a *foreign* role entry written before this
+            # moment is rejected on read. Parse Server does not clear its own
+            # role cache on a `_Role` delete, so without this the next read
+            # would take its stale entry back and our clear would shorten
+            # revocation by nothing.
+            cache.roles.touch_epoch
+          end
+        end
+
+        # Run an identity-trigger invalidation.
+        #
+        # Public, and invoked on an explicit receiver, because a webhook
+        # handler block does NOT run with `self` bound to the module that
+        # created it. {Parse::Webhooks.invoke_handler} binds the block to the
+        # payload (`payload.define_singleton_method(name, &block)`), and the
+        # historical `payload.instance_exec(payload, &block)` did the same.
+        # A block body calling a bare `guard` / `bump_subject` / `subject_id`
+        # therefore resolved against {Parse::Webhooks::Payload}, which defines
+        # none of them, and raised `NoMethodError` on every `_User`, `_Role`,
+        # and `_Session` trigger.
+        #
+        # That failure was not contained. `guard`'s `rescue` lives inside
+        # `guard`'s own body, which was never entered, so the error escaped
+        # into `call_route`'s `registry.map`. `Array#map` abandons the whole
+        # collection on the first raise, and these triggers register at
+        # `Parse.setup` and therefore sit AHEAD of any application handler for
+        # the same trigger. One unresolvable method name silently prevented
+        # every application `after_save "_User"` hook from running at all.
+        #
+        # Capturing the module in a local and calling it explicitly is what
+        # makes the handler independent of whatever `self` the dispatcher
+        # binds.
+        #
+        # @!visibility private
+        # @param cache [Parse::Cache::Redis] the keyspace-configured cache.
+        # @param type [Symbol] the trigger being handled.
+        # @param payload [Parse::Webhooks::Payload] the incoming payload.
+        # @return [void]
+        def handle_identity_trigger(cache, type, payload)
+          guard do
+            case type
+            when :after_logout
+              # The only trigger Parse Server permits on `_Session`. The
+              # object's own sessionToken is scrubbed from the payload, but
+              # the token is captured from the requesting user before
+              # scrubbing, and for a logout that user *is* the session being
+              # ended. A master-key logout carries no user, so fall back to
+              # the generation bump.
+              #
+              # Pass the RAW token, not a pre-hashed digest.
+              # `Parse::Cache::SubCache#invalidate` hashes its `key`
+              # argument internally for the `:idn` family (see
+              # `SubCache#logical_key`), the same way `#get` / `#set` do.
+              # That is what makes a `set(raw_token, ...)` /
+              # `get(raw_token)` pair round-trip. Hashing here first and
+              # handing SubCache an already-hashed value made it hash the
+              # digest a second time, landing on a key nothing had ever
+              # written to, so logout silently failed to evict the entry.
+              token = payload.respond_to?(:session_token) ? payload.session_token : nil
+              if token && !token.to_s.empty?
+                cache.identity.invalidate(token.to_s)
+              else
+                bump_subject(cache, subject_id(payload))
+              end
+            else
+              # A `_User` write gives a user id, but identity entries are
+              # keyed by session token and no reverse map exists. Bumping a
+              # per-user generation invalidates every one of that user's
+              # entries in O(1), including tokens this process has never
+              # resolved, and without Parse Server's master-key `_Session`
+              # query.
+              bump_subject(cache, subject_id(payload))
+            end
+          end
+        end
+
         private
 
         def install_role_triggers!(cache)
+          # `invalidator` is a captured LOCAL, not `self`. The registered block
+          # runs with `self` rebound to the payload, so a bare method call in
+          # its body would resolve against `Parse::Webhooks::Payload`. A local
+          # closes over correctly regardless of the receiver the dispatcher
+          # binds.
+          invalidator = self
           TRIGGERS[:role].map do |(type, class_name)|
             Parse::Webhooks.route(type, class_name) do |payload|
-              guard do
-                # A role write does not say which users are affected: membership
-                # and hierarchy changes arrive as relation deltas on `users` and
-                # `roles`, and the cached value is a flattened transitive closure,
-                # so a parent-role change reaches the members of every child.
-                # Clearing the whole plane is both correct and cheap under a
-                # scoped SCAN. Parse Server does the same, for the same reason.
-                cache.roles.clear
-                # Stamp the epoch so a *foreign* role entry written before this
-                # moment is rejected on read. Parse Server does not clear its own
-                # role cache on a `_Role` delete, so without this the next read
-                # would take its stale entry back and our clear would shorten
-                # revocation by nothing.
-                cache.roles.touch_epoch
-              end
+              invalidator.handle_role_trigger(cache)
               true
             end
             [type, class_name]
@@ -79,43 +164,10 @@ module Parse
         end
 
         def install_identity_triggers!(cache)
+          invalidator = self
           TRIGGERS[:identity].map do |(type, class_name)|
             Parse::Webhooks.route(type, class_name) do |payload|
-              guard do
-                case type
-                when :after_logout
-                  # The only trigger Parse Server permits on `_Session`. The
-                  # object's own sessionToken is scrubbed from the payload, but
-                  # the token is captured from the requesting user before
-                  # scrubbing, and for a logout that user *is* the session being
-                  # ended. A master-key logout carries no user, so fall back to
-                  # the generation bump.
-                  #
-                  # Pass the RAW token, not a pre-hashed digest.
-                  # `Parse::Cache::SubCache#invalidate` hashes its `key`
-                  # argument internally for the `:idn` family (see
-                  # `SubCache#logical_key`), the same way `#get` / `#set` do —
-                  # that is what makes a `set(raw_token, ...)` /
-                  # `get(raw_token)` pair round-trip. Hashing here first and
-                  # handing SubCache an already-hashed value made it hash the
-                  # digest a second time, landing on a key nothing had ever
-                  # written to, so logout silently failed to evict the entry.
-                  token = payload.respond_to?(:session_token) ? payload.session_token : nil
-                  if token && !token.to_s.empty?
-                    cache.identity.invalidate(token.to_s)
-                  else
-                    bump_subject(cache, subject_id(payload))
-                  end
-                else
-                  # A `_User` write gives a user id, but identity entries are
-                  # keyed by session token and no reverse map exists. Bumping a
-                  # per-user generation invalidates every one of that user's
-                  # entries in O(1), including tokens this process has never
-                  # resolved, and without Parse Server's master-key `_Session`
-                  # query.
-                  bump_subject(cache, subject_id(payload))
-                end
-              end
+              invalidator.handle_identity_trigger(cache, type, payload)
               true
             end
             [type, class_name]

data/lib/parse/client/request.rb

@@ -17,12 +17,24 @@ module Parse
     # @!attribute [rw] body
     #   @return [Hash] the body of this request.
 
-    # TODO: Document opts and cache options.
-
     # @!attribute [rw] opts
-    #   @return [Hash] a set of options for this request.
+    #   @return [Hash] per-request options consumed by {Parse::Client#request}
+    #     when it builds the HTTP headers for this request. Recognized keys:
+    #     * `:cache` — `false` sends `Cache-Control: no-cache`; `:write_only`
+    #       skips the cache read but still writes the response; a `Numeric`
+    #       overrides the cache expiration (seconds) for this request only.
+    #     * `:use_master_key` — `false` forces the master key off for this
+    #       request even if the client has one configured.
+    #     * `:session_token` — a session token to authenticate this request as
+    #       a specific user, bypassing the client's default auth context.
+    #     * `:idempotent` — explicitly enables/disables idempotency-header
+    #       generation for this request, overriding the class-level defaults.
+    #     * `:request_id` — a caller-supplied idempotency key; see
+    #       {.enable_idempotency!}.
     # @!attribute [rw] cache
-    #   @return [Boolean]
+    #   @return [Boolean] unused by {Parse::Request} itself; retained as a
+    #     plain accessor for callers that stash a cache handle or flag
+    #     directly on the request object rather than through `opts[:cache]`.
     attr_accessor :method, :path, :body, :headers, :opts, :cache
 
     # @!visibility private

data/lib/parse/client.rb

@@ -505,23 +505,44 @@ module Parse
       end
 
       # @!visibility private
-      # Emit a redacted warning about a Parse::Response error to stderr.
+      # Emit a redacted warning about a Parse::Response error.
       #
       # Routes the response error string through
       # {Parse::Middleware::BodyBuilder.redact} to strip credentials (passwords,
       # tokens, sessionTokens, access_tokens, authData) before logging, and
       # truncates to {SAFE_WARN_MAX_ERROR_LENGTH} chars.
       #
+      # Writes through {Parse::Middleware::Logging.logger} when the app has
+      # configured one (`Parse.logger = ...`), so these warnings land wherever
+      # the rest of the app's Parse request/response logging goes instead of
+      # bypassing it. Falls back to plain `warn` (STDERR) when no logger is
+      # configured, matching prior behavior. Every call site immediately
+      # raises the corresponding typed {Parse::Error} right after calling
+      # this method, so a misbehaving app-supplied logger (closed handle,
+      # full disk, a remote-aggregator client that raises on socket error)
+      # must not be allowed to propagate in its place and mask the real
+      # error — falls back to `warn` if the logger itself raises.
+      #
       # @param tag [String] the bracketed prefix (e.g. "AuthenticationError").
       # @param response [Parse::Response] the response carrying the error.
       # @param name [String, nil] optional cloud-function or job name for context.
       # @return [nil]
       def _safe_warn(tag, response, name: nil)
         err = Parse::Middleware::BodyBuilder.redact(response.error.to_s)[0, SAFE_WARN_MAX_ERROR_LENGTH]
-        if name
-          warn "[Parse:#{tag}] `#{name}` [#{response.code}] #{err} (HTTP #{response.http_status})"
+        msg = if name
+            "[Parse:#{tag}] `#{name}` [#{response.code}] #{err} (HTTP #{response.http_status})"
+          else
+            "[Parse:#{tag}] [E-#{response.code}] #{response.request} : #{err} (#{response.http_status})"
+          end
+        logger = Parse::Middleware::Logging.logger
+        if logger
+          begin
+            logger.warn(msg)
+          rescue StandardError
+            warn msg
+          end
         else
-          warn "[Parse:#{tag}] [E-#{response.code}] #{response.request} : #{err} (#{response.http_status})"
+          warn msg
         end
         nil
       end

data/lib/parse/embeddings/image_fetch.rb

@@ -164,7 +164,15 @@ module Parse
 
         mime = verify!(bytes, url: canonical)
         bytes = strip_metadata(bytes, mime) if exif_strip
-        FetchedImage.new(bytes: bytes, mime_type: mime, url: canonical)
+        # Store the query-stripped URL, not `canonical` verbatim: when
+        # `url` is a presigned URL (a private-bucket file adapter),
+        # `canonical` carries a live signature, and FetchedImage#url is
+        # purely informational from here on (nothing re-fetches it).
+        # Keeping the signature out of the struct preserves the
+        # log-safety `#inspect` below was written for — third-party
+        # provider adapters and error reporters that capture locals
+        # would otherwise leak a valid bearer credential through it.
+        FetchedImage.new(bytes: bytes, mime_type: mime, url: Parse::File.strip_query(canonical))
       end
 
       # Verify raw bytes: sniff the magic, check the allowlist, and

data/lib/parse/embeddings.rb

@@ -382,6 +382,17 @@ module Parse
       # `"true"`, or a non-matching String) raises
       # {ConfirmationRequired}. Reset to `nil` to disable.
       #
+      # For a `:file` source backed by a private-bucket adapter
+      # (S3/GCS with server-side presigning), the URL forwarded under
+      # this sentinel may be the file's presigned URL rather than its
+      # bare canonical one — a time-limited bearer credential for that
+      # object, not just a pointer to it (see {Parse::File#presigned_url}
+      # and `Parse::Core::EmbedManaged.embed_image`). Reviewing the
+      # provider's egress behavior before setting this sentinel should
+      # account for that: the provider (and anyone with access to its
+      # request logs) gains temporary read access to the object for
+      # however long the signature remains valid.
+      #
       # @param value [String, nil] {TRUST_PROVIDER_URL_FETCH_SENTINEL} or nil.
       # @raise [ConfirmationRequired] on any other value.
       def trust_provider_url_fetch=(value)
@@ -395,10 +406,12 @@ module Parse
                 "String #{TRUST_PROVIDER_URL_FETCH_SENTINEL.inspect}. Plain `true` and " \
                 "other values are refused — forwarding image URLs to a third-party " \
                 "provider lets that provider issue an HTTP request from its own network " \
-                "with attacker-controllable host/path. Set the sentinel only after you " \
-                "have configured Parse::Embeddings.allowed_image_hosts AND reviewed the " \
-                "provider's documented egress behavior (DNS rebinding window, redirect " \
-                "policy)."
+                "with attacker-controllable host/path, and for a private-bucket file may " \
+                "hand it a time-limited presigned URL rather than a bare pointer. Set the " \
+                "sentinel only after you have configured " \
+                "Parse::Embeddings.allowed_image_hosts AND reviewed the provider's " \
+                "documented egress behavior (DNS rebinding window, redirect policy, " \
+                "request-log retention)."
         end
         CONFIG_MUTEX.synchronize { @trust_provider_url_fetch = value }
       end

data/lib/parse/model/associations/belongs_to.rb

@@ -243,6 +243,10 @@ module Parse
               instance_variable_set ivar, val
             end
 
+            # Capture after lazy hydration, before a caller can mutate an
+            # object returned by this association getter.
+            send(:_capture_transaction_state!) if respond_to?(:_capture_transaction_state!, true)
+
             # Track association source for N+1 detection when returning an unfetched pointer
             # Uses a registry instead of setting instance variables on the pointer object
             if val.is_a?(Parse::Pointer) && val.pointer? && Parse.warn_on_n_plus_one

data/lib/parse/model/associations/collection_proxy.rb

@@ -359,6 +359,9 @@ module Parse
 
     # Notifies the delegate that the collection changed.
     def notify_will_change!
+      if @delegate && @delegate.respond_to?(:_capture_transaction_state!, true)
+        @delegate.send(:_capture_transaction_state!)
+      end
       collection_will_change!
       forward "#{@key}_will_change!"
     end

data/lib/parse/model/associations/has_many.rb

@@ -502,6 +502,10 @@ module Parse
               val = instance_variable_get ivar
             end
 
+            # Capture before this getter materializes or returns a mutable
+            # proxy that can be changed in place.
+            send(:_capture_transaction_state!) if respond_to?(:_capture_transaction_state!, true)
+
             # if the result is not a collection proxy, then create a new one.
             unless val.is_a?(Parse::PointerCollectionProxy)
               results = []