parse-stack-next 4.5.0

data/lib/parse/client/protocol.rb

@@ -0,0 +1,91 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+module Parse
+  # Set of Parse protocol constants.
+  module Protocol
+    # The default server url, based on the hosted Parse platform.
+    # Uses HTTPS by default for security. Override with ENV["PARSE_SERVER_URL"]
+    # or pass server_url: to Parse.setup for custom configurations.
+    SERVER_URL = "https://localhost:1337/parse".freeze
+    # The request header field to send the application Id.
+    APP_ID = "X-Parse-Application-Id"
+    # The request header field to send the REST API key.
+    API_KEY = "X-Parse-REST-API-Key"
+    # The request header field to send the Master key.
+    MASTER_KEY = "X-Parse-Master-Key"
+    # The request header field to send the revocable Session key.
+    SESSION_TOKEN = "X-Parse-Session-Token"
+    # The request header field to request a revocable session token.
+    REVOCABLE_SESSION = "X-Parse-Revocable-Session"
+    # The request header field to send the installation id.
+    INSTALLATION_ID = "Parse-Installation-Id"
+    # The request header field to send an email when authenticating with Parse hosted platform.
+    EMAIL = "X-Parse-Email"
+    # The request header field to send the password when authenticating with the Parse hosted platform.
+    PASSWORD = "X-Parse-Password"
+    # The request header field for the Content type.
+    CONTENT_TYPE = "Content-Type"
+    # The default content type format for sending API requests.
+    CONTENT_TYPE_FORMAT = "application/json; charset=utf-8"
+    # The request header field for MongoDB read preference.
+    # Supported values: PRIMARY, PRIMARY_PREFERRED, SECONDARY, SECONDARY_PREFERRED, NEAREST
+    READ_PREFERENCE = "X-Parse-Read-Preference"
+
+    # Valid read preference values for MongoDB
+    READ_PREFERENCES = %w[PRIMARY PRIMARY_PREFERRED SECONDARY SECONDARY_PREFERRED NEAREST].freeze
+  end
+
+  # All Parse error codes.
+  # @todo Implement all error codes as StandardError
+  #
+  # List of error codes.
+  #  OtherCause	-1	Error code indicating that an unknown error or an error unrelated to Parse occurred.
+  #  InternalServerError	1	Error code indicating that something has gone wrong with the server. If you get this error code, it is Parse's fault. Please report the bug to https://parse.com/help.
+  #  ConnectionFailed	100	Error code indicating the connection to the Parse servers failed.
+  #  ObjectNotFound	101	Error code indicating the specified object doesn't exist.
+  #  InvalidQuery	102	Error code indicating you tried to query with a datatype that doesn't support it, like exact matching an array or object.
+  #  InvalidClassName	103	Error code indicating a missing or invalid classname. Classnames are case-sensitive. They must start with a letter, and a-zA-Z0-9_ are the only valid characters.
+  #  MissingObjectId	104	Error code indicating an unspecified object id.
+  #  InvalidKeyName	105	Error code indicating an invalid key name. Keys are case-sensitive. They must start with a letter, and a-zA-Z0-9_ are the only valid characters.
+  #  InvalidPointer	106	Error code indicating a malformed pointer. You should not see this unless you have been mucking about changing internal Parse code.
+  #  InvalidJSON	107	Error code indicating that badly formed JSON was received upstream. This either indicates you have done something unusual with modifying how things encode to JSON, or the network is failing badly.
+  #  CommandUnavailable	108	Error code indicating that the feature you tried to access is only available internally for testing purposes.
+  #  NotInitialized	109	You must call Parse.initialize before using the Parse library.
+  #  IncorrectType	111	Error code indicating that a field was set to an inconsistent type.
+  #  InvalidChannelName	112	Error code indicating an invalid channel name. A channel name is either an empty string (the broadcast channel) or contains only a-zA-Z0-9_ characters and starts with a letter.
+  #  PushMisconfigured	115	Error code indicating that push is misconfigured.
+  #  ObjectTooLarge	116	Error code indicating that the object is too large.
+  #  OperationForbidden	119	Error code indicating that the operation isn't allowed for clients.
+  #  CacheMiss	120	Error code indicating the result was not found in the cache.
+  #  InvalidNestedKey	121	Error code indicating that an invalid key was used in a nested JSONObject.
+  #  InvalidFileName	122	Error code indicating that an invalid filename was used for ParseFile. A valid file name contains only a-zA-Z0-9_. characters and is between 1 and 128 characters.
+  #  InvalidACL	123	Error code indicating an invalid ACL was provided.
+  #  Timeout	124	Error code indicating that the request timed out on the server. Typically this indicates that the request is too expensive to run.
+  #  InvalidEmailAddress	125	Error code indicating that the email address was invalid.
+  #  DuplicateValue	137	Error code indicating that a unique field was given a value that is already taken.
+  #  InvalidRoleName	139	Error code indicating that a role's name is invalid.
+  #  ExceededQuota	140	Error code indicating that an application quota was exceeded. Upgrade to resolve.
+  #  ScriptFailed	141	Error code indicating that a Cloud Code script failed.
+  #  ValidationFailed	142	Error code indicating that a Cloud Code validation failed.
+  #  FileDeleteFailed	153	Error code indicating that deleting a file failed.
+  #  RequestLimitExceeded	155	Error code indicating that the application has exceeded its request limit.
+  #  InvalidEventName	160	Error code indicating that the provided event name is invalid.
+  #  UsernameMissing	200	Error code indicating that the username is missing or empty.
+  #  PasswordMissing	201	Error code indicating that the password is missing or empty.
+  #  UsernameTaken	202	Error code indicating that the username has already been taken.
+  #  EmailTaken	203	Error code indicating that the email has already been taken.
+  #  EmailMissing	204	Error code indicating that the email is missing, but must be specified.
+  #  EmailNotFound	205	Error code indicating that a user with the specified email was not found.
+  #  SessionMissing	206	Error code indicating that a user object without a valid session could not be altered.
+  #  MustCreateUserThroughSignup	207	Error code indicating that a user can only be created through signup.
+  #  AccountAlreadyLinked	208	Error code indicating that an an account being linked is already linked to another user.
+  #  InvalidSessionToken	209	Error code indicating that the current session token is invalid.
+  #  LinkedIdMissing	250	Error code indicating that a user cannot be linked to an account because that account's id could not be found.
+  #  InvalidLinkedSession	251	Error code indicating that a user with a linked (e.g. Facebook) account has an invalid session.
+  #  UnsupportedService	252	Error code indicating that a service being linked (e.g. Facebook or Twitter) is unsupported.
+  # module ErrorCodes
+  #
+  # end
+
+end

