parse-stack-next 5.6.0 → 5.7.1

data/lib/parse/cache/redis.rb

@@ -3,7 +3,13 @@
 
 require "moneta"
 require "json"
+require "securerandom"
 require_relative "pool"
+require_relative "keyspace"
+require_relative "moneta_surface"
+require_relative "sub_cache"
+require_relative "upstream_roles"
+require_relative "scoped_view"
 
 module Parse
   module Cache
@@ -29,6 +35,10 @@ module Parse
     # `delete`, `store` — to a pooled backend), so it can be passed
     # directly to `Parse.setup(cache:)` / `Parse::Client.new(cache:)`.
     class Redis
+      # `[]=`, `fetch`, `load`, `values_at`, `slice`, `merge!` and friends,
+      # derived from the four primitives below. See {Parse::Cache::MonetaSurface}.
+      include Parse::Cache::MonetaSurface
+
       # @return [String, nil] cache key namespace prefix (or nil if not set).
       attr_reader :namespace
 
@@ -38,6 +48,176 @@ module Parse
       # @return [String] Redis connection URL.
       attr_reader :url
 
+      # There is deliberately no `keyspace` reader/writer and no `keyspace:`
+      # constructor option on this class anymore. This backend is a shared
+      # connection pool: several {Parse::Client} instances (several Parse
+      # apps, or several tenants) pointing one `Parse::Cache::Redis` at the
+      # same Redis is a normal, supported deployment. A mutable keyspace
+      # binding on the SHARED object was not, because a second client
+      # calling `keyspace = ks_b` rebound the one `@keyspace` ivar out from
+      # under the first: client A's caching middleware kept using A's
+      # keyspace object (captured at construction) while `clear`, `identity`,
+      # `roles`, and the memoized `upstream_roles` on this now-shared object
+      # answered with B's. A stopped invalidating its own entries, or a
+      # scoped `clear` issued through A deleted B's keys instead.
+      #
+      # {#scoped} replaces that mutable path entirely: it hands back a
+      # {Parse::Cache::ScopedView} carrying its own keyspace and its own
+      # memoized identity/roles/upstream_roles, so two callers can share this
+      # backend's connection pool without ever being able to share, or steal,
+      # keyspace ownership.
+      #
+      # Derive a per-client view over this shared backend.
+      #
+      # @param keyspace [Parse::Cache::Keyspace]
+      # @return [Parse::Cache::ScopedView]
+      def scoped(keyspace)
+        Parse::Cache::ScopedView.new(backend: self, keyspace: keyspace)
+      end
+
+      # @return [String, nil] Parse Server's cache database URL, when attached.
+      attr_reader :parse_cache_url
+
+      # Read-only view of Parse Server's role cache, or nil when not attached.
+      #
+      # Uses a raw redis-rb client rather than the Moneta pool: Moneta's Redis
+      # adapter issues a MULTI/PEXPIRE pipeline on every read when built with
+      # `expires:`, which a credential restricted to `+get +pttl` rejects with
+      # NOPERM.
+      #
+      # This backend-level reader has no keyspace, and therefore no app id or
+      # role-plane freshness gate to scope itself with: {#scoped} is the only
+      # way to bind one to an app. Its `app_id` is nil, so `key_for` /
+      # `roles_for` on this instance can never match a real Parse Server
+      # entry (which is always `<appId>:role:<userId>`). They will only
+      # ever report a miss. Prefer `backend.scoped(keyspace).upstream_roles`
+      # for any real read. This method is NOT used by
+      # {#verify_upstream_isolation!}, which needs a database-wide probe
+      # rather than one scoped to a single (missing) app id and builds its
+      # own reader.
+      # @return [Parse::Cache::UpstreamRoles, nil]
+      def upstream_roles
+        return nil if @parse_cache_url.nil?
+        @upstream_roles ||= UpstreamRoles.new(client: upstream_client, app_id: nil, roles_plane: nil)
+      end
+
+      # Verify the attached endpoint is a different database from ours, and warn
+      # if not.
+      #
+      # Deliberately a warning rather than a refusal: the hazard comes entirely
+      # from the upstream FLUSHDB bug, so it disappears on a server carrying the
+      # scoped-clear fix, and refusing to boot would be permanently wrong there.
+      # It routes through the existing degraded-lock path so the caller's
+      # `on_degraded:` decides whether to warn or raise, because the consequence
+      # that is not merely a performance loss is a create-lock deleted mid-hold,
+      # which silently removes `first_or_create!` mutual exclusion.
+      #
+      # Three outcomes, because two of them were previously collapsed into
+      # one and the collapse hid a false negative:
+      #
+      # - `true`: isolation positively established. A sentinel written to our
+      #   database was NOT visible through the upstream connection.
+      # - `false`: sharing positively established, and warned about.
+      # - `:unknown`: neither could be established. Truthy, so callers that
+      #   branch on truthiness behave as before, but distinguishable for
+      #   callers that want to escalate. This is what a credential restricted
+      #   to `~<appId>:role:*` produces: the sentinel read comes back NOPERM,
+      #   which says nothing about which database it was denied on.
+      #
+      # The scan alone cannot return `true`. It only ever finds a
+      # Parse-Server-shaped key or fails to, and "no such key" is equally
+      # consistent with a separate database and with a shared one on which
+      # Parse Server has not yet cached a role. A stack that was just
+      # deployed is in that second state, which is precisely when an operator
+      # runs this check, so treating the empty scan as proof of isolation
+      # returned a confident "isolated" for the shared case it exists to
+      # catch.
+      #
+      # @return [Boolean, :unknown] see above.
+      def verify_upstream_isolation!(on_degraded: :warn_throttled)
+        return true if @parse_cache_url.nil?
+        # Deliberately NOT {#upstream_roles}: this backend has no keyspace
+        # (and therefore no app id: that can only come from {#scoped} now)
+        # to build a reader from, and there is no single "the" app id to use
+        # here anyway: this backend can be shared by clients of more than one
+        # app (see {#scoped}), and this check is a database-sharing probe,
+        # not a per-app one.
+        #
+        # `UpstreamRoles#shares_database_with?` scans for
+        # `"#{app_id}:role:*"`. Two wrong ways to pick `app_id` were tried and
+        # rejected here, in favor of a third:
+        #
+        # - `nil` turns that into the literal pattern `":role:*"`, which never
+        #   matches a real Parse Server key (`<appId>:role:<userId>`, no
+        #   leading colon), so the probe always reports "isolated", even on
+        #   a database that is genuinely shared. Silently disables the exact
+        #   warning this method exists to raise.
+        # - A bare `"*"` wildcard produces `"*:role:*"`. Redis (and
+        #   `File.fnmatch`) glob `*` crosses `:` just like any other
+        #   character, so that pattern ALSO matches this SDK's own role-plane
+        #   keys (`parse-stack:v1:<scope>:<ns>:role:<userId>`). The probe
+        #   would report "shared" as soon as the role plane held anything,
+        #   even on a database that is genuinely isolated. A permanent false
+        #   positive is worse than the false negative it replaced: it trains
+        #   operators to ignore the warning.
+        #
+        # The fix keeps the broad `"*"` wildcard (so this still catches ANY
+        # app's cached role, not one we'd have to already know the id of) and
+        # keeps only keys matching Parse Server's own three-segment
+        # `<appId>:role:<userId>` shape, so `shares_database_with?` can only
+        # ever see a genuine upstream entry. See {ExcludeOwnKeysScanner} for
+        # why the filter matches the upstream shape rather than rejecting a
+        # `parse-stack:` prefix.
+        reader = UpstreamRoles.new(client: upstream_client, app_id: "*")
+        # The probe scans OUR database for THEIR key pattern, so it needs a
+        # scannable client rather than this Moneta-shaped wrapper.
+        shared = @pool.pool.with do |store|
+          reader.shares_database_with?(ExcludeOwnKeysScanner.new(backend_client(store)))
+        end
+
+        unless shared
+          # The scan found nothing, which does not distinguish a separate
+          # database from a shared one Parse Server has not written to yet.
+          # Settle it by writing a key only we can have written and asking
+          # the upstream connection whether it can see it.
+          #
+          # Only two of the three outcomes return. `:shared` deliberately
+          # falls through to the warning path below, which is the same
+          # handling a positive scan gets.
+          case sentinel_probe
+          when :isolated then return true
+          when :unknown
+            warn "[Parse::Cache::Redis] could not verify that parse_cache_url addresses a " \
+                 "different Redis database than url. The probe key was neither readable nor " \
+                 "conclusively absent through the upstream connection, which is what a " \
+                 "credential restricted to ~<appId>:role:* produces. Confirm the two " \
+                 "databases differ by hand, or grant the reader GET on parse-stack:probe:* " \
+                 "so this check can answer. " \
+                 "See https://github.com/parse-community/parse-server/issues/10617"
+            return :unknown
+          end
+        end
+
+        if defined?(Parse::LockBackend)
+          Parse::LockBackend.handle_degraded(
+            on_degraded, "cache:shared-database", source: "Parse::Cache::Redis",
+          )
+        end
+        warn "[Parse::Cache::Redis] parse_cache_url resolves to the same Redis database as " \
+             "url. Parse Server clears its cache with FLUSHDB on every _Role write, which " \
+             "deletes this SDK's cached responses and its parse-stack:foc:v1:* create-locks, " \
+             "so first_or_create! loses cross-process mutual exclusion. Point the two at " \
+             "different databases (redis://host/0 and redis://host/1), or run a Parse Server " \
+             "carrying the scoped-clear fix. " \
+             "See https://github.com/parse-community/parse-server/issues/10617"
+        false
+      end
+
+      # Note: there is no `identity` / `roles` plane accessor on this class.
+      # Both require a keyspace, and a keyspace can only ever be bound
+      # through {#scoped} now, never directly on this shared backend. Use
+      # `backend.scoped(keyspace).identity` / `.roles` instead.
+
       # @param url [String] Redis URL (e.g. `"redis://localhost:6379/0"`).
       # @param namespace [String, nil] optional key prefix so multiple Parse
       #   apps can share one Redis without colliding. When non-nil, the
