raca 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96ffbbfd74e51b99894091ce939cb3521766e52c
-  data.tar.gz: 0551b2e01de644084a4099a984a25c90e6add01c
+  metadata.gz: 0f887cfa6d624450eb2805122c998cc29acc0b01
+  data.tar.gz: 89109fe3d3b728239a0ab9795d24508b96bff2ae
 SHA512:
-  metadata.gz: 9b5cf1bc1d8c2a93d6c17bef62e9fd9e6bdd35df9dd56915309ccc771cb48659703561ea3d1d2e45b46d701c11a48d12f2662c22b3f4f248370076aedf556720
-  data.tar.gz: 90ebbc528ed8b7a8782ea9a7dd30a3c4a30d2799ea6267995a114fe68a7a6e687c34ab0d2ecbc24b61df4be33a1c05716f4eb899646c95a5a8748eefaf7c2da6
+  metadata.gz: 65b7f065c88ec68907b6580fc65b1ed05187988807a450bfee8dff001d2bb0c2ac552b973bdc188567edd0bbcc1bb12ef5ca2de9e732dd9713df64220d8f8c80
+  data.tar.gz: ce61916a750f740b82b569be8913eaa806dffab65e3ad34013d49702ceaca9aa63ab7a01333a277adf51dc674427984c2fb534fc8f6cde915438ad1ce5007df8

data/README.markdown

@@ -113,9 +113,34 @@ is the temp URL key that can be set using Raca::Containers#set_temp_url_key
 
 ### Cloud Servers
 
-    account = Raca::Account.new("username", "api_key")
-    server = account.servers(:ord).get("foo")
-    puts server.public_addresses
+Using an existing Raca::Account object, retrieve a collection of Cloud Servers
+from a region like so:
+
+    ord_servers = account.servers(:ord)
+
+You can retrieve a existing server from the collection:
+
+    a_server = ord_servers.get("server_name")
+
+Retrieve some details on the server:
+
+    put a_server.metadata
+
+You can use the collection to create a brand new server:
+
+    a_server = ord_servers.create("server_name", "1Gb", "Ubuntu 10.04 LTS")
+
+## General API principles
+
+Methods that make calls to an API should never return a raw HTTP response
+object. If a sensible return value is expected (retrieving metadata, listing
+matches, etc) then that should always be returned. If return value isn't obvious
+(change remote state, deleting an object, etc) then a simple boolean or similar
+should be returned to indicate success.
+
+If an unexpected error occurs (a network timeout, a 500, etc) then an exception
+should be raised.
+
 
 ## Why not fog?
 

data/Rakefile

@@ -1,9 +1,22 @@
 require 'rspec/core/rake_task'
+require "cane/rake_task"
 
-task default: :spec
+task default: [:cane, :spec]
 
 desc "Run all rspec files"
 RSpec::Core::RakeTask.new("spec") do |t|
   t.rspec_opts  = ["--color", "--format progress"]
   t.ruby_opts = "-w"
 end
+
+desc "Run cane to check quality metrics"
+Cane::RakeTask.new(:cane) do |cane|
+  # keep the ABC complexity of methods to something reasonable
+  cane.abc_max = 15
+
+  # keep line lengths to something that fit into a reasonable split terminal
+  cane.style_measure = 148
+
+  # 0 is the goal
+  cane.max_violations = 3
+end

data/lib/raca/account.rb

@@ -3,12 +3,9 @@ require 'json'
 
 module Raca
 
-  # The rackspace auth API accepts a username and API key and returns a range
-  # of settings that are used for interacting with their other APIS. Think
-  # auth tokens, hostnames, paths, etc.
-  #
-  # This class caches these settings so we don't have to continually use our
-  # username/key to retrieve them.
+  # This is your entrypoint to the rackspace API. Start by creating a
+  # Raca::Account object and then use the instance method to access each of
+  # the supported rackspace APIs.
   #
   class Account
 
@@ -21,10 +18,25 @@ module Raca
       end
     end
 
