ravello-sdk 0.9 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8e22bc14b505f0312ca1ec12dab8dc3ccaaebfce
-  data.tar.gz: 4f0a9072a6547b515dc3afb55e1c2e7b19b02cf8
+  metadata.gz: 8a0e3fca67a534a87c88d788893a19010bb7d943
+  data.tar.gz: 1d3af88858452d9b64380a7be31ec77e72000fed
 SHA512:
-  metadata.gz: e4f35dbecf51404a26d46851e67ec46a417940aeca29d6143ea6d2dc4900b74f89959c460e3d80bd5531f761603c58cbd4128fa56bc9581543d14dae62413b6d
-  data.tar.gz: 55c6a7da642fe7d0f70136e28285e82d55cb7eea6073563ef43a6fce74ef4ad60b661c5b3d8156e57c8a2f75ac0d3e6448738ecf16226ea7dbf599d12b887573
+  metadata.gz: 5d40f979fe440eeaf9875c4bf109de76c11be8fa96a5bfe7d2d9d77e1480b0a3c146b01a551ac7fc49803476904712b04aef8f0d4950c48eea51ec5f9a8b79d5
+  data.tar.gz: 74331233fbfa7d3863c6029a461e992ee7a3924f0a47b29b8269745f52e2d5f7b202cec65881ee413ece5ee84d12b82a7cf86cba5b136ebaf67e9617d0441367

data/lib/ravello-sdk.rb

@@ -7,10 +7,13 @@ require "net/http"
 
 class Net::HTTPResponse
 
+  # The parsed entity, if any.
   def entity
     @entity if defined? @entity
   end
 
+  # Set the parsed entity.
+  # @private
   def entity=(value)
     @entity = value
   end
@@ -19,18 +22,22 @@ end
 
 module Ravello
 
+  # The default service endpoint used by the Client.
   DEFAULT_URL = "https://cloud.ravellosystems.com/services"
 
-  @@prng = Random.new
-
+  # Return a deep copy of an object.
+  # @param o [Hash] The object to copy.
+  # @return [Hash] A deep copy of the object.
   def deep_copy(o)
     Marshal.load(Marshal.dump(o))
   end
 
+  # Generate a new random local ID.
   def random_luid
     @@prng.rand 1<<63
   end
 
+  # Like #update_luids, but replaces ID attributes in place.
   def update_luids!(o)
     if o.is_a? Hash
       o.each_pair do |key,value|
@@ -42,10 +49,21 @@ module Ravello
     o
   end
 
+  # Recursively replace all attributes called "id" in the supplied hash with a
+  # new random ID. This is useful when adding a VM or other object to an
+  # application's design. All objects in a design require a unique ID. The term
+  # "luid" means "local id".
+  #
+  # @param o [Hash] The object to 
+  # return [Hash] A copy of the object with new id attributes.
   def update_luids(o)
     update_luids!(deep_copy o)
   end
 
+  # Return the consolidated state of an application.
+  # @return [String, Array<String>, nil] A single string if all VMs in the
+  #   deployment are in the same state, or a list of strings if there are
+  #   multiple states. In case there are no VMs in the deployment, return nil.
   def application_state(app)
     if !app.is_a? Hash
       raise ArgumentError, "expecting a Hash, got #{app}"
@@ -60,16 +78,65 @@ module Ravello
 
   module_function :deep_copy, :random_luid, :update_luids, :update_luids!
 
