deltacloud-client 1.1.2 → 1.1.3

data/README.md

@@ -0,0 +1,73 @@
+# deltacloud-client
+
+The Deltacloud project includes a Ruby client.  Other language-bindings
+are possible and will be supported soon.  The client aims to insulate
+users from having to deal with HTTP and REST directly.
+
+Each resource type has an associated model to ease usage.  Where
+resource reference other resources, natural navigation across the
+object model is possible.
+
+This is a Ruby client library for the [Deltacloud API](http://deltacloud.apache.org).
+
+## Usage
+
+```ruby
+require 'deltacloud/client'
+
+API_URL = "http://localhost:3001/api" # Deltacloud API endpoint
+
+# Simple use-cases
+client = Deltacloud::Client(API_URL, 'mockuser', 'mockpassword')
+
+pp client.instances           # List all instances
+pp client.instance('i-12345') # Get one instance
+
+inst = client.create_instance 'ami-1234', :hwp_id => 'm1.small' # Create instance
+
+inst.reboot!  # Reboot instance
+
+# Advanced usage
+
+# Deltacloud API supports changing driver per-request:
+
+client.use(:ec2, 'API_KEY', 'API_SECRET').instances # List EC2 instances
+client.use(:openstack, 'admin@tenant', 'password', KEYSTONE_URL).instances # List Openstack instances
+
+```
+# Want help?
+
+## Adding new Deltacloud collection to client
+
+```
+$ rake generate[YOUR_COLLECTION] # eg. 'storage_snapshot'
+# Hit Enter 2x
+```
+
+- Edit `lib/deltacloud/client/methods/YOUR_COLLECTION.rb` and add all
+  methods for manipulating your collection. The list/show methods
+  should already be generated for you, but double-check them.
+
+- Edit `lib/deltacloud/client/model/YOUR_COLLECTION.rb` and add model
+  methods. Model methods should really be just a syntax sugar and exercise
+  the *Deltacloud::Client::Methods* methods.
+  The purpose of *model* class life is to deserialize XML body received
+  from Deltacloud API to a Ruby class.
+
+## Debugging a nasty bug?
+
+- You can easily debug deltacloud-client using powerful **pry**.
+
+  - `gem install deltacloud-core`
+  - optional: `rbenv rehash` ;-)
+  - `deltacloudd -i mock -p 3002`
+  - `rake console`
+
+Console require **pry** gem installed. If you are not using this awesome
+gem, you can fix it by `gem install pry`.
+
+# License
+
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/

data/Rakefile

@@ -1,4 +1,3 @@
-#
 # Licensed to the Apache Software Foundation (ASF) under one or more
 # contributor license agreements.  See the NOTICE file distributed with
 # this work for additional information regarding copyright ownership.  The
@@ -14,26 +13,110 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
+require 'rubygems'
 require 'rubygems/package_task'
+require 'rake'
 require 'rake/testtask'
 
-load 'deltacloud-client.gemspec'
-
 spec = Gem::Specification.load('deltacloud-client.gemspec')
 
 Gem::PackageTask.new(spec) do |pkg|
   pkg.need_tar = true
 end
 
-desc "Re-install the deltacloud-client gem"
+desc "Re-install the deltacloud-client gem (used for development)"
 task :reinstall do
   puts %x{gem uninstall deltacloud-client --all -I -x}
   puts %x{gem build deltacloud-client.gemspec}
   puts %x{gem install deltacloud-client-*.gem --local}
 end
 
+desc 'Generate model/methods files for collection.'
+task :generate, :name do |t, args|
+  require 'erb'
+  require_relative './lib/deltacloud/core_ext'
+  model_tpl = ERB.new(File.read('support/model_template.erb'))
+  methods_tpl = ERB.new(File.read('support/methods_template.erb'))
+  name = args[:name]
+  model_file = "lib/deltacloud/client/models/#{name}.rb"
+  methods_file = "lib/deltacloud/client/methods/#{name}.rb"
+  puts model_body = model_tpl.result(binding)
+  print "Save model to '#{model_file}'? [Y/n]"
+  answer = $stdin.gets.chomp
+  if answer.empty? or answer == 'Y'
+    File.open(model_file, 'w') { |f|
+      f.write(model_body)
+    }
+    File.open('lib/deltacloud/client/models.rb', 'a') { |f|
+      f.puts "require_relative './models/#{name}'"
+    }
+  end
+  puts methods_body = methods_tpl.result(binding)
+  print "Save methods to '#{methods_file}'? [Y/n]"
+  answer = $stdin.gets.chomp
+  if answer.empty? or answer == 'Y'
+    File.open(methods_file, 'w') { |f|
+      f.write(methods_body)
+    }
+    File.open('lib/deltacloud/client/methods.rb', 'a') { |f|
+      f.puts "require_relative './methods/#{name}'"
+    }
+  end
+  puts
+  puts "Don't forget to add this line to 'lib/deltacloud/client/connection.rb':"
+  puts
+  puts "include Deltacloud::Client::Methods::#{name.to_s.camelize}"
+  puts
+end
+
+desc 'Generate method test file'
+task :test_generate, :name do |t, args|
+  require 'erb'
+  require_relative './lib/deltacloud/core_ext'
+  method_tpl = ERB.new(File.read('support/method_test_template.erb'))
+  name = args[:name]
+  methods_file = "tests/methods/#{name}_test.rb"
+  puts method_body = method_tpl.result(binding)
+  print "Save method test to '#{methods_file}'? [Y/n]"
+  answer = $stdin.gets.chomp
+  if answer.empty? or answer == 'Y'
+    File.open(methods_file, 'w') { |f|
+      f.write(method_body)
+    }
+  end
+end
+
+
+desc "Open console with client connected to #{ENV['API_URL'] || 'localhost:3002/api'}"
+task :console do
+  require 'pry'
+  unless binding.respond_to? :pry
+    puts 'To open a console, you need to have "pry" installed (gem install pry)'
+    exit(1)
+  end
+  require_relative './lib/deltacloud/client'
+  client = Deltacloud::Client(
+    ENV['API_URL'] || 'http://localhost:3002/api',
+    ENV['API_USER'] || 'mockuser',
+    ENV['API_PASSWORD'] || 'mockpassword'
+  )
+  binding.pry
+end
+
 Rake::TestTask.new(:test) do |t|
   t.test_files = FileList[
-    'tests/*test.rb',                     # EC2 frontend internal API tests
+    'tests/*/*_test.rb'
   ]
 end
