momento 0.1.0 → 0.2.0

data/lib/momento/get_response.rb

@@ -1,49 +1,43 @@
-require 'grpc'
-require 'momento/cacheclient_pb'
+require_relative 'response/error'
 
 module Momento
-  # Responses specific to get.
+  # A response containing the value retrieved from a cache.
   class GetResponse < Response
-    class << self
-      # Build a Momento::GetResponse from a block of code
-      # which returns a Momento::ControlClient::GetResponse.
-      #
-      # @return [Momento::GetResponse]
-      # @raise [StandardError] when the exception is not recognized.
-      # @raise [TypeError] when the response is not recognized.
-      def from_block
-        response = yield
-      rescue GRPC::BadStatus => e
-        Error.new(grpc_exception: e)
-      else
-        from_response(response)
-      end
-
-      private
-
-      def from_response(response)
-        raise TypeError unless response.is_a?(Momento::CacheClient::GetResponse)
-
-        case response.result
-        when :Hit
-          Hit.new(grpc_response: response)
-        when :Miss
-          Miss.new
-        else
-          raise "Unknown get result: #{response.result}"
-        end
-      end
-    end
-
+    # There was a value for the key.
+    # @return [Boolean]
     def hit?
       false
     end
 
+    # There was no value for the key.
+    # @return [Boolean]
     def miss?
       false
     end
 
-    # Successfully got an item from the cache.
+    # The gotten value, if any, as binary data: an ASCII_8BIT encoded frozen String.
+    #
+    # @return [String,nil] the value, if any, frozen and ASCII_8BIT encoded
+    def value_bytes
+      nil
+    end
+
+    # The gotten value, if any, as a string using your default encoding or specified one.
+    #
+    # @param encoding [Encoding] defaults to Encoding.default_external
+    # @return [String,nil] the value, if any, re-encoded
+    # rubocop:disable Lint/UnusedMethodArgument
+    def value_string(encoding = Encoding.default_external)
+      nil
+    end
+    # rubocop:enable Lint/UnusedMethodArgument
+
+    # @!method to_s
+    #   Displays the response and the value, if any.
+    #   A long value will be truncated.
+    #   @return [String]
+
+    # @private
     class Hit < GetResponse
       # rubocop:disable Lint/MissingSuper
       def initialize(grpc_response:)
@@ -55,24 +49,27 @@ module Momento
         true
       end
 
-      # @return [String] the value from the cache
-      def value
+      def value_bytes
         @grpc_response.cache_body
       end
 
+      def value_string(encoding = Encoding.default_external)
+        value_bytes.dup.force_encoding(encoding)
+      end
+
       def to_s
-        value
+        "#{super}: #{display_string(value_string)}"
       end
     end
 
-    # The key had no value stored in the cache.
+    # @private
     class Miss < GetResponse
       def miss?
         true
       end
     end
 
-    # There was a problem getting the value from the cache.
+    # @private
     class Error < GetResponse
       include Momento::Response::Error
     end

data/lib/momento/get_response_builder.rb

@@ -0,0 +1,37 @@
+require_relative 'response_builder'
+require_relative 'cacheclient_pb'
+require_relative 'get_response'
+
+module Momento
+  # @private
+  class GetResponseBuilder < ResponseBuilder
+    # Build a Momento::GetResponse from a block of code
+    # which returns a Momento::ControlClient::GetResponse.
+    #
+    # @return [Momento::GetResponse]
+    # @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
+      GetResponse::Error.new(exception: e, context: context)
+    else
+      from_response(response)
+    end
+
+    private
+
+    def from_response(response)
+      raise TypeError unless response.is_a?(Momento::CacheClient::GetResponse)
+
+      case response.result
+      when :Hit
+        GetResponse::Hit.new(grpc_response: response)
+      when :Miss
+        GetResponse::Miss.new
+      else
+        raise "Unknown get result: #{response.result}"
+      end
+    end
+  end
+end

data/lib/momento/list_caches_response.rb

@@ -1,31 +1,39 @@
-require 'grpc'
-require 'momento/controlclient_pb'
+require_relative 'response/error'
 
 module Momento
-  # Responses specific to list_caches.
+  # A response from listing the caches.
+  #
+  # Each response is a single page of caches, there may be additional pages.
+  # Use Momento::SimpleCacheClient#caches to efficiently get the whole list.
   class ListCachesResponse < Response
-    # Build a Momento::ListCachesResponse from a block of code
-    # which returns a Momento::ControlClient::ListCachesResponse.
-    #
-    # @return [Momento::ListCachesResponse]
-    # @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::ListCachesResponse)
-
-      return Success.new(grpc_response: response)
-    end
-
+    # Did it get a page of caches?
+    # @return [Boolean]
     def success?
       false
     end
 
-    # A Momento resposne with a page of caches.
+    # The names of the caches in this page.
+    # @return [Array,nil]
+    def cache_names
+      nil
+    end
+
+    # A token to fetch the next page.
+    # The last page will have a blank token.
+    # @return [String,nil]
+    def next_token
+      nil
+    end
+
+    # @!method to_s
+    #   Displays the response and the list of cache names.
+    #   The list of cache names will be truncated.
+    #   @return [String]
+
+    # @private
     class Success < ListCachesResponse
+      CACHE_NAMES_TO_DISPLAY = 5
+
       # rubocop:disable Lint/MissingSuper
       def initialize(grpc_response:)
         @grpc_response = grpc_response
@@ -43,9 +51,25 @@ module Momento
       def next_token
         @grpc_response.next_token
       end
