raca 0.3.3 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: aaa0a7402a954f81c2f50f2baf971bd5fe2393b3
-  data.tar.gz: 5e047547e7fec0af4e9ef1f0874706b3c6a2decb
+  metadata.gz: e941f8aeb1ac9f4a298aa8bf39d9de49cfeeced0
+  data.tar.gz: cbbb18973fd14aed6dbf03d277229a47668a3019
 SHA512:
-  metadata.gz: b0dd7c796af6df4919a712d2a41396f18b5801598202493125f65c6299576d3101c6ce826bf523878c61e42ec761152cada2bd802b4bef0ecc356313c0c9921d
-  data.tar.gz: 64c50f121fa1e365242faef9d7688f826562f6fa6b28b8363fd23307dfb44ab57d61eb7a00d92ebb2065a1e2fc3e40e0875b58ea92981398cb8baa9ab2cea3d0
+  metadata.gz: ff7704021fa4e079271978663d322553e99bcfc7fad5036a5f62381c71d77150df410f42d436c700dbcf7f7f430d4ffba3f35eb606aea90895b17ccf9f4aa9c4
+  data.tar.gz: 07b80eb013f6e8ab98db0b502b382169746d82dd7d4d5981f1f5384a5241e36867e8e1aad4faeec2376c43a7050dfeb403cde1e22110ae7d5a3177d92cb1bc31

data/CHANGELOG

@@ -1,3 +1,13 @@
+v0.4.0 (25th August 2014)
+* Added Raca::Container#temp_upload_url
+* Renamed Raca::Container#expiring_url to Raca::Container#temp_url
+  * the old method still exists for now but is deprecated
+* Expand Raca::Container#metadata to include custom metadata
+* Added raca::Container#set_metadata
+* For non regioned APIs (like Cloud DNS) the region argument to Raca::Account#public_endpoint
+  can be left off
+* Added read access to user accounts via Raca::Account#users
+
 v0.3.3 (26th April 2014)
 * Added a User-Agent header to all requests
 * Remove automatic retries after a rackspace timeout

data/README.markdown

@@ -112,7 +112,7 @@ is the temp URL key that can be set using Raca::Containers#set_temp_url_key
     ord_containers = account.containers(:ord)
     ord_containers.set_temp_url_key("secret")
     dir = ord_containers.get("container_name")
-    puts dir.expiring_url("remote_key.txt", "secret", Time.now.to_i + 60)
+    puts dir.temp_url("remote_key.txt", "secret", Time.now.to_i + 60)
 
 ### Cloud Servers
 
@@ -133,6 +133,21 @@ You can use the collection to create a brand new server:
 
     a_server = ord_servers.create("server_name", "1Gb", "Ubuntu 10.04 LTS")
 
+### Users
+
+Using an existing Raca::Account object, retrieve a collection of Users like so:
+
+    users = account.users
+
+You can retrieve an existing user from the collection:
+
+    a_user = users.get("username")
+
+You can display details for each user with the details method:
+
+    a_user = users.get("username")
+    a_user.details
+
 ## General API principles
 
 Methods that make calls to an API should never return a raw HTTP response

data/lib/raca.rb

@@ -6,4 +6,6 @@ require 'raca/containers'
 require 'raca/http_client'
 require 'raca/server'
 require 'raca/servers'
+require 'raca/user'
+require 'raca/users'
 require 'raca/util'

data/lib/raca/account.rb

@@ -8,6 +8,7 @@ module Raca
   # the supported rackspace APIs.
   #
   class Account
+    IDENTITY_URL = "https://identity.api.rackspacecloud.com/v2.0/"
 
     def initialize(username, key, cache = nil)
       @username, @key, @cache = username, key, cache
@@ -37,11 +38,28 @@ module Raca
     #     account = Raca::Account.new("username", "secret")
     #     puts account.public_endpoint("cloudServers", :syd)
     #
