jsonrpc2 0.0.1

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in jsonrpc2.gemspec
+gemspec

data/README.markdown

@@ -0,0 +1,176 @@
+# JSON-RPC2 Ruby Server
+
+A Rack compatible, documenting JSON-RPC 2 DSL/server implementation for ruby.
+
+## Features
+
+* Inline documentation
+* Type checking for parameters and return values
+* Authentication support - including HTTP Basic Authentication
+* Rack mountable
+* Interactive browser based API testing
+
+## Example
+
+    class Calculator < JSONRPC2::Interface
+      title "JSON-RPC2 Calculator"
+      introduction "This interface allows basic maths calculations via JSON-RPC2"
+      auth_with JSONRPC2::BasicAuth.new({'apiuser' => 'secretword'})
+
+      section 'Simple Ops' do
+         desc 'Multiply two numbers'
+         param 'a', 'Number', 'First number'
+         param 'b', 'Number', 'Second number'
+         result 'Number', 'a * b'
+         def mul args
+           args['a'] * args['b']
+         end
+   
+         desc 'Add numbers'
+         param 'a', 'Number', 'First number'
+         param 'b', 'Number', 'Second number'
+         optional 'c', 'Number', 'Third number'
+         example 'Calculate 1 + 1', :params => { 'a' => 1, 'b' => 1}, :result => 2
+         result 'Number', 'a + b + c'
+         def sum args
+           val = args['a'] + args['b']
+           val += args['c'] if args['c']
+           val
+         end
+      end
+    end
+
+To run example:
+
+    $ gem install shotgun # unless it's already installed
+    $ shotgun example/config.ru
+
+Browse API and test it via a web browser at http://localhost:9393/
+
+
+## Inline documentation
+
+Use built in helper methods to declare complex types and function
+parameters before defining method calls.
+
+### Custom type definitions
+
+e.g.
+
+    type "Address" do |t|
+      t.string "street", "Street name"
+      t.string "city", "City"
+      ...
+    end
+
+    type "Person" do |t|
+      t.string "name", "Person's name"
+      t.number "age", "Person's age"
+      t.boolean "is_member", "Is person a member of our club?"
+      t.optional do
+        t.field "address", "Address", "Address of person"
+      end
+    end
+
+#### type "Name", &block
+
+> Declare a JSON object type with named keys and value types
+
+#### field "Name", "Type", "Description"
+#### string "Name", "Description"
+#### number "Name", "Description"
+#### integer "Name", "Description"
+#### boolean "Name", "Description"
+
+> Describes the members of a JSON object - fields can be of any known type (see {JSONRPC2::Types} for details).
+
+#### optional &block
+#### required &block
+
+> Use blocks to specify whether an object field is required or optional
+
+---
+
+### Method annotations
+
+e.g.
+
+         desc 'Add numbers'
+         param 'a', 'Number', 'First number'
+         param 'b', 'Number', 'Second number'
+         optional 'c', 'Number', 'Third number'
+         example 'Calculate 1 + 1', :params => { 'a' => 1, 'b' => 1}, :result => 2
+         result 'Number', 'a + b + c'
+         def sum args
+           val = args['a'] + args['b']
+           val += args['c'] if args['c']
+           val
+         end
+
+#### desc "Description of method"
+
+> Short description of what the method does
+
+#### param "Name", "Type", "Description"
+
+or
+
+#### optional "Name", "Type", "Description"
+
+> Description of a named parameter for the method, including type and purpose (see {JSONRPC2::Types} for type details)
+
+#### result "Type", "Description"
+
+> Type and description of return value for method (see {JSONRPC2::Types} for type details)
+
+#### example "Description", "Detail"
+
+> Describe example usage
+
+#### example "Description", { :params => { ... }, :result => value }
+
+> Describe example usage and valid result (NB: values specified for both params and result are checked against the method type descriptions and generating docs will throw an error if the values are invalid).
+
+#### example "Description", { :params => { ... }, :error => value }
+
+> Describe example usage and sample error (NB: values specified for params are checked against the method type descriptions and generating docs throws an error if the values are invalid).
+
+#### nodoc
+
+> Don't include next method in documentation
+
+---
+
+### Interface annotations
+
+e.g.
+
+    title "Calculator interface"
+    introduction "Very simple calculator interface"
+
+    section "Entry points" do 
+      ...
+    end
+
+#### title "Title"
+
+> Set title for interface
+
+#### introduction "Introduction/description of interface"
+
+> Add a basic introduction for the API
+
+#### section "Name", &block
+
+> Group methods into logical sections for documentation purposes
+
+### Authentication
+
+#### auth_with Authenticator
+
+e.g.
+    auth_with JSONRPC2::BasicAuth.new({'apiuser' => 'secretword'})
+
+> Specify authentication method that should be used to verify the access credentials before printing.  See {JSONRPC2::BasicAuth} for examples/info.
+
+

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/example/config.ru

