squall 1.0.2 → 1.1.0

data/lib/squall/user.rb

@@ -4,84 +4,180 @@ module Squall
     # Return a list of all users
     def list
       response = request(:get, '/users.json')
-      response.collect { |user| user['user']}
+      response.collect { |user| user['user'] }
     end
 
 
     # Create a new User
     #
-    # ==== Options
+    # ==== Params
     #
     # * +options+ - Params for creating the User
     #
+    # ==== Options
+    #
+    # * +login*+ - Login name
+    # * +email*+ - Email address
+    # * +first_name*+ - First name
+    # * +last_name*+ - Last name
+    # * +password*+ - Password
+    # * +passwor_confirmation*+ - Password
+    # * +role+ - Role to be assigned to user
+    # * +time_zone+ - Time zone for user.  If not provided it will be set automatically.
+    # * +locale+ - Locale for user.  If not provided it will be set automatically.
+    # * +status+ - User's status: +active+, +suspended+, +deleted+
+    # * +billing_plan_id+ - ID of billing plan to be applied to user's account
+    # * +role_ids+ - Array of IDs of roles to be assigned to the user
+    # * +suspend_after_hours+ - Number of hours after which the account will be automatically suspended
+    # * +suspend_at+ - Time after which the account will automatically be suspended, formatted as +YYYYMMDD ThhmmssZ+
+    #
     # ==== Example
     #
-    #   create :login      => 'bob',
-    #          :email      => 'something@example.com',
-    #          :password   => 'secret',
-    #          :first_name => 'Bob',
-    #          :last_name  => 'Smith',
-    #          :group_id   => 1
+    #   create :login                 => 'bob',
+    #          :email                 => 'something@example.com',
+    #          :password              => 'secret',
+    #          :password_confirmation => 'secret'
+    #          :first_name            => 'Bob',
+    #          :last_name             => 'Smith'
     def create(options = {})
-      params.required(:login, :email, :password).accepts(:first_name, :last_name, :group_id).validate!(options)
+      params.required(:login, :email,:first_name, :last_name, :password, :password_confirmation).accepts(:role, :time_zone, :locale, :status, :billing_plan_id, :role_ids, :suspend_after_hours, :suspend_at).validate!(options)
       request(:post, '/users.json', default_params(options))
     end
 
-    # Return a Hash of the given User
+    # Edit a user
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
+    # * +options+ - Params for creating the user
+    #
+    # ==== Options
+    #
+    # See #create
+    def edit(id, options={})
+      params.accepts(:email, :password, :password_confirmation, :first_name, :last_name, :user_group_id, :billing_plan_id, :role_ids, :suspend_at).validate!(options)
+      request(:put, "/users/#{id}.json", default_params(options))
+    end
+
+    # Return a Hash of the given user
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
     def show(id)
       response = request(:get, "/users/#{id}.json")
-      response.first[1]
+      response["user"]
     end
 
-    # Create a new API Key for a User
+    # Create a new API Key for a user
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
     def generate_api_key(id)
-      request(:post, "/users/#{id}/make_new_api_key.json")
+      response = request(:post, "/users/#{id}/make_new_api_key.json")
+      response["user"]
     end
 
-    # Suspend a User
+    # Suspend a user
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
     def suspend(id)
       response = request(:get, "/users/#{id}/suspend.json")
-      response.first[1]
+      response["user"]
     end
 
     # Activate a user
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
     def activate(id)
       response = request(:get, "/users/#{id}/activate_user.json")
-      response.first[1]
+      response["user"]
     end
     alias_method :unsuspend, :activate
 
     # Delete a user
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
+    #
+    # Note: this does not delete remove a user from the database.  First, their status will be set to "Deleted."  If you call this method again, the user will be completely removed.
     def delete(id)
-      response = request(:delete, "/users/#{id}.json")
-      success
+      request(:delete, "/users/#{id}.json")
     end
 
-    # Get the stats for a User
+    # Get the stats for each of a User's VirtualMachines
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
     def stats(id)