+    # Return the temporary token that should be used when making further API
+    # requests.
+    #
+    #     account = Raca::Account.new("username", "secret")
+    #     puts account.auth_token
+    #
     def auth_token
-      extract_value(cloudfiles_data, "access", "token", "id")
+      extract_value(identity_data, "access", "token", "id")
     end
 
+    # Return the public API URL for a particular rackspace service.
+    #
+    # Use Account#service_names to see a list of valid service_name's for this.
+    #
+    # Check the project README for an updated list of the available regions.
+    #
+    #     account = Raca::Account.new("username", "secret")
+    #     puts account.public_endpoint("cloudServers", :syd)
+    #
     def public_endpoint(service_name, region)
       region = region.to_s.upcase
       endpoints = service_endpoints(service_name)
@@ -32,14 +44,45 @@ module Raca
       regional_endpoint["publicURL"]
     end
 
+    # Return the names of the available services. As rackspace add new services and
+    # APIs they should appear here.
+    #
+    # Any name returned from here can be passe to #public_endpoint to get the API
+    # endpoint for that service
+    #
+    #     account = Raca::Account.new("username", "secret")
+    #     puts account.service_names
+    #
+    def service_names
+      catalog = extract_value(identity_data, "access", "serviceCatalog") || {}
+      catalog.map { |service|
+        service["name"]
+      }
+    end
+
+    # Return a Raca::Containers object for a region. Use this to interact with the
+    # cloud files service.
+    #
+    #     account = Raca::Account.new("username", "secret")
+    #     puts account.containers(:ord)
+    #
     def containers(region)
       Raca::Containers.new(self, region)
     end
 
+    # Return a Raca::Containers object for a region. Use this to interact with the
+    # next gen cloud servers service.
+    #
+    #     account = Raca::Account.new("username", "secret")
+    #     puts account.servers(:ord)
+    #
     def servers(region)
       Raca::Servers.new(self, region)
     end
 
+    # Raca classes use this method to occasionally re-authenticate with the rackspace
+    # servers. You can probable ignore it.
+    #
     def refresh_cache
       Net::HTTP.new('identity.api.rackspacecloud.com', 443).tap {|http|
         http.use_ssl = true
@@ -57,14 +100,27 @@ module Raca
           JSON.dump(payload),
           {'Content-Type' => 'application/json'},
         )
-        if response.is_a? Net::HTTPSuccess
+        if response.is_a?(Net::HTTPSuccess)
           cache_write(cache_key, JSON.load(response.body))
+        else
+          raise_on_error(response)
         end
       }
     end
 
     private
 
+    def raise_on_error(response)
+      error_klass = case response.code.to_i
+      when 400 then BadRequestError
+      when 404 then NotFoundError
+      when 500 then ServerError
+      else
+        HTTPError
+      end
+      raise error_klass, "Rackspace returned HTTP status #{response.code}"
+    end
+
     # This method is opaque, but it was the best I could come up with using just
     # the standard library. Sorry.
     #
@@ -94,7 +150,7 @@ module Raca
     # cloud servers, dns, etc)
     #
     def service_endpoints(service_name)
-      catalog = extract_value(cloudfiles_data, "access", "serviceCatalog") || {}
+      catalog = extract_value(identity_data, "access", "serviceCatalog") || {}
       service = catalog.detect { |s| s["name"] == service_name } || {}
       service["endpoints"] || []
     end
@@ -115,7 +171,7 @@ module Raca
       end
     end
 
-    def cloudfiles_data
+    def identity_data
       refresh_cache unless cache_read(cache_key)
 
       cache_read(cache_key) || {}

data/lib/raca/container.rb

@@ -4,13 +4,18 @@ require 'openssl'
 require 'uri'
 
 module Raca
