parse-stack-next 4.5.0 → 5.0.0

data/lib/parse/atlas_search.rb

@@ -243,6 +243,18 @@ module Parse
       # @option options [Hash] :sort sort specification (default: by relevance score)
       # @option options [Boolean] :raw return raw MongoDB documents (default: false)
       # @option options [String] :class_name Parse class name for object conversion
+      # @option options [String] :session_token Parse session token used to scope
+      #   ACL/CLP enforcement to the owning user.
+      # @option options [Boolean] :master run with master-key semantics and bypass
+      #   ACL/CLP enforcement (default: false).
+      # @option options [Parse::User, Parse::Pointer] :acl_user act as the given
+      #   user pointer for ACL evaluation (no REST equivalent; mongo-direct only).
+      # @option options [String, Parse::Role] :acl_role act as the given role for
+      #   ACL evaluation (no REST equivalent; mongo-direct only).
+      # @option options [Symbol] :read_preference MongoDB read preference applied
+      #   to the underlying collection (e.g. +:secondary+).
+      # @option options [Integer] :max_time_ms maximum server-side execution time
+      #   in milliseconds for the aggregate command.
       #
       # @return [Parse::AtlasSearch::SearchResult] search result object
       #
@@ -393,6 +405,19 @@ module Parse
       # @option options [Integer] :limit max suggestions to return (default: 10)
       # @option options [Hash] :filter additional constraints
       # @option options [Boolean] :raw return raw documents (default: false)
+      # @option options [String] :class_name Parse class name for object conversion.
+      # @option options [String] :session_token Parse session token used to scope
+      #   ACL/CLP enforcement to the owning user.
+      # @option options [Boolean] :master run with master-key semantics and bypass
+      #   ACL/CLP enforcement (default: false).
+      # @option options [Parse::User, Parse::Pointer] :acl_user act as the given
+      #   user pointer for ACL evaluation (no REST equivalent; mongo-direct only).
+      # @option options [String, Parse::Role] :acl_role act as the given role for
+      #   ACL evaluation (no REST equivalent; mongo-direct only).
+      # @option options [Symbol] :read_preference MongoDB read preference applied
+      #   to the underlying collection (e.g. +:secondary+).
+      # @option options [Integer] :max_time_ms maximum server-side execution time
+      #   in milliseconds for the aggregate command.
       #
       # @return [Parse::AtlasSearch::AutocompleteResult] autocomplete result
       #
@@ -509,7 +534,14 @@ module Parse
       # @param collection_name [String] the Parse collection name
       # @param query [String, nil] the search query text (nil for match-all)
       # @param facets [Hash] facet definitions
-      # @param options [Hash] search options (same as #search)
+      # @param options [Hash] search options (same as {#search}; see that
+      #   method for the full list of accepted +@option+ entries including
+      #   +:index+, +:fields+, +:fuzzy+, +:limit+, +:filter+, +:read_preference+,
+      #   +:max_time_ms+, and the scoping kwargs +:master+, +:session_token+,
+      #   +:acl_user+, +:acl_role+). Note: scoped identity kwargs require
+      #   +master: true+ to be passed explicitly — $searchMeta bucket counts
+      #   cannot be filtered by ACL after the fact, so the method refuses
+      #   to silently downgrade.
       #
       # @return [Parse::AtlasSearch::FacetedResult] faceted result
       #
@@ -944,19 +976,15 @@ module Parse
           objects = parse_results.each_with_index.map do |doc, idx|
             obj = build_parse_object(doc, class_name)
             raw_doc = raw_results[idx]
-            # Attach search metadata from original raw document (scores are stripped during conversion)
+            # Attach search metadata from original raw document. `search_score`
+            # and `search_highlights` readers are defined once on Parse::Object
+            # (see lib/parse/model/object.rb) so we only set the ivars here —
+            # no per-row singleton method definition.
             if obj && raw_doc["_score"]
               obj.instance_variable_set(:@_search_score, raw_doc["_score"])
-              # Define accessor if not already defined
-              unless obj.respond_to?(:search_score)
-                obj.define_singleton_method(:search_score) { @_search_score }
-              end
             end
             if obj && raw_doc["_highlights"]
               obj.instance_variable_set(:@_search_highlights, raw_doc["_highlights"])
