RubyGems - jsonrpc2 - Versions diffs - 0.1.1 → 0.3.0 - Mend

jsonrpc2 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

checksums.yaml +5 -5
data/.github/workflows/test.yml +26 -0
data/.gitignore +1 -0
data/.rspec +1 -0
data/CHANGELOG.md +42 -0
data/Dockerfile +8 -0
data/README.markdown +36 -56
data/bin/run-example +7 -0
data/bin/setup +3 -0
data/bin/test +7 -0
data/example/config.ru +27 -25
data/{bin → exe}/jsonrpc2 +0 -0
data/jsonrpc2.gemspec +15 -3
data/lib/jsonrpc2/html.rb +3 -3
data/lib/jsonrpc2/interface.rb +319 -289
data/lib/jsonrpc2/textile.rb +5 -5
data/lib/jsonrpc2/types.rb +14 -10
data/lib/jsonrpc2/version.rb +1 -1
data/spec/lib/interface_spec.rb +208 -0
data/spec/spec_helper.rb +94 -0
metadata +133 -39

data/lib/jsonrpc2/interface.rb CHANGED Viewed

@@ -1,3 +1,7 @@
+# frozen_string_literal: true
+require 'rack'
+require 'digest'
 require 'jsonrpc2'
 require 'jsonrpc2/accept'
 require 'jsonrpc2/textile'
@@ -9,12 +13,15 @@ require 'base64'
 module JSONRPC2
   module_function
   def environment
     ENV['RACK_ENV'] || ENV['RAILS_ENV'] || 'development'
   end
   def development?
     environment.eql?('development')
   end
   # Authentication failed error - only used if transport level authentication isn't.
   # e.g. BasicAuth returns a 401 HTTP response, rather than throw this.
   class AuthFail < RuntimeError; end
@@ -34,356 +41,379 @@ module JSONRPC2
     end
   end