-  # Handy abstraction for interacting with a single Cloud Files container. We
-  # could use fog or similar, but this ~200 line class is simple and does
-  # everything we need.
+
+  # Represents a single cloud files container. Contains methods for uploading,
+  # downloading, collecting stats, listing files, etc.
+  #
+  # You probably don't want to instantiate this directly,
+  # see Raca::Account#containers
+  #
   class Container
     MAX_ITEMS_PER_LIST = 10_000
     LARGE_FILE_THRESHOLD = 5_368_709_120 # 5 Gb
     LARGE_FILE_SEGMENT_SIZE = 104_857_600 # 100 Mb
+    RETRY_PAUSE = 5
 
     attr_reader :container_name
 
@@ -24,6 +29,7 @@ module Raca
     end
 
     # Upload data_or_path (which may be a filename or an IO) to the container, as key.
+    #
     def upload(key, data_or_path)
       case data_or_path
       when StringIO, File
@@ -39,9 +45,11 @@ module Raca
 
     # Delete +key+ from the container. If the container is on the CDN, the object will
     # still be served from the CDN until the TTL expires.
+    #
     def delete(key)
       log "deleting #{key} from #{container_path}"
-      storage_request(Net::HTTP::Delete.new(File.join(container_path, key)))
+      response = storage_request(Net::HTTP::Delete.new(File.join(container_path, key)))
+      (200..299).cover?(response.code.to_i)
     end
 
     # Remove +key+ from the CDN edge nodes on which it is currently cached. The object is
@@ -50,12 +58,14 @@ module Raca
     #
     # This shouldn't be used except when it's really required (e.g. when a piece has to be
     # taken down) because it's expensive: it lodges a support ticket at Akamai. (!)
+    #
     def purge_from_akamai(key, email_address)
       log "Requesting #{File.join(container_path, key)} to be purged from the CDN"
-      cdn_request(Net::HTTP::Delete.new(
+      response = cdn_request(Net::HTTP::Delete.new(
         File.join(container_path, key),
         'X-Purge-Email' => email_address
       ))
+      (200..299).cover?(response.code.to_i)
     end
 
     # Returns some metadata about a single object in this container.
@@ -71,15 +81,20 @@ module Raca
       }
     end
 
+    # Download the object at key into a local file at filepath.
+    #
+    # Returns the number of downloaded bytes.
+    #
     def download(key, filepath)
       log "downloading #{key} from #{container_path}"
-      storage_request(Net::HTTP::Get.new(File.join(container_path, key))) do |response|
+      response = storage_request(Net::HTTP::Get.new(File.join(container_path, key))) do |response|
         File.open(filepath, 'wb') do |io|
           response.read_body do |chunk|
             io.write(chunk)
           end
         end
       end
+      response["Content-Length"].to_i
     end
 
     # Return an array of files in the container.
@@ -89,6 +104,7 @@ module Raca
     # max - the maximum number of items to return
     # marker - return items alphabetically after this key. Useful for pagination
     # prefix - only return items that start with this string
+    #
     def list(options = {})
       max = options.fetch(:max, MAX_ITEMS_PER_LIST)
       marker = options.fetch(:marker, nil)
@@ -112,11 +128,18 @@ module Raca
       }
     end
 
+    # Returns an array of object keys that start with prefix. This is a convenience
+    # method that is equivilant to:
+    #
+    #     container.list(prefix: "foo/bar/")
+    #
     def search(prefix)
       log "retrieving container listing from #{container_path} items starting with #{prefix}"
       list(prefix: prefix)
     end
 
+    # Return some basic stats on the current container.
+    #
     def metadata
       log "retrieving container metadata from #{container_path}"
       response = storage_request(Net::HTTP::Head.new(container_path))
@@ -126,6 +149,9 @@ module Raca
       }
     end
 
+    # Return the key details for CDN access to this container. Can be called
+    # on non CDN enabled containers, but the details won't make much sense.
+    #
     def cdn_metadata
       log "retrieving container CDN metadata from #{container_path}"
       response = cdn_request(Net::HTTP::Head.new(container_path))
@@ -143,10 +169,13 @@ module Raca
     # via the CDN. CDN enabling can be done via the web UI but only with a TTL of 72 hours.
     # Using the API it's possible to set a TTL of 50 years.
     #
