Raca

A simple gem for interacting with Rackspace cloud APIs. The following APIs are supported:

  • Identity
  • Cloud Files
  • Cloud Servers

Raca intentionally has no dependencies outside the ruby standard library.

If loaded alongside Rails, it will utilise the rails cache to avoid repeated requests to the rackspace identity API.

Installation

gem install raca

Usage

For full usage details check the documentation for each class, but here's a taste of the basics.

Regions

Many of the Rackspace cloud products are available in multiple regions. When required, you can specify a region using a symbol with the 3-letter region code.

Currently, the following regions are valid:

  • :ord - Chicago
  • :iad - Northern Virginia
  • :syd - Sydney
  • :dfw - Dallas-Fort Worth
  • :hkg - Hong Kong

Identity

To authenticate and begin any interaction with rackspace, you must create a Raca::Account instance.

 = Raca::Account.new("username", "api_key")

You can view the token that will be used for subsequent requests:

puts .auth_token

List the available APIs:

puts .service_names

... and then view the URLs for each service:

puts .public_endpoint("cloudFiles", :ord)

Cloud Files

Using an existing Raca::Account object, retrieve a collection of Cloud Files containers in a region like so:

ord_containers = .containers(:ord)

You can retrieve a single container from the collection:

dir = ord_containers.get("container_name")

Retrieve some metadata on the collection:

put ord_containers.metadata

With a single container, you can perform a range of operations on the container and objects inside it.

dir = ord_containers.get("container_name")

Download a file:

dir.download("remote_key.txt", "/home/jh/local_file.txt")

Upload a file:

dir.upload("target_path.txt", "/home/jh/local_file.txt")

List keys in the container, optionally limiting the results to those starting with a prefix:

puts dir.list
puts dir.list(prefix: "subdir/")

Delete an object:

dir.delete("target_path.txt")

View metadata on the container:

puts dir.metadata
puts dir.cdn_metadata

Enable access to the container contents via a public CDN. Use this with caution, it will make all objects public!

It accepts an argument telling the CDN edge nodes how long they can cache each object for (in seconds).

dir.cdn_enable(60 * 60 * 24) # 1 day

Purge an object from the CDN:

dir.purge_from_akamai("target_path.txt", "[email protected]")

Generate a public URL to an object in a private container. The second argument is the temp URL key that can be set using Raca::Containers#set_temp_url_key

ord_containers = .containers(:ord)
ord_containers.set_temp_url_key("secret")
dir = ord_containers.get("container_name")
puts dir.temp_url("remote_key.txt", "secret", Time.now.to_i + 60)

Cloud Servers

Using an existing Raca::Account object, retrieve a collection of Cloud Servers from a region like so:

ord_servers = .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")

Users

Using an existing Raca::Account object, retrieve a collection of Users like so:

users = .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 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?

fog is the official ruby library for interacting with the Rackspace API. It is a very capable library and supports much more of the API than this modest gem.

As of version 1.20.0, fog supports dozens of providers, contains ~152000 lines of ruby and adds ~500ms to the boot time of our rails apps. raca is a lightweight, rackspace-only alternative with minimal dependencies that should have a negligable impact on application boot times. Version 0.3 has ~700 lines of ruby (excluding specs). It also does much less than fog. We can't have our cake and eat it too.

Compatibility

The Raca version number is < 1.0 because it's highly unstable. Until we release a 1.0.0, consider the API of this gem to be unstable.

License

This library is released undr the MIT License. See the included MIT-LICENSE file for further details