parse-stack-next 5.2.1 → 5.4.0

data/lib/parse/webhooks/payload.rb

@@ -25,7 +25,9 @@ module Parse
                      original: nil, update: nil,
                      query: nil, log: nil,
                      objects: nil,
-                     triggerName: nil }.freeze
+                     triggerName: nil,
+                     event: nil, clients: nil, subscriptions: nil,
+                     context: nil }.freeze
       include ::ActiveModel::Serializers::JSON
       # @!attribute [rw] master
       #   @return [Boolean] whether the master key was used for this request.
@@ -64,6 +66,43 @@ module Parse
       attr_accessor :master, :user, :installation_id, :params, :function_name, :object, :trigger_name
       attr_accessor :query, :log, :objects
       attr_accessor :original, :update, :raw
+      # @!attribute [rw] event
+      #   The LiveQuery event type for an +afterEvent+ trigger -- one of
+      #   +"create"+, +"enter"+, +"update"+, +"leave"+, or +"delete"+ -- or
+      #   +"connect"+ for a +beforeConnect+ trigger. +nil+ for every non-
+      #   LiveQuery trigger. See {#after_event?} / {#before_connect?}.
+      #   @return [String, nil]
+      # @!attribute [rw] clients
+      #   Connection-global metadata sent on the LiveQuery +beforeConnect+ /
+      #   +afterEvent+ triggers: the number of currently-connected LiveQuery
+      #   clients. +nil+ for non-LiveQuery triggers.
+      #   @return [Integer, nil]
+      # @!attribute [rw] subscriptions
+      #   Connection-global metadata sent on the LiveQuery +beforeConnect+ /
+      #   +afterEvent+ triggers: the number of active subscriptions. +nil+ for
+      #   non-LiveQuery triggers.
+      #   @return [Integer, nil]
+      attr_accessor :event, :clients, :subscriptions
+      # @!attribute [rw] context
+      #   The caller-supplied context object threaded from the originating REST
+      #   write or cloud-function call via the +X-Parse-Cloud-Context+ header.
+      #   Parse Server includes this as a top-level +context+ key in trigger
+      #   payloads (beforeSave/afterSave/etc.). Returns a Hash when present, or
+      #   +nil+ when the originating request carried no context.
+      #   @return [Hash, nil]
+      attr_accessor :context
+      # @!attribute [r] session_token
+      #   The caller's live Parse session token, captured from the incoming
+      #   webhook payload (`user.sessionToken`) before credentials are scrubbed
+      #   from {#user} / {#object} / {#original} / {#update}. Present only when
+      #   the originating request was made by a logged-in user -- a master-key
+      #   request carries no user and no token, so this is +nil+. It is
+      #   intentionally NOT one of {ATTRIBUTES}, so it never appears in
+      #   {#as_json} or in the redacted request log. Reach for it (or the
+      #   higher-level {#user_client} / {#user_agent}) only when a handler
+      #   deliberately wants to act on the server as the calling user.
+      #   @return [String, nil]
+      attr_reader :session_token
       # @!visibility private
       attr_accessor :webhook_class
       alias_method :installationId, :installation_id
@@ -73,11 +112,44 @@ module Parse
       # You would normally never create a {Parse::Webhooks::Payload} object since it is automatically
       # provided to you when using Parse::Webhooks.
       # @see Parse::Webhooks
-      def initialize(hash = {})
+      # @param hash [String, Hash] the raw webhook body (JSON string or Hash).
+      # @param webhook_class [String, nil] the Parse class name derived from the
+      #   webhook URL path (`<endpoint>/<triggerName>/<className>`). This is the
+      #   ONLY authoritative source of the class for beforeFind/afterFind
+      #   triggers — Parse Server omits `className` from the find payload body
+      #   entirely (the matched `objects` carry no `className` and there is no
+      #   top-level one). Threading it here lets `parse_class` resolve (so find
+      #   triggers route) and lets `:vector` columns be stripped from afterFind
+      #   `objects`. For save/delete triggers the path className equals the
+      #   body's, so it is consistent; for functions it is nil.
+      def initialize(hash = {}, webhook_class = nil)
         hash = JSON.parse(hash, max_nesting: 20) if hash.is_a?(String)
         hash = Hash[hash.map { |k, v| [k.to_s.underscore.to_sym, v] }]
         @raw = hash