-              unless obj.respond_to?(:search_highlights)
-                obj.define_singleton_method(:search_highlights) { @_search_highlights }
-              end
             end
             obj
           end.compact

data/lib/parse/cache/pool.rb

@@ -0,0 +1,73 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "connection_pool"
+require "moneta"
+
+module Parse
+  module Cache
+    # Moneta-compatible facade over a ConnectionPool of Moneta stores. The
+    # Faraday caching middleware only calls four methods on its store
+    # (`[]`, `key?`, `delete`, `store`); this class checks out a backend
+    # for each of them via `@pool.with`.
+    #
+    # Why a pool: a single Moneta-Redis store wraps one Redis connection.
+    # Under a multi-threaded Puma worker (or any concurrent caller), threads
+    # serialize on that connection's mutex. A pool of N stores lets up to N
+    # cache calls run in parallel.
+    #
+    # Note that a cache hit costs two checkouts (`key?` then `[]`). That is
+    # accepted to keep behavior identical to a plain Moneta store; callers
+    # should size the pool with that in mind (default 5, which matches the
+    # Puma default thread count).
+    class Pool
+      # The wrapped ConnectionPool instance.
+      attr_reader :pool
+
+      # @param size [Integer] number of pooled backend stores.
+      # @param timeout [Numeric] seconds to wait for a checkout before
+      #   raising `ConnectionPool::TimeoutError`.
+      # @yield Block invoked to build a single backend store. Must return a
+      #   Moneta store responding to `[]`, `key?`, `delete`, `store`.
+      def initialize(size: 5, timeout: 5, &block)
+        raise ArgumentError, "Parse::Cache::Pool requires a block that builds a Moneta store" unless block_given?
+        @pool = ConnectionPool.new(size: size, timeout: timeout, &block)
+        @closed = false
+      end
+
+      def [](key)
+        @pool.with { |store| store[key] }
+      end
+
+      def key?(key)
+        @pool.with { |store| store.key?(key) }
+      end
+
+      def delete(key)
+        @pool.with { |store| store.delete(key) }
+      end
+
+      def store(key, value, options = {})
+        @pool.with { |store| store.store(key, value, options) }
+      end
+
+      # Clear the underlying backend. Pooled Moneta stores all point at the
+      # same Redis DB, so a single checkout suffices — issuing `clear` on
+      # one connection flushes the DB for every connection.
+      def clear
+        @pool.with { |store| store.clear if store.respond_to?(:clear) }
+        self
+      end
+
+      # Close all pooled backends. Safe to call multiple times — repeat
+      # calls are no-ops. `ConnectionPool#shutdown` raises
+      # `ConnectionPool::PoolShuttingDownError` on a second invocation,
+      # so we gate it with a `@closed` flag.
+      def close
+        return if @closed
+        @closed = true
+        @pool.shutdown { |store| store.close if store.respond_to?(:close) }
+      end
+    end
+  end
+end

data/lib/parse/cache/redis.rb

