@yawetse/pkgcloud/docs/providers/openstack/storage.md

An infrastructure-as-a-service agnostic cloud library for node.js

## Using the Openstack Storage provider

* Container
  * [Model](#container-model)
  * [APIs](#container-apis)
* File
  * [Model](#file-model)
  * [APIs](#file-apis)
  
Creating a client is straight-forward:

``` js
  var openstack = pkgcloud.storage.createClient({
    provider: 'openstack', // required
    username: 'your-user-name', // required
    password: 'your-password', // required
    authUrl: 'your identity service url' // required
  });
```

**Note:** *Due to variances between OpenStack deployments, you may or may not need a `region` option.*

Learn about [more options for creating clients](README.md) in the Openstack `storage` provider.

### Container Model

A Container for Openstack has following properties:

```Javascript
{
  name: 'my-container',
  count: 1, // number of files in your container
  bytes: 12345, // size of the container in bytes
  metadata: { // key value pairs for the container
    // ...
  }
}
```

### File Model

A File for Openstack has the following properties:

```Javascript
{
  name: 'my-file',
  container:  'my-container', // may be an instance of container if provided
  size: 12345, // size of the file in bytes
  contentType: 'plain/text' // Mime type for the file
  lastModified: Fri Dec 14 2012 10:16:50 GMT-0800 (PST), // Last modified date of the file
  etag: '1234567890abcdef', // MD5 sum of the file
  metadata: {} // optional object metadata
}
```

### Container APIs

* [`client.getContainers(function(err, containers) { })`](#clientgetcontainersfunctionerr-containers--)
* [`client.getContainer(container, function(err, container) { })`](#clientgetcontainercontainer-functionerr-container--)
* [`client.createContainer(container, function(err, container) { })`](#clientcreatecontainercontainer-functionerr-container--)
* [`client.destroyContainer(container, function(err, result) { })`](#clientdestroycontainercontainer-functionerr-result--)
* [`client.updateContainerMetadata(container, function(err, container) { })`](#clientupdatecontainermetadatacontainer-functionerr-container--)
* [`client.removeContainerMetadata(container, metadataToRemove, function(err, container) { })`](#clientremovecontainermetadatacontainer-metadatatoremove-functionerr-container--)

### Container API Details

For all of the container methods, you can pass either an instance of [`container`](#container) or the container name as `container`. For example:

```Javascript
client.getContainer('my-container', function(err, container) { ... });
```

This call is functionally equivalent to:

```Javascript
var myContainer = new Container({ name: 'my-container' });

client.getContainer(myContainer, function(err, container) { ... });
```

#### client.getContainers(function(err, containers) { })

Retreives the containers for the current client instance as an array of [`container`](#container-model)

#### client.getContainer(container, function(err, container) { })

Retrieves the specified [`container`](#container-model) from the current client instance.

#### client.createContainer(container, function(err, container) { })

Creates a new [`container`](#container-model) with the name from argument `container`. You can optionally provide `metadata` on the request:

```javascript
client.createContainer({
 name: 'my-container',
 metadata: {
  brand: 'bmw',
  model: '335i'
  year: 2009
 }}, function(err, container) {
  // ...
 })
```

#### client.destroyContainer(container, function(err, result) { })

Removes the [`container`](#container-model) from the storage account. If there are any files within the `container`, they will be deleted before removing the `container` on the client. `result` will be `true` on success.

#### client.updateContainerMetadata(container, function(err, container) { })

Updates the metadata on the provided [`container`](#container-model) . Currently, the `updateContainer` method only adds new metadata fields. If you need to remove specific metadata properties, you should call `client.removeContainerMetadata(...)`.

```javascript
container.metadata.color = 'red';
client.updateContainerMetadata(container, function(err, container) {
  // ...
})
```

#### client.removeContainerMetadata(container, metadataToRemove, function(err, container) { })

Removes the keys in the `metadataToRemove` object from the stored [`container`](#container-model) metadata.

```Javascript
client.removeContainerMetadata(container, { year: false }, function(err, c) {
  // ...
});
```

### File APIs

* [`client.upload(options)`](#clientuploadoptions)
* [`client.download(options, function(err, file) { })`](#clientdownloadoptions-functionerr-file--)
* [`client.getFile(container, file, function(err, file) { })`](#clientgetfilecontainer-file-functionerr-file--)
* [`client.getFiles(container, function(err, file) { })`](#clientgetfilescontainer-functionerr-file--)
* [`client.removeFile(container, file, function(err, result) { })`](#clientremovefilecontainer-file-functionerr-result--)
* [`client.updateFileMetadata(container, file, function(err, file) { })`](#clientupdatefilemetadatacontainer-file-functionerr-file--)

### File API Details

For all of the file methods, you can pass either an instance of [`container`](#container-model) or the container name as `container`. For example:

```Javascript
client.getFile('my-container', 'my-file', function(err, file) { ... });
```

This call is functionally equivalent to:

```Javascript
var myContainer = new Container({ name: 'my-container' });

client.getFile(myContainer, 'my-file', function(err, file) { ... });
```

#### client.upload(options)
Returns a `writableStream`. Upload a new file to a [`container`](#container-model). `writableStream` will emit `success` on completion of the upload, and will emit `error` on any failure. Function for `success` is `function(file) { ... }` where `file` is a [`file`](#file-model) model

To upload a file, you need to provide an `options` argument:

```Javascript
var options = {
    // required options
    container: 'my-container', // this can be either the name or an instance of container
    remote: 'my-file', // name of the new file
    contentType: 'application/json', // optional mime type for the file, will attempt to auto-detect based on remote name
    size: 1234 // size of the file
};
```

```Javascript
  var readStream = fs.createReadStream('a-file.txt');
  var writeStream = client.upload({
    container: 'a-container',
    remote: 'remote-file-name.txt'
  });

  writeStream.on('error', function(err) {
    // handle your error case
  });

  writeStream.on('success', function(file) {
    // success, file will be a File model
  });

  readStream.pipe(writeStream);
```

#### client.download(options, function(err, file) { })

Returns a readable stream. Download a [`file`](#file-model) from a [`container`](#container-model).

To download a file, you need to provide an `options` argument:

```Javascript
var options = {
    // required options
    container: 'my-container', // this can be either the name or an instance of container
    remote: 'my-file', // name of the new file

    // optional, either stream or local
    stream: myStream, // any instance of a writeable stream
    local: '/path/to/local/file' // the path to a local file to write to
};
```

You need not provide either `stream` or `local`. `client.download` returns a readable stream, so you can simply pipe it into your writeable stream. For example:

```Javascript
var fs = require('fs'),
    pkgcloud = require('pkgcloud');

var client = pkgcloud.providers.openstack.storage.createClient({ ... });

var myFile = fs.createWriteStream('/my/local/file');

client.download({
    container: 'my-container',
    remote: 'my-file'
}, function(err, result) {
    // handle the download result
})).pipe(myFile);
```

You could also download to a local file via the `local` property on `options`:

```Javascript
var pkgcloud = require('pkgcloud');

var client = pkgcloud.providers.openstack.storage.createClient({ ... });

client.download({
    container: 'my-container',
    remote: 'my-file',
    local: '/path/to/my/file'
}, function(err, result) {
    // handle the download result
});
```

This is functionally equivalent to piping from an `fs.createWriteStream`, but has a simplified calling convention. 

#### client.getFile(container, file, function(err, file) { })

Retrieves the specified [`file`](#file-model) details in the specified [`container`](#container-model) from the current client instance.

#### client.getFiles(container, function(err, files) { })

Retreives an array of [`file`](#file-model) for the provided [`container`](#container-model).

#### client.removeFile(container, file, function(err, result) { })

Removes the provided [`file`](#file-model) from the provided [`container`](#container-model).

#### client.updateFileMetadata(container, file, function(err, file) { })

Updates the [`file`](#file-model) metadata in the the provided [`container`](#container-model).

File metadata is completely replaced with each call to updateFileMetadata. This is different than container metadata. To delete a property, just remove it from the metadata attribute on the `File` and call `updateFileMetadata`.
```javascript
file.metadata = {
 campaign = '2011 website'
};

client.updateFileMetadata(file.container, file, function(err, file) {
  // ...
});
```