parse-stack-next 5.6.0 → 5.7.1

data/lib/parse/webhooks/trigger_audit.rb

@@ -51,12 +51,12 @@ module Parse
       # inside the save handler (Parse Server has no create trigger); the webhook
       # router runs the destroy chain inside the beforeDelete handler.
       CALLBACK_TRIGGER_MAP = {
-        [:save,    :before] => :before_save,
-        [:create,  :before] => :before_save,
-        [:save,    :after]  => :after_save,
-        [:create,  :after]  => :after_save,
+        [:save, :before] => :before_save,
+        [:create, :before] => :before_save,
+        [:save, :after] => :after_save,
+        [:create, :after] => :after_save,
         [:destroy, :before] => :before_delete,
-        [:destroy, :after]  => :after_delete,
+        [:destroy, :after] => :after_delete,
       }.freeze
 
       # ActiveModel callback chains + phases with NO server trigger that can run
@@ -67,10 +67,10 @@ module Parse
       # trigger registration changes that. Surfaced as an informational note, not
       # a fixable gap.
       LOCAL_ONLY_MAP = {
-        [:update,     :before] => :before_update,
-        [:update,     :after]  => :after_update,
+        [:update, :before] => :before_update,
+        [:update, :after] => :after_update,
         [:validation, :before] => :before_validation,
-        [:validation, :after]  => :after_validation,
+        [:validation, :after] => :after_validation,
       }.freeze
 
       # The ActiveModel callback chains we introspect.
@@ -104,12 +104,12 @@ module Parse
 
         def initialize(parse_class:, callbacks:, local_routes:, server_triggers:,
                        findings:, modeled:)
-          @parse_class     = parse_class
-          @callbacks       = callbacks
-          @local_routes    = local_routes
+          @parse_class = parse_class
+          @callbacks = callbacks
+          @local_routes = local_routes
           @server_triggers = server_triggers
-          @findings        = findings
-          @modeled         = modeled
+          @findings = findings
+          @modeled = modeled
         end
 
         # @return [Boolean] true when the class has at least one finding.
@@ -120,12 +120,12 @@ module Parse
         # @return [Hash] a JSON-safe representation of this row.
         def to_h
           {
-            parse_class:     parse_class,
-            modeled:         modeled,
-            callbacks:       callbacks,
-            local_routes:    local_routes,
+            parse_class: parse_class,
+            modeled: modeled,
+            callbacks: callbacks,
+            local_routes: local_routes,
             server_triggers: server_triggers,
-            findings:        findings,
+            findings: findings,
           }
         end
       end
@@ -144,11 +144,11 @@ module Parse
       #   callbacks (e.g. the `_User` default-ACL callback). Off by default to keep
       #   the report focused on app-defined logic.
       def initialize(network: true, client: nil, include_framework: false)
-        @networked         = network
+        @networked = network
         @include_framework = include_framework
-        @client            = client
-        @server_lookup     = network ? fetch_server_triggers : {}
-        @classes           = build_classes
+        @client = client
+        @server_lookup = network ? fetch_server_triggers : {}
+        @classes = build_classes
       end
 
       # @return [Array<Hash>] every finding across all classes, flattened, with the
@@ -164,10 +164,11 @@ module Parse
       def to_h
         {
           networked: networked,
-          classes:   @classes.map(&:to_h),
-          summary:   summary,
+          classes: @classes.map(&:to_h),
+          summary: summary,
         }
       end
+
       alias as_json to_h
 
       # @return [Hash] finding counts keyed by kind, plus class totals.
@@ -175,9 +176,9 @@ module Parse
         counts = Hash.new(0)
         gaps.each { |g| counts[g[:kind]] += 1 }
         {
-          classes_audited:    @classes.size,
+          classes_audited: @classes.size,
           classes_with_issues: @classes.count(&:issues?),
-          findings:           counts,
+          findings: counts,
         }
       end
 
@@ -212,6 +213,7 @@ module Parse
         s[:findings].sort.each { |kind, n| lines << "  #{kind}: #{n}" }
         lines.join("\n")
       end
+
       alias to_s pretty
 
       private
@@ -231,7 +233,7 @@ module Parse
         lookup = Hash.new { |h, k| h[k] = {} }
         client.triggers.results.each do |t|
           next unless t["url"].present?
-          name  = t["triggerName"]
+          name = t["triggerName"]
           klass = t[Parse::Model::KEY_CLASS_NAME] || t["className"]
           next if name.blank? || klass.blank?
           lookup[klass.to_s][name.to_s.underscore.to_sym] = t["url"]
@@ -262,18 +264,18 @@ module Parse
       end
 
       def audit_class(name)