@@ -71,9 +251,25 @@ module Parse
       #   note that doing so causes cached responses to live forever,
       #   which is rarely what you want for a session-token-scoped
       #   response cache.
-      def initialize(url:, namespace: nil, pool_size: 5, pool_timeout: 5, **moneta_options)
+      def initialize(url:, namespace: nil, pool_size: 5, pool_timeout: 5,
+                     parse_cache_url: nil, **moneta_options)
         @url = url
+        # Parse Server's own cache database, read-only and optional. It must NOT
+        # be the same database as `url:`: on released Parse Server a `_Role`
+        # write FLUSHDBs the whole database, which would take this SDK's
+        # response cache and, worse, its create-locks with it.
+        @parse_cache_url = parse_cache_url
         @namespace = normalize_namespace(namespace)
+        # A caller-supplied Moneta `prefix:` silently rewrites the physical key
+        # layout underneath us, which would break every SCAN pattern this class
+        # builds and quietly restore the unscoped-clear behavior the keyspace
+        # exists to prevent. Reject it rather than trying to compose with it.
+        if moneta_options.key?(:prefix)
+          raise ArgumentError,
+                "Parse::Cache::Redis does not accept a Moneta prefix: option; it would " \
+                "change the physical key layout that scoped clearing depends on. Use " \
+                "namespace: instead."
+        end
         @pool_size = pool_size
         @pool_timeout = pool_timeout
         # Default expires: true so per-call `expires:` (the TTL the
