parse-stack-next 4.5.0 → 5.0.0

data/lib/parse/client/response.rb

@@ -33,6 +33,14 @@ module Parse
     ERROR_EMAIL_NOT_FOUND = 205
     # Code when the email is invalid
     ERROR_EMAIL_INVALID = 125
+    # Code returned for invalid or expired session tokens (Parse Server).
+    ERROR_INVALID_SESSION_TOKEN = 209
+    # Code returned for operations that are not permitted under the
+    # caller's ACL / CLP / authentication scope. Parse Server uses
+    # this code for both "you are not authenticated for this" and
+    # "you are authenticated, but not authorized" — see
+    # {#permission_denied?} for the SDK-friendly predicate.
+    ERROR_OPERATION_FORBIDDEN = 119
 
     # The field name for the error.
     ERROR = "error".freeze
@@ -171,6 +179,25 @@ module Parse
       @code == ERROR_OBJECT_NOT_FOUND
     end
 
+    # true if the response indicates the caller is not authorized to
+    # perform the requested operation. Parse Server signals authorization
+    # failure in two shapes that no-master-key clients commonly hit:
+    #
+    # - HTTP 403 with no body (sometimes 401) — recorded as
+    #   `http_status` only, with no error code in the JSON.
+    # - HTTP 400 + error code 119 (`OPERATION_FORBIDDEN`) — typical for
+    #   CLP and `protectedFields` denials.
+    # - HTTP 400 + error code 209 (`INVALID_SESSION_TOKEN`) — session
+    #   token missing, revoked, or expired.
+    #
+    # This predicate normalizes those into a single check so client code
+    # doesn't have to remember both the HTTP-status and code-only paths.
+    # @return [Boolean]
+    def permission_denied?
+      return true if @http_status == 401 || @http_status == 403
+      @code == ERROR_OPERATION_FORBIDDEN || @code == ERROR_INVALID_SESSION_TOKEN
+    end
+
     # @return [Array] the result data from the response.
     def results
       return [] if @result.nil?

data/lib/parse/client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "faraday"
 
 # Attempt to load the persistent connection adapter for better performance.
@@ -29,6 +31,7 @@ require_relative "client/batch"
 require_relative "client/body_builder"
 require_relative "client/authentication"
 require_relative "client/caching"
+require_relative "cache/redis"
 require_relative "client/logging"
 require_relative "client/profiling"
 require_relative "api/all"
@@ -392,10 +395,13 @@ module Parse
     #      Parse.setup(
     #        connection_pooling: { pool_size: 5, idle_timeout: 60, keep_alive: 60 }
     #      )
-    # @option opts [Moneta::Transformer,Moneta::Expires] :cache A caching adapter of type
+    # @option opts [Moneta::Transformer,Moneta::Expires,Parse::Cache::Redis,String] :cache A caching adapter of type
     #    {https://github.com/minad/moneta Moneta::Transformer} or
     #    {https://github.com/minad/moneta Moneta::Expires} that will be used
-    #    by the caching middleware {Parse::Middleware::Caching}.
+    #    by the caching middleware {Parse::Middleware::Caching}. You can also
+    #    pass a `redis://` URL string (an internal Moneta-Redis store will be
+    #    built for you) or a {Parse::Cache::Redis} wrapper, which adds a
+    #    connection pool and automatic namespace forwarding.
     #    Caching queries and object fetches can help improve the performance of
     #    your application, even if it is for a few seconds. Only successful GET
     #    object fetches and non-empty result queries will be cached by default.
@@ -407,6 +413,13 @@ module Parse
     #    middleware. The default value is 3 seconds. If :expires is set to 0,
     #    caching will be disabled. You can always clear the current state of the
     #    cache using the clear_cache! method on your Parse::Client instance.
+    # @option opts [String] :cache_namespace Optional prefix applied to every
+    #    cache key. Useful when two Parse apps share one Redis instance and
+    #    would otherwise collide on identical paths (e.g.
+    #    `mk:/classes/Song/abc`). Keys become `<namespace>:<existing-prefix>:<url>`,
+    #    so a `SCAN <namespace>:*` evicts a whole app cleanly. Defaults to no
+    #    namespace for backward compatibility — explicit only, never auto-derived
+    #    from `app_id`.
     # @option opts [Hash] :faraday You may pass a hash of options that will be
     #    passed to the Faraday constructor.
     # @option opts [String] :live_query_url The WebSocket URL for Parse LiveQuery server
