thtp 0.1.0

data/lib/thtp/client/instrumentation.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'thtp/utils'
+
+module THTP
+  class Client
+    module Instrumentation
+      # Automagic instrumentation for all outbound RPCs as a THTP::Client middleware
+      class Metrics
+        OUTBOUND_RPC_STAT = 'rpc.outgoing'
+
+        SUCCESS_TAG = 'rpc.status:success' # everything is ok
+        EXCEPTION_TAG = 'rpc.status:exception' # schema-defined (expected) exception
+        ERROR_TAG = 'rpc.status:error' # unexpected error
+        INTERNAL_ERROR_TAG = 'rpc.status:internal_error'
+
+        def initialize(app, from:, to:, statsd:)
+          unless defined?(Datadog::Statsd) && statsd.is_a?(Datadog::Statsd)
+            raise ArgumentError, "Only dogstatsd is supported, not #{statsd.class.name}"
+          end
+          @app = app
+          @statsd = statsd
+          @base_tags = ["rpc.from:#{from}", "rpc.to:#{to}"]
+        end
+
+        def call(rpc, *rpc_args, **rpc_opts)
+          start = Utils.get_time
+          status_tag = SUCCESS_TAG
+          error_tag = nil
+          @app.call(rpc, *rpc_args, **rpc_opts)
+        rescue Thrift::Exception => e
+          status_tag = EXCEPTION_TAG
+          error_tag = "rpc.exception:#{e.class.name.underscore}"
+          raise
+        rescue => e
+          status_tag = ERROR_TAG
+          error_tag = "rpc.error:#{e.class.name.underscore}"
+          raise
+        ensure
+          tags = ["rpc:#{rpc}", status_tag, error_tag, *@base_tags].compact
+          @statsd.timing(OUTBOUND_RPC_STAT, Utils.elapsed_ms(start), tags: tags)
+        end
+      end
+    end
+  end
+end

data/lib/thtp/client/middleware.rb

@@ -0,0 +1,27 @@
+require 'thrift'
+require 'thtp/errors'
+
+module THTP
+  class Client
+    module Middleware
+      # Raise Thrift validation issues as their own detectable error type, rather
+      # than just ProtocolException.
+      class SchemaValidation
+        def initialize(app)
+          require 'thrift/validator' # if you don't have it, you'll need it
+          @app = app
+          @validator = Thrift::Validator.new
+        end
+
+        # Raises a ValidationError if any part of the request or response did not
+        # match the schema
+        def call(rpc, *rpc_args, **rpc_opts)
+          @validator.validate(rpc_args)
+          @app.call(rpc, *rpc_args, **rpc_opts).tap { |resp| @validator.validate(resp) }
+        rescue Thrift::ProtocolException => e
+          raise ClientValidationError, e.message
+        end
+      end
+    end
+  end
+end

data/lib/thtp/encoding.rb

@@ -0,0 +1,32 @@
+require 'thrift'
+
+module THTP
+  # Handling of registered MIME types and protocols
+  module Encoding
+    BINARY = 'application/vnd.apache.thrift.binary'.freeze
+    COMPACT = 'application/vnd.apache.thrift.compact'.freeze
+    JSON = 'application/vnd.apache.thrift.json'.freeze
+
+    def self.protocol(content_type)
+      case content_type
+      when BINARY
+        Thrift::BinaryProtocol
+      when COMPACT
+        Thrift::CompactProtocol
+      when JSON
+        Thrift::JsonProtocol
+      end
+    end
+
+    def self.content_type(protocol)
+      # this can't be a case/when because Class !=== Class
+      if protocol == Thrift::BinaryProtocol
+        BINARY
+      elsif protocol == Thrift::CompactProtocol
+        COMPACT
+      elsif protocol == Thrift::JsonProtocol
+        JSON
+      end
+    end
+  end
+end

data/lib/thtp/errors.rb