-      response = request(:get, "/users/#{id}/vm_stats.json")
-      response.first['vm_stats']
+      request(:get, "/users/#{id}/vm_stats.json")
+    end
+
+    # Get a list of bills for the User
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
+    def monthly_bills(id)
+      response = request(:get, "/users/#{id}/monthly_bills.json")
     end
 
     # Return a list of VirtualMachines for a User
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
     def virtual_machines(id)
       response = request(:get, "/users/#{id}/virtual_machines.json")
       response.collect { |vm| vm['virtual_machine']}
     end
 
-    # Edit a role for a user
+    # Return a list of Hypervisors for a User's VirtualMachines
     #
-    # ==== Options
+    # ==== Params
     #
-    # * +id+ - id of the User
-    # * +roles+ - A single Role id or Array of Roles
+    # * +id*+ - ID of user
+    def hypervisors(id)
+      response = request(:get, "/users/#{id}/hypervisors.json")
+      response.collect { |vm| vm['hypervisor']}
+    end
+
+    # Return a list of data store zones associated with user
     #
-    # ==== Example
+    # ==== Params
+    #
+    # * +id*+ - ID of user
+    def data_store_zones(id)
+      response = request(:get, "/users/#{id}/data_store_zones.json")
+      response.collect { |vm| vm['data-store-group']}
+    end
+
+    # Return a list of network zones associated with user
+    #
+    # ==== Params
     #
-    #   edit_role 1, 2 # Role 2
-    #   edit_role 1, [1,2] # Role 1 & 2
-    def edit_role(id, *roles)
-      request(:put, "/users/#{id}.json", default_params(:role_ids => roles))
+    # * +id*+ - ID of user
+    def network_zones(id)
+      response = request(:get, "/users/#{id}/network_zones.json")
+      response.collect { |vm| vm['network_group']}
     end
+
+    # Return a description of resources available to a user for creating a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of user
+    def limits(id)
+      response = request(:get, "/users/#{id}/limits.json")
+      response["limits"]
+    end
+
   end
 end

data/lib/squall/user_group.rb

@@ -0,0 +1,56 @@
+module Squall
+  # OnApp UserGroup
+  class UserGroup < Base
+
+    # Return a list of all user groups
+    def list
+      response = request(:get, "/user_groups.json")
+      response.collect { |user_group| user_group['user_group'] }
+    end
+
+    # Create a user group
+    #
+    # ==== Params
+    #
+    # * +options+ - Params for creating the user groups
+    #
+    # ==== Options
+    #
+    # * +label*+ - Label for the user group
+    #
+    # ==== Example
+    #
+    #   create :label => "My new user group"
+    def create(options={})
+      params.required(:label).validate!(options)
+      request(:post, "/user_groups.json", default_params(options))
+    end
+
+    # Edit a user group
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the user group
+    # * +options+ - Params for creating the user groups
+    #
+    # ==== Options
+    #
+    # See #create
+    #
+    # * +options+ - Params for editing the user group.
+    def edit(id, options={})
+      params.accepts(:label).validate!(options)
+      request(:put, "/user_groups/#{id}.json", default_params(options))
+    end
+
+    # Delete a user group
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the user group
+    def delete(id)
+      request(:delete, "/user_groups/#{id}.json")
+    end
+
+  end
+end

data/lib/squall/virtual_machine.rb

@@ -1,40 +1,66 @@
 module Squall
   # OnApp VirtualMachine
   class VirtualMachine < Base
-    # Return a list of VirtualMachines
+    # Return a list of virtual machines
     def list
       response = request(:get, '/virtual_machines.json')
       response.collect { |v| v['virtual_machine'] }
     end
 
-    # Return a Hash for the given VirtualMachine
+    # Return a Hash for the given virtual machines
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
     def show(id)
       response = request(:get, "/virtual_machines/#{id}.json")
       response.first[1]
     end
 
-    # Create a new VirtualMachine
+    # Create a new virtual machine
+    #
+    # ==== Params
+    #
+    # * +options+ - Params for creating the virtual machine
     #
     # ==== Options
     #
