openstax_exchange 0.0.0 → 0.0.1

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+coverage

data/.rspec

@@ -0,0 +1 @@
+--color --format documentation

data/.ruby-gemset

@@ -0,0 +1 @@
+exchange-ruby

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.9.3-p545

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+rvm:
+  - "1.9.3-p545"
+install:
+  - gem install bundler
+  - bundle install
+script:
+  - bundle exec rake spec

data/Gemfile

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

data/MIT-LICENSE

@@ -1,4 +1,6 @@
-Copyright 2014 Rice University
+Copyright (c) 2015 Rice University
+
+MIT License
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,7 +1,7 @@
 exchange-ruby
 =============
 
-[![Gem Version](https://badge.fury.io/rb/exchange_ruby.svg)](http://badge.fury.io/rb/exchange_ruby)
+[![Gem Version](https://badge.fury.io/rb/openstax_exchange.svg)](http://badge.fury.io/rb/openstax_exchange)
 [![Build Status](https://travis-ci.org/openstax/exchange-ruby.svg?branch=master)](https://travis-ci.org/openstax/exchange-ruby)
 [![Code Climate](https://codeclimate.com/github/openstax/exchange-ruby.png)](https://codeclimate.com/github/openstax/exchange-ruby)
 
@@ -10,35 +10,73 @@ A ruby client for interfacing with the OpenStax Exchange API.
 Usage
 -----
 
-Add the engine to your Gemfile and then run `bundle install`.
+Include the gem in your project:
+```rb
+gem 'openstax_exchange'
+```
+
+Include the following in your script:
+
+```rb
+require 'openstax_exchange'
+```
 
-Create an `openstax_exchange.rb` initializer in `config/initializers`,
-with at least the following contents:
+Configure the client's knowledge of the Exchange server:
 
 ```rb
 OpenStax::Exchange.configure do |config|
-  config.openstax_exchange_platform_id = 'value_from_openstax_exchange_here'
-  config.openstax_exchange_platform_secret = 'value_from_openstax_exchange_here'
+  config.client_platform_id     = '123'
+  config.client_platform_secret = 'abc' ## do not check real secrets into version control!
+  config.client_server_url      = 'http://www.example.com:3000/base/path'
+  config.client_api_version     = 'v1'
+end
+```
+
+By default the real Exchange client will be used.  However, the choice can be made explicitly by using the following:
+
+```rb
+OpenStax::Exchange.use_real_client
+OpenStax::Exchange.use_fake_client
+```
+
+If using the fake client, configure the faked server settings:
+
+```rb
+OpenStax::Exchange::FakeClient.configure do |config|
+  config.registered_platforms   = {'123' => 'abc'}
+  config.server_url             = 'http://www.example.com:3000/base/path'
+  config.supported_api_versions = ['v1']
 end
 ```
 
-If you're running the OpenStax Exchange server in a dev instance on your
-machine, you can specify that instance's local URL with:
+After changing the client configuration, use:
+```rb
+OpenStax::Exchange.reset!
+```
+to ensure that the changes take effect.
 
+The following Exchange API methods are currently supported:
 ```rb
-config.openstax_exchange_url = 'http://localhost:3003/'
+identifier = OpenStax::Exchange.create_identifier
 ```
+```rb
+response = OpenStax::Exchange.record_multiple_choice_answer(identifier, resource_uri, trial, answer)
+```
+
+Running the Specs
+-----------------
 
-Exchange API
-------------
+Create a local clone of the repo, and run the following commands:
+```rb
+bundle install
+bundle exec rake
+```
+The result should be a set of passing specs.
 
-Exchange-ruby provides convenience methods for accessing
-the OpenStax Exchange API.
+## Contributing
 
-`OpenStax::Exchange.api_call(http_method, url, options = {})` provides a
-convenience method capable of making API calls to Exchange. `http_method` can
-be any valid HTTP method, and `url` is the desired API URL, without the 'api/'
-prefix. Options is a hash that can contain any option that
-OAuth2 requests accept, such as :headers, :params, :body, etc,
-plus the optional values :api_version (to specify an API version) and
-:access_token (to specify an OAuth access token).
+1. Fork it ( https://github.com/[my-github-username]/exchange-ruby/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -1,22 +1,14 @@
-#!/usr/bin/env rake
-
 begin
   require 'bundler/setup'
 rescue LoadError
   puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
 end
 
-APP_RAKEFILE = File.expand_path('../spec/dummy/Rakefile', __FILE__)
-load 'rails/tasks/engine.rake'
-
-Bundler::GemHelper.install_tasks
-
-Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each {|f| load f }
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
-require 'rspec/core'
-require 'rspec/core/rake_task'
-
-desc 'Run all specs in spec directory (excluding plugin specs)'
-RSpec::Core::RakeTask.new(:spec => 'app:db:test:prepare')
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.rspec_opts = ['--color', '--format', 'documentation']
+end
 
 task :default => :spec

data/exchange-client.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'openstax/exchange/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "openstax_exchange"
+  spec.version       = OpenStax::Exchange::VERSION
+  spec.authors       = ["Kevin Burleigh"]
+  spec.email         = ["klb@kindlinglabs"]
+  spec.summary       = %q{Ruby client for OpenStax Exchange}
+  spec.description   = %q{}
+  spec.homepage      = "http://github.com/openstax/exchange-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "oauth2", ">= 0.5.0"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "vcr"
+  spec.add_development_dependency "webmock"
+end

data/lib/openstax/exchange/client_instance.rb

@@ -0,0 +1,23 @@
+module OpenStax
+  module Exchange
+    module ClientInstance
+
+      def is_real_client?
+        raise NotImplementedError
+      end
+
+      def token
+        raise NotImplementedError
+      end
+
+      def create_identifier
+        raise NotImplementedError
+      end
+
+      def record_multiple_choice_answer(identifier, resource, trial, answer)
+        raise NotImplementedError
+      end
+
+    end
+  end
+end

data/lib/openstax/exchange/configuration.rb

@@ -0,0 +1,12 @@
+module OpenStax
+  module Exchange
+
+    class Configuration
+      attr_accessor :client_platform_id
+      attr_accessor :client_platform_secret
+      attr_accessor :client_server_url
+      attr_accessor :client_api_version
+    end
+
+  end
+end

data/lib/openstax/exchange/exceptions.rb

@@ -0,0 +1,21 @@
+module OpenStax
+  module Exchange
+
+    class ClientError < StandardError
+      def initialize(msg, original=$!)
+        super(msg)
+        @original = original
+        set_backtrace(original.backtrace)
+      end
+
+      def inspect
+        [super, @original.inspect].join(" ")
+      end
+
+      def message
+        [super, "(#{@original.message})"].join(" ")
+      end
+    end
+
+  end
+end

data/lib/openstax/exchange/exchange.rb

@@ -0,0 +1,65 @@
+module OpenStax
+  module Exchange
+
+    @use_real_client = true
+
+    def self.configure
+      yield configuration
+    end
+
+    def self.configuration
+      @configuration ||= Configuration.new
+    end
+
+    def self.reset!
+      @client = nil
+    end
+
+    def self.use_real_client
+      @use_real_client = true
+    end
+
+    def self.use_fake_client
+      @use_real_client = false
+    end
+
+    def self.use_real_client?
+      !!@use_real_client
+    end
+
+    def self.create_identifier
+      begin
+        client.create_identifier
+      rescue StandardError => error
+        raise ClientError.new("create_identifier failure", error)
+      end
+    end
+
+    def self.record_multiple_choice_answer(*args)
+      begin
+        client.record_multiple_choice_answer(*args)
+      rescue StandardError => error
+        raise ClientError.new("record_multiple_choice_answer failure", error)
+      end
+    end
+
+    private
+
+    def self.client
+      begin
+        @client ||= create_client
+      rescue StandardError => error
+        raise ClientError.new("initialization failure", error)
+      end
+    end
+
+    def self.create_client
+      if use_real_client?
+        RealClient.new configuration
+      else
+        FakeClient.new configuration
+      end
+    end
+
+  end
+end

data/lib/openstax/exchange/fake_client/configuration.rb

@@ -0,0 +1,13 @@
+module OpenStax
+  module Exchange
+
+    class FakeClient
+      class Configuration
+        attr_accessor :registered_platforms
+        attr_accessor :server_url
+        attr_accessor :supported_api_versions
+      end
+    end
+
+  end
+end

data/lib/openstax/exchange/fake_client/fake_client.rb

@@ -0,0 +1,71 @@
+require 'securerandom'
+require 'uri'
+
+module OpenStax
+  module Exchange
+
+    class FakeClient
+      include ClientInstance
+
+      def self.configure
+        yield configuration
+      end
+
+      def self.configuration
+        @configuration ||= Configuration.new
+      end
+
+      def initialize(exchange_configuration)
+        @client_config_platform_id     = exchange_configuration.client_platform_id
+        @client_config_platform_secret = exchange_configuration.client_platform_secret
+        @client_config_server_url      = exchange_configuration.client_server_url
+        @client_config_api_version     = exchange_configuration.client_api_version
+
+        @server_registered_platforms   = self.class.configuration.registered_platforms
+        @server_server_url             = self.class.configuration.server_url
+
+        raise "invalid server url" \
+          unless @client_config_server_url == @server_server_url
+
+        raise "invalid platform credentials" \
+          unless @server_registered_platforms.fetch(@client_config_platform_id) == @client_config_platform_secret
+
+        @token = SecureRandom.hex(64)
+        @multiple_choice_responses = {}
+      end
+
+      def is_real_client?
+        false
+      end
+
+      def token
+        @token
+      end
+
+      def create_identifier
+        SecureRandom.hex(64)
+      end
+
+      def record_multiple_choice_answer(identifier, resource, trial, answer)
+        @multiple_choice_responses[identifier] ||= {}
+        @multiple_choice_responses[identifier][resource] ||= {}
+
+        raise "invalid resource" \
+          unless URI(resource).host == "exercises.openstax.org"
+
+        raise "duplicate response for (identifier,resource,trial) triplet" \
+          if @multiple_choice_responses[identifier][resource][trial]
+
+        @multiple_choice_responses[identifier][resource][trial] = answer
+
+        return {
+          'identifier' => identifier,
+          'resource'   => resource,
+          'trial'      => trial,
+          'answer'     => answer
+        }
+      end
+    end
+
+  end
+end

data/lib/openstax/exchange/real_client/real_client.rb

@@ -0,0 +1,76 @@
+require 'oauth2'
+
+module OpenStax
+  module Exchange
+
+    class RealClient
+      include ClientInstance
+
+      def initialize(exchange_configuration)
+        @platform_id     = exchange_configuration.client_platform_id
+        @platform_secret = exchange_configuration.client_platform_secret
+        @server_url      = exchange_configuration.client_server_url
+        @api_version     = exchange_configuration.client_api_version
+
+        @oauth_client = OAuth2::Client.new(
+          @platform_id,
+          @platform_secret,
+          site: @server_url)
+
+        @oauth_token = @oauth_client.client_credentials.get_token
+      end
+
+      def is_real_client?
+        true
+      end
+
+      def token
+        @oauth_token.token
+      end
+
+      def create_identifier
+        options = {}
+        add_accept_header! options
+
+        response = @oauth_token.request(
+          :post,
+          "#{@server_url}/api/identifiers",
+          options)
+
+        return JSON.parse(response.body)['identifier']
+      end
+
+      def record_multiple_choice_answer(identifier, resource, trial, answer)
+        options = {}
+        add_accept_header! options
+        add_authorization_header! options
+
+        options[:body] = { identifier: identifier, resource: resource, trial: trial, answer: answer }.to_json
+
+        response = @oauth_token.request(
+          :post,
+          "#{@server_url}/api/events/platforms/multiple_choices",
+          options)
+
+        return JSON.parse(response.body)
+      end
+
+      private
+
+      def add_header_hash!(options)
+        options[:headers] = {} unless options.has_key? :headers
+      end
+
+      def add_accept_header!(options)
+        add_header_hash! options
+        options[:headers].merge!({ 'Accept' => "application/vnd.exchange.openstax.#{@api_version}" })
+      end
+
+      def add_authorization_header!(options)
+        add_header_hash! options
+        options[:headers].merge!({ 'Authorization' => "Bearer #{token}" })
+      end
+    end
+
+  end
+end