parse-stack-next 5.8.0 → 5.8.1

data/lib/parse/stack/version.rb

@@ -6,6 +6,6 @@ module Parse
   # The Parse Server SDK for Ruby
   module Stack
     # The current version.
-    VERSION = "5.8.0"
+    VERSION = "5.8.1"
   end
 end

data/lib/parse/stack.rb

@@ -62,6 +62,25 @@ module Parse
   # the first attempt and gone by the retry; the fiber-local state lives
   # for the lifetime of the block).
   #
+  # Mongo-direct reads follow the same rule: an explicit `master: true`
+  # passed to `Parse::MongoDB.aggregate`, a `Parse::Query` direct terminal,
+  # Atlas Search, or vector search runs in the public scope inside the
+  # block (or raises `ACLRequired` when `require_session_token` is on), and
+  # the `parse.mongodb.aggregate` notification payload carries
+  # `master_dropped: true`. `Parse::AtlasSearch.faceted_search` refuses to
+  # run inside the block. A LiveQuery admin connection opened inside the
+  # block sends no master key; one that already connected with it stays
+  # elevated, because Parse Server authorizes per connection.
+  #
+  # The SDK's own metadata reads keep the master key inside the block: the
+  # class schemas and role graph it reads to enforce a scope, index
+  # statistics, and the Atlas Search index listing. Those requests are
+  # marked individually; the block's state is never lifted while they run.
+  #
+  # This is a guard against accidental master-key use, not an isolation
+  # boundary. Code inside the block can call {Parse.with_master_key}, and
+  # `Parse::MongoDB.find` and `Parse::MongoDB.indexes` take no scope at all.
+  #
   # @yield runs the block with master-key disabled
   # @return [Object] the block's return value
   # @example

data/lib/parse/vector_search/hybrid.rb

@@ -399,9 +399,10 @@ module Parse
         # Build the native `$rankFusion` pipeline (without ACL/CLP
         # stages). Public-ish via {.native_pipeline} for snapshot tests;
         # the live path appends ACL enforcement in {#run_native}.
-        def build_rank_fusion_stage(lex, vec, oversample, k_constant:, weights:)
-          vsel = vector_search_stage(vec, oversample)
-          lsel = lexical_search_stage(lex, oversample)
+        def build_rank_fusion_stage(lex, vec, oversample, k_constant:, weights:,
+                                    owner_vector_filter: nil, owner_match: nil)
+          vsel = vector_search_stage(vec, oversample, owner_filter: owner_vector_filter)
+          lsel = lexical_search_stage(lex, oversample, owner_match: owner_match)
           stage = {
             "input" => {
               "pipelines" => { "vector" => vsel, "lexical" => lsel },
@@ -437,19 +438,44 @@ module Parse
           # AFTER the ACL `$match`, so trimming to `k` there would
           # reintroduce the underfill the window exists to prevent. The
           # trim to `k` happens client-side once enforcement is done.
+          pointer_fields = resolve_pointer_fields!(collection_name, resolution)
           native_pipeline_for(lex, vec, candidate_window, resolution,
                               k_constant: fusion[:k_constant] || DEFAULT_K_CONSTANT,
-                              weights: fusion[:weights], limit: candidate_window)
-        end
-
-        def native_pipeline_for(lex, vec, oversample, resolution, k_constant:, weights:, limit:)
-          pipeline = [build_rank_fusion_stage(lex, vec, oversample, k_constant: k_constant, weights: weights)]
+                              weights: fusion[:weights], limit: candidate_window,
+                              pointer_fields: pointer_fields,
+                              owner_vector_filter: owner_vector_filter(collection_name, vec, pointer_fields, resolution))
+        end
+
+        def native_pipeline_for(lex, vec, oversample, resolution, k_constant:, weights:, limit:,
+                                pointer_fields: nil, owner_vector_filter: nil)
+          scoped = !(resolution.nil? || resolution.master?)
+          # Ownership inside each `$rankFusion` input as well as after it:
+          # every input is capped at `oversample`, so a final `$match`
+          # alone only sees the fused top rows and can underfill when
+          # other users' rows dominate both branches. The lexical input
+          # filters before its `$limit`; the vector input uses the
+          # `$vectorSearch.filter` prefilter when the owner path is
+          # filter-indexed and served (see Parse::VectorSearch).
+          owner_match = if scoped && pointer_fields
+              Parse::CLPScope.pointer_fields_predicate(pointer_fields, resolution.user_id)
+            end
+          pipeline = [build_rank_fusion_stage(lex, vec, oversample, k_constant: k_constant, weights: weights,
+                                                                    owner_vector_filter: (owner_vector_filter if scoped),
+                                                                    owner_match: owner_match)]
           # The fused RRF score is surfaced via `{ $meta: "score" }`
           # (a numeric), not "scoreDetails" (a breakdown document).
           pipeline << { "$addFields" => { "_hybrid_score" => { "$meta" => "score" } } }
           unless resolution.nil? || resolution.master?
             acl_match = Parse::ACLScope.match_stage_for(resolution)
             pipeline << acl_match if acl_match
+            # pointerFields / readUserFields ownership before `$limit`, so
+            # rows ranked above the caller's own rows cannot crowd them
+            # out of the page.
+            if pointer_fields
+              pipeline << {
+                "$match" => Parse::CLPScope.pointer_fields_predicate(pointer_fields, resolution.user_id),
+              }
+            end
           end
           pipeline << { "$sort" => { "_hybrid_score" => -1 } }
           pipeline << { "$limit" => limit }
@@ -491,8 +517,11 @@ module Parse
             )
           end
 
