Class: Visor::Meta::Client

Inherits:
Object
  • Object
show all
Includes:
Common::Exception
Defined in:
lib/meta/client.rb

Overview

The Client API for the VISoR Meta. This class supports all image metadata manipulation operations through a programmatically interface.

After Instantiate a Client object its possible to directly interact with the meta server and its database backend.

Constant Summary collapse

DEFAULT_HOST = 
configs[:bind_host] || '0.0.0.0'
DEFAULT_PORT = 
configs[:bind_port] || 4567

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(opts = {}) ⇒ Client

Initializes a new new VISoR Meta Client.

Examples:

Instantiate a client with default values:

client = Visor::Meta::Client.new

Instantiate a client with default values and SSL enabled:

client = Visor::Meta::Client.new(ssl: true)

Instantiate a client with custom host and port:

client = Visor::Meta::Client.new(host: '127.0.0.1', port: 3000)

Parameters:

  • opts (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (opts):

  • :host (String) — default: DEFAULT_HOST —

    The host address where VISoR meta server resides.

  • :port (String) — default: DEFAULT_PORT —

    The host port where VISoR meta server resides.

  • :ssl (String) — default: false —

    If the connection should be made through HTTPS (SSL).



41
42
43
44
45
 
# File 'lib/meta/client.rb', line 41

def initialize(opts = {})
  @host = opts[:host] || DEFAULT_HOST
  @port = opts[:port] || DEFAULT_PORT
  @ssl  = opts[:ssl] || false
end

Instance Attribute Details

#host ⇒ Object (readonly)

Returns the value of attribute host.



24
25
26
 
# File 'lib/meta/client.rb', line 24

def host
  @host
end

#port ⇒ Object (readonly)

Returns the value of attribute port.



24
25
26
 
# File 'lib/meta/client.rb', line 24

def port
  @port
end

#ssl ⇒ Object (readonly)

Returns the value of attribute ssl.



24
25
26
 
# File 'lib/meta/client.rb', line 24

def ssl
  @ssl
end

Instance Method Details

#delete_image(id) ⇒ Hash

Removes an image record based on its _id and returns its metadata.

Examples:

Delete an image metadata:

# wanted image _id
id = "2373c3e5-b302-4529-8e23-c4ffc85e7613"
# delete the image metadata, which returns it as it was before deletion
client.delete_image(id)

Parameters:

  • id (String) —

    The image’s _id which will be deleted.

Returns:

  • (Hash) —

    The already deleted image metadata. This is useful for recover on accidental delete.

Raises:

  • (NotFound) —

    If required image was not found.



220
221
222
223
 
# File 'lib/meta/client.rb', line 220

def delete_image(id)
  request = Net::HTTP::Delete.new("/images/#{id}")
  do_request(request)
end

#get_image(id) ⇒ Hash

Retrieves detailed image metadata of the image with the given id.

Examples:

Retrieve the image metadata with _id value:

# wanted image _id
id = "5e47a41e-7b94-4f65-824e-28f94e15bc6a"
# ask for that image metadata
client.get_image(id)

  # return example:
  {
     :_id          => "2cceffc6-ebc5-4741-9653-745524e7ac30",
     :name         => "Ubuntu 10.10",
     :architecture => "x86_64",
     :access       => "public",
     :uri          => "http://0.0.0.0:4567/images/2cceffc6-ebc5-4741-9653-745524e7ac30",
     :format       => "iso",
     :status       => "available",
     :store        => "file"
  }

Parameters:

  • id (String) —

    The wanted image’s _id.

Returns:

  • (Hash) —

    The requested image metadata.

Raises:

  • (NotFound) —

    If image not found.



140
141
142
143
 
# File 'lib/meta/client.rb', line 140

def get_image(id)
  request = Net::HTTP::Get.new("/images/#{id}")
  do_request(request)
end

#get_images(query = {}) ⇒ Array

Retrieves brief metadata of all public images. Options for filtering the returned results can be passed in.

Examples:

Retrieve all public images brief metadata:

client.get_images

  # returns:
  [<all images brief metadata>]

Retrieve all public 32bit images brief metadata:

client.get_images(architecture: 'i386')

  # returns something like:
  [
    {:_id => "28f94e15...", :architecture => "i386", :name => "Fedora 16"},
    {:_id => "8cb55bb6...", :architecture => "i386", :name => "Ubuntu 11.10 Desktop"}
  ]

Retrieve all public 64bit images brief metadata, descending sorted by their name:

client.get_images(architecture: 'x86_64', sort: 'name', dir: 'desc')

  # returns something like:
  [
    {:_id => "5e47a41e...", :architecture => "x86_64", :name => "Ubuntu 10.04 Server"},
    {:_id => "069320f0...", :architecture => "x86_64", :name => "CentOS 6"}
  ]

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :attribute (String) —

    The image attribute value to filter returned results.

  • :sort (String) — default: "_id" —

    The image attribute to sort returned results.

  • :dir (String) — default: "asc" —

    The direction to sort results (“asc”/“desc”).

Returns:

  • (Array) —

    All public images brief metadata. Just BRIEF fields are returned.

Raises:

  • (NotFound) —

    If there are no public images registered on the server.



83
84
85
86
87
 
# File 'lib/meta/client.rb', line 83

def get_images(query = {})
  str     = build_query(query)
  request = Net::HTTP::Get.new("/images#{str}")
  do_request(request)
end

#get_images_detail(query = {}) ⇒ Array

Retrieves detailed metadata of all public images.

Filtering and querying works the same as with #get_images. The only difference is the number of disclosed attributes.

Examples:

Retrieve all public images detailed metadata:

# request for it
client.get_images_detail
# returns an array of hashes with all public images metadata.

Parameters:

  • query (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (query):

  • :attribute (String) —

    The image attribute value to filter returned results.

  • :sort (String) — default: "_id" —

    The image attribute to sort returned results.

  • :dir (String) — default: "asc" —

    The direction to sort results (“asc”/“desc”).

Returns:

  • (Array) —

    All public images detailed metadata. The DETAIL_EXC fields are excluded from results.

Raises:

  • (NotFound) —

    If there are no public images registered on the server.



108
109
110
111
112
 
# File 'lib/meta/client.rb', line 108

def get_images_detail(query = {})
  str     = build_query(query)
  request = Net::HTTP::Get.new("/images/detail#{str}")
  do_request(request)
end

#post_image(meta) ⇒ Hash

Register a new image on the server with the given metadata and returns its metadata.

Examples:

Insert a sample image metadata:

# sample image metadata
meta = {name: 'example', architecture: 'i386', access: 'public'}
# insert the new image metadata
client.post_image(meta)

  # returns:
  { :_id=>"2373c3e5-b302-4529-8e23-c4ffc85e7613",
    :name=>"example",
    :architecture=>"i386",
    :access=>"public",
    :uri=>"http://0.0.0.0:4567/images/2373c3e5-b302-4529-8e23-c4ffc85e7613",
    :status=>"locked",
    :created_at=>"2011-12-13 19:19:26 UTC" }

Parameters:

  • meta (Hash) —

    The image metadata.

Returns:

  • (Hash) —

    The already inserted image metadata.

Raises:

  • (Invalid) —

    If image meta validation fails.



168
169
170
171
172
 
# File 'lib/meta/client.rb', line 168

def post_image(meta)
  request      = Net::HTTP::Post.new('/images')
  request.body = prepare_body(meta)
  do_request(request)
end

#put_image(id, meta) ⇒ Hash

Updates an image record with the given metadata and returns its metadata.

Examples:

Update a sample image metadata:

# wanted image _id
id = "2373c3e5-b302-4529-8e23-c4ffc85e7613"
# update the image metadata with some new values
client.put_image(id, name: 'update example')

  # returns:
  { :_id=>"2373c3e5-b302-4529-8e23-c4ffc85e7613",
    :name=>"update example",
    :architecture=>"i386",
    :access=>"public",
    :uri=>"http://0.0.0.0:4567/images/2373c3e5-b302-4529-8e23-c4ffc85e7613",
    :status=>"locked",
    :created_at=>"2011-12-13 19:19:26 UTC",
    :updated_at=>"2011-12-13 19:24:37 +0000" }

Parameters:

  • id (String) —

    The image’s _id which will be updated.

  • meta (Hash) —

    The image metadata.

Returns:

  • (Hash) —

    The already updated image metadata.

Raises:

  • (Invalid) —

    If image meta validation fails.

  • (NotFound) —

    If required image was not found.



200
201
202
203
204
 
# File 'lib/meta/client.rb', line 200

def put_image(id, meta)
  request      = Net::HTTP::Put.new("/images/#{id}")
  request.body = prepare_body(meta)
  do_request(request)
end