-    def cdn_enable(ttl = 72.hours.to_i)
+    # TTL is defined in seconds, default is 72 hours.
+    #
+    def cdn_enable(ttl = 259200)
       log "enabling CDN access to #{container_path} with a cache expiry of #{ttl / 60} minutes"
 
-      cdn_request Net::HTTP::Put.new(container_path, "X-TTL" => ttl.to_i.to_s)
+      response = cdn_request(Net::HTTP::Put.new(container_path, "X-TTL" => ttl.to_i.to_s))
+      (200..299).cover?(response.code.to_i)
     end
 
     # Generate a expiring URL for a file that is otherwise private. useful for providing temporary
@@ -184,8 +213,8 @@ module Raca
       if io.respond_to?(:path)
         headers['Content-Type'] ||= extension_content_type(io.path)
         headers['Content-Type'] ||= file_content_type(io.path)
-        headers['Etag']           = md5(io.path)
       end
+        headers['Etag']           = md5_io(io)
       headers['Content-Type']   ||= "application/octet-stream"
       if content_type_needs_cors(key)
         headers['Access-Control-Allow-Origin'] = "*"
@@ -196,7 +225,8 @@ module Raca
       request = Net::HTTP::Put.new(full_path, headers)
       request.body_stream = io
       request.content_length = byte_count
-      storage_request(request)
+      response = storage_request(request)
+      response['ETag']
     end
 
     def upload_io_large(key, io, byte_count)
@@ -207,8 +237,8 @@ module Raca
         segment_key = "%s.%03d" % [key, segments.size]
         io.seek(start_pos)
         segment_io = StringIO.new(io.read(LARGE_FILE_SEGMENT_SIZE))
-        result = upload_io_standard(segment_key, segment_io, segment_io.size)
-        segments << {path: "#{@container_name}/#{segment_key}", etag: result["ETag"], size_bytes: segment_io.size}
+        etag = upload_io_standard(segment_key, segment_io, segment_io.size)
+        segments << {path: "#{@container_name}/#{segment_key}", etag: etag, size_bytes: segment_io.size}
       end
       manifest_key = "#{key}?multipart-manifest=put"
       manifest_body = StringIO.new(JSON.dump(segments))
@@ -230,14 +260,12 @@ module Raca
       end
     rescue Timeout::Error
       if retries >= 3
-        raise "Timeout from Rackspace at #{Time.now} while trying #{request.class} to #{request.path}"
+        raise Raca::TimeoutError, "Timeout from Rackspace while trying #{request.class} to #{request.path}"
       end
 
-      unless defined?(Rails) && Rails.env.test?
-        retry_interval = 5 + (retries.to_i * 5) # Retry after 5, 10, 15 and 20 seconds
-        log "Rackspace timed out: retrying after #{retry_interval}s"
-        sleep(retry_interval)
-      end
+      retry_interval = RETRY_PAUSE + (retries.to_i * RETRY_PAUSE) # Retry after 5, 10, 15 and 20 seconds
+      log "Rackspace timed out: retrying after #{retry_interval}s"
+      sleep(retry_interval)
 
       cloud_request(request, hostname, retries + 1, &block)
     end
@@ -253,11 +281,25 @@ module Raca
           @account.refresh_cache
           response = block.call http
         end
-        raise "Failure: Rackspace returned #{response.inspect}" unless response.is_a?(Net::HTTPSuccess)
-        response
+        if response.is_a?(Net::HTTPSuccess)
+          response
+        else
+          raise_on_error(response)
+        end
       end
     end
 
+    def raise_on_error(response)
+      error_klass = case response.code.to_i
+      when 400 then BadRequestError
+      when 404 then NotFoundError
+      when 500 then ServerError
+      else
+        HTTPError
+      end
+      raise error_klass, "Rackspace returned HTTP status #{response.code}"
+    end
+
     def log(msg)
       if @logger.respond_to?(:debug)
         @logger.debug msg
@@ -308,14 +350,14 @@ module Raca
       [".eot",".ttf",".woff"].include?(File.extname(path))
     end
 
