High available Node Client for OpenStack Switf Object Storage

High availability, Performances, and Simplicity are the main focus of this tiny Node SDK to request the OpenStack Object Storage API. It was initially made to request the OVHCloud Object storage, but it can be used for any OpenStack Object Storage.

Highlights

• 🦄 Simple to use - Only 5 methods: uploadFile, deleteFile, listFiles, downloadFile and request for custom requests.
• 🌎 High availability - Initiate the SDK with a list of object storages credentials, and the SDK will switch storage if something goes wrong (Server/DNS not responding, timeout, error 500, too many redirection, authentication error, and more...).
• ✨ Reconnect automatically - If a request fails due to an authentication token expiration, the SDK fetches a new authentication token and retry the initial request with it.
• 🚀 Performances - Less than 500 lines of code with only 2 dependencies simple-get and debug.
• ✅ 100% tested - Battle-tested against hundreds of GBs of file uploads & downloads

Install

1. Prior installing

you need a minimum of one object storage container, or you can synchronize Object Storages containers in order to access same objects if a fallback occur:

• Sync 2 containers: 1 <=> 2. They would both need to share the same secret synchronization key.
• You can also set up a chain of synced containers if you want more than two. You would point 1 -> 2, then 2 -> 3, and finally 3 -> 1 for three containers. They would all need to share the same secret synchronization key. Learn more on the OpenStack documentation or on the OVHCloud documentation.

$ pip install python-swiftclient

1$ source openrc.sh

1$ sharedKey=$(openssl rand -base64 32)

1env | grep OS_REGION

1destContainer=$(swift --debug stat containerBHS 2>&1 | grep 'curl -i.*storage' | awk '{ print $4 }') && echo $destContainer

1OS_REGION_NAME=RegionSource

1$ swift post -t ‘//OVH_PUBLIC_CLOUD/RegionDestination/AUTH_xxxxxxxxx/containerNameDestination’ -k "$sharedKey" containerNameSource

1$ swift stat containerName

1$ OS_REGION_NAME=RegionSource && swift list containerName
2$ OS_REGION_NAME=RegionDestination && swift list containerName

2. Install the package with your package manager:

1$ npm install --save high-availability-object-storage
2// od
3$ yarn add high-availability-object-storage

API Usage

Connection

Initialise the SDK with one or multiple storage, if something goes wrong, the next region will take over automatically. If any storage is available, an error message is returned Error: Object Storages are not available.

1const storageSDK = require('high-availability-object-storage');
2
3let storage = storageSDK([{
4  authUrl    : 'https://auth.cloud.ovh.net/v3',
5  username   : 'username-1',
6  password   : 'password-1',
7  tenantName : 'tenantName-1',
8  region     : 'region-1'
9},
10{
11  authUrl    : 'https://auth.cloud.ovh.net/v3',
12  username   : 'username-2',
13  password   : 'password-2',
14  tenantName : 'tenantName-2',
15  region     : 'region-2'
16}]);
17
18storage.connection((err) => {
19  if (err) {
20    // Invalid credentials
21  }
22  // Success, connected!
23})

Upload a file

1const path = require(path);
2
3/** SOLUTION 1: The file content can be passed by giving the file absolute path **/
4storage.uploadFile('container', 'filename.jpg', path.join(__dirname, './assets/file.txt'), (err) => {
5  if (err) {
6    // handle error
7  }
8  // success
9});
10
11/** SOLUTION 2: A buffer can be passed for the file content **/
12storage.uploadFile('container', 'filename.jpg', Buffer.from("File content"), (err) => {
13  if (err) {
14    // handle error
15  }
16  // success
17});
18
19/** SOLUTION 3: the function accepts a optionnal fourth argument `option` including query parameters and headers. List of query parameters and headers: https://docs.openstack.org/api-ref/object-store/?expanded=create-or-replace-object-detail#create-or-replace-object **/
20storage.uploadFile('container', 'filename.jpg', Buffer.from("File content"), { queries: { temp_url_expires: '1440619048' }, headers: { 'X-Object-Meta-LocationOrigin': 'Paris/France' }}, (err) => {
21  if (err) {
22    // handle error
23  }
24  // success
25});

Download a file

1storage.downloadFile('templates', 'filename.jpg', (err, body, headers) => {
2  if (err) {
3    // handle error
4  }
5  // success, the `body` argument is the content of the file as a Buffer
6});