@@ -565,8 +578,23 @@ module Parse
             unless [:key?, :[], :delete, :store].all? { |method| opts[:cache].respond_to?(method) }
               raise ArgumentError, "Parse::Client option :cache needs to be a type of Moneta store"
             end
+
+            # If the caller passed a `Parse::Cache::Redis` wrapper, let its
+            # built-in namespace flow through automatically. An explicit
+            # `cache_namespace:` still wins so callers can override.
+            if defined?(Parse::Cache::Redis) && opts[:cache].is_a?(Parse::Cache::Redis)
+              opts[:cache_namespace] ||= opts[:cache].namespace
+            end
+
             self.cache = opts[:cache]
-            conn.use Parse::Middleware::Caching, self.cache, { expires: opts[:expires].to_i }
+            conn.use Parse::Middleware::Caching, self.cache, {
+              expires: opts[:expires].to_i,
+              # Optional `cache_namespace:` prefixes every key so two Parse
+              # apps sharing one Redis don't collide on `mk:/classes/Song/abc`.
+              # Explicit only — we do NOT auto-derive from app_id to keep
+              # existing single-app deployments backward-compatible.
+              namespace: opts[:cache_namespace],
+            }
 
             # Inform about opt-in cache behavior
             unless Parse.default_query_cache
@@ -738,6 +766,29 @@ module Parse
     # @see Parse::Protocol
     # @see Parse::Request
     def request(method, uri = nil, body: nil, query: nil, headers: nil, opts: {})
+      # Pre-declare locals referenced inside rescue blocks so CodeQL's
+      # uninitialized-variable analysis is satisfied even if an exception
+      # raises before the natural assignment site.
+      response     = nil
+      _retry_count = nil
+      _retry_delay = nil
+      _request     = nil
+      # Kwarg-absorption guard. The `**opts` splat in API helper methods
+      # (lib/parse/api/*.rb) absorbs a caller-passed `opts: { ... }`
+      # keyword as a key named `:opts` rather than as the request options
+      # hash itself. The auth context (session_token, use_master_key)
+      # buried under :opts then never reaches the request — the call
+      # silently goes out anonymous (or master, if one is configured),
+      # which is a permission-downgrade footgun. Fail loudly here so the
+      # bug surfaces in dev/test instead of in production.
+      if opts.is_a?(Hash) && opts[:opts].is_a?(Hash)
+        raise ArgumentError, "Parse::Client#request received nested `opts: { opts: { ... } }` — " \
+                             "pass session_token: / use_master_key: directly as keywords, " \
+                             "not wrapped in an `opts:` hash. " \
+                             "Bad: Parse.client.create_object('X', body, opts: { session_token: t }) " \
+                             "Good: Parse.client.create_object('X', body, session_token: t, use_master_key: false)"
+      end
+
       _retry_count ||= self.retry_limit
 
       if opts[:retry] == false
@@ -776,11 +827,31 @@ module Parse
         headers[Parse::Middleware::Caching::CACHE_EXPIRES_DURATION] = opts[:cache].to_s
       end
 
+      # Resolve the auth context in three layers:
+      #   1. explicit per-call `use_master_key:` and `session_token:`
+      #   2. ambient session set by `Parse.with_session { ... }` (fiber-local)
+      #   3. process-wide `Parse.client_mode` flag — when true, master key is
+      #      never sent unless the caller explicitly passed `use_master_key: true`
+      explicit_master = opts.key?(:use_master_key)
+
       if opts[:use_master_key] == false
         headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
+      elsif Parse.client_mode && opts[:use_master_key] != true
+        # client mode defaults master key OFF unless explicitly opted in
+        headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"
       end
 
       token = opts[:session_token]
+      # When no explicit token was passed AND the caller didn't ask to send
+      # the master key, fall through to the fiber-local ambient set by
+      # `Parse.with_session`. Explicit `use_master_key: true` is treated as
+      # a deliberate admin call and skips the ambient — otherwise an
+      # `admin.do_thing(use_master_key: true)` nested inside a
+      # `with_session(user)` block would silently downgrade.
+      if token.nil? && !(explicit_master && opts[:use_master_key] == true)
+        ambient = Parse.current_session_token
+        token = ambient if ambient.is_a?(String) && !ambient.empty?
+      end
       if token.present?
         token = token.session_token if token.respond_to?(:session_token)
         headers[Parse::Middleware::Authentication::DISABLE_MASTER_KEY] = "true"

