gruf 1.1.0 → 1.2.0

data/lib/gruf/client.rb

@@ -15,22 +15,56 @@
 # OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Gruf
+  ##
+  # Abstracts out the calling interface for interacting with gRPC clients. Streamlines calling and provides
+  # instrumented response objects that also can contain deserialized error messages via serialized objects transported
+  # via the service's trailing metadata.
+  #
+  #   begin
+  #     client = ::Gruf::Client.new(service: ::Demo::ThingService)
+  #     response = client.call(:GetMyThing, id: 123)
+  #     puts response.message.inspect
+  #   rescue Gruf::Client::Error => e
+  #     puts e.error.inspect
+  #   end
+  #
+  # Utilizes SimpleDelegator to wrap the given service that the client is connecting to, which allows a clean interface
+  # to the underlying RPC descriptors and methods.
+  #
   class Client < SimpleDelegator
     include Gruf::Loggable
 
+    ##
+    # Represents an error that was returned from the server's trailing metadata. Used as a custom exception object
+    # that is instead raised in the case of the service returning serialized error data, as opposed to the normal
+    # GRPC::BadStatus error
+    #
     class Error < StandardError
+      # @return [Object] error The deserialized error
       attr_reader :error
 
+      ##
+      # Initialize the client error
+      #
+      # @param [Object] error The deserialized error
+      #
       def initialize(error)
         @error = error
       end
     end
 
-    attr_reader :base_klass, :service_klass, :opts
+    # @return [Class] The base, friendly name of the service being requested
+    attr_reader :base_klass
+    # @return [Class] The class name of the gRPC service being requested
+    attr_reader :service_klass
+    # @return [Hash] A hash of options for the client
+    attr_reader :opts
 
     ##
+    # Initialize the client and setup the stub
+    #
     # @param [Module] service The namespace of the client Stub that is desired to load
-    # @param [Hash] options
+    # @param [Hash] options A hash of options for the client
     # @option options [String] :password The password for basic authentication for the service.
     # @option options [String] :hostname The hostname of the service. Defaults to linkerd.
     #
@@ -47,7 +81,16 @@ module Gruf
     ##
     # Call the client's method with given params
     #
+    # @param [String|Symbol] request_method The method that is being requested on the service
+    # @param [Hash] params (Optional) A hash of parameters that will be inserted into the gRPC request message that is required
+    # for the given above call
+    # @param [Hash] metadata (Optional) A hash of metadata key/values that are transported with the client request
+    # @param [Hash] opts (Optional) A hash of options to send to the gRPC request_response method
+    # @return [Gruf::Response] The response from the server
+    # @raise [Gruf::Client::Error|GRPC::BadStatus] If an error occurs, an exception will be raised according to the
+    # error type that was returned
     def call(request_method, params = {}, metadata = {}, opts = {})
+      request_method = request_method.to_sym
       req = request_object(request_method, params)
       md = build_metadata(metadata)
       call_sig = call_signature(request_method)
@@ -64,11 +107,14 @@ module Gruf
     private
 
     ##
+    # Execute the given request to the service
+    #
     # @param [Symbol] call_sig The call signature being executed
-    # @param [Object] req
-    # @param [Hash] md
+    # @param [Object] req (Optional) The protobuf request message to send
+    # @param [Hash] md (Optional) A hash of metadata key/values that are transported with the client request
+    # @param [Hash] opts (Optional) A hash of options to send to the gRPC request_response method
     #
-    def execute(call_sig, req, md, opts)
+    def execute(call_sig, req, md, opts = {})
       timed = Timer.time do
         opts[:return_op] = true
         opts[:metadata] = md
@@ -78,14 +124,21 @@ module Gruf
     end
 
     ##
-    # @return [Struct<GRPC::RpcDesc>]
+    # Get the appropriate RPC descriptor given the method on the service being called
+    #
+    # @param [Symbol] request_method The method name being called on the remote service
+    # @return [Struct<GRPC::RpcDesc>] Return the given RPC descriptor given the method on the service being called
     #
     def rpc_desc(request_method)
-      service_klass.rpc_descs[request_method.to_sym]
+      service_klass.rpc_descs[request_method]
     end
 
     ##
