parse-stack 1.5.3 → 1.6.0

data/lib/parse/api/sessions.rb

@@ -6,6 +6,7 @@ module Parse
   module API
     # Defines the Session class interface for the Parse REST API
     module Sessions
+      # @!visibility private
       SESSION_PATH_PREFIX = "sessions"
 
       # Fetch a session record for a given session token.

data/lib/parse/api/users.rb

@@ -8,10 +8,13 @@ module Parse
   module API
     # Defines the User class interface for the Parse REST API
     module Users
-
+      # @!visibility private
       USER_PATH_PREFIX = "users"
+      # @!visibility private
       LOGOUT_PATH = "logout"
+      # @!visibility private
       LOGIN_PATH = "login"
+      # @!visibility private
       REQUEST_PASSWORD_RESET = "requestPasswordReset"
 
       # Fetch a {Parse::User} for a given objectId.

data/lib/parse/client.rb

@@ -18,15 +18,24 @@ require_relative "client/caching"
 require_relative "api/all"
 
 module Parse
-
-  class ConnectionError < StandardError; end;
-  class TimeoutError < StandardError; end;
-  class ProtocolError < StandardError; end;
-  class ServerError < StandardError; end;
-  class ServiceUnavailableError < StandardError; end;
-  class AuthenticationError < StandardError; end;
-  class RequestLimitExceededError < StandardError; end;
-  class InvalidSessionTokenError < StandardError; end;
+  class Error < StandardError
+    # An error when a general connection occurs.
+    class ConnectionError < Error; end;
+    # An error when a connection timeout occurs.
+    class TimeoutError < Error; end;
+    # An error when there is an Parse REST API protocol error.
+    class ProtocolError < Error; end;
+    # An error when the Parse server returned invalid code.
+    class ServerError < Error; end;
+    # An error when a Parse server responds with HTTP 500.
+    class ServiceUnavailableError < Error; end;
+    # An error when the authentication credentials in the request are invalid.
+    class AuthenticationError < Error; end;
+    # An error when the burst limit has been exceeded.
+    class RequestLimitExceededError < Error; end;
+    # An error when the session token provided in the request is invalid.
+    class InvalidSessionTokenError < Error; end;
+  end
 
   # Retrieve the App specific Parse configuration parameters. The configuration
   # for a connection is cached after the first request. Use the bang version to
@@ -86,19 +95,30 @@ module Parse
   # Faraday, which means it is open to add any additional middleware for
   # features you'd like to implement.
   class Client
-    include Parse::API::Objects
+    include Parse::API::Analytics
+    include Parse::API::Apps
+    include Parse::API::Batch
+    include Parse::API::CloudFunctions
     include Parse::API::Config
     include Parse::API::Files
-    include Parse::API::CloudFunctions
-    include Parse::API::Users
-    include Parse::API::Sessions
     include Parse::API::Hooks
-    include Parse::API::Apps
-    include Parse::API::Batch
+    include Parse::API::Objects
     include Parse::API::Push
     include Parse::API::Schema
-    RETRY_COUNT = 2
-    RETRY_DELAY = 2 #seconds
+    include Parse::API::Server
+    include Parse::API::Sessions
+    include Parse::API::Users
+    # The user agent header key.
+    USER_AGENT_HEADER = "User-Agent".freeze
+    # The value for the User-Agent header.
+    USER_AGENT_VERSION = "Parse-Stack v#{Parse::Stack::VERSION}".freeze
+    # The default retry count
+    DEFAULT_RETRIES = 2
+    # The wait time in seconds between retries
+    RETRY_DELAY = 1.5
+
+    # An error when a general response error occurs when communicating with Parse server.
+    class ResponseError < Parse::Error; end;
 
     # @!attribute cache
     #  The underlying cache store for caching API requests.
@@ -117,7 +137,11 @@ module Parse
     #  The Parse server url that will be receiving these API requests. By default
     #  this will be {Parse::Protocol::SERVER_URL}.
     #  @return [String]
-    attr_accessor :cache
+    # @!attribute retry_limit
+    #  The default retry count for the client when a specific request timesout or
+    #  the service is unavailable. Defaults to {DEFAULT_RETRIES}.
+    #  @return [String]
+    attr_accessor :cache, :retry_limit
     attr_reader :application_id, :api_key, :master_key, :server_url
     alias_method :app_id, :application_id
     # The client can support multiple sessions. The first session created, will be placed