-    def md5(path)
+    def md5_io(io)
+      io.seek(0)
       digest = Digest::MD5.new
-      File.open(path, 'rb') do |f|
-        # read in 128K chunks
-        f.each(1024 * 128) do |chunk|
-          digest << chunk
-        end
+      # read in 128K chunks
+      io.each(1024 * 128) do |chunk|
+        digest << chunk
       end
+      io.seek(0)
       digest.hexdigest
     end
   end

data/lib/raca/containers.rb

@@ -1,4 +1,12 @@
 module Raca
+  # Represents a collection of cloud files containers within a single region.
+  #
+  # There's a handful of methods that relate to the entire collection, but this
+  # is primarily used to retrieve a single Raca::Container object.
+  #
+  # You probably don't want to instantiate this directly,
+  # see Raca::Account#containers
+  #
   class Containers
     def initialize(account, region, opts = {})
       @account, @region = account, region
@@ -23,14 +31,19 @@ module Raca
       }
     end
 
-    # Set the secret key that will be used to generate expiring URLs for all cloud files containers on the current account. This value should be passed to the expiring_url() method.
+    # Set the secret key that will be used to generate expiring URLs for all cloud
+    # files containers on the current account. This value should be passed to the
+    # expiring_url() method.
     #
-    # Use this with caution, this will invalidate all previously generated expiring URLS *FOR THE ENTIRE ACCOUNT*
+    # Use this with caution, this will invalidate all previously generated expiring
+    # URLS *FOR THE ENTIRE ACCOUNT*
     #
     def set_temp_url_key(secret)
       log "setting Account Temp URL Key on #{storage_path}"
 
-      storage_request Net::HTTP::Post.new(storage_path, "X-Account-Meta-Temp-Url-Key" => secret.to_s)
+      request = Net::HTTP::Post.new(storage_path, "X-Account-Meta-Temp-Url-Key" => secret.to_s)
+      response = storage_request(request)
+      (200..299).cover?(response.code.to_i)
     end
 
     private
@@ -65,11 +78,26 @@ module Raca
           @account.refresh_cache
           response = block.call http
         end
-        raise "Failure: Rackspace returned #{response.inspect}" unless response.is_a?(Net::HTTPSuccess)
+        if response.is_a?(Net::HTTPSuccess)
+          response
+        else
+          raise_on_error(response)
+        end
         response
       end
     end
 
+    def raise_on_error(response)
+      error_klass = case response.code.to_i
+      when 400 then BadRequestError
+      when 404 then NotFoundError
+      when 500 then ServerError
+      else
+        HTTPError
+      end
+      raise error_klass, "Rackspace returned HTTP status #{response.code}"
+    end
+
     def log(msg)
       if @logger.respond_to?(:debug)
         @logger.debug msg

data/lib/raca/errors.rb

@@ -0,0 +1,17 @@
+module Raca
+  # base error for unexpected HTTP responses from rackspace
+  class HTTPError < RuntimeError; end
+
+  # for 400 responses from rackspace
+  class BadRequestError < HTTPError; end
+
+  # for 404 responses from rackspace
+  class NotFoundError < HTTPError; end
+
+  # for 500 responses from rackspace
+  class ServerError < HTTPError; end
+
+  # for rackspace timeouts
+  class TimeoutError < RuntimeError; end
+
+end

data/lib/raca/server.rb

@@ -3,69 +3,24 @@ require 'base64'
 require 'net/http'
 
 module Raca
-  # Handy abstraction for interacting with a single rackspace Clpud Server. We
-  # could use fog or similar, but this ~200 line class is simple and does
-  # everything we need.
+  # Represents a single cloud server. Contains methods for deleting a server,
+  # listing IP addresses, checking the state, etc.
+  #
+  # You probably don't want to instantiate this directly,
+  # see Raca::Account#servers
+  #
   class Server
 
-    attr_reader :server_name, :server_id
+    attr_reader :server_id
 