+        # Set BEFORE the vector scrub below so the route-derived class is
+        # available to strip :vector columns from afterFind objects (whose
+        # body carries no className of its own).
+        @webhook_class = webhook_class.to_s if webhook_class && !webhook_class.to_s.empty?
         @master = hash[:master]
+        # Capture the caller's session token from the *unscrubbed* user hash
+        # before scrub_credentials strips it below. Parse Server includes
+        # `user.sessionToken` on every trigger fired by a logged-in caller
+        # (it is absent for master-key-originated requests). Pulling it aside
+        # here -- rather than leaving it in @user -- keeps it out of any object
+        # a handler might persist and out of #as_json / the request log, while
+        # still letting a handler opt in to acting as the calling user via
+        # #session_token / #user_client / #user_agent.
+        @session_token = self.class.extract_session_token(hash[:user])
+        # LiveQuery beforeConnect/beforeSubscribe carry the caller's session
+        # token at the TOP LEVEL (not nested under `user`), because no user is
+        # resolved yet when the trigger fires. Capture it here -- with the same
+        # "set it aside, keep it out of as_json / the log" treatment as the
+        # nested form -- so #user_client / #user_agent can act as the caller.
+        # It is intentionally NOT one of ATTRIBUTES.
+        if @session_token.nil?
+          top_token = hash[:session_token].to_s.strip
+          @session_token = top_token unless top_token.empty?
+        end
         # Webhook trigger payloads (beforeSave/afterSave/etc.) are delivered by
         # Parse Server and, when a webhook key is configured (the default; see
         # Parse::Webhooks.allow_unauthenticated for the opt-out used in tests /
@@ -85,7 +157,8 @@ module Parse
         # server-authoritative state. A handler is meant to receive the full
         # object -- createdAt/updatedAt, ACL, internal fields and all. The only
         # thing stripped here is genuine credential material a handler never
-        # legitimately needs to read (live session tokens, offline-crackable
+        # legitimately needs to read inline (live session tokens -- captured
+        # above for opt-in user-scoped clients first -- and offline-crackable
         # password hashes); see WEBHOOK_TRIGGER_CREDENTIAL_KEYS. Protection
         # against *persisting* forged privileged fields lives on the write path
         # (changes_payload emits only declared, dirty-tracked properties), not on
@@ -103,14 +176,42 @@ module Parse
         @params = hash[:params]
         @params = @params.with_indifferent_access if @params.is_a?(Hash)
         @function_name = hash[:function_name]
-        @object = self.class.scrub_credentials(hash[:object])
         @trigger_name = hash[:trigger_name]
-        @original = self.class.scrub_credentials(hash[:original])
-        @update = self.class.scrub_credentials(hash[:update]) || {}
-        # Added for beforeFind and afterFind triggers
+        # Resolve the model class once so :vector columns can be stripped from
+        # every object-shaped payload (see scrub_vector_columns). Credentials
+        # are scrubbed first, then vectors. The route-derived @webhook_class is
+        # authoritative and preferred — it is the only class source for
+        # afterFind (whose body carries no className anywhere); for save/delete
+        # it equals the body's className. Falls back to the object/original
+        # className for older callers that don't supply a route class.
+        vec_klass = self.class.resolve_klass_by_name(@webhook_class) ||
+                    self.class.resolve_vector_klass(hash[:object], hash[:original])
+        @object = self.class.scrub_vector_columns(self.class.scrub_credentials(hash[:object]), vec_klass)
+        @original = self.class.scrub_vector_columns(self.class.scrub_credentials(hash[:original]), vec_klass)
+        @update = self.class.scrub_vector_columns(self.class.scrub_credentials(hash[:update]), vec_klass) || {}
+        # Added for beforeFind and afterFind triggers. afterFind objects are all
+        # of one class but carry no className of their own, so the route-derived
+        # vec_klass is the only way to strip their :vector columns.
         @query = hash[:query]