@@ -0,0 +1,190 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "moneta"
+require_relative "pool"
+
+module Parse
+  module Cache
+    # Ergonomic Redis cache builder for Parse Stack. Composes a
+    # ConnectionPool of Moneta-Redis stores and carries an optional
+    # `namespace` that `Parse::Client` will pick up automatically — there
+    # is no need to also pass `cache_namespace:` to `Parse.setup` when
+    # using this wrapper.
+    #
+    # Usage:
+    #   Parse.setup(
+    #     cache: Parse::Cache::Redis.new(
+    #       url: "redis://localhost:6379/0",
+    #       namespace: "app_x",
+    #       pool_size: 10,
+    #     ),
+    #     expires: 60,
+    #     ...
+    #   )
+    #
+    # The instance is a Moneta-compatible store (it delegates the four
+    # methods the Faraday caching middleware uses — `[]`, `key?`,
+    # `delete`, `store` — to a pooled backend), so it can be passed
+    # directly to `Parse.setup(cache:)` / `Parse::Client.new(cache:)`.
+    class Redis
+      # @return [String, nil] cache key namespace prefix (or nil if not set).
+      attr_reader :namespace
+
+      # @return [Integer] pool size.
+      attr_reader :pool_size
+
+      # @return [String] Redis connection URL.
+      attr_reader :url
+
+      # @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
+      #   namespace is automatically forwarded to the caching middleware
+      #   as `cache_namespace:`.
+      # @param pool_size [Integer] number of pooled Moneta-Redis stores.
+      #   Defaults to 5 (the Puma default thread count).
+      #
+      #   **Sizing math (per Faraday request):**
+      #   - cache hit: `key?` + `[]` = **2 checkouts**
+      #   - GET miss + successful store: `key?` + 3 variant deletes
+      #     (anonymous + master-key sibling + final key) + 1 `store` in
+      #     `on_complete` = **up to 5 checkouts**
+      #   - non-GET write (POST/PUT/DELETE): 3 variant deletes =
+      #     **3 checkouts**
+      #
+      #   The worst case (5) is on the write-through-after-miss path, not
+      #   the hit path. Rule of thumb: start at `pool_size = RAILS_MAX_THREADS`,
+      #   then bump it up if you observe `ConnectionPool::TimeoutError` in
+      #   `parse.cache.error` notifications (the middleware swallows that
+      #   error into a passthrough request rather than raising to the caller).
+      # @param pool_timeout [Numeric] seconds to wait for a backend
+      #   checkout before raising `ConnectionPool::TimeoutError`. Defaults
+      #   to 5s. The caching middleware catches that error and falls back
+      #   to a passthrough request rather than raising to the caller.
+      # @param moneta_options [Hash] extra options passed through to
+      #   `Moneta.new(:Redis, ...)` (e.g. `:db`, `:connect_timeout`).
+      #   `expires: true` is set automatically so per-key TTLs supplied
+      #   by the caching middleware (the `:expires` Faraday option) are
+      #   honored by Redis. Pass `expires: false` here to opt out — but
+      #   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)
+        @url = url
+        @namespace = normalize_namespace(namespace)
+        @pool_size = pool_size
+        @pool_timeout = pool_timeout
+        # Default expires: true so per-call `expires:` (the TTL the
+        # Faraday caching middleware passes on store) is honored. The
+        # Moneta-Redis adapter ignores per-call expires unless the
+        # store was constructed with this flag. Without it, cached
+        # session-scoped REST responses outlive their token's
+        # validity. Callers can still pass `expires: false` to opt out.
+        merged_options = { expires: true }.merge(moneta_options)
+        @moneta_options = merged_options
+        @closed = false
+        @pool = Pool.new(size: pool_size, timeout: pool_timeout) do
+          Moneta.new(:Redis, { url: url }.merge(merged_options))
+        end
+      end
+
+      def [](key)
+        @pool[key]
+      end
+
+      def key?(key)
+        @pool.key?(key)
+      end
+
+      def delete(key)
+        @pool.delete(key)
+      end
+
+      def store(key, value, options = {})
+        @pool.store(key, value, options)
+      end
+
+      # Clear cached entries belonging to this wrapper. Required for
+      # `Parse::Client#clear_cache!` compatibility.
+      #
+      # **Namespace-scoped when a namespace is set:** the wrapper walks
+      # `<namespace>:*` via Redis SCAN and DELs the matching keys,
+      # leaving other tenants on the same DB untouched. When no
+      # namespace is configured the wrapper falls back to `FLUSHDB` on
+      # the backing DB — same blast radius as previous versions, but
+      # only for unnamespaced deployments. To opt into the wide
+      # FLUSHDB explicitly (e.g. ops tooling), call {#flush_db!}.
+      def clear
+        if @namespace
+          delete_keys_matching!("#{@namespace}:*")
+        else
+          @pool.clear
+        end
+        self
+      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
+      # owns the whole DB.
+      def flush_db!
+        @pool.clear
+        self
+      end
+
+      # Close all pooled connections. Safe to call multiple times.
+      def close
+        return if @closed
+        @closed = true
+        @pool.close
+      end
+
+      private
+
+      def delete_keys_matching!(pattern)
+        @pool.pool.with do |store|
+          redis = backend_client(store)
+          # SCAN-DEL loop. `count:` is a hint to the server; the actual
+          # batch size returned varies. Loop until the cursor wraps back
+          # to "0".
+          cursor = "0"
+          loop do
+            cursor, keys = redis.scan(cursor, match: pattern, count: 1000)
+            redis.del(*keys) unless keys.empty?
+            break if cursor == "0"
+          end
+        end
+      end
+
+      def backend_client(moneta_store)
+        # Walk down the Moneta proxy chain (Expires → Adapter → redis-rb)
+        # until we reach an object that quacks like the redis-rb client
+        # (i.e. responds to #scan). Moneta wraps the actual adapter when
+        # `expires: true` is passed, and the adapter then exposes the
+        # underlying redis-rb client via `#backend` (modern releases) or
+        # the `@backend` ivar (older releases).
+        node = moneta_store
+        12.times do
+          return node if node.respond_to?(:scan)
+          if node.respond_to?(:backend)
+            node = node.backend
+          elsif node.instance_variable_defined?(:@backend)
+            node = node.instance_variable_get(:@backend)
+          elsif node.instance_variable_defined?(:@adapter)
+            node = node.instance_variable_get(:@adapter)
+          else
+            break
+          end
+          break if node.nil?
+        end
+        node
+      end
+
+      def normalize_namespace(ns)
+        s = ns.to_s.chomp(":")
+        s.empty? ? nil : s
+      end
+    end
+  end
+end