@@ -0,0 +1,143 @@
+require 'thrift'
+
+module THTP
+  # Parent class of all THTP errors
+  class Error < StandardError; end
+
+  # parent class for all errors during RPC execution;
+  # serializable as a Thrift::ApplicationException
+  class ServerError < Error
+    # @return [Thrift::ApplicationExceptionType]
+    def self.type
+      Thrift::ApplicationException::UNKNOWN
+    end
+
+    # @return [Thrift::ApplicationException] a serialisable Thrift exception
+    def to_thrift
+      Thrift::ApplicationException.new(self.class.type, message)
+    end
+  end
+
+  # parent class for all errors during RPC calls
+  class ClientError < Error; end
+
+  # Indicates an unrecognised or inappropriate RPC request format
+  class BadRequestError < ServerError
+    def self.type
+      Thrift::ApplicationException::UNKNOWN_METHOD
+    end
+
+    def initialize
+      super 'Calls must be made as POSTs to /:service/:rpc'
+    end
+  end
+
+  # Indicates a well-formatted request for an RPC that does not exist
+  class UnknownRpcError < ServerError
+    def self.type
+      Thrift::ApplicationException::WRONG_METHOD_NAME
+    end
+
+    # @param rpc [String] the RPC requested
+    def initialize(rpc)
+      super "Unknown RPC '#{rpc}'"
+    end
+  end
+
+  # We don't recognise the response (client & server schemas don't match, or it's just invalid)
+  class BadResponseError < ServerError
+    def self.type
+      Thrift::ApplicationException::MISSING_RESULT
+    end
+
+    def initialize(rpc, response = nil)
+      super "#{rpc} failed: unknown result#{": '#{response.inspect}'" if response}"
+    end
+  end
+
+  # Indicates a failure to turn a value into Thrift bytes according to schema
+  class SerializationError < ServerError
+    def self.type
+      Thrift::ApplicationException::PROTOCOL_ERROR
+    end
+
+    # @param error [StandardError] the exception encountered while serialising
+    def initialize(error)
+      super friendly_message(error)
+    end
+
+    private
+
+    def friendly_type(error)
+      return :other unless error.respond_to?(:type)
+      {
+        1 => :invalid_data,
+        2 => :negative_size,
+        3 => :size_limit,
+        4 => :bad_version,
+        5 => :not_implemented,
+        6 => :depth_limit,
+      }[error.type] || :unknown
+    end
+
+    def friendly_message(error)
+      "Serialization error (#{friendly_type(error)}): #{error.message}"
+    end
+  end
+
+  # Indicates a failure to parse Thrift according to schema
+  class DeserializationError < SerializationError
+    # @param error [StandardError] the exception encountered while deserialising
+    def friendly_message(error)
+      "Deserialization error (#{friendly_type(error)}): #{error.message}"
+    end
+  end
+
+  # Indicates that some Thrift struct failed cursory schema validation on the server
+  class ServerValidationError < ServerError
+    def initialize(validation_message)
+      super validation_message, Thrift::ApplicationException::UNKNOWN
+    end
+  end
+
+  # Indicates an uncategorised exception -- an error unrelated to Thrift,
+  # somewhere in application code.
+  class InternalError < ServerError
+    def self.type
+      Thrift::ApplicationException::INTERNAL_ERROR
+    end
+
+    # @param error [StandardError]
+    def initialize(error)
+      super "Internal error (#{error.class}): #{error.message}"
+    end
+  end
+
+  # Indicates an unexpected and unknown message type (HTTP status)
+  class UnknownMessageType < ClientError
+    def self.type
+      Thrift::ApplicationException::INVALID_MESSAGE_TYPE
+    end
+
+    def initialize(rpc, status, message)
+      super "#{rpc} returned unknown response code #{status}: #{message}"
+    end
+  end
+
+  # Indicates that the remote server could not be found
+  class ServerUnreachableError < ClientError
+    def initialize
+      super 'Failed to open connection to host'
+    end
+  end
+
+  # Indicates that RPC execution took too long
+  class RpcTimeoutError < ClientError
+    def initialize(rpc)
+      super "Host did not respond to #{rpc} in the allotted time"
+    end
+  end
+
+  # Indicates that some Thrift struct failed cursory schema validation on the client
+  class ClientValidationError < ClientError; end
+end

