gprov 0.0.7 → 0.0.8

data/CHANGELOG

@@ -0,0 +1,8 @@
+Changelog
+=========
+
+0.0.8
+
+  - (gprov #4) Perform full fetches of paginates results
+  - Expand and clean up test coverage
+  - Better comments

data/Guardfile

@@ -0,0 +1,9 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+
+end

data/README.markdown

@@ -24,3 +24,14 @@ Examples
 
 [gtool](https://github.com/adrienthebo/gtool) - a command line interface to the
 provisioning API.
+
+Development
+-----------
+
+  * Source: https://github.com/adrienthebo/ruby-gprov
+  * Issues: https://github.com/adrienthebo/ruby-gprov/issues
+
+This is alpha software. While I've done extensive real world testing of this
+myself, it's not feature complete and doesn't have enough test coverage. Please
+file bug reports and let me know where it's lacking; I'm very interested in
+improving it!

data/lib/gprov/connection.rb

@@ -50,7 +50,7 @@ module GProv
 
         # Assign default arguments and validate passed arguments
         if path.nil?
-          raise "#{self.class}##{verb} requires a non-nil path"
+          raise ArgumentError, "#{self.class}##{verb} requires a non-nil path"
         end
 
         # If extra headers were passed in, explode the containing array. Else,

data/lib/gprov/error.rb

@@ -20,8 +20,15 @@ module GProv
     def initialize(request = nil)
       @request = request
     end
+
+    # Raised when the requesting user is not authenticated, IE has an invalid
+    # token
     class TokenInvalid < GProv::Error; end
+
+    # Raised when a request is malformed
     class InputInvalid < GProv::Error; end
+
+    # Raised when the Google Apps request quota is exceeded
     class QuotaExceeded < GProv::Error; end
   end
 end

data/lib/gprov/provision/entrybase.rb

@@ -31,6 +31,7 @@ module GProv
       # Possible data sources:
       #  * Hash of attribute names and values
       #  * A nokogiri node containing the root of the object
+      #  * nothing, as in we have a fresh object.
       def initialize(opts={})
 
         @status = (opts[:status] || :new)
@@ -50,12 +51,12 @@ module GProv
         when NilClass
           # New object!
         else
-          raise
+          raise ArgumentError, "unrecognized object source #{opts[:source]}"
         end
       end
 
-      # Takes all xml_attr_accessors defined and an xml document and
-      # extracts the values from the xml into a hash.
+      # Takes all xmlattrs defined against this object, and a given XML
+      # document, and converts each xmlattr into the according value.
       def xml_to_hash(xml)
         h = {}
         if attrs = self.class.attributes

data/lib/gprov/provision/entrybase/xmlattr.rb

@@ -31,7 +31,12 @@ module GProv
   module Provision
     class EntryBase
       class XMLAttr
+
+        # The name attribute is not used by this class, but is used by calling
+        # classes to determine the method/attribute name they'll use to
+        # associate with this object.
         attr_reader :name
+
         def initialize(name, options={})
           @name = name
           @type = :string
@@ -48,12 +53,14 @@ module GProv
           if [:numeric, :string, :bool].include? val
             @type = val
           else
-            raise ArgumentException
+            raise ArgumentError, "#{@type} is not recognized as a valid format type"
           end
 
           @type
         end
 
+        # Given an XML document, use the supplied xpath value to extract the
+        # desired value for this attribute from the document.
         def parse(xml)
           @value = xml.at_xpath(@xpath).to_s
           format
@@ -61,6 +68,8 @@ module GProv
 
         private
 
+        # Convert the given attribute from a string into an actual meaningful
+        # type.
         def format
           case @type
           when :numeric
@@ -73,10 +82,20 @@ module GProv
             else # XXX sketchy
               @value = false
             end
+          else
+            raise ArgumentError, "Unable to format data: #{@type} is not recognized as a valid format type"
           end
           @value
         end
 
+        # Given a hash, use the keys as method names and the values as the
+        # arguments to send to the method. This allows for quick instantiation
+        # of this type.
+        #
+        # *Example:*
+        #
+        #   XMLAttr.new(:example, :type => :bool, :xpath => '/my/xpath')
+        #
         def methodhash(hash)
           hash.each_pair do |method, value|
             if respond_to? method

data/lib/gprov/provision/feed.rb

@@ -1,44 +1,99 @@
 # Generic representation of the various types of feeds available from the
 # provisioning api
 require 'gprov'
+require 'gprov/provision/entrybase/xmlattr'
 require 'nokogiri'
 
 module GProv
   module Provision
     class Feed
 
-      attr_reader :results
-      def initialize(connection, path, xpath)
+      def initialize(connection, url, xpath)
         @connection = connection
-        @url        = path
+        @url        = url
         @xpath      = xpath
 
         @results = []
       end
 
-      def fetch
-        retrieve_page
+      # Retrieve all entries in a feed, represented as nokogiri elements. Takes
+      # an optional block and yields to it each successive page of results
+      # retrieved. Returns all of the entries in the feed.
+      def fetch(&block)
+        link = @url
+
+        until link.nil?
+          document = retrieve(link)
+          results  = parse(document)
+          link     = results[:nextpage]
+          entries  = results[:entries]
+
+          yield entries if block_given?
+        end
         @results
       end
 
-      private
+      # If no results are available, fetch them. Else return what data we have
+      # already downloaded.
+      def results
+        fetch unless @results
+        @results
+      end
 
-      def retrieve_page
-        response = @connection.get(@url)
+      private
 
-        if response.code == 200
-          document = Nokogiri::XML(response.body)
-          entries = document.xpath(@xpath)
+      # Retrieves a page of results.
+      def retrieve(url)
+        response = @connection.get(url)
 
-          @results.concat(entries.to_a)
+        if response.success?
+          response.body
+        else
+          raise RuntimeError, "Failed to retrieve #{url}: HTTP #{response.code} #{response.body}"
         end
       end
 
-      def retrieve_all
-        raise NotImplementedError
+      # Given an XML document, returns an array of the desired entries and a
+      # link to the next page in the feed.
+      def parse(xml)
+
+        document = Nokogiri::XML(xml)
+        entries = document.xpath(@xpath)
+        @results.concat(entries.to_a)
+
+        {:entries => entries, :nextpage => atomlink(document)}
       end
 
+      # Attempt to retrieve the atom:link tag if it's contained in the
+      # given document, indicating that there are more paginated results.
+      def atomlink(xml)
+        # Effectively memoize this XMLAttr object, since we can use it for
+        # ever parsed page.
+        @atomlink ||= GProv::Provision::EntryBase::XMLAttr.new(:link, :xpath => %{/xmlns:feed/xmlns:link[@rel = "next"]/@href})
+
+        # REVIEW This might be utilizing behavior that's unexpected. This
+        # retrieves a fully qualified URL, which means that it might be
+        # bypassing some of the logic in the GProv::Conection code. Instead of
+        # passing in the base resource URI like the rest of GProv, we're
+        # blindly using this
+        #
+        # So instead of retrieving this:
+        #
+        #   /group/2.0/:domain/<group>@<domain>/member?start=<string>
+        #
+        # We're retrieving this:
+        #
+        # https://apps-apis.google.com/a/feeds/group/2.0/<domain>/<group>@<domain>/member?start=<string>
+        #
+        # This works, since by the nature of this request the group and domain
+        # are filled in correctly. However, it ignores the baseuri respected by
+        # the rest of this library, the :domain symbol, and other behaviors.
+        # This should continue to work, but if HTTParty stops allowing fully
+        # qualified URLs like this and merely prepends the current baseuri to
+        # this string then the world will explode.
+        link = @atomlink.parse(xml)
+        link unless link.empty?
+      end
     end
   end
 end
-

data/lib/gprov/version.rb

@@ -1,3 +1,3 @@
 module GProv
-  VERSION = "0.0.7"
+  VERSION = "0.0.8"
 end

data/spec/gprov/connection_spec.rb

@@ -1,8 +1,15 @@
 require 'spec_helper'
 
-describe GProv::Connection do
+klass = GProv::Connection
 
-  let(:klass) { GProv::Connection }
+describe klass, 'HTTPary' do
+
+  it "should use to google apps API url as the base uri" do
+    klass.base_uri.should == "https://apps-apis.google.com/a/feeds"
+  end
+end
+
+describe klass, "base methods" do
 
   subject { GProv::Connection.new("domain", "token") }
 
@@ -13,49 +20,141 @@ describe GProv::Connection do
     }}
   end
 
