ruby-fs-stack 0.1.7

data/lib/ruby-fs-stack/fs_communicator.rb

@@ -0,0 +1,109 @@
+require 'net/https'
+require 'uri'
+
+class FsCommunicator
+  attr_accessor :domain, :key, :user_agent, :session, :handle_throttling
+  
+  # ====Params
+  # <tt>options</tt> - a hash with the following options
+  # * :domain - Defaults to "http://www.dev.usys.org" (the Reference System)
+  # * :key - Your developer key. Defaults to ''
+  # * :user_agent - Your User-Agent string. This should be overridden by your app. It
+  #   defaults to "FsCommunicator/0.1 (Ruby)"
+  # * :session - A session string if you already have one.
+  # * :handle_throttling - (true|false) Defaults to false. If true, when a 503 response
+  #   is received from the API, it will sleep 15 seconds, and try again until successful.
+  #   You will likely want this turned off when running this library from Rails or any other
+  #   system that is single-threaded so as to not sleep the entire process until throttling 
+  #   is successful.
+  def initialize(options = {})
+    # merge default options with options hash
+    o = {
+      :domain => 'http://www.dev.usys.org',
+      :key => '',
+      :user_agent => 'FsCommunicator/0.1 (Ruby)', # should be overridden by options user_agent
+      :session => nil,
+      :handle_throttling => false
+    }.merge(options)
+    @domain = o[:domain]
+    @key = o[:key]
+    @user_agent = o[:user_agent]
+    @session = o[:session]
+    @handle_throttling = o[:handle_throttling]
+  end
+  
+  def post(url,payload)
+    uri = URI.parse(self.domain+url)
+    full_url = set_extra_params(uri)
+    request = Net::HTTP::Post.new(full_url)
+    request.body = payload
+    request['Content-Type'] = "application/json"
+    request['User-Agent'] = self.user_agent
+    http = Net::HTTP.new(uri.host, uri.port)
+    if uri.scheme == 'https'
+      http.use_ssl = true 
+      http.ca_file = File.join File.dirname(__FILE__), 'assets','entrust-ca.crt'
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+    end
+    res = http.start do |ht|
+      ht.request(request)
+    end
+    if res.code == '503' && @handle_throttling
+      sleep 15
+      res = post(url,payload)
+    end
+    return res
+  end
+  
+  def get(url,credentials = {})
+    uri = URI.parse(self.domain+url)
+    full_url = set_extra_params(uri,credentials)
+    request = Net::HTTP::Get.new(full_url)
+    request['User-Agent'] = self.user_agent
+    if credentials[:username] && credentials[:password]
+      request.basic_auth credentials[:username], credentials[:password]
+    end
+    http = Net::HTTP.new(uri.host, uri.port)
+    if uri.scheme == 'https'
+      http.use_ssl = true 
+      http.ca_file = File.join File.dirname(__FILE__), 'assets','entrust-ca.crt'
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+    end
+    res = http.start do |ht|
+      ht.request(request)
+    end
+    if res.code == '503' && @handle_throttling
+      sleep 15
+      res = get(url,credentials)
+    end
+    return res
+  end
+  
+  private
+  def set_extra_params(uri,credentials = {})
+    if credentials[:username] && credentials[:password]
+      sessionized_url = add_key(uri)
+    else
+      sessionized_url = add_session(uri)
+    end
+    sessionized_url << '&dataFormat=application/json'
+  end
+  
+  def add_session(uri)
+    if uri.query
+      uri.query << '&sessionId=' + self.session
+    else
+      uri.query = 'sessionId=' + self.session
+    end
+    uri.request_uri
+  end
+  
+  def add_key(uri)
+    if uri.query
+      uri.query << '&key=' + self.key
+    else
+      uri.query = 'key=' + self.key
+    end
+    uri.request_uri
+  end
+end

data/lib/ruby-fs-stack/fs_utils.rb

