RubyGems - jsonrpc2 - Versions diffs - 0.0.1 - Mend

jsonrpc2 0.0.1

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 (16) hide show

data/lib/jsonrpc2/html.rb ADDED

@@ -0,0 +1,137 @@
+require 'cgi'
+module JSONRPC2
+  # HTML output helpers for browseable API interface
+  module HTML
+  module_function
+  # Wrap body in basic bootstrap template using cdn
+  def html5(title, body, options={})
+    request = options[:request]
+    [
+    <<-HTML5
+<!DOCTYPE html><html>
+<head>
+<meta http-equiv="content-type" content="text/html; charset=utf-8">
+<title>#{title}</title>
+#{options[:head]}
+<link rel="stylesheet" href="//current.bootstrapcdn.com/bootstrap-v204/css/bootstrap-combined.min.css">
+<script src="//current.bootstrapcdn.com/bootstrap-v204/js/bootstrap.min.js"></script>
+   <style>
+      body {
+        padding-top: 60px; /* 60px to make the container go all the way to the bottom of the topbar */
+      }
+    </style>
+</head>
+<body>   <div class="navbar navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+          </a>
+          <a class="brand" href="#">JSON-RPC Interface</a>
+          <div class="nav-collapse">
+            <ul class="nav">
+              <li class="#{['', '/'].include?(request.path_info) ? 'active' : ''}"><a href="#{request.script_name}/">API Overview</a></li>
+            </ul>
+          </div><!--/.nav-collapse -->
+        </div>
+      </div>
+    </div>
+    <div class="container">#{body}</div>
+</body>
+</html>
+HTML5
+  ]
+  end
+  # Process browser request for #interface
+  # @param [JSONRPC2::Interface] interface Interface being accessed
+  # @param [Rack::Request] request Request being processed
+  # @return [Rack::Response]
+  def call(interface, request)
+    #require 'pp'; pp interface.about
+    if interface.auth_with.kind_of?(JSONRPC2::HttpAuth)
+      response = catch(:rack_response) do
+        interface.auth_with.check(request.env, {}); nil
+      end
+      return response if response
+    end
+    case request.path_info
+    when /^\/([a-zA-Z_0-9]+)/
+      method = $1
+      if info = interface.about_method(method)
+        if json = request.POST['__json__']
+          begin
+            data = JSON.parse(json)
+            result = interface.new(request.env).dispatch(data)
+          rescue => e
+            result = e.class.name + ": " + e.message
+          end
+        end
+        [200, {'Content-Type' => 'text/html'}, html5(method,describe(interface, request, info, :result => result), :request => request) ]
+      else
+        [404, {'Content-Type' => 'text/html'}, html5("Method not found", "<h1>No such method</h1>", :request => request)]
+      end
+    else
+      body = RedCloth.new(interface.to_textile).to_html.gsub(/\<h3\>(.*?)\<\/h3\>/, '<h3><a href="'+request.script_name+'/\1">\1</a></h3>')
+      [200, {'Content-Type' => 'text/html'},
+              html5('Interface: '+interface.name.to_s, body, :request => request)]
+    end
+  end
+  # Returns HTML page describing method
+  def describe interface, request, info, options = {}
+    params = {}
+    if info[:params]
+      info[:params].each do |param|
+        params[param[:name]] = case param[:type]
+        when 'String'
+          ""
+        when 'Boolean', 'false'
+          false
+        when 'true'
+          true
+        when 'null'
+          nil
+        when 'Number', 'Integer'
+          0
+        when /^Array/
+          []
+        else
+          {}
+        end
+      end
+    end
+    <<-EOS
+<h1>Method Info: #{info[:name]}</h1>
+#{RedCloth.new(interface.method_to_textile(info)).to_html}
+<hr>
+<h2>Test method</h2>
+<div class="row">
+<div class="span6">
+<form method="POST" action="#{request.script_name}/#{info[:name]}">
+<textarea name="__json__" cols="60" rows="8" class="span6">
+#{CGI.escapeHTML((request.POST['__json__'] || JSON.pretty_unparse({'jsonrpc'=>'2.0', 'method' => info[:name], 'id' => 1, 'params' => params})).strip)}
+</textarea>
+<div class="form-actions">
+<input type="submit" class="btn btn-primary" value="Call Method">
+</div>
+</form>
+</div>
+<div class="span6">
+<h3>Result</h3>
+<xmp>
+#{options[:result]}
+</xmp>
+</div>
+</div>
+EOS
+  end
+  end
+end

