Interface Connection

Connection is something like an interface which is implemented in both require('osapi/s3').Connection and require('osapi/swift').Connection. There are three ways to retrieve an instance of Connection:

// 1.
const osapi = require('osapi');
let conn = osapi.createConnection(options);

// 2.
const swift = require('osapi/swift');
let conn = new swift.Connection(options);

// 3.
const s3 = require('osapi/s3');
let conn = new s3.Connection(options);

The returned conn is actually an instance of s3.Connection or swift.Connection according to what properties owned by options.

APIs

Both instances of s3.Connection and swift.Connection SHOULD implement the following methods. However, they may offer other special methods, and accept other properties of options besides those described in this chapter.

In most cases, to accommodate developers familiar with Swift, it is allowed to replace bucket with container in both method names and options names. E.g., createContainer() is equivalent to createBucket(), and options.container is equivalent to options.bucket. And vice versa.

ATTENTION: Some properties of options and result in this document are not always available. E.g.

[ swift ]
Only avaiable for servers compatible with swift-style API.
[ s3 ]
Only avaiable for servers compatible with s3-style API.
[ AWS S3 ]
Only avaiable for AWS S3 server.
[ Aliyun OSS | AWS S3 ]
Available for Aliyun OSS or AWS S3 servers.
[ CEPH + s3 ]
Only avaiable for CEPH server with s3-style API.

We cannot blame such shortcoming on dependency APIs offered by storage servers. Mostly, it is due to the imperfectness of this package itself.

All asynchronuous methods are promisible. That means, if callback passed in, the method will return the Connection instance itself, and the callback function will be invoked when the operation accomplished or failed. Otherwise, a Promise instance will be returned.

If callback offered, it SHOULD be a standard Error-First callback function with parameters (err, data).

// With `callback` passed in, the `conn` itself will be returned.
// So that chained invocation is avaiable.
conn
	.<method1>(options, (error, result) => {
		// ...
	})
	.<method2>(options, (error, result) => {
		// ...
	});

// Without `callback` passed in, a `Promise` instance will be returned.
conn.<method>(options)
	.then(result => {
		// ...
	})
	.catch(error => {
		// ...
	})
	;

Hereinafter, result will refer to which in callback(err, result) or .then(result => { ... }). Maybe you will find some other properties of result that not I have not declared, PLEASE ignore them because even myself don't know what they represent.

If you need more information in case of failures, see OsapiError for details. But, not all errors are instance of OsapiError.

Constructor

s3.Connection and swift.Connection accept different options. Please read correnspond documents.

[- toc -]¹

isConnected()

boolean __<conn>.isConnected()

This method will tell you whether the connection is ready for real execuations. It is not necessary to avoid invoking other methods before conn.isConnected(). You may call something like conn.createObject() immediately when the Connection instance is created. If conn is not ready at that time, your operations will be staged in a queue.

[- toc -]¹

-- Bucket / Container --

createBucket()

Promise | Connection <conn>.createBucket( string name [, Function callback ] )
Promise | Connection <conn>.createBucket( object options [, Function callback ] )

So far, options accepts following properties:

options.name string
Bucket name.
options.meta object OPTIONAL
User-defined meta data you wanna attach to the bucket.
[ CEPH + swift ]

Once resolved:

result.requestId string
Request / transaction Id.

ATTNENTION: NO error will be thrown if the bucket already exists.

[- toc -]¹

deleteBucket()

Promise | Connection <conn>.deleteBucket( string name [, Function callback ] )
Promise | Connection <conn>.deleteBucket( object options [, Function callback ] )

So far, options accepts following properties:

options.name string
Bucket name.

Once resolved:

result.requestId string
Request / transaction Id.

ATTNENTION: NO error will be thrown if the bucket not found.

[- toc -]¹

readBucket()

Promise | Connection <conn>.readBucket( string name [, Function callback ] )
Promise | Connection <conn>.readBucket( object options [, Function callback ] )

So far, options accepts following properties:

options.name string
Name of bucket.
options.suppressNotFoundError boolean
Don't threw exception on 404 Not Found.

Once resolved:

result.requestId string
Request / transaction Id.
result.region string
Region of bucket.
[ Aliyun OSS | AWS S3 ]
result.objectCount number
Number of objects stored in the bucket.
[ CEPH ]
result.bytesUsed number
Totoal size of objects stored in the bucket.
[ CEPH ]
result.meta object OPTIONAL
User-defined meta data attached to the bucket.
If there is no user-defined meta data, this property will be undefined instead of empty {}.
[ CEPH + swift ]
result.storagePolicy string OPTIONAL
Storage policy of the bucket.
[ CEPH + swift ]

[- toc -]¹

findBuckets()

Promise | Connection <conn>.findBuckets( object options [, Function callback ] )

So far, options accepts following properties:

options.prefix string OPTIONAL
Prefix of bucket name.
[ CEPH + swift ]
options.marker string OPTIONAL
Marker (a bucket name) to start with.
[ CEPH + swift ]
The marker will be compared with buckets' names. Only those whit name greater than the marker will be responsed. So, the one whose name equals to the marker will not be in the responsed list.
options.limit number OPTIONAL
Number of buckets to be responsed at most.
[ CEPH + swift ]

Once resolved, the result should be an array:

result Bucket[]

Here, Bucket is an object contains:

name string Bucket name.
created Date
When the bucket is created. [ s3 ]
objectCount number
Number of objects stored in the bucket.
[ swift ]
bytesUsed number
Totoal size of objects stored in the bucket.
[ swift ]

[- toc -]¹

-- Object --

In the following methods, conn.bucket will be used by default. However, if neither conn.bucket nor options.bucket here, an error will be thrown.