@@ -0,0 +1,27 @@
+class FsUtils
+  
+  def self.querystring_from_hash(hash)
+    params = hash.map do |k,v|
+      k = k.to_s
+      if v.is_a? Hash
+        v.collect do |k2,v2|
+          k2 = k2.to_s
+          v2 = v2.to_s
+          url_encode(v2)
+          "#{k}.#{k2}=#{v2}"
+        end.join('&')
+      else
+        v = v.to_s
+        self.url_encode(v)
+        k + '=' + v
+      end
+    end
+    params.join('&')
+  end
+  
+  private
+  def self.url_encode(string)
+    # Taken from http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/156044
+    string.gsub!( /[^a-zA-Z0-9\-_\.!~*'()]/n ) {|x| sprintf('%%%02x', x[0]) }
+  end
+end

data/lib/ruby-fs-stack/identity.rb

@@ -0,0 +1,45 @@
+require 'rubygems'
+require 'ruby-fs-stack/fs_communicator'
+# Including more than one enunciate library raises a warning of
+# already initialized constant.
+require 'ruby-fs-stack/warning_suppressor'
+with_warnings_suppressed do
+  require 'ruby-fs-stack/enunciate/identity'
+end
+
+module IdentityV1
+  
+  # This method gets mixed into the FsCommunicator so that
+  # you can make calls on the fs_familytree_v1 module
+  def identity_v1
+    @identity_v1_com ||= Communicator.new self # self at this point refers to the FsCommunicator instance
+  end
+  
+  class Communicator
+    Base = '/identity/v1/'
+    
+    # ====params
+    # fs_communicator: FsCommunicator instance
+    def initialize(fs_communicator)
+      @communicator = fs_communicator
+    end
+    
+    # ==== Params
+    # <tt>credentials</tt> - :username, :password
+    def authenticate(credentials = {})
+      url = Base + 'login'
+      response = @communicator.get(url, credentials)
+      login_result = Org::Familysearch::Ws::Identity::V1::Schema::Identity.from_json JSON.parse(response.body)
+      if login_result.statusCode == 200
+        @communicator.session = login_result.session.id
+        return true
+      end
+    end
+  end
+  
+end
+
+# Mix in the module so that the identity_v1 can be called
+class FsCommunicator
+  include IdentityV1
+end

data/lib/ruby-fs-stack/warning_suppressor.rb

@@ -0,0 +1,18 @@
+# Kernel#with_warnings_suppressed - Supresses warnings in a given block.
+# Require this file to use it or run it directly to perform a self-test.
+# 
+# Author:: Rob Pitt
+# Copyright:: Copyright (c) 2008 Rob Pitt
+# License:: Free to use and modify so long as credit to previous author(s) is left in place.
+#
+
+module Kernel
+  # Suppresses warnings within a given block.
+  def with_warnings_suppressed
+    saved_verbosity = $-v
+    $-v = nil
+    yield
+  ensure
+    $-v = saved_verbosity
+  end
+end

data/lib/ruby-fs-stack.rb

@@ -0,0 +1,2 @@
+require 'ruby-fs-stack/identity'
+require 'ruby-fs-stack/familytree'

data/spec/communicator_spec.rb

@@ -0,0 +1,214 @@
+ require File.dirname(__FILE__) + '/spec_helper'
+require 'ruby-fs-stack/fs_communicator'
+
+describe FsCommunicator do
+  include HttpCommunicatorHelper
+  describe "initializing" do
+    it "should accept a hash of options" do
+      lambda {
+        com = FsCommunicator.new :domain => 'https://api.familysearch.org', :key => '1111-1111', :user_agent => "FsCommunicator/0.1"
+      }.should_not raise_error
+    end
+    
+    it "should set defaults to the Reference System" do
+      com = FsCommunicator.new
+      com.domain.should == 'http://www.dev.usys.org'
+      com.key.should == ''
+      com.user_agent.should == 'FsCommunicator/0.1 (Ruby)'
+      com.handle_throttling.should == false
+    end
+    
+    it "should set the domain, key, and user_agent to options hash" do
+      options = {
+        :domain => 'https://api.familysearch.org', 
+        :key => '1111-1111', 
+        :user_agent => "RSpecTest/0.1",
+        :session => 'SESSID',
+        :handle_throttling => true
+      }
+      com = FsCommunicator.new options
+      com.domain.should == options[:domain]
+      com.key.should == options[:key]
+      com.user_agent.should == options[:user_agent]
+      com.session.should == options[:session]
+      com.handle_throttling.should == true
+    end
+  end
+  
+  describe "GET on a URL" do
+    before(:each) do
+      options = {
+        :domain => 'https://api.familysearch.org', 
+        :key => '1111-1111', 
+        :user_agent => "FsCommunicator/0.1",
+        :session => 'SESSID'
+      }
+      @com = FsCommunicator.new options
+      stub_net_objects #found in the spec helper
+      @url = '/familytree/v1/person/KWQS-BBQ'
+      @session_url = @url + "?sessionId=#{@com.session}&dataFormat=application/json"
+      @res = mock('HTTP::Response')
+      @res.stub!(:code).and_return('200')
+      @http.stub!(:start).and_return(@res)
+    end
+    
+    def do_get(url, credentials = {})
+      @com.get(url, credentials)
+    end
+    
+    it "should initialize a Net::HTTP object to make the request" do
+      Net::HTTP.should_receive(:new).with('api.familysearch.org',443).and_return(@http)
+      do_get(@url)
+    end
+    
+    it "should create a GET request with url containing a session" do
+      Net::HTTP::Get.should_receive(:new).with(@session_url).and_return(@request)
+      do_get(@url)
+    end
+    
+    it "should tack a sessionId as an additional parameter if params already set" do
+      url = "/familytree/v1/person/KWQS-BBQ?view=summary"
+      Net::HTTP::Get.should_receive(:new).with(url+"&sessionId=#{@com.session}&dataFormat=application/json").and_return(@request)
+      do_get(url)
+    end
+    
+    it "should set the http object to use ssl if https" do
+      @http.should_receive(:use_ssl=).with(true)
+      do_get(@url)
+    end
+    
+    it "should not set the http object to use ssl if no http" do
+      @com.domain = 'http://www.dev.usys.org'
+      @http.should_not_receive(:use_ssl=)
+      do_get(@url)
+    end
+    
+    it "should set the ca file to the entrust certificate (for FamilySearch systems)" do
+      @http.should_receive(:ca_file=).with(File.join(File.dirname(__FILE__),'..','lib','ruby-fs-stack','assets','entrust-ca.crt'))
+      do_get(@url)
+    end
+    
+    it "should set the basic_authentication if the credentials passed as parameters" do
+      @request.should_receive(:basic_auth).with('user','pass')
+      @request.should_receive(:[]=).with('User-Agent',@com.user_agent)
+      Net::HTTP::Get.should_receive(:new).with(@url+"?key=#{@com.key}&dataFormat=application/json").and_return(@request)
+      do_get(@url,:username => 'user',:password => 'pass')
+    end
+    
+    it "should make the request" do
+      block = lambda{ |ht|
+        ht.request('something')
+      }
+      @http.should_receive(:start)
+      do_get(@url)
+    end
+    
+    it "should sleep and call again if handle_throttling is set to true and the response code is 503" do
+      @com.handle_throttling = true
+      @res.stub!(:code).and_return('503','200')
+      @http.stub!(:start).and_return(@res)
+      @com.should_receive(:sleep).once
+      do_get(@url)
+    end
+    
+    it "should not call sleep if handle_throttling is set to false" do
+      @com.handle_throttling = false
+      @res.stub!(:code).and_return('503','200')
+      @http.stub!(:start).and_return(@res)
+      @com.should_not_receive(:sleep)
+      do_get(@url)
+    end
+    
+  end
+  
+  describe "POST on a URL" do
+    before(:each) do
+      options = {
+        :domain => 'https://api.familysearch.org', 
+        :key => '1111-1111', 
+        :user_agent => "FsCommunicator/0.1",
+        :session => 'SESSID'
+      }
+      @com = FsCommunicator.new options
+      stub_net_objects
+      @url = '/familytree/v1/person/KWQS-BBQ'
+      @session_url = @url + "?sessionId=#{@com.session}&dataFormat=application/json"
+      @payload = "<familytree></familytree>"
+      @res = mock('HTTP::Response')
+      @res.stub!(:code).and_return('200')
+      @http.stub!(:start).and_return(@res)
+    end
+    
+    def do_post(url, payload = '')
+      @com.post(url, payload)
+    end
+    
+    it "should initialize a Net::HTTP object to make the request" do
+      Net::HTTP.should_receive(:new).with('api.familysearch.org',443).and_return(@http)
+      do_post(@url)
+    end
+    
+    it "should create a POST request with url containing a session" do
+      Net::HTTP::Post.should_receive(:new).with(@session_url).and_return(@request)
+      do_post(@url)
+    end
+    
+    it "should tack a sessionId as an additional parameter if params already set" do
+      url = "/familytree/v1/person/KWQS-BBQ?view=summary"
+      Net::HTTP::Post.should_receive(:new).with(url+"&sessionId=#{@com.session}&dataFormat=application/json").and_return(@request)
+      do_post(url)
+    end
+    
+    it "should set the request's body to the payload attached" do
+      @request.should_receive(:body=).with(@payload)
+      do_post(@url,@payload)
+    end
+    
+    it "should set the request's Content-Type to application/json" do
+      @request.should_receive(:[]=).with('Content-Type','application/json')
+      do_post(@url,@payload)
+    end
+    
+    it "should set the http object to use ssl if https" do
+      @http.should_receive(:use_ssl=).with(true)
+      do_post(@url)
+    end
+    
+    it "should not set the http object to use ssl if no http" do
+      @com.domain = 'http://www.dev.usys.org'
+      @http.should_not_receive(:use_ssl=)
+      do_post(@url)
+    end
+    
+    it "should set the ca file to the entrust certificate (for FamilySearch systems)" do
+      @http.should_receive(:ca_file=).with(File.join(File.dirname(__FILE__),'..','lib','ruby-fs-stack','assets','entrust-ca.crt'))
+      do_post(@url)
+    end
+        
+    it "should make the request" do
+      block = lambda{ |ht|
+        ht.request('something')
+      }
+      @http.should_receive(:start)
+      do_post(@url)
+    end
+    
+    it "should sleep and call again if handle_throttling is set to true and the response code is 503" do
+      @com.handle_throttling = true
+      @res.stub!(:code).and_return('503','200')
+      @http.stub!(:start).and_return(@res)
+      @com.should_receive(:sleep).once
+      do_post(@url)
+    end
+    
+    it "should not call sleep if handle_throttling is set to false" do
+      @com.handle_throttling = false
+      @res.stub!(:code).and_return('503','200')
+      @http.stub!(:start).and_return(@res)
+      @com.should_not_receive(:sleep)
+      do_post(@url)
+    end
+    
+  end
+  
+end