@@ -0,0 +1,34 @@
+$: << File.join(File.dirname(__FILE__),'../lib')
+require 'jsonrpc2/interface'
+
+class ::Object::Calculator < JSONRPC2::Interface
+  title "JSON-RPC2 Calculator"
+  introduction "This interface allows basic maths calculations via JSON-RPC2"
+  auth_with JSONRPC2::BasicAuth.new({'user' => 'secretword'})
+
+  section 'Simple Ops' do
+      desc 'Multiply two numbers'
+      param 'a', 'Number', 'a'
+      param 'b', 'Number', 'b'
+      result 'Number', 'a * b'
+      def mul args
+        args['a'] * args['b']
+      end
+
+      desc 'Add numbers'
+      example "Calculate 1 + 1 = 2", :params => { 'a' => 1, 'b' => 1}, :result => 2
+
+      param 'a', 'Number', 'First number'
+      param 'b', 'Number', 'Second number'
+      optional 'c', 'Number', 'Third number'
+      result 'Number', 'a + b + c'
+      def sum args
+        val = args['a'] + args['b']
+        val += args['c'] if args['c']
+        val
+      end
+  end
+end
+
+run Calculator
+

data/jsonrpc2.gemspec

@@ -0,0 +1,55 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/jsonrpc2/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Geoff Youngs"]
+  gem.email         = ["git@intersect-uk.co.uk"]
+  gem.description   = <<-EOD
+JSON-RPC2 server DSL - allows APIs to be created as mountable Rack applications
+with inline documentation, authentication and type checking.
+
+e.g.
+
+class Calculator < JSONRPC2::Interface
+  title "JSON-RPC2 Calculator"
+  introduction "This interface allows basic maths calculations via JSON-RPC2"
+  auth_with JSONRPC2::BasicAuth.new({'user' => 'secretword'})
+
+  section 'Simple Ops' do
+      desc 'Multiply two numbers'
+      param 'a', 'Number', 'a'
+      param 'b', 'Number', 'b'
+      result 'Number', 'a * b'
+      def mul args
+        args['a'] * args['b']
+      end
+
+      desc 'Add numbers'
+      example "Calculate 1 + 1 = 2", :params => { 'a' => 1, 'b' => 1}, :result => 2
+
+      param 'a', 'Number', 'First number'
+      param 'b', 'Number', 'Second number'
+      optional 'c', 'Number', 'Third number'
+      result 'Number', 'a + b + c'
+      def sum args
+        val = args['a'] + args['b']
+        val += args['c'] if args['c']
+        val
+      end
+  end
+end
+
+EOD
+  gem.summary       = %q{JSON-RPC2 server DSL}
+  gem.homepage      = "http://github.com/geoffyoungs/jsonrpc2"
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "jsonrpc2"
+  gem.require_paths = ["lib"]
+  gem.version       = JSONRPC2::VERSION
+  gem.add_dependency("httpclient")
+  gem.add_dependency("json")
+  gem.add_development_dependency("RedCloth")
+end

data/lib/jsonrpc2.rb

@@ -0,0 +1,4 @@
+require "jsonrpc2/version"
+
+module JSONRPC2
+end

data/lib/jsonrpc2/accept.rb

@@ -0,0 +1,67 @@
+# Utils for parsing HTTP fields
+module JSONRPC2::HTTPUtils
+  module_function
+  # Converts */* -> /^.*?/.*?$/
+  #          text/* -> /^text\/.*?$/
+  #          text/html -> /^text\/html$/
+  #
+  # @param [String] type Media type descriptor
+  # @return [Regexp] Regular expression that matches type
+  def type_to_regex type
+    case type
+    when /[*]/
+      Regexp.new("^#{type.split(/[*]/).map { |bit| Regexp.quote(bit) }.join('.*?')}$")
+    else
+      Regexp.new("^#{Regexp.quote(type)}$")
+    end
+  end
+
+  # Parses the HTTP Accept field and returns a sorted list of prefered
+  # types
+  #
+  # @param field
+  def parse_accept field, regex = false
+    index = -1
+    list = field.split(/,\s*/).map do |media|
+     index += 1
+     case media
+     when /;/
+       media, param_str = *media.split(/\s*;\s*(?=q\s*=)/,2)
+       params = param_str.to_s.split(/\s*;\s*/).inject({}) { |hash, str|
+         k,v = *str.strip.split(/=/).map(&:strip)
+         hash.merge(k => v)
+       }
+       { :q => (params['q'] || 1.0).to_f, :media => media, :index => index }
+     else
+       { :q => 1.0, :media => media, :index => index }
+     end
+    end.sort_by { |option| [-1 * option[:q], option[:media].scan(/[*]/).size, option[:index]] }
+
+    final = {}
+    list.each do |item|
+      q = item[:q]
+      final[q] ||= []
+      final[q].push(regex ? type_to_regex(item[:media]) : item[:media])
+    end
+
+    final.sort_by { |k,v| -1 * k }
+  end
+
+  # Selects the clients preferred media/mime type based on Accept header
+  #
+  # @param [String] http_client_accepts HTTP Accepts header
+  # @param [Array<String>] options Media types available
+  def which http_client_accepts, options
+    return nil unless http_client_accepts
+
+    parse_accept(http_client_accepts, true).each do |preference, types|
+      types.each do |type|
+        options.each do |option|
+          return option if type.match(option)
+        end
+      end
+    end
+
+    nil
+  end
+end