@@ -169,16 +193,13 @@ module Parse
     # @param opts [Hash] a set of connection options to configure the client.
     # @option opts [String] :server_url The server url of your Parse Server if you
     #   are not using the hosted Parse service. By default it will use
-    #   PARSE_SERVER_URL environment variable available or fall back to
-    #   https://api.parse.com/1/ if not specified.
-    # @option opts [String] :app_id The Parse application id. By default it will
-    #    use PARSE_APP_ID environment variable if not specified.
-    # @option opts [String] :api_key The Parse REST API Key. By default it will
-    #    use PARSE_API_KEY environment variable if not specified.
+    #   ENV["PARSE_SERVER_URL"] if available, otherwise fallback to {Parse::Protocol::SERVER_URL}.
+    # @option opts [String] :app_id The Parse application id. Defaults to
+    #    ENV['PARSE_APP_ID'] or ENV['PARSE_APPLICATION_ID'].
+    # @option opts [String] :api_key The Parse REST API Key. Defaults to ENV['PARSE_REST_API_KEY'].
     # @option opts [String] :master_key The Parse application master key (optional).
     #    If this key is set, it will be sent on every request sent by the client
-    #    and your models. By default it will use PARSE_MASTER_KEY environment
-    #    variable if not specified.
+    #    and your models. Defaults to ENV['PARSE_MASTER_KEY'].
     # @option opts [Boolean] :logging It provides you additional logging information
     #    of requests and responses. If set to the special symbol of *:debug*, it
     #    will provide additional payload data in the log messages. This option affects
@@ -201,6 +222,7 @@ module Parse
     #    cache using the clear_cache! method on your Parse::Client instance.
     # @option opts [Hash] :faraday You may pass a hash of options that will be
     #    passed to the Faraday constructor.
+    # @raise Parse::Error::ConnectionError if the client was not properly configured with required keys or url.
     # @raise ArgumentError if the cache instance passed to the :cache option is not of Moneta::Transformer.
     # @see Parse::Middleware::BodyBuilder
     # @see Parse::Middleware::Caching
@@ -208,13 +230,13 @@ module Parse
     # @see Parse::Protocol
     def initialize(opts = {})
       @server_url     = opts[:server_url] || ENV["PARSE_SERVER_URL"] || Parse::Protocol::SERVER_URL
-      @application_id = opts[:application_id] || opts[:app_id] || ENV["PARSE_APP_ID"] || ENV['PARSE_SERVER_APPLICATION_ID']
-      @api_key        = opts[:api_key] || opts[:rest_api_key]  || ENV["PARSE_API_KEY"] || ENV["PARSE_REST_API_KEY"]
-      @master_key     = opts[:master_key] || ENV["PARSE_MASTER_KEY"] || ENV['PARSE_SERVER_MASTER_KEY']
+      @application_id = opts[:application_id] || opts[:app_id] || ENV["PARSE_APP_ID"] || ENV['PARSE_APPLICATION_ID']
+      @api_key        = opts[:api_key] || opts[:rest_api_key]  || ENV["PARSE_REST_API_KEY"] || ENV["PARSE_API_KEY"]
+      @master_key     = opts[:master_key] || ENV["PARSE_MASTER_KEY"]
       opts[:adapter] ||= Faraday.default_adapter
       opts[:expires] ||= 3
-      if @application_id.nil? || ( @api_key.nil? && @master_key.nil? )
-        raise "Please call Parse.setup(application_id:, api_key:) to setup a client"
+      if @server_url.nil? || @application_id.nil? || ( @api_key.nil? && @master_key.nil? )
+        raise Parse::Error::ConnectionError, "Please call Parse.setup(server_url:, application_id:, api_key:) to setup a client"
       end
       @server_url += '/' unless @server_url.ends_with?('/')
       #Configure Faraday
@@ -260,6 +282,14 @@ module Parse
       Parse::Client.clients[:default] ||= self
     end
 