-    # * +options+ - Params for creating the VirtualMachine
+    # * +label*+ - Label for the virtual machine
+    # * +hostname*+ - Hostname for the virtual machine
+    # * +memory*+ - Amount of RAM assigned to this virtual machine
+    # * +cpus*+ - Number of CPUs assigned to the virtual machine
+    # * +cpu_shares*+ - CPU priority for this virtual machine
+    # * +primary_disk_size*+ - Disk space for this virtual machine
+    # * +template_id*+ - ID for a template from which the virtual machine will be built
+    # * +hypervisor_id+ - ID for a hypervisor where virtual machine will be built.  If not provided the virtual machine will be assigned to the first available hypervisor
+    # * +swap_disk_size+ - Swap space (does not apply to Windows virtual machines)
+    # * +primary_network_id+ - ID of the primary network
+    # * +required_automatic_backup+ - Set to '1' if automatic backups are required
+    # * +rate_limit+ - Max port speed
+    # * +required_ip_address_assignment+ - Set to '1' if you wish to assign an IP address automatically
+    # * +required_virtual_machine_build+ - Set to '1' to build virtual machine automatically
+    # * +admin_note+ - Comment that can only be set by admin of virtual machine
+    # * +note+ - Comment that can be set by the user of the virtual machine
+    # * +allowed_hot_migrate+ - Set to '1'  to allow hot migration
+    # * +initial_root_password+ - Root password for the virtual machine.  6-31 characters consisting of letters, numbers, '-' and '_'
     #
     # ==== Example
     #
     #  params = {
-    #    :label => 'testmachine', 
+    #    :label => 'testmachine',
     #    :hypervisor_id => 5,
-    #    :hostname => 'testmachine', 
-    #    :memory => 512, 
+    #    :hostname => 'testmachine',
+    #    :memory => 512,
     #    :cpus => 1,
-    #    :cpu_shares => 10, 
-    #    :primary_disk_size => 10
+    #    :cpu_shares => 10,
+    #    :primary_disk_size => 10,
+    #    :template_id => 1
     #  }
     #
     #  create params
     def create(options = {})