-    # @return [Class] The request object
+    # Get the appropriate protobuf request message for the given request method on the service being called
+    #
+    # @param [Symbol] request_method The method name being called on the remote service
+    # @param [Hash] params (Optional) A hash of parameters that will populate the request object
+    # @return [Class] The request object that corresponds to the method being called
     #
     def request_object(request_method, params = {})
       desc = rpc_desc(request_method)
@@ -93,6 +146,8 @@ module Gruf
     end
 
     ##
+    # Properly find the appropriate call signature for the GRPC::GenericService given the request method name
+    #
     # @return [Symbol]
     #
     def call_signature(request_method)
@@ -101,7 +156,10 @@ module Gruf
     end
 
     ##
-    # @return [Hash]
+    # Build a sanitized, authenticated metadata hash for the given request
+    #
+    # @param [Hash] metadata A base metadata hash to build from
+    # @return [Hash] The compiled metadata hash that is ready to be transported over the wire
     #
     def build_metadata(metadata = {})
       unless opts[:password].empty?
@@ -114,7 +172,9 @@ module Gruf
     end
 
     ##
-    # @return [Symbol|GRPC::Core::ChannelCredentials]
+    # Build the SSL/TLS credentials for the outbound gRPC request
+    #
+    # @return [Symbol|GRPC::Core::ChannelCredentials] The generated SSL credentials for the outbound gRPC request
     #
     # :nocov:
     def build_ssl_credentials
@@ -130,7 +190,9 @@ module Gruf
     # :nocov:
 
     ##
-    # @return [Class]
+    # Return the specified error deserializer class by the configuration
+    #
+    # @return [Class] The proper error deserializer class. Defaults to JSON.
     #
     def error_deserializer_class
       if Gruf.error_serializer

data/lib/gruf/configuration.rb

@@ -38,7 +38,9 @@ module Gruf
       authorization_metadata_key: 'authorization',
       append_server_errors_to_trailing_metadata: true,
       use_default_hooks: true,
-      backtrace_on_error: false
+      backtrace_on_error: false,
+      use_exception_message: true,
+      internal_error_message: 'Internal Server Error'
     }.freeze
 
     attr_accessor *VALID_CONFIG_KEYS.keys
@@ -53,8 +55,8 @@ module Gruf
     ##
     # Yield self for ruby-style initialization
     #
-    # @yields [Gruf::Configuration]
-    # @return [Gruf::Configuration]
+    # @yields [Gruf::Configuration] The configuration object for gruf
+    # @return [Gruf::Configuration] The configuration object for gruf
     #
     def configure
       yield self
@@ -63,7 +65,7 @@ module Gruf
     ##
     # Return the current configuration options as a Hash
     #
-    # @return [Hash]
+    # @return [Hash] The configuration for gruf, represented as a Hash
     #
     def options
       opts = {}
@@ -80,7 +82,7 @@ module Gruf
     #
     def reset
       VALID_CONFIG_KEYS.each do |k, v|
-        send((k.to_s + '=').to_sym, v)
+        send((k.to_s + '='), v)
       end
       if defined?(Rails) && Rails.logger
         self.root_path = Rails.root
@@ -102,6 +104,7 @@ module Gruf
       if use_default_hooks
         Gruf::Hooks::Registry.add(:ar_connection_reset, Gruf::Hooks::ActiveRecord::ConnectionReset)
         Gruf::Instrumentation::Registry.add(:output_metadata_timer, Gruf::Instrumentation::OutputMetadataTimer)
+        Gruf::Instrumentation::Registry.add(:request_logging, Gruf::Instrumentation::RequestLogging::Hook)
       end
       options
     end
@@ -111,7 +114,7 @@ module Gruf
     ##
     # Automatically determine environment
     #
-    # @return [String]
+    # @return [String] The current Ruby environment
     #
     def environment
       if defined?(Rails)

data/lib/gruf/error.rb

@@ -28,6 +28,7 @@ module Gruf
   class Error
     include Gruf::Loggable
 
+    # @return [Hash<GRPC::BadStatus>] A hash mapping of gRPC BadStatus codes to error symbols
     TYPES = {
       ok: GRPC::Ok,
       cancelled: GRPC::Cancelled,
@@ -50,15 +51,30 @@ module Gruf
       data_loss: GRPC::DataLoss
     }.freeze
 