+  # A client for the Ravello API. The client is a thin layer on top of the
+  # RESTful API. The client manages a single HTTPS connection, and implements
+  # login and retry functionality.
+  #
+  # Some general comments on how the RESTful API is mapped:
+  #
+  # * The calls are named "<verb>_<noun>", for example, "get_keypair".
+  # * There is no client-side object model. The return value from any API call
+  #   is simply the parsed JSON response.
+  # * Resources are returned as a Hash, containing the key/value pairs of
+  #   the resource. It is common that resources contain nested hashes.
+  # * Lists of resources are returned as an Array of zero or more hashes. It is
+  #   common that resources in an Array only contain a subset of all available
+  #   attributes.
+  # * Resources are identifed by a numeric ID.
+  # * Methods that retrieve a single resource take this ID parameter as a
+  #   parameter. As a special case, it is also allowed to pass in a hash with
+  #   an "id" key. These methods return a Hash, or nil if the resource was not
+  #   found.
+  # * Methods that retrieve multiple resources can be passed a filter. The
+  #   filter consists of hash style arguments. Only resources that have the
+  #   specified key/value pairs will included in the response.
+  # * Methods that create a resource return a represenation of the created
+  #   resources. It is common that this represenation contains (a lot) more
+  #   attributes than you passed in. The extra attributes are defaults filled
+  #   in by the system.
+  # * API errors are HTTP response codes in the 4xx or 5xx range. All API
+  #   errors are turned into exceptions, except for the 404 (Not Found) code
+  #   for a "get" call. In this case, nil is returned.
+  # * In case a certain API call is not yet mapped as a method, a fallback
+  #   #request method is available that allows you to invoke arbitrary
+  #   requests.
+
   class Client
 
-    attr_accessor :retries, :timeout
-    attr_reader :url, :user_info
+    # The default network timeout.
+    attr_accessor :timeout
 
+    # The number of times to retry an API call before giving up. Only
+    # idempotent API calls are retried.
+    attr_accessor :retries
+
+    # The parsed URL used in the current connection.
+    attr_reader :url
+    
+    # A hash containing user information. Available when the client is logged
+    # in.
+    attr_reader :user_info
+
+    # Create a new API client. The following options are supported:
+    # @param :username [String] The API user name.
+    # @param :password [String] The API password.
+    # @param :timeout [Integer] The network timeout.
+    # @param :retries [Integer] Times to retry a failed operation.
     def initialize(options={})
       @username = options[:username]
       @password = options[:password]
-      @retries = options.fetch(:retries, 3)
       @timeout = options.fetch(:timeout, 60)
+      @retries = options.fetch(:retries, 3)
       @logger = Logger.new(STDERR)
       @logger.level = if $DEBUG then Logger::DEBUG \
                         elsif $VERBOSE then Logger::INFO else Logger::WARN end
@@ -81,27 +148,29 @@ module Ravello
       set_url(options.fetch(:url, DEFAULT_URL))
     end
 
+    # @return [Boolean] Whether the client is connected.
     def connected?
       !@connection.nil?
     end
 
-    def closed?
-      @connection.nil?
-    end
-
+    # @return [Boolean] Whether the client is logged in.
     def logged_in?
       !@cookies.nil?
     end
 
-    def url=(url)
-      set_url(url)
-    end
-
+    # Connect to the API.
+    # @param url [String] The URL to connect to. If not provided, use the
+    #   default service end point.
     def connect(url=nil)
       url = url unless url.nil?
       do_connect
     end
 
+    # Authenticate to the API. Authentication is required for most operations.
+    # @param username The API username. If not provided, use the username
+    #   specified in the constructor.
+    # @param password The API password If not provided, use the password
+    #   specified in the constructor.
     def login(username=nil, password=nil)
       raise "already logged in" if logged_in?
       @username = username unless username.nil?
@@ -110,22 +179,37 @@ module Ravello
       do_login
     end
 
+    # Logout. The connection is maintained.
     def logout
       do_logout if logged_in?
     end
 
+    # Close the connection to the API.
     def close
       @connection.finish if !@connection.nil?
       @connection = nil
       @cookies = nil
     end
 
+    # Issue a call to the API. This is a low-level method that you should only
+    # use in case the call you want is not mapped as a method.
+    # @param method [Symbol] The HTTP method, e.g. :GET or :POST.
+    # @param path [String] The path relative to the API root.
+    # @param entity [Hash] A JSON serializable hash that is specific to
+    #   the method and path.
+    # @return [Hash,Array<Hash>] The parsed JSON response.
     def request(method, path, entity=nil)
       body = JSON.generate(entity) unless entity.nil?
       response = make_request(method, path, body)
       response.entity
     end
 
