visor-image 0.0.3 → 0.0.4

data/lib/image/cli.rb

@@ -65,30 +65,30 @@ module Visor
             options[:address] = addr
             new_opts << :address
           end
-          opts.on("-p", "--port PORT", "Use PORT (default: #{options[:port]})") do |port|
+          opts.on("-p", "--port PORT", "Bind to PORT number (default: #{options[:port]})") do |port|
             options[:port] = port.to_i
             new_opts << :port
           end
-          opts.on("-e", "--env NAME", "Set the execution environment (default: #{options[:env]})") do |env|
+          opts.on("-e", "--env ENV", "Set execution environment (default: #{options[:env]})") do |env|
             options[:env] = env.to_sym
             new_opts << :env
           end
-
-          opts.separator ""
-          opts.on('-l', '--log FILE', "Log to file (default: #{@options[:log_file]})") do |file|
-            @options[:log_file] = file
-            new_opts << :log_file
-          end
-          opts.on('-u', '--user USER', "Run as specified user") do |v|
-            @options[:user] = v
-            new_opts << :user
-          end
-          opts.on("-f", "--foreground", "Do not daemonize") do
+          opts.on("-f", "--foreground", "Do not daemonize, run in foreground") do
             options[:daemonize]  = false
             options[:log_stdout] = true
             new_opts << :daemonize
           end
 
+          #opts.separator ""
+          #opts.on('-l', '--log FILE', "Log to file (default: #{@options[:log_file]})") do |file|
+          #  @options[:log_file] = file
+          #  new_opts << :log_file
+          #end
+          #opts.on('-u', '--user USER', "Run as specified user") do |v|
+          #  @options[:user] = v
+          #  new_opts << :user
+          #end
+
           #opts.separator ""
           #opts.separator "SSL options:"
           #opts.on('--ssl', 'Enables SSL (default: off)') {|v| @options[:ssl] = v }
@@ -99,16 +99,16 @@ module Visor
           opts.separator ""
           opts.separator "Common options:"
 
-          opts.on_tail("-d", "--debug", "Set debugging on") do
+          opts.on_tail("-d", "--debug", "Enable debugging") do
             options[:debug] = true
             new_opts << :debug
           end
-          opts.on_tail('-v', '--verbose', "Enable verbose logging") do
-            options[:verbose] = true
-            new_opts << :verbose
-          end
-          opts.on_tail("-h", "--help", "Show this message") { show_options(opts) }
-          opts.on_tail('-V', '--version', "Show version") { show_version }
+          #opts.on_tail('-v', '--verbose', "Enable verbose logging") do
+          #  options[:verbose] = true
+          #  new_opts << :verbose
+          #end
+          opts.on_tail("-h", "--help", "Show this help message") { show_options(opts) }
+          opts.on_tail('-v', '--version', "Show version") { show_version }
         end
       end
 
@@ -161,9 +161,9 @@ module Visor
       # Display current server status
       def status
         if running?
-          STDERR.puts "VISoR Image Server is running PID: #{fetch_pid} URL: #{fetch_url}"
+          STDERR.puts "visor-image is running PID: #{fetch_pid} URL: #{fetch_url}"
         else
-          STDERR.puts "VISoR Image Server is not running."
+          STDERR.puts "visor-image is not running."
         end
       end
 
@@ -171,11 +171,11 @@ module Visor
       def stop
         begin
           pid = File.read(pid_file)
-          put_and_log :warn, "Stopping VISoR Image Server with PID: #{pid.to_i} Signal: INT"
+          put_and_log :warn, "Stopping visor-image with PID: #{pid.to_i} Signal: INT"
           Process.kill(:INT, pid.to_i)
           File.delete(url_file)
         rescue
-          put_and_log :warn, "Cannot stop VISoR Image Server, is it running?"
+          put_and_log :warn, "Cannot stop visor-image, is it running?"
           exit! 1
         end
       end
@@ -189,14 +189,14 @@ module Visor
           write_url
           launch!
         rescue => e
-          put_and_log :warn, "Error starting VISoR Image Server: #{e.message}\n#{e.backtrace.to_s}"
+          put_and_log :warn, "Error starting visor-image: #{e.message}\n#{e.backtrace.to_s}"
           exit! 1
         end
       end
 
       # Launch the server
       def launch!
-        put_and_log :info, "Starting VISoR Image Server at #{options[:address]}:#{options[:port]}"
+        put_and_log :info, "Starting visor-image at #{options[:address]}:#{options[:port]}"
         debug_settings
 
         runner     = Goliath::Runner.new(opts_to_goliath, Visor::Image::Server.new)
@@ -243,9 +243,9 @@ module Visor
         exit
       end
 
-      # Show VISoR Image Server version
+      # Show VISOR Image System version
       def show_version
-        puts "VISoR Image Server v#{Visor::Image::VERSION}"
+        puts "visor-image #{Visor::Image::VERSION}"
         exit
       end
 
@@ -253,7 +253,7 @@ module Visor
       def is_it_running?
         if files_exist?(pid_file, url_file)
           if running?
-            put_and_log :warn, "VISoR Image Server is already running at #{fetch_url}"
+            put_and_log :warn, "visor-image is already running at #{fetch_url}"
             exit! 1
           else
             clean
@@ -330,7 +330,7 @@ module Visor
         conf_file.each { |k, v| logger.debug "#{k}: #{v}" unless k == :file }
         logger.debug "**************************************************************"
 
-        logger.debug "Configurations passed from VISoR Image Server CLI:"
+        logger.debug "Configurations passed from visor-image CLI:"
         logger.debug "**************************************************************"
         if new_opts.empty?
           logger.debug "none"

data/lib/image/client.rb

@@ -6,37 +6,45 @@ require 'json'
 module Visor
   module Image
 
-    # The Client API for the VISoR Image Server. This class supports all image metadata and
-    # files operations through a programmatically interface.
+    # The programming API for the VISOR Image System (VIS). This class supports all image metadata and
+    # files operations through a programming interface.
     #
-    # After Instantiate a Client object its possible to directly interact with the
-    # image server and its store backends.
+    # After Instantiate a VIS Client object, its possible to directly interact with the VIS server. This API conforms
+    # to the tenets of the VIS server REST API {Visor::Image::Server Visor Image System server}.
+    #
+    # @note In the examples presented in this page, we will consider that the VIS server is listening in the 10.0.0.1 address and port 4568. We will also use a sample user account, with access_key "foo" and secret_key "bar".
     #
     class Client
       include Visor::Common::Exception
       include Visor::Common::Util
 
-      attr_reader :host, :port, :ssl, :access_key, :secret_key
+      attr_reader :host, :port, :access_key, :secret_key
 
-      # Initializes a new new VISoR Image Client.
+      # Initializes a new VIS programming client. VIS server settings (host and port address) and user's
+      # credentials should be provided for initialization or ignored (where settings will be loaded from the local VISOR configuration file).
       #
-      # @option opts [String] :host (DEFAULT_HOST) The host address where VISoR image server resides.
-      # @option opts [String] :port (DEFAULT_PORT) The host port where VISoR image server resides.
-      # @option opts [String] :ssl (false) If the connection should be made through HTTPS (SSL).
+      # @option opts [String] :host The host address where the VIS server resides.
+      # @option opts [String] :port The host port where the VIS server listens.
+      # @option opts [String] :access_key The user access key.
+      # @option opts [String] :secret_key The user secret key.
       #
-      # @example Instantiate a client with default values:
+      # @example Instantiate a client with default values loaded from the VISOR configuration file:
       #   client = Visor::Image::Client.new
       #
-      # @example Instantiate a client with custom host and port:
-      #   client = Visor::Image::Client.new(host: '127.0.0.1', port: 3000)
+      # @example Instantiate a client with custom host and port and with user's credentials loaded from the VISOR configuration file:
+      #   client = Visor::Image::Client.new(host: '10.0.0.1', port: 4568)
+      #
+      # @example Instantiate a client with custom host, port and user's credentials (nothing is loaded from the VISOR configuration file):
+      #   client = Visor::Image::Client.new(host: '10.0.0.1', port: 4568, access_key: 'foo', secret_key: 'bar')
+      #
+      # @return [Visor::Image::Client] A VIS programming client object.
       #
       def initialize(opts = {})
         configs     = Common::Config.load_config :visor_image
         @host       = opts[:host] || configs[:bind_host] || '0.0.0.0'
         @port       = opts[:port] || configs[:bind_port] || 4568
-        @ssl        = opts[:ssl] || false
-        @access_key = configs[:access_key]
-        @secret_key = configs[:secret_key]
+        @access_key = opts[:access_key] || configs[:access_key]
+        @secret_key = opts[:secret_key] || configs[:secret_key]
       end
 
       # Retrieves detailed image metadata of the image with the given id.
@@ -46,25 +54,32 @@ module Visor
       # @example Retrieve the image metadata with _id value:
       #   # wanted image _id
       #   id = "5e47a41e-7b94-4f65-824e-28f94e15bc6a"
+      #
       #   # ask for that image metadata
       #   client.head_image(id)
       #
       #     # return example:
       #     {
-      #        :_id          => "2cceffc6-ebc5-4741-9653-745524e7ac30",
-      #        :name         => "Ubuntu 10.10",
+      #        :_id          => "edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :uri          => "http://10.0.0.1:4568/images/edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :name         => "Ubuntu 12.04 Server",
       #        :architecture => "x86_64",
       #        :access       => "public",
-      #        :uri          => "http://0.0.0.0:4567/images/2cceffc6-ebc5-4741-9653-745524e7ac30",
-      #        :format       => "iso",
       #        :status       => "available",
-      #        :store        => "file"
+      #        :format       => "iso",
+      #        :size         => "732213248",
+      #        :store        => "s3",
+      #        :location     => "s3://mys3accesskey:mys3secretkey@s3.amazonaws.com/mybucket/edfa919a-0415-4d26-b54d-ae78ffc4dc79.iso",
+      #        :created_at   => "2012-06-15 21:05:20 +0100",
+      #        :checksum     => "140f3-2ba4b000-4be8328106940",
+      #        :owner        => "foo"
       #     }
       #
       # @return [Hash] The requested image metadata.
       #
       # @raise [NotFound] If image not found.
-      # @raise [InternalError] On internal server error.
+      # @raise [Forbidden] If user authentication fails.
+      # @raise [InternalError] If VIS server was not found on the referenced host and port address.
       #
       def head_image(id)
         path = "/images/#{id}"
@@ -73,20 +88,20 @@ module Visor
         pull_meta_from_headers(res)
       end
 
-      # Retrieves brief metadata of all public images.
+      # Retrieves brief metadata of all public and user's private images.
       # Options for filtering the returned results can be passed in.
       #
       # @option query [String] :attribute The image attribute value to filter returned results.
       # @option query [String] :sort ("_id") The image attribute to sort returned results.
       # @option query [String] :dir ("asc") The direction to sort results ("asc"/"desc").
       #
-      # @example Retrieve all public images brief metadata:
+      # @example Retrieve all images brief metadata:
       #   client.get_images
       #
       #     # returns:
       #     [<all images brief metadata>]
       #
-      # @example Retrieve all public 32bit images brief metadata:
+      # @example Retrieve all 32bit images brief metadata:
       #   client.get_images(architecture: 'i386')
       #
       #     # returns something like:
@@ -95,7 +110,7 @@ module Visor
       #       {:_id => "8cb55bb6...", :architecture => "i386", :name => "Ubuntu 11.10 Desktop"}
       #     ]
       #
-      # @example Retrieve all public 64bit images brief metadata, descending sorted by their name:
+      # @example Retrieve all 64bit images brief metadata, descending sorted by their name:
       #   client.get_images(architecture: 'x86_64', sort: 'name', dir: 'desc')
       #
       #     # returns something like:
@@ -104,11 +119,12 @@ module Visor
       #       {:_id => "069320f0...", :architecture => "x86_64", :name => "CentOS 6"}
       #     ]
       #
-      # @return [Array] All public images brief metadata.
+      # @return [Array] All images brief metadata.
       #   Just {Visor::Meta::Backends::Base::BRIEF BRIEF} fields are returned.
       #
-      # @raise [NotFound] If there are no public images registered on the server.
-      # @raise [InternalError] On internal server error.
+      # @raise [NotFound] If there are no images registered on VISOR.
+      # @raise [Forbidden] If user authentication fails.
+      # @raise [InternalError] If VIS server was not found on the referenced host and port address.
       #
       def get_images(query = {})
         str = build_query(query)
@@ -116,7 +132,7 @@ module Visor
         do_request(req)
       end
 
-      # Retrieves detailed metadata of all public images.
+      # Retrieves detailed metadata of all public and user's private images.
       #
       # @note Filtering and querying works the same as with {#get_images}. The only difference is the number
       # of disclosed attributes.
@@ -125,16 +141,17 @@ module Visor
       # @option query [String] :sort ("_id") The image attribute to sort returned results.
       # @option query [String] :dir ("asc") The direction to sort results ("asc"/"desc").
       #
-      # @example Retrieve all public images detailed metadata:
+      # @example Retrieve all images detailed metadata:
       #   # request for it
       #   client.get_images_detail
-      #   # returns an array of hashes with all public images metadata.
+      #   # returns an array of hashes with all images detailed metadata.
       #
-      # @return [Array] All public images detailed metadata.
+      # @return [Array] All images detailed metadata.
       #   The {Visor::Meta::Backends::Base::DETAIL_EXC DETAIL_EXC} fields are excluded from results.
       #
-      # @raise [NotFound] If there are no public images registered on the server.
-      # @raise [InternalError] On internal server error.
+      # @raise [NotFound] If there are no images registered on VISOR.
+      # @raise [Forbidden] If user authentication fails.
+      # @raise [InternalError] If VIS server was not found on the referenced host and port address.
       #
       def get_images_detail(query = {})
         str = build_query(query)
@@ -152,6 +169,7 @@ module Visor
       # @example Retrieve the image file with _id value:
       #   # wanted image _id
       #   id = "5e47a41e-7b94-4f65-824e-28f94e15bc6a"
+      #
       #   # ask for that image file
       #   client.get_image(id) do |chunk|
       #     # do something with chunks as they arrive here (e.g. write to file, etc)
@@ -160,7 +178,8 @@ module Visor
       # @return [Binary] The requested image file binary data.
       #
       # @raise [NotFound] If image not found.
-      # @raise [InternalError] On internal server error.
+      # @raise [Forbidden] If user authentication fails.
+      # @raise [InternalError] If VIS server was not found on the referenced host and port address.
       #
       def get_image(id)
         req = Net::HTTP::Get.new("/images/#{id}")
@@ -174,7 +193,7 @@ module Visor
         end
       end
 
-      # Register a new image on the server with the given metadata and optionally
+      # Register a new image on VISOR with the given metadata and optionally
       # upload its file, or provide a :location parameter containing the full path to
       # the already existing image file, stored somewhere.
       #
@@ -189,68 +208,74 @@ module Visor
       #
       # @example Insert a sample image metadata:
       #   # sample image metadata
-      #   meta = {:name => 'example', :architecture => 'i386'}
+      #   meta = {:name => 'CentOS 6.2', :architecture => 'i386', :format => 'iso', :access => 'private'}
+      #
       #   # insert the new image metadata
       #   client.post_image(meta)
       #
       #     # returns:
       #     {
-      #        :_id          => "d8b36b3f-e044-4a57-88fc-27b57338be10",
-      #        :uri          => "http://0.0.0.0:4568/images/d8b36b3f-e044-4a57-88fc-27b57338be10",
-      #        :name         => "Ubuntu 10.04 Server",
-      #        :architecture => "x86_64",
-      #        :access       => "public",
+      #        :_id          => "7583d669-8a65-41f1-b8ae-eb34ff6b322f",
+      #        :uri          => "http://10.0.0.1:4568/images/7583d669-8a65-41f1-b8ae-eb34ff6b322f",
+      #        :name         => "CentOS 6.2",
+      #        :architecture => "i386",
+      #        :access       => "private",
       #        :status       => "locked",
-      #        :created_at   => "2012-02-04 16:33:27 +0000"
+      #        :format       => "iso",
+      #        :created_at   => "2012-06-15 21:01:21 +0100",
+      #        :owner        => "foo"
       #     }
       #
       # @example Insert a sample image metadata and provide the location of its file:
-      #   # sample image poiting to the latest release of Ubuntu Server distro
-      #   meta = {:name  => 'Ubuntu Server (Latest)', :architecture => 'x86_64', :format => 'iso',
-      #           :store => 'http', :location => 'http://www.ubuntu.com/start-download?distro=server&bits=64&release=latest'}
+      #   # sample image pointing to the latest release of Ubuntu Server distro
+      #   meta = {:name  => 'Ubuntu 12.04 Server', :architecture => 'x86_64', :format => 'iso',
+      #           :store => 'http', :location => 'http://releases.ubuntu.com/12.04/ubuntu-12.04-desktop-amd64.iso'}
+      #
       #   # insert the new image metadata
       #   client.post_image(meta)
       #
       #     # returns:
       #     {
-      #        :_id          => "0733827b-836d-469e-8860-b900d4dabc46",
-      #        :uri          => "http://0.0.0.0:4568/images/0733827b-836d-469e-8860-b900d4dabc46",
-      #        :name         => "Ubuntu Server (Latest)",
+      #        :_id          => "edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :uri          => "http://10.0.0.1:4568/images/edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :name         => "Ubuntu 12.04 Server",
       #        :architecture => "x86_64",
       #        :access       => "public",
+      #        :status       => "available",
       #        :format       => "iso",
+      #        :size         => 732213248, # it will find the remote file size
       #        :store        => "http",
-      #        :location     => "http://www.ubuntu.com/start-download?distro=server&bits=64&release=latest",
-      #        :status       => "available",
-      #        :size         => 715436032, # it will fetch the correct remote file size
-      #        :created_at   => "2012-02-04 16:40:04 +0000",
-      #        :updated_at   => "2012-02-04 16:40:04 +0000",
-      #        :checksum     => "76264-2aa4b000-4af0618f1b180" # it will also fetch the remote file checksum or etag
+      #        :location     => "http://releases.ubuntu.com/12.04/ubuntu-12.04-desktop-amd64.iso",
+      #        :created_at   => "2012-06-15 21:05:20 +0100",
+      #        :checksum     => "140f3-2ba4b000-4be8328106940", # it will also find the remote file checksum or etag
+      #        :owner        => "foo"
       #     }
       #
       # @example Insert a sample image metadata and upload its file:
       #   # sample image metadata
-      #   meta = {:name => 'Ubuntu 10.04 Server', :architecture => 'x86_64', :store => 's3', :format => 'iso'}
+      #   meta = {:name => 'Fedora Desktop 17', :architecture => 'x86_64', :format => 'iso', :store => 'file'}
+      #
       #   # sample image file path
-      #   file = '~/ubuntu-10.04.3-server-amd64.iso'
+      #   file = '~/Fedora-17-x86_64-Live-Desktop.iso'
+      #
       #   # insert the new image metadata and upload file
       #   client.post_image(meta, file)
       #
       #     # returns:
       #     {
-      #        :_id          => "8074d23e-a9c0-454d-b935-cda5f6eb1bc8",
-      #        :uri          => "http://0.0.0.0:4568/images/8074d23e-a9c0-454d-b935-cda5f6eb1bc8",
-      #        :name         => "Ubuntu 10.04 Server",
+      #        :_id          => "e5fe8ea5-4704-48f1-905a-f5747cf8ba5e",
+      #        :uri          => "http://10.0.0.1:4568/images/e5fe8ea5-4704-48f1-905a-f5747cf8ba5e",
+      #        :name         => "Fedora Desktop 17",
       #        :architecture => "x86_64",
       #        :access       => "public",
+      #        :status       => "available",
       #        :format       => "iso",
+      #        :size         => 676331520,
       #        :store        => "file",
-      #        :location     => "s3://<access_key>:<secret_key>@s3.amazonaws.com/<bucket>/8074d23e-a9c0-454d-b935-cda5f6eb1bc8.iso",
-      #        :status       => "available",
-      #        :size         => 713529344,
-      #        :created_at   => "2012-02-04 16:29:04 +0000",
-      #        :updated_at   => "2012-02-04 16:29:04 +0000",
-      #        :checksum     => "fbd9044604120a1f6cc708048a21e066"
+      #        :location     => "file:///home/foo/VMs/e5fe8ea5-4704-48f1-905a-f5747cf8ba5e.iso",
+      #        :created_at   => "2012-06-15 21:03:32 +0100",
+      #        :checksum     => "330dcb53f253acdf76431cecca0fefe7",
+      #        :owner        => "foo"
       #     }
       #
       # @return [Hash] The already inserted image metadata.
@@ -259,9 +284,10 @@ module Visor
       # @raise [Invalid] If the location header is present no file content can be provided.
       # @raise [Invalid] If trying to post an image file to a HTTP backend.
       # @raise [Invalid] If provided store is an unsupported store backend.
-      # @raise [NotFound] If no image data is found at the provided location.
-      # @raise [ConflictError] If the provided image file already exists in the backend store.
-      # @raise [InternalError] On internal server error.
+      # @raise [NotFound] If no image file is found at the provided location.
+      # @raise [ConflictError] If the provided image file already exists in the target backend store.
+      # @raise [Forbidden] If user authentication fails.
+      # @raise [InternalError] If VIS server was not found on the referenced host and port address.
       #
       def post_image(meta, file = nil)
         req = Net::HTTP::Post.new('/images')
@@ -290,74 +316,91 @@ module Visor
       #
       # @example Update a sample image metadata:
       #   # wanted image _id
-      #   id = "2373c3e5-b302-4529-8e23-c4ffc85e7613"
+      #   id = "edfa919a-0415-4d26-b54d-ae78ffc4dc79."
+      #
       #   # metadata to update
-      #   update = {:name => 'Debian 6.0', :architecture => "x86_64"}
+      #   update = {:name => 'Ubuntu 12.04', :architecture => "i386"}
+      #
       #   # update the image metadata with some new values
       #   client.put_image(id, update)
       #
       #     # returns:
       #     {
-      #        :_id          => "2373c3e5-b302-4529-8e23-c4ffc85e7613",
-      #        :uri          => "http://0.0.0.0:4568/images/2373c3e5-b302-4529-8e23-c4ffc85e7613",
-      #        :name         => "Debian 6.0",
-      #        :architecture => "x86_64",
+      #        :_id          => "edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :uri          => "http://10.0.0.1:4568/images/edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :name         => "Ubuntu 12.04",
+      #        :architecture => "i386",
       #        :access       => "public",
-      #        :status       => "locked",
-      #        :created_at   => "2012-02-03 12:40:30 +0000",
-      #        :updated_at   => "2012-02-04 16:35:10 +0000"
+      #        :status       => "available",
+      #        :format       => "iso",
+      #        :size         => 732213248,
+      #        :store        => "http",
+      #        :location     => "http://releases.ubuntu.com/12.04/ubuntu-12.04-desktop-amd64.iso",
+      #        :created_at   => "2012-06-15 21:05:20 +0100",
+      #        :updated_at   => "2012-06-15 21:10:36 +0100",
+      #        :checksum     => "140f3-2ba4b000-4be8328106940",
+      #        :owner        => "foo"
       #     }
       #
-      # @example Update a sample image metadata and provide the location of its file:
+      # @example Update the image metadata and provide the location of its file. In this example,
+      # the image file was already stored in the local filesystem backend,
+      # thus it is not needed to upload the file, but rather just register that the image file is there.
       #   # wanted image _id
-      #   id = "2373c3e5-b302-4529-8e23-c4ffc85e7613"
+      #   id = "7583d669-8a65-41f1-b8ae-eb34ff6b322f"
+      #
       #   # metadata update
       #   update = {:format => 'iso', :store => 'file', :location => 'file:///Users/server/debian-6.0.4-amd64.iso'}
+      #
       #   # update the image metadata with file values
       #   client.put_image(id, update)
       #
       #     # returns:
       #     {
-      #        :_id          => "2373c3e5-b302-4529-8e23-c4ffc85e7613",
-      #        :uri          => "http://0.0.0.0:4568/images/2373c3e5-b302-4529-8e23-c4ffc85e7613",
-      #        :name         => "Debian 6.0",
-      #        :architecture => "x86_64",
-      #        :access       => "public",
-      #        :status       => "locked",
+      #        :_id          => "7583d669-8a65-41f1-b8ae-eb34ff6b322f",
+      #        :uri          => "http://10.0.0.1:4568/images/7583d669-8a65-41f1-b8ae-eb34ff6b322f",
+      #        :name         => "CentOS 6.2",
+      #        :architecture => "i386",
+      #        :access       => "private",
+      #        :status       => "available",
       #        :format       => "iso",
+      #        :size         => 729808896,
       #        :store        => "file",
-      #        :location     => "file:///Users/server/debian-6.0.4-amd64.iso",
-      #        :status       => "available",
-      #        :size         => 764529654,
-      #        :created_at   => "2012-02-03 12:40:30 +0000",
-      #        :updated_at   => "2012-02-04 16:38:55 +0000"
+      #        :location     => "file:///home/foo/downloads/CentOS-6.2-i386-LiveCD.iso",
+      #        :created_at   => "2012-06-15 21:01:21 +0100",
+      #        :updated_at   => "2012-06-15 21:12:27 +0100",
+      #        :checksum     => "1b8441b6f4556be61c16d9750da42b3f",
+      #        :owner        => "foo"
       #     }
       #
-      # @example Update image metadata and upload its file:
+      # @example OR update image metadata and upload its file, if it is not already in some compatible storage backend:
       #   # wanted image _id
-      #   id = "d5bebdc8-66eb-4450-b8d1-d8127f50779d"
+      #   id = "7583d669-8a65-41f1-b8ae-eb34ff6b322f"
+      #
       #   # metadata update
-      #   update = {:format => 'iso', :store => 's3'}
+      #   update = {:format => 'iso', :store => 'file'}
+      #
       #   # sample image file path
-      #   file = '~/CentOS-6.2-x86_64-LiveCD.iso'
+      #   file = '~/CentOS-6.2-i386-LiveCD.iso'
+      #
       #   # insert the new image metadata and upload file
       #   client.put_image(id, meta, file)
       #
       #     # returns:
       #     {
-      #        :_id          => "d5bebdc8-66eb-4450-b8d1-d8127f50779d",
-      #        :uri          => "http://0.0.0.0:4568/images/d5bebdc8-66eb-4450-b8d1-d8127f50779d",
+      #        :_id          => "7583d669-8a65-41f1-b8ae-eb34ff6b322f",
+      #        :uri          => "http://10.0.0.1:4568/images/7583d669-8a65-41f1-b8ae-eb34ff6b322f",
       #        :name         => "CentOS 6.2",
-      #        :architecture => "x86_64",
-      #        :access       => "public",
-      #        :format       => "iso",
-      #        :store        => "s3",
-      #        :location     => "s3://<access_key>:<secret_key>@s3.amazonaws.com/<bucket>/d5bebdc8-66eb-4450-b8d1-d8127f50779d.iso",
+      #        :architecture => "i386",
+      #        :access       => "private",
       #        :status       => "available",
-      #        :size         => 731906048,
-      #        :created_at   => "2012-01-20 16:29:01 +0000",
-      #        :updated_at   => "2012-02-04 16:50:12 +0000",
-      #        :checksum     => "610c0b9684dba804467514847e8a012f"
+      #        :format       => "iso",
+      #        :size         => 729808896,
+      #        :store        => "file",
+      #        :location     => "file:///home/foo/VMs/7583d669-8a65-41f1-b8ae-eb34ff6b322f.iso",
+      #        :created_at   => "2012-06-15 21:01:21 +0100",
+      #        :updated_at   => "2012-06-15 21:12:27 +0100",
+      #        :checksum     => "1b8441b6f4556be61c16d9750da42b3f",
+      #        :owner        => "foo"
       #     }
       #
       # @return [Hash] The already inserted image metadata.
@@ -370,7 +413,8 @@ module Visor
       # @raise [NotFound] If no image data is found at the provided location.
       # @raise [ConflictError] If trying to assign image file to a locked or uploading image.
       # @raise [ConflictError] If the provided image file already exists in the backend store.
-      # @raise [InternalError] On internal server error.
+      # @raise [Forbidden] If user authentication fails.
+      # @raise [InternalError] If VIS server was not found on the referenced host and port address.
       #
       def put_image(id, meta, file = nil)
         req = Net::HTTP::Put.new("/images/#{id}")
@@ -388,42 +432,95 @@ module Visor
       #
       # @param id [String] The image's _id which will be deleted.
       #
-      # @example Delete an image metadata:
+      # @example Delete an image:
       #   # wanted image _id
-      #   id = "66414330-bbb5-42be-8a0e-b336cf6665f4"
+      #   id = "edfa919a-0415-4d26-b54d-ae78ffc4dc79"
+      #
       #   # delete the image metadata and file
       #   client.delete_image(id)
       #
       #     # returns:
       #     {
-      #        :_id          => "66414330-bbb5-42be-8a0e-b336cf6665f4",
-      #        :uri          => "http://0.0.0.0:4568/images/66414330-bbb5-42be-8a0e-b336cf6665f4",
-      #        :name         => "Ubuntu 11.04 Server",
-      #        :architecture => "x86_64",
+      #        :_id          => "edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :uri          => "http://10.0.0.1:4568/images/edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :name         => "Ubuntu 12.04",
+      #        :architecture => "i386",
       #        :access       => "public",
-      #        :format       => "iso",
-      #        :store        => "file",
-      #        :location     => "file:///Users/server/VMs/66414330-bbb5-42be-8a0e-b336cf6665f4.iso",
       #        :status       => "available",
-      #        :size         => 722549344,
-      #        :created_at   => "2012-02-04 15:23:48 +0000",
-      #        :updated_at   => "2012-02-04 15:54:52 +0000",
-      #        :accessed_at  => "2012-02-04 16:02:44 +0000",
-      #        :access_count => 26,
-      #        :checksum     => "fbd9044604120a1f6cc708048a21e066"
+      #        :format       => "iso",
+      #        :size         => 732213248,
+      #        :store        => "http",
+      #        :location     => "http://releases.ubuntu.com/12.04/ubuntu-12.04-desktop-amd64.iso",
+      #        :created_at   => "2012-06-15 21:05:20 +0100",
+      #        :updated_at   => "2012-06-15 21:10:36 +0100",
+      #        :checksum     => "140f3-2ba4b000-4be8328106940",
+      #        :owner        => "foo"
       #     }
       #
       # @return [Hash] The already deleted image metadata. Useful for recover on accidental delete.
       #
-      # @raise [NotFound] If image meta or data not found.
+      # @raise [NotFound] If image meta or file were not found.
       # @raise [Forbidden] If user does not have permission to manipulate the image file.
-      # @raise [InternalError] On internal server error.
+      # @raise [Forbidden] If user authentication fails.
+      # @raise [InternalError] If VIS server was not found on the referenced host and port address.
       #
       def delete_image(id)
         req = Net::HTTP::Delete.new("/images/#{id}")
         do_request(req)
       end
 
+      # Removes images that match a specific query.
+      #
+      # @param query [Hash] A query to find images that should be deleted.
+      #
+      # @example Delete an image by queries:
+      #   # we want to delete all 64-bit images:
+      #   query = {architecture: 'x86_64'}
+      #
+      #   # delete the image metadata and file
+      #   client.delete_by_query(query)
+      #
+      #     # returns the matched and deleted images metadata (where in this example we had only the following 64-bit images registered):
+      #     [
+      #       {
+      #        :_id          => "e5fe8ea5-4704-48f1-905a-f5747cf8ba5e",
+      #        :uri          => "http://10.0.0.1:4568/images/e5fe8ea5-4704-48f1-905a-f5747cf8ba5e",
+      #        :name         => "Fedora Desktop 17",
+      #        :architecture => "x86_64",
+      #        :access       => "public",
+      #        :status       => "available",
+      #        :format       => "iso",
+      #        :size         => 676331520,
+      #        :store        => "file",
+      #        :location     => "file:///home/foo/VMs/e5fe8ea5-4704-48f1-905a-f5747cf8ba5e.iso",
+      #        :created_at   => "2012-06-15 21:03:32 +0100",
+      #        :checksum     => "330dcb53f253acdf76431cecca0fefe7",
+      #        :owner        => "foo"
+      #       },
+      #       {
+      #        :_id          => "edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :uri          => "http://10.0.0.1:4568/images/edfa919a-0415-4d26-b54d-ae78ffc4dc79",
+      #        :name         => "Ubuntu 12.04 Server",
+      #        :architecture => "x86_64",
+      #        :access       => "public",
+      #        :status       => "available",
+      #        :format       => "iso",
+      #        :size         => "732213248",
+      #        :store        => "s3",
+      #        :location     => "s3://mys3accesskey:mys3secretkey@s3.amazonaws.com/mybucket/edfa919a-0415-4d26-b54d-ae78ffc4dc79.iso",
+      #        :created_at   => "2012-06-15 21:05:20 +0100",
+      #        :checksum     => "140f3-2ba4b000-4be8328106940",
+      #        :owner        => "foo"
+      #       }
+      #     ]
+      #
+      # @return [Hash] The already deleted image metadata. Useful for recover on accidental delete.
+      #
+      # @raise [NotFound] If image meta or file were not found.
+      # @raise [Forbidden] If user does not have permission to manipulate the image file.
+      # @raise [Forbidden] If user authentication fails.
+      # @raise [InternalError] If VIS server was not found on the referenced host and port address.
+      #
       def delete_by_query(query)
         result = []
         images = get_images(query)
@@ -440,7 +537,7 @@ module Visor
       # Prepare headers for request
       def prepare_headers(req)
         sign_request(access_key, secret_key, req.method, req.path, req)
-        req['User-Agent'] = 'VISoR Image Server client'
+        req['User-Agent'] = 'VISOR Image System client'
         req['Accept']     = "application/json"
       end
 
@@ -473,6 +570,8 @@ module Visor
           raise Forbidden, parse_response(res)
         when Net::HTTPInternalServerError then
           raise InternalError, parse_response(res)
+        when Net::HTTPServiceUnavailable then
+          raise InternalError, parse_response(res)
         end
       end