os²

OpenStack Object Storage wrapper for Node.js

os² is a wrapper for the OpenStack Object Storage API v1. Use it to communicate with an Object Storage via it's REST api without managing the HTTP requests.

Features

• Abstractions to write and read data from an Object Storage using Node.js streams.
• Authentication to the OpenStack Object Storage using the TempAuth method. (No production, contributions are welcome)
• Asynchronous communication using ES6 Promise
• Support for Large Objects

Getting started

Installation

Installing globally from the npm package manager:

npm install os2 --global

Or add os² as a dependency to a node.js project using the package.json file:

"dependencies": {
  "os2": "0.0.1"
}

and then update the project's dependencies

npm install

Import

Import os² components as any Node.js package. For example, all os² components at once :

const os2 = require('os2');

Or, to import os² components separately:

// pick only what you need, lol
const { Store, Account, Container, Segment, DynamicLargeObject, StaticLargeObject } = require('os2');

Example

// First, create a Store to connect to
let store = new Store('http://example.openstackobjectstorage:8080/');
    
// Then, make an account, give it the store and the credentials
let account = new Account(store, 'username', 'password');
    
// Authenticate with tempAuth
account.connect().then(function() {
    
        //We can now create containers using the connected account
        let container = new Container(account, 'example_container');
        
        //Perform the container creation on the object storage API
        container.create().then(function() {
    
            //Create an object inside the container
            let obj = new Segment(container, 'example_segment');
                
            //Put the content of a file into: example_container/example_segment
            obj.createFromDisk('./path/to/my/file.txt').then(function(ok) {
               // Yeah the file is created ! 
            });
        });
    });

Quick reference

1. Store
2. Account
3. Container
4. Segment
5. Dynamic Large Object
6. Static Large Object
7. Error handling

Store

A Store instance represents the Object Storage API service. It is defined by a URL of where the service is hosted.

Methods

new Store([url])

Create a new store from a URL.

• url <String> Object storage API url. Defaults to http://127.0.0.1

info()

Attempts to list activated capabilities on this Store, will fail if not configured on OpenStack.

Returns a <Promise> resolves to <Object> a json object containing the list of capabilities on success, or rejects with a <Error>.

Properties

• URL <String>: The URL in use by this Store can be read using getUrl and updated with setUrl

Account

Your service provider creates your account and you own all resources in that account. The account defines a namespace for containers. In the OpenStack environment, account is synonymous with a project or tenant.

Methods

new Account(store, [username, [password, [storage_url, [token]]]])

Create a new <Account> instance, main constructor.

• store <Store> os² Store instance where the account resides.
• username <String> Username used authenticate. Defaults to null.
• password <String> Password used authenticate. Defaults to null.
• storage_url <String> URL pointing to this account storage API.
• storage_token <String> Authentication token to use when querying the API.

Account.fromUsernameAndPassword(storeUrl, username, password)

Alternative constructor for construction from a URL and a username/password.

• storeUrl <String> An OpenStack Object Storage URL.
• username <String> Username used for authentication.
• password <String> Password used for authentication.

Returns a new <Account> instance.

Account.fromNameAndToken(storeUrl, name, token)

Alternative constructor for construction from a URL and an account name and authentication token

• storeUrl <String> An OpenStack Object Storage URL.
• name <String> As used by OpenStack in this account storage URL.
• token <String> A valid authentication token to connecting this account.

Returns a new <Account> instance.

connect()

Performs this account connection with the Store. Uses the /auth/v1.0 authentication mechanism of swift object storage

Returns a <Promise>, which resolves to true on success or rejects a native <Error> on failure.

disconnect()

Disconnects this account from the store.

Returns <Promise> that always resolves to true.

listContainers()

List all the containers in this account.

Returns <Promise> that resolves to a json array of containers on success, rejects a native <Error> otherwise.

getMetadata()

Retrieve stored metadata for this account, MUST be connected.

Returns <Promise>. Resolves to an object containing all the metadata on success, reject an <Error> otherwise

setMetadata(metadata)

Update metadata for this account. Omitted metadata items are unchanged, metadata items with null or undefined values are removed.