data/lib/parse/client/body_builder.rb

@@ -48,6 +48,26 @@ module Parse
       SENSITIVE_FIELDS_SET = SENSITIVE_FIELDS.map(&:downcase).to_set.freeze
       # Placeholder used in place of redacted values.
       REDACTED_PLACEHOLDER = "[FILTERED]"
+      # Minimum length at which a numeric-only Array in a logged JSON
+      # body is compacted to a single placeholder string instead of
+      # printed verbatim. Two concerns drive this:
+      #
+      # 1. **Noise.** A 1536-float OpenAI embedding inlines as ~25 KB of
+      #    JSON per logged row. Aggregation pipelines with
+      #    `$vectorSearch.queryVector` and any save/fetch carrying a
+      #    `:vector` field would otherwise drown operator logs.
+      # 2. **Sensitivity.** Embeddings are reversible-by-similarity:
+      #    an attacker who scrapes operator logs can reconstruct
+      #    high-level features of the source text (topic, sentiment,
+      #    sometimes near-verbatim phrases for short inputs) by
+      #    nearest-neighbor lookup against a public model.
+      #
+      # Threshold rationale: 32 is well below every common embedding
+      # width (BGE-small 384, Cohere 1024, OpenAI small 1536, OpenAI
+      # large 3072) and well above any normal Parse Array property
+      # (tags, role lists, etc.). Numeric-only check additionally
+      # protects normal long arrays of strings/objects.
+      LOG_VECTOR_COMPACT_THRESHOLD = 32
       # Request headers that must never be printed verbatim in debug logs.
       # Matched case-insensitively against Faraday header keys.
       REDACTED_HEADERS = [
@@ -57,6 +77,31 @@ module Parse
         "X-Parse-JavaScript-Key",
         "Authorization",
         "Cookie",
+        # Embedding-provider credentials (Parse::Embeddings::OpenAI and
+        # forthcoming Cohere/Voyage adapters). These never touch Parse
+        # Server itself, but they share the same Faraday log path when a
+        # caller mounts the embeddings connection through Parse logging.
+        # OpenAI's official auth header is `Authorization: Bearer …`
+        # (already covered above); Organization/Project are listed here
+        # since they're account-identifying metadata operators may not
+        # want to publish. `X-Api-Key` and `Anthropic-Api-Key` are
+        # reserved for forthcoming non-OpenAI providers.
+        "X-Api-Key",
+        "OpenAI-Organization",
+        "OpenAI-Project",
+        "Anthropic-Api-Key",
+        # Cohere, Voyage, Jina, and DashScope (Qwen) use Bearer auth
+        # (covered by "Authorization" above), but some operators front
+        # them with a proxy that rewrites to a vendor-specific header.
+        # These are listed defensively so a future header-form switch
+        # doesn't silently leak keys into Faraday logs. `Api-Key` is the
+        # bare form some vendor SDKs and proxies use; covered for parity.
+        "Cohere-Api-Key",
+        "Voyage-Api-Key",
+        "Jina-Api-Key",
+        "Api-Key",
+        "X-DashScope-Api-Key",
+        "DashScope-Api-Key",
       ].map(&:downcase).freeze
 
       class << self