-  it "should use to google apps API url as the base uri" do
-    klass.base_uri.should == "https://apps-apis.google.com/a/feeds"
-  end
-
   it { should respond_to :domain }
 
   it "should expose the default headers" do
     subject.default_headers.should == expected_options
   end
 
+  let(:successful_request) do
+    req = stub 'request'
+    req.stubs(:code).returns 200
+    req.stubs(:success?).returns true
+    req
+  end
 
-  describe "http instance method" do
-    [:put, :get, :post, :delete].each do |verb|
-
+  [:put, :get, :post, :delete].each do |verb|
+    describe "method ##{verb}" do
       it { should respond_to verb }
 
-      describe "##{verb}" do
+      it "should be forwarded to the class" do
+        klass.expects(verb).returns successful_request
+        subject.send(verb, '')
+      end
+    end
+  end
+
+  describe 'request processing' do
+
+    it "should interpolate the :domain substring" do
+      klass.expects(:get).with("/domain", expected_options).returns successful_request
+      subject.send(:get, "/:domain")
+    end
+
+    it "should require a non-nil path" do
+      expect {
+        subject.send(:get, nil)
+      }.to raise_error ArgumentError, /non-nil/
+    end
+
+    describe "with HTTP return code 200" do
+      before do
+        klass.stubs(:get).returns successful_request
+      end
+
+      it "should not raise an error" do
+        subject.send(:get, '/')
+      end
+
+      it "should return the http response" do
+        output = subject.send(:get, "/url")
+        output.should be successful_request
+      end
+    end
+
+    describe "with HTTP return code 401" do
+      let(:noauth) do
+        req = stub 'request'
+        req.stubs(:code).returns 401
+        req
+      end
+
+      before do
+        klass.stubs(:get).returns noauth
+      end
+
+      it "should raise an invalid token error" do
+        expect { subject.send(:get, '/') }.to raise_error GProv::Error::TokenInvalid
+      end
+    end
+
+    describe "with HTTP return code 403" do
+      let(:noauth) do
+        req = stub 'request'
+        req.stubs(:code).returns 403
+        req
+      end
+
+      before do
+        klass.stubs(:get).returns noauth
+      end
+
+      it "should raise an invalid input error" do
+        expect { subject.send(:get, '/') }.to raise_error GProv::Error::InputInvalid
+      end
+    end
+
+    describe "with HTTP return code 503" do
+      let(:exceeded) do
+        req = stub 'request'
+        req.stubs(:code).returns 503
+        req
+      end
+
+      before do
+        klass.stubs(:get).returns exceeded
+      end
+
+      it "should raise a quota exceeded error" do
+        expect { subject.send(:get, '/') }.to raise_error GProv::Error::QuotaExceeded
+      end
+    end
+
+    describe "with any other HTTP status code" do
+
+      describe "that is successful" do
+        let(:ok) do
+          req = stub 'request'
+          req.stubs(:code).returns 201
+          req.stubs(:success?).returns true
+          req
+        end
+
         before do