-    def initialize(account, region, server_name)
+    def initialize(account, region, server_id)
       @account = account
       @region = region
       @servers_url = @account.public_endpoint("cloudServersOpenStack", region)
-      @server_name = server_name
-      @server_id = find_server_id(server_name)
-    end
-
-    # return true if this server exists on Rackspace
-    #
-    def exists?
-      @server_id != nil
-    end
-
-    # create this server on Rackspace.
-    #
-    # flavor_name is a string that describes the amount of RAM. If you enter
-    # an invalid option a list of valid options will be raised.
-    #
-    # image_name is a string that describes the OS image to use. If you enter
-    # an invalid option a list of valid options will be raised. I suggest
-    # starting with 'Ubuntu 10.04 LTS'
-    #
-    # files is an optional Hash of path to blobs. Use it to place a file on the
-    # disk of the new server.
-    #
-    # Use it like this:
-    #
-    #     server.create(512, "Ubuntu 10.04 LTS", "/root/.ssh/authorised_keys" => File.read("/foo"))
-    #
-    def create(flavor_name, image_name, files = {})
-      raise ArgumentError, "server already exists" if exists?
-
-      request = {
-        "server" => {
-          "name" => @server_name,
-          "imageRef" => image_name_to_id(image_name),
-          "flavorRef" => flavor_name_to_id(flavor_name),
-        }
-      }
-      files.each do |path, blob|
-        request['server']['personality'] ||= []
-        request['server']['personality'] << {
-          'path' => path,
-          'contents' => Base64.encode64(blob)
-        }
-      end
-
-      data = cloud_request(Net::HTTP::Post.new(servers_path), JSON.dump(request)).body
-      data = JSON.parse(data)['server']
-      @server_id = data['id']
+      @server_id = server_id
     end
 
     def delete!
-      raise ArgumentError, "server doesn't exist" unless exists?
-
       response = cloud_request(Net::HTTP::Delete.new(server_path))
       response.is_a? Net::HTTPSuccess
     end
@@ -95,42 +50,12 @@ module Raca
     # A Hash of various matadata about the server
     #
     def details
-      raise ArgumentError, "server doesn't exist" unless exists?
-
       data = cloud_request(Net::HTTP::Get.new(server_path)).body
       JSON.parse(data)['server']
     end
 
     private
 
-    def list
-      json = cloud_request(Net::HTTP::Get.new(servers_path)).body
-      JSON.parse(json)['servers']
-    end
-
-    def find_server_id(server_name)
-      server = list.detect {|row|
-        row["name"] == server_name
-      }
-      server ? server["id"] : nil
-    end
-
-    def flavors_path
-      @flavors_path ||= File.join(account_path, "flavors")
-    end
-
-    def images_path
-      @images_path ||= File.join(account_path, "images")
-    end
-
-    def server_path
-      @server_path ||= File.join(account_path, "servers", @server_id.to_s)
-    end
-
-    def servers_path
-      @servers_path ||= File.join(account_path, "servers")
-    end
-
     def servers_host
       @servers_host ||= URI.parse(@servers_url).host
     end
@@ -139,48 +64,8 @@ module Raca
       @account_path ||= URI.parse(@servers_url).path
     end
 
-    def flavors
-      @flavors ||= begin
-        data = cloud_request(Net::HTTP::Get.new(flavors_path)).body
-        JSON.parse(data)['flavors']
-      end
-    end
-
-    def flavor_names
-      flavors.map {|row| row['name'] }
-    end
-
-    def flavor_name_to_id(str)
-      flavor = flavors.detect {|row|
-        row['name'].downcase.include?(str.to_s.downcase)
-      }
-      if flavor
-        flavor['id']
-      else
-        raise ArgumentError, "valid flavors are: #{flavor_names.join(', ')}"
-      end
-    end
-
-    def images
-      @images ||= begin
-        data = cloud_request(Net::HTTP::Get.new(images_path)).body
-        JSON.parse(data)['images']
-      end
-    end
-
-    def image_names
-      images.map {|row| row['name'] }
-    end
-
-    def image_name_to_id(str)
-      image = images.detect {|row|
-        row['name'].downcase.include?(str.to_s.downcase)
-      }
-      if image
-        image['id']
-      else
-        raise ArgumentError, "valid images are: #{image_names.join(', ')}"
-      end
+    def server_path
+      @server_path ||= File.join(account_path, "servers", @server_id.to_s)
     end
 
     def cloud_request(request, body = nil)