@@ -104,20 +300,34 @@ module Parse
         end
       end
 
+      # Moneta's read primitive. Defined here rather than derived, because
+      # only this class knows how to reach its pool and how to decode what
+      # comes back.
+      def load(key, options = {})
+        decode_value(@pool.load(key, options || {}))
+      end
+
       def [](key)
-        decode_value(@pool[key])
+        load(key, {})
       end
 
-      def key?(key)
-        @pool.key?(key)
+      def key?(key, options = {})
+        @pool.key?(key, options || {})
       end
 
-      def delete(key)
-        @pool.delete(key)
+      # Returns the DECODED value, matching Moneta, which returns what was
+      # removed. This used to hand back the raw JSON string this wrapper had
+      # encoded on the way in, so `delete` and `store` returned
+      # `"{\"a\":1}"` where every other read returned `{"a" => 1}`.
+      def delete(key, options = {})
+        decode_value(@pool.delete(key, options || {}))
       end
 
+      # Returns the value as given, matching Moneta. The encoded form is an
+      # implementation detail of how it is stored and must not leak out.
       def store(key, value, options = {})
-        @pool.store(key, encode_value(value), options)
+        @pool.store(key, encode_value(value), options || {})
+        value
       end
 
       # Atomic SETNX. Required so `Parse::CreateLock` can acquire