-# Base class for JSONRPC2 interface
-class Interface
-  class << self
+  # Base class for JSONRPC2 interface
+  class Interface
+    class << self
+      # @!group Authentication
+        # Get/set authenticator object for API interface - see {JSONRPC2::Auth} and {JSONRPC2::BasicAuth}
+        #
+        # @param [#check] args An object that responds to check(environment, json_call_data)
+        # @return [#check, nil] Currently set object or nil
+        def auth_with *args
+          if args.empty?
+            return @auth_with
+          else
+            @auth_with = args[0]
+          end
+        end
+      # @!endgroup
+      # @!group Rack-related
+        # Rack compatible call handler
+        #
+        # @param [Hash] environment Rack environment hash
+        # @return [Array<Fixnum, Hash<String,String>, Array<String>>] Rack-compatible response
+        def call(environment)
+          environment['json.request-id'] = Digest::MD5.hexdigest("#{$host ||= Socket.gethostname}-#{$$}-#{Time.now.to_f}")[0,8]
+          request = Rack::Request.new(environment)
+          catch :rack_response do
+            best = JSONRPC2::HTTPUtils.which(environment['HTTP_ACCEPT'], %w[text/html application/json-rpc application/json])
+            if request.path_info =~ %r'/_assets' or request.path_info == '/favicon.ico'
+              best = 'text/html' # hack for assets
+            end
+            case best
+            when 'text/html', 'text/css', 'image/png' # Assume browser
+              monitor_time(environment, request.POST['__json__']) { JSONRPC2::HTML.call(self, request) }
+            when 'application/json-rpc', 'application/json', nil # Assume correct by default
+              environment['rack.input'].rewind
+              raw = environment['rack.input'].read
+              data = JSON.parse(raw) if raw.to_s.size >= 2
+              monitor_time(environment, raw) { self.new(environment).rack_dispatch(data) }
+            else
+              [406, {'Content-Type' => 'text/html'},
+                ["<!DOCTYPE html><html><head><title>Media type mismatch</title></head><body>I am unable to acquiesce to your request</body></html>"]]
+            end
+          end
-# @!group Authentication
+        rescue Exception => e
+          if environment['rack.logger'].respond_to?(:error)
+            environment['rack.logger'].error "#{e.class}: #{e.message} - #{e.backtrace * "\n    "}"
+          end
+          raise e.class, e.message, e.backtrace
+        end
-    # Get/set authenticator object for API interface - see {JSONRPC2::Auth} and {JSONRPC2::BasicAuth}
-    #
-    # @param [#check] args An object that responds to check(environment, json_call_data)
-    # @return [#check, nil] Currently set object or nil
-    def auth_with *args
-      if args.empty?
-        return @auth_with
-      else
-        @auth_with = args[0]
-      end
+        private
+        def monitor_time(env, data, &block)
+          if env['rack.logger'].respond_to?(:info)
+            if env["HTTP_AUTHORIZATION"].to_s =~ /Basic /i
+              auth = Base64.decode64(env["HTTP_AUTHORIZATION"].to_s.sub(/Basic /i, '')) rescue nil
+              auth ||= env["HTTP_AUTHORIZATION"]
+            else
+              auth = env["HTTP_AUTHORIZATION"]
+            end
+            env['rack.logger'].info("[JSON-RPC2] #{env['json.request-id']} #{env['REQUEST_URI']} - Auth: #{auth}, Data: #{data.is_a?(String) ? data : data.inspect}")
+          end
+          t = Time.now.to_f
+          return yield
+        ensure
+          if env['rack.logger'].respond_to?(:info)
+            env['rack.logger'].info("[JSON-RPC2] #{env['json.request-id']} Completed in #{'%.3f' % ((Time.now.to_f - t) * 1000)}ms#{ $! ? " - exception = #{$!.class}:#{$!.message}" : "" }")
+          end
+        end
+      # @!endgroup
     end
-# @!endgroup
-# @!group Rack-related
-    # Rack compatible call handler
+    # Create new interface object
     #
-    # @param [Hash] environment Rack environment hash
-    # @return [Array<Fixnum, Hash<String,String>, Array<String>>] Rack-compatible response
-    def call(environment)
-      environment['json.request-id'] = Digest::MD5.hexdigest("#{$host ||= Socket.gethostname}-#{$$}-#{Time.now.to_f}")[0,8]
-      request = Rack::Request.new(environment)
-      catch :rack_response do
-        best = JSONRPC2::HTTPUtils.which(environment['HTTP_ACCEPT'], %w[text/html application/json-rpc application/json])
-        if request.path_info =~ %r'/_assets' or request.path_info == '/favicon.ico'
-          best = 'text/html' # hack for assets
-        end
-        case best
-        when 'text/html', 'text/css', 'image/png' # Assume browser
-          monitor_time(environment, request.POST['__json__']) { JSONRPC2::HTML.call(self, request) }
-        when 'application/json-rpc', 'application/json', nil # Assume correct by default
-          environment['rack.input'].rewind
-          raw = environment['rack.input'].read
-          data = JSON.parse(raw) if raw.to_s.size >= 2
-          monitor_time(environment, raw) { self.new(environment).rack_dispatch(data) }
-        else
-          [406, {'Content-Type' => 'text/html'},
-            ["<!DOCTYPE html><html><head><title>Media type mismatch</title></head><body>I am unable to acquiesce to your request</body></html>"]]
-        end
-      end
+    # @param [Hash] env Rack environment
+    def initialize(env)
+      @_jsonrpc_env = env
+      @_jsonrpc_request = Rack::Request.new(env)
+    end
-    rescue Exception => e
-      if environment['rack.logger'].respond_to?(:error)
-        environment['rack.logger'].error "#{e.class}: #{e.message} - #{e.backtrace * "\n    "}"
+    # Internal
+    def rack_dispatch(rpcData)
+      catch(:rack_response) do
+        json = dispatch(rpcData)
+        [200, {'Content-Type' => 'application/json-rpc'}, [json]]
       end
-      raise e.class, e.message, e.backtrace
     end
-    private
-    def monitor_time(env, data, &block)
-      if env['rack.logger'].respond_to?(:info)
-        if env["HTTP_AUTHORIZATION"].to_s =~ /Basic /i
-          auth = Base64.decode64(env["HTTP_AUTHORIZATION"].to_s.sub(/Basic /i, '')) rescue nil
-          auth ||= env["HTTP_AUTHORIZATION"]
-        else
-          auth = env["HTTP_AUTHORIZATION"]
-        end
-        env['rack.logger'].info("[JSON-RPC2] #{env['json.request-id']} #{env['REQUEST_URI']} - Auth: #{auth}, Data: #{data.is_a?(String) ? data : data.inspect}")
-      end
-      t = Time.now.to_f
-      return yield
-    ensure
-      if env['rack.logger'].respond_to?(:info)
-        env['rack.logger'].info("[JSON-RPC2] #{env['json.request-id']} Completed in #{'%.3f' % ((Time.now.to_f - t) * 1000)}ms#{ $! ? " - exception = #{$!.class}:#{$!.message}" : "" }")
+    # Dispatch call to api method(s)
+    #
+    # @param [Hash,Array] rpc_data Array of calls or Hash containing one call
+    # @return [Hash,Array] Depends on input, but either a hash result or an array of results corresponding to calls.
+    def dispatch(rpc_data)
+      result = case rpc_data
+      when Array
+        rpc_data.map { |rpc| dispatch_single(rpc) }
+      else
+        dispatch_single(rpc_data)
       end
+      return result.to_json
     end
-# @!endgroup
+    protected
-  end
+    # JSON result helper
+    def response_ok(id, result)
+      { 'jsonrpc' => '2.0', 'result' => result, 'id' => id }
+    end
-  # Create new interface object
-  #
-  # @param [Hash] env Rack environment
-  def initialize(env)
-    @_jsonrpc_env = env
-    @_jsonrpc_request = Rack::Request.new(env)
-  end
-  # Internal
-  def rack_dispatch(rpcData)
-    catch(:rack_response) do
-      json = dispatch(rpcData)
-      [200, {'Content-Type' => 'application/json-rpc'}, [json]]
+    # JSON error helper
+    def response_error(code, message, data)
+      { 'jsonrpc' => '2.0', 'error' => { 'code' => code, 'message' => message, 'data' => data }, 'id' => (@_jsonrpc_call && @_jsonrpc_call['id'] || nil) }
     end
-  end
-  # Dispatch call to api method(s)
-  #
-  # @param [Hash,Array] rpc_data Array of calls or Hash containing one call
-  # @return [Hash,Array] Depends on input, but either a hash result or an array of results corresponding to calls.
-  def dispatch(rpc_data)
-    result = case rpc_data
-    when Array
-      rpc_data.map { |rpc| dispatch_single(rpc) }
-    else
-      dispatch_single(rpc_data)
+    # Params helper
+    def params
+      @_jsonrpc_call['params']
     end
-    return result.to_json
-  end
+    # Auth info
+    def auth
+      @_jsonrpc_auth
+    end
-  protected
-  # JSON result helper
-  def response_ok(id, result)
-    { 'jsonrpc' => '2.0', 'result' => result, 'id' => id }
-  end
-  # JSON error helper
-  def response_error(code, message, data)
-    { 'jsonrpc' => '2.0', 'error' => { 'code' => code, 'message' => message, 'data' => data }, 'id' => (@_jsonrpc_call && @_jsonrpc_call['id'] || nil) }
-  end
-  # Params helper
-  def params
-    @_jsonrpc_call['params']
-  end
-  # Auth info
-  def auth
-    @_jsonrpc_auth
-  end
-  # Rack::Request
-  def request
-    @_jsonrpc_request
-  end
-  def env
-    @_jsonrpc_env
-  end
+    # Rack::Request
+    def request
+      @_jsonrpc_request
+    end
-  # Logger
-  def logger
-    @_jsonrpc_logger ||= (@_jsonrpc_env['rack.logger'] || Rack::NullLogger.new("null"))
-  end
-  # Check call validity and authentication & make a single method call
-  #
-  # @param [Hash] rpc JSON-RPC-2 call
-  def dispatch_single(rpc)
-    t = Time.now.to_f
-    result = _dispatch_single(rpc)
-    if result['result']
-      logger.info("[JSON-RPC2] #{env['json.request-id']} Call completed OK in #{'%.3f' % ((Time.now.to_f - t) * 1000)}ms")
-    elsif result['error']
-      logger.info("[JSON-RPC2] #{env['json.request-id']} Call to ##{rpc['method']} failed in #{'%.3f' % ((Time.now.to_f - t) * 1000)}ms with error #{result['error']['code']} - #{result['error']['message']}")
+    def env
+      @_jsonrpc_env
     end
-    result
-  end
-  def _dispatch_single(rpc)
-    t = Time.now.to_f
-    unless rpc.has_key?('id') && rpc.has_key?('method') && rpc['jsonrpc'].eql?('2.0')
-      return response_error(-32600, 'Invalid request', nil)
+    # Logger
+    def logger
+      @_jsonrpc_logger ||= (@_jsonrpc_env['rack.logger'] || Rack::NullLogger.new("null"))
     end
-    @_jsonrpc_call = rpc
-    begin
-      if self.class.auth_with && ! @_jsonrpc_auth
-        (@_jsonrpc_auth = self.class.auth_with.client_check(@_jsonrpc_env, rpc)) or raise AuthFail, "Invalid credentials"
-      end
+    # Check call validity and authentication & make a single method call
+    #
+    # @param [Hash] rpc JSON-RPC-2 call
+    def dispatch_single(rpc)
+      t = Time.now.to_f
-      call(rpc['method'], rpc['id'], rpc['params'])
-    rescue AuthFail => e
-      response_error(-32000, "AuthFail: #{e.class}: #{e.message}", {}) # XXX: Change me
-    rescue APIFail => e
-      response_error(-32000, "APIFail: #{e.class}: #{e.message}", {}) # XXX: Change me
-    rescue KnownError => e
-      response_error(e.code, e.message, e.data) # XXX: Change me
-    rescue Exception => e
-      logger.error("#{env['json.request-id']} Internal error calling #{rpc.inspect} - #{e.class}: #{e.message} #{e.backtrace.join("\n    ")}") if logger.respond_to?(:error)
-      response_error(-32000, "#{e.class}: #{e.message}", e.backtrace) # XXX: Change me
-    else
-    end
-  end
-  # List API methods
-  #
-  # @return [Array] List of api method names
-  def api_methods
-    public_methods(false).map(&:to_s) - ['rack_dispatch', 'dispatch']
-  end
+      result = _dispatch_single(rpc)
-  # Call method, checking param and return types
-  #
-  # @param [String] method Method name
-  # @param [Integer] id Method call ID - for response
-  # @param [Hash] params Method parameters
-  # @return [Hash] JSON response
-  def call(method, id, params)
-    if api_methods.include?(method)
-      begin
-        Types.valid_params?(self.class, method, params)
-      rescue Exception => e
-        return response_error(-32602, "Invalid params - #{e.message}", {})
+      if result['result']
+        logger.info("[JSON-RPC2] #{env['json.request-id']} Call completed OK in #{'%.3f' % ((Time.now.to_f - t) * 1000)}ms")
+      elsif result['error']
+        logger.info("[JSON-RPC2] #{env['json.request-id']} Call to ##{rpc['method']} failed in #{'%.3f' % ((Time.now.to_f - t) * 1000)}ms with error #{result['error']['code']} - #{result['error']['message']}")
       end
-      if self.method(method).arity.zero?
-        result = send(method)
-      else
-        result = send(method, params)
+      result
+    end
+    def _dispatch_single(rpc)
+      unless rpc.has_key?('id') && rpc.has_key?('method') && rpc['jsonrpc'].eql?('2.0')
+        return response_error(-32600, 'Invalid request', nil)
       end
+      @_jsonrpc_call = rpc
       begin
-        Types.valid_result?(self.class, method, result)
+        if self.class.auth_with && ! @_jsonrpc_auth
+          (@_jsonrpc_auth = self.class.auth_with.client_check(@_jsonrpc_env, rpc)) or raise AuthFail, "Invalid credentials"
+        end
+        call(rpc['method'], rpc['id'], rpc['params'])
+      rescue AuthFail => e
+        response_error(-32000, 'AuthFail: Invalid credentials', {})
+      rescue APIFail => e
+        response_error(-32000, 'APIFail', {})
+      rescue KnownError => e
+        response_error(e.code, 'An error occurred', {})
       rescue Exception => e
-        return response_error(-32602, "Invalid result - #{e.message}", {})
+        log_error("Internal error calling #{rpc.inspect} - #{e.class}: #{e.message} #{e.backtrace.join("\n    ")}")
+        invoke_server_error_hook(e)
+        response_error(-32000, "An error occurred. Check logs for details", {})
       end
-      response_ok(id, result)
-    else
-      response_error(-32601, "Unknown method `#{method.inspect}'", {})
     end
-  end
-  class << self
-    # Store parameter in internal hash when building API
-    def ___append_param name, type, options
-      @params ||= []
-      unless options.has_key?(:required)
-        options[:required] = true
-      end
-      @params << options.merge({ :name => name, :type => type })
+    # List API methods
+    #
+    # @return [Array] List of api method names
+    def api_methods
+      public_methods(false).map(&:to_s) - ['rack_dispatch', 'dispatch']
     end
-    private :___append_param
-# @!group DSL
-    # Define a named parameter of type #type for next method
+    # Call method, checking param and return types
     #
-    # @param [String] name parameter name
-    # @param [String] type description of type see {Types}
-    def param name, type, desc = nil, options = nil
-      if options.nil? && desc.is_a?(Hash)
-        options, desc = desc, nil
+    # @param [String] method Method name
+    # @param [Integer] id Method call ID - for response
+    # @param [Hash] params Method parameters
+    # @return [Hash] JSON response
+    def call(method, id, params)
+      invoke_before_validation_hook(method, id, params)
+      if api_methods.include?(method)
+        begin
+          Types.valid_params?(self.class, method, params)
+        rescue Types::InvalidParamsError => e
+          return response_error(-32602, "Invalid params - #{e.message}", {})
+        end
+        if self.method(method).arity.zero?
+          result = send(method)
+        else
+          result = send(method, params)
+        end
+        Types.valid_result?(self.class, method, result)
+        response_ok(id, result)
+      else
+        response_error(-32601, "Unknown method `#{method.inspect}'", {})
       end
-      options ||= {}
-      options[:desc] = desc if desc.is_a?(String)
-      ___append_param name, type, options
     end
-    # Define an optional parameter for next method
-    def optional name, type, desc = nil, options = nil
-      if options.nil? && desc.is_a?(Hash)
-        options, desc = desc, nil
+    class << self
+      # Store parameter in internal hash when building API
+      def ___append_param name, type, options
+        @params ||= []
+        unless options.has_key?(:required)
+          options[:required] = true
+        end
+        @params << options.merge({ :name => name, :type => type })
       end
-      options ||= {}
-      options[:desc] = desc if desc.is_a?(String)
+      private :___append_param
+      # @!group DSL
+        # Define a named parameter of type #type for next method
+        #
+        # @param [String] name parameter name
+        # @param [String] type description of type see {Types}
+        def param name, type, desc = nil, options = nil
+          if options.nil? && desc.is_a?(Hash)
+            options, desc = desc, nil
+          end
+          options ||= {}
+          options[:desc] = desc if desc.is_a?(String)
-      ___append_param(name, type, options.merge(:required => false))
-    end
+          ___append_param name, type, options
+        end
-    # Define type of return value for next method
-    def result type, desc = nil
-      @result = { :type => type, :desc => desc }
-    end
+        # Define an optional parameter for next method
+        def optional name, type, desc = nil, options = nil
+          if options.nil? && desc.is_a?(Hash)
+            options, desc = desc, nil
+          end
+          options ||= {}
+          options[:desc] = desc if desc.is_a?(String)
-    # Set description for next method
-    def desc str
-      @desc = str
-    end
+          ___append_param(name, type, options.merge(:required => false))
+        end
-    # Add an example for next method
-    def example desc, code
-      @examples ||= []
-      @examples << { :desc => desc, :code => code }
-    end
+        # Define type of return value for next method
+        def result type, desc = nil
+          @result = { :type => type, :desc => desc }
+        end
-    # Define a custom type
-    def type name, *fields
-      @types ||= {}
-      type = JsonObjectType.new(name, fields)
+        # Set description for next method
+        def desc str
+          @desc = str
+        end
-      if block_given?
-        yield(type)
-      end
+        # Add an example for next method
+        def example desc, code
+          @examples ||= []
+          @examples << { :desc => desc, :code => code }
+        end
-      @types[name] = type
-    end
+        # Define a custom type
+        def type name, *fields
+          @types ||= {}
+          type = JsonObjectType.new(name, fields)
-    # Group methods
-    def section name, summary=nil
-      @sections ||= []
-      @sections << {:name => name, :summary => summary}
+          if block_given?
+            yield(type)
+          end
-      @current_section = name
-      if block_given?
-        yield
-        @current_section = nil
-      end
-    end
+          @types[name] = type
+        end
-    # Exclude next method from documentation
-    def nodoc
-      @nodoc = true
-    end
+        # Group methods
+        def section name, summary=nil
+          @sections ||= []
+          @sections << {:name => name, :summary => summary}
-    # Set interface title
-    def title str = nil
-      @title = str if str
-    end
+          @current_section = name
+          if block_given?
+            yield
+            @current_section = nil
+          end
+        end
-    # Sets introduction for interface
-    def introduction str = nil
-      @introduction = str if str
-    end
+        # Exclude next method from documentation
+        def nodoc
+          @nodoc = true
+        end
-# @!endgroup
-    # Catch methods added to class & store documentation
-    def method_added(name)
-      return if self == JSONRPC2::Interface
-      @about ||= {}
-      method = {}
-      method[:params] = @params if @params
-      method[:returns] = @result if @result
-      method[:desc] = @desc if @desc
-      method[:examples] = @examples if @examples
-      if method.empty?
-        if public_methods(false).include?(name)
-          unless @nodoc
-            #logger.info("#{name} has no API documentation... :(")
+        # Set interface title
+        def title str = nil
+          @title = str if str
+        end
+        # Sets introduction for interface
+        def introduction str = nil
+          @introduction = str if str
+        end
+      # @!endgroup
+      # Catch methods added to class & store documentation
+      def method_added(name)
+        return if self == JSONRPC2::Interface
+        @about ||= {}
+        method = {}
+        method[:params] = @params if @params
+        method[:returns] = @result if @result
+        method[:desc] = @desc if @desc
+        method[:examples] = @examples if @examples
+        if method.empty?
+          if public_methods(false).include?(name)
+            unless @nodoc
+              #logger.info("#{name} has no API documentation... :(")
+            end
+          else
+            #logger.debug("#{name} isn't public - so no API")
           end
         else
-          #logger.debug("#{name} isn't public - so no API")
+          method[:name] = name
+          method[:section] = @current_section
+          method[:index] = @about.size
+          @about[name.to_s] = method
         end
-      else
-        method[:name] = name
-        method[:section] = @current_section
-        method[:index] = @about.size
-        @about[name.to_s] = method
+        @result = nil
+        @params = nil
+        @desc = nil
+        @examples = nil
+        @nodoc = false
       end
+      private :method_added
+      attr_reader :about, :types
+    end
-      @result = nil
-      @params = nil
-      @desc = nil
-      @examples = nil
-      @nodoc = false
+    extend JSONRPC2::TextileEmitter
+    private
+    def invoke_server_error_hook(error)
+      on_server_error(request_id: env['json.request-id'], error: error)
+    rescue => error
+      log_error("Server error hook failed - #{error.class}: #{error.message} #{error.backtrace.join("\n    ")}")
     end
-    private :method_added
-    attr_reader :about, :types
-  end
+    def invoke_before_validation_hook(method, id, params)
+      before_validation(method: method, id: id, params: params)
+    rescue => error
+      log_error("Before validation hook failed - #{error.class}: #{error.message} #{error.backtrace.join("\n    ")}")
+    end
-  extend JSONRPC2::TextileEmitter
-end
+    # Available for reimplementation by a subclass, noop by default
+    def on_server_error(request_id:, error:)
+    end
+    def before_validation(method:, id:, params:)
+    end
+    def log_error(message)
+      logger.error("#{env['json.request-id']} #{message}") if logger.respond_to?(:error)
+    end
+  end
 end