data/lib/jsonrpc2/interface.rb ADDED

@@ -0,0 +1,298 @@
+require 'jsonrpc2'
+require 'jsonrpc2/accept'
+require 'jsonrpc2/textile'
+require 'jsonrpc2/auth'
+require 'jsonrpc2/html'
+require 'jsonrpc2/types'
+require 'json'
+require 'base64'
+module JSONRPC2
+  # 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
+  # API error - thrown when an error is detected, e.g. params of wrong type.
+  class APIFail < RuntimeError; end
+# 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)
+      request = Rack::Request.new(environment)
+      catch :rack_response do
+        case JSONRPC2::HTTPUtils.which(environment['HTTP_ACCEPT'], %w[text/html application/json-rpc application/json])
+        when 'text/html', nil
+          JSONRPC2::HTML.call(self, request)
+        when 'application/json-rpc', 'application/json'
+          environment['rack.input'].rewind
+          data = JSON.parse(environment['rack.input'].read)
+          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
+    end
+# @!endgroup
+	end
+  # Create new interface object
+  #
+  # @param [Hash] env Rack environment
+	def initialize(env)
+		@env = env
+	end
+  # Internal
+  def rack_dispatch(rpcData)
+    catch(:rack_response) do
+      json = dispatch(rpcData)
+      [200, {'Content-Type' => 'application/json-rpc'}, [json]]
+    end
+  end
+	protected
+  # 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)
+		case rpc_data
+    when Array
+			rpc_data.map { |rpc| dispatch_single(rpc) }.to_json
+		else
+			dispatch_single(rpc_data).to_json
+		end
+	end
+  # 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' => @id }
+	end
+  # Check call validity and authentication & make a single method call
+  #
+  # @param [Hash] rpc JSON-RPC-2 call
+	def dispatch_single(rpc)
+		unless rpc.has_key?('id') && rpc.has_key?('method') && rpc['jsonrpc'].eql?('2.0')
+			@id = nil
+			return response_error(-32600, 'Invalid request', nil)
+		end
+		@id = rpc['id']
+		@method = rpc['method']
+		@rpc = rpc
+		begin
+      if self.class.auth_with
+        self.class.auth_with.check(@env, rpc) or raise AuthFail, "Invalid credentials"
+      end
+			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 Exception => e
+			response_error(-32000, "#{e.class}: #{e.message}", e.backtrace) # XXX: Change me
+		end
+	end
+  # List API methods
+  #
+  # @return [Array] List of api method names
+  def api_methods
+    public_methods(false).map(&:to_s) - ['rack_dispatch']
+  end
+  # 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}", {})
+			end
+      if self.method(method).arity.zero?
+  			result = send(method)
+      else
+	  		result = send(method, params)
+      end
+			begin
+				Types.valid_result?(self.class, method, result)
+			rescue Exception => e
+				return response_error(-32602, "Invalid result - #{e.message}", {})
+			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 })
+		end
+    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
+		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)
+			___append_param(name, type, options.merge(:required => false))
+		end
+    # Define type of return value for next method
+		def result type, desc = nil
+			@result = { :type => type, :desc => desc }
+		end
+    # Set description for next method
+		def desc str
+			@desc = str
+		end
+    # Add an example for next method
+		def example desc, code
+			@examples ||= []
+			@examples << { :desc => desc, :code => code }
+		end
+    # Define a custom type
+		def type name, *fields
+			@types ||= {}
+			type = JsonObjectType.new(name, fields)
+			if block_given?
+				yield(type)
+			end
+			@types[name] = type
+		end
+    # Group methods
+		def section name, summary=nil
+			@sections ||= []
+			@sections << {:name => name, :summary => summary}
+			@current_section = name
+			if block_given?
+				yield
+				@current_section = nil
+			end
+		end
+    # Exclude next method from documentation
+		def nodoc
+			@nodoc = true
+		end
+    # 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
+				method[:name] = name
+				method[:section] = @current_section
+				method[:index] = @about.size
+				@about[name.to_s] = method
+			end
+			@result = nil
+			@params = nil
+			@desc = nil
+			@examples = nil
+			@nodoc = false
+		end
+    private :method_added
+		attr_reader :about, :types
+	end
+  extend JSONRPC2::TextileEmitter
+end
+end

data/lib/jsonrpc2/textile.rb ADDED