@@ -136,6 +346,28 @@ module Parse
         @pool.increment(key, amount, options)
       end
 
+      # Set a TTL on an existing key WITHOUT touching its value.
+      #
+      # Exists because `INCR` sets no expiry, and the only other way to add
+      # one through Moneta is to re-`store` the value, which loses concurrent
+      # increments. For {Parse::Cache::SubCache}'s generation counters a lost
+      # increment moves the counter backwards, and since generation checks
+      # are equality comparisons, a counter returning to a previously issued
+      # value re-admits the identity entries that value had invalidated.
+      # PEXPIRE touches only the TTL, so it cannot do that.
+      #
+      # @param key [String] the physical key.
+      # @param ttl [Numeric] seconds.
+      # @return [Boolean] true when the key existed and the TTL was set.
+      def expire(key, ttl)
+        return false if ttl.nil?
+        @pool.pool.with do |store|
+          !!backend_client(store).pexpire(key, (ttl.to_f * 1000).round)
+        end
+      rescue StandardError
+        false
+      end
+
       # Lua compare-and-delete: delete `key` only if its current value
       # equals `expected`. Atomic on the Redis server (the GET, the
       # compare, and the DEL are one script invocation), which closes the
@@ -210,7 +442,29 @@ module Parse
       #   The scope must be a non-empty String; the trailing `:` is added
       #   automatically and any trailing `:` in the input is stripped so
       #   `"tenant_x"` and `"tenant_x:"` are equivalent.
-      def clear(scope: nil)
+      #
+      # This backend never has a keyspace of its own (see {#scoped}), so
+      # `family:` / `tenant:` cannot be honored here: interpreting them needs
+      # a `root_prefix`, and only a {Parse::Cache::ScopedView} has one.
+      #
+      # Passing either is therefore a hard error rather than a silent
+      # no-op. Ignoring them would take the `else` branch below and issue
+      # `FLUSHDB`, so a caller asking to clear ONE family on an unnamespaced
+      # backend would wipe the entire database: every other family, every
+      # other app sharing the backend, and the `parse-stack:foc:v1:*`
+      # create-locks whose loss silently removes `first_or_create!` mutual
+      # exclusion. A request to narrow must never widen. Use
+      # `backend.scoped(keyspace).clear(family:)` instead.
+      #
+      # @raise [ArgumentError] when `family:` or `tenant:` is given.
+      def clear(scope: nil, family: nil, tenant: nil)
+        unless family.nil? && tenant.nil?
+          raise ArgumentError,
+                "Parse::Cache::Redis#clear cannot honor family:/tenant: without a keyspace, " \
+                "and ignoring them here would fall through to FLUSHDB. " \
+                "Call backend.scoped(keyspace).clear(family:, tenant:) instead."
+        end
+
         if scope
           prefix = validate_scope!(scope)
           delete_keys_matching!("#{prefix}:*")
@@ -222,6 +476,24 @@ module Parse
         self
       end
 
