azure-armrest 0.3.5 → 0.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f4ef3f0022820f1bff78cb13d0be5e2704e1b60
-  data.tar.gz: 1be8e6dc7474255e856886a5f9ad280f69f64e6a
+  metadata.gz: d581e8606ff8fb662506a034bd0ba4dca0d5ce02
+  data.tar.gz: f5b4a1c3e4b474db88bab04a40a5b73e395ee2e2
 SHA512:
-  metadata.gz: ecd8bde54c64287d360291fe01e832f76a4328bdcfb162ab07d66afe93ff46df27521eb37e9960f206e31a2a8675054aa4f29fc78e5e24d1c4527381b79a4195
-  data.tar.gz: 51c49f5d53aedd4bf340034352a7abcf389bb703692bae4834bbb8324f1e130cadbacf847525cba6530a110eaa7acf406c533c1c99dfdb39e24e68db03a923a8
+  metadata.gz: b2a57e5c9b36b7c1bf9d28525cd4d3b3be4772c89b1b9d1342d6773b434846634b458fa8efefbc6f3549f6b6aac469dea7489c9ca44f0b80d45d4f5263cd5863
+  data.tar.gz: 411f85036c00fea64f13ff0c494e2d27172f6fcf67ad029e98b4a3f705f61966179485034c982de7598a6f642c24edd2e4429fbd13f0457ec80ac4d70f556f70

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+/futz/

data/CHANGES

@@ -1,3 +1,14 @@
+= 0.3.6 - 13-Sep-2016
+* Added the poll and wait methods to the ArmrestService base class. These
+  are meant for use with asynchronous operations, e.g. create and delete.
+* All methods that returned a plain array now return an ArmrestCollection
+  object instead. This is a subclass of Array, but includes header and
+  skip token information.
+* Added the ArmrestCollection.create_from_response method. This creates
+  and returns a collection based on a JSON response and a model type.
+* Minor update to the ApiException#to_s method so that includes a bit
+  more information.
+
 = 0.3.5 - 11-Aug-2016
 * When we added subscription ID validation in 0.3.2 we forgot to set proxy
   information first. That has been fixed.

data/lib/azure/armrest/armrest_collection.rb

@@ -4,6 +4,34 @@ module Azure
   module Armrest
     class ArmrestCollection < Array
       attr_accessor :continuation_token
+      attr_accessor :response_headers
+
+      alias skip_token continuation_token
+      alias skip_token= continuation_token=
+
+      class << self
+        # Creates and returns a ArmrestCollection object based on JSON input,
+        # using +klass+ to generate the list elements. In addition, both the
+        # response headers and continuation token are set.
+        #
+        def create_from_response(response, klass = nil)
+          json_response = JSON.parse(response)
+          array = new(json_response['value'].map { |hash| klass.new(hash) })
+
+          array.response_headers = response.headers
+          array.continuation_token = parse_skip_token(json_response)
+
+          array
+        end
+
+        private
+
+        # Parse the skip token value out of the nextLink attribute from a response.
+        def parse_skip_token(json)
+          return nil unless json['nextLink']
+          json['nextLink'][/.*?skipToken=(.*?)$/i, 1]
+        end
+      end
     end
   end
 end

data/lib/azure/armrest/armrest_service.rb

@@ -157,6 +157,44 @@ module Azure
         JSON.parse(resp.body)['value'].map{ |hash| Azure::Armrest::Tenant.new(hash) }
       end
 
+      # Poll a resource and return its current operations status. The
+      # +response+ argument should be a ResponseHeaders object that
+      # contains the :azure_asyncoperation header. It may optionally
+      # be an object that returns a URL from a .to_s method.
+      #
+      # This is meant to check the status of asynchronous operations,
+      # such as create or delete.
+      #
+      def poll(response)
+        url = response.respond_to?(:azure_asyncoperation) ? response.azure_asyncoperation : response.to_s
+        JSON.parse(rest_get(url))['status']
+      end
+
+      # Wait for the given +response+ to return a status of 'Succeeded', up
+      # to a maximum of +max_time+ seconds, and return the operations status.
+      # The first argument must be a ResponseHeaders object that contains
+      # the azure_asyncoperation header.
+      #
+      # Internally this will poll the response header every :retry_after
+      # seconds (or 10 seconds if that header isn't found), up to a maximum of
+      # 60 seconds by default.
+      #
+      # For most resources the +max_time+ argument should be more than sufficient.
+      # Certain resources, such as virtual machines, could take longer.
+      #
+      def wait(response, max_time = 60)
+        sleep_time = response.respond_to?(:retry_after) ? response.retry_after.to_i : 10
+        total_time = 0
+
+        while (status = poll(response)).casecmp('Succeeded') != 0
+          total_time += sleep_time
+          break if total_time >= max_time
+          sleep sleep_time
+        end
+
+        status
+      end
+
       class << self
         private
 

data/lib/azure/armrest/exception.rb

@@ -4,15 +4,30 @@ module Azure
       attr_accessor :cause
       attr_writer :message
 
