momento 0.1.0 → 0.2.0

data/lib/momento/create_cache_response.rb

@@ -1,50 +1,35 @@
-require 'grpc'
-require 'momento/controlclient_pb'
+require_relative 'response/error'
 
 module Momento
-  # Responses specific to create_cache.
+  # A response from creating a cache.
   class CreateCacheResponse < Response
-    # Build a Momento::CreateCacheResponse from a block of code
-    # which returns a Momento::ControlClient::CreateCacheResponse.
-    #
-    # @return [Momento::CreateCacheResponse]
-    # @raise [StandardError] when the exception is not recognized.
-    # @raise [TypeError] when the response is not recognized.
-    def self.from_block
-      response = yield
-    rescue GRPC::AlreadyExists
-      return AlreadyExists.new
-    rescue GRPC::BadStatus => e
-      Error.new(grpc_exception: e)
-    else
-      raise TypeError unless response.is_a?(Momento::ControlClient::CreateCacheResponse)
-
-      return Success.new
-    end
-
+    # Does the cache already exist?
+    # @return [Boolean]
     def already_exists?
       false
     end
 
+    # Was the cache created?
+    # @return [Boolean]
     def success?
       false
     end
 
-    # A cache with that name already exists.
+    # @private
     class AlreadyExists < CreateCacheResponse
       def already_exists?
         true
       end
     end
 
-    # The cache was created.
+    # @private
     class Success < CreateCacheResponse
       def success?
         true
       end
     end
 
-    # There was an error creating the cache.
+    # @private
     class Error < CreateCacheResponse
       include ::Momento::Response::Error
     end

data/lib/momento/create_cache_response_builder.rb

@@ -0,0 +1,27 @@
+require 'grpc'
+require_relative 'controlclient_pb'
+
+module Momento
+  # @private
+  class CreateCacheResponseBuilder < ResponseBuilder
+    # Build a Momento::CreateCacheResponse from a block of code
+    # which returns a Momento::ControlClient::CreateCacheResponse.
+    #
+    # @return [Momento::CreateCacheResponse]
+    # @raise [StandardError] when the exception is not recognized.
+    # @raise [TypeError] when the response is not recognized.
+    def from_block
+      response = yield
+    rescue GRPC::AlreadyExists
+      return CreateCacheResponse::AlreadyExists.new
+    rescue *RESCUED_EXCEPTIONS => e
+      CreateCacheResponse::Error.new(
+        exception: e, context: context
+      )
+    else
+      raise TypeError unless response.is_a?(::Momento::ControlClient::CreateCacheResponse)
+
+      return CreateCacheResponse::Success.new
+    end
+  end
+end

data/lib/momento/delete_cache_response.rb

@@ -1,35 +1,20 @@
-require 'grpc'
-require 'momento/controlclient_pb'
+require_relative 'response/error'
 
 module Momento
-  # Responses specific to delete_cache
+  # A response from deleting a cache.
   class DeleteCacheResponse < Response
-    # Build a Momento::DeleteCacheResponse from a block of code
-    # which returns a Momento::ControlClient::DeleteCacheResponse..
-    #
-    # @return [Momento::DeleteCacheResponse]
-    # @raise [StandardError] when the exception is not recognized.
-    # @raise [TypeError] when the response is not recognized.
-    def self.from_block
-      response = yield
-    rescue GRPC::BadStatus => e
-      Error.new(grpc_exception: e)
-    else
-      raise TypeError unless response.is_a?(Momento::ControlClient::DeleteCacheResponse)
-
-      return Success.new
-    end
-
+    # Was the cache deleted?
+    # @return [Boolean]
     def success?
       false
     end
 
-    # There was an error deleting the cache.
+    # @private
     class Error < DeleteCacheResponse
       include ::Momento::Response::Error
     end
 
-    # The cache was deleted.
+    # @private
     class Success < DeleteCacheResponse
       def success?
         true

data/lib/momento/delete_cache_response_builder.rb