data/lib/parse/client/request.rb

@@ -0,0 +1,233 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/json"
+require "securerandom"
+
+module Parse
+  #This class represents a Parse request.
+  class Request
+    # @!attribute [rw] method
+    #   @return [String] the HTTP method used for this request.
+
+    # @!attribute [rw] path
+    #   @return [String] the uri path.
+
+    # @!attribute [rw] body
+    #   @return [Hash] the body of this request.
+
+    # TODO: Document opts and cache options.
+
+    # @!attribute [rw] opts
+    #   @return [Hash] a set of options for this request.
+    # @!attribute [rw] cache
+    #   @return [Boolean]
+    attr_accessor :method, :path, :body, :headers, :opts, :cache
+
+    # @!visibility private
+    # Used to correlate batching requests with their responses.
+    attr_accessor :tag
+
+    # @!attribute [rw] request_id
+    #   @return [String] unique identifier for this request to enable idempotency
+    attr_accessor :request_id
+
+    # Class-level configuration for request ID behavior
+    class << self
+      # @!attribute [rw] enable_request_id
+      #   @return [Boolean] whether to automatically generate request IDs for idempotency
+      attr_accessor :enable_request_id
+
+      # @!attribute [rw] request_id_header
+      #   @return [String] the header name to use for request IDs
+      attr_accessor :request_id_header
+
+      # @!attribute [rw] idempotent_methods
+      #   @return [Array<Symbol>] HTTP methods that should include request IDs
+      attr_accessor :idempotent_methods
+    end
+
+    # Default configuration
+    self.enable_request_id = true  # Enabled by default for production safety
+    self.request_id_header = "X-Parse-Request-Id"  # Standard Parse header
+    self.idempotent_methods = [:post, :put, :patch]  # Methods that can benefit from idempotency
+
+    # Creates a new request
+    # @param method [String] the HTTP method
+    # @param uri [String] the API path of the request (without the host)
+    # @param body [Hash] the body (or parameters) of this request.
+    # @param headers [Hash] additional headers to send in this request.
+    # @param opts [Hash] additional optional parameters.
+    # @option opts [String] :request_id custom request ID for idempotency
+    # @option opts [Boolean] :idempotent force enable/disable idempotency for this request
+    def initialize(method, uri, body: nil, headers: nil, opts: {})
+      @tag = 0
+      method = method.downcase.to_sym
+      unless method == :get || method == :put || method == :post || method == :delete
+        raise ArgumentError, "Invalid method #{method} for request : '#{uri}'"
+      end
+
+      self.method = method
+      self.path = uri
+      self.body = body
+      self.headers = headers || {}
+      self.opts = opts || {}
+
+      # Handle request ID for idempotency
+      setup_request_id
+    end
+
+    # The parameters of this request if the HTTP method is GET.
+    # @return [Hash]
+    def query
+      body if @method == :get
+    end
+
+    # @return [Hash] JSON encoded hash
+    def as_json
+      signature.as_json
+    end
+
+    # @return [Boolean]
+    def ==(r)
+      return false unless r.is_a?(Request)
+      @method == r.method && @path == r.path && @body == r.body && @headers == r.headers
+    end
+
+    # Signature provies a way for us to compare different requests objects.
+    # Two requests objects are the same if they have the same signature.
+    # @return [Hash] A hash representing this request.
+    def signature
+      { method: @method.upcase, path: @path, body: @body }
+    end
+
+    # @!visibility private
+    def inspect
+      "#<#{self.class} @method=#{@method} @path='#{@path}'>"
+    end
+
+    # @return [String]
+    def to_s
+      "#{@method.to_s.upcase} #{@path}"
+    end
+
+    private
+
+    # Sets up request ID for idempotency based on configuration and request properties
+    def setup_request_id
+      # Check if idempotency should be enabled for this request
+      should_use_request_id = determine_idempotency_requirement
+
+      return unless should_use_request_id
+
+      # Use custom request ID if provided, otherwise generate one
+      @request_id = @opts[:request_id] || generate_request_id
+
+      # Add request ID to headers if not already present
+      header_name = self.class.request_id_header
+      @headers[header_name] ||= @request_id
+    end
+
+    # Determines if this request should use a request ID for idempotency
+    # @return [Boolean]
+    def determine_idempotency_requirement
+      # Explicit override in opts takes precedence
+      return @opts[:idempotent] if @opts.key?(:idempotent)
+
+      # Check if request ID is already in headers (manually added)
+      return true if @headers[self.class.request_id_header]
+
+      # Check global configuration and method
+      return false unless self.class.enable_request_id
+      return false unless self.class.idempotent_methods.include?(@method)
+
+      # Don't add request IDs to certain paths that are inherently idempotent
+      # or where Parse handles idempotency differently
+      return false if non_idempotent_path?
+
+      true
+    end
+
+    # Checks if the request path should not use request IDs
+    # @return [Boolean]
+    def non_idempotent_path?
+      # GET requests are naturally idempotent
+      return true if @method == :get
+
+      # Some Parse endpoints handle their own idempotency or shouldn't be retried
+      non_idempotent_patterns = [
+        %r{/sessions},           # Session creation/management
+        %r{/logout},             # Logout operations
+        %r{/requestPasswordReset}, # Password reset requests
+        %r{/functions/},         # Cloud functions (may have their own logic)
+        %r{/jobs/},              # Background jobs
+        %r{/events/},            # Analytics events
+        %r{/push},                # Push notifications
+      ]
+
+      non_idempotent_patterns.any? { |pattern| @path =~ pattern }
+    end
+
+    # Generates a unique request ID
+    # @return [String] a unique identifier for this request
+    def generate_request_id
+      # Use a format that identifies the request came from Ruby Parse Stack
+      # and includes a UUID for uniqueness
+      "_RB_#{SecureRandom.uuid}"
+    end
+
+    public
+
+    # Enables idempotency for this specific request
+    # @param custom_id [String] optional custom request ID to use
+    # @return [self] for method chaining
+    def with_idempotency(custom_id = nil)
+      @opts[:idempotent] = true
+      @opts[:request_id] = custom_id if custom_id
+      setup_request_id
+      self
+    end
+
+    # Disables idempotency for this specific request
+    # @return [self] for method chaining
+    def without_idempotency
+      @opts[:idempotent] = false
+      @request_id = nil
+      @headers.delete(self.class.request_id_header)
+      self
+    end
+
+    # Checks if this request has idempotency enabled
+    # @return [Boolean]
+    def idempotent?
+      @request_id.present? && @headers[self.class.request_id_header].present?
+    end
+
+    # Class methods for configuration
+
+    # Enables request ID generation globally
+    # @param methods [Array<Symbol>] HTTP methods to apply idempotency to
+    # @param header [String] header name to use for request IDs
+    def self.enable_idempotency!(methods: [:post, :put, :patch], header: "X-Parse-Request-Id")
+      self.enable_request_id = true
+      self.idempotent_methods = methods
+      self.request_id_header = header
+    end
+
+    # Disables request ID generation globally
+    def self.disable_idempotency!
+      self.enable_request_id = false
+    end
+
+    # Configures idempotency settings
+    # @param enabled [Boolean] whether to enable idempotency
+    # @param methods [Array<Symbol>] HTTP methods to apply idempotency to
+    # @param header [String] header name to use for request IDs
+    def self.configure_idempotency(enabled: true, methods: [:post, :put, :patch], header: "X-Parse-Request-Id")
+      self.enable_request_id = enabled
+      self.idempotent_methods = methods
+      self.request_id_header = header
+    end
+  end
+end