+      # Create a new Armrest::Exception object. The +message+ should be an
+      # error string, while +cause_exception+ is typically set to the
+      # raw RestClient exception.
+      #
+      # You will not typically use this object directly.
+      #
       def initialize(message = nil, cause_exception = nil)
         @message = message
         @cause = cause_exception
       end
 
+      # The stringified version (message) of the exception.
+      #
       def to_s
-        message
+        if cause
+          "#{message} (cause: #{cause})"
+        else
+          message
+        end
       end
 
+      # The error message or, if the message is not set, the name of the
+      # exception class.
+      #
       def message
         @message || self.class.name
       end
@@ -21,16 +36,24 @@ module Azure
     class ApiException < Exception
       attr_accessor :code
 
+      # Create a new ApiException class. The +code+ is the error code.
+      #
+      # This class serves as the parent
       def initialize(code, message, cause_exception)
         @code = code
         super(message, cause_exception)
       end
 
+      # A stringified version of the error. If self is a plain ApiException,
+      # then the cause is included to aid in debugging.
+      #
       def to_s
-        "[#{code}] #{message}"
+        "[#{code}] #{super}"
       end
     end
 
+    # A list of predefined exceptions that we wrap around RestClient exceptions.
+
     class ResourceNotFoundException < ApiException; end
 
     class BadRequestException < ApiException; end
@@ -42,6 +65,5 @@ module Azure
     class GatewayTimeoutException < ApiException; end
 
     class TooManyRequestsException < ApiException; end
-
   end
 end

data/lib/azure/armrest/insights/event_service.rb

@@ -44,22 +44,16 @@ module Azure
         #   filter = "eventTimestamp ge #{date} and eventChannels eq 'Admin, Operation'"
         #   select = "resourceGroupName, operationName"
         #
-        #   ies.list(:filter => filter, :select => select, :all => true).events.each{ |event|
+        #   ies.list(:filter => filter, :select => select, :all => true).each{ |event|
         #     p event
         #   }
         #
         def list(options = {})
           url = build_url(options)
           response = rest_get(url)
-          json_response = JSON.parse(response.body)
 
-          events = ArmrestCollection.new(
-            json_response['value'].map do |hash|
-              Azure::Armrest::Insights::Event.new(hash)
-            end
-          )
-
-          events.continuation_token = parse_skip_token(json_response)
+          klass  = Azure::Armrest::Insights::Event
+          events = Azure::Armrest::ArmrestCollection.create_from_response(response, klass)
 
           if options[:all] && events.continuation_token
             events.push(*list(options.merge(:skip_token => events.continuation_token)))

data/lib/azure/armrest/model/base_model.rb

@@ -22,6 +22,8 @@ module Azure
 
       attr_hash :tags
 
+      attr_accessor :response_headers
+
       # Constructs and returns a new JSON wrapper class. Pass in a plain
       # JSON string and it will automatically give you accessor methods
       # that make it behave like a typical Ruby object. You may also pass

data/lib/azure/armrest/model/storage_account.rb

@@ -21,7 +21,7 @@ module Azure
       class TableData < BaseModel; end
 
       # The version string used in headers sent as part any internal http
-      # request. The default is 2015-02-21.
+      # request. The default is 2015-12-11.
       attr_accessor :storage_api_version
 
       # An http proxy to use per request. Defaults to ENV['http_proxy'] if set.
@@ -35,7 +35,7 @@ module Azure
 
       def initialize(json)
         super
-        @storage_api_version = '2015-02-21'
+        @storage_api_version = '2015-12-11'
         @proxy = ENV['http_proxy']
         @ssl_version = 'TLSv1'
         @ssl_verify = nil
@@ -99,11 +99,12 @@ module Azure
         key ||= properties.key1
 
         query = build_query(options)
-
         response = table_response(key, query, name)
-        json_response = JSON.parse(response.body)
 
-        data = ArmrestCollection.new(json_response['value'].map { |t| TableData.new(t) })
+        klass = Azure::Armrest::StorageAccount::TableData
+        data  = Azure::Armrest::ArmrestCollection.create_from_response(response, klass)
+
+        # Continuation tokens are parsed differently for storage
         data.continuation_token = parse_continuation_tokens(response)
 
         if options[:all] && data.continuation_token

data/lib/azure/armrest/resource_group_based_service.rb

@@ -2,6 +2,17 @@ module Azure
   module Armrest
     # Base class for services that need to run in a resource group
     class ResourceGroupBasedService < ArmrestService
+      # Create a resource +name+ within the resource group +rgroup+, or the
+      # resource group that was specified in the configuration, along with
+      # a hash of appropriate +options+.
+      #
+      # Returns an instance of the object that was created if possible,
+      # otherwise nil is returned.
+      #
+      # Note that this is an asynchronous operation. You can check the current
+      # status of the resource by inspecting the :response_headers instance and
+      # polling either the :azure_asyncoperation or :location URL.
+      #
       def create(name, rgroup = configuration.resource_group, options = {})
         validate_resource_group(rgroup)
         validate_resource(name)
@@ -9,18 +20,33 @@ module Azure
         url = build_url(rgroup, name)
         url = yield(url) || url if block_given?
         response = rest_put(url, options.to_json)