data/lib/thtp/middleware_stack.rb

@@ -0,0 +1,54 @@
+require 'thtp/utils'
+
+module THTP
+  # An implementation of the middleware pattern (a la Rack) for RPC handling.
+  # Extracts RPCs from a Thrift service and passes requests to a handler via
+  # a middleware stack. Note, NOT threadsafe -- mount all desired middlewares
+  # before calling.
+  class MiddlewareStack
+    # @param thrift_service [Class] The Thrift service from which to extract RPCs
+    # @param handlers [Object,Array<Object>] An object or objects responding to
+    #   each defined RPC; if multiple respond, the first will be used
+    def initialize(thrift_service, handlers)
+      # initialise middleware stack as empty with a generic dispatcher at the bottom
+      @stack = []
+      @dispatcher = ->(rpc, *rpc_args, **_rpc_opts) do
+        handler = Array(handlers).find { |h| h.respond_to?(rpc) }
+        raise NoMethodError, "No handler for rpc #{rpc}" unless handler
+        handler.public_send(rpc, *rpc_args) # opts are for middleware use only
+      end
+      # define instance methods for each RPC
+      Utils.extract_rpcs(thrift_service).each do |rpc|
+        define_singleton_method(rpc) { |*rpc_args_and_opts| call(rpc, *rpc_args_and_opts) }
+      end
+    end
+
+    # Nests a middleware at the bottom of the stack (closest to the function
+    # call). A middleware is any class implementing #call and calling app.call
+    # in turn., i.e.,
+    #   class PassthroughMiddleware
+    #     def initialize(app, *opts)
+    #       @app = app
+    #     end
+    #     def call(rpc, *rpc_args, **rpc_opts)
+    #       @app.call(rpc, *rpc_args, **rpc_opts)
+    #     end
+    #   end
+    def use(middleware_class, *middleware_args)
+      @stack << [middleware_class, middleware_args]
+    end
+
+    # Freezes and execute the middleware stack culminating in the RPC itself
+    def call(rpc, *rpc_args, **rpc_opts)
+      compose.call(rpc, *rpc_args, **rpc_opts)
+    end
+
+    private
+
+    # compose stack functions into one callable: [f, g, h] => f . g . h
+    def compose
+      @app ||= @stack.freeze.reverse_each. # rubocop:disable Naming/MemoizedInstanceVariableName
+        reduce(@dispatcher) { |app, (mw, mw_args)| mw.new(app, *mw_args) }
+    end
+  end
+end

data/lib/thtp/server.rb