+    # Wait until a condition on the object evaluates to true.
+    # @param obj [Hash] The object to wait for. It must be a hash returned by
+    #   this client that has a "href" attribute.
+    # @param timeout [Numeric] The number of seconds to wait.
+    # @param block [Block] A block that evaluates the condition. The block must
+    #   return true if the condition holds, false otherwise.
     def wait_for(obj, timeout, &block)
       end_time = Time.now + timeout
       raise 'object requires a "href" key' if !obj.key? 'href'
@@ -137,142 +221,259 @@ module Ravello
       raise 'timeout' if end_time < Time.now
     end
 
+    # Get an application by its ID.
+    # @param id [Integer, Hash] The numeric ID of the application. This may
+    #   also be a hash, in which case it must have a numeric "id" key.
+    # @return [Hash, nil] The application, or nil if the application does not
+    #   exist.
     def get_application(id)
       if id.is_a? Hash then id = id['id'] end
       request(:GET, "/applications/#{id}")
     end
 
+    # Get a list of all applications.
+    # @param filter [Hash] A hash containing key/value pairs the application
+    #   must have.
+    # @return [Array<Hash>] A list of applications.
     def get_applications(filter={})
       result = request(:GET, '/applications')
       result.select! do |app| match_filter(app, filter) end if !filter.empty?
       result
     end
 
+    # Create a new application.
+    # @param app [Hash] The application.
+    # @return [Hash] The application that was created.
     def create_application(app)
       request(:POST, '/applications', app)
     end
 
+    # Update an existing application
+    # @param app [Hash] The application to update.
+    # @return [Hash] The updated application.
     def update_application(app)
       request(:PUT, "/applications/#{app['id']}", app)
     end
 
+    # Delete an application
+    # @param id [Numeric,Hash] The ID of the application. This parameter may
+    #   also be a Hash with a numeric "id" key.
+    # @return nil
     def delete_application(id)
       if id.is_a? Hash then id = id['id'] end
       request(:DELETE, "/applications/#{id}")
     end
 
+    # Publish an application
+    # @param id [Numeric, Hash] The ID of the application to publish. This
+    #   parameter may also be a Hash with a numeric "id" key.
+    # @param req [Hash] The publish request.
+    # @return [Hash] The publish response.
     def publish_application(id, req={})
       if id.is_a? Hash then id = id['id'] end
       request(:POST, "/applications/#{id}/publish", req)
     end
 
+    # Start an application.
+    # @param id [Numeric, Hash] The ID of the application to start. This
+    #   parameter may also be a Hash with a numeric "id" key.
+    # @return [Hash] The start response.
     def start_application(id)
       if id.is_a? Hash then id = id['id'] end
       request(:POST, "/applications/#{id}/start")
     end
 
+    # Stop an application.
+    # @param id [Numeric, Hash] The ID of the application to stop. This
+    #   parameter may also be a Hash with a numeric "id" key.
+    # @return [Hash] The stop response.
     def stop_application(id)
       if id.is_a? Hash then id = id['id'] end
       request(:POST, "/applications/#{id}/stop")
     end
 
+    # Restart an application.
+    # @param id [Numeric, Hash] The ID of the application to restart. This
+    #   parameter may also be a Hash with a numeric "id" key.
+    # @return [Hash] The restart response.
     def restart_application(id)
       if id.is_a? Hash then id = id['id'] end
       request(:POST, "/applications/#{id}/restart")
     end
 
+    # Publish application updates.
+    # @param id [Numeric, Hash] The ID of the application to publish updates
+    #   for. This  parameter may also be a Hash with a numeric "id" key.
+    # @return [Hash] The publish updates response.
     def publish_application_updates(id)
       if id.is_a? Hash then id = id['id'] end
       request(:POST, "/applications/#{id}/publishUpdates")
     end
 