• metadata <Object> each property is considered to be a metadata item.

Returns <Promise>. Resolves to true on success, rejects a native js <Error> on failure

Properties

• connected <Boolean> Account's connection status. True if a valid authentication has been performed. Access it with isConnected
• store <Store> An account is backed by a store instance. getStore and setStore are available.
• username <String> Username used for authentication. getUsername and setUsername
• password <String> Password used for authentication. getPassword and setPassword
• token <String> Authentication token from the store tempAuth. This property is read only: getToken
• storageUrl <String> Once authenticated, url where this account objects are. Read only : getStorageUrl
• name <String> Name of the account in the store, exctracted from strorageUrl or passed at contruction. Read only: getName

Container

Defines a namespace for objects. An object with the same name in two different containers represents two different objects. There can be any number of containers within an account.

Methods

new Container(account, name)

Creates a new Container instance.

• account <Account> A valid instance of Account the new container will belong to.
• name <String> Is the namespace representing the container on the object store.

create()

Creates or updates the container instance in the object storage.

Returns a <Promise> which resolves to the object storage response on success, on error it rejects a native js Error.

delete()

Delete the container instance in the object storage.

Returns a <Promise> which resolves to the object storage response on success, on error it rejects a native js Error.

setMetadata(metadata)

Update metadata associated with the container. Omitted metadata items are unchanged, metadata items with null or undefined values are removed.

• metadata <Object> each property is considered to be a metadata item.

Returns <Promise>. and resolves to true on success, rejects a native js <Error> on failure

getMetadata()

Retrieve the stored metadata in this container.

Returns <Promise>. Resolves to an object containing all the metadata on success, reject an <Error> otherwise

listObjects()

Get details and objects list from the container. Returns a <Promise> which resolves to the json content of the container or rejects an <Error> instance.

Properties

• account <Account> A valid Account instance where the container belongs. getAccount and setAccount are available.
• name <String> The container identifier. getName and setName are available.

Segment

Stores data content, such as documents, images, and so on. You can also store custom metadata with an object.

Methods

new Segment(container, name)

Create a new Segment/Object in the container.

• container <Container> An instance of a container for the Segment
• name <String> As the name or identifier for the Segment

createFromDisk(filepath)

Assign the segment's content from a file on disk, replaces its content if already exists.

• filepath <String> Absolute or relative path to the file on disk

Returns a <Promise>. It resolves to true on success, on error it rejects a <Error>

createFromStream(readStream)

Assign the segment's content from stream, replaces its content if already exists

• readStream Segment content in the form of a Node.js <stream.Readable> instance

Returns a <Promise>. It resolves to true on success, on error it rejects a <Error>

delete()

Delete this object form the Object Storage.

Returns a <Promise>. It resolves to true on success, on error it rejects a <Error>

copy

Copies this object to the destination object. If the destination object is already created in the Object storage, it is replaced If the source segment is a Large Object, the manifest is copied, referencing the same content.

• object <Segment> As a destination object

Returns a <Promise>. It resolves to true on success, on error it rejects a <Error>

getContentStream()

Get a stream readable on the segment content

Returns a <Promise>. It resolves to a <stream.Readable> on success. A javascript <Error> is rejected on error.

setMetadata(metadata)

Update metadata associated with the Segment. Omitted metadata items are unchanged, metadata items with null or undefined values are removed.

• metadata <Object> each property is considered to be a metadata item.

Returns <Promise>. and resolves to true on success, rejects a native js <Error> on failure

getMetadata()

Retrieve the stored metadata with this segment.

Returns <Promise>. Resolves to an object containing all the metadata on success, reject an <Error> otherwise

Properties

• name <String> Identifier or name for the segment. getName and setName methods are provided.
• container <Container> An instance of a container the segment is stored into. getContainer and setContainerare available.

DLO

A DynamicLargeObject contains multiple Segments. It is defined by a container: where the segment objects are stored; and a prefix: a string that all segment objects have in common.

Methods