-    def public_endpoint(service_name, region)
-      region = region.to_s.upcase
+    # Some service APIs are not regioned. In those cases, the region code can be
+    # left off:
+    #
+    #     account = Raca::Account.new("username", "secret")
+    #     puts account.public_endpoint("cloudDNS")
+    #
+    def public_endpoint(service_name, region = nil)
+      return IDENTITY_URL if service_name == "identity"
+
       endpoints = service_endpoints(service_name)
-      regional_endpoint = endpoints.detect { |e| e["region"] == region } || {}
-      regional_endpoint["publicURL"]
+      if endpoints.size > 1 && region
+        region = region.to_s.upcase
+        endpoints = endpoints.select { |e| e["region"] == region } || {}
+      elsif endpoints.size > 1 && region.nil?
+        raise ArgumentError, "The requested service exists in multiple regions, please specify a region code"
+      end
+
+      if endpoints.size == 0
+        raise ArgumentError, "No matching services found"
+      else
+        endpoints.first["publicURL"]
+      end
     end
 
     # Return the names of the available services. As rackspace add new services and
@@ -80,13 +98,23 @@ module Raca
       Raca::Servers.new(self, region)
     end
 
+    # Return a Raca::Users object. Use this to query and manage the users associated
+    # with the current account.
+    #
+    #     account = Raca::Account.new("username", "secret")
+    #     puts account.users
+    #
+    def users
+      Raca::Users.new(self)
+    end
+
     # Raca classes use this method to occasionally re-authenticate with the rackspace
     # servers. You can probably ignore it.
     #
     def refresh_cache
       # Raca::HttpClient depends on Raca::Account, so we intentionally don't use it here
       # to avoid a circular dependency