+      # Delete every key matching a glob pattern. Exposed so the caching
+      # middleware can evict all auth variants of one resource on write, which
+      # it cannot do by naming keys: it has no way to enumerate the entries
+      # belonging to sessions this process has never seen.
+      #
+      # This backend never has a keyspace of its own (see {#scoped}), so a
+      # direct call here is always a no-op: there is no root_prefix to
+      # confine the pattern to. Callers with a keyspace should call
+      # `backend.scoped(keyspace).delete_matching(pattern)` instead, which
+      # confines the pattern to that view's own root_prefix before it ever
+      # reaches Redis.
+      #
+      # @param pattern [String] a Redis glob pattern.
+      # @return [Integer] number of keys removed. Always 0 on this backend.
+      def delete_matching(pattern)
+        0
+      end
+
       # Issue `FLUSHDB` on the backing Redis DB, regardless of whether a
       # namespace is configured. Evicts every key on the selected DB,
       # including unrelated tenants — use only for ops tooling that
@@ -240,6 +512,115 @@ module Parse
 
       private
 
+      # Redis-rb-shaped decorator used only by {#verify_upstream_isolation!}.
+      # Wraps the raw scan-capable client and keeps only Parse-Server-shaped
+      # role keys in each SCAN batch before
+      # `UpstreamRoles#shares_database_with?` ever sees it. That is what lets
+      # the isolation probe use a broad, app-id-less `"*"` pattern (catching
+      # ANY app's role cache key without having to know its app id) while the
+      # same glob would otherwise also match this SDK's own role-plane keys
+      # (`parse-stack:<version>:<scope>:<ns>:role:<userId>`), making the probe
+      # report "shared" as soon as the role plane held anything, on a database
+      # that is in fact isolated.
+      class ExcludeOwnKeysScanner
+        # Parse Server writes exactly `<appId>:role:<userId>`: three
+        # colon-separated segments, with `role` in the middle and neither
+        # outer segment containing a colon.
+        #
+        # This keeps only keys of that shape, rather than rejecting keys that
+        # look like ours. The difference matters because the two are not
+        # complements. Rejecting anything under `parse-stack:` drops a genuine
+        # upstream key when the Parse application is itself named
+        # `parse-stack`, since `parse-stack:role:U1` starts with that prefix,
+        # and the probe then reports a shared database as isolated: the exact
+        # false negative this scanner was added to prevent, just reachable
+        # through an app id instead of through a glob.
+        #
+        # Narrowing the rejection to `parse-stack:v1:` would fix that one case
+        # and break another. `v1` is {Parse::Cache::Keyspace::VERSION}, but the
+        # version is a constructor parameter, so a keyspace built with any
+        # other value would no longer be excluded and its role-plane keys would
+        # be counted as Parse Server's. Matching the upstream shape depends on
+        # nothing this SDK can reconfigure.
+        #
+        # Our own role-plane keys are
+        # `parse-stack:<version>:<scope>:<namespace>:role:<userId>`, six
+        # segments, so they can never satisfy the anchored three-segment
+        # pattern no matter how the keyspace is configured.
+        UPSTREAM_ROLE_KEY = /\A[^:]+:role:[^:]+\z/.freeze
+        private_constant :UPSTREAM_ROLE_KEY
+
+        def initialize(client)
+          @client = client
+        end
+
+        def scan(cursor, match:, count: 100)
+          cursor, keys = @client.scan(cursor, match: match, count: count)
+          [cursor, keys.select { |k| UPSTREAM_ROLE_KEY.match?(k.to_s) }]
+        end
+      end
+
+      private_constant :ExcludeOwnKeysScanner
+
+      def upstream_client
+        @upstream_client ||= begin
+            require "redis"
+            ::Redis.new(url: @parse_cache_url)
+          end
+      end
+
+      # Write a random key to OUR database and ask the upstream connection to
+      # read it back. This is the only direction that can establish isolation:
+      # a key that just appeared on our database and is not visible through
+      # the other connection proves the two are not the same database.
+      #
+      # The value is random too, so a stale key from a previous run cannot be
+      # mistaken for this run's sentinel.
+      #
+      # An earlier version of this check did the round-trip and treated a nil
+      # read as isolated, full stop. That is wrong under the restricted
+      # credential this SDK documents (`~<appId>:role:* ... +get +pttl`),
+      # where reading anything else raises NOPERM. redis-rb surfaces that as
+      # a `CommandError`, which is distinguishable from a nil, so the two are
+      # kept apart here instead of both meaning "isolated".
+      #
+      # @return [:shared, :isolated, :unknown]
+      def sentinel_probe
+        token = SecureRandom.hex(16)
+        key = "#{Keyspace::ROOT}:probe:#{token}"
+        begin
+          # Raw client, not Moneta: the upstream read is a plain GET and must
+          # see the same bytes we wrote, unmediated by a key/value serializer.
+          @pool.pool.with { |store| backend_client(store).set(key, token, ex: SENTINEL_TTL) }
+        rescue StandardError
+          # Cannot write, so cannot establish anything.
+          return :unknown
+        end
+
+        begin
+          seen = upstream_client.get(key)
+          return :shared if seen == token
+          # A non-nil value that is not our token means something else owns
+          # this key, which should be impossible. Do not call that isolated.
+          return :unknown unless seen.nil?
+          :isolated
+        rescue StandardError
+          # NOPERM, a transport failure, a Cluster CROSSSLOT: all say nothing
+          # about which database the key lives on.
+          :unknown
+        ensure
+          begin
+            @pool.pool.with { |store| backend_client(store).del(key) }
+          rescue StandardError
+            # The TTL collects it.
+          end
+        end
+      end
+
+      # Seconds the probe key lives if the explicit delete does not land.
+      SENTINEL_TTL = 10
+      private_constant :SENTINEL_TTL
+
       # Serialize a cache value to a JSON String before handing it to Moneta
       # (which stores it raw, since the value serializer is disabled — see the
       # constructor). JSON is used instead of Marshal so the read side never
