RubyGems - jsonrpc2 - Versions diffs - 0.0.1 - Mend

jsonrpc2 0.0.1

Files changed (16) hide show

@@ -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