parse-stack-next 4.5.0

data/lib/parse/client/caching.rb

@@ -0,0 +1,203 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "faraday"
+require "moneta"
+require "digest"
+require_relative "protocol"
+
+module Parse
+  module Middleware
+    # This is a caching middleware for Parse queries using Moneta. The caching
+    # middleware will cache all GET requests made to the Parse REST API as long
+    # as the API responds with a successful non-empty result payload.
+    #
+    # Whenever an object is created or updated, the corresponding entry in the cache
+    # when fetching the particular record (using the specific non-Query based API)
+    # will be cleared.
+    class Caching < Faraday::Middleware
+      include Parse::Protocol
+
+      # List of status codes that can be cached:
+      # * 200 - 'OK'
+      # * 203 - 'Non-Authoritative Information'
+      # * 300 - 'Multiple Choices'
+      # * 301 - 'Moved Permanently'
+      # * 302 - 'Found'
+      # * 404 - 'Not Found' - removed
+      # * 410 - 'Gone' - removed
+      CACHEABLE_HTTP_CODES = [200, 203, 300, 301, 302].freeze
+      # Cache control header
+      CACHE_CONTROL = "Cache-Control"
+      # Request env key for the content length
+      CONTENT_LENGTH_KEY = "content-length"
+      # Header in response that is sent if this is a cached result
+      CACHE_RESPONSE_HEADER = "X-Cache-Response"
+      # Header in request to set caching information for the middleware.
+      CACHE_EXPIRES_DURATION = "X-Parse-Stack-Cache-Expires"
+      # Header in request to enable write-only cache mode (skip read, still write)
+      CACHE_WRITE_ONLY = "X-Parse-Stack-Cache-Write-Only"
+
+      class << self
+        # @!attribute enabled
+        # @return [Boolean] whether the caching middleware should be enabled.
+        attr_writer :enabled
+
+        # @!attribute logging
+        # @return [Boolean] whether the logging should be enabled.
+        attr_accessor :logging
+
+        def enabled
+          @enabled = true if @enabled.nil?
+          @enabled
+        end
+
+        # @return [Boolean] whether caching is enabled.
+        def caching?
+          @enabled
+        end
+      end
+
+      # @!attribute [rw] store
+      # The internal moneta cache store instance.
+      # @return [Moneta::Transformer,Moneta::Expires]
+      attr_accessor :store
+
+      # @!attribute [rw] expires
+      # The expiration time in seconds for this particular request.
+      # @return [Integer]
+      attr_accessor :expires
+
+      # Creates a new caching middleware.
+      # @param adapter [Faraday::Adapter] An instance of the Faraday adapter
+      #  used for the connection. Defaults Faraday::Adapter::NetHttp.
+      # @param store [Moneta] An instance of the Moneta cache store to use.
+      # @param opts [Hash] additional options.
+      # @option opts [Integer] :expires the default expiration for a cache entry.
+      # @raise ArgumentError, if `store` is not a Moneta::Transformer or Moneta::Expires instance.
+      def initialize(adapter, store, opts = {})
+        super(adapter)
+        @store = store
+        @opts = { expires: 0 }
+        @opts.merge!(opts) if opts.is_a?(Hash)
+        @expires = @opts[:expires]
+
+        unless [:key?, :[], :delete, :store].all? { |method| @store.respond_to?(method) }
+          raise ArgumentError, "Caching store object must a Moneta key/value store."
+        end
+      end
+
+      # Thread-safety
+      # @!visibility private
+      def call(env)
+        dup.call!(env)
+      end
+
+      # @!visibility private
+      def call!(env)
+        @request_headers = env[:request_headers]
+
+        # get default caching state
+        @enabled = self.class.enabled
+        # disable cache for this request if "no-cache" was passed
+        if @request_headers[CACHE_CONTROL] == "no-cache"
+          @enabled = false
+        end
+
+        # Check for write-only mode (skip cache read, still write to cache)
+        # This is useful for fetch!/reload! which want fresh data but should update cache
+        @write_only = @request_headers[CACHE_WRITE_ONLY] == "true"
+
+        # get the expires information from header (per-request) or instance default
+        if @request_headers[CACHE_EXPIRES_DURATION].to_i > 0
+          @expires = @request_headers[CACHE_EXPIRES_DURATION].to_i
+        end
+
+        # cleanup
+        @request_headers.delete(CACHE_CONTROL)
+        @request_headers.delete(CACHE_EXPIRES_DURATION)
+        @request_headers.delete(CACHE_WRITE_ONLY)
+
+        # if caching is enabled and we have a valid cache duration, use cache
+        # otherwise work as a passthrough.
+        return @app.call(env) unless @enabled && @store.present? && @expires > 0
+
+        url = env.url
+        method = env.method
+        @cache_key = url.to_s
+
+        if @request_headers.key?(SESSION_TOKEN)
+          @session_token = @request_headers[SESSION_TOKEN]
+          hashed_token = Digest::SHA256.hexdigest(@session_token.to_s)[0, 32]
+          @cache_key = "#{hashed_token}:#{@cache_key}" # prefix with hashed token
+        elsif @request_headers.key?(MASTER_KEY)
+          @cache_key = "mk:#{@cache_key}" # prefix for master key requests
+        end
+
+        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?
+            response = Faraday::Response.new
+            begin
+              cache_data = @store[@cache_key] # previous cached response
+            rescue => e
+              puts "[Parse::Cache] Error: #{e}"
+              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.
+            if cache_data.is_a?(Faraday::Env)
+              body = cache_data.respond_to?(:body) ? cache_data.body : nil
+              response_headers = cache_data.response_headers || {}
+            elsif cache_data.is_a?(Hash)
+              body = cache_data[:body]
+              response_headers = cache_data[:headers] || {}
+            end
+
+            if cache_data.present? && body.present?
+              response_headers[CACHE_RESPONSE_HEADER] = "true"
+              response.finish({ status: 200, response_headers: response_headers, body: body })
+              return response
+            else
+              @store.delete @cache_key
+            end
+          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
+          end
+        rescue ::TypeError, Errno::EINVAL, Redis::CannotConnectError, Redis::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}"
+        end
+
+        @app.call(env).on_complete do |response_env|
+          # Only cache GET requests with valid HTTP status codes whose content-length
+          # is between 20 bytes and 1MB. Otherwise they could be errors, successes and empty result sets.
+
+          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)
+            begin
+              @store.store(@cache_key,
+                           { headers: response_env.response_headers, body: response_env.body },
+                           expires: @expires)
+            rescue => e
+              puts "[Parse::Cache] Store Error: #{e}"
+            end
+          end # if
+          # do something with the response
+          # response_env[:response_headers].merge!(...)
+        end
+      end
+    end #Caching
+  end #Middleware
+end