-        @objects = hash[:objects] || []
+        # LiveQuery connection metadata. `event` is the afterEvent event type
+        # (create/enter/update/leave/delete) or "connect" for beforeConnect;
+        # `clients`/`subscriptions` are connection-global counts. All nil for
+        # the object / auth triggers. These are plain scalars (no credential
+        # material), so they pass through unscrubbed.
+        @event = hash[:event]
+        @clients = hash[:clients]
+        @subscriptions = hash[:subscriptions]
+        @objects = Array(hash[:objects]).map do |o|
+          self.class.scrub_vector_columns(self.class.scrub_credentials(o), vec_klass)
+        end
         @log = hash[:log]
+        # Caller-supplied context object threaded via X-Parse-Cloud-Context.
+        # This is caller metadata (not a credential), so it passes through
+        # without scrubbing — mirroring the treatment of @query and @log.
+        @context = hash[:context]
+        # Blocks registered by a handler via #after_response / #defer, to run
+        # after the webhook response has been sent (drained by the Rack app).
+        @deferred_callbacks = []
       end
 
       # @!visibility private
@@ -144,11 +245,95 @@ module Parse
         end
       end
 
+      # @!visibility private
+      # Resolve the Parse::Object subclass for a webhook payload from the
+      # `className` of the first object-shaped hash given. Returns nil when
+      # no class name is present or no matching model is registered (the
+      # caller then skips vector stripping — fail-open is acceptable here:
+      # an unregistered class has no declared `:vector` columns to strip).
+      def self.resolve_vector_klass(*candidates)
+        candidates.each do |obj|
+          next unless obj.is_a?(Hash)
+          name = obj["className"] || obj[:className]
+          next if name.nil? || name.to_s.empty?
+          klass = resolve_klass_by_name(name)
+          return klass if klass
+        end
+        nil
+      end
+
+      # @!visibility private
+      # Resolve a registered Parse::Object subclass from a bare class-name
+      # string (e.g. the route-derived @webhook_class). Returns nil for a blank
+      # name or an unregistered class (the caller then skips vector stripping —
+      # fail-open, as an unregistered class has no declared :vector columns).
+      def self.resolve_klass_by_name(name)
+        return nil if name.nil? || name.to_s.empty?
+        klass = (Parse::Object.find_class(name.to_s) rescue nil)
+        klass.respond_to?(:fields) ? klass : nil
+      end
+
+      # @!visibility private
+      # Returns a copy of +obj+ with the model's declared `:vector`
+      # columns removed. Embeddings are large dense float arrays that leak
+      # ML signal; a webhook handler has no reason to receive them, and
+      # leaving them in bloats logs and any object a handler re-persists.
+      # Mirrors the `as_json` default (vectors omitted) — a class that opts
+      # into `vector_visibility :public` keeps its vectors here too.
+      #
+      # `klass` may be passed explicitly (so changed-only payloads like
+      # `update`, which carry no `className`, are still scrubbed using the
+      # class resolved from the sibling `object`/`original` hash); when nil
+      # it is resolved from the hash's own `className`.
+      # Pass-through for non-Hash input (and nil).
+      def self.scrub_vector_columns(obj, klass = nil)
+        return obj unless obj.is_a?(Hash)
+        klass ||= resolve_vector_klass(obj)
+        return obj if klass.nil?
+        if klass.respond_to?(:vectors_public_by_default?) && klass.vectors_public_by_default?
+          return obj
+        end
+        vector_fields = klass.fields(:vector).keys.map(&:to_s)
+        return obj if vector_fields.empty?
+        field_map = klass.respond_to?(:field_map) ? klass.field_map : {}
+        wire = vector_fields.map { |f| (field_map[f.to_sym] || f).to_s }
+        denied = (vector_fields + wire)
+        obj.reject { |k, _| denied.include?(k.to_s) }
+      end
+
+      # @!visibility private
+      # Pulls the caller's session token out of the (unscrubbed) +user+ hash.
+      # Parse Server sends it as the camelCase string key +sessionToken+; this
+      # tolerates a symbol key and the snake_case form too, mirroring the
+      # leniency in +scrub_credentials+. Returns +nil+ for a blank token or a
+      # non-Hash / absent user (a master-key request has no user).
+      def self.extract_session_token(user_hash)
+        return nil unless user_hash.is_a?(Hash)
+        token = user_hash["sessionToken"] || user_hash[:sessionToken] ||
+                user_hash["session_token"] || user_hash[:session_token]
+        token = token.to_s.strip
+        token.empty? ? nil : token
+      end
+
       # @return [ATTRIBUTES]
       def attributes
         ATTRIBUTES
       end
 