@@ -0,0 +1,122 @@
+require 'rack'
+require 'thrift'
+
+require 'thtp/encoding'
+require 'thtp/errors'
+require 'thtp/middleware_stack'
+require 'thtp/status'
+require 'thtp/utils'
+
+require 'thtp/server/instrumentation'
+require 'thtp/server/middleware'
+require 'thtp/server/pub_sub'
+require 'thtp/server/null_route'
+
+module THTP
+  # An HTTP (Rack middleware) implementation of Thrift-RPC
+  class Server
+    include PubSub
+    include Utils
+
+    attr_reader :service
+
+    # @param app [Object?] The Rack application underneath, if used as middleware
+    # @param service [Thrift::Service] The service class handled by this server
+    # @param handlers [Object,Array<Object>] The object(s) handling RPC requests
+    def initialize(app = NullRoute.new, service:, handlers: [])
+      @app = app
+      @service = service
+      @handler = MiddlewareStack.new(service, handlers)
+      @route = %r{^/#{canonical_name(service)}/(?<rpc>[\w.]+)/?$} # /:service/:rpc
+    end
+
+    # delegate to RPC handler stack
+    def use(middleware_class, *middleware_args)
+      @handler.use(middleware_class, *middleware_args)
+    end
+
+    # Rack implementation entrypoint
+    def call(rack_env)
+      start_time = get_time
+      # verify routing
+      request = Rack::Request.new(rack_env)
+      protocol = Encoding.protocol(request.media_type) || Thrift::JsonProtocol
+      return @app.call(rack_env) unless request.post? && @route.match(request.path_info)
+      # get RPC name from route
+      rpc = Regexp.last_match[:rpc]
+      raise UnknownRpcError, rpc unless @handler.respond_to?(rpc)
+      # read, perform, write
+      args = read_args(request.body, rpc, protocol)
+      result = @handler.public_send(rpc, *args)
+      write_reply(result, rpc, protocol).tap do
+        publish :rpc_success,
+                request: request, rpc: rpc, args: args, result: result, time: elapsed_ms(start_time)
+      end
+    rescue Thrift::Exception => e # known schema-defined Thrift errors
+      write_reply(e, rpc, protocol).tap do
+        publish :rpc_exception,
+                request: request, rpc: rpc, args: args, exception: e, time: elapsed_ms(start_time)
+      end
+    rescue ServerError => e # known server/communication errors
+      write_error(e, protocol).tap do
+        publish :rpc_error,
+                request: request, rpc: rpc, args: args, error: e, time: elapsed_ms(start_time)
+      end
+    rescue => e # a non-Thrift exception occurred; translate to Thrift as best we can
+      write_error(InternalError.new(e), protocol).tap do
+        publish :internal_error, request: request, error: e, time: elapsed_ms(start_time)
+      end
+    end
+
+    private
+
+    # fetches args from a request
+    def read_args(request_body, rpc, protocol)
+      args_struct = args_class(service, rpc).new
+      # read off the request body into a Thrift args struct
+      deserialize_stream(request_body, args_struct, protocol)
+      # args are named methods, but handler signatures use positional arguments;
+      # convert between the two using struct_fields, which is an ordered hash.
+      args_struct.struct_fields.values.map { |f| args_struct.public_send(f[:name]) }
+    end
+
+    # given any schema-defined response (success or exception), write it to the HTTP response
+    def write_reply(reply, rpc, protocol)
+      result_struct = result_class(service, rpc).new
+      # void return types have no spot in the result struct
+      unless reply.nil?
+        if reply.is_a?(Thrift::Exception)
+          # detect the correct exception field, if it exists, and set its value
+          field = result_struct.struct_fields.values.find do |f|
+            f.key?(:class) && reply.instance_of?(f[:class])
+          end
+          raise BadResponseError, rpc, reply unless field
+          result_struct.public_send("#{field[:name]}=", reply)
+        else
+          # if it's not an exception, it must be the "success" value
+          result_struct.success = reply
+        end
+      end
+      # write to the response as a REPLY message
+      [
+        Status::REPLY,
+        { Rack::CONTENT_TYPE => Encoding.content_type(protocol) },
+        [serialize_buffer(result_struct, protocol)],
+      ]
+    end
+
+    # Given an unexpected error (non-schema), try to write it schemaless. The
+    # status code indicate to clients that an error occurred and should be
+    # deserialised. The implicit schema for a non-schema exception is:
+    #   struct exception { 1: string message, 2: i32 type }
+    # @param exception [Errors::ServerError]
+    def write_error(exception, protocol)
+      # write to the response as an EXCEPTION message
+      [
+        Status::EXCEPTION,
+        { Rack::CONTENT_TYPE => Encoding.content_type(protocol) },
+        [serialize_buffer(exception.to_thrift, protocol)],
+      ]
+    end
+  end
+end

data/lib/thtp/server/instrumentation.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require 'thrift'
+require 'thtp/errors'
+require 'thtp/utils'
+
+module THTP
+  class Server
+    module Instrumentation
+      # A THTP::Server Server subscriber for RPC metrics reporting
+      class Metrics
+        include Utils
+
+        INBOUND_RPC_STAT = 'rpc.incoming'
+
+        SUCCESS_TAG = 'rpc.status:success' # everything is ok
+        EXCEPTION_TAG = 'rpc.status:exception' # schema-defined (expected) exception
+        ERROR_TAG = 'rpc.status:error' # unexpected error
+        INTERNAL_ERROR_TAG = 'rpc.status:internal_error'
+
+        def initialize(statsd)
+          unless defined?(Datadog::Statsd) && statsd.is_a?(Datadog::Statsd)
+            raise ArgumentError, 'Only dogstatsd is supported'
+          end
+          @statsd = statsd
+        end
+
+        # Everything went according to plan
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param rpc [Symbol] The name of the RPC
+        # @param args [Thrift::Struct] The deserialized thrift args
+        # @param result [Thrift::Struct] The to-be-serialized thrift response
+        # @param time [Integer] Milliseconds of execution wall time
+        def rpc_success(request:, rpc:, args:, result:, time:)
+          tags = ["rpc:#{rpc}", SUCCESS_TAG]
+          @statsd.timing(INBOUND_RPC_STAT, time, tags: tags)
+        end
+
+        # Handler raised an exception defined in the schema
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param rpc [Symbol] The name of the RPC
+        # @param args [Thrift::Struct] The deserialized thrift args
+        # @param exception [Thrift::Struct] The to-be-serialized thrift exception
+        # @param time [Integer] Milliseconds of execution wall time
+        def rpc_exception(request:, rpc:, args:, exception:, time:)
+          tags = ["rpc:#{rpc}", EXCEPTION_TAG, "rpc.error:#{canonical_name(exception.class)}"]
+          @statsd.timing(INBOUND_RPC_STAT, time, tags: tags)
+        end
+
+        # Handler raised an unexpected error
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param rpc [Symbol] The name of the RPC
+        # @param args [Thrift::Struct?] The deserialized thrift args
+        # @param error [THTP::ServerError] The to-be-serialized exception
+        # @param time [Integer] Milliseconds of execution wall time
+        def rpc_error(request:, rpc:, args:, error:, time:)
+          tags = ["rpc:#{rpc}", ERROR_TAG, "rpc.error:#{canonical_name(error.class)}"]
+          @statsd.timing(INBOUND_RPC_STAT, time, tags: tags)
+        end
+
+        # An unknown error occurred
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param error [Exception] The to-be-serialized exception
+        # @param time [Integer] Milliseconds of execution wall time
+        def internal_error(request:, error:, time:)
+          tags = [INTERNAL_ERROR_TAG, "rpc.error:#{canonical_name(error.class)}"]
+          @statsd.timing(INBOUND_RPC_STAT, time, tags: tags)
+        end
+      end
+
+      # A THTP::Server subscriber for RPC logging and exception recording
+      class Logging
+        include Utils
+
+        def initialize(logger, backtrace_lines: 10)
+          @logger = logger
+          @backtrace_lines = backtrace_lines
+        end
+
+        # Everything went according to plan
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param rpc [Symbol] The name of the RPC
+        # @param args [Thrift::Struct] The deserialized thrift args
+        # @param result [Thrift::Struct] The to-be-serialized thrift response
+        # @param time [Integer] Milliseconds of execution wall time
+        def rpc_success(request:, rpc:, args:, result:, time:)
+          @logger.info :rpc do
+            {
+              rpc: rpc,
+              http: http_request_to_hash(request),
+              request: args_to_hash(args),
+              result: result_to_hash(result),
+              elapsed_ms: time,
+            }
+          end
+        end
+
+        # Handler raised an exception defined in the schema
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param rpc [Symbol] The name of the RPC
+        # @param args [Thrift::Struct] The deserialized thrift args
+        # @param exception [Thrift::Struct] The to-be-serialized thrift exception
+        # @param time [Integer] Milliseconds of execution wall time
+        def rpc_exception(request:, rpc:, args:, exception:, time:)
+          @logger.info :rpc do
+            {
+              rpc: rpc,
+              http: http_request_to_hash(request),
+              request: args_to_hash(args),
+              exception: result_to_hash(exception),
+              elapsed_ms: time,
+            }
+          end
+        end
+
+        # Handler raised an unexpected error
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param rpc [Symbol] The name of the RPC
+        # @param args [Thrift::Struct?] The deserialized thrift args
+        # @param error [THTP::ServerError] The to-be-serialized exception
+        # @param time [Integer] Milliseconds of execution wall time
+        def rpc_error(request:, rpc:, args:, error:, time:)
+          @logger.error :rpc do
+            {
+              rpc: rpc,
+              http: http_request_to_hash(request),
+              request: args_to_hash(args),
+              error: error_to_hash(error),
+              elapsed_ms: time,
+            }
+          end
+        end
+
+        # An unknown error occurred
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param error [Exception] The to-be-serialized exception
+        # @param time [Integer] Milliseconds of execution wall time
+        def internal_error(request:, error:, time:)
+          @logger.error :server do
+            {
+              http: http_request_to_hash(request),
+              internal_error: error_to_hash(error),
+              elapsed_ms: time,
+            }
+          end
+        end
+
+        private
+
+        def http_request_to_hash(rack_request)
+          {
+            user_agent: rack_request.user_agent,
+            content_type: rack_request.content_type,
+            verb: rack_request.request_method,
+            path: rack_request.path_info,
+            ssl: rack_request.ssl?,
+          }
+        end
+
+        def args_to_hash(rpc_args)
+          jsonify(rpc_args)
+        end
+
+        # converts all possible Thrift result types to JSON, inferring types
+        # from collections, with the intent of producing ELK-compatible output
+        # (i.e., no multiple-type-mapped fields)
+        def result_to_hash(result)
+          case result
+          when nil
+            nil # nulls are ok in ELK land
+          when Array
+            { list: { canonical_name(result.first.class) => jsonify(result) } }
+          when Set
+            { set: { canonical_name(result.first.class) => jsonify(result) } }
+          when Hash
+            ktype, vtype = result.first.map { |obj| canonical_name(obj.class) }
+            { hash: { ktype => { vtype => jsonify(result) } } }
+          when StandardError
+            error_to_hash(result, backtrace: false)
+          else # primitives
+            { canonical_name(result.class) => jsonify(result) }
+          end
+        end
+
+        # converts non-schema errors to an ELK-compatible format (JSON-serialisable hash)
+        def error_to_hash(error, backtrace: true)
+          error_info = { message: error.message, repr: error.inspect }
+          error_info[:backtrace] = error.backtrace.first(@backtrace_lines) if backtrace
+          { canonical_name(error.class) => error_info }
+        end
+      end
+
+      # Captures exceptions to Sentry
+      class Sentry
+        # @param raven [Raven] A Sentry client instance, or something that acts like one
+        def initialize(raven)
+          @raven = raven
+        end
+
+        # Handler raised an unexpected error
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param rpc [Symbol] The name of the RPC
+        # @param args [Thrift::Struct?] The deserialized thrift args
+        # @param error [THTP::ServerError] The to-be-serialized exception
+        # @param time [Integer] Milliseconds of execution wall time
+        def rpc_error(request:, rpc:, args:, error:, time:)
+          @raven.capture_exception(error, **rpc_context(request, rpc, args))
+        end
+
+        # An unknown error occurred
+        # @param request [Rack::Request] The inbound HTTP request
+        # @param error [Exception] The to-be-serialized exception
+        # @param time [Integer] Milliseconds of execution wall time
+        def internal_error(request:, error:, time:)
+          @raven.capture_exception(error, **http_context(request))
+        end
+
+        private
+
+        # subclass and override if desired
+        # @param rack_request [Rack::Request] The inbound HTTP request
+        def http_context(rack_request)
+          {
+            user: { ip: rack_request.ip, user_agent: rack_request.user_agent },
+            extra: {},
+          }
+        end
+
+        # subclass and override if desired
+        # @param rack_request [Rack::Request] The inbound HTTP request
+        # @param rpc [Symbol] The name of the RPC
+        # @param args [Thrift::Struct] The deserialized thrift args
+        def rpc_context(rack_request, rpc, _args)
+          http_context(rack_request).tap do |context|
+            context[:extra].merge!(rpc: rpc)
+          end
+        end
+      end
+    end
+  end
+end