@@ -202,15 +87,32 @@ module Raca
           @account.refresh_cache
           response = block.call http
         end
-        raise "Failure: Rackspace returned #{response.inspect}" unless response.is_a?(Net::HTTPSuccess)
+        if response.is_a?(Net::HTTPSuccess)
+          response
+        else
+          raise_on_error(response)
+        end
         response
       end
-    rescue Timeout::Error => e
-      raise e if retries <= 0
+    rescue Timeout::Error
+      if retries <= 0
+        raise Raca::TimeoutError, "Timeout from Rackspace while trying #{request.class} to #{request.path}"
+      end
 
       cloud_http(hostname, retries - 1, &block)
     end
 
+    def raise_on_error(response)
+      error_klass = case response.code.to_i
+      when 400 then BadRequestError
+      when 404 then NotFoundError
+      when 500 then ServerError
+      else
+        HTTPError
+      end
+      raise error_klass, "Rackspace returned HTTP status #{response.code}"
+    end
+
     def log(msg)
       if defined?(Rails)
         Rails.logger.info msg

data/lib/raca/servers.rb

@@ -1,11 +1,196 @@
 module Raca
+  # Represents a collection of cloud servers within a single region.
+  #
+  # There's currently no methods that relate to the entire collection,
+  # this is primarily used to retrieve a single Raca::Server object.
+  #
+  # You probably don't want to instantiate this directly,
+  # see Raca::Account#servers
+  #
   class Servers
     def initialize(account, region)
       @account, @region = account, region
+      @servers_url = @account.public_endpoint("cloudServersOpenStack", region)
     end
 
     def get(server_name)
-      Raca::Server.new(@account, @region, server_name)
+      server_id = find_server_id(server_name)
+      if server_id
+        Raca::Server.new(@account, @region, server_id)
+      else
+        nil
+      end
     end