+      # Redacted inspection. The default Ruby `#inspect` would dump every ivar,
+      # including the captured `@session_token` and the *pre-scrub* `@raw` hash
+      # (which still holds the caller's sessionToken and any password hashes).
+      # That is exactly the surface an error reporter or a stray `p payload`
+      # hits, so show only non-sensitive routing fields and a boolean for the
+      # token's presence. Use #as_json / the individual accessors for the
+      # (already credential-scrubbed) object data.
+      def inspect
+        "#<#{self.class.name} trigger=#{@trigger_name.inspect} " \
+        "function=#{@function_name.inspect} class=#{parse_class.inspect} " \
+        "id=#{parse_id.inspect} master=#{@master ? true : false} " \
+        "session_token=#{@session_token ? "[FILTERED]" : "nil"}>"
+      end
+
       # Method to print to standard that utilizes the an internal id to make it easier
       # to trace incoming requests.
       def wlog(s)
@@ -170,6 +355,51 @@ module Parse
         @master.present?
       end
 
+      # true if this payload carried a caller session token -- i.e. the
+      # originating request was made by a logged-in user rather than the
+      # master key, so {#user_client} / {#user_agent} can act as that user.
+      # @return [Boolean]
+      def session_token?
+        !@session_token.nil?
+      end
+
+      # An opt-in, user-scoped {Parse::Client} for acting on the server as the
+      # webhook's calling user. It mirrors the default client's connection
+      # settings (+server_url+, +application_id+, +api_key+) but carries NO
+      # master key and BINDS the caller's {#session_token}, so every request it
+      # makes -- with no further ceremony -- is authorized by Parse Server as
+      # that user: ACL, CLP and +protectedFields+ are all enforced. (A
+      # `Parse.with_session` block still overrides the bound token if you need
+      # to act as someone else within a call.) Memoized per payload, since each
+      # webhook delivery carries a distinct token.
+      # @return [Parse::Client, nil] +nil+ when the payload carried no token.
+      def user_client
+        return nil if @session_token.nil?
+        @user_client ||= Parse::Client.client.become(@session_token)
+      end
+
+      # An opt-in, non-master {Parse::Agent} scoped to the webhook caller's
+      # session token. Because its client has no master key and it is built
+      # with a non-empty +session_token:+, the agent runs in CLIENT MODE:
+      # every tool/query routes through a path Parse Server (or the SDK's own
+      # ACL/CLP enforcement layer) authorizes as the calling user, with no
+      # master-key fallback to silently bypass row-level security. This is the
+      # handle to use when a handler should read or act strictly within the
+      # caller's permissions. Additional agent options (e.g.
+      # +permissions: :readwrite+) may be passed through.
+      # @param opts [Hash] extra keyword args forwarded to {Parse::Agent#initialize}.
+      # @return [Parse::Agent, nil] +nil+ when the payload carried no token.
+      def user_agent(**opts)
+        return nil if @session_token.nil?
+        require_relative "../agent" unless defined?(Parse::Agent)
+        # Strip the two identity kwargs from the passthrough: a Ruby double-splat
+        # that repeats an explicit keyword WINS, so user_agent(client: master)
+        # or user_agent(session_token: other) would otherwise silently defeat the
+        # whole point (scoping to the caller). The scoping is non-negotiable here.
+        opts = opts.except(:session_token, :client)
+        Parse::Agent.new(session_token: @session_token, client: user_client, **opts)
+      end
+
       # @return [String] the name of the Parse class for this request.
       def parse_class
         return @webhook_class if @webhook_class.present?
@@ -230,6 +460,73 @@ module Parse
         trigger? && @trigger_name.to_sym == :afterFind
       end
 