+          owner_filter = owner_vector_filter(collection_name, vec, pointer_fields, resolution)
           pipeline = native_pipeline_for(lex, vec, oversample, resolution,
-                                         k_constant: k_constant, weights: weights, limit: oversample)
+                                         k_constant: k_constant, weights: weights, limit: oversample,
+                                         pointer_fields: pointer_fields,
+                                         owner_vector_filter: owner_filter)
           rows = run_pipeline!(collection_name, pipeline,
                                authorizing_client: Parse::ACLScope.client_of(resolution))
 
@@ -516,6 +545,8 @@ module Parse
             rows.select! { |doc| native_row_visible?(doc, perms_set) }
             Parse::ACLScope.redact_results!(rows, resolution)
             Parse::CLPScope.redact_protected_fields!(rows, protected_fields) if protected_fields.any?
+            # Defense in depth: the pointerFields `$match` already ran
+            # before `$limit`, so this should drop nothing.
             if pointer_fields
               rows = Parse::CLPScope.filter_by_pointer_fields(rows, pointer_fields, resolution.user_id)
             end
@@ -535,7 +566,13 @@ module Parse
           rows
         rescue Parse::CLPScope::Denied
           raise
-        rescue StandardError
+        rescue StandardError => e
+          # A refused owner prefilter means Atlas serves an index version
+          # without that filter path; stop pushing it down so the client
+          # fallback below (and later searches) run without it.
+          if owner_filter && Parse::VectorSearch.owner_prefilter_rejected?(e, owner_filter)
+            Parse::VectorSearch.owner_prefilter_unavailable!(collection_name, vector_index_name(vec))
+          end
           # Native execution failed (e.g. a cluster that probed as
           # supported but rejects this exact shape, or a transient error).
           # Fall back to the client-side path rather than failing the
@@ -543,7 +580,23 @@ module Parse
           nil
         end
 
-        def vector_search_stage(vec, oversample)
+        # The owner prefilter for the native vector input, or nil when it
+        # cannot be pushed down (master, no pointerFields, or the owner
+        # path not filter-indexed in the index Atlas is serving).
+        def owner_vector_filter(collection_name, vec, pointer_fields, resolution)
+          return nil if resolution.nil? || resolution.master? || pointer_fields.nil?
+          Parse::VectorSearch.send(:owner_vector_prefilter, collection_name, vector_index_name(vec),
+                                   pointer_fields, resolution)
+        end
+
+        # The vector index the native input searches: the branch's
+        # `index:` or {Parse::VectorSearch.default_index}, the same
+        # fallback {Parse::VectorSearch.search} uses on the client path.
+        def vector_index_name(vec)
+          vec[:index] || Parse::VectorSearch.default_index
+        end
+
+        def vector_search_stage(vec, oversample, owner_filter: nil)
           # Parity with Parse::VectorSearch: Atlas requires
           # `numCandidates >= limit` and caps it at 10_000. The default
           # (`oversample * MULTIPLIER`) can blow past 10_000 for a large