-      Net::HTTP.new('identity.api.rackspacecloud.com', 443).tap {|http|
+      Net::HTTP.new(identity_host, 443).tap {|http|
         http.use_ssl = true
       }.start {|http|
         payload = {
@@ -98,7 +126,7 @@ module Raca
           }
         }
         response = http.post(
-          '/v2.0/tokens',
+          tokens_path,
           JSON.dump(payload),
           {'Content-Type' => 'application/json'},
         )
@@ -116,8 +144,24 @@ module Raca
       Raca::HttpClient.new(self, hostname)
     end
 
+    def inspect
+      "#<Raca::Account:#{__id__} username=#{@username}>"
+    end
+
     private
 
+    def identity_host
+      URI.parse(IDENTITY_URL).host
+    end
+
+    def identity_path
+      URI.parse(IDENTITY_URL).path
+    end
+
+    def tokens_path
+      File.join(identity_path, "tokens")
+    end
+
     def raise_on_error(response)
       error_klass = case response.code.to_i
       when 400 then BadRequestError

data/lib/raca/container.rb

@@ -90,14 +90,14 @@ module Raca
     def download(key, filepath)
       log "downloading #{key} from #{container_path}"
       object_path = File.join(container_path, Raca::Util.url_encode(key))
-      response = storage_client.get(object_path) do |response|
+      outer_response = storage_client.get(object_path) do |response|
         File.open(filepath, 'wb') do |io|
           response.read_body do |chunk|
             io.write(chunk)
           end
         end
       end
-      response["Content-Length"].to_i
+      outer_response["Content-Length"].to_i
     end
 
     # Return an array of files in the container.
@@ -151,12 +151,34 @@ module Raca
     def metadata
       log "retrieving container metadata from #{container_path}"
       response = storage_client.head(container_path)
+      custom = {}
+      response.each_capitalized_name { |name|
+        custom[name] = response[name] if name[/\AX-Container-Meta-/]
+      }
       {
         :objects => response["X-Container-Object-Count"].to_i,
-        :bytes => response["X-Container-Bytes-Used"].to_i
+        :bytes => response["X-Container-Bytes-Used"].to_i,
+        :custom => custom,
       }
     end
 
+    # Set metadata headers on the container
+    #
+    #     headers = { "X-Container-Meta-Access-Control-Allow-Origin" => "*" }
+    #     container.set_metadata(headers)
+    #
+    # Note: Rackspace requires some headers to begin with 'X-Container-Meta-' or other prefixes, e.g. when setting
+    #       'Access-Control-Allow-Origin', it needs to be set as 'X-Container-Meta-Access-Control-Allow-Origin'.
+    # See:  http://docs.rackspace.com/files/api/v1/cf-devguide/content/CORS_Container_Header-d1e1300.html
+    #       http://docs.rackspace.com/files/api/v1/cf-devguide/content/
+    #         POST_updateacontainermeta_v1__account___container__containerServicesOperations_d1e000.html
+    #
+    def set_metadata(headers)
+      log "setting headers for container #{container_path}"
+      response = storage_client.post(container_path, '', headers)
+      (200..299).cover?(response.code.to_i)
+    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.
     #
@@ -186,13 +208,37 @@ module Raca
       (200..299).cover?(response.code.to_i)
     end
 
-    # Generate a expiring URL for a file that is otherwise private. useful for providing temporary
-    # access to files.
+    # Generate an expiring URL for downloading a file that is otherwise private.
+    # Useful for providing temporary access to files.
+    #
+    def temp_url(object_key, temp_url_key, expires_at = Time.now.to_i + 60)
+      private_url("GET", object_key, temp_url_key, expires_at)
+    end
+
+    # DEPRECATED: use temp_url instead, this will be removed in version 1.0
     #
     def expiring_url(object_key, temp_url_key, expires_at = Time.now.to_i + 60)
-      digest = OpenSSL::Digest::Digest.new('sha1')
+      temp_url(object_key, temp_url_key, expires_at)
+    end
+
+    # Generate a temporary URL for uploading a file to a private container. Anyone
+    # can perform a PUT request to the URL returned from this method and an object
+    # will be created in the container.
+    #
+    def temp_upload_url(object_key, temp_url_key, expires_at = Time.now.to_i + 60)
+      private_url("PUT", object_key, temp_url_key, expires_at)
+    end
+
+    def inspect
+      "#<Raca::Container:#{__id__} region=#{@region} container_name=#{@container_name}>"
+    end
+
+    private
+
+    def private_url(method, object_key, temp_url_key, expires_at)
+      raise ArgumentError, "method must be GET or PUT" unless %w{GET PUT}.include?(method)
+      digest = OpenSSL::Digest.new('sha1')
 
-      method  = 'GET'
       expires = expires_at.to_i
       path    = File.join(container_path, object_key)
       encoded_path = File.join(container_path, Raca::Util.url_encode(object_key))
@@ -204,8 +250,6 @@ module Raca
       "https://#{storage_host}#{encoded_path}?temp_url_sig=#{hmac.hexdigest}&temp_url_expires=#{expires}"
     end
 
-    private
-
     # build the request path for listing the contents of a container
     #
     def list_request_path(marker, prefix, details, limit)

data/lib/raca/containers.rb

@@ -45,6 +45,10 @@ module Raca
       (200..299).cover?(response.code.to_i)
     end
 
+    def inspect
+      "#<Raca::Containers:#{__id__} region=#{@region}>"
+    end
+
     private
 
     def storage_host

data/lib/raca/http_client.rb

@@ -65,6 +65,10 @@ module Raca
       cloud_request(request)
     end
 
+    def inspect
+      "#<Raca::HttpClient:#{__id__}>"
+    end
+
     private
 
     def build_streaming_put_request(path, io, byte_count, headers)
@@ -91,7 +95,7 @@ module Raca
     def cloud_request(request, &block)
       cloud_http do |http|
         request['X-Auth-Token'] = @account.auth_token
-        request['User-Agent'] = "raca 0.3.3 (http://rubygems.org/gems/raca)"
+        request['User-Agent'] = "raca 0.4.0 (http://rubygems.org/gems/raca)"
         http.request(request, &block)
       end
     end

data/lib/raca/server.rb

@@ -53,6 +53,10 @@ module Raca
       JSON.parse(data)['server']
     end
 
+    def inspect
+      "#<Raca::Server:#{__id__} region=#{@region} server_id=#{@server_id}>"
+    end
+
     private
 
     def json_headers

data/lib/raca/servers.rb

@@ -61,6 +61,10 @@ module Raca
       Raca::Server.new(@account, @region, data['id'])
     end
 
+    def inspect
+      "#<Raca::Servers:#{__id__} region=#{@region}>"
+    end
+
     private
 
     def json_headers

data/lib/raca/user.rb

@@ -0,0 +1,50 @@
+module Raca
+  # Represents a single user within the current account.
+  #
+  # You probably don't want to instantiate this directly,
+  # see Raca::Account#users
+  #
+  class User
+    attr_reader :username
+
+    def initialize(account, username, opts = {})
+      @account, @username = account, username
+      @identity_url = @account.public_endpoint("identity")
+      @logger = opts[:logger]
+      @logger ||= Rails.logger if defined?(Rails)
+    end
+
+    def details
+      response = identity_client.get(user_path)
+      JSON.load(response.body)["user"]
+    end
+
+    def inspect
+      "#<Raca::User:#{__id__} @username=#{@username}>"
+    end
+
+    private
+
+    def identity_host
+      URI.parse(@identity_url).host
+    end
+
+    def identity_path
+      URI.parse(@identity_url).path
+    end
+
+    def user_path
+      @user_path ||= File.join(identity_path, "users") + "?name=" + Raca::Util.url_encode(@username)
+    end
+
+    def identity_client
+      @identity_client ||= @account.http_client(identity_host)
+    end
+
+    def log(msg)
+      if @logger.respond_to?(:debug)
+        @logger.debug msg
+      end
+    end
+  end
+end

data/lib/raca/users.rb

@@ -0,0 +1,59 @@
+module Raca
+  # Represents a collection of users associated with a rackspace account
+  #
+  # You probably don't want to instantiate this directly,
+  # see Raca::Account#users
+  #
+  class Users
+    def initialize(account, opts = {})
+      @account = account
+      @identity_url = @account.public_endpoint("identity")
+      @logger = opts[:logger]
+      @logger ||= Rails.logger if defined?(Rails)
+    end
+
+    def get(username)
+      list.detect { |user| user.username == username }
+    end
+
+    def inspect
+      "#<Raca::Users:#{__id__}>"
+    end
+
+    private
+
+    # TODO should this (or something like it) be part of the public API?
+    def list
+      log "retrieving users list from #{users_path}"
+      response = identity_client.get(users_path)
+      records = JSON.load(response.body)["users"]
+      records.map { |record|
+        record["username"]
+      }.map { |username|
+        Raca::User.new(@account, username)
+      }
+    end
+
+    def identity_host
+      URI.parse(@identity_url).host
+    end
+
+    def identity_path
+      URI.parse(@identity_url).path
+    end
+
+    def users_path
+      File.join(identity_path, "users")
+    end
+
+    def identity_client
+      @identity_client ||= @account.http_client(identity_host)
+    end
+
+    def log(msg)
+      if @logger.respond_to?(:debug)
+        @logger.debug msg
+      end
+    end
+  end
+end

data/lib/raca/util.rb

@@ -3,8 +3,8 @@ module Raca
   class Util
     # CGI.escape, but without special treatment on spaces
     def self.url_encode(str)
-      str.gsub(%r{([^a-zA-Z0-9_./-]+)}) do |match|
-        '%' + match.unpack('H2*' * match.bytesize).join('%').upcase
+      str.gsub(%r{([^a-zA-Z0-9_./-])}) do |match|
+        '%' + match.unpack('H*').first.scan(/../).join("%").upcase
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: raca
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.4.0
 platform: ruby
 authors:
 - James Healy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-26 00:00:00.000000000 Z
+date: 2014-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -99,6 +99,8 @@ files:
 - lib/raca/http_client.rb
 - lib/raca/server.rb
 - lib/raca/servers.rb
+- lib/raca/user.rb
+- lib/raca/users.rb
 - lib/raca/util.rb
 homepage: http://github.com/conversation/raca
 licenses:
@@ -128,3 +130,4 @@ signing_key:
 specification_version: 4
 summary: A simple wrapper for the Rackspace Cloud API with no dependencies
 test_files: []
+has_rdoc: true