data/lib/parse/console.rb

@@ -0,0 +1,203 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+# Console-friendly helpers for interactive Parse sessions.
+#
+# `watch` and `wait_for` wrap the LiveQuery subscription machinery in a
+# blocking-by-default shape suited for `bin/rails console`, `bin/console`,
+# or one-off Rake tasks where the caller wants to:
+#
+#   - Tail a class as rows arrive ("watch new posts"), Ctrl-C to stop.
+#   - Block until a specific row appears or a condition matches
+#     ("wait until job N flips to :done"), with an optional timeout.
+#
+# Auth resolution is automatic:
+#   - If `Parse.current_session_token` is set (via `Parse.login`,
+#     `Parse.with_session`, or `Parse.session_token=`), the subscription
+#     is ACL-aware as that user.
+#   - Otherwise it falls through with no token — the LiveQuery server
+#     then applies whatever default the master-key / unauthenticated
+#     subscription model dictates for the class.
+#
+# Both helpers also accept an explicit `session_token:` kwarg for
+# tests / fixtures.
+
+require "timeout"
+
+module Parse
+  module Console
+    DEFAULT_WATCH_EVENTS  = [:create, :update, :delete, :enter, :leave].freeze
+    DEFAULT_WAIT_FOR_EVENTS = [:create, :enter].freeze
+
+    module_function
+
+    # Open a LiveQuery subscription on `klass` and block until SIGINT
+    # (Ctrl-C). Intended for REPL / console use — emits arriving events
+    # to `$stdout` by default, or yields each one to a caller-supplied
+    # block.
+    #
+    # @example Tail every event for a class
+    #   Parse.watch(Post)
+    #   # ^C to stop
+    #
+    # @example Tail with a query and a custom handler
+    #   Parse.watch(Post, where: { category: "alerts" }) do |event, obj|
+    #     puts "[#{event}] #{obj.title} (#{obj.id})"
+    #   end
+    #
+    # @example Admin-style with master key (no ambient session)
+    #   Parse.with_session(nil) { Parse.watch(JobRun) }
+    #
+    # @param klass [Class] a Parse::Object subclass.
+    # @param where [Hash] optional query constraints.
+    # @param on [Symbol, Array<Symbol>, nil] which event types to
+    #   subscribe to (default: all of :create/:update/:delete/:enter/:leave).
+    # @param fields [Array<String>, nil] only fire updates when these
+    #   fields change.
+    # @param session_token [String, nil] explicit override; defaults to
+    #   `Parse.current_session_token`.
+    # @yield [event, object] called for each emitted event when a block
+    #   is supplied. `event` is one of the watched symbols; `object` is
+    #   the row.
+    # @return [Integer] the count of events delivered before the caller
+    #   interrupted (Ctrl-C) or the subscription was torn down.
+    def watch(klass, where: {}, on: nil, fields: nil, session_token: nil, &block)
+      events = Array(on || DEFAULT_WATCH_EVENTS).map(&:to_sym)
+      printer = block_given? ? block : ->(ev, obj) {
+        title = obj.respond_to?(:id) ? obj.id : obj.inspect
+        puts "[#{Time.now.iso8601}] #{klass.parse_class}.#{ev} #{title}"
+      }
+
+      delivered = 0
+      counter_lock = Monitor.new
+      sub = _open_subscription(klass, where: where, fields: fields, session_token: session_token)
+
+      events.each do |ev|
+        sub.on(ev) do |obj, _original = nil|
+          counter_lock.synchronize { delivered += 1 }
+          begin
+            printer.call(ev, obj)
+          rescue StandardError => e
+            warn "[Parse.watch] handler raised #{e.class}: #{e.message}"
+          end
+        end
+      end
+      sub.on(:error) { |err| warn "[Parse.watch] error: #{err}" }
+
+      _block_until_interrupt
+      delivered
+    ensure
+      sub.unsubscribe if sub && sub.respond_to?(:unsubscribe)
+    end
+
+    # Block until a row matching the predicate arrives via LiveQuery,
+    # then return that row. Useful for `wait until the job flips`,
+    # `wait until the inbox row lands`, integration tests, etc.
+    #
+    # By default the first `:create`/`:enter` event resolves the wait.
+    # Pass a block to require the event also satisfy a predicate —
+    # `wait_for(Job, where: { kind: "import" }) { |j| j.status == "done" }`
+    # will keep waiting until both the query matches AND the block
+    # returns truthy.
+    #
+    # @example Wait for the first row of a class
+    #   first = Parse.wait_for(Notification)
+    #
+    # @example Wait with a query and a predicate
+    #   done = Parse.wait_for(Job, where: { kind: "import" },
+    #                          timeout: 60) { |j| j.status == "done" }
+    #
+    # @param klass [Class] a Parse::Object subclass.
+    # @param where [Hash] optional query constraints applied server-side.
+    # @param on [Symbol, Array<Symbol>] which event types to count
+    #   (default: [:create, :enter]; pass :update for status-flip
+    #   watching).
+    # @param timeout [Numeric, nil] seconds to wait. nil = forever.
+    # @param fields [Array<String>, nil] field filter for update events.
+    # @param session_token [String, nil] explicit override; defaults to
+    #   `Parse.current_session_token`.
+    # @yield [object] optional predicate; must return truthy to resolve.
+    # @return [Parse::Object] the matched row.
+    # @raise [Timeout::Error] when `timeout:` elapses with no match.
+    def wait_for(klass, where: {}, on: nil, timeout: nil, fields: nil,
+                 session_token: nil, &predicate)
+      events = Array(on || DEFAULT_WAIT_FOR_EVENTS).map(&:to_sym)
+      queue  = Queue.new
+      sub = _open_subscription(klass, where: where, fields: fields, session_token: session_token)
+
+      events.each do |ev|
+        sub.on(ev) do |obj, _original = nil|
+          begin
+            next if predicate && !predicate.call(obj)
+            queue << obj
+          rescue StandardError => e
+            queue << e
+          end
+        end
+      end
+      sub.on(:error) { |err| queue << err }
+
+      result = if timeout
+          Timeout.timeout(timeout) { queue.pop }
+        else
+          queue.pop
+        end
+
+      raise result if result.is_a?(Exception)
+      result
+    ensure
+      sub.unsubscribe if sub && sub.respond_to?(:unsubscribe)
+    end
+
+    # @!visibility private
+    def _open_subscription(klass, where:, fields:, session_token:)
+      unless klass.respond_to?(:subscribe)
+        raise ArgumentError, "#{klass.inspect} does not implement .subscribe — pass a Parse::Object subclass"
+      end
+      klass.subscribe(where: where, fields: fields, session_token: session_token)
+    end
+
+    # @!visibility private
+    #
+    # Block the current thread until SIGINT (Ctrl-C) is received.
+    # We install a one-shot handler that releases a sleeping queue.pop
+    # and restore the prior handler on exit so library users can wrap
+    # `watch` inside their own signal-handling code without losing it.
+    def _block_until_interrupt
+      gate = Queue.new
+      prior = Signal.trap("INT") { gate << :interrupted }
+      gate.pop
+    ensure
+      Signal.trap("INT", prior || "DEFAULT") if defined?(prior)
+    end
+  end
+
+  class << self
+    # @see Parse::Console.watch
+    def watch(klass, **kwargs, &block)
+      Console.watch(klass, **kwargs, &block)
+    end
+
+    # @see Parse::Console.wait_for
+    def wait_for(klass, **kwargs, &block)
+      Console.wait_for(klass, **kwargs, &block)
+    end
+  end
+
+  class Object < Pointer
+    class << self
+      # Tail this class as LiveQuery events arrive — blocking, Ctrl-C
+      # to stop. See {Parse::Console.watch}.
+      def watch(**kwargs, &block)
+        Parse::Console.watch(self, **kwargs, &block)
+      end
+
+      # Block until the first row matching {where} (and an optional
+      # predicate block) arrives via LiveQuery. See
+      # {Parse::Console.wait_for}.
+      def wait_for(**kwargs, &block)
+        Parse::Console.wait_for(self, **kwargs, &block)
+      end
+    end
+  end
+end