rest_connection 1.0.1 → 1.0.2

data/README.rdoc.starting.point

@@ -0,0 +1,202 @@
+= Rest Connection
+
+The rest_connection gem simplifies the use of RightScale's MultiCloud API. It provides
+a simple object model of the API resources, and handles all of the fine details involved
+in making HTTP calls and translating their responses.
+It is assumed that users are already familiar with the RightScale API:
+- API Documentation: http://support.rightscale.com/12-Guides/RightScale_API_1.5
+- API Reference Docs: http://support.rightscale.com/api1.5
+
+== Installation
+Ruby 1.8.7 or higher is required.
+    gem install rest_connection
+
+== Versioning
+The rest_connection gem is versioned using the usual X.Y.Z notation, where X.Y is the
+RightScale API version, and Z is the client version. For example, if you want to use
+RightScale API 1.5, you should use the latest version of the 1.5 gem. This will ensure
+that you get the latest bug fixes for the client that is compatible with that API version.
+
+== Usage Instructions
+New users can start with the following few lines of code and navigate their way around the API by following
+the available methods. You can find your account id by logging into the RightScale dashboard (https://my.rightscale.com),
+navigate to the Settings > Account Settings page. The account is is at the end of the browser address bar.
+    require 'rest_connection'
+    @client = RightApi::Client.new(:email => 'my@email.com', :password => 'my_password', :account_id => 'my_account_id')
+    puts "Available methods: #{@client.api_methods}"
+
+The client makes working with and getting to know the API much easier. It spiders the API dynamically to
+discover its resources on the fly. At every step, the user has the ability to query api_methods(), which
+indicates the potential methods that can be called. The <tt>config/login.yml.example</tt> file provides
+details of different login parameters.
+
+=== Making API calls
+Essentially, just follow the RightScale API documentation (available from http://support.rightscale.com)
+and treat every resource in the paths as objects that can call other objects using the dot (.) operator:
+
+Examples:
+   - Index:     /api/clouds/:cloud_id/datacenters             =>  @client.clouds(:id => :cloud_id).show.datacenters.index
+   - Show:      /api/clouds/:cloud_id/datacenters/:id         =>  @client.clouds(:id => :cloud_id).show.datacenters(:id => :datacenter_id).show
+   - Create:    /api/deployments/:deployment_id/servers       =>  @client.deployments(:id => :deployment_id).show.servers.create
+   - Update:    /api/deployments/:deployment_id/servers/:id   =>  @client.deployments(:id => :deployment_id).show.servers(:id => :server_id).update
+   - Destroy:   /api/deployments/:deployment_id/servers/:id   =>  @client.deployments(:id => :deployment_id).show.servers(:id => :server_id).destroy
+   - An action: /api/servers/:server_id/launch                =>  @client.servers(:id => :server_id).show.launch
+
+As seen above, whenever you need to chain methods, you must call .show before specifying the next method.
+
+=== Parameters
+Pass-in parameters to the method that they belong to. Lets say you want to filter on the index for deployments:
+    @client.deployments.index(:filter => ['name==my_deployment'])
+The filter is the parameter for the index call and not the deployment call.
+
+=== Logging HTTP Requests
+The HTTP calls made by rest_connection can be logged in two ways:
+1. Log to a file
+    @client.log('~/rest_connection.log')
+2. Log to SDTOUT
+    @client.log(STDOUT)
+
+== Examples
+Get a list of all servers (aka doing an Index call)
+    @client.servers.index
+
+Get a list of all servers in a deployment
+    @client.deployments(:id => 'my_deployment_id').show.servers.index
+
+Get a particular server (aka doing a Show call)
+    @client.servers(:id => 'my_server_id').show
+
+Creating a server involves setting up the required parameters, then calling the create method
+    server_template_href = @client.server_templates.index(:filter => ['name==Base ServerTemplate']).first.href
+    cloud = @client.clouds(:id => 'my_cloud_id').show
+    params = { :server => {
+        :name => 'Test Server',
+        :deployment_href => @client.deployments(:id => 'my_deployment_id').show.href,
+        :instance => {
+            :server_template_href => server_template_href,
+            :cloud_href           => cloud.href,
+            :security_group_hrefs => [cloud.security_groups.index(:filter => ['name==default']).first.href],
+            :ssh_key_href         => cloud.ssh_keys.index.first.href,
+            :datacenter_href      => cloud.datacenters.index.first.href
+        }}}
+    new_server = @client.servers.create(params)
+    new_server.api_methods
+
+Launch the newly created server. Inputs are a bit tricky so they have to be set in a long string
+    inputs = "inputs[][name]=NAME1&inputs[][value]=text:VALUE1&inputs[][name]=NAME2&inputs[][value]=text:VALUE2"
+    new_server.show.launch(inputs)
+
+Run a script on the server. The API does not currently expose right_scripts, hence, the script href has
+to be retrieved from the dashboard and put in the following href format.
+    script_href = "right_script_href=/api/right_scripts/382371"
+    task = new_server.show.current_instance.show.run_executable(script_href + "&inputs[][name]=TEST_NAME&inputs[][value]=text:VALUE1")
+    task.show.api_methods
+
+Update the server's name
+    params = { :server => {:name => 'New Server Name'}}
+    @client.servers(:id => 'my_server_id').update(params)
+
+Terminate the server (i.e. shutdown its current_instance)
+    @client.servers(:id => 'my_server_id').show.terminate
+
+Destroy the server (i.e. delete it)
+    @client.servers(:id => 'my_server_id').destroy
+
+== Object Types
+The client returns 3 types of objects:
+- <b>Resources</b>: returned when you are querying a collection of resources, e.g.: <tt>client.deployments</tt>
+- <b>Resource</b>: returned when you specify an id and therefore a specific resource, e.g.: <tt>@client.deployments(:id => :deployment_id)</tt>
+  - When the content-type is type=collection then an array of Resource objects will be returned, e.g.: <tt>@client.deployments.index</tt>
+  - When the content-type is not a collection then a Resource object will be returned, e.g.: <tt>@client.deployments(:id => deployment_id).show</tt>
+- <b>ResourceDetail</b>: returned when you do a .show on a Resource, e.g.: <tt>client.deployments(:id => deployment_id).show</tt>
+<b>On all 3 types of objects you can query <tt>.api_methods</tt> to see a list of available methods, e.g.: <tt>client.deployments.api_methods</tt></b>
+
+=== Exceptions:
+- <tt>inputs.index</tt> will return an array of ResourceDetail objects since you cannot do a .show on an input
+- <tt>session.index</tt> will return a ResourceDetail object since you cannot do a .show on a session
+- <tt>tags.by_resource, tags.by_tag</tt> will return an array of ResourceDetail objects since you cannot do a .show on a resource_tag
+- <tt>monitoring_metrics(:id => :m_m_id).show.data</tt> will return a ResourceDetail object since you cannot do
+  a .show on a monitoring_metric_data
+
+== Instance Facing Calls:
+The client also supports 'instance facing calls', which use the instance_token to login.
+Unlike regular email-password logins, instance-facing-calls are limited in the amount of allowable calls.
+Since in most of the cases, the calls are scoped to the instance's cloud (or the instance itself), the cloud_id and
+the instance_id will be automatically recorded by the client, so that the user does not need to specify it.
+
+=== Examples
+    @instance_client = RightApi::Client.new(:instance_token => 'my_token', :account_id => 'my_account_id')
+    @instance_client.volume_attachments     links to /api/clouds/:cloud_id/volume_attachments
+    @instance_client.volumes_snapshots      links to /api/clouds/:cloud_id/volumes_snapshots
+    @instance_client.volumes_types          links to /api/clouds/:cloud_id/volumes_types
+    @instance_client.volumes                links to /api/clouds/:cloud_id/volumes
+    @instance_client.backups                links to /api/backups
+    @instance_client.live_tasks(:id)        links to /api/clouds/:cloud_id/instances/:instance_id/live/tasks/:id
+
+=== Notes
+For volume_attachments and volumes_snapshots you can also go through the volume:
+    @instance_client.volumes(:id => :volume_id).show.volume_attachments
+    which maps to:
+    /api/clouds/:cloud_id/volumes/:volume_id/volume_attachment
+The instance's volume_attachments can be accessed using:
+    @instance_client.get_instance.volume_attachments
+    which maps to:
+    /api/clouds/:cloud_id/instances/:instance_id/volume_attachments
+
+Because the cloud_id and the instance_id are automatically added by the client, scripts that work for regular
+email-password logins will have to be modified for instance-facing calls. The main reason behind this is the
+inability for instance-facing calls to access the clouds resource (i.e.: <tt>@instance_client.clouds(:id=> :cloud_id).show</tt> will fail)
+
+When you query <tt>api_methods</tt>, it will list all of the methods that one sees with regular email-password logins.
+Due to the limiting scope of the instance-facing calls, only a subset of these methods can be called
+(see the API Reference Docs for valid methods). If you call a method that instance's are not authorized to access,
+you will get a 403 Permission Denied error.
+
+
+= Design Decisions
+In the code, we only hard-code CRUD operations for resources. We use the .show and .index methods to make the client
+more efficient. Since it dynamically creates methods it needs to query the API at times. The .show and the .index make
+it explicit that querying needs to take place. Without them a GET would have to be queried every step of the way
+(i.e.: the index call would be client.deployments, and the create call would be client.deployments.create which would
+first do an index call).
+
+<b>In general, when a new API resource is added, you need to indicate in the client whether index, show, create, update
+and delete methods are allowed for that resource.</b>
+
+== Special Cases
+=== Returning resource_types that are not actual API resources:
+  - tags:
+    - by_resource, by_tag: both return a COLLECTION of resource_type = RESOURCE_TAG
+      - no show or index is defined for that resource_type, therefore return a collection of ResourceDetail objects
+  - data:
+    - querying .data for monitoring_metrics:
+      - no show is defined for that resource_type, therefore return a ResourceDetail object
+
+=== Index call does not act like an index call
+  - session:
+    - session.index should act like a show call and not like an index call (since you cannot query show).
+      Therefore it should return a ResourceDetail object
+  - inputs
+    - inputs.index cannot return a collection of Resource objects since .show is not allowed. Therefore it should
+      return a collection of ResourceDetail objects
+
+=== Having a resource_type that cannot be accurately determined from the URL:
+  - In server_arrays.show: resource_type = current_instance(s) (although it should be instance(s))
+  - In multi_cloud_images.show: resource_type = setting(s) (although it should be multi_cloud_image_setting)
+Put these special cases in the <tt>RightApi::Helper::INCONSISTENT_RESOURCE_TYPES</tt> hash.
+
+=== Method defined on the generic resource_type itself
+  - 'instances' => {:multi_terminate => 'do_post', :multi_run_executable => 'do_post'},
+  - 'inputs'    => {:multi_update => 'do_put'},
+  - 'tags'      => {:by_tag => 'do_post', :by_resource => 'do_post', :multi_add => 'do_post', :multi_delete =>'do_post'},
+  - 'backups'   => {:cleanup => 'do_post'}
+Put these special cases in the <tt>RightApi::Helper::RESOURCE_TYPE_SPECIAL_ACTIONS</tt> hash.
+
+=== Resources are not linked together
+  - In ResourceDetail, resource_type = Instance, need live_tasks as a method.
+
+= Troubleshooting
+
+== Wrong ruby version
+
+Ruby 1.8.7 or higher is required.

data/VERSION

@@ -1 +1 @@
-1.0.1
+1.0.2

data/lib/rest_connection/rightscale/mc_server.rb

@@ -60,32 +60,32 @@ class McServer < Server
       begin
         connection.post(t.path + '/launch')
       rescue Exception => e
-        puts "************* McServer.launch(): Caught exception #{e.inspect}"
-        puts "************* McServer.launch(): connection.settings[:azure_hack_on] = #{connection.settings[:azure_hack_on]}"
-        puts "************* McServer.launch(): connection.settings[:azure_hack_retry_count] = #{connection.settings[:azure_hack_retry_count]}"
-        puts "************* McServer.launch(): connection.settings[:azure_hack_sleep_seconds] = #{connection.settings[:azure_hack_sleep_seconds]}"
-        # THIS IS A TEMPORARY HACK TO GET AROUND AZURE SERVER LAUNCH PROBLEMS AND SHOULD BE REMOVED ONCE MICROSOFT
-        # FIXES THIS BUG ON THEIR END!
-
-        # Retry on 422 conflict exception (ONLY MS AZURE WILL GENERATE THIS EXCEPTION)
-        target_422_conflict_error_message = "Invalid response HTTP code: 422: CloudException: ConflictError:"
-        target_504_gateway_timeout_error_message = "504 Gateway Time-out"
-        if e.message =~ /#{target_504_gateway_timeout_error_message}/
-          exception_matched_message = "McServer.launch(): Caught #{e.message}, treating as a successful launch..."
-          puts(exception_matched_message)
-          connection.logger(exception_matched_message)
-          true
-        elsif e.message =~ /#{target_422_conflict_error_message}/
-          if connection.settings[:azure_hack_on]
+        if connection.settings[:azure_hack_on]
+          puts "**** [AZURE_HACK is ON] - McServer.launch() nickname: #{nickname}, caught exception #{e.message}"
+          puts "**** connection.settings[:azure_hack_retry_count] = #{connection.settings[:azure_hack_retry_count]}"
+          puts "**** connection.settings[:azure_hack_sleep_seconds] = #{connection.settings[:azure_hack_sleep_seconds]}"
+
+          # 504 Gateway should always be treated as a successful launch
+          target_504_gateway_timeout_error_message = "504 Gateway Time-out"
+
+          # All 422 exceptions should be retried
+          target_422_error_message = "Invalid response HTTP code: 422:"
+
+          if e.message =~ /#{target_504_gateway_timeout_error_message}/
+            exception_matched_message = "**** McServer.launch(): Caught #{e.message}, treating as a successful launch..."
+            puts(exception_matched_message)
+            connection.logger(exception_matched_message)
+            true
+          elsif e.message =~ /#{target_422_error_message}/
             azure_hack_retry_count = connection.settings[:azure_hack_retry_count]
-            exception_matched_message = "************* McServer.launch(): Matched Azure exception: \"#{target_422_conflict_error_message}\""
+            exception_matched_message = "**** McServer.launch(): Caught #{e.message}, retrying launch..."
             puts(exception_matched_message)
             connection.logger(exception_matched_message)
 
             retry_count = 1
             loop do
               # sleep for azure_hack_sleep_seconds seconds
-              sleep_message = "************* McServer.launch(): Sleeping for #{connection.settings[:azure_hack_sleep_seconds]} seconds and then retrying (#{retry_count}) launch..."
+              sleep_message = "**** McServer.launch(): Sleeping for #{connection.settings[:azure_hack_sleep_seconds]} seconds and then retrying (#{retry_count}) launch..."
               puts(sleep_message)
               connection.logger(sleep_message)
               sleep(connection.settings[:azure_hack_sleep_seconds])
@@ -94,23 +94,37 @@ class McServer < Server
               begin
                 connection.post(t.path + '/launch')
               rescue Exception => e2
-                if e2.message =~ /#{target_422_conflict_error_message}/
+                exception_caught_message = "**** McServer.launch(): Retry caught #{e2.message}..."
+                puts(exception_caught_message)
+                connection.logger(exception_caught_message)
+
+                if e2.message =~ /#{target_422_error_message}/
                   azure_hack_retry_count -= 1
                   if azure_hack_retry_count > 0
                     retry_count += 1
+
+                    # Try again on next iteration
                     next
                   else
+                    # Azure Hack maximum retries exceeded so rethrow the new 422 exception
                     raise
                   end
                 else
+                  # On this re-launch we got some other exception so rethrow it
                   raise
                 end
               end
+
+              # Fell through so launch worked and we need to break out of the retry do loop
               break
             end
           else
+            # Didn't match on any target exception so rethrow the original exception
             raise
           end
+        else
+          # Azure Hack isn't enabled so rethrow the original exception
+          raise
         end
       end
     elsif self.state == "inactive"

data/lib/rest_connection/rightscale/server.rb

@@ -97,7 +97,7 @@ class Server
     reload
     connection.logger("#{nickname} is #{self.state}")
     step = 15
-    catch_early_terminated = 60 / step
+    catch_early_terminated = 1200 / step
     while(timeout > 0)
       return true if state =~ /#{st}/
       return true if state =~ /terminated|stopped/ && st =~ /terminated|stopped/
@@ -106,7 +106,7 @@ class Server
       connection.logger("waiting for server #{nickname} to go #{st}, state is #{state}")
       if state =~ /terminated|stopped|inactive|error/ and st !~ /terminated|stopped|inactive|error/
         if catch_early_terminated <= 0
-          raise "FATAL error, this server terminated when waiting for #{st}: #{nickname}"
+          raise "FATAL error, this server entered #{state} state waiting for #{st}: #{nickname}"
         end
         catch_early_terminated -= 1
       end

data/login_to_connection_irb.rb

@@ -0,0 +1,22 @@
+# A quick way to login to the API and jump into IRB so you can experiment with the connection.
+# Add this to your bash profile to make it simpler:
+#   alias connection='bundle exec ruby login_to_connection_irb.rb'
+
+require File.expand_path('../lib/rest_connection', __FILE__)
+require 'yaml'
+require 'irb'
+
+begin
+  @connection = RestConnection::Connection.new()
+  puts "logged-in to the API, use the '@connection' variable to use the connection"
+end
+
+IRB.start
+
+#
+#require 'rubygems'
+#require 'rest_connection'
+#require 'ruby-debug'
+#
+#debugger
+#puts "done!"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: rest_connection
 version: !ruby/object:Gem::Version 
-  hash: 21
-  prerelease: 
+  hash: 19
+  prerelease: false
   segments: 
   - 1
   - 0
-  - 1
-  version: 1.0.1
+  - 2
+  version: 1.0.2
 platform: ruby
 authors: 
 - Jeremy Deininger
@@ -16,7 +16,8 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-11-20 00:00:00 Z
+date: 2012-11-29 00:00:00 -08:00
+default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: activesupport
@@ -116,6 +117,7 @@ extensions: []
 extra_rdoc_files: 
 - LICENSE
 - README.rdoc
+- README.rdoc.starting.point
 files: 
 - LICENSE
 - README.rdoc
@@ -208,6 +210,7 @@ files:
 - lib/rest_connection/rightscale/vpc_dhcp_option.rb
 - lib/rest_connection/ssh_hax.rb
 - log_api_call_parser
+- login_to_connection_irb.rb
 - spec/ec2_server_array_spec.rb
 - spec/ec2_ssh_key_internal_spec.rb
 - spec/image_jockey.rb
@@ -222,6 +225,8 @@ files:
 - spec/server_template_internal.rb
 - spec/spec_helper.rb
 - spec/tag_spec.rb
+- README.rdoc.starting.point
+has_rdoc: true
 homepage: http://github.com/rightscale/rest_connection
 licenses: []
 
@@ -251,7 +256,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.8.15
+rubygems_version: 1.3.7
 signing_key: 
 specification_version: 3
 summary: Modular RESTful API library