Delete a file

1storage.deleteFile('templates', 'filename.jpg', (err) => {
2  if (err) {
3    // handle error
4  }
5  // success
6});

List objects from a container

1/**
2 * SOLUTION 1
3 **/
4storage.listFiles('templates', function (err, body) {
5  if (err) {
6    // handle error
7  }
8  // success
9});
10
11/**
12 * SOLUTION 2
13 * Possible to pass queries and overwrite request headers, list of options: https://docs.openstack.org/api-ref/object-store/? expanded=show-container-details-and-list-objects-detail#show-container-details-and-list-objects
14 **/
15storage.listFiles('templates', { queries: { prefix: 'prefixName' }, headers: { Accept: 'application/xml' } }, function (err, body) {
16  if (err) {
17    // handle error
18  }
19  // success
20});

Get file metadata

Shows object metadata. Checkout the list of headers.

1storage.getFileMetadata('templates', 'filename.jpg', (err, headers) => {
2  if (err) {
3    // handle error
4  }
5  /**
6   * Returned headers: {
7   *  Content-Length: 14
8   *  Accept-Ranges: bytes
9   *  Last-Modified: Thu, 16 Jan 2014 21:12:31 GMT
10   *  Etag: 451e372e48e0f6b1114fa0724aa79fa1
11   *  X-Timestamp: 1389906751.73463
12   *  X-Object-Meta-Book: GoodbyeColumbus
13   *  Content-Type: application/octet-stream
14   *  X-Trans-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
15   *  X-Openstack-Request-Id: tx37ea34dcd1ed48ca9bc7d-0052d84b6f
16   *  Date: Thu, 16 Jan 2014 21:13:19 GMT
17   *  X-Object-Meta-Custom-Metadata-1: Value
18   *  X-Object-Meta-Custom-Metadata-2: Value
19   * }
20   * // Details: https://docs.openstack.org/api-ref/object-store/?expanded=show-object-metadata-detail#show-object-metadata
21   */
22});

Set file metadata

To create or update custom metadata, use the "X-Object-Meta-name" header, where name is the name of the metadata item. The function overwrite all custom metadata applied on the file. Checkout the list of headers availables.

1storage.setFileMetadata('templates', 'filename.jpg', { headers: { 'Content-Type': 'image/jpeg', 'X-Object-Meta-LocationOrigin': 'Paris/France', 'X-Delete-At': 1440619048 }} (err, headers) => {
2  if (err) {
3    // handle error
4  }
5  // success
6});

Custom request

The request function can be used to request the object storage with custom options. Prototype to get the data as Buffer:

1request(method, path, { headers, queries, body }, (err, body, headers) => {}).

Prototype to get the data as Stream, set the option stream:true:

1request(method, path, { headers, queries, body, stream: true }, (err, dataStream) => {})`.

The base URL requests by default the account, passing an empty string will request the account details. For container requests, pass the container name, such as: /{container}. For file requests, pass the container and the file, such as: /{container}/{filename}. Object Storage Swift API specification: https://docs.openstack.org/api-ref/object-store/

The request function automatically reconnects to the Object Storage or switch storage if something goes wrong.

Example of custom request, bulk delete file from a customerDocuments container:

1  const _headers = {
2    'Content-Type': 'text/plain',
3    'Accept'      : 'application/json'
4  }
5
6 storage.request('POST', '/customerDocuments?bulk-delete', { headers: _headers, body: 'file1\nfile2\n' }, (err, body, headers) => {
7  /**
8  * body: {
9  *  "Number Not Found": 0,
10  *  "Response Status": "200 OK",
11  *  "Errors": [],
12  *  "Number Deleted": 2,
13  *  "Response Body": ""
14  * }
15  */
16  done();
17});

Log

The package uses debug to print logs into the terminal. To activate logs, you must pass the DEBUG=* environment variable. You can use the setLogFunction to override the default log function. Create a function with two arguments: message as a string, level as a string and the value can be: info/warning/error. Example to use:

1storage.setLogFunction((message, level) => {
2  console.log(`${level} : ${message}`);
3})

Run tests

Install

1$ npm install

To run all the tests:

1$ npm run test

🤝 Contributing

Contributions, issues and feature requests are welcome!

Feel free to check issues page.

Show your support

Give a ⭐️ if this project helped you!

👤 Author

• @steevepay