-      required = [:label, :hypervisor_id, :hostname, :memory, :cpus, :cpu_shares, :primary_disk_size]
-      optional = [:cpu_shares,
+      required = [:label, :hostname, :memory, :cpus, :cpu_shares, :primary_disk_size, :template_id]
+      optional = [:hypervisor_id,
                   :swap_disk_size,
                   :primary_network_id,
                   :required_automatic_backup,
@@ -44,7 +70,6 @@ module Squall
                   :admin_note,
                   :note,
                   :allowed_hot_migrate,
-                  :template_id,
                   :initial_root_password
       ]
       params.required(required).accepts(optional).validate! options
@@ -52,37 +77,33 @@ module Squall
       response['virtual_machine']
     end
 
-    # Build a VirtualMachine
+    # Build a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    # * +options+ - Params for creating the virtual machine
     #
     # ==== Options
     #
-    # * +id+
-    # * +options+ - :template_id, :required_startup
+    # * +template_id*+ - ID of the template to be used to build the virtual machine
+    # * +required_startup+ - Set to '1' to startup virtual machine after building
     def build(id, options = {})
-      params.accepts(:template_id, :required_startup).validate! options
+      params.required(:template_id).accepts(:required_startup).validate! options
       response = request(:post, "/virtual_machines/#{id}/build.json", default_params(options))
       response.first[1]
     end
 
-    # Edit a new VirtualMachine
+    # Edit a virtual machine
     #
-    # ==== Options
+    # ==== Params
     #
-    # * +options+ - Params for editing the VirtualMachine
+    # * +id*+ - ID of the virtual machine
+    # * +options+ - Params for creating the virtual machine
     #
-    # ==== Example
-    #
-    #  params = {
-    #    :label => 'testmachine', 
-    #    :hypervisor_id => 5,
-    #    :hostname => 'testmachine', 
-    #    :memory => 512, 
-    #    :cpus => 1,
-    #    :cpu_shares => 10, 
-    #    :primary_disk_size => 10
-    #  }
+    # ==== Options
     #
-    #  edit params
+    # See #create
     def edit(id, options = {})
       optional = [:label,
                   :hypervisor_id,
@@ -108,79 +129,182 @@ module Squall
       request(:put, "/virtual_machines/#{id}.json", default_params(options))
     end
 
-    # Change the owner of a VirtualMachine
+    # Change the owner of a virtual machine
     #
-    # ==== Options
-    # * +id+ - id of the VirtualMachine
-    # * +user_id+ - id of the target User
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    # * +user_id*+ - ID of the target User
     def change_owner(id, user_id)
       response = request(:post, "/virtual_machines/#{id}/change_owner.json", :query => { :user_id => user_id })
       response['virtual_machine']
     end
 
     # Change the password
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    # * +password*+ - New password
     def change_password(id, password)
       response = request(:post, "/virtual_machines/#{id}/reset_password.json", :query => { :new_password => password })
       response['virtual_machine']
     end
 
-    # Migrate a VirtualMachine to a new Hypervisor
+    # Assigns SSH keys of all administrators and a owner to a virtual machine
     #
-    # ==== Options
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    def set_ssh_keys(id)
+      response = request(:post, "/virtual_machines/#{id}/set_ssh_keys.json")
+      response['virtual_machine']
+    end
+
+    # Migrate a virtual machine to a new hypervisor
+    #
+    # ==== Params
     #
-    # * +id+
+    # * +id*+ - ID of the virtual machine
     # * +options+ - :destination, :cold_migrate_on_rollback
+    #
+    # ==== Options
+    #
+    # * +destination*+ - ID of a hypervisor to which to migrate the virtual machine
+    # * +cold_migrate_on_rollback+ - Set to '1' to switch to cold migration if migration fails
     def migrate(id, options = {})
-      params.required(:destination).accepts(:cold_migrate_on_rollback).validate! options 
-      response = request(:post, "/virtual_machines/#{id}/migrate.json", :query => options )
+      params.required(:destination).accepts(:cold_migrate_on_rollback).validate! options
+      response = request(:post, "/virtual_machines/#{id}/migrate.json", :query => {:virtual_machine => options} )
+    end
+
+    # Toggle the VIP status of the virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    def set_vip(id)
+      response = request(:post, "/virtual_machines/#{id}/set_vip.json")
+      response['virtual_machine']
     end
 
-    # Delete a VirtualMachine
+    # Delete a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
     def delete(id)
       request(:delete, "/virtual_machines/#{id}.json")
     end
 
-    # Resize a VirtualMachine's memory
+    # Resize a virtual machine's memory
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    # * +options+ - Options for resizing
+    #
+    # * ==== Options
+    #
+    # * +memory*+ - Amount of RAM assigned to this virtual machine
+    # * +cpus*+ - Number of CPUs assigned to the virtual machine
+    # * +cpu_shares*+ - CPU priority for this virtual machine
+    # * +allow_cold_resize*+ - Set to '1' to allow cold resize
     def resize(id, options = {})
-      params.required(:memory).accepts(:allow_migration).validate! options
+      raise ArgumentError, "You must specify at least one of the following attributes to resize: :memory, :cpus, :cpu_shares, :allow_cold_resize" if options.empty?
+      params.accepts(:memory, :cpus, :cpu_shares, :allow_cold_resize).validate! options
       response = request(:post, "/virtual_machines/#{id}/resize.json", default_params(options))
       response['virtual_machine']
     end
 
-    # Suspend/Unsuspend a VirtualMachine
+    # Suspend/Unsuspend a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
     def suspend(id)
       response = request(:post, "/virtual_machines/#{id}/suspend.json")
       response['virtual_machine']
     end
-    alias_method :unsuspend, :suspend
 
-    # Unlock a VirtualMachine
+    # Unlock a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
     def unlock(id)
       response = request(:post, "/virtual_machines/#{id}/unlock.json")
       response['virtual_machine']
     end
 
-    # Boot a VirtualMachine
+    # Boot a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
     def startup(id)
       response = request(:post, "/virtual_machines/#{id}/startup.json")
       response['virtual_machine']
     end
 
-    # Shutdown a VirtualMachine
+    # Shutdown a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
     def shutdown(id)
       response = request(:post, "/virtual_machines/#{id}/shutdown.json")
       response['virtual_machine']
     end
 
-    # Stop a VirtualMachine
+    # Stop a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
     def stop(id)
       response = request(:post, "/virtual_machines/#{id}/stop.json")
       response['virtual_machine']
     end
 
-    # Reboot a VirtualMachine
-    def reboot(id)
-      response = request(:post, "/virtual_machines/#{id}/reboot.json")
+    # Reboot a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    # * +recovery+ - Set to true to reboot in recovery, defaults to false
+    def reboot(id, recovery=false)
+      response = request(:post, "/virtual_machines/#{id}/reboot.json", {:query => recovery ? {:mode => :recovery} : nil})
+      response['virtual_machine']
+    end
+
+    # Segregate a virtual machine from another virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    # * +target_vm_id+* - ID of another virtual machine from which it should be segregated
+    def segregate(id, target_vm_id)
+      response = request(:post, "/virtual_machines/#{id}/strict_vm.json", default_params(:strict_virtual_machine_id => target_vm_id))
+      response['virtual_machine']
+    end
+
+    # Open a console for a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    def console(id)
+      response = request(:post, "/virtual_machines/#{id}/console.json")
+      response['virtual_machine']
+    end
+
+    # Get billing statistics for a virtual machine
+    #
+    # ==== Params
+    #
+    # * +id*+ - ID of the virtual machine
+    def stats(id)
+      response = request(:post, "/virtual_machines/#{id}/vm_stats.json")
       response['virtual_machine']
     end
   end

data/lib/squall/whitelist.rb

@@ -0,0 +1,74 @@
+module Squall
+  # OnApp Whitelist
+  class Whitelist < Base
+
+    # Return a list of all whitelists
+    #
+    # ==== Params
+    #
+    # * +user_id*+ - ID of the user to display whitelists for
+    def list(user_id)
+      response = request(:get, "/users/#{user_id}/user_white_lists.json")
+      response.collect { |user| user['user_white_list'] }
+    end
+
+    # Get the details for a whitelist
+    #
+    # ==== Params
+    #
+    # * +user_id*+ - ID of the user
+    # * +id*+ - ID of the whitelist
+    def show(user_id, id)
+      response = request(:get, "/users/#{user_id}/user_white_lists/#{id}.json")
+      response['user_white_list']
+    end
+
+    # Create a whitelist for a user
+    #
+    # ==== Params
+    #
+    # * +user_id*+ - ID of the user
+    # * +options+ - Params for creating the whitelist
+    #
+    # ==== Options
+    #
+    # * +ip*+ - IP to be whitelisted
+    # * +description+ - Description of the whitelist
+    #
+    # ==== Example
+    #
+    #   create :ip          => 192.168.1.1,
+    #          :description => "Computer that someone I trust uses"
+    def create(user_id, options={})
+      params.required(:ip).accepts(:description).validate!(options)
+      request(:post, "/users/#{user_id}/user_white_lists.json", :query => {:user_white_list => options})
+    end
+
+    # Edit a whitelist
+    #
+    # ==== Params
+    #
+    # * +user_id*+ - ID of the user
+    # * +id*+ - ID of whitelist
+    # * +options+ - Params for editing the whitelist
+    #
+    # ==== Options
+    #
+    # See #create
+    def edit(user_id, id, options={})
+      params.accepts(:ip, :description).validate!(options)
+      request(:put, "/users/#{user_id}/user_white_lists/#{id}.json", :query => {:user_white_list => options})
+    end
+
+    # Delete a whitelist
+    #
+    # ==== Params
+    #
+    # * +user_id*+ - ID of the user
+    # * +id*+ - ID of whitelist
+    def delete(user_id, id)
+      request(:delete, "/users/#{user_id}/user_white_lists/#{id}.json")
+    end
+
+  end
+end