data/lib/jsonrpc2/auth.rb

@@ -0,0 +1,66 @@
+module JSONRPC2
+
+# @abstract Base authentication class
+class Auth
+  # Validate an API request
+  # 
+  # 
+  def check(env, rpc)
+    true
+  end
+end
+
+# @abstract Base class for http-based authentication methods, e.g.
+# {BasicAuth}
+class HttpAuth < Auth
+end
+
+# HTTP Basic authentication implementation
+class BasicAuth < HttpAuth
+  # Create a BasicAuth object
+  #
+  # @param [Hash<String,String>] users containing containing usernames and passwords
+  # @yield [user, pass] Username and password to authenticate
+  # @yieldreturn [Boolean] True if credentials are approved
+  def initialize(users=nil, &block)
+    @users, @lookup = users, block
+  end
+
+  # Checks that the client is authorised to access the API
+  #
+  # @param [Hash,Rack::Request] env Rack environment hash
+  # @param [Hash] rpc JSON-RPC2 call content
+  # @return [true] Returns true or throws :rack_response, [ 401, ... ]
+  def check(env, rpc)
+    valid?(env) or
+    throw(:rack_response, [401, {
+          'Content-Type'     => 'text/html',
+          'WWW-Authenticate' => 'Basic realm="API"'
+    }, ["<html><head/><body>Authentication Required</body></html>"]])
+  end
+
+  def valid?(env)
+    auth = env['HTTP_AUTHORIZATION']
+
+    return false unless auth
+
+    m = /Basic\s+([A-Za-z0-9+\/]+=*)/.match(auth)
+    user, pass = Base64.decode64(m[1]).split(/:/, 2)
+    user_valid?(user, pass)
+  end
+
+  # Checks users hash and then the block given to the constructor to
+  # verify username / password.
+  def user_valid?(user, pass)
+    if @users && @users.respond_to?(:[])
+      if expected = @users[user]
+        return pass == expected
+      end
+    end
+    if @lookup
+      return @lookup.call(user, pass)
+    end
+    false
+  end
+end
+end

data/lib/jsonrpc2/client.rb

@@ -0,0 +1,59 @@
+require 'httpclient'
+require 'json'
+
+module JSONRPC2
+# JSON RPC client error
+class RemoteError < RuntimeError
+end
+
+# Simple JSONRPC client
+class Client
+  # Create client object
+  #
+  # @param [String] uri Create client object
+  # @param [Hash] options Global options
+  def initialize(uri, options = {})
+		@uri = uri
+		@client = HTTPClient.new
+    @options = options
+		@id = 0
+	end
+
+  # Call method with named arguments
+  # @param [String] method Remote method name
+  # @param [Hash<String,Value>] args Hash of named arguments for function
+  # @param [Hash<String,String>] options Additional parameters
+  # @return Method call result
+  # @raise [RemoteError] Error thrown by API
+  # @raise Transport/Network/HTTP errors
+	def call(method, args = {}, options = {}, &block)
+		headers = { 'Content-Type' => 'application/json-rpc' }
+
+    # Merge one level of hashes - ie. merge :headers
+    options = @options.merge(options) { |key,v1,v2| v2 = v1.merge(v2) if v1.class == v2.class && v1.is_a?(Hash); v2 }
+
+    if options[:headers]
+      headers = headers.merge(options[:headers])
+    end
+
+    if options[:auth]
+      @client.set_auth(@uri, options[:auth][:username], options[:auth][:password])
+    end
+		result = @client.post(@uri, 
+							  { 'method' => method, 'params' => args, 'jsonrpc' => '2.0', 'id' => (@id+=1) }.to_json,
+							  headers)
+		if result.contenttype =~ /^application\/json/
+			body = result.body
+			body = body.content if body.respond_to?(:content) #
+			data = JSON.parse body
+			if data.has_key?('result')
+				return data['result']
+			else
+				raise RemoteError, data['error']['message']
+			end
+		else
+			raise result.body
+		end
+	end
+end
+end