@@ -91,6 +136,7 @@ module Parse
         after_structural = s
         if (parsed = try_parse_json(s))
           scrubbed = scrub_sensitive!(parsed)
+          compact_vectors!(scrubbed)
           begin
             after_structural = scrubbed.to_json
           rescue StandardError
@@ -160,12 +206,60 @@ module Parse
         node
       end
 
+      # @!visibility private
+      # Recursively walk a parsed JSON structure replacing any
+      # numeric-only Array of length >= +LOG_VECTOR_COMPACT_THRESHOLD+
+      # with a compact placeholder string ("<vector dims=N>"). Mutates
+      # Hashes/Arrays in place; returns the node for chaining. Distinct
+      # pass from {scrub_sensitive!} because the criterion is shape
+      # (numeric array width), not key name.
+      #
+      # The walker does NOT descend into the replaced array — once a
+      # node is recognised as a vector its inner Numerics aren't of
+      # interest. Nested vectors (Array<Array<Numeric>>, e.g. a batched
+      # embedding response in a logged HTTP body) are caught at the
+      # inner array level on the next recursion.
+      def self.compact_vectors!(node)
+        case node
+        when Hash
+          node.each do |key, value|
+            if vector_shape?(value)
+              node[key] = "<vector dims=#{value.length}>"
+            elsif value.is_a?(Hash) || value.is_a?(Array)
+              compact_vectors!(value)
+            end
+          end
+        when Array
+          node.each_with_index do |item, i|
+            if vector_shape?(item)
+              node[i] = "<vector dims=#{item.length}>"
+            elsif item.is_a?(Hash) || item.is_a?(Array)
+              compact_vectors!(item)
+            end
+          end
+        end
+        node
+      end
+
+      # @!visibility private
+      # An Array is "vector-shaped" if it meets the compaction threshold
+      # AND every element is Numeric. The numeric check prevents long
+      # tag arrays / role lists / mixed-type arrays from being mangled.
+      # Boolean is not Numeric in Ruby, so an array of booleans (rare
+      # but possible) is left alone — also fine.
+      def self.vector_shape?(val)
+        return false unless val.is_a?(Array)
+        return false if val.length < LOG_VECTOR_COMPACT_THRESHOLD
+        val.all? { |x| x.is_a?(Numeric) }
+      end
+
       # @!visibility private
       # If +str+ parses as JSON (object or array), scrub structurally and
       # re-encode. Otherwise return the original string unchanged.
       def self.maybe_scrub_embedded_json(str)
         return str unless (inner = try_parse_json(str))
         scrub_sensitive!(inner)
+        compact_vectors!(inner)
         begin
           inner.to_json
         rescue StandardError

data/lib/parse/client/caching.rb

@@ -3,6 +3,7 @@
 
 require "faraday"
 require "moneta"
+require "connection_pool"
 require "digest"
 require_relative "protocol"
 
@@ -81,6 +82,14 @@ module Parse
         @opts = { expires: 0 }
         @opts.merge!(opts) if opts.is_a?(Hash)
         @expires = @opts[:expires]
+        # Optional cache key namespace so two Parse apps sharing one Redis don't
+        # collide (e.g. `mk:/classes/Song/abc` is the same path for both apps).
+        # When set, keys become `<namespace>:<existing-prefix>:<url>`. Empty
+        # string is treated as nil. Trailing `:` is stripped once so users can
+        # pass either `"app_x"` or `"app_x:"`.
+        ns = @opts[:namespace].to_s
+        ns = ns.chomp(":")
+        @namespace = ns.empty? ? nil : ns
 
         unless [:key?, :[], :delete, :store].all? { |method| @store.respond_to?(method) }
           raise ArgumentError, "Caching store object must a Moneta key/value store."
