gruf 1.1.0 → 1.2.0

data/lib/gruf/server.rb

@@ -22,8 +22,14 @@ module Gruf
   class Server
     include Gruf::Loggable
 
+    # @return [Array<Class>] The services this server is handling
     attr_accessor :services
 
+    ##
+    # Initialize the server and load and setup the services
+    #
+    # @param [Array<Class>] services The services that this server should handle
+    #
     def initialize(services: [])
       setup!
       load_services(services)
@@ -50,8 +56,8 @@ module Gruf
     ##
     # Return all loaded gRPC services
     #
-    # @param [Array<Class>] svcs
-    # @return [Array<Class>]
+    # @param [Array<Class>] svcs An array of service classes that will be handled by this server
+    # @return [Array<Class>] The given services that were added
     #
     def load_services(svcs)
       unless @services
@@ -74,6 +80,8 @@ module Gruf
     # :nocov:
 
     ##
+    # Load the SSL/TLS credentials for this server
+    #
     # @return [GRPC::Core::ServerCredentials|Symbol]
     #
     # :nocov:

data/lib/gruf/service.rb

@@ -16,7 +16,10 @@
 #
 module Gruf
   ##
-  # Module for gRPC endpoints
+  # Module for gRPC endpoints. Include this in any gRPC service you wish Gruf to serve. It will automatically mount
+  # it to the given gruf server and can be run via the command:
+  #
+  #  bundle exec gruf
   #
   module Service
     extend ActiveSupport::Concern
@@ -37,7 +40,7 @@ module Gruf
         without = :"#{method_name}_without_intercept"
         @__last_methods_added = [method_name, with, without]
         define_method with do |*args, &block|
-          call_chain(without, args[0], args[1], &block)
+          call_chain(method_name, args[0], args[1], &block)
         end
         alias_method without, method_name
         alias_method method_name, with
@@ -122,6 +125,12 @@ module Gruf
     #
     def outer_around_call(call_signature, req, call, &block)
       outer_around_hooks = []
+
+      # run instrumentation hooks as outer_around calls
+      Gruf::Instrumentation::Registry.each do |_name, h|
+        outer_around_hooks << h.new(self, Gruf.instrumentation_options)
+      end
+
       Gruf::Hooks::Registry.each do |_name, h|
         outer_around_hooks << h.new(self, Gruf.hook_options) if h.instance_methods.include?(:outer_around)
       end
@@ -187,7 +196,6 @@ module Gruf
     # @param [Symbol] app_code The application-specific code for the error
     # @param [String] message (Optional) A detail message about the error
     # @param [Hash] metadata (Optional) Any metadata to inject into the trailing metadata for the response
-    # @return [RPC::Error]
     #
     def fail!(_req, call, error_code, app_code = nil, message = '', metadata = {})
       error.code = error_code.to_sym
@@ -202,41 +210,43 @@ module Gruf
     ##
     # Encapsulate the call chain to provide before/around/after hooks
     #
-    # @param [Symbol] original_call_sig The original call signature for the service
+    # @param [String] original_call_sig The original call signature for the service
     # @param [Object] req The request object
     # @param [GRPC::ActiveCall] call The ActiveCall object being executed
     # @return [Object] The response object
     #
     def call_chain(original_call_sig, req, call, &block)
       outer_around_call(original_call_sig, req, call) do
-        before_call(original_call_sig, req, call)
-        timed = Timer.time do
-          around_call(original_call_sig, req, call) do
-            send(original_call_sig, req, call, &block) # send the actual request to gRPC
-          end
-        end
-        after_call(timed.success?, timed.result, original_call_sig, req, call)
+        begin
+          before_call(original_call_sig, req, call)
 
-        Gruf::Instrumentation::Registry.each do |_name, h|
-          h.new(self, req, timed.result, timed.time, original_call_sig, call, Gruf.instrumentation_options).call
+          result = around_call(original_call_sig, req, call) do
+            send("#{original_call_sig}_without_intercept", req, call, &block) # send the actual request to gRPC
+          end
+        rescue GRPC::BadStatus => e
+          result = e
         end