+
+desc "Execute test against live Deltacloud API"
+task :test_live do
+  ENV['NO_VCR'] = 'true'
+  Rake::Task[:test].invoke
+end
+
+desc "Generate test coverage report"
+task :coverage do
+  ENV['COVERAGE'] = 'true'
+  Rake::Task[:test].invoke
+end

data/lib/deltacloud/client.rb

@@ -0,0 +1,79 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+module Deltacloud
+  module Client
+    require 'require_relative' if RUBY_VERSION < '1.9'
+    require 'ostruct'
+    require 'nokogiri'
+    require 'faraday'
+    require 'base64'
+
+    # Core extensions
+    require_relative './core_ext'
+
+    # Errors && Helpers
+    require_relative './client/helpers/model_helper'
+    require_relative './client/helpers/xml_helper'
+    require_relative './client/helpers/property_helper'
+
+    # Exceptions goes here
+    require_relative './client/base_error'
+
+    # Faraday Middleware for Deltacloud errors
+    require_relative './error_response'
+
+    # Deltacloud API methods
+    require_relative './client/methods/api'
+    require_relative './client/methods/backward_compatiblity'
+
+    # Extend Client module with methods that existed in old client
+    # that need to be kept.
+    # Deprecation warnings should be provided to users if they use something
+    # from these modules.
+    #
+    extend Deltacloud::Client::Methods::BackwardCompatibility::ClassMethods
+
+    # Deltacloud methods
+    require_relative './client/methods'
+
+    # Deltacloud models
+    require_relative './client/models'
+
+    require_relative './client/connection'
+
+    VERSION = '1.1.2'
+
+    # Check if the connection to Deltacloud API is valid
+    def self.valid_connection?(api_url)
+      begin
+        Deltacloud::Client(api_url, '', '') && true
+      rescue Faraday::Error::ConnectionFailed
+        false
+      rescue Deltacloud::Client::AuthenticationError
+        false
+      end
+    end
+
+  end
+
+  def self.Client(url, api_user, api_password, opts={})
+    Client::Connection.new({
+      :url => url,
+      :api_user => api_user,
+      :api_password => api_password
+    }.merge(opts))
+  end
+end

data/lib/deltacloud/client/base_error.rb

@@ -0,0 +1,80 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+module Deltacloud::Client
+
+  # Reporting internal client errors
+  #
+  class Error < StandardError; end
+
+  class BaseError < Error
+    attr_reader :server_backtrace
+    attr_reader :driver
+    attr_reader :provider
+    attr_reader :status
+    attr_reader :original_error
+
+    def initialize(opts={})
+      if opts.is_a? Hash
+        @server_backtrace = opts[:server_backtrace]
+        @driver = opts[:driver]
+        @provider = opts[:provider]
+        @status = opts[:status]
+        @original_error = opts[:original_error]
+        super(opts[:message])
+      else
+        super(opts)
+      end
+    end
+
+    # If the Deltacloud API server error response contain backtrace from
+    # server,then make this backtrace available as part of this exception
+    # backtrace
+    #
+    def set_backtrace(backtrace)
+      return super(backtrace) if @server_backtrace.nil?
+      super([
+        backtrace[0..3],
+        "-------Deltacloud API backtrace-------",
+        @server_backtrace.split[0..10],
+      ].flatten)
+    end
+
+  end
+
+  # Report 401 errors
+  class AuthenticationError < BaseError; end
+
+  # Report 502 errors (back-end cloud provider encounter error)
+  class BackendError < BaseError; end
+
+  # Report 5xx errors (error on Deltacloud API server)
+  class ServerError < BaseError; end
+
+  # Report 501 errors (collection or operation is not supported)
+  class NotSupported < ServerError; end
+
+  # Report 4xx failures (client failures)
+  class ClientFailure < BaseError; end
+
+  # Report 404 error (object not found)
+  class NotFound < BaseError; end
+
+  # Report 405 failures (resource state does not permit the requested operation)
+  class InvalidState < ClientFailure; end
+
+  # Report this when client do Image#launch using incompatible HWP
+  class IncompatibleHardwareProfile < ClientFailure; end
+end