-    attr_accessor :code, :app_code, :message, :field_errors, :debug_info, :grpc_error
+    # @return [Symbol] The given internal gRPC code for the error
+    attr_accessor :code
+    # @return [Symbol] An arbitrary application code that can be used for logical processing of the error by the client
+    attr_accessor :app_code
+    # @return [String] The error message returned by the server
+    attr_accessor :message
+    # @return [Array] An array of field errors that can be returned by the server
+    attr_accessor :field_errors
+    # @return [Object] A hash of debugging information, such as a stack trace and exception name, that can be used to
+    # debug an given error response. This is sent by the server over the trailing metadata.
+    attr_accessor :debug_info
+    # @return [GRPC::BadStatus] The gRPC BadStatus error object that was generated
+    attr_accessor :grpc_error
+    # @return [Hash] The trailing metadata that was attached to the error
     attr_reader :metadata
 
     ##
     # Initialize the error, setting default values
     #
+    # @param [Hash] args (Optional) An optional hash of arguments that will set fields on the error object
+    #
     def initialize(args = {})
       args.each do |k, v|
-        send("#{k.to_sym}=", v) if respond_to?(k.to_sym)
+        send("#{k}=", v) if respond_to?(k)
       end
       @field_errors = []
     end
@@ -66,24 +82,29 @@ module Gruf
     ##
     # Add a field error to this error package
     #
-    # @param [Symbol] field_name
-    # @param [Symbol] error_code
-    # @param [String] message
+    # @param [Symbol] field_name The field name for the error
+    # @param [Symbol] error_code The application error code for the error; e.g. :job_not_found
+    # @param [String] message The application error message for the error; e.g. "Job not found with ID 123"
     #
     def add_field_error(field_name, error_code, message = '')
       @field_errors << Errors::Field.new(field_name, error_code, message)
     end
 
     ##
-    # @param [String] detail
-    # @param [Array<String>] stack_trace
+    # Set the debugging information for the error message
+    #
+    # @param [String] detail The detailed message generated by the exception
+    # @param [Array<String>] stack_trace An array of strings that represents the exception backtrace generated by the
+    # service
     #
     def set_debug_info(detail, stack_trace = [])
       @debug_info = Errors::DebugInfo.new(detail, stack_trace)
     end
 
     ##
-    # Ensure all metadata values are strings
+    # Ensure all metadata values are strings as HTTP/2 requires string values for transport
+    #
+    # @return [Hash] The newly set metadata
     #
     def metadata=(md)
       @metadata = md.map { |k, str| [k, str.to_s] }.to_h
@@ -92,7 +113,7 @@ module Gruf
     ##
     # Serialize the error for transport
     #
-    # @return [String]
+    # @return [String] The serialized error message
     #
     def serialize
       serializer = serializer_class.new(self)
@@ -100,8 +121,10 @@ module Gruf
     end
 
     ##
-    # @param [GRPC::ActiveCall]
-    # @return [Error]
+    # Append any appropriate errors to the gRPC call and properly update the output metadata
+    #
+    # @param [GRPC::ActiveCall] active_call The marshalled gRPC call
+    # @return [Error] Return the error itself with the GRPC::ActiveCall attached and error metadata appended
     #
     def attach_to_call(active_call)
       metadata[Gruf.error_metadata_key.to_sym] = serialize if Gruf.append_server_errors_to_trailing_metadata
@@ -112,15 +135,20 @@ module Gruf
     end
 
     ##
-    # @param [GRPC::ActiveCall]
-    # @return [GRPC::BadStatus]
+    # Fail the current gRPC call with the given error, properly attaching it to the call and raising the appropriate
+    # gRPC BadStatus code.
+    #
+    # @param [GRPC::ActiveCall] active_call The marshalled gRPC call
+    # @return [GRPC::BadStatus] The gRPC BadStatus code this error is mapped to
     #
     def fail!(active_call)
       raise attach_to_call(active_call).grpc_error
     end
 
     ##