data/lib/parse/client/response.rb

@@ -0,0 +1,208 @@
+# encoding: UTF-8
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/json"
+
+module Parse
+
+  # Represents a response from Parse server. A response can also
+  # be a set of responses (from a Batch response).
+  class Response
+    include Enumerable
+
+    # Code for an unknown error.
+    ERROR_INTERNAL = 1
+    # Code when the server returns a 500 or is non-responsive.
+    ERROR_SERVICE_UNAVAILABLE = 2
+    # Code when the request times out.
+    ERROR_TIMEOUT = 124
+    # Code when the requests per second limit as been exceeded.
+    ERROR_EXCEEDED_BURST_LIMIT = 155
+    # Code when a requested record is not found.
+    ERROR_OBJECT_NOT_FOUND = 101
+    # Code when the username is missing in request.
+    ERROR_USERNAME_MISSING = 200
+    # Code when the password is missing in request.
+    ERROR_PASSWORD_MISSING = 201
+    # Code when the username is already in the system.
+    ERROR_USERNAME_TAKEN = 202
+    # Code when the email is already in the system.
+    ERROR_EMAIL_TAKEN = 203
+    # Code when the email is not found
+    ERROR_EMAIL_NOT_FOUND = 205
+    # Code when the email is invalid
+    ERROR_EMAIL_INVALID = 125
+
+    # The field name for the error.
+    ERROR = "error".freeze
+    # The field name for the success.
+    SUCCESS = "success".freeze
+    # The field name for the error code.
+    CODE = "code".freeze
+    # The field name for the results of the request.
+    RESULTS = "results".freeze
+    # The field name for the count result in a count response.
+    COUNT = "count".freeze
+
+    # The Retry-After header name.
+    RETRY_AFTER = "Retry-After".freeze
+
+    # @!attribute [rw] parse_class
+    #  @return [String] the Parse class for this request
+    # @!attribute [rw] code
+    #  @return [Integer] the error code
+    # @!attribute [rw] error
+    #  @return [Integer] the error message
+    # @!attribute [rw] result
+    #  @return [Hash] the body of the response result.
+    # @!attribute [rw] http_status
+    #  @return [Integer] the HTTP status code from the response.
+    # @!attribute [rw] request
+    #  @return [Integer] the Parse::Request that generated this response.
+    #  @see Parse::Request
+    # @!attribute [rw] headers
+    #  @return [Hash] the HTTP response headers.
+    attr_accessor :parse_class, :code, :error, :result, :http_status,
+                  :request, :headers
+    # You can query Parse for counting objects, which may not actually have
+    # results.
+    # @return [Integer] the count result from a count query request.
+    attr_reader :count
+
+    # Get the Retry-After header value as seconds.
+    # The Retry-After header can be either a number of seconds or an HTTP-date.
+    # @return [Integer, nil] seconds to wait before retrying, or nil if not present.
+    def retry_after
+      return nil unless @headers.is_a?(Hash)
+      value = @headers[RETRY_AFTER] || @headers["retry-after"]
+      return nil if value.nil?
+
+      # Try parsing as integer (seconds)
+      if value.to_s =~ /\A\d+\z/
+        value.to_i
+      else
+        # Try parsing as HTTP-date
+        begin
+          date = Time.httpdate(value.to_s)
+          delay = (date - Time.now).ceil
+          delay > 0 ? delay : 1
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+
+    # Create an instance with a Parse response JSON hash.
+    # @param res [Hash] the JSON hash
+    def initialize(res = {})
+      @http_status = 0
+      @count = 0
+      @batch_response = false # by default, not a batch response
+      @result = nil
+      # If a string is used for initializing, treat it as JSON
+      # check for string to not be 'OK' since that is the health check API response
+      res = JSON.parse(res) if res.is_a?(String) && res != "OK".freeze
+      # If it is a hash (or parsed JSON), then parse the result.
+      parse_result!(res) if res.is_a?(Hash)
+      # if the result is an Array, then most likely it is a set of responses
+      # from using a Batch API.
+      if res.is_a?(Array)
+        @batch_response = true
+        @result = res || []
+        @count = @result.count
+      end
+      #if none match, set pure result
+      @result = res if @result.nil?
+    end
+
+    # true if this was a batch response.
+    def batch?
+      @batch_response
+    end
+
+    # If it is a batch respnose, we'll create an array of Response objects for each
+    # of the ones in the batch.
+    # @return [Array] an array of Response objects.
+    def batch_responses
+      return [@result] unless @batch_response
+      # if batch response, generate array based on the response hash.
+      @result.map do |r|
+        next r unless r.is_a?(Hash)
+        hash = r[SUCCESS] || r[ERROR]
+        Parse::Response.new hash
+      end
+    end
+
+    # This method takes the result hash and determines if it is a regular
+    # parse query result, object result or a count result. The response should
+    # be a hash either containing the result data or the error.
+    def parse_result!(h)
+      @result = {}
+      return unless h.is_a?(Hash)
+      @code = h[CODE]
+      @error = h[ERROR]
+      if h[RESULTS].is_a?(Array)
+        @result = h[RESULTS]
+        @count = h[COUNT] || @result.count
+      else
+        @result = h
+        @count = 1
+      end
+    end
+
+    alias_method :parse_results!, :parse_result!
+
+    # true if the response is successful.
+    # @see #error?
+    def success?
+      @code.nil? && @error.nil?
+    end
+
+    # true if the response has an error code.
+    # @see #success?
+    def error?
+      !success?
+    end
+
+    # true if the response has an error code of 'object not found'
+    # @see ERROR_OBJECT_NOT_FOUND
+    def object_not_found?
+      @code == ERROR_OBJECT_NOT_FOUND
+    end
+
+    # @return [Array] the result data from the response.
+    def results
+      return [] if @result.nil?
+      @result.is_a?(Array) ? @result : [@result]
+    end
+
+    # @return [Object] the first thing in the result array.
+    def first
+      @result.is_a?(Array) ? @result.first : @result
+    end
+
+    # Iterate through each result item.
+    # @yieldparam [Object] a result entry.
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      results.each(&block)
+      self
+    end
+
+    # @!visibility private
+    def inspect
+      if error?
+        "#<#{self.class} @code=#{code} @error='#{error}'>"
+      else
+        "#<#{self.class} @result='#{@result}'>"
+      end
+    end
+
+    # @return [String] JSON encoded object, or an error string.
+    def to_s
+      return "[E-#{@code}] #{@request} : #{@error} (#{@http_status})" if error?
+      @result.to_json
+    end
+  end
+end