@@ -0,0 +1,25 @@
+require 'grpc'
+require_relative 'controlclient_pb'
+
+module Momento
+  # @private
+  class DeleteCacheResponseBuilder < ResponseBuilder
+    # Build a Momento::DeleteCacheResponse from a block of code
+    # which returns a Momento::ControlClient::DeleteCacheResponse..
+    #
+    # @return [Momento::DeleteCacheResponse]
+    # @raise [StandardError] when the exception is not recognized.
+    # @raise [TypeError] when the response is not recognized.
+    def from_block
+      response = yield
+    rescue *RESCUED_EXCEPTIONS => e
+      DeleteCacheResponse::Error.new(
+        exception: e, context: context
+      )
+    else
+      raise TypeError unless response.is_a?(::Momento::ControlClient::DeleteCacheResponse)
+
+      return DeleteCacheResponse::Success.new
+    end
+  end
+end

data/lib/momento/delete_response.rb

@@ -1,31 +1,22 @@
-require 'grpc'
-require 'momento/cacheclient_pb'
+require_relative 'response/error'
 
 module Momento
-  # Responses specific to delete.
+  # A response from deleting a key.
   class DeleteResponse < Response
-    def self.from_block
-      response = yield
-    rescue GRPC::BadStatus => e
-      Error.new(grpc_exception: e)
-    else
-      raise TypeError unless response.is_a?(Momento::CacheClient::DeleteResponse)
-
-      Success.new
-    end
-
+    # Was the key deleted?
+    # @return [Boolean]
     def success?
       false
     end
 
-    # The item was deleted from the cache.
+    # @private
     class Success < DeleteResponse
       def success?
         true
       end
     end
 
-    # There was an error deleting the item from the cache.
+    # @private
     class Error < DeleteResponse
       include Momento::Response::Error
     end

data/lib/momento/delete_response_builder.rb

@@ -0,0 +1,23 @@
+require 'grpc'
+require_relative 'cacheclient_pb'
+
+module Momento
+  # @private
+  class DeleteResponseBuilder < ResponseBuilder
+    # Build a Momento::DeleteResponse from a block of code
+    # which returns a Momento::CacheClient::DeleteResponse..
+    #
+    # @return [Momento::DeleteResponse]
+    # @raise [StandardError] when the exception is not recognized.
+    # @raise [TypeError] when the response is not recognized.
+    def from_block
+      response = yield
+    rescue *RESCUED_EXCEPTIONS => e
+      DeleteResponse::Error.new(exception: e, context: context)
+    else
+      raise TypeError unless response.is_a?(::Momento::CacheClient::DeleteResponse)
+
+      DeleteResponse::Success.new
+    end
+  end
+end

data/lib/momento/error/grpc_details.rb

@@ -0,0 +1,38 @@
+module Momento
+  module Error
+    # Details about a GRPC error.
+    # Returned by `response.error.transport_details.grpc`
+    #
+    # @example
+    #   # Information about the underlying GRPC error which
+    #   # caused a Momento error response.
+    #   puts response.error.transport_details.grpc.details
+    class GrpcDetails
+      # @return [GRPC::BadStatus] the GRPC exception
+      attr_reader :grpc
+
+      # @param grpc [GRPC::BadStatus] the GRPC exception to wrap
+      def initialize(grpc)
+        @grpc = grpc
+      end
+
+      # The GRPC numeric error code
+      # @return [Integer]
+      def code
+        grpc.code
+      end
+
+      # Any details about the error provided by GRPC
+      # @return [String]
+      def details
+        grpc.details
+      end
+
+      # Any metadata associated with the GRPC error
+      # @return [Hash]
+      def metadata
+        grpc.metadata
+      end
+    end
+  end
+end

data/lib/momento/error/transport_details.rb

@@ -0,0 +1,20 @@
+module Momento
+  module Error
+    # A class to capture information specific to particular transport layers.
+    #
+    # @example
+    #   # Information about the underlying GRPC error which
+    #   # caused a Momento error response.
+    #   puts response.error.transport_details.grpc.details
+    class TransportDetails
+      # Details specific to GRPC.
+      # @return [Momento::Error::GrpcDetails]
+      attr_reader :grpc
+
+      # param grpc [GRPC::BadStatus]
+      def initialize(grpc:)
+        @grpc = GrpcDetails.new(grpc)
+      end
+    end
+  end
+end

data/lib/momento/error/types.rb

@@ -0,0 +1,232 @@
+module Momento
+  module Error
+    # rubocop:disable Layout/LineLength
+
+    # A cache with the specified name already exists.
+    class AlreadyExistsError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :ALREADY_EXISTS_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "A cache with the specified name already exists.  To resolve this error, either delete the existing cache and make a new one, or use a different name.  Cache name: '#{context[:cache_name]}'"
+      end
+    end
+
+    # Invalid authentication credentials to connect to cache service
+    class AuthenticationError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :AUTHENTICATION_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "Invalid authentication credentials to connect to cache service: #{details}"
+      end
+    end
+
+    # The request was invalid.
+    class BadRequestError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :BAD_REQUEST_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "The request was invalid; please contact Momento: #{details}"
+      end
+    end
+
+    # The request was cancelled by the server.
+    class CancelledError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :CANCELLED_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "The request was cancelled by the server; please contact Momento: #{details}"
+      end
+    end
+
+    # A client resource (most likely memory) was exhausted.
+    class ClientResourceExhaustedError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :CLIENT_RESOURCE_EXHAUSTED
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "A client resource (most likely memory) was exhausted.  If you are executing a high volume of concurrent requests or using very large object sizes, your Configuration may need to be updated to allocate more memory.  Please contact Momento for assistance."
+      end
+    end
+
+    # System is not in a state required for the operation\'s execution
+    class FailedPreconditionError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :FAILED_PRECONDITION_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "System is not in a state required for the operation's execution"
+      end
+    end
+
+    # An unexpected error occurred while trying to fulfill the request.
+    class InternalServerError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :INTERNAL_SERVER_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "An unexpected error occurred while trying to fulfill the request; please contact Momento: #{details}"
+      end
+    end
+
+    # Invalid argument passed to Momento client
+    class InvalidArgumentError < ArgumentError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :INVALID_ARGUMENT_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "Invalid argument passed to Momento client: #{details}"
+      end
+    end
+
+    # Request rate exceeded the limits for this account.
+    class LimitExceededError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :LIMIT_EXCEEDED_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "Request rate exceeded the limits for this account.  To resolve this error, reduce your request rate, or contact Momento to request a limit increase."
+      end
+    end
+
+    # A cache with the specified name does not exist.
+    class NotFoundError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :NOT_FOUND_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "A cache with the specified name does not exist.  To resolve this error, make sure you have created the cache before attempting to use it.  Cache name: '#{context[:cache_name]}'"
+      end
+    end
+
+    # Insufficient permissions to perform an operation on a cache.
+    class PermissionError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :PERMISSION_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "Insufficient permissions to perform an operation on a cache: #{details}"
+      end
+    end
+
+    # The server was unable to handle the request
+    class ServerUnavailableError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :SERVER_UNAVAILABLE
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "The server was unable to handle the request; consider retrying.  If the error persists, please contact Momento."
+      end
+    end
+
+    # The client's configured timeout was exceeded.
+    class TimeoutError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :TIMEOUT_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "The client's configured timeout was exceeded; you may need to use a Configuration with more lenient timeouts.  Timeout value: #{context[:timeout]}"
+      end
+    end
+
+    # The cache service failed due to an internal error
+    class UnknownError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :UNKNOWN_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "CacheService failed due to an internal error"
+      end
+    end
+
+    # The cache service failed due to an internal error
+    class UnknownServiceError < RuntimeError
+      include Momento::Error
+
+      # (see Momento::Error#error_code)
+      def error_code
+        :UNKNOWN_SERVICE_ERROR
+      end
+
+      # (see Momento::Error#message)
+      def message
+        "The service returned an unknown response; please contact Momento: #{details}"
+      end
+    end
+
+    # rubocop:enable Layout/LineLength
+  end
+end

data/lib/momento/error.rb

@@ -0,0 +1,54 @@
+require_relative 'error/types'
+
+module Momento
+  # Errors from the Momento client or service, available as `response.error`.
+  #
+  # Momento::Errors are Exceptions. They can be raised. If the error was
+  # caused by an exception, it will be available in {#cause}.
+  #
+  # @example
+  #   # This is a contrived example to show what you can do with a Momento::Error.
+  #   response = client.cache_name(cache_name, key)
+  #   if response.error?
+  #     error = response.error
+  #
+  #     puts "Creating the cache failed: #{error}"
+  #     puts "The cause was #{error.cause}"
+  #     puts "The details of the error are #{error.details}"
+  #     puts "The error code is #{error.error_code}"
+  #
+  #     case error
+  #     when Momento::Error::LimitExceededError
+  #       puts "We'll have to slow down"
+  #     when Momento::Error::PermissionError
+  #       puts "We'll have to fix our auth token"
+  #     when Momento::Error::InvalidArgumentError
+  #       puts "We can't make a cache named #{cache_name}"
+  #     end
+  #
+  #     raise error
+  #   end
+  module Error
+    # @return [Exception] the original exception which was the cause of the error
+    attr_accessor :cause
+    # @return [Hash] any context relevant to the error such as method arguments
+    attr_accessor :context
+    # @return [Momento::Error::TransportDetails] details about the transport layer
+    attr_accessor :transport_details
+    # @return [String] details about the error
+    attr_accessor :details
+
+    # @!method error_code
+    #   A Momento-specific code for the type of error.
+    #   @return [Symbol]
+
+    # @!method message
+    #   The error message.
+    #   @return [String]
+
+    # (see #message)
+    def to_s
+      message
+    end
+  end
+end

data/lib/momento/error_builder.rb

@@ -0,0 +1,50 @@
+require 'grpc'
+require_relative 'error/types'
+require_relative 'exceptions'
+
+module Momento
+  # @private
+  class ErrorBuilder
+    EXCEPTION_MAP = {
+      GRPC::Aborted => Error::InternalServerError,
+      GRPC::AlreadyExists => Error::AlreadyExistsError,
+      GRPC::Cancelled => Error::CancelledError,
+      GRPC::DataLoss => Error::InternalServerError,
+      GRPC::DeadlineExceeded => Error::TimeoutError,
+      GRPC::FailedPrecondition => Error::FailedPreconditionError,
+      GRPC::Internal => Error::InternalServerError,
+      GRPC::InvalidArgument => Error::InvalidArgumentError,
+      GRPC::NotFound => Error::NotFoundError,
+      GRPC::OutOfRange => Error::BadRequestError,
+      GRPC::PermissionDenied => Error::PermissionError,
+      GRPC::ResourceExhausted => Error::LimitExceededError,
+      GRPC::Unauthenticated => Error::AuthenticationError,
+      GRPC::Unavailable => Error::ServerUnavailableError,
+      GRPC::Unimplemented => Error::BadRequestError,
+      GRPC::Unknown => Error::UnknownServiceError,
+      Momento::CacheNameError => Error::InvalidArgumentError
+    }.freeze
+
+    class << self
+      def from_exception(exception, context: {})
+        error_class = EXCEPTION_MAP[exception.class] || Error::UnknownError
+
+        error = error_class.new
+        error.context = context
+        error.cause = exception
+
+        case exception
+        when GRPC::BadStatus
+          error.transport_details = Error::TransportDetails.new(grpc: exception)
+          error.details = exception.details
+        else
+          error.details = exception.message
+        end
+
+        error.freeze
+
+        return error
+      end
+    end
+  end
+end

data/lib/momento/exceptions.rb

@@ -0,0 +1,7 @@
+module Momento
+  # Used to indicate an error in the cache name to be rescued
+  # and turned into an InvalidArgument respponse.
+  # @private
+  class CacheNameError < ::ArgumentError
+  end
+end