-        model_class.new(response) unless response.empty?
+
+        obj = nil
+
+        unless response.empty?
+          obj = model_class.new(response.body)
+          obj.response_headers = Azure::Armrest::ResponseHeaders.new(response.headers)
+        end
+
+        obj
       end
 
       alias update create
 
+      # List all resources within the resource group +rgroup+, or the
+      # resource group that was specified in the configuration.
+      #
+      # Returns an ArmrestCollection, with the response headers set
+      # for the operation as a whole.
+      #
       def list(rgroup = configuration.resource_group)
         validate_resource_group(rgroup)
 
         url = build_url(rgroup)
         url = yield(url) || url if block_given?
         response = rest_get(url)
-        JSON.parse(response)['value'].map { |hash| model_class.new(hash) }
+
+        Azure::Armrest::ArmrestCollection.create_from_response(response, model_class)
       end
 
       # Use a single call to get all resources for the service. You may
@@ -35,11 +61,16 @@ module Azure
       def list_all(filter = {})
         url = build_url
         url = yield(url) || url if block_given?
+
         response = rest_get(url)
-        results = JSON.parse(response)['value'].map { |hash| model_class.new(hash) }
+        results  = Azure::Armrest::ArmrestCollection.create_from_response(response, model_class)
+
         filter.empty? ? results : results.select { |obj| filter.all? { |k, v| obj.public_send(k) == v } }
       end
 
+      # Get information about a single resource +name+ within resource group
+      # +rgroup+, or the resource group that was set in the configuration.
+      #
       def get(name, rgroup = configuration.resource_group)
         validate_resource_group(rgroup)
         validate_resource(name)
@@ -47,7 +78,11 @@ module Azure
         url = build_url(rgroup, name)
         url = yield(url) || url if block_given?
         response = rest_get(url)
-        model_class.new(response)
+
+        obj = model_class.new(response.body)
+        obj.response_headers = Azure::Armrest::ResponseHeaders.new(response.headers)
+
+        obj
       end
 
       # Delete the resource with the given +name+ for the provided +resource_group+,
@@ -101,19 +136,27 @@ module Azure
 
       # Aggregate resources from all resource groups.
       #
-      # To be used in the cases where the API does not support list_all with one call.
+      # To be used in the cases where the API does not support list_all with
+      # one call. Note that this does not set the skip token because we're
+      # actually collating the results of multiple calls internally.
       #
       def list_in_all_groups
-        array = []
-        mutex = Mutex.new
+        array   = []
+        mutex   = Mutex.new
+        headers = nil
 
         Parallel.each(list_resource_groups, :in_threads => configuration.max_threads) do |rg|
           response = rest_get(build_url(rg.name))
-          results = JSON.parse(response)['value'].map { |hash| model_class.new(hash) }
+          json_response = JSON.parse(response.body)['value']
+          headers = Azure::Armrest::ResponseHeaders.new(response.headers)
+          results = json_response.map { |hash| model_class.new(hash) }
           mutex.synchronize { array << results } unless results.blank?
         end
 
-        array.flatten
+        array = ArmrestCollection.new(array.flatten)
+        array.response_headers = headers # Use the last set of headers for the overall result
+
+        array
       end
     end
   end

data/lib/azure/armrest/resource_group_service.rb

@@ -26,8 +26,7 @@ module Azure
         url << "&$filter=#{options[:filter]}" if options[:filter]
 
         response = rest_get(url)
-
-        JSON.parse(response)['value'].map { |hash| Azure::Armrest::ResourceGroup.new(hash) }
+        Azure::Armrest::ArmrestCollection.create_from_response(response, Azure::Armrest::ResourceGroup)
       end
 
       # Creates a new +group+ in +location+ for the current subscription.

data/lib/azure/armrest/resource_service.rb

@@ -23,7 +23,7 @@ module Azure
       def list(resource_group, options = {})
         url = build_url(resource_group, options)
         response = rest_get(url)
-        JSON.parse(response)['value'].map { |hash| Azure::Armrest::Resource.new(hash) }
+        Azure::Armrest::ArmrestCollection.create_from_response(response, Azure::Armrest::Resource)
       end
 
       # Same as Azure::Armrest::ResourceService#list but returns all resources
@@ -32,7 +32,7 @@ module Azure
       def list_all(options = {})
         url = build_url(nil, options)
         response = rest_get(url)
-        JSON.parse(response)['value'].map { |hash| Azure::Armrest::Resource.new(hash) }
+        Azure::Armrest::ArmrestCollection.create_from_response(response, Azure::Armrest::Resource)
       end
 
       # Move the resources from +source_group+ under +source_subscription+,

data/lib/azure/armrest/version.rb

@@ -1,5 +1,5 @@
 module Azure
   module Armrest
-    VERSION = '0.3.5'.freeze
+    VERSION = '0.3.6'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: azure-armrest
 version: !ruby/object:Gem::Version
-  version: 0.3.5
+  version: 0.3.6
 platform: ruby
 authors:
 - Daniel J. Berger
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-08-11 00:00:00.000000000 Z
+date: 2016-09-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json