@@ -0,0 +1,131 @@
+require 'redcloth'
+module JSONRPC2
+  # Textile documentation output functions
+  module TextileEmitter
+    # Returns interface description in textile
+		def to_textile
+			return nil if @about.nil? or @about.empty?
+			str = ""
+			if @title
+				str << "h1. #{@title}\n"
+      else
+        str << "h1. #{name}\n"
+			end
+			if @introduction
+				str << "\nh2. Introduction\n\n#{@introduction}\n"
+			end
+			unless @types.nil? or @types.empty?
+				str << "\nh2. Types\n"
+				@types.sort_by { |k,v| k }.each do |k,type|
+					str << "\nh5. #{k} type\n"
+					str << "\n|_. Field |_. Type |_. Required? |_. Description |"
+					type.fields.each do |field|
+						str << "\n| @#{field[:name]}@ | @#{field[:type]}@ | #{field[:required] ? 'Yes' : 'No'} | #{field[:desc]} |"
+					end
+					str << "\n"
+				end
+			end
+			@sections.each do |section|
+				str << "\nh2. #{section[:name]}\n"
+				if section[:summary]
+					str << "\n#{section[:summary]}\n"
+				end
+				str += to_textile_group(section).to_s
+			end
+			miscfn = to_textile_group({:name => nil})
+			if miscfn
+				str << "\nh2. Misc functions\n"
+				str << miscfn
+			end
+			str
+		end
+    # Returns method description in textile
+    def method_to_textile(info)
+      str = ''
+      str << "\nh3. #{info[:name]}\n"
+      str << "\n#{info[:desc]}\n" if info[:desc]
+      str << "\nh5. Params\n"
+      if info[:params].nil?
+        str << "\n* _None_\n"
+      elsif info[:params].is_a?(Array)
+        str << "\n|_. Name |_. Type |_. Required |_. Description |\n"
+        info[:params].each do |param|
+          str << "| @#{param[:name]}@ | @#{param[:type]}@ | #{param[:required] ? 'Yes' : 'No'} | #{param[:desc]} |\n"
+        end
+      end
+      if res = info[:returns]
+        str << "\nh5. Result\n"
+        str << "\n* @#{res[:type]}@"
+        str << " - #{res[:desc]}" if res[:desc]
+        str << "\n"
+      else
+        str << "\nh5. Result\n"
+        str << "\n* @null@"
+      end
+      if examples = info[:examples]
+        str << "\nh5. Sample usage\n"
+        nice_json = lambda do |data|
+          JSON.pretty_unparse(data).gsub(/\n\n+/,"\n").gsub(/[{]\s+[}]/m, '{ }').gsub(/\[\s+\]/m, '[ ]')
+        end
+        examples.each do |ex|
+          str << "\n#{ex[:desc]}\n"
+          code = ex[:code]
+          if code.is_a?(String)
+            str << "\nbc. #{ex[:code]}\n"
+          elsif code.is_a?(Hash) && code.has_key?(:params) && (code.has_key?(:result) || code.has_key?(:error))
+            str << "\nbc. "
+            if code[:result] # ie. we expect success
+              unless JSONRPC2::Types.valid_params?(self, info[:name], code[:params])
+                raise "Invalid example params for #{info[:name]} / #{ex[:desc]}"
+              end
+            end
+            input = { 'jsonrpc' => 2.0, 'method' => info[:name], 'params' => code[:params], 'id' => 0 }
+            str << "--> #{nice_json.call(input)}\n"
+            if code[:error]
+              error = { 'jsonrpc' => 2.0, 'error' => code[:error], 'id' => 0 }
+              str << "<-- #{nice_json.call(error)}\n"
+            elsif code[:result]
+              unless JSONRPC2::Types.valid_result?(self, info[:name], code[:result])
+                raise "Invalid result example for #{info[:name]} / #{ex[:desc]}"
+              end
+              result = { 'jsonrpc' => 2.0, 'result' => code[:result], 'id' => 0 }
+              str << "<-- #{nice_json.call(result)}\n"
+            end
+          end
+        end
+      end
+      str
+    end
+    # Gets method docs for method #name
+    def about_method(name)
+      @about[name.to_s]
+    end
+    # Returns documentation #section contents in textile
+		def to_textile_group(section)
+			list = @about.values.select { |info| info[:section] == section[:name] }
+			return nil if list.empty?
+			str = ''
+			list.sort_by { |info| info[:index] }.each do |info|
+        str << method_to_textile(info)
+			end
+			str
+		end
+  end
+end