@@ -134,21 +143,36 @@ module Parse
           @cache_key = "mk:#{@cache_key}" # prefix for master key requests
         end
 
+        # Namespace outermost so a SCAN over `<namespace>:*` evicts a whole
+        # tenant/app cleanly without touching another app's entries.
+        @cache_key = "#{@namespace}:#{@cache_key}" if @namespace
+
+        url_path = url.path
+
         begin
           # Skip cache read if write_only mode is enabled
           if method == :get && @cache_key.present? && !@write_only && @store.key?(@cache_key)
-            puts("[Parse::Cache] Hit >> #{url}") if self.class.logging.present?
+            # Debug-log the URL **path only** — `url.to_s` would include the
+            # query string, which Parse encodes JSON `where=` into and may
+            # contain PII. Same redaction discipline as the AS::N payload.
+            puts("[Parse::Cache] Hit >> #{url_path}") if self.class.logging.present?
             response = Faraday::Response.new
             begin
               cache_data = @store[@cache_key] # previous cached response
             rescue => e
-              puts "[Parse::Cache] Error: #{e}"
+              # Log only the class name — some Moneta/Redis drivers echo the
+              # offending key in `e.message`, and our key contains a hashed
+              # session-token prefix that we treat as side-channel material.
+              puts "[Parse::Cache] Error: #{e.class.name}"
+              instrument_cache(:error, method: method, url_path: url_path, error: e.class.name)
               cache_data = nil
             end
 
             # check if the store was from a legacy parse-stack cache value which
             # is stored as Faraday::Env. T\he new system stores less content in a simple hash
             # for improved interoperability and access time.
+            body             = nil
+            response_headers = nil
             if cache_data.is_a?(Faraday::Env)
               body = cache_data.respond_to?(:body) ? cache_data.body : nil
               response_headers = cache_data.response_headers || {}
@@ -160,24 +184,43 @@ module Parse
             if cache_data.present? && body.present?
               response_headers[CACHE_RESPONSE_HEADER] = "true"
               response.finish({ status: 200, response_headers: response_headers, body: body })
+              instrument_cache(:hit, method: method, url_path: url_path)
               return response
             else
-              @store.delete @cache_key
+              delete_cache_variants(url)
+              instrument_cache(:miss, method: method, url_path: url_path, reason: :empty_payload)
             end
+          elsif method == :get && @cache_key.present? && !@write_only
+            # GET miss: opportunistically clear any sibling variants of the
+            # current namespace (anonymous `<url>` and master-key `mk:<url>`
+            # under the same namespace) so a stale variant from a prior
+            # request flavor doesn't linger until TTL.
+            #
+            # When @namespace is set we deliberately do NOT touch the bare
+            # un-namespaced `<url>` / `mk:<url>` keys — those could belong to
+            # another Parse app sharing the Redis DB, and cross-namespace
+            # eviction would be a blast-radius bug, not a fix. Operators
+            # upgrading an SDK that previously wrote un-namespaced keys
+            # should evict those once at upgrade time via SCAN.
+            delete_cache_variants(url)
+            instrument_cache(:miss, method: method, url_path: url_path)
+          elsif method == :get && @cache_key.present? && @write_only
+            delete_cache_variants(url)
+            instrument_cache(:miss, method: method, url_path: url_path, reason: :write_only)
           elsif @cache_key.present?
             #non GET requets should clear the cache for that same resource path.
             #ex. a POST to /1/classes/Artist/<objectId> should delete the cache for a GET
             # request for the same '/1/classes/Artist/<objectId>' where objectId are equivalent
-            @store.delete url.to_s # regular
-            @store.delete "mk:#{url.to_s}" # master key cache-key
-            @store.delete @cache_key # final key
+            delete_cache_variants(url)
+            instrument_cache(:delete, method: method, url_path: url_path)
           end
