A common Object Storage API
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.
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;
});
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;
});
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 ofPromise
. - Otherwise,
callback
SHOULD be passed at the end of the arguments. - And, in style
callback(error, data)
.
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
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.
- meta
- 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.
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 ])
- class OptionAbsentError
- class RequestRefusedError
- string <instance>.action
- Object <instance>.meta
- Object <instance>.response
- number statusCode
- string statusMessage
- string code
- void <instance>.print()
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. |
For convenience, this package has following names (alias):