+    # If set, returns the current retry count for this instance. Otherwise,
+    # returns {DEFAULT_RETRIES}. Set to 0 to disable retry mechanism.
+    # @return [Integer] the current retry count for this client.
+    def retry_limit
+      return DEFAULT_RETRIES if @retry_limit.nil?
+      @retry_limit
+    end
+
     # @return [String] the url prefix of the Parse Server url.
     def url_prefix
       @conn.url_prefix
@@ -295,21 +325,21 @@ module Parse
     #  - *:retry* [Integer] The number of retrties to perform if the service is unavailable.
     #    Set to false to disable the retry mechanism. When performing request retries, the
     #    client will sleep for a number of seconds ({Parse::Client::RETRY_DELAY}) between requests.
-    #    The default value is {Parse::Client::RETRY_COUNT}.
-    # @raise Parse::AuthenticationError when HTTP response status is 401 or 403
-    # @raise Parse::TimeoutError when HTTP response status is 400 or
+    #    The default value is {Parse::Client::DEFAULT_RETRIES}.
+    # @raise Parse::Error::AuthenticationError when HTTP response status is 401 or 403
+    # @raise Parse::Error::TimeoutError when HTTP response status is 400 or
     #   408, and the Parse code is 143 or {Parse::Response::ERROR_TIMEOUT}.
-    # @raise Parse::ConnectionError when HTTP response status is 404 is not an object not found error.
+    # @raise Parse::Error::ConnectionError when HTTP response status is 404 is not an object not found error.
     #  - This will also be raised if after retrying a request a number of times has finally failed.
-    # @raise Parse::ProtocolError when HTTP response status is 405 or 406
-    # @raise Parse::ServiceUnavailableError when HTTP response status is 500 or 503.
+    # @raise Parse::Error::ProtocolError when HTTP response status is 405 or 406
+    # @raise Parse::Error::ServiceUnavailableError when HTTP response status is 500 or 503.
     #   - This may also happen when the Parse Server response code is any
     #     number less than {Parse::Response::ERROR_SERVICE_UNAVAILABLE}.
-    # @raise Parse::ServerError when the Parse response code is less than 100
-    # @raise Parse::RequestLimitExceededError when the Parse response code is {Parse::Response::ERROR_EXCEEDED_BURST_LIMIT}.
+    # @raise Parse::Error::ServerError when the Parse response code is less than 100
+    # @raise Parse::Error::RequestLimitExceededError when the Parse response code is {Parse::Response::ERROR_EXCEEDED_BURST_LIMIT}.
     #   - This usually means you have exceeded the burst limit on requests, which will mean you will be throttled for the
     #     next 60 seconds.
-    # @raise Parse::InvalidSessionTokenError when the Parse response code is 209.
+    # @raise Parse::Error::InvalidSessionTokenError when the Parse response code is 209.
     #   - This means the session token that was sent in the request seems to be invalid.
     # @return [Parse::Response] the response for this request.
     # @see Parse::Middleware::BodyBuilder
@@ -318,12 +348,12 @@ module Parse
     # @see Parse::Protocol
     # @see Parse::Request
     def request(method, uri = nil, body: nil, query: nil, headers: nil, opts: {})
-      retry_count ||= RETRY_COUNT
+      _retry_count ||= self.retry_limit
 
       if opts[:retry] == false
-        retry_count = 0
+        _retry_count = 0
       elsif opts[:retry].to_i > 0
-        retry_count = opts[:retry]
+        _retry_count = opts[:retry]
       end
 
       headers ||= {}
@@ -343,7 +373,7 @@ module Parse
       # http method
       method = method.downcase.to_sym
       # set the User-Agent
-      headers["User-Agent"] = "Parse-Stack v#{Parse::Stack::VERSION}"
+      headers[USER_AGENT_HEADER] = USER_AGENT_VERSION
 
       if opts[:cache] == false
         headers[Parse::Middleware::Caching::CACHE_CONTROL] = "no-cache"
@@ -373,59 +403,63 @@ module Parse
 
       case response.http_status
       when 401, 403
-        puts "[Parse:AuthenticationError] #{response}"
-        raise Parse::AuthenticationError, response
+        warn "[Parse:AuthenticationError] #{response}"
+        raise Parse::Error::AuthenticationError, response
       when 400, 408
         if response.code == Parse::Response::ERROR_TIMEOUT || response.code == 143 #"net/http: timeout awaiting response headers"