+        success = !result.is_a?(GRPC::BadStatus)
+        after_call(success, result, original_call_sig, req, call)
 
-        raise timed.result unless timed.success?
+        raise result unless success
 
-        timed.result
+        result
       end
+    rescue GRPC::BadStatus
+      raise
     rescue => e
-      raise e if e.is_a?(GRPC::BadStatus)
       set_debug_info(e.message, e.backtrace) if Gruf.backtrace_on_error
-      fail!(req, call, :internal, :unknown, e.message)
+      error_message = Gruf.use_exception_message ? e.message : Gruf.internal_error_message
+      fail!(req, call, :internal, :unknown, error_message)
     end
 
     ##
     # Add a field error to this endpoint
     #
-    # @param [Symbol] field_name
-    # @param [Symbol] error_code
-    # @param [String] message
+    # @param [Symbol] field_name The name of the field
+    # @param [Symbol] error_code The application error code for the field
+    # @param [String] message A given error message for the field
     #
     def add_field_error(field_name, error_code, message = '')
       error.add_field_error(field_name, error_code, message)
@@ -245,7 +255,7 @@ module Gruf
     ##
     # Return true if there are any present field errors
     #
-    # @return [Boolean]
+    # @return [Boolean] True if the service has any field errors
     #
     def has_field_errors?
       error.field_errors.any?
@@ -262,7 +272,7 @@ module Gruf
     end
 
     ##
-    # @return [Gruf::Error]
+    # @return [Gruf::Error] The generated gruf error object
     #
     def error
       @error ||= Gruf::Error.new

data/lib/gruf/timer.rb

@@ -15,15 +15,30 @@
 # OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Gruf
+  ##
+  # Times a given block and returns the result and the elapsed time as a Float
+  #
+  #   result = Timer.time { do_my_thing }
+  #
   class Timer
-
+    ##
+    # Represents a timer result that contains both the elapsed time and the result of the block
+    #
+    #   result = Timer.time { do_my_thing }
+    #   result.time # => 1.10123
+    #   result.result # => 'my_thing_is_done'
+    #
     class Result
+      # @return [Object] result The result of the block that was called
       attr_reader :result
+      # @return [Float] time The time, in ms, of the block execution
       attr_reader :time
 
       ##
-      # @param [Object] result
-      # @param [Float] time
+      # Initialize the result object
+      #
+      # @param [Object] result The result of the block that was called
+      # @param [Float] time The time, in ms, of the block execution
       #
       def initialize(result, time)
         @result = result
@@ -31,7 +46,9 @@ module Gruf
       end
 
       ##
-      # @return [Boolean]
+      # Was this result a successful result?
+      #
+      # @return [Boolean] Whether or not this result was a success
       #
       def success?
         !result.is_a?(GRPC::BadStatus)
@@ -39,7 +56,11 @@ module Gruf
     end
 
     ##
-    # @return [Timer::Result]
+    # Times a given block by recording start and end times
+    #
+    #  result = Timer.time { do_my_thing }
+    #
+    # @return [Timer::Result] Returns the timed result of the block
     #
     def self.time
       start_time = Time.now

data/lib/gruf/version.rb

@@ -15,5 +15,5 @@
 # OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 #
 module Gruf
-  VERSION = '1.1.0'.freeze
+  VERSION = '1.2.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gruf
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Shaun McCormick
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-07-11 00:00:00.000000000 Z
+date: 2017-08-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -124,6 +124,11 @@ files:
 - lib/gruf/instrumentation/base.rb
 - lib/gruf/instrumentation/output_metadata_timer.rb
 - lib/gruf/instrumentation/registry.rb
+- lib/gruf/instrumentation/request_context.rb
+- lib/gruf/instrumentation/request_logging/formatters/base.rb
+- lib/gruf/instrumentation/request_logging/formatters/logstash.rb
+- lib/gruf/instrumentation/request_logging/formatters/plain.rb
+- lib/gruf/instrumentation/request_logging/hook.rb
 - lib/gruf/instrumentation/statsd.rb
 - lib/gruf/loggable.rb
 - lib/gruf/logging.rb