-    # @return [Hash]
+    # Return the error represented in Hash form
+    #
+    # @return [Hash] The error as a hash
     #
     def to_h
       {
@@ -133,6 +161,8 @@ module Gruf
     end
 
     ##
+    # Return the appropriately mapped GRPC::BadStatus error object for this error
+    #
     # @return [GRPC::BadStatus]
     #
     def grpc_error
@@ -142,6 +172,8 @@ module Gruf
     private
 
     ##
+    # Return the error serializer being used for gruf
+    #
     # @return [Gruf::Serializers::Errors::Base]
     #
     def serializer_class
@@ -153,7 +185,9 @@ module Gruf
     end
 
     ##
-    # @return [Class]
+    # Return the appropriate gRPC class for the given error code
+    #
+    # @return [Class] The gRPC error class
     #
     def grpc_class
       TYPES[code]

data/lib/gruf/errors/debug_info.rb

@@ -17,14 +17,17 @@
 module Gruf
   module Errors
     ##
-    # Represents debugging information
+    # Represents debugging information for an exception that occurred in a gRPC service
     #
     class DebugInfo
-      attr_reader :detail, :stack_trace
+      # @return [String] The detail message of the exception
+      attr_reader :detail
+      # @return [Array<String>] The stack trace generated by the exception as an array of strings
+      attr_reader :stack_trace
 
       ##
-      # @param [String] detail
-      # @param [Array<String>] stack_trace
+      # @param [String] detail The detail message of the exception
+      # @param [Array<String>] stack_trace The stack trace generated by the exception as an array of strings
       #
       def initialize(detail, stack_trace = [])
         @detail = detail
@@ -32,7 +35,9 @@ module Gruf
       end
 
       ##
-      # @return [Hash]
+      # Return this object marshalled into a hash
+      #
+      # @return [Hash] The debug info represented as a has
       #
       def to_h
         {

data/lib/gruf/errors/field.rb

@@ -20,12 +20,17 @@ module Gruf
     # Represents a field-specific error
     #
     class Field
-      attr_reader :field_name, :error_code, :message
+      # @return [Symbol] The name of the field as a Symbol
+      attr_reader :field_name
+      # @return [Symbol] The application error code for the field, e.g. :job_not_found
+      attr_reader :error_code
+      # @return [String] The error message for the field, e.g. "Job with ID 123 not found"
+      attr_reader :message
 
       ##
-      # @param [Symbol] field_name
-      # @param [Symbol] error_code
-      # @param [String] message
+      # @param [Symbol] field_name The name of the field as a Symbol
+      # @param [Symbol] error_code The application error code for the field, e.g. :job_not_found
+      # @param [String] message (Optional) The error message for the field, e.g. "Job with ID 123 not found"
       #
       def initialize(field_name, error_code, message = '')
         @field_name = field_name
@@ -34,7 +39,9 @@ module Gruf
       end
 
       ##
-      # @return [Hash]
+      # Return the field error represented as a hash
+      #
+      # @return [Hash] The error represented as a hash
       #
       def to_h
         {

data/lib/gruf/hooks/active_record/connection_reset.rb

@@ -21,12 +21,26 @@ module Gruf
       # Resets the ActiveRecord connection to maintain accurate connected state in the thread pool
       #
       class ConnectionReset < Gruf::Hooks::Base
-        def after(_success, _response, _call_signature, _req, _call)
+        ##
+        # Reset any ActiveRecord connections after a gRPC service is called. Because of the way gRPC manages its
+        # connection pool, we need to ensure that this is done to properly
+        #
+        # @param [Boolean] _success Whether or not the call was successful
+        # @param [Object] _response The protobuf response object
+        # @param [Symbol] _call_signature The gRPC method on the service that was called
+        # @param [Object] _request The protobuf request object
+        # @param [GRPC::ActiveCall] _call the gRPC core active call object, which represents marshalled data for
+        # the call itself
+        #
+        def after(_success, _response, _call_signature, _request, _call)
           ::ActiveRecord::Base.clear_active_connections! if enabled?
         end
 
         private
 
+        ##
+        # @return [Boolean] If AR is loaded, we can enable this hook safely
+        #
         def enabled?
           defined?(::ActiveRecord::Base)
         end