-          puts "[Parse:TimeoutError] #{response}"
-          raise Parse::TimeoutError, response
+          warn "[Parse:TimeoutError] #{response}"
+          raise Parse::Error::TimeoutError, response
         end
       when 404
         unless response.object_not_found?
-          puts "[Parse:ConnectionError] #{response}"
-          raise Parse::ConnectionError, response
+          warn "[Parse:ConnectionError] #{response}"
+          raise Parse::Error::ConnectionError, response
         end
       when 405, 406
-        puts "[Parse:ProtocolError] #{response}"
-        raise Parse::ProtocolError, response
+        warn "[Parse:ProtocolError] #{response}"
+        raise Parse::Error::ProtocolError, response
       when 500, 503
-        puts "[Parse:ServiceUnavailableError] #{response}"
-        raise Parse::ServiceUnavailableError, response
+        warn "[Parse:ServiceUnavailableError] #{response}"
+        raise Parse::Error::ServiceUnavailableError, response
       end
 
       if response.error?
         if response.code <= Parse::Response::ERROR_SERVICE_UNAVAILABLE
-          puts "[Parse:ServiceUnavailableError] #{response}"
-          raise Parse::ServiceUnavailableError, response
+          warn "[Parse:ServiceUnavailableError] #{response}"
+          raise Parse::Error::ServiceUnavailableError, response
         elsif response.code <= 100
-          puts "[Parse:ServerError] #{response}"
-          raise Parse::ServerError, response
+          warn "[Parse:ServerError] #{response}"
+          raise Parse::Error::ServerError, response
         elsif response.code == Parse::Response::ERROR_EXCEEDED_BURST_LIMIT
-          puts "[Parse:RequestLimitExceededError] #{response}"
-          raise Parse::RequestLimitExceededError, response
+          warn "[Parse:RequestLimitExceededError] #{response}"
+          raise Parse::Error::RequestLimitExceededError, response
         elsif response.code == 209 # Error 209: invalid session token
-          puts "[Parse:InvalidSessionTokenError] #{response}"
-          raise Parse::InvalidSessionTokenError, response
+          warn "[Parse:InvalidSessionTokenError] #{response}"
+          raise Parse::Error::InvalidSessionTokenError, response
         end
       end
 
       response
-    rescue Parse::ServiceUnavailableError => e
-      if retry_count > 0
-        puts "[Parse:Retry] Retries remaining #{retry_count} : #{response.request}"
-        sleep RETRY_DELAY
-        retry_count -= 1
+    rescue Parse::Error::ServiceUnavailableError => e
+      if _retry_count > 0
+        warn "[Parse:Retry] Retries remaining #{_retry_count} : #{response.request}"
+        _retry_count -= 1
+        backoff_delay = RETRY_DELAY * (self.retry_limit - _retry_count)
+        _retry_delay = [0,RETRY_DELAY, backoff_delay].sample
+        sleep _retry_delay if _retry_delay > 0
         retry
       end
       raise
     rescue Faraday::Error::ClientError, Net::OpenTimeout => e
-      if retry_count > 0
-        puts "[Parse:Retry] Retries remaining #{retry_count} : #{_request}"
-        sleep RETRY_DELAY
-        retry_count -= 1
+      if _retry_count > 0
+        warn "[Parse:Retry] Retries remaining #{_retry_count} : #{_request}"
+        _retry_count -= 1
+        backoff_delay = RETRY_DELAY * (self.retry_limit - _retry_count)
+        _retry_delay = [0,RETRY_DELAY, backoff_delay].sample
+        sleep _retry_delay if _retry_delay > 0
         retry
       end
-      raise Parse::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
+      raise Parse::Error::ConnectionError, "#{_request} : #{e.class} - #{e.message}"
     end
 
     # Send a GET request.
@@ -479,10 +513,12 @@ module Parse
     # Any subclass can override their `client` methods to provide a different session to use
     module Connectable
 
+      # @!visibility private
       def self.included(baseClass)
         baseClass.extend ClassMethods
       end
-
+      # Class methods to be added to any object that wants to have standard access to
+      # a the default {Parse::Client} instance.
       module ClassMethods
 
           # @return [Parse::Client] the current client for :default.