-        rescue ::TypeError, Errno::EINVAL, Redis::CannotConnectError, Redis::TimeoutError => e
+        rescue ::TypeError, Errno::EINVAL, Redis::CannotConnectError, Redis::TimeoutError, ConnectionPool::TimeoutError => e
           # if the cache store fails to connect, catch the exception but proceed
           # with the regular request, but turn off caching for this request. It is possible
           # that the cache connection resumes at a later point, so this is temporary.
           @enabled = false
-          puts "[Parse::Cache] Error: #{e}"
+          puts "[Parse::Cache] Error: #{e.class.name}"
+          instrument_cache(:error, method: method, url_path: url_path, error: e.class.name)
         end
 
         @app.call(env).on_complete do |response_env|
@@ -186,18 +229,75 @@ module Parse
 
           if @enabled && method == :get && CACHEABLE_HTTP_CODES.include?(response_env.status) &&
              response_env.body.present? && response_env.response_headers[CONTENT_LENGTH_KEY].to_i.between?(20, 1_250_000)
+            store_start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
             begin
               @store.store(@cache_key,
                            { headers: response_env.response_headers, body: response_env.body },
                            expires: @expires)
+              duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - store_start) * 1000.0).round(3)
+              instrument_cache(:store, method: method, url_path: url_path, duration_ms: duration_ms)
             rescue => e
-              puts "[Parse::Cache] Store Error: #{e}"
+              puts "[Parse::Cache] Store Error: #{e.class.name}"
+              instrument_cache(:error, method: method, url_path: url_path, error: e.class.name)
             end
           end # if
           # do something with the response
           # response_env[:response_headers].merge!(...)
         end
       end
+
+      private
+
+      # Emit an ActiveSupport::Notifications event under the `parse.cache.*`
+      # namespace.
+      #
+      # **Payload shape (stable):** `{ event:, namespace:, method:, url_path:,
+      # [reason:], [duration_ms:], [error:] }`.
+      #
+      # **Security invariants:**
+      # - The cache key is NEVER emitted. The key contains a hashed
+      #   session-token prefix that would be a side-channel for "this user
+      #   has data at this URL" enumeration.
+      # - `url_path` is `URI#path` only — query strings are stripped because
+      #   Parse encodes query JSON there (potentially long or PII-bearing).
+      # - `error` is `Exception#class.name` only — never the exception
+      #   message or backtrace.
+      # - `namespace` is whatever the SDK consumer configured at setup. Treat
+      #   subscribers as you would your application log sink: they observe
+      #   the namespace, the HTTP method, and the URL path of every cached
+      #   GET / invalidating write.
+      #
+      # **Subscriber discipline:** ActiveSupport::Notifications runs
+      # subscribers **synchronously on the Faraday request thread**. A
+      # blocking subscriber (e.g. synchronous I/O to a slow sink) blocks
+      # every cached request for the duration of its work, and an exception
+      # raised inside a subscriber will surface as a request failure. Keep
+      # subscribers cheap — counter increments, in-memory accumulators, or
+      # non-blocking sinks like StatsD-over-UDP.
+      # @!visibility private
+      def instrument_cache(event, **extra)
+        return unless defined?(ActiveSupport::Notifications)
+        payload = { event: event, namespace: @namespace }.merge!(extra)
+        ActiveSupport::Notifications.instrument("parse.cache.#{event}", payload)
+      end
+
+      # Delete the canonical cache_key plus its legacy un-namespaced and
+      # master-key-prefixed variants. Called on both GET misses (defensive
+      # cleanup of stale pre-namespace entries) and non-GET writes (cache
+      # invalidation for the resource).
+      # @!visibility private
+      def delete_cache_variants(url)
+        if @namespace
+          # Namespaced: only delete our app's variants so a write through
+          # client A doesn't blow away client B's cache when both share Redis.
+          @store.delete "#{@namespace}:#{url.to_s}"
+          @store.delete "#{@namespace}:mk:#{url.to_s}"
+        else
+          @store.delete url.to_s # regular
+          @store.delete "mk:#{url.to_s}" # master key cache-key
+        end
+        @store.delete @cache_key # final key
+      end
     end #Caching
   end #Middleware
 end