+
+    # create a new server on Rackspace.
+    #
+    # server_name is a free text name you want to assign the server.
+    #
+    # flavor_name is a string that describes the amount of RAM. If you enter
+    # an invalid option a list of valid options will be raised.
+    #
+    # image_name is a string that describes the OS image to use. If you enter
+    # an invalid option a list of valid options will be raised. I suggest
+    # starting with 'Ubuntu 10.04 LTS'
+    #
+    # files is an optional Hash of path to blobs. Use it to place a file on the
+    # disk of the new server.
+    #
+    # Use it like this:
+    #
+    #     server.create("my-server", 512, "Ubuntu 10.04 LTS", "/root/.ssh/authorised_keys" => File.read("/foo"))
+    #
+    def create(server_name, flavor_name, image_name, files = {})
+      request = {
+        "server" => {
+          "name" => server_name,
+          "imageRef" => image_name_to_id(image_name),
+          "flavorRef" => flavor_name_to_id(flavor_name),
+        }
+      }
+      files.each do |path, blob|
+        request['server']['personality'] ||= []
+        request['server']['personality'] << {
+          'path' => path,
+          'contents' => Base64.encode64(blob)
+        }
+      end
+
+      data = cloud_request(Net::HTTP::Post.new(servers_path), JSON.dump(request)).body
+      data = JSON.parse(data)['server']
+      Raca::Server.new(@account, @region, data['id'])
+    end
+
+    private
+
+    def servers_host
+      @servers_host ||= URI.parse(@servers_url).host
+    end
+
+    def account_path
+      @account_path ||= URI.parse(@servers_url).path
+    end
+
+    def flavors_path
+      @flavors_path ||= File.join(account_path, "flavors")
+    end
+
+    def images_path
+      @images_path ||= File.join(account_path, "images")
+    end
+
+    def servers_path
+      @servers_path ||= File.join(account_path, "servers")
+    end
+
+    def list
+      json = cloud_request(Net::HTTP::Get.new(servers_path)).body
+      JSON.parse(json)['servers']
+    end
+
+    def find_server_id(server_name)
+      server = list.detect {|row|
+        row["name"] == server_name
+      }
+      server ? server["id"] : nil
+    end
+
+    def flavors
+      @flavors ||= begin
+        data = cloud_request(Net::HTTP::Get.new(flavors_path)).body
+        JSON.parse(data)['flavors']
+      end
+    end
+
+    def flavor_names
+      flavors.map {|row| row['name'] }
+    end
+
+    def flavor_name_to_id(str)
+      flavor = flavors.detect {|row|
+        row['name'].downcase.include?(str.to_s.downcase)
+      }
+      if flavor
+        flavor['id']
+      else
+        raise ArgumentError, "valid flavors are: #{flavor_names.join(', ')}"
+      end
+    end
+
+    def images
+      @images ||= begin
+        data = cloud_request(Net::HTTP::Get.new(images_path)).body
+        JSON.parse(data)['images']
+      end
+    end
+
+    def image_names
+      images.map {|row| row['name'] }
+    end
+
+    def image_name_to_id(str)
+      image = images.detect {|row|
+        row['name'].downcase.include?(str.to_s.downcase)
+      }
+      if image
+        image['id']
+      else
+        raise ArgumentError, "valid images are: #{image_names.join(', ')}"
+      end
+    end
+
+    def cloud_request(request, body = nil)
+      request['X-Auth-Token'] = @account.auth_token
+      request['Content-Type'] = 'application/json'
+      request['Accept']       = 'application/json'
+      cloud_http(servers_host) do |http|
+        http.request(request, body)
+      end
+    end
+
+    def cloud_http(hostname, retries = 3, &block)
+      http = Net::HTTP.new(hostname, 443)
+      http.use_ssl = true
+      http.start do |http|
+        response = block.call http
+        if response.is_a?(Net::HTTPUnauthorized)
+          log "Rackspace returned HTTP 401; refreshing auth before retrying."
+          @account.refresh_cache
+          response = block.call http
+        end
+        if response.is_a?(Net::HTTPSuccess)
+          response
+        else
+          raise_on_error(response)
+        end
+        response
+      end
+    rescue Timeout::Error
+      if retries <= 0
+        raise Raca::TimeoutError, "Timeout from Rackspace while trying #{request.class} to #{request.path}"
+      end
+
+      cloud_http(hostname, retries - 1, &block)
+    end
+
+    def raise_on_error(response)
+      error_klass = case response.code.to_i
+      when 400 then BadRequestError
+      when 404 then NotFoundError
+      when 500 then ServerError
+      else
+        HTTPError
+      end
+      raise error_klass, "Rackspace returned HTTP status #{response.code}"
+    end
+
+    def log(msg)
+      if defined?(Rails)
+        Rails.logger.info msg
+      else
+        puts msg
+      end
+    end
+
   end
 end

data/lib/raca.rb

@@ -1,3 +1,5 @@
+require 'raca/errors'
+
 require 'raca/account'
 require 'raca/container'
 require 'raca/containers'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: raca
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - James Healy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-24 00:00:00.000000000 Z
+date: 2014-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -66,6 +66,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: cane
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: A simple wrapper for the Rackspace Cloud API with no dependencies
 email:
 - james.healy@theconversation.edu.au
@@ -79,6 +93,7 @@ files:
 - lib/raca/account.rb
 - lib/raca/container.rb
 - lib/raca/containers.rb
+- lib/raca/errors.rb
 - lib/raca/server.rb
 - lib/raca/servers.rb
 homepage: http://github.com/conversation/raca
@@ -104,7 +119,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.0
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: A simple wrapper for the Rackspace Cloud API with no dependencies