data/lib/parse/client/authentication.rb

@@ -15,6 +15,7 @@ module Parse
     # Parse REST API endpoint.
     class Authentication < Faraday::Middleware
       include Parse::Protocol
+      # @!visibility private
       DISABLE_MASTER_KEY = "X-Disable-Parse-Master-Key".freeze
       # @return [String] the application id for this Parse endpoint.
       attr_accessor :application_id
@@ -44,7 +45,7 @@ module Parse
         @content_type = options[:content_type] || CONTENT_TYPE_FORMAT
       end
 
-      # we dup the call for thread-safety
+      # Thread-safety
       # @!visibility private
       def call(env)
         dup.call!(env)

data/lib/parse/client/batch.rb

@@ -1,3 +1,5 @@
+# encoding: UTF-8
+# frozen_string_literal: true
 
 require_relative 'request'
 require_relative 'response'
@@ -33,9 +35,15 @@ module Parse
   # @see Array.save
   # @see Array.destroy
   class BatchOperation
+    include Enumerable
+    
+    # @!attribute requests
+    #  @return [Array] the set of requests in this batch.
 
+    # @!attribute responses
+    #  @return [Array] the set of responses from this batch.
     attr_accessor :requests, :responses
-    include Enumerable
+
 
     # @return [Parse::Client] the client to be used for the request.
     def client

data/lib/parse/client/body_builder.rb

@@ -10,11 +10,26 @@ require 'active_support/core_ext'
 require 'active_model_serializers'
 
 module Parse
+
+  # @!attribute self.logging
+  # Sets {Parse::Middleware::BodyBuilder} logging.
+  # You may specify `:debug` for additional verbosity.
+  # @return (see Parse::Middleware::BodyBuilder.logging)
+  def self.logging
+    Parse::Middleware::BodyBuilder.logging
+  end
+  # @!visibility private
+  def self.logging=(value)
+    Parse::Middleware::BodyBuilder.logging = value
+  end
+  
+  # Namespace for Parse-Stack related middleware.
   module Middleware
     # This middleware takes an incoming Parse response, after an outgoing request,
     # and creates a Parse::Response object.
     class BodyBuilder < Faraday::Middleware
       include Parse::Protocol
+      # Header sent when a GET requests exceeds the limit.
       HTTP_OVERRIDE = 'X-Http-Method-Override'
 
       class << self
@@ -24,7 +39,7 @@ module Parse
         attr_accessor :logging
       end
 
-      # thread-safety
+      # Thread-safety
       # @!visibility private
       def call(env)
         dup.call!(env)

data/lib/parse/client/caching.rb

@@ -8,7 +8,6 @@ require_relative 'protocol'
 
 module Parse
   module Middleware
-    class CachingError < StandardError; end;
     # 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.
@@ -19,19 +18,22 @@ module Parse
     class Caching < Faraday::Middleware
       include Parse::Protocol
 
-      # Internal: 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
-
+      # 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'
 
       class << self
@@ -71,7 +73,7 @@ module Parse
       # @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 Parse::Middleware::CachingError, if `store` is not a Moneta::Transformer instance.
+      # @raise ArgumentError, if `store` is not a Moneta::Transformer instance.
       def initialize(adapter, store, opts = {})
         super(adapter)
         @store = store
@@ -80,11 +82,12 @@ module Parse
         @expires = @opts[:expires]
 
         unless @store.is_a?(Moneta::Transformer)
-          raise Parse::Middleware::CachingError, "Caching store object must a Moneta key/value store (Moneta::Transformer)."
+          raise ArgumentError, "Caching store object must a Moneta key/value store (Moneta::Transformer)."
         end
 
       end
 
+      # Thread-safety
       # @!visibility private
       def call(env)
         dup.call!(env)
@@ -153,7 +156,6 @@ module Parse
           puts "[Parse::Cache] Error: #{e}"
         end
 
-        puts("[Parse::Cache::Miss] !! #{url}") if self.class.logging.present?
         @app.call(env).on_complete do |response_env|
           # Only cache GET requests with valid HTTP status codes whose content-length
           # is greater than 20. Otherwise they could be errors, successes and empty result sets.