visor-meta 0.0.1

data/lib/meta/client.rb

@@ -0,0 +1,313 @@
+require 'net/http'
+require 'net/https'
+require 'uri'
+require 'json'
+
+module Visor
+  module Meta
+
+    # 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.
+    #
+    class Client
+
+      include Visor::Common::Exception
+
+      configs = Common::Config.load_config :visor_meta
+
+      DEFAULT_HOST = configs[:bind_host] || '0.0.0.0'
+      DEFAULT_PORT = configs[:bind_port] || 4567
+
+      attr_reader :host, :port, :ssl
+
+      # Initializes a new new VISoR Meta Client.
+      #
+      # @option opts [String] :host (DEFAULT_HOST) The host address where VISoR meta server resides.
+      # @option opts [String] :port (DEFAULT_PORT) The host port where VISoR meta server resides.
+      # @option opts [String] :ssl (false) If the connection should be made through HTTPS (SSL).
+      #
+      # @example Instantiate a client with default values:
+      #   client = Visor::Meta::Client.new
+      #
+      # @example Instantiate a client with default values and SSL enabled:
+      #   client = Visor::Meta::Client.new(ssl: true)
+      #
+      # @example Instantiate a client with custom host and port:
+      #   client = Visor::Meta::Client.new(host: '127.0.0.1', port: 3000)
+      #
+      def initialize(opts = {})
+        @host = opts[:host] || DEFAULT_HOST
+        @port = opts[:port] || DEFAULT_PORT
+        @ssl  = opts[:ssl] || false
+      end
+
+      # Retrieves brief metadata of all public 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:
+      #   client.get_images
+      #
+      #     # returns:
+      #     [<all images brief metadata>]
+      #
+      # @example 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"}
+      #     ]
+      #
+      # @example 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"}
+      #     ]
+      #
+      # @return [Array] All public 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.
+      #
+      def get_images(query = {})
+        str     = build_query(query)
+        request = Net::HTTP::Get.new("/images#{str}")
+        do_request(request)
+      end
+
+      # 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.
+      #
+      # @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 detailed metadata:
+      #   # request for it
+      #   client.get_images_detail
+      #   # returns an array of hashes with all public images metadata.
+      #
+      # @return [Array] All public 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.
+      #
+      def get_images_detail(query = {})
+        str     = build_query(query)
+        request = Net::HTTP::Get.new("/images/detail#{str}")
+        do_request(request)
+      end
+
+      # Retrieves detailed image metadata of the image with the given id.
+      #
+      # @param id [String] The wanted image's _id.
+      #
+      # @example 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"
+      #     }
+      #
+      # @return [Hash] The requested image metadata.
+      #
+      # @raise [NotFound] If image not found.
+      #
+      def get_image(id)
+        request = Net::HTTP::Get.new("/images/#{id}")
+        do_request(request)
+      end
+
+      # Register a new image on the server with the given metadata and returns its metadata.
+      #
+      # @param meta [Hash] The image metadata.
+      #
+      # @example 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" }
+      #
+      # @return [Hash] The already inserted image metadata.
+      #
+      # @raise [Invalid] If image meta validation fails.
+      #
+      def post_image(meta)
+        request      = Net::HTTP::Post.new('/images')
+        request.body = prepare_body(meta)
+        do_request(request)
+      end
+
+      # Updates an image record with the given metadata and returns its metadata.
+      #
+      # @param id [String] The image's _id which will be updated.
+      # @param meta [Hash] The image metadata.
+      #
+      # @example 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" }
+      #
+      # @return [Hash] The already updated image metadata.
+      #
+      # @raise [Invalid] If image meta validation fails.
+      # @raise [NotFound] If required image was not found.
+      #
+      def put_image(id, meta)
+        request      = Net::HTTP::Put.new("/images/#{id}")
+        request.body = prepare_body(meta)
+        do_request(request)
+      end
+
+      # Removes an image record based on its _id and returns its metadata.
+      #
+      # @param id [String] The image's _id which will be deleted.
+      #
+      # @example 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)
+      #
+      # @return [Hash] The already deleted image metadata. This is useful for recover on accidental delete.
+      #
+      # @raise [NotFound] If required image was not found.
+      #
+      def delete_image(id)
+        request = Net::HTTP::Delete.new("/images/#{id}")
+        do_request(request)
+      end
+
+      private
+
+      # Parses a response body with the JSON parser and extracts and returns a single
+      # key value from it if defined, otherwise returns all the body.
+      #
+      # @param key (nil) [Symbol] The hash key to extract the wanted value.
+      # @param response [Net::HTTPResponse] The response which contains the body to parse.
+      #
+      # @return [String, Hash] If key is provided and exists on the response body, them return
+      #   its value, otherwise return all the body hash.
+      #
+      def parse(key=nil, response)
+        parsed = JSON.parse(response.body, symbolize_names: true)
+        key ? parsed[key] : parsed
+      end
+
+      # Generate a valid URI query string from key/value pairs of the given hash.
+      #
+      # @param opts [Hash] The hash with the key/value pairs to generate query from.
+      #
+      # @return [String] The generated query in the form of "?k=v&k1=v1".
+      #
+      def build_query(opts)
+        opts.empty? ? '' : '?' + URI.encode_www_form(opts)
+      end
+
+      # Fill common header keys before each request. This sets the 'User-Agent' and 'Accept'
+      # headers for every request and additionally sets the 'content-type' header
+      # for POST and PUT requests.
+      #
+      # @param request [Net::HTTPResponse] The request which will be modified in its headers.
+      #
+      def prepare_headers(request)
+        request['User-Agent'] = 'VISoR meta server'
+        request['Accept']     = 'application/json'
+        request['content-type'] = 'application/json' if ['POST', 'PUT'].include?(request.method)
+      end
+
+      # Generate a valid JSON request body for POST and PUT requests.
+      # It generates a JSON object encapsulated inside a :image key and then returns it.
+      #
+      # @param hash [Hash] The hash with the key/value pairs to generate a JSON object from.
+      #
+      # @return [Hash] If an :image key is already present in the hash, it just returns the plain
+      #   JSON object, otherwise, encapsulate the hash inside a :image key and returns it.
+      #
+      def prepare_body(hash)
+        hash.has_key?(:image) ? meta.to_json : {image: hash}.to_json
+      end
+
+      # Process requests by preparing its headers, launch them and assert or raise their response.
+      #
+      # @param request [Net::HTTPResponse] The request which will be launched.
+      #
+      # @return [String, Hash] If an error is raised, then it parses and returns its message,
+      #   otherwise it properly parse and return the response body.
+      #
+      # @raise [NotFound] If required image was not found (on a GET, PUT or DELETE request).
+      # @raise [Invalid] If image meta validation fails (on a POST or PUT request).
+      #
+      def do_request(request)
+        prepare_headers(request)
+        response = http_or_https.request(request)
+        case response
+        when Net::HTTPNotFound then
+          raise NotFound, parse(:message, response)
+        when Net::HTTPBadRequest then
+          raise Invalid, parse(:message, response)
+        else
+          parse(:image, response) or parse(:images, response)
+        end
+      end
+
+      # Generate a new HTTP or HTTPS connection based on initialization parameters.
+      #
+      # @return [Net::HTTP] A HTTP or HTTPS (not done yet) connection ready to use.
+      #
+      def http_or_https
+        if @ssl
+          #TODO: ssl connection
+          #https://github.com/augustl/net-http-cheat-sheet/blob/master/ssl_and_https.rb
+        else
+          Net::HTTP.new(@host, @port)
+        end
+      end
+
+    end
+  end
+end