createObject()

Promise | Connection <conn>.createObject( string name, content [, Function callback ] )
Promise | Connection <conn>.createObject( object options, content [, Function callback ] )

Parameters:

name string
If the first argument is a string, it will be regarded as object name.
options object
See next paragraph for details.
content string | Buffer | stream.Readable
Content of the object.

So far, options accepts following properties:

options.acl string OPTIONAL
ACL is abbreviation of "Access Control List".
[ s3 ]

Generally, valid values are:
- private
- public-read
- public-read-write
- authenticated-read
ATTNETION: NOT all servers accept all above values.
options.bucket string OPTIONAL
Bucket name.
options.contentType string OPTIONAL
MIME value.
options.name string
Object name.
options.meta object OPTIONAL
User-defined meta data associated with the object.

Once resolved:

result.requestId string
Request / transaction Id.
result.etag string
ETag of created object.

ATTNENTION: NO error will be thrown if the object already exists.

[- toc -]¹

copyObject()

Promise | Connection <conn>.copyObject( string source, string target [, Function callback ] )
Promise | Connection <conn>.copyObject( object source, object target [, Function callback ] )

Parameters:

source string | object
Represent the source object.
If being string, it is regarded as the object name. Otherwise it may contain the following properties:
- source.name string
- source.bucket string OPTIONAL
target string | object
Represent the target object.
If being string, it is regarded as the object name. Otherwise it may contain the following properties:
- target.name string
- target.bucket string OPTIONAL

Once resolved:

result.requestId string
Request / transaction Id..b

[- toc -]¹

deleteObject()

Promise | Connection <conn>.deleteObject( string name [, Function callback ] )
Promise | Connection <conn>.deleteObject( object options [, Function callback ] )

Parameters:

name string
If the first argument is a string, it will be regarded as object name.
options object
See next paragraph for details.

So far, options accepts following properties:

options.bucket string OPTIONAL
Bucket name.
options.name string
Object name.

Once resolved:

result.requestId string
Request / transaction Id.

ATTNENTION: NO error will be thrown if the object not found.

[- toc -]¹

readObject()

Promise | Connection <conn>.readObject( string name [, Function callback ] )
Promise | Connection <conn>.readObject( object options [, Function callback ] )

Parameters:

name string
If the first argument is a string, it will be regarded as object name.
options object
See next paragraph for details.

So far, options accepts following properties:

options.bucket string OPTIONAL
Bucket name.
options.name string
Object name.
options.onlyMeta boolean OPTIONAL DEFAULT(false)
Response without object content.
options.suppressNotFoundError boolean OPTIONAL DEFAULT(false)
Don't threw exception on 404 Not Found.

Once resolved:

result.requestId string
Request / transaction Id.
result.buffer Buffer
Object content.
result.contentLength number
Content length.
WARNING: This meaning of this property may be ambiguous.
result.contentType string
MIME value.
result.etag string
ETag.
result.lastModified Date
Last modified time.
result.meta object OPTIONAL
User-defined meta data attached to the object.
If there is no user-defined meta data, this property will be undefined instead of empty {}.

[- toc -]¹

readObjectMeta()

Promise | Connection <conn>.readObjectMeta( string name [, Function callback ] )
Promise | Connection <conn>.readObjectMeta( object options [, Function callback ] )

See documentation about readObject() for details.

[- toc -]¹

updateObjectUserMeta()

Promise | Connection <conn>.readObjectMeta( string name, object usermeta [, Function callback ] )
Promise | Connection <conn>.readObjectMeta( object options, object usermeta [, Function callback ] )

So far, options accepts following properties:

options.bucket string OPTIONAL
Bucket name.
options.name string
Object name.
options.replace boolean OPTIONAL DEFAULT(false)
Delete all the old user meta fields.

[- toc -]¹

findObjects()

Promise | Connection <conn>.findObjects( object options [, Function callback ] )

So far, options accepts following properties:

options.delimiter string OPTIONAL DEFAULT('/')
Path delimiter.
See pseudo directory for details.
options.limit number OPTIONAL DEFAULT(?)
Number of buckets to be responsed at most.
options.marker string OPTIONAL
Marker to start with.
The marker will be compared with objects' (or directories') names. Only those whit name greater than the marker will be responsed. So, the one whose name equals to the marker will not be in the responsed list.
options.path string OPTIONAL
Leading path.
See pseudo directory for details.
options.prefix string OPTIONAL
Prefix of object name.

Once resolved, the result should be an array:

result item[]

Here, item generally represents an object. Under certain conditions, it may also represent a pseudo directory.

An item represents an object contains:

etag string
ETag.
lastModified Date
When the object is created.
name string
Object name.
size number
Object size (in bytes).

And item represents a pseudo directory contains:

dirname string
Pesudo sub directory name which ends with a delimiter ('/' by default).
See pseudo directory for details.

[- toc -]¹

Footnotes

#table-of-contents ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹² ↩¹³

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

connection.md

connection.md

Interface Connection

Table of Contents

APIs

Constructor

isConnected()

-- Bucket / Container --

createBucket()

deleteBucket()

readBucket()

findBuckets()

-- Object --

createObject()

copyObject()

deleteObject()

readObject()

readObjectMeta()

updateObjectUserMeta()

findObjects()

Files

connection.md

Latest commit

History

connection.md

File metadata and controls

Interface Connection

Table of Contents

APIs

Constructor

isConnected()

-- Bucket / Container --

createBucket()

deleteBucket()

readBucket()

findBuckets()

-- Object --

createObject()

copyObject()

deleteObject()

readObject()

readObjectMeta()

updateObjectUserMeta()

findObjects()

Footnotes