data/lib/parse/client/logging.rb

@@ -0,0 +1,293 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "faraday"
+require "logger"
+
+module Parse
+  module Middleware
+    # Faraday middleware that logs Parse API requests and responses.
+    #
+    # This middleware provides detailed logging of HTTP requests and responses
+    # with configurable log levels and optional body truncation for large payloads.
+    #
+    # @example Basic setup
+    #   Parse.logging = true
+    #
+    # @example Detailed configuration
+    #   Parse.configure do |config|
+    #     config.logging = true
+    #     config.log_level = :debug
+    #     config.logger = Rails.logger  # or Logger.new(STDOUT)
+    #   end
+    #
+    # Log levels:
+    # - :info  - Logs request method, URL, status, and timing
+    # - :debug - Also logs headers and truncated body content
+    # - :warn  - Only logs errors and warnings
+    #
+    class Logging < Faraday::Middleware
+      # Maximum length of body content to log before truncation
+      MAX_BODY_LENGTH = 500
+
+      class << self
+        # @return [Boolean] Whether logging is enabled
+        attr_accessor :enabled
+
+        # @return [Symbol] The log level (:info, :debug, :warn)
+        attr_accessor :log_level
+
+        # @return [Logger] The logger instance to use
+        attr_accessor :logger
+
+        # @return [Integer] Maximum body length to log (defaults to MAX_BODY_LENGTH)
+        attr_accessor :max_body_length
+
+        # Default logger instance
+        # @return [Logger]
+        def default_logger
+          @default_logger ||= begin
+              l = Logger.new(STDOUT)
+              l.progname = "Parse"
+              l.formatter = proc do |severity, datetime, progname, msg|
+                "[#{progname}] #{msg}\n"
+              end
+              l
+            end
+        end
+
+        # Get the configured logger or default
+        # @return [Logger]
+        def current_logger
+          logger || default_logger
+        end
+
+        # Get the current log level (defaults to :info)
+        # @return [Symbol]
+        def current_log_level
+          log_level || :info
+        end
+
+        # Get the max body length (defaults to MAX_BODY_LENGTH)
+        # @return [Integer]
+        def current_max_body_length
+          max_body_length || MAX_BODY_LENGTH
+        end
+      end
+
+      # Thread-safety: duplicate the middleware for each request
+      # @!visibility private
+      def call(env)
+        dup.call!(env)
+      end
+
+      # @!visibility private
+      def call!(env)
+        return @app.call(env) unless self.class.enabled
+
+        start_time = Time.now
+        log_request(env)
+
+        @app.call(env).on_complete do |response_env|
+          elapsed_ms = ((Time.now - start_time) * 1000).round(2)
+          log_response(response_env, elapsed_ms)
+        end
+      end
+
+      private
+
+      def log_request(env)
+        logger = self.class.current_logger
+        level = self.class.current_log_level
+
+        method = env[:method].to_s.upcase
+        url = sanitize_url(env[:url].to_s)
+
+        case level
+        when :debug
+          logger.debug "▶ #{method} #{url}"
+          log_headers(env[:request_headers], "Request")
+          log_body(env[:body], "Request")
+        when :info
+          logger.info "▶ #{method} #{url}"
+        end
+      end
+
+      def log_response(response_env, elapsed_ms)
+        logger = self.class.current_logger
+        level = self.class.current_log_level
+        status = response_env[:status]
+
+        # Determine if this is an error response
+        is_error = status >= 400
+
+        case level
+        when :debug
+          log_debug_response(logger, response_env, elapsed_ms, is_error)
+        when :info
+          log_info_response(logger, response_env, elapsed_ms, is_error)
+        when :warn
+          log_warn_response(logger, response_env, elapsed_ms) if is_error
+        end
+      end
+
+      def log_debug_response(logger, response_env, elapsed_ms, is_error)
+        status = response_env[:status]
+        status_indicator = is_error ? "✗" : "◀"
+
+        logger.debug "#{status_indicator} #{status} (#{elapsed_ms}ms)"
+        log_body(response_body_content(response_env), "Response")
+      end
+
+      def log_info_response(logger, response_env, elapsed_ms, is_error)
+        status = response_env[:status]
+        status_indicator = is_error ? "✗" : "◀"
+
+        if is_error
+          logger.info "#{status_indicator} #{status} (#{elapsed_ms}ms) - #{error_summary(response_env)}"
+        else
+          logger.info "#{status_indicator} #{status} (#{elapsed_ms}ms)"
+        end
+      end
+
+      def log_warn_response(logger, response_env, elapsed_ms)
+        status = response_env[:status]
+        logger.warn "✗ #{status} (#{elapsed_ms}ms) - #{error_summary(response_env)}"
+      end
+
+      def log_headers(headers, prefix)
+        return unless headers
+        logger = self.class.current_logger
+        headers.each do |key, value|
+          # Don't log sensitive headers. Reuses the canonical denylist on
+          # Parse::Middleware::BodyBuilder so Authorization, Cookie, and
+          # X-Parse-JavaScript-Key are also redacted (the prior regex only
+          # caught master-key / api-key / session-token shaped names).
+          if Parse::Middleware::BodyBuilder::REDACTED_HEADERS.include?(key.to_s.downcase)
+            logger.debug "  [#{prefix} Header] #{key}: [FILTERED]"
+          else
+            logger.debug "  [#{prefix} Header] #{key}: #{value}"
+          end
+        end
+      end
+
+      def log_body(body, prefix)
+        return unless body
+        logger = self.class.current_logger
+        max_length = self.class.current_max_body_length
+
+        content = if body.is_a?(String)
+            body
+          else
+            begin
+              body.to_json
+            rescue JSON::GeneratorError, Encoding::UndefinedConversionError
+              body.to_s
+            end
+          end
+
+        if content.length > max_length
+          logger.debug "  [#{prefix} Body] #{content[0...max_length]}... (truncated, #{content.length} total)"
+        elsif content.length > 0
+          logger.debug "  [#{prefix} Body] #{content}"
+        end
+      end
+
+      def response_body_content(response_env)
+        body = response_env[:body]
+        if body.is_a?(Parse::Response)
+          begin
+            body.result.to_json
+          rescue JSON::GeneratorError, Encoding::UndefinedConversionError
+            body.to_s
+          end
+        else
+          body
+        end
+      end
+
+      def error_summary(response_env)
+        body = response_env[:body]
+        if body.is_a?(Parse::Response) && body.error?
+          "#{body.code}: #{body.error}"
+        elsif body.is_a?(Hash)
+          body["error"] || body[:error] || "Unknown error"
+        else
+          "HTTP #{response_env[:status]}"
+        end
+      end
+
+      def sanitize_url(url)
+        # Remove sensitive query parameters from logged URLs
+        url.gsub(/([?&])(sessionToken|masterKey|apiKey)=[^&]*/, '\1\2=[FILTERED]')
+      end
+    end
+  end
+
+  # Module-level configuration methods for logging
+  class << self
+    # Enable or disable request/response logging
+    # @example Enable logging
+    #   Parse.logging_enabled = true
+    # @param value [Boolean]
+    def logging_enabled=(value)
+      Middleware::Logging.enabled = value
+    end
+
+    # @return [Boolean] whether logging is enabled
+    def logging_enabled
+      Middleware::Logging.enabled
+    end
+
+    # Set the log level for Parse requests
+    # @example Set debug level
+    #   Parse.log_level = :debug
+    # @param value [Symbol] one of :info, :debug, :warn
+    def log_level=(value)
+      unless [:info, :debug, :warn].include?(value)
+        raise ArgumentError, "Invalid log level: #{value}. Use :info, :debug, or :warn"
+      end
+      Middleware::Logging.log_level = value
+    end
+
+    # @return [Symbol] the current log level
+    def log_level
+      Middleware::Logging.current_log_level
+    end
+
+    # Set a custom logger for Parse requests
+    # @example Use Rails logger
+    #   Parse.logger = Rails.logger
+    # @param value [Logger]
+    def logger=(value)
+      Middleware::Logging.logger = value
+    end
+
+    # @return [Logger] the current logger
+    def logger
+      Middleware::Logging.current_logger
+    end
+
+    # Set the maximum body length to log before truncation
+    # @param value [Integer]
+    def log_max_body_length=(value)
+      Middleware::Logging.max_body_length = value.to_i
+    end
+
+    # @return [Integer] the maximum body length
+    def log_max_body_length
+      Middleware::Logging.current_max_body_length
+    end
+
+    # Configure Parse logging with a block
+    # @example
+    #   Parse.configure_logging do |config|
+    #     config.enabled = true
+    #     config.log_level = :debug
+    #     config.logger = Rails.logger
+    #   end
+    def configure_logging
+      yield Middleware::Logging if block_given?
+    end
+  end
+end