new DynamicLargeObject(container, name, [prefix]) {

Create a new DynamicLargeObject or DLO.

• container <Container> An instance of a container for the DLO
• name <String> As the name or identifier of the DLO

createManifest()

Creates or updates this DLO manifest

Returns <Promise>. and resolves to true on success, rejects a js <Error> otherwise.

createFromStream

Creates a SLO from a single stream.

• stream <stream.Readable> A readable stream providing the content
• chunkSize Optional maximum size of the generated segments. Default and max to 1Go

Returns <Promise>. Resolves to a map of segments:status on success and rejects a js <Error> otherwise.

createFromDisk(filePath[, chunkSize])

Create a dlo from a file on disk. The file gets split in segments if needed.

• path <String> Path of the source file on the disk.
• chunkSize Optional maximum size of the generated segments. Default to 5Go.

Returns <Promise>. Resolves to a map of segments:status on success and rejects a js <Error> otherwise.

createFromStreams(streams)

Create a DLO from multiple data streams, where each stream is stored as a segment. The created DLO contains the concatenated content of the streams, ordered as received

• streams <Array> An array of streams to get the data from.

Returns <Promise>. Resolves to a map of segments:status on success and rejects a js <Error> otherwise.

getContentStream([manifest])

Get the DLO content or its manifest content.

• manifest <Boolean> Set to true to get the manifest, false for the content. Defaults to false.

Returns a <Promise>. It resolves to a <stream.Readable> on success. A javascript <Error> is rejected on error.

Inherited methods from Segment

• delete
• copy
• getMetadata
• setMetadata

Properties

• prefix <String> A DLO has a prefix to identify which segments are part of the DLO. Accessors are getPrefix and setPrefix.

Inherited properties from Segment

• name
• container

SLO

A StaticLargeObject contains multiple segments, and is defined by a manifest.

Methods

new StaticLargeObject(container, name)

Creates a new StaticLargeObject or SLO.

• container <Container> An instance of a container for the SLO
• name <String> As the name or identifier of the SLO.

createManifest(manifestContent)

Creates or updates this SLO manifest

• manifestContent A json <Array>, where each element is an object representing a segment. These objects may contain the following attributes:
  • path (required). The container and object name in the format: {container-name}/{object-name}
  • etag (optional). If provided, this value must match the ETag of the segment object. This was included in the response headers when the segment was created. Generally, this will be the MD5 sum of the segment.
  • size_bytes (optional). The size of the segment object. If provided, this value must match the Content-Length of that object.
  • range (optional). The subset of the referenced object that should be used for segment data. This behaves similar to the Range header. If omitted, the entire object will be used.

Returns a <Promise>. and resolves to true on success, rejects a native js <Error> on failure

createFromStream

Creates a SLO from a single stream.

• stream <stream.Readable> A readable stream providing the content
• chunkSize Optional maximum size of the generated segments. Default and max to 1Go

Returns <Promise>. Resolves to a map of segments:status on success and rejects a js <Error> otherwise.

createFromStreams(streams)

Create a SLO from multiple data streams, where each stream is stored as a segment. The created SLO contains the concatenated content of the streams, ordered as received

• streams <Array> An array of streams to get the data from.

Returns <Promise>. Resolves to a map of segments:status on success and rejects a js <Error> otherwise.

getContentStream([manifest])

Get the SLO content or its manifest content.

• manifest <Boolean> Set to true to get the manifest, false for the content. Defaults to false.

Returns a <Promise>. It resolves to a <stream.Readable> on success. A javascript <Error> is rejected on error.

deleteWithContent()

Delete the static large object and the segments it refers to.

Returns a <Promise>. and resolves to true on success, rejects a native js <Error> on failure

Inherited methods from Segment

• delete
• copy
• getMetadata
• setMetadata

Inherited methods from DynamicLargeObject

• createFromDisk
• createFromStream

Inherited properties from Segment

• name
• container

Error

When an operation on the Object Storage API timeouts or the HTTP status code indicates an error, the Promise will reject a native javascript Error containing an error message.

let account = new Account(example_store, username, password);
account.connect().then(function() {
  // Code here
}, function (error) {
console.error(error.toString());
});