+    # Set the application expiration time.
+    # @param id [Numeric, Hash] The ID of the application to set the
+    #   expiration time of. This parameter may also be a Hash with a numeric
+    #   "id" key.
+    # @param req [Hash] The set expiration time request.
+    # @return [Hash] The set expiration time response.
     def set_application_expiration(id, req)
       if id.is_a? Hash then id = id['id'] end
       request(:POST, "/applications/#{id}/setExpiration", req)
     end
 
+    # Start a virtual machine
+    # @param appid [Numeric, Hash] The ID of the application that contains the
+    #   VM. This parameter may also be a Hash with an "id" key.
+    # @param vmid [Numeric, Hash] The ID of the VM to start. This parameter
+    #   may also be a Hash with an "id" key.
+    # @return [Hash] The start VM response.
     def start_vm(appid, vmid)
       if appid.is_a? Hash then appid = appid['id'] end
       if vmid.is_a? Hash then vmid = vmid['id'] end
       request(:POST, "/applications/#{appid}/vms/#{vmid}/start")
     end
 
+    # Stop a virtual machine
+    # @param appid [Numeric, Hash] The ID of the application that contains the
+    #   VM. This parameter may also be a Hash with an "id" key.
+    # @param vmid [Numeric, Hash] The ID of the VM to stop. This parameter
+    #   may also be a Hash with an "id" key.
+    # @return [Hash] The stop VM response.
     def stop_vm(appid, vmid)
       if appid.is_a? Hash then appid = appid['id'] end
       if vmid.is_a? Hash then vmid = vmid['id'] end
       request(:POST, "/applications/#{appid}/vms/#{vmid}/stop")
     end
 
+    # Restart a virtual machine
+    # @param appid [Numeric, Hash] The ID of the application that contains the
+    #   VM. This parameter may also be a Hash with an "id" key.
+    # @param vmid [Numeric, Hash] The ID of the VM to restart. This parameter
+    #   may also be a Hash with an "id" key.
+    # @return [Hash] The restart VM response.
     def restart_vm(appid, vmid)
       if appid.is_a? Hash then appid = appid['id'] end
       if vmid.is_a? Hash then vmid = vmid['id'] end
       request(:POST, "/applications/#{appid}/vms/#{vmid}/restart")
     end
 
+    # Get a blueprint.
+    # @param id [Integer, Hash] The ID of the blueprint. This may also be a
+    #   Hash, in which case it must have an "id" key.
+    # @return [Hash, nil] The blueprint as a Hash, or nil in case the blueprint
+    #   does not exist.
     def get_blueprint(id)
       if id.is_a? Hash then id = id['id'] end
       request(:GET, "/blueprints/#{id}")
     end
 
+    # Get a list of all blueprints.
+    # @param filter [Hash] An optional filter. Only blueprints that have 
+    #   key/value pairs as specified in the filter will be returned.
+    # @return [Array<Hash>] A list of blueprints.
     def get_blueprints(filter={})
       result = request(:GET, '/blueprints')
       result.select! do |bp| match_filter(bp, filter) end if !filter.empty?
       result
     end
 
+    # Create a new blueprint.
+    # @param req [Hash] The blueprint creation request.
+    # @return [Hash] The blueprint that was created.
     def create_blueprint(req)
       request(:POST, '/blueprints', req)
     end
 
+    # Delete a blueprint.
+    # @param id [Integer, Hash] The ID of the blueprint to delete. This
+    #   parameter may also be a Hash, in which case it must have an "id" key.
+    # @return nil
     def delete_blueprint(id)
       if id.is_a? Hash then id = id['id'] end
       request(:DELETE, "/blueprints/#{id}")
     end
     
+    # Get an image.
+    # @param id [Integer, Hash] The ID of the image. This may also be a
+    #   Hash, in which case it must have an "id" key.
+    # @return [Hash, nil] The image as a Hash, or nil in case the image
+    #   does not exist.
     def get_image(id)
       if id.is_a? Hash then id = id['id'] end
       request(:GET, "/images/#{id}")
     end
 