+
+      def to_s
+        "#{super}: #{display_cache_names}"
+      end
+
+      private
+
+      def display_cache_names
+        display = cache_names.first(CACHE_NAMES_TO_DISPLAY).join(", ")
+
+        if cache_names.size > CACHE_NAMES_TO_DISPLAY
+          "#{display}, ..."
+        else
+          display
+        end
+      end
     end
 
-    # There was an error listing the caches.
+    # @private
     class Error < ListCachesResponse
       include ::Momento::Response::Error
     end

data/lib/momento/list_caches_response_builder.rb

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

data/lib/momento/response/error.rb

@@ -1,16 +1,23 @@
 module Momento
   class Response
     # A module for responses which contain errors.
+    # @private
     module Error
-      attr_accessor :grpc_exception
+      attr_reader :error
 
-      def initialize(grpc_exception:)
-        @grpc_exception = grpc_exception
+      def initialize(exception:, context: {})
+        @error = Momento::ErrorBuilder.from_exception(
+          exception, context: context
+        ).freeze
       end
 
       def error?
         true
       end
+
+      def to_s
+        "#{super}: #{error.message}"
+      end
     end
   end
 end

data/lib/momento/response.rb

@@ -1,17 +1,70 @@
 require 'grpc'
 require_relative 'response/error'
+require_relative 'error'
+require_relative 'error/grpc_details'
+require_relative 'error/transport_details'
+require_relative 'error_builder'
+require_relative 'response_builder'
 require_relative 'create_cache_response'
+require_relative 'create_cache_response_builder'
 require_relative 'delete_response'
+require_relative 'delete_response_builder'
 require_relative 'delete_cache_response'
+require_relative 'delete_cache_response_builder'
 require_relative 'get_response'
+require_relative 'get_response_builder'
 require_relative 'list_caches_response'
+require_relative 'list_caches_response_builder'
 require_relative 'set_response'
+require_relative 'set_response_builder'
 
 module Momento
-  # A superclass for all Momento responses.
+  # The response from a Momento service request.
+  #
+  # {Momento::SimpleCacheClient} returns a response for both success
+  # and error, as well as other states. See the documenation for each
+  # type of response for more.
+  #
+  # You can always check for an error response with
+  # `response.error?` and get the error itself with `response.error`.
+  #
+  # `response.error` is an Exception and can be raised. It contains
+  # additional information about the error, see {Momento::Error} for
+  # more information.
+  #
+  # @see Momento::Error
   class Response
+    MAX_STRING_DISPLAY_LENGTH = 32
+    private_constant :MAX_STRING_DISPLAY_LENGTH
+
+    # Returns the error portion of the response, if any.
+    #
+    # @return [Momento::Error, nil]
+    def error
+      nil
+    end
+
+    # Is the response an error?
+    #
+    # @return [Boolean]
     def error?
       false
     end
+
+    # Displays the type of response and additional info, if any.
+    # @return [String]
+    def to_s
+      self.class.to_s
+    end
+
+    protected
+
+    def display_string(string, max_length: MAX_STRING_DISPLAY_LENGTH)
+      if string.length < max_length
+        string
+      else
+        "#{string[0, max_length]}..."
+      end
+    end
   end
 end

data/lib/momento/response_builder.rb

@@ -0,0 +1,18 @@
+module Momento
+  # A superclass for building responses.
+  #
+  # @private
+  class ResponseBuilder
+    attr_accessor :context
+
+    RESCUED_EXCEPTIONS = ErrorBuilder::EXCEPTION_MAP.keys.freeze
+
+    def initialize(context: {})
+      @context = context
+    end
+
+    def from_block
+      raise NotImplementedError
+    end
+  end
+end

data/lib/momento/set_response.rb

@@ -1,37 +1,37 @@
-require 'grpc'
-require 'momento/cacheclient_pb'
+require_relative 'response/error'
 
 module Momento
-  # Responses specific to set.
+  # A response from setting a key.
   class SetResponse < Response
-    # Build a Momento::SetResponse from a block of code
-    # which returns a Momento::ControlClient::SetResponse.
-    #
-    # @return [Momento::SetResponse]
-    # @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::CacheClient::SetResponse)
-
-      Success.new
-    end
-
+    # Was the key/value pair added to the cache?
+    # @return [Boolean]
     def success?
       false
     end
 
-    # The item was set.
+    # @private
     class Success < SetResponse
+      attr_accessor :key, :value
+
+      # rubocop:disable Lint/MissingSuper
+      def initialize(key:, value:)
+        @key = key
+        @value = value
+
+        return
+      end
+      # rubocop:enable Lint/MissingSuper
+
       def success?
         true
       end
+
+      def to_s
+        "#{super}: '#{display_string(key)}' = '#{display_string(value)}'"
+      end
     end
 
-    # There was an error setting the item.
+    # @private
     class Error < SetResponse
       include Momento::Response::Error
     end

data/lib/momento/set_response_builder.rb

@@ -0,0 +1,25 @@
+require 'grpc'
+require_relative 'cacheclient_pb'
+
+module Momento
+  # Builds SetResponses
+  #
+  # @private
+  class SetResponseBuilder < ResponseBuilder
+    # Build a Momento::SetResponse from a block of code
+    # which returns a Momento::CacheClient::SetResponse..
+    #
+    # @return [Momento::SetResponse]
+    # @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
+      SetResponse::Error.new(exception: e, context: context)
+    else
+      raise TypeError unless response.is_a?(::Momento::CacheClient::SetResponse)
+
+      SetResponse::Success.new(key: context[:key], value: context[:value])
+    end
+  end
+end