ksx123 / nodejs.osapi

A common Object Storage API

osapi

A common Object Storage API

Languages / 简体中文 / 繁體中文

This API is compatible with CEPH object storage, so the package is also named ceph. You may install and require one of osapi and ceph at your will.

There are two styles available: OpenStack SWIFT and Amazon S3.

Table Of Contents

• Get Started
• API
• Terms
• About
• References

Get Started

OpenStack Swift Style

const swift = require('osapi/swift');

let conn = new swift.Connection({
	endPoint   : 'http://storage.example.com/',
	subuser    : 'userName:subUserName',
	key        : '380289ba59473a368c593c1f1de6efb0380289ba5',
	             // generally 40 characters 
	tempURLKey : '380289ba59473a368c593c1f1de6efb0', 
	             // generally 32 characters
	container  : 'containerName',
});

conn.createObject('hello/world', 'Hello world!', (err) => {
	// ...
});

conn.readObject('hello/world', (err, data) => {
	// ...
	data.contentType;
	data.buffer;
});

AWS S3 Style

const s3 = require('osapi/s3');

let conn = new s3.Connection({
	endPoint        : 'http://storage.example.com/',
	accessKey       : '380289ba59473a368c59', 
	                  // 20 characters 
	secretAccessKey : '380289ba59473a368c593c1f1de6efb0380289ba5', 
	                  // 40 characters
	bucket          : 'bucketName',
});

conn.createObject({
	name: 'hello/world',
	meta: { /* self defined meta info */ }
	}, 'Hello world!', (err) => {
	// ...
});

conn.readObject('hello/world', (err, data) => {
	// ...
	data.contentType;
	data.buffer;
	data.meta;
});

API

With each osapi/* style, you should start with creating an instance of class Connection, see Get Started for examples.

Generally, methods of class Connection are ASYNCHRONOUS:

• Parameter callback is optional.
• If callback is ingored, function will return an instance of Promise.
• Otherwise, callback SHOULD be passed at the end of the arguments.
• And, in style callback(error, data).

adaptive

const osapi = require('osapi');

// See osapi/swift and osapi/s3 for details of options and member methods of the created connection.
const conn = osapi.createConnection(options);

osapi.isConnection(conn);
// RETURN: true

osapi.getConnectionStyle(conn);
// RETURN: 
// * "s3"     if conn is instance of osapi/s3.Connection
// * "swift"  if conn is instance of osapi/swift.Connection
// * null     otherwise

osapi/swift

const swift = require('osapi/swift');

• new swift.Connection(object options)
• Promise | void <conn>.createContainer(object | string options [, Function callback ])
• Promise | void <conn>.createObject(object | string options, content [, Function callback ])
• Promise | void <conn>.deleteContainer(bject | string options [, Function callback ])
• Promise | void <conn>.deleteObject(object | string options [, Function callback ])
• Promise | void <conn>.findContainers(object options [, Function callback ])
• Promise | void <conn>.findObjects(object options [, Function callback ])
• Promise | void <conn>.generateTempUrl(object | string options [, Function callback ])
• stream.Readable <conn>.pullObject(object | string options [, Function callback ])
  The return stream may emit following events:
  • meta
    Along with argument meta which contains metadata of the object.
  • events which a readable stream may emit
    See Class: stream.Readable for details.
• Promise | void <conn>.readObject(object | string options [, Function callback ])

ATTENTION: Since version 0.1.0, the entrance (main js) of osapi will be a toolset compatiable with swift and s3, and will no longer refer to osapi/swift.

osapi/s3

const swift = require('osapi/s3');

• new s3.Connection(object options)
• Promise | void <conn>.createObject(object | string options, content [, Function callback ])
• Promise | void <conn>.readObject(object | string options [, Function callback ])
• Promise | void <conn>.deleteObject(object | string options [, Function callback ])
• Promise | void <conn>.generateTempUrl(object | string options [, Function callback ])

Customised Error

• class OptionAbsentError
• class RequestRefusedError
  • string <instance>.action
  • Object <instance>.meta
  • Object <instance>.response
    • number statusCode
    • string statusMessage
    • string code
  • void <instance>.print()

Terms

Amazon Simple Storage Service (S3) and OpenStack Swift are similiar but still two different things.

S3	SWIFT	meaning
bucket	container	An container belongs to one account and is used to store objects.
access_key	-	Unique token used to identify an account.
secret_secret_key	-	Secret token accompanying the access_key and used to verify the requests.
-	key	Secret token used to generate access token for current subuser.
-	temp_url_key	Secret token used to generate temporary downloading URLs for objects.
-	user	Account.
-	subuser	User under specified account.

About

For convenience, this package has following names (alias):

• ceph
• osapi

References

• S3 vs Swift