-          xml = %Q{<?xml version="1.0" encoding="UTF-8"?>\n<test xml="pointy" />}
-          @stub_request = mock
-          @stub_request.stubs(:code).returns 200
-          @stub_request.stubs(:success?).returns true
-          @stub_request.stubs(:class).returns HTTParty::Response
+          klass.stubs(:get).returns ok
         end
 
+        it "should not raise an error" do
+          expect { subject.send(:get, '/') }.to_not raise_error
+        end
+      end
 
-        it "should be forwarded to the class" do
-          klass.expects(verb).returns @stub_request
-          subject.send(verb, '')
+      describe "that is not successful" do
+        let(:nok) do
+          req = stub 'request'
+          req.stubs(:code).returns 404
+          req.stubs(:success?).returns false
+          req
         end
 
-        it "should return the http response" do
-          klass.expects(verb).returns @stub_request
-          output = subject.send(verb, "/url")
-          output.class.should == HTTParty::Response
+        before do
+          klass.stubs(:get).returns nok
         end
 
-        it "should interpolate the :domain substring" do
-          klass.expects(verb).with("/domain", expected_options).returns @stub_request
-          subject.send(verb, "/:domain")
+        it "should raise an error" do
+          expect { subject.send(:get, '/') }.to raise_error GProv::Error
         end
       end
     end
   end
 end
-

data/spec/gprov/provision/entrybase/classmethods_spec.rb

@@ -5,7 +5,7 @@ describe GProv::Provision::EntryBase::ClassMethods do
 
   subject { FakeEntry }
 
-  [:xmlattr, :xml_to_hash, :attributes].each do |method|
+  [:xmlattr, :attributes].each do |method|
     it { should respond_to method }
   end
 

data/spec/gprov/provision/entrybase_spec.rb

@@ -5,7 +5,21 @@ require 'fakeentry'
 
 describe GProv::Provision::EntryBase do
 
-  [:status, :connection].each do |method|
-    it { should respond_to method }
+  let(:klass) { GProv::Provision::EntryBase }
+
+  describe "initialization" do
+
+    it "should require a connection" do
+      expect { klass.new }.to raise_error ArgumentError, /requires a connection parameter/
+    end
+  end
+
+  describe "basic methods" do
+    let(:connection) { stub 'connection' }
+    subject { klass.new(:connection => connection) }
+
+    [:status, :connection].each do |method|
+      it { should respond_to method }
+    end
   end
 end

metadata

@@ -1,89 +1,86 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: gprov
-version: !ruby/object:Gem::Version 
-  hash: 17
+version: !ruby/object:Gem::Version
+  version: 0.0.8
   prerelease: 
-  segments: 
-  - 0
-  - 0
-  - 7
-  version: 0.0.7
 platform: ruby
-authors: 
+authors:
 - Adrien Thebo
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-05-10 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-05-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: httparty
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 27
-        segments: 
-        - 0
-        - 8
-        version: "0.8"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0.8'
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: nokogiri
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 5
-        segments: 
-        - 1
-        - 5
-        version: "1.5"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.5'
   type: :runtime
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rspec
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 7
-        segments: 
-        - 2
-        version: "2"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: mocha
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id004
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Ruby bindings to the Google Provisioning API
 email: adrien@puppetlabs.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - lib/gprov/auth/clientlogin.rb
 - lib/gprov/auth.rb
 - lib/gprov/connection.rb
@@ -111,41 +108,33 @@ files:
 - spec/gprov/provision/user.rb
 - spec/lib/fakeentry.rb
 - spec/spec_helper.rb
+- CHANGELOG
+- Guardfile
 - LICENSE
 - Rakefile
 - README.markdown
 homepage: http://github.com/adrienthebo/ruby-gprov
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Ruby bindings to the Google Provisioning API
 test_files: []
-