data/lib/parse/client/profiling.rb

@@ -0,0 +1,181 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "faraday"
+
+module Parse
+  module Middleware
+    # Faraday middleware that profiles Parse API requests.
+    #
+    # This middleware provides detailed timing information for HTTP requests
+    # including network time and overall request duration.
+    #
+    # @example Enable profiling
+    #   Parse.profiling_enabled = true
+    #
+    # @example Access profile data in callbacks
+    #   Parse.on_request_complete do |profile|
+    #     puts "Request to #{profile[:url]} took #{profile[:duration_ms]}ms"
+    #   end
+    #
+    # @example Get recent profiles
+    #   Parse.recent_profiles.each do |profile|
+    #     puts "#{profile[:method]} #{profile[:url]}: #{profile[:duration_ms]}ms"
+    #   end
+    #
+    class Profiling < Faraday::Middleware
+      # Maximum number of profiles to keep in memory
+      MAX_PROFILES = 100
+
+      class << self
+        # @return [Boolean] Whether profiling is enabled
+        attr_accessor :enabled
+
+        # @return [Array<Hash>] Recent profile data
+        def profiles
+          @profiles ||= []
+        end
+
+        # Clear all stored profiles
+        def clear_profiles!
+          @profiles = []
+        end
+
+        # @return [Array<Proc>] Callbacks to execute on request completion
+        def callbacks
+          @callbacks ||= []
+        end
+
+        # Register a callback to be executed when a request completes
+        # @yield [Hash] the profile data for the completed request
+        def on_request_complete(&block)
+          callbacks << block if block_given?
+        end
+
+        # Clear all registered callbacks
+        def clear_callbacks!
+          @callbacks = []
+        end
+
+        # Add a profile entry
+        # @param profile [Hash] the profile data
+        def add_profile(profile)
+          profiles << profile
+          # Keep only the most recent profiles
+          profiles.shift while profiles.size > MAX_PROFILES
+
+          # Execute callbacks
+          callbacks.each { |cb| cb.call(profile) }
+        end
+
+        # Get aggregate statistics for recent profiles
+        # @return [Hash] statistics including count, avg, min, max durations
+        def statistics
+          return {} if profiles.empty?
+
+          durations = profiles.map { |p| p[:duration_ms] }
+          {
+            count: profiles.size,
+            total_ms: durations.sum,
+            avg_ms: (durations.sum.to_f / durations.size).round(2),
+            min_ms: durations.min,
+            max_ms: durations.max,
+            by_method: profiles.group_by { |p| p[:method] }.transform_values(&:size),
+            by_status: profiles.group_by { |p| p[:status] }.transform_values(&:size),
+          }
+        end
+      end
+
+      # Thread-safety: duplicate the middleware for each request
+      # @!visibility private
+      def call(env)
+        dup.call!(env)
+      end
+
+      # @!visibility private
+      def call!(env)
+        return @app.call(env) unless self.class.enabled
+
+        start_time = Time.now
+
+        @app.call(env).on_complete do |response_env|
+          end_time = Time.now
+          duration_ms = ((end_time - start_time) * 1000).round(2)
+
+          profile = {
+            method: env[:method].to_s.upcase,
+            url: sanitize_url(env[:url].to_s),
+            status: response_env[:status],
+            duration_ms: duration_ms,
+            started_at: start_time.iso8601(3),
+            completed_at: end_time.iso8601(3),
+            request_size: env[:body].to_s.bytesize,
+            response_size: response_body_size(response_env),
+          }
+
+          self.class.add_profile(profile)
+        end
+      end
+
+      private
+
+      def sanitize_url(url)
+        # Remove sensitive query parameters
+        url.gsub(/([?&])(sessionToken|masterKey|apiKey)=[^&]*/, '\1\2=[FILTERED]')
+      end
+
+      def response_body_size(response_env)
+        body = response_env[:body]
+        if body.is_a?(Parse::Response)
+          body.result.to_json.bytesize rescue 0
+        elsif body.is_a?(String)
+          body.bytesize
+        else
+          body.to_s.bytesize
+        end
+      end
+    end
+  end
+
+  # Module-level profiling configuration
+  class << self
+    # Enable or disable request profiling
+    # @param value [Boolean]
+    def profiling_enabled=(value)
+      Middleware::Profiling.enabled = value
+    end
+
+    # @return [Boolean] whether profiling is enabled
+    def profiling_enabled
+      Middleware::Profiling.enabled
+    end
+
+    # Get recent profile data
+    # @return [Array<Hash>]
+    def recent_profiles
+      Middleware::Profiling.profiles
+    end
+
+    # Clear all stored profiles
+    def clear_profiles!
+      Middleware::Profiling.clear_profiles!
+    end
+
+    # Get profiling statistics
+    # @return [Hash]
+    def profiling_statistics
+      Middleware::Profiling.statistics
+    end
+
+    # Register a callback for request completion
+    # @yield [Hash] profile data
+    def on_request_complete(&block)
+      Middleware::Profiling.on_request_complete(&block)
+    end
+
+    # Clear all profiling callbacks
+    def clear_profiling_callbacks!
+      Middleware::Profiling.clear_callbacks!
+    end
+  end
+end