node-cloudfiles

A client implementation for Rackspace CloudFiles in node.js

Installation

Installing npm (node package manager)

  $ curl http://npmjs.org/install.sh | sh

Installing node-cloudfiles

  $ npm install cloudfiles

Getting Rackspace Account

Usage

The node-cloudfiles library is compliant with the Rackspace CloudFiles API. Using node-cloudfiles is easy for a variety of scenarios: authenticating, creating and working with both containers and storage objects.

Getting Started

Before we can do anything with cloudfiles, we have to create a client with valid credentials. Cloudfiles will authenticate for you automatically:

  var cloudfiles = require('cloudfiles');
  var config = {
    auth : {
      username: 'your-username',
      apiKey: 'your-api-key'
    }
  };
  
  var client = cloudfiles.createClient(config);

Working with Containers

Rackspace Cloudfiles divides files into 'Containers'. These are very similar to S3 Buckets if you are more familiar with Amazon. There are a couple of simple operations exposed by node-cloudfiles:

  // Creating a container
  client.setAuth(function () {
    client.createContainer('myContainer', function (err, container) {
      // Listing files in the Container 
      container.getFiles(function (err, files) {

      });
    });
  });

Uploading and Downloading Files

Each Container has a set of 'StorageObjects' (or files) which can be retrieved via a Cloudfiles client. Files are downloaded to a local file cache that can be configured per client.

  client.createContainer('myContainer', function (err, container) {
    //
    // Uploading a file
    //
    client.addFile('myContainer', 'remoteName.txt', 'path/to/local/file.txt', function (err, uploaded) {
      // File has been uploaded
    });
  
    //
    // Downloading a file
    //
    client.getFile('myContainer', 'remoteName.txt', function (err, file) {
      //
      // Save it to a location outside the cache
      //
      file.save({ local: 'path/to/local/file.txt' }, function (err, filename) {
        //
        // File has been saved.
        //
      });
    });
  });

Authentication Service

Use the 'host' key in the auth configuration to specify the url to use for authentication:

  var cloudfiles = require('cloudfiles');
  var config = {
    auth : {
      username: 'your-username',
      apiKey: 'your-api-key',
      host : "lon.auth.api.rackspacecloud.com"
    }
  };

  var client = cloudfiles.createClient(config);

Roadmap

1. Implement Storage Object metadata APIs.

Run Tests

All of the node-cloudservers tests are written in vows, and cover all of the use cases described above. You will need to add your Rackspace API username and API key to test/fixtures/test-config.json before running tests:

  {
    "auth": {
      "username": "your-username",
      "apiKey": "your-apikey"
    }
  }

Once you have valid Rackspace credentials you can run tests with vows:

  vows test/*-test.js --spec

Author: Charlie Robbins

Contributors: Fedor Indutny, aaronds