data/lib/meta/server.rb

@@ -0,0 +1,295 @@
+require 'sinatra/base'
+require 'json'
+require 'uri'
+
+module Visor
+  module Meta
+
+    # The VISoR Meta Server class. This class supports all image metadata manipulation
+    # operations through the VISoR REST API implemented along the following routes.
+    #
+    # After initialize the Server its possible to directly interact with the meta backend.
+    #
+    class Server < Sinatra::Base
+      include Visor::Common::Exception
+      include Visor::Common::Config
+
+      # Configuration
+      #
+      configure do
+        backend_map = {'mongodb' => Visor::Meta::Backends::MongoDB,
+                       'mysql'   => Visor::Meta::Backends::MySQL}
+
+        conf = Visor::Common::Config.load_config(:visor_meta)
+        log  = Visor::Common::Config.build_logger(:visor_meta)
+
+        DB = backend_map[conf[:backend].split(':').first].connect uri: conf[:backend]
+
+        #enable :threaded
+        disable :show_exceptions, :logging #, :protection
+
+        use Rack::CommonLogger, log
+      end
+
+      #configure :development do
+        #require 'sinatra/reloader'
+        #register Sinatra::Reloader
+      #end
+
+      # Helpers
+      #
+      helpers do
+        def json_error(code, message)
+          error code, {code: code, message: message}.to_json
+        end
+      end
+
+      # Filters
+      #
+      before do
+        @parse_opts = {symbolize_names: true}
+        content_type :json
+      end
+
+      # Routes
+      #
+
+      # @method get_all_brief
+      # @overload get '/images'
+      #
+      # Get brief information about all public images.
+      #
+      #   { "images": [{
+      #       "_id":<_id>,
+      #       "uri":<uri>,
+      #       "name":<name>,
+      #       "architecture":<architecture>,
+      #       "type":<type>,
+      #       "format":<format>,
+      #       "store":<type>,
+      #       "size":<size>,
+      #       "created_at":<creation timestamp>
+      #       }, ...]}
+      #
+      # The following options can be passed as query parameters, plus any other additional
+      # image attribute not defined in the schema.
+      #
+      # @param [String] name The image name.
+      # @param [String] architecture The image architecture.
+      # @param [String] type The image type.
+      # @param [String] format The image format.
+      # @param [String] store The image store.
+      # @param [Fixnum] size The image size.
+      # @param [Date] created_at The image creation timestamp.
+      # @param [String] sort ('_id') The image attribute to sort results.
+      # @param [String] dir ('asc') The sorting order ('asc'/'desc').
+      #
+      # @return [JSON] The public images brief metadata.
+      #
+      # @raise [HTTP Error 404] If there is no public images.
+      #
+      get '/images' do
+        begin
+          images = DB.get_public_images(true, params)
+          {images: images}.to_json
+        rescue NotFound => e
+          json_error 404, e.message
+        rescue => e
+          json_error 500, e.message
+        end
+      end
+
+      # @method get_all_detail
+      # @overload get '/images/detail'
+      #
+      # Get detailed information about all public images.
+      #
+      #   {"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.
+      #
+      # @param [String] name The image name.
+      # @param [String] architecture The image architecture.
+      # @param [String] access The image access permission.
+      # @param [String] type The image type.
+      # @param [String] format The image format.
+      # @param [String] store The image store.
+      # @param [Fixnum] size The image size.
+      # @param [Date] created_at The image creation timestamp.
+      # @param [Date] updated_at The image update timestamp.
+      # @param [String] kernel The image associated kernel image's _id.
+      # @param [String] ramdisk The image associated kernel image's _id.
+      # @param [String] sort (_id) The image attribute to sort results.
+      # @param [String] dir ('asc') The sorting order ('asc'/'desc').
+      #
+      # @return [JSON] The public images detailed metadata.
+      #
+      # @raise [HTTP Error 404] If there is no public images.
+      #
+      get '/images/detail' do
+        begin
+          images = DB.get_public_images(false, params)
+          {images: images}.to_json
+        rescue NotFound => e
+          json_error 404, e.message
+        rescue => e
+          json_error 500, e.message
+        end
+      end
+
+      # @method get_detail
+      # @overload get '/images/:id'
+      #
+      # Get detailed information about a specific image.
+      #
+      #   {"image": {
+      #       "_id":<_id>,
+      #       "uri":<uri>,
+      #       "name":<name>,
+      #       "architecture":<architecture>,
+      #       "access":<access>,
+      #       "status":<status>,
+      #       "size":<size>,
+      #       "type":<type>,
+      #       "format":<format>,
+      #       "store":<type>,
+      #       "created_at":<creation timestamp>
+      #       "updated_at":<update timestamp>,
+      #       "kernel":<associated kernel>,
+      #       "ramdisk":<associated ramdisk>,
+      #       ...
+      #   }}
+      #
+      # @param [String] id The wanted image _id.
+      #
+      # @return [JSON] The image detailed metadata.
+      #
+      # @raise [HTTP Error 404] If image not found.
+      #
+      get '/images/:id' do |id|
+        begin
+          image = DB.get_image(id)
+          {image: image}.to_json
+        rescue NotFound => e
+          json_error 404, e.message
+        rescue => e
+          json_error 500, e.message
+        end
+      end
+
+      # @method post
+      # @overload post '/images'
+      #
+      # Create a new image metadata and returns it.
+      #
+      # @param [JSON] http-body The image metadata.
+      #
+      # @return [JSON] The already created image detailed metadata.
+      #
+      # @raise [HTTP Error 400] Image metadata validation errors.
+      #
+      post '/images' do
+        begin
+          meta  = JSON.parse(request.body.read, @parse_opts)
+          image = DB.post_image(meta[:image])
+          {image: image}.to_json
+        rescue NotFound => e
+          json_error 404, e.message
+        rescue ArgumentError => e
+          json_error 400, e.message
+        rescue => e
+          json_error 500, e.message
+        end
+      end
+
+      # @method put
+      # @overload put '/images/:id'
+      #
+      # Update an existing image metadata and return it.
+      #
+      # @param [String] id The wanted image _id.
+      # @param [JSON] http-body The image metadata.
+      #
+      # @return [JSON] The already updated image detailed metadata.
+      #
+      # @raise [HTTP Error 400] Image metadata update validation errors.
+      #
+      put '/images/:id' do |id|
+        begin
+          meta  = JSON.parse(request.body.read, @parse_opts)
+          image = DB.put_image(id, meta[:image])
+          {image: image}.to_json
+        rescue NotFound => e
+          json_error 404, e.message
+        rescue ArgumentError => e
+          json_error 400, e.message
+        rescue => e
+          json_error 500, e.message
+        end
+      end
+
+      # @method delete
+      # @overload delete '/images/:id'
+      #
+      # Delete an image metadata and returns it.
+      #
+      # @param [String] id The image _id to delete.
+      #
+      # @return [JSON] The already deleted image detailed metadata.
+      #
+      # @raise [HTTP Error 404] If image not found.
+      #
+      delete '/images/:id' do
+        begin
+          image = DB.delete_image(params[:id])
+          {image: image}.to_json
+        rescue NotFound => e
+          json_error 404, e.message
+        rescue => e
+          json_error 500, e.message
+        end
+      end
+
+      # misc handlers: error, not_found, etc.
+      get "*" do
+        json_error 404, 'Invalid operation or path.'
+      end
+
+      put "*" do
+        json_error 404, 'Invalid operation or path.'
+      end
+
+      post "*" do
+        json_error 404, 'Invalid operation or path.'
+      end
+
+      delete "*" do
+        json_error 404, 'Invalid operation or path.'
+      end
+
+      error do
+        json_error 500, env['sinatra.error'].message
+      end
+
+    end
+  end
+end
+
+

data/lib/meta/version.rb

@@ -0,0 +1,5 @@
+module Visor
+  module Meta
+    VERSION = "0.0.1"
+  end
+end

data/lib/visor-meta.rb

@@ -0,0 +1,12 @@
+require 'visor-common'
+
+$:.unshift File.expand_path('../../lib', __FILE__)
+require 'meta/version'
+require 'meta/backends/base'
+require 'meta/backends/mongo_db'
+require 'meta/backends/mysql_db'
+require 'meta/server'
+require 'meta/client'
+require 'meta/cli'
+
+