+      # true if this is a beforeLogin webhook trigger request.
+      #
+      # NOTE: a +beforeLogin+ payload carries the user being authenticated as
+      # {#object} / {#parse_object} (a +_User+), NOT as {#user} -- the caller is
+      # not yet authenticated when the trigger fires, so {#user} is +nil+. (By
+      # +afterLogin+ both are populated and equal.) Reach for {#parse_object} to
+      # inspect the logging-in user during +beforeLogin+.
+      def before_login?
+        trigger? && @trigger_name.to_sym == :beforeLogin
+      end
+
+      # true if this is a afterLogin webhook trigger request.
+      def after_login?
+        trigger? && @trigger_name.to_sym == :afterLogin
+      end
+
+      # true if this is a afterLogout webhook trigger request. The logged-out
+      # session is carried as {#object} / {#parse_object} (a +_Session+).
+      def after_logout?
+        trigger? && @trigger_name.to_sym == :afterLogout
+      end
+
+      # true if this is a beforePasswordResetRequest webhook trigger request.
+      # The target user is carried as {#object} / {#parse_object} (a +_User+).
+      def before_password_reset_request?
+        trigger? && @trigger_name.to_sym == :beforePasswordResetRequest
+      end
+
+      # true if this is a LiveQuery beforeConnect webhook trigger request.
+      # Connection-global: carries no {#object}; the className is the +@Connect+
+      # sentinel and the caller's token (if any) is in {#session_token}.
+      def before_connect?
+        trigger? && @trigger_name.to_sym == :beforeConnect
+      end
+
+      # true if this is a LiveQuery beforeSubscribe webhook trigger request.
+      # Shaped like beforeFind: carries a {#query} (see {#parse_query}) and the
+      # className comes from the request path, not the body.
+      def before_subscribe?
+        trigger? && @trigger_name.to_sym == :beforeSubscribe
+      end
+
+      # true if this is a LiveQuery afterEvent webhook trigger request. The
+      # event type (create/enter/update/leave/delete) is in {#event}.
+      def after_event?
+        trigger? && @trigger_name.to_sym == :afterEvent
+      end
+
+      # true if this is one of the authentication-side triggers
+      # (beforeLogin / afterLogin / afterLogout / beforePasswordResetRequest).
+      # These carry a +_User+ / +_Session+ as {#object} but are NOT object
+      # save/delete triggers: no ActiveModel save/create/destroy callbacks run
+      # for them, and Parse Server ignores the response body (the only way to
+      # affect a +before*+ one is to deny it -- see the webhook router).
+      def auth_trigger?
+        before_login? || after_login? || after_logout? || before_password_reset_request?
+      end
+
+      # true if this is one of the LiveQuery triggers (beforeConnect /
+      # beforeSubscribe / afterEvent). Parse Server delivers these over an HTTP
+      # webhook only in a co-located single-process LiveQuery setup;
+      # +beforeConnect+ in particular carries a live client and is effectively
+      # in-process-only. See the webhooks guide.
+      def live_query_trigger?
+        before_connect? || before_subscribe? || after_event?
+      end
+
       # true if this request is a trigger that contains an object.
       def object?
         trigger? && @object.present?
@@ -321,9 +618,57 @@ module Parse
           return o
         end
 
-        # afterSave on a CREATE (and every other trigger): the full object as the
-        # server sent it. createdAt/updatedAt survive (only credentials are
-        # scrubbed), so `new?` / `existed?` read correctly.
+        # afterSave on a CREATE: there is no prior persisted state, so every
+        # populated data field is new. Build symmetry with the UPDATE path above
+        # by seeding the identity / system fields (objectId, timestamps, ACL,
+        # className, plus the credential / permission keys) into a pristine
+        # object, then overlaying the full object with dirty tracking. Because
+        # the overlay's protected_set is exactly the seed key set, the system
+        # fields come ONLY from the clean seed and the overlay touches ONLY
+        # declared data properties (nil -> value -> changed) -- so `*_changed?`
+        # reports every field the create populated while createdAt / updatedAt /
+        # ACL stay clean. This lets handlers key off dirty tracking uniformly
+        # across create and update (e.g. building a sync payload from changed
+        # fields). Credentials / _rperm / _wperm / authData / roles are filtered
+        # from the overlay (seeded read-only, never marked changed), and an
+        # after-trigger response is only true/false, so nothing here can persist
+        # a forged field.
+        if after_save? && @object.is_a?(Hash)
+          seed_keys = Parse::Properties::PROTECTED_INITIALIZE_KEYS +
+                      %w[objectId createdAt updatedAt ACL className __type]
+          seed = @object.slice(*seed_keys)
+          o = Parse::Object.build seed, parse_class
+          # `build` applies declared `default:` values onto the seed and then
+          # clears changes, baking each default into the "pristine" baseline.
+          # Without correction, the overlay's dirty guard (`unless val ==
+          # current`) would SUPPRESS marking any create value equal to its
+          # default (e.g. status: "draft", count: 0, archived: false), silently
+          # defeating this branch's whole purpose. Reset the default-bearing
+          # ivars to nil for the fields the overlay is about to set, then
+          # re-clear, so the overlay's guard sees a differing current ivar and
+          # marks every populated data field changed. (`*_changed?` / `changes`
+          # / `changed` then report the field; for a defaulted field the
+          # reported prior value is the default rather than nil, since the
+          # getter re-derives the default — its prior *effective* value.)
+          # `defaults_list` never contains the seeded system fields
+          # (objectId/createdAt/updatedAt/ACL), so this cannot disturb them;
+          # defaults for fields ABSENT from the payload are left intact so their
+          # value still reads through.
+          fmap = o.class.respond_to?(:field_map) ? o.class.field_map : {}
+          o.class.defaults_list.each do |k|
+            wire = (fmap[k] || k).to_s
+            next unless @object.key?(wire) || @object.key?(k.to_s)
+            o.instance_variable_set(:"@#{k}", nil)
+          end
+          o.clear_changes!
+          o.apply_attributes! @object, dirty_track: true, protected_set: seed_keys
+          return o
+        end
+
+        # Every other trigger (afterDelete, afterFind, and any before* path that
+        # did not match above): the full object as the server sent it.
+        # createdAt/updatedAt survive (only credentials are scrubbed), so
+        # `new?` / `existed?` read correctly.
         Parse::Object.build(@object, parse_class)
       end
 
@@ -340,6 +685,49 @@ module Parse
         raise Parse::Webhooks::ResponseError, msg
       end
 
+      # Register a block to run **after** this webhook's response has been sent
+      # to Parse Server, off the client's critical path. Use it to do work that
+      # should not add latency to the save/function the client is waiting on —
+      # search indexing, cache warming, fan-out notifications.
+      #
+      # The handler still returns its value synchronously (the response Parse
+      # Server acts on); the deferred block runs afterward. When the SDK is
+      # mounted under a server that supports `rack.after_reply` (Puma, Unicorn)
+      # the block runs once the response is flushed to the socket, on the same
+      # worker thread; otherwise it runs in a detached thread. Each block is
+      # isolated, so one raising neither affects the response nor the others.
+      #
+      #   Parse::Webhooks.route :after_save, :Post do
+      #     post = parse_object
+      #     after_response { SearchIndex.reindex(post.id) }
+      #     post
+      #   end
+      #
+      # `self` inside the block is this payload (it closes over the handler's
+      # scope), so `parse_object`, `params`, etc. remain available. Note the
+      # block runs in-process and does not survive a worker restart — for work
+      # that *must* happen, hand it to a durable job queue instead. Deferred
+      # callbacks fire only when the payload is processed through the mounted
+      # `Parse::Webhooks` Rack app.
+      #
+      # @yield the work to run after the response is sent.
+      # @return [Boolean] true if a block was registered.
+      def after_response(&block)
+        return false unless block_given?
+        @deferred_callbacks ||= []
+        @deferred_callbacks << block
+        true
+      end
+      alias_method :defer, :after_response
+
+      # @!visibility private
+      # The blocks registered via {#after_response}; drained by the Rack app
+      # ({Parse::Webhooks.dispatch_deferred}) after the response is finished.
+      # @return [Array<Proc>]
+      def deferred_callbacks
+        @deferred_callbacks ||= []
+      end
+
       # @return [Parse::Query] the Parse query for a beforeFind trigger.
       def parse_query
         return nil unless parse_class.present? && @query.is_a?(Hash)