@@ -267,18 +648,52 @@ module Parse
       end
 
       def delete_keys_matching!(pattern)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        deleted = 0
         @pool.pool.with do |store|
           redis = backend_client(store)
-          # SCAN-DEL loop. `count:` is a hint to the server; the actual
+          # SCAN-UNLINK loop. `count:` is a hint to the server; the actual
           # batch size returned varies. Loop until the cursor wraps back
           # to "0".
+          #
+          # UNLINK reclaims memory on a background thread, so a large scoped
+          # eviction does not stall the server the way DEL would. It has been
+          # available since Redis 4.0; fall back to DEL on anything older or on
+          # a client that does not expose it.
+          unlink = redis.respond_to?(:unlink)
           cursor = "0"
           loop do
             cursor, keys = redis.scan(cursor, match: pattern, count: 1000)
-            redis.del(*keys) unless keys.empty?
+            unless keys.empty?
+              removed = unlink ? redis.unlink(*keys) : redis.del(*keys)
+              # Keys can disappear between SCAN and UNLINK/DEL. Redis reports
+              # how many it actually removed; using the scanned batch size
+              # overstates both this return value and parse.cache.evict.
+              deleted += removed.to_i
+            end
             break if cursor == "0"
           end
         end
+        instrument_eviction(pattern, deleted, started)
+        deleted
+      end
+
+      # Emit a structured event for a scoped eviction so operators can see how
+      # much a clear actually removed and how long it took. The pattern is a
+      # key prefix, so it is digested rather than logged: a response-cache
+      # pattern embeds a URL digest and a tenant, and the identity family's
+      # keys are derived from session tokens.
+      def instrument_eviction(pattern, deleted, started)
+        return unless defined?(ActiveSupport::Notifications)
+        ActiveSupport::Notifications.instrument(
+          "parse.cache.evict",
+          pattern_digest: Digest::SHA256.hexdigest(pattern.to_s)[0, 16],
+          deleted: deleted,
+          duration_ms: ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round(2),
+        )
+      rescue StandardError
+        # Instrumentation must never turn a successful eviction into a failure.
+        nil
       end
 
       def backend_client(moneta_store)