-        klass     = name == "*" ? nil : (Parse::Model.find_class(name) rescue nil)
+        klass = name == "*" ? nil : (Parse::Model.find_class(name) rescue nil)
         callbacks = klass ? collect_callbacks(klass) : {}
-        routes    = collect_local_routes(name)
-        server    = @server_lookup[name] || {}
-        findings  = analyze(name, callbacks, routes, server)
+        routes = collect_local_routes(name)
+        server = @server_lookup[name] || {}
+        findings = analyze(name, callbacks, routes, server)
         ClassAudit.new(
-          parse_class:     name,
-          callbacks:       callbacks,
-          local_routes:    routes,
+          parse_class: name,
+          callbacks: callbacks,
+          local_routes: routes,
           server_triggers: server,
-          findings:        findings,
-          modeled:         !klass.nil?,
+          findings: findings,
+          modeled: !klass.nil?,
         )
       end
 
@@ -373,7 +375,7 @@ module Parse
         end
 
         required.each do |trigger, cb_keys|
-          has_route  = routes.include?(trigger)
+          has_route = routes.include?(trigger)
           has_server = server.key?(trigger)
           missing = []
           missing << :route unless has_route
@@ -381,7 +383,7 @@ module Parse
           next if missing.empty?
 
           findings << {
-            kind:    :callbacks_inert,
+            kind: :callbacks_inert,
             trigger: trigger,
             missing: missing,
             callbacks: cb_keys.sort,
@@ -398,7 +400,7 @@ module Parse
             # Wildcard-only coverage is reported on the "*" row, not here.
             next unless Parse::Webhooks.routes[trigger]&.key?(name)
             findings << {
-              kind:    :route_not_registered,
+              kind: :route_not_registered,
               trigger: trigger,
               message: "Local `webhook :#{trigger}` block for #{name} is not " \
                        "registered as a server trigger — run register_triggers! " \
@@ -410,7 +412,7 @@ module Parse
           server.each_key do |trigger|
             next if routes.include?(trigger)
             findings << {
-              kind:    :orphan_server_trigger,
+              kind: :orphan_server_trigger,
               trigger: trigger,
               message: "Server trigger #{trigger} is registered for #{name} but no " \
                        "local webhook block handles it — every matching operation " \
@@ -426,7 +428,7 @@ module Parse
         end
         if local_only.any?
           findings << {
-            kind:    :local_only_callbacks,
+            kind: :local_only_callbacks,
             callbacks: local_only.sort,
             message: "#{name} has local-only callbacks (#{local_only.sort.join(", ")}) " \
                      "that no server trigger can run — they fire for Ruby-initiated " \
@@ -451,25 +453,24 @@ module Parse
 
       def inert_message(name, trigger, missing, cb_keys)
         callbacks = cb_keys.sort.join(", ")
-        reason =
-          if missing == [:route, :server]
+        reason = if missing == [:route, :server]
             "neither a local `webhook :#{trigger}` block nor a server trigger is " \
-              "registered"
+            "registered"
           elsif missing == [:route]
             "no local `webhook :#{trigger}` block is registered to handle it"
           else # [:server]
             "a local block exists but the #{trigger} server trigger is not registered"
           end
         "#{name} callbacks (#{callbacks}) will NOT run for non-Ruby clients: " \
-          "#{reason}. Register `webhook :#{trigger}` and run register_triggers!."
+        "#{reason}. Register `webhook :#{trigger}` and run register_triggers!."
       end
 
       def finding_glyph(kind)
         case kind
-        when :callbacks_inert       then "GAP "
-        when :route_not_registered  then "GAP "
+        when :callbacks_inert then "GAP "
+        when :route_not_registered then "GAP "
         when :orphan_server_trigger then "WARN"
-        when :local_only_callbacks  then "note"
+        when :local_only_callbacks then "note"
         else "    "
         end
       end
@@ -493,7 +494,7 @@ module Parse
       #   `pretty: true`.
       def trigger_audit(pretty: false, network: true, client: nil, include_framework: false)
         audit = TriggerAudit.new(
-          network: network, client: client, include_framework: include_framework
+          network: network, client: client, include_framework: include_framework,
         )
         pretty ? audit.pretty : audit.to_h
       end

data/lib/parse/webhooks.rb

@@ -132,6 +132,46 @@ module Parse
 
     class << self
 
+      # Whether an exception raised by one `after_*` handler prevents the
+      # remaining handlers for that same trigger from running.
+      #
+      # Only the accumulating, non-rejectable `after_*` triggers can have more
+      # than one handler (see {Parse::Webhooks::Registration#route}), so this
+      # governs `after_save`, `after_delete`, and `after_logout` and nothing
+      # else. `before_*` dispatch is untouched: a raise there is how a handler
+      # denies an operation, and it must continue to abort.
+      #
+      # Defaults to `true`, which is the historical behavior. Handlers are
+      # folded with `Array#map`, and `map` abandons the collection on the first
+      # raise, so a handler that raises silently prevents every handler
+      # registered after it from running. That ordering is not something an
+      # application fully controls: the SDK's own cache-invalidation triggers
+      # install during `Parse.setup` and therefore sit ahead of handlers
+      # registered by application files loaded later.
+      #
+      # Set to `false` to isolate handlers from each other, so that each one
+      # runs regardless of what an earlier one raised. The error is reported
+      # (a warning plus a `parse.webhooks.handler_error` notification) and
+      # dispatch continues.
+      #
+      # Either way, nothing is reverted. An `after_*` trigger fires once the
+      # write has already committed, so there is no version of this setting
+      # that can undo the save; the only question it answers is whether the
+      # remaining handlers still get to run.
+      #
+      # @example Keep one failing handler from starving the others
+      #   Parse::Webhooks.abort_after_callbacks_on_error = false
+      #
+      # @return [Boolean]
+      attr_writer :abort_after_callbacks_on_error
+
+      # (see #abort_after_callbacks_on_error=)
+      # @return [Boolean]
+      def abort_after_callbacks_on_error
+        return @abort_after_callbacks_on_error unless @abort_after_callbacks_on_error.nil?
+        true
+      end
+
       # Allows support for web frameworks that support auto-reloading of source.
       # @!visibility private
       def reload!(args = {})
@@ -182,8 +222,26 @@ module Parse
           raise ArgumentError, "Invalid Webhook registration trigger #{type} #{className}"
         end
 
-        # AfterSave/AfterDelete hooks support more than one
-        if type == :after_save || type == :after_delete
+        # Triggers whose handlers compose instead of replacing one another.
+        #
+        # `after_save` / `after_delete` have always accumulated. The remaining
+        # `after_*` triggers are added because the SDK itself now registers
+        # them for cache invalidation: without this, registering an internal
+        # `after_logout` handler would silently replace an application's own,
+        # with the winner decided by file load order and no warning.
+        #
+        # This is safe only for non-rejectable triggers. Parse Server ignores
+        # their response body, and {#call_route} normalizes their result to
+        # `true` regardless, so `.last` semantics are irrelevant.
+        # {REJECTABLE_NON_OBJECT_TRIGGERS} are deliberately excluded: a
+        # composite of those must deny if ANY handler denies, and folding with
+        # `.last` would discard an earlier rejection.
+        composable = type == :after_save || type == :after_delete ||
+                     (NON_OBJECT_TRIGGERS.include?(type) &&
+                      !REJECTABLE_NON_OBJECT_TRIGGERS.include?(type) &&
+                      type.to_s.start_with?("after_"))
+
+        if composable
           routes[type][className] ||= []
           routes[type][className].push block
         else
@@ -227,6 +285,60 @@ module Parse
       # block that declares a parameter (`do |payload| ... end`) or a splat
       # receives the payload.
       #
+      # Run every handler registered for one accumulating `after_*` trigger.
+      #
+      # `.last` is preserved as the composed result because Parse Server
+      # ignores the response body for these triggers and {#call_route}
+      # normalizes it anyway, so which handler's value survives is not
+      # observable.
+      #
+      # When {abort_after_callbacks_on_error} is false, a handler that raises
+      # is reported and skipped rather than taking the rest of the trigger down
+      # with it. Nothing is reverted in either mode: the write these triggers
+      # fire on has already committed.
+      #
+      # @param payload [Parse::Webhooks::Payload] the request payload.
+      # @param registry [Array<Proc>] the handlers, in registration order.
+      # @param type [Symbol] the trigger being dispatched.
+      # @return [Object] the last handler result.
+      def dispatch_composed(payload, registry, type)
+        return registry.map { |hook| invoke_handler(payload, hook) }.last if
+          abort_after_callbacks_on_error
+
+        last = nil
+        registry.each do |hook|
+          begin
+            last = invoke_handler(payload, hook)
+          rescue StandardError => e
+            report_handler_error(type, e)
+          end
+        end
+        last
+      end
+
+      # Report a handler failure that was isolated rather than propagated.
+      #
+      # The message is included because an application's own handler raised it
+      # and the application needs it to debug; this is not the SDK's internal
+      # `guard`, which deliberately omits messages that can carry a cache key.
+      #
+      # @param type [Symbol] the trigger being dispatched.
+      # @param error [StandardError] the raised error.
+      # @return [void]
+      def report_handler_error(type, error)
+        warn "[Parse::Webhooks] #{type} handler raised #{error.class}: #{error.message}; " \
+             "continuing with the remaining handlers " \
+             "(Parse::Webhooks.abort_after_callbacks_on_error is false)"
+        return unless defined?(ActiveSupport::Notifications)
+        begin
+          ActiveSupport::Notifications.instrument(
+            "parse.webhooks.handler_error", trigger: type, error: error.class.name,
+          )
+        rescue StandardError
+          nil
+        end
+      end
+
       # @param payload [Parse::Webhooks::Payload] the request payload (becomes `self`).
       # @param block [Proc] the registered handler block.
       # @return [Object] the handler's result value.
@@ -353,14 +465,17 @@ module Parse
             if pre_obj.respond_to?(:apply_field_guards!)
               pre_obj.apply_field_guards!(
                 master: payload.master? || false,
-                is_new: payload.original.blank?
+                is_new: payload.original.blank?,
               )
             end
           end
         end
 
         if registry.is_a?(Array)
-          result = registry.map { |hook| invoke_handler(payload, hook) }.last
+          # An Array registry only ever exists for the accumulating,
+          # non-rejectable `after_*` triggers, so isolating handlers here
+          # cannot affect `before_*` rejection semantics.
+          result = dispatch_composed(payload, registry, type)
         else
           result = invoke_handler(payload, registry)
         end
@@ -777,7 +892,7 @@ module Parse
           else
             if self.logging.present?
               puts "[Webhooks] --> Could not find mapping route for " \
-                   "#{Parse::Middleware::BodyBuilder.redact(payload.to_json)}"
+                "#{Parse::Middleware::BodyBuilder.redact(payload.to_json)}"
             end
           end
 

data/parse-stack-next.gemspec

@@ -6,7 +6,7 @@ require "parse/stack/version"
 Gem::Specification.new do |spec|
   spec.name = "parse-stack-next"
   spec.version = Parse::Stack::VERSION
-  spec.authors =  ["Adrian Curtin", "Anthony Persaud", "Henry Spindell"]
+  spec.authors = ["Adrian Curtin", "Anthony Persaud", "Henry Spindell"]
   spec.email = ["adrian+parse-stack@neurosynq.net"]
 
   spec.summary = %q{Parse Server SDK for Ruby — ORM, queries, auth, and MongoDB-direct access}
@@ -15,11 +15,11 @@ Gem::Specification.new do |spec|
   spec.license = "MIT"
 
   spec.metadata = {
-    "homepage_uri"          => "https://github.com/neurosynq/parse-stack-next",
-    "source_code_uri"       => "https://github.com/neurosynq/parse-stack-next",
-    "changelog_uri"         => "https://github.com/neurosynq/parse-stack-next/blob/main/CHANGELOG.md",
-    "bug_tracker_uri"       => "https://github.com/neurosynq/parse-stack-next/issues",
-    "documentation_uri"     => "https://neurosynq.github.io/parse-stack-next/",
+    "homepage_uri" => "https://github.com/neurosynq/parse-stack-next",
+    "source_code_uri" => "https://github.com/neurosynq/parse-stack-next",
+    "changelog_uri" => "https://github.com/neurosynq/parse-stack-next/blob/main/CHANGELOG.md",
+    "bug_tracker_uri" => "https://github.com/neurosynq/parse-stack-next/issues",
+    "documentation_uri" => "https://neurosynq.github.io/parse-stack-next/",
     "rubygems_mfa_required" => "true",
   }
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parse-stack-next
 version: !ruby/object:Gem::Version
-  version: 5.6.0
+  version: 5.7.1
 platform: ruby
 authors:
 - Adrian Curtin
@@ -225,6 +225,7 @@ files:
 - docs/_config.yml
 - docs/acl_clp_guide.md
 - docs/atlas_vector_search_guide.md
+- docs/caching.md
 - docs/client_sdk_guide.md
 - docs/mcp_guide.md
 - docs/mongodb_direct_guide.md
@@ -242,6 +243,7 @@ files:
 - examples/webhook_server.rb
 - lib/parse-stack-next.rb
 - lib/parse-stack.rb
+- lib/parse/access.rb
 - lib/parse/acl_scope.rb
 - lib/parse/agent.rb
 - lib/parse/agent/approval_gate.rb
@@ -284,8 +286,15 @@ files:
 - lib/parse/atlas_search/result.rb
 - lib/parse/atlas_search/search_builder.rb
 - lib/parse/atlas_search/session.rb
+- lib/parse/authorization.rb
+- lib/parse/cache/invalidation.rb
+- lib/parse/cache/keyspace.rb
+- lib/parse/cache/moneta_surface.rb
 - lib/parse/cache/pool.rb
 - lib/parse/cache/redis.rb
+- lib/parse/cache/scoped_view.rb
+- lib/parse/cache/sub_cache.rb
+- lib/parse/cache/upstream_roles.rb
 - lib/parse/client.rb
 - lib/parse/client/authentication.rb
 - lib/parse/client/batch.rb