+    # Get a list of all images.
+    # @param filter [Hash] An optional filter. Only images that have 
+    #   key/value pairs as specified in the filter will be returned.
+    # @return [Array<Hash>] A list of images.
     def get_images(filter={})
       result = request(:GET, '/images')
       result.select! do |img| match_filter(img, filter) end if !filter.empty?
       result
     end
 
+    # Update an image.
+    # @param image [Hash] The image to update.
+    # @return [Hash] The updated image.
     def update_image(image)
       request(:PUT, "/images/#{image['id']}", image)
     end
 
+    # Delete an image.
+    # @param id [Numeric, Hash] The Id of the image to delete. This may also be
+    #   a Hash, in which case it must have an "id" key.
+    # @return nil
     def delete_image(id)
       if id.is_a? Hash then id = id['id'] end
       request(:DELETE, "/images/#{id}")
     end
 
+    # Get a keypair.
+    # @param id [Integer, Hash] The ID of the keypair. This parameter may also
+    #   be a Hash, in which case it must have an "id" key.
+    # @return [Hash, nil] The keypair as a Hash, or nil in case the keypair
+    #   does not exist.
     def get_keypair(id)
       if id.is_a? Hash then id = id['id'] end
       request(:GET, "/keypairs/#{id}")
     end
 
+    # Get a list of all keypairs.
+    # @param filter [Hash] An optional filter. Only keypairs that have 
+    #   key/value pairs as specified in the filter will be returned.
+    # @return [Array<Hash>] A list of keypairs.
     def get_keypairs(filter={})
       result = request(:GET, '/keypairs')
       result.select! do |kp| match_filter(kp, filter) end if !filter.empty?
       result
     end
 
+    # Create a new keypair.
+    # @param keypair [Hash] The keypair to created.
+    # @return [Hash] The keypair that was created.
     def create_keypair(keypair)
       request(:POST, '/keypairs', keypair)
     end
 
+    # Update a keypair.
+    # @param keypair [Hash] The keypair to update.
+    # @return [Hash] The updated keypair.
     def update_keypair(keypair)
       request(:PUT, "/keypairs/#{keypair['id']}", keypair)
     end
 
+    # Delete a keypair.
+    # @param id The ID of the keypair to delete. This parameter may also be a
+    #   Hash, in which case it must have an "id" key.
+    # @return nil
     def delete_keypair(id)
       if id.is_a? Hash then id = id['id'] end
       request(:DELETE, "/keypairs/#{id}")
     end
 
+    # Generate a new keyapair.
+    # @return [Hash] The newly generated keypair.
     def generate_keypair
       request(:POST, '/keypairs/generate')
     end
@@ -284,7 +485,7 @@ module Ravello
   private
 
     def set_url(url)
-      raise 'cannot change URL when connected' if !closed?
+      raise 'cannot change URL when connected' if connected?
       parsed = URI.parse(url.chomp '/')
       raise ArgumentError, 'https is required' if parsed.scheme != "https"
       @url = parsed
@@ -409,19 +610,23 @@ module Ravello
       response
     end
 
-  def match_filter(obj, filter)
-    filter.each_pair do |fkey,fvalue|
-      obval = obj[fkey.to_s]
-      if obval.nil?
-        return false
-      elsif fvalue.is_a? Hash
-        return false if !obval.is_a? Hash || !match_filter(obval, fvalue)
-      elsif fvalue != obval
-        return false
+    def match_filter(obj, filter)
+      filter.each_pair do |fkey,fvalue|
+        obval = obj[fkey.to_s]
+        if obval.nil?
+          return false
+        elsif fvalue.is_a? Hash
+          return false if !obval.is_a? Hash || !match_filter(obval, fvalue)
+        elsif fvalue != obval
+          return false
+        end
       end
+      true
     end
-    true
   end
 
-  end
+  private
+
+  @@prng = Random.new
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ravello-sdk
 version: !ruby/object:Gem::Version
-  version: '0.9'
+  version: 0.9.1
 platform: ruby
 authors:
 - Geert Jansen
@@ -42,3 +42,4 @@ signing_key:
 specification_version: 4
 summary: A Ruby SDK for the Ravello Systems API
 test_files: []
+has_rdoc: