Class: Visor::Image::Server

Inherits:

Goliath::API

Object
Goliath::API
Visor::Image::Server

Defined in:: lib/image/server.rb

Overview

The VISoR Image Server. This supports all image metadata manipulation operations, dispatched to the VISoR Meta Server and the image files storage operations.

*The Server API is a RESTful web service for image meta as follows:*

HEAD    /images/<id>    - Returns metadata about the image with the given id
GET     /images         - Returns a set of brief metadata about all public images
GET     /images/detail  - Returns a set of detailed metadata about all public images
GET     /images/<id>    - Returns image data and metadata for the image with the given id
POST    /images         - Stores a new image data and metadata and returns the registered metadata
PUT     /images/<id>    - Update image metadata and/or data for the image with the given id
DELETE  /images/<id>    - Delete the metadata and data of the image with the given id

The Image is multi-format, most properly it supports response encoding in JSON and XML formats. It will auto negotiate and encode the response metadata and error messages in the proper format, based on the request Accept header, being it ‘application/json’ or ‘application/xml’. If no Accept header is provided, Image will encode and render it as JSON by default.

This server routes all metadata operations to the Visor Meta Server.

The server will interact with the multiple supported backend store to manage the image files.

*Currently we support the following store backend and operations:*

Amazon Simple Storage (s3)  - GET, POST, PUT, DELETE
Nimbus Cumulus (cumulus)    - GET, POST, PUT, DELETE
Eucalyptus Walrus (walrus)  - GET, POST, PUT, DELETE
Local Filesystem (file)     - GET, POST, PUT, DELETE
Remote HTTP (http)          - GET

Instance Method Summary collapse

#delete('/images/: id') ⇒ JSON, XML

Delete the metadata and data of the image with the given id, see DeleteImage.
#get('/images') ⇒ JSON, XML

Get brief information about all public images, see GetImages.
#get('/images/detail') ⇒ JSON, XML

Get detailed information about all public images, see GetImagesDetail.
#get('/images/: id') ⇒ HTTP Headers, HTTP Body

Get image data and detailed metadata for the given id, see GetImage.
#head('/image/: id') ⇒ HTTP Headers

Head metadata about the image with the given id, see HeadImage.
#post('/images') ⇒ JSON, XML

Post image data and metadata and returns the registered metadata, see PostImage.
#put('/images/: id') ⇒ JSON, XML

Put image metadata and/or data for the image with the given id, see PutImage.

Instance Method Details

#delete('/images/: id') ⇒ `JSON`, `XML`

Delete the metadata and data of the image with the given id, see DeleteImage.

Examples:

Delete the image with id ‘19b39ed6-6c43-41cc-8d59-d1a1ed24ac9d’:

'DELETE /images/19b39ed6-6c43-41cc-8d59-d1a1ed24ac9d'

Parameters:

id (String) —

The image _id to delete.

Returns:

(JSON, XML) —

The already deleted image detailed metadata.

Raises:

(HTTP Error 404) —

If image meta or data not found.
(HTTP Error 403) —

If user does not have permission to manipulate the image file.
(HTTP Error 500) —

On internal server error.

296	# File 'lib/image/server.rb', line 296 delete '/images/:id', DeleteImage

#get('/images') ⇒ `JSON`, `XML`

Get brief information about all public images, see GetImages.

{ "images":
  [
    {
      "_id":<_id>,
      "uri":<uri>,
      "name":<name>,
      "architecture":<architecture>,
      "type":<type>,
      "format":<format>,
      "store":<type>,
      "size":<size>,
      "created_at":<timestamp>
    },
    ...
  ]
}

The following options can be passed as query parameters, plus any other additional image attribute not defined in the schema.

Examples:

Retrieve all public images brief metadata:

'GET /images'

Retrieve all public ‘x86_64` images brief metadata:

'GET /images?architecture=x86_64'

Retrieve all public ‘.iso` images brief metadata, descending sorted by `size`:

'GET /images?format=iso&sort=size&dir=desc'

Parameters:

parameter (String, Integer, Date) —

The image attribute to filter results based on its value.
sort (String) —

(“_id”) The image attribute to sort results.
dir (String) —

(“asc”) The sorting order (“asc”/“desc”).

Returns:

(JSON, XML) —

The public images brief metadata.

Raises:

(HTTP Error 404) —

If there is no public images.
(HTTP Error 500) —

On internal server error.

127	# File 'lib/image/server.rb', line 127 get '/images', GetImages

#get('/images/detail') ⇒ `JSON`, `XML`

Note:

Querying and ordering results are made as with #get_all_detail

Get detailed information about all public images, see GetImagesDetail.

{ "images":
  [
    {
      "_id":<_id>,
      "uri":<uri>,
      "name":<name>,
      "architecture":<architecture>,
      "access":<access>,
      "status":<status>,
      "size":<size>,
      "type":<type>,
      "format":<format>,
      "store":<store>,
      "created_at":<timestamp>
      "updated_at":<timestamp>,
      "kernel":<associated kernel>,
      "ramdisk":<associated ramdisk>,
    },
    ...
  ]
}

The following options can be passed as query parameters, plus any other additional image attribute not defined in the schema.

Examples:

Retrieve all public images detailed metadata:

'GET /images/detail'

Parameters:

parameter (String, Integer, Date) —

The image attribute to filter results based on its value.
sort (String) —

(“_id”) The image attribute to sort results.
dir (String) —

(“asc”) The sorting order (“asc”/“desc”).

Returns:

(JSON, XML) —

The public images detailed metadata.

Raises:

(HTTP Error 404) —

If there is no public images.
(HTTP Error 500) —

On internal server error.

174	# File 'lib/image/server.rb', line 174 get '/images/detail', GetImagesDetail

#get('/images/: id') ⇒ `HTTP Headers`, `HTTP Body`

Note:

Undefined attributes are ignored and not included into response’s header.

Get image data and detailed metadata for the given id, see GetImage.

The image data file is streamed as response’s body. The server will return a 200 status code, with a special HTTP header, indicating that the response body will be streamed in chunks and connection shouldn’t be closed until the transfer is complete.

Also, the image metadata is promptly passed as a set of HTTP headers, as the following example:

x-image-meta-_id:           <id>
x-image-meta-uri:           <uri>
x-image-meta-name:          <name>
x-image-meta-architecture:  <architecture>
x-image-meta-access:        <access>
x-image-meta-status:        <status>
x-image-meta-created_at:    <timestamp>

Examples:

Retrieve the image with id ‘19b39ed6-6c43-41cc-8d59-d1a1ed24ac9d’:

'GET /images/19b39ed6-6c43-41cc-8d59-d1a1ed24ac9d'

Parameters:

id (String) —

The wanted image _id.

Returns:

(HTTP Headers) —

The image data file.
(HTTP Body) —

The image data file.

Raises:

(HTTP Error 404) —

If image not found.
(HTTP Error 500) —

On internal server error.

209	# File 'lib/image/server.rb', line 209 get '/images/:id', GetImage

#head('/image/: id') ⇒ `HTTP Headers`

Note:

Undefined attributes are ignored and not included into response’s header. Also any raised error will be passed through HTTP headers as expected.

Head metadata about the image with the given id, see HeadImage.

The image metadata is promptly passed as a set of HTTP headers, as the following example:

x-image-meta-_id:           <id>
x-image-meta-uri:           <uri>
x-image-meta-name:          <name>
x-image-meta-architecture:  <architecture>
x-image-meta-access:        <access>
x-image-meta-status:        <status>
x-image-meta-created_at:    <timestamp>

Examples:

Retrieve the image metadata with id ‘19b39ed6-6c43-41cc-8d59-d1a1ed24ac9d’:

'HEAD /images/19b39ed6-6c43-41cc-8d59-d1a1ed24ac9d'

Parameters:

id (String) —

The wanted image _id.

Returns:

(HTTP Headers) —

The image data file.

Raises:

(HTTP Error 404) —

If image not found.
(HTTP Error 500) —

On internal server error.

81	# File 'lib/image/server.rb', line 81 head '/images/:id', HeadImage

#post('/images') ⇒ `JSON`, `XML`

Post image data and metadata and returns the registered metadata, see PostImage.

The image metadata should be encoded as HTTP headers and passed with the request, as the following example:

x-image-meta-name:          Ubuntu 10.10 Desktop
x-image-meta-architecture:  i386
x-image-meta-store:         s3

If wanted, the image data file should be streamed through the request body. The server will receive that data in chunks, buffering them to a properly secured temporary file, avoiding buffering all the data into memory. Server will then handle the upload of that data to the definitive store location, cleaning then the generated temporary file.

Alternatively, a x-image-meta-location header can be passed, if the file is already stored in some provided location. If this header is present, no body content can be passed in the request.

Returns:

(JSON, XML) —

The already created image detailed metadata.

Raises:

(HTTP Error 400) —

If the image metadata validation fails.
(HTTP Error 400) —

If the location header is present no file content can be provided.
(HTTP Error 400) —

If trying to post an image file to a HTTP backend.
(HTTP Error 400) —

If provided store is an unsupported store backend.
(HTTP Error 404) —

If no image data is found at the provided location.
(HTTP Error 409) —

If the provided image file already exists in the backend store.
(HTTP Error 500) —

On internal server error.

241	# File 'lib/image/server.rb', line 241 post '/images', PostImage

#put('/images/: id') ⇒ `JSON`, `XML`

Note:

Only images with status set to ‘locked’ or ‘error’ can be updated with an image data file.

Put image metadata and/or data for the image with the given id, see PutImage.

The image metadata should be encoded as HTTP headers and passed with the request, as the following example:

x-image-meta-name:          Ubuntu 10.10 Server
x-image-meta-architecture:  x86_64
x-image-meta-location:      http://www.ubuntu.com/start-download?distro=server&bits=64&release=latest

Alternatively, a x-image-meta-location header can be passed, if the file is already stored in some provided location. If this header is present, no body content can be passed in the request.

Returns:

(JSON, XML) —

The already updated image detailed metadata.

Raises:

(HTTP Error 400) —

If the image metadata validation fails.
(HTTP Error 400) —

If no headers neither body found for update.
(HTTP Error 400) —

If the location header is present no file content can be provided.
(HTTP Error 400) —

If trying to post an image file to a HTTP backend.
(HTTP Error 400) —

If provided store is an unsupported store backend.
(HTTP Error 404) —

If no image data is found at the provided location.
(HTTP Error 409) —

If trying to assign image file to a locked or uploading image.
(HTTP Error 409) —

If the provided image file already exists in the backend store.
(HTTP Error 500) —

On internal server error.

277	# File 'lib/image/server.rb', line 277 put '/images/:id', PutImage

Class: Visor::Image::Server

Overview

Instance Method Summary collapse

Instance Method Details

#delete('/images/: id') ⇒ JSON, XML

#get('/images') ⇒ JSON, XML

#get('/images/detail') ⇒ JSON, XML

#get('/images/: id') ⇒ HTTP Headers, HTTP Body

#head('/image/: id') ⇒ HTTP Headers

#post('/images') ⇒ JSON, XML

#put('/images/: id') ⇒ JSON, XML

#delete('/images/: id') ⇒ `JSON`, `XML`

#get('/images') ⇒ `JSON`, `XML`

#get('/images/detail') ⇒ `JSON`, `XML`

#get('/images/: id') ⇒ `HTTP Headers`, `HTTP Body`

#head('/image/: id') ⇒ `HTTP Headers`

#post('/images') ⇒ `JSON`, `XML`

#put('/images/: id') ⇒ `JSON`, `XML`