data/lib/deltacloud/client/connection.rb

@@ -0,0 +1,139 @@
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.  The
+# ASF licenses this file to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance with the
+# License.  You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+module Deltacloud::Client
+  class Connection
+
+    attr_accessor :connection
+    attr_reader :request_driver
+    attr_reader :request_provider
+    attr_reader :entrypoint
+
+    include Deltacloud::Client::Helpers::Model
+
+    include Deltacloud::Client::Methods::Address
+    include Deltacloud::Client::Methods::Api
+    include Deltacloud::Client::Methods::BackwardCompatibility
+    include Deltacloud::Client::Methods::Blob
+    include Deltacloud::Client::Methods::Bucket
+    include Deltacloud::Client::Methods::Common
+    include Deltacloud::Client::Methods::Driver
+    include Deltacloud::Client::Methods::Firewall
+    include Deltacloud::Client::Methods::HardwareProfile
+    include Deltacloud::Client::Methods::Image
+    include Deltacloud::Client::Methods::Instance
+    include Deltacloud::Client::Methods::InstanceState
+    include Deltacloud::Client::Methods::Key
+    include Deltacloud::Client::Methods::Realm
+    include Deltacloud::Client::Methods::StorageSnapshot
+    include Deltacloud::Client::Methods::StorageVolume
+    include Deltacloud::Client::Methods::LoadBalancer
+    include Deltacloud::Client::Methods::Metric
+
+    def initialize(opts={})
+      @request_driver = opts[:driver]
+      @request_provider = opts[:provider]
+      @connection = Faraday.new(:url => opts[:url]) do |f|
+        # NOTE: The order of this is somehow important for VCR
+        #       recording.
+        f.request :url_encoded
+        f.headers = deltacloud_request_headers
+        f.basic_auth opts[:api_user], opts[:api_password]
+        f.use Deltacloud::ErrorResponse
+        f.adapter :net_http
+      end
+      cache_entrypoint!
+      @request_driver ||= current_driver
+      @request_provider ||= current_provider
+    end
+
+    # Change the current driver and return copy of the client
+    # This allows chained calls like: client.driver(:ec2).instances
+    #
+    # - driver_id -> The new driver id (:mock, :ec2, :rhevm, ...)
+    # - api_user -> API user name
+    # - api_password -> API password
+    # - api_provider -> API provider (aka API_PROVIDER string)
+    #
+    def use(driver_id, api_user, api_password, api_provider=nil, &block)
+      new_client = self.class.new(
+        :url => @connection.url_prefix.to_s,
+        :api_user => api_user,
+        :api_password => api_password,
+        :provider => api_provider,
+        :driver => driver_id
+      )
+      new_client.cache_entrypoint!
+      yield new_client if block_given?
+      new_client
+    end
+
+    # Change the API provider but keep the current client credentials.
+    # This allows to change the EC2 region and list instances in that
+    # region without need to supply credentials.
+    #
+    # client.use_provider('eu-west-1') { |p| p.instances }
+    #
+    # - provider_id -> API provider (aka API_PROVIDER)
+    #
+    def use_provider(provider_id, &block)
+      new_client = self.clone
+      new_connection = @connection.clone
+      new_connection.headers['X-Deltacloud-Provider'] = provider_id
+      new_client.connection = new_connection
+      new_client.cache_entrypoint!(true)
+      yield new_client if block_given?
+      new_client
+    end
+
+    # Cache the API entrypoint (/api) for the current connection,
+    # so we don't need to query /api everytime we ask if certain
+    # collection/operation is supported
+    #
+    # - force -> If 'true' force to refresh stored cached entrypoint
+    #
+    def cache_entrypoint!(force=false)
+      @entrypoint = nil if force
+      @entrypoint ||= connection.get(path).body
+    end
+
+    # Check if the credentials used are valid for the current @connection
+    #
+    def valid_credentials?
+      begin
+        r = connection.get(path, { :force_auth => 'true' })
+        r.status == 200
+      rescue error(:authentication_error)
+        false
+      end
+    end
+
+    private
+
+    # Default Deltacloud HTTP headers. Common for *all* requests
+    # to Deltacloud API
+    #
+    def deltacloud_request_headers
+      headers = {}
+      headers['Accept'] = 'application/xml'
+      headers['X-Deltacloud-Driver'] = @request_driver.to_s \
+        if @request_driver
+      headers['X-Deltacloud-Provider'] = @request_provider.to_s \
+        if @request_provider
+      headers
+    end
+
+  end
+end