@@ -554,19 +607,23 @@ module Parse
           num_candidates = (vec[:num_candidates] || oversample * Parse::VectorSearch::DEFAULT_NUM_CANDIDATES_MULTIPLIER).to_i
           num_candidates = [[num_candidates, oversample].max, 10_000].min
           stage = {
-            "index" => vec[:index].to_s,
+            "index" => vector_index_name(vec).to_s,
             "path" => vec[:field].to_s,
             "queryVector" => vec[:query_vector],
             "numCandidates" => num_candidates,
             "limit" => oversample,
           }
-          stage["filter"] = vec[:vector_filter] if vec[:vector_filter] && !vec[:vector_filter].empty?
+          caller_filter = vec[:vector_filter] if vec[:vector_filter] && !vec[:vector_filter].empty?
+          prefilter = [caller_filter, owner_filter].compact
+          unless prefilter.empty?
+            stage["filter"] = prefilter.size == 1 ? prefilter.first : { "$and" => prefilter }
+          end
           inner = [{ "$vectorSearch" => stage }]
           inner << { "$match" => vec[:filter] } if vec[:filter]
           inner
         end
 
-        def lexical_search_stage(lex, oversample)
+        def lexical_search_stage(lex, oversample, owner_match: nil)
           require_relative "../atlas_search" if defined?(Parse::AtlasSearch::SearchBuilder).nil?
           builder = Parse::AtlasSearch::SearchBuilder.new(index_name: lex[:index])
           fields = lex[:fields]
@@ -575,7 +632,9 @@ module Parse
           else
             Array(fields).each { |f| builder.text(query: lex[:query], path: f.to_s, fuzzy: lex[:fuzzy]) }
           end
-          inner = [builder.build, { "$limit" => oversample }]
+          inner = [builder.build]
+          inner << { "$match" => owner_match } if owner_match
+          inner << { "$limit" => oversample }
           inner << { "$match" => lex[:filter] } if lex[:filter]
           inner
         end

data/lib/parse/vector_search.rb

@@ -47,8 +47,10 @@ module Parse
   #
   # * CLP `find` boundary check — refuses calls the equivalent REST
   #   find would refuse.
-  # * Optional `pointerFields` post-filter — drops rows that don't
-  #   name the current user_id in the configured pointer fields.
+  # * `pointerFields` / `readUserFields` ownership `$match` after
+  #   `$vectorSearch`, pushed into the `$vectorSearch.filter` prefilter
+  #   when every owner pointer (`_p_<field>`) is declared as a
+  #   `type: "filter"` field of the index.
   # * Post-`$vectorSearch` ACL `$match` injection (Parse Server's
   #   `_rperm` predicate).
   # * Post-fetch `protectedFields` redaction.
@@ -124,9 +126,10 @@ module Parse
     #
     # * `candidate_limit` / `num_candidates` — the requested window.
     # * `post_filter_count` — rows returned by the pipeline, i.e. after
-    #   the server-side ACL `$match` and any caller `filter`.
+    #   the server-side ACL `$match`, the pointerFields `$match`, and any
+    #   caller `filter`.
     # * `post_pointer_count` — rows left after client-side redaction and
-    #   pointer-field filtering.
+    #   the defense-in-depth pointer-field re-check.
     # * `returned_count` — rows handed back, after trimming to `k`.
     # * `underfilled` — the caller received fewer than `k`.
     #
@@ -137,6 +140,10 @@ module Parse
     # Accepted {.index_drift_policy} values.
     INDEX_DRIFT_POLICIES = %i[warn raise ignore].freeze
 
+    # Guards the lazy creation of the owner-prefilter negative cache mutex.
+    PREFILTER_MUTEX_INIT = Mutex.new
+    private_constant :PREFILTER_MUTEX_INIT
+
     class << self
       # Policy applied when first-query index verification (see
       # {Parse::Core::VectorSearchable}) finds the deployed Atlas
@@ -319,7 +326,14 @@ module Parse
           # result set is trimmed to `k` after enforcement runs.
           "limit" => candidate_limit,
         }
-        vs_stage["filter"] = vector_filter if vector_filter && !vector_filter.empty?
+        caller_prefilter = vector_filter if vector_filter && !vector_filter.empty?
+        owner_prefilter = unless resolution.master?
+            owner_vector_prefilter(collection_name, index_name, pointer_fields, resolution)
+          end
+        prefilter = [caller_prefilter, owner_prefilter].compact
+        unless prefilter.empty?
+          vs_stage["filter"] = prefilter.size == 1 ? prefilter.first : { "$and" => prefilter }
+        end
         pipeline = [{ "$vectorSearch" => vs_stage }]
 
         pipeline << {
@@ -337,12 +351,39 @@ module Parse
         unless resolution.master?
           acl_match = Parse::ACLScope.match_stage_for(resolution)
           pipeline << acl_match if acl_match
+          # pointerFields / readUserFields ownership, server-side so it
+          # runs on the whole candidate window before the trim to `k`.
+          # When every owner pointer is filter-indexed it also ran as the
+          # `$vectorSearch.filter` prefilter above; this stage then drops
+          # nothing but still covers the array-of-pointers storage form.
+          if pointer_fields
+            pipeline << {
+              "$match" => Parse::CLPScope.pointer_fields_predicate(pointer_fields, resolution.user_id),
+            }
+          end
         end
 
         pipeline << { "$match" => filter } if filter
 
-        raw_results = run_pipeline!(collection_name, pipeline, max_time_ms: max_time_ms,
-                                                               authorizing_client: Parse::ACLScope.client_of(resolution))
+        authorizing_client = Parse::ACLScope.client_of(resolution)
+        raw_results = begin
+            run_pipeline!(collection_name, pipeline, max_time_ms: max_time_ms,
+                                                     authorizing_client: authorizing_client)
+          rescue StandardError => e
+            raise unless owner_prefilter && owner_prefilter_rejected?(e, owner_prefilter)
+            # Atlas is serving an index version without the owner filter
+            # path (a rebuild in progress, or a stale cached definition).
+            # Stop pushing it down and rerun once without it; the
+            # ownership `$match` after `$vectorSearch` still enforces it.
+            owner_prefilter_unavailable!(collection_name, index_name)
+            if caller_prefilter
+              vs_stage["filter"] = caller_prefilter
+            else
+              vs_stage.delete("filter")
+            end
+            run_pipeline!(collection_name, pipeline, max_time_ms: max_time_ms,
+                                                     authorizing_client: authorizing_client)
+          end
         # Already past the server-side ACL `$match` and any caller
         # `filter` — NOT the number $vectorSearch emitted.
         post_filter_count = raw_results.length
@@ -353,6 +394,8 @@ module Parse
         unless resolution.master?
           Parse::ACLScope.redact_results!(raw_results, resolution)
           Parse::CLPScope.redact_protected_fields!(raw_results, protected_fields) if protected_fields.any?
+          # Defense in depth: the pointerFields `$match` already ran in
+          # the pipeline, so this should drop nothing.
           if pointer_fields
             raw_results = Parse::CLPScope.filter_by_pointer_fields(
               raw_results, pointer_fields, resolution.user_id,
@@ -442,6 +485,52 @@ module Parse
       #   @return [String, nil]
       attr_accessor :default_index
 
+      # @!visibility private
+      # Whether an error is Atlas refusing one of the owner prefilter's
+      # paths because the served index does not declare it as
+      # `type: "filter"`. Atlas words the refusal the same way for any
+      # path, so the message must name an owner path: a caller
+      # `vector_filter` on an unindexed field raises as it always did and
+      # does not switch the owner prefilter off for other callers.
+      # @param error [Exception]
+      # @param owner_prefilter [Hash] the owner clause that was pushed down.
+      # @return [Boolean]
+      def owner_prefilter_rejected?(error, owner_prefilter)
+        message = error.message.to_s
+        return false unless message.match?(PREFILTER_REJECTED_PATTERN)
+        owner_prefilter_paths(owner_prefilter).any? { |path| message.include?(path) }
+      end
+
+      # @!visibility private
+      # The `_p_<field>` paths an owner prefilter clause names.
+      # @param owner_prefilter [Hash]
+      # @return [Array<String>]
+      def owner_prefilter_paths(owner_prefilter)
+        return [] unless owner_prefilter.is_a?(Hash)
+        clauses = owner_prefilter.key?("$or") ? Array(owner_prefilter["$or"]) : [owner_prefilter]
+        clauses.flat_map { |c| c.is_a?(Hash) ? c.keys.map(&:to_s) : [] }.select { |k| k.start_with?("_p_") }
+      end
+
+      # @!visibility private
+      # Stop pushing the owner prefilter down for this index until the
+      # index cache TTL passes, and drop the cached index definition so
+      # the next lookup reads what Atlas now reports.
+      # @param collection_name [String]
+      # @param index_name [String, Symbol]
+      def owner_prefilter_unavailable!(collection_name, index_name)
+        require_relative "atlas_search"
+        Parse::AtlasSearch::IndexManager.clear_cache(collection_name)
+        mark_prefilter_unavailable(prefilter_cache_key(collection_name, index_name))
+      end
+
+      # @!visibility private
+      # Forget every negative prefilter lookup (tests, or after an
+      # operator fixes the index and does not want to wait out the TTL).
+      def clear_prefilter_cache!
+        prefilter_mutex.synchronize { @prefilter_unavailable = {} }
+        nil
+      end
+
       private
 
       def require_available!
@@ -507,6 +596,124 @@ module Parse
                                             label: "VectorSearch")
       end
 
+      # The pointerFields ownership constraint as a `$vectorSearch.filter`
+      # clause, or nil when it cannot be pushed down. Atlas only accepts a
+      # prefilter on paths declared `type: "filter"` in the index, so this
+      # applies only when every owner pointer's storage path
+      # (`_p_<field>`) is filter-indexed. A prefilter keeps other users'
+      # rows out of the candidate window entirely, so an owner-scoped
+      # caller is not underfilled by higher-ranked rows they cannot read.
+      # Any lookup failure returns nil: the post-`$vectorSearch` `$match`
+      # still enforces ownership, only the fill is weaker.
+      #
+      # The prefilter matches only the scalar `_p_<field>` storage form.
+      # CLP ownership also accepts an array of pointers stored under the
+      # bare field name, so pushing down on such a field would drop rows
+      # the caller owns. It is therefore used only when every owner field
+      # is declared as a scalar pointer on the local model.
+      def owner_vector_prefilter(collection_name, index_name, pointer_fields, resolution)
+        return nil if pointer_fields.nil? || pointer_fields.empty?
+        uid = resolution.user_id.to_s
+        return nil if uid.empty?
+        return nil unless scalar_pointer_fields?(collection_name, pointer_fields)
+        paths = pointer_fields.map { |f| "_p_#{f}" }
+        indexed = vector_filter_paths(collection_name, index_name)
+        return nil unless paths.all? { |path| indexed.include?(path) }
+        storage = "#{Parse::Model::CLASS_USER}$#{uid}"
+        clauses = paths.map { |path| { path => { "$eq" => storage } } }
+        clauses.size == 1 ? clauses.first : { "$or" => clauses }
+      end
+
+      # Whether every owner field is declared as a scalar pointer
+      # (`belongs_to`) on the local model for the collection. Read from the
+      # model's declared fields, so no schema request is made. An unknown
+      # class, an undeclared field, or an array field all answer false.
+      def scalar_pointer_fields?(collection_name, pointer_fields)
+        klass = Parse::Model.find_class(collection_name.to_s)
+        return false unless klass.respond_to?(:fields)
+        fields = klass.fields
+        pointer_fields.all? { |f| fields[f.to_s.to_sym] == :pointer }
+      rescue StandardError
+        false
+      end
+
+      # Paths the named vectorSearch index declares as `type: "filter"`.
+      # Read through {Parse::AtlasSearch::IndexManager}, which caches the
+      # `$listSearchIndexes` result. Empty unless the index is READY and
+      # serving its latest definition: during a rebuild
+      # `latestDefinition` already lists the new filter path while Atlas
+      # still serves the old version, and a prefilter on that path is
+      # refused. A lookup error is remembered for the index cache TTL so a
+      # deployment without the `listSearchIndexes` privilege does not pay
+      # a failing round trip on every search.
+      def vector_filter_paths(collection_name, index_name)
+        key = prefilter_cache_key(collection_name, index_name)
+        return Set.new if prefilter_unavailable?(key)
+        require_relative "atlas_search"
+        idx = begin
+            Parse::AtlasSearch::IndexManager.get_index(collection_name, index_name.to_s)
+          rescue StandardError
+            mark_prefilter_unavailable(key)
+            return Set.new
+          end
+        return Set.new unless idx && index_serving_latest?(idx)
+        defn = idx["latestDefinition"] || idx[:latestDefinition] || {}
+        Array(defn["fields"] || defn[:fields]).each_with_object(Set.new) do |f, set|
+          next unless (f["type"] || f[:type]).to_s == "filter"
+          set << (f["path"] || f[:path]).to_s
+        end
+      end
+
+      # Whether Atlas is serving the index's latest definition: status
+      # READY and, when per-host `statusDetail` is reported, every host's
+      # main index at `latestDefinitionVersion`. Missing status fails
+      # toward "not serving" so the prefilter is simply skipped.
+      def index_serving_latest?(idx)
+        return false unless (idx["status"] || idx[:status]).to_s.upcase == "READY"
+        latest = definition_version(idx["latestDefinitionVersion"] || idx[:latestDefinitionVersion])
+        details = Array(idx["statusDetail"] || idx[:statusDetail])
+        return true if latest.nil? || details.empty?
+        details.all? do |detail|
+          main = detail["mainIndex"] || detail[:mainIndex]
+          main && definition_version(main["definitionVersion"] || main[:definitionVersion]) == latest
+        end
+      end
+
+      def definition_version(value)
+        return nil unless value.is_a?(Hash)
+        value["version"] || value[:version]
+      end
+
+      PREFILTER_REJECTED_PATTERN = /indexed as (?:a )?filter/i
+      private_constant :PREFILTER_REJECTED_PATTERN
+
+      def prefilter_cache_key(collection_name, index_name)
+        "#{collection_name}\x1f#{index_name}"
+      end
+
+      def prefilter_mutex
+        @prefilter_mutex ||= PREFILTER_MUTEX_INIT.synchronize { @prefilter_mutex ||= Mutex.new }
+      end
+
+      def prefilter_unavailable?(key)
+        prefilter_mutex.synchronize do
+          expires = (@prefilter_unavailable ||= {})[key]
+          next false unless expires
+          next true if Process.clock_gettime(Process::CLOCK_MONOTONIC) < expires
+          @prefilter_unavailable.delete(key)
+          false
+        end
+      end
+
+      def mark_prefilter_unavailable(key)
+        require_relative "atlas_search"
+        ttl = Parse::AtlasSearch::IndexManager.cache_ttl.to_f
+        return if ttl <= 0
+        prefilter_mutex.synchronize do
+          (@prefilter_unavailable ||= {})[key] = Process.clock_gettime(Process::CLOCK_MONOTONIC) + ttl
+        end
+      end
+
       # Execute the pipeline directly against the MongoDB collection.
       # Mirrors `Parse::AtlasSearch#run_atlas_pipeline!` — bypasses
       # `Parse::MongoDB.aggregate` because that helper prepends an

data/lib/parse/webhooks/payload.rb

@@ -557,6 +557,49 @@ module Parse
         # object from @object/@original).
         return @parse_object if defined?(@parse_object) && !@parse_object.nil?
         @parse_object = build_parse_object
+        # On a beforeSave create, note when the handler assigns an ACL. The
+        # model's dirty tracking ignores an assignment equal to the default
+        # stamp (`obj.acl = Parse::ACL.new` under a `{}` default), and the
+        # reply must still treat it as the handler's explicit choice.
+        if before_save? && @original.blank? && @parse_object.is_a?(Parse::Object)
+          @parse_object.extend(HandlerAclAssignment)
+        end
+        @parse_object
+      end
+
+      # Marks an object whose handler assigned its ACL. Used only on the
+      # object a beforeSave create handler receives.
+      # @!visibility private
+      module HandlerAclAssignment
+        def acl=(value)
+          @_webhook_handler_acl_assigned = true
+          super
+        end
+
+        # Mass assignment (`attributes=`, `apply_attributes!`) sets the ACL
+        # through these setters rather than `acl=`: `acl` by its Ruby name,
+        # `ACL` (an alias bound at class definition) by its remote name.
+        def acl_set_attribute!(*args, **kwargs, &block)
+          @_webhook_handler_acl_assigned = true
+          super
+        end
+
+        def ACL_set_attribute!(*args, **kwargs, &block)
+          @_webhook_handler_acl_assigned = true
+          super
+        end
+
+        # Forget assignments made before the handler ran (the field-guard
+        # pre-step reverts a client ACL through `acl=`).
+        # @!visibility private
+        def reset_webhook_handler_acl_assigned!
+          @_webhook_handler_acl_assigned = false
+        end
+
+        # @return [Boolean] whether the handler assigned the ACL.
+        def webhook_handler_acl_assigned?
+          @_webhook_handler_acl_assigned == true
+        end
       end
 
       # @!visibility private