racker/Readme.md

Robust Rackspace cloudfiles client

# Racker

Elegant [Rackspace](//rackspace.com) [cloudfiles](//rackspace.com) client.

```javascript
var racker = require('racker');

racker
  .set('user', 'foo')
  .set('key', '...')
  .upload(__dirname + '/Makefile')
  .to('make files')
  .as('makefile')
  .on('progress', console.log.bind(console))
  .end(function (err, res) {});
```

## Features

  * Container / Object metadatas.
  * Uploading streams / localfiles / buffers
  * Upload progress support.
  * Elegant API
  * Authenticates automagically.

## Installation

    $ npm install racker

## Getting started

##### Authentication

Racker authenticates automatically once you attempt to issue
a request, it will also re authenticate automatically if the token
has expired.

So you just need to set your credentials and you'r ready to issue
requests.

```javascript
var racker = require('racker');

racker
  .set('user', 'username')
  .set('key', '...')
  .set('host', 'us'); // defaulted to us
```

That's it this Racker instance will now wait until you attempt
to issue a request.

##### Creating a container

```javascript
racker
  .create('my images')
  .set('X-Container-Meta-Type', 'png')
  .end(function (err, res) {});
```

##### Updating a container

```javascript
racker
  .update('my images')
  .set('X-Container-Meta-Type', 'png, jpg')
  .end(function (err, res) {});
```

##### Uploading a file

Local file.
```javascript
racker
  .upload('cat.png')
  .to('my images')
  .as('lion.png')
  .end(function (err, res) {});
```

Stream.
```javascript
racker
  .upload(fs.createReadStream('cat.png'))
  .to('my images')
  .as('lion.png')
  .end(function (err, res) {});
```

Buffer.
```javascript
racker
  .upload(new Buffer('mew'))
  .to('my images')
  .as('roar')
  .end(function (err, res) {});
```

##### Deleting a file

```javascript
racker
  .del('cats container', 'cat.png')
  .end(function (err, res) {});
```

##### Deleting a container

```javascript
racker
  .del('cats container')
  .end(function (err, res){});
```

##### Listing stuff

Note that the list is always defaulted to `json` and will be parsed
for you by superagent, the length of the list is defaulted to `50`
you can change those with `.query()` parameters

```javascript
// containers
racker
  .list(function (err, res) {
    res.body;
    // > an array of containers.
  });

// objects from a container
racker
  .list('my images')
  .end(function (err, res){
    res.body;
    // > an array of objects
  });

// listing more than 50 at once
racker
  .list('my images')
  .query('limit=500')
  .end(function (err, res){
    res.body;
    // > an array of 500 objects.
  });
```

### Running Tests

To run the test suite create a `test/auth.json`:

```json
{
  "user": "<username>",
  "host": "<host-either-us-or-uk>",
  "test": "<container-name>",
  "key": "<access-key>"
}
```

Then run:

```bash
$ npm install
$ make test
```

that's it.

### Contributing

I accept pull requests this library is not yet full featured,
i have several features i plan on implementing see todos below.

### todos

  * List container objects.
  * List all containers.
  * Tests on updating object metadata.
  * implement `request.meta()` to set object / container metas.
  * implement `response.meta()` to get object / container metas.
  * implement large object uploads.
  * Test wether or not re-authentication works..

## License

MIT