ali-oss JavaScript SDK

Cluster mode allows you to manage multiple OSS clients across different hosts. It currently only supports object operations.

Configuration

Initialize using ClusterClient from ali-oss. You provide an array of client configurations and a schedule strategy.

Scheduling Strategies

• roundRobin: The default strategy.
• masterSlave: Routes requests to a master or slave based on the operation type.

Supported Methods

Get Methods (Uses the schedule to choose an available client):

• client.get()
• client.head()
• client.getStream()
• client.list()
• client.signatureUrl()
• client.chooseAvailable()
• client.getACL()

Put Methods (Executes the operation on ALL clients in the cluster):

• client.put()
• client.putStream()
• client.delete()
• client.deleteMulti()
• client.copy()
• client.putMeta()
• client.putACL()
• client.restore()

const Cluster = require('ali-oss').ClusterClient;

const client = Cluster({
  cluster: [
    {
      host: 'host1',
      accessKeyId: 'id1',
      accessKeySecret: 'secret1'
    },
    {
      host: 'host2',
      accessKeyId: 'id2',
      accessKeySecret: 'secret2'
    }
  ],
  schedule: 'masterSlave' // default is `roundRobin`
});

// listen error event to logging error
client.on('error', function (err) {
  console.error(err.stack);
});

// client init ready
client.ready(function () {
  console.log('cluster client init ready, go ahead!');
});

You can stop an ongoing multipart upload using two different mechanisms:

1. Abort (abortMultipartUpload)

Use this to permanently stop an upload. You must capture the checkpoint from the progress callback to get the name and uploadId. When an upload is aborted, the promise will catch an error with err.name === 'abort'.

2. Cancel (cancel)

Use this to cancel the upload via the client instance. To detect if an upload was cancelled, check store.isCancel() within the catch block.

Note: Both abort and cancel support Node.js and Browser environments.

// --- Abort Example ---
let abortCheckpoint;
store.multipartUpload('object', '/tmp/file', {
  progress: function (p, cpt, res) {
    abortCheckpoint = cpt;
  }
}).then(res => {
  // success
}).catch(err => {
  if (err.name === 'abort') {
    console.log('error: ', err.message)
  }
});

// Trigger abort
store.abortMultipartUpload(abortCheckpoint.name, abortCheckpoint.uploadId);

// --- Cancel Example ---
try {
  await store.multipartUpload('object', '/tmp/file', {
    progress: (p, cpt, res) => {}
  });
} catch (err) {
  if (store.isCancel()) {
    console.log('Upload was cancelled');
  }
}

// Trigger cancel (must use same client instance)
store.cancel();

You can use most ali-oss functionalities in the browser, but note the following limitations and requirements:

Limitations

• Streaming Uploads: put with streaming does not support chunked encoding; it uses multipart upload instead.
• Local File Downloads: Direct file system manipulation is not possible; use signed object URLs for downloading.
• Bucket Operations: Operations like listBuckets or putBucketLogging will fail because the OSS server does not currently support CORS for bucket-level operations.

Setup Requirements

1. CORS Configuration

To allow browser-side JavaScript to interact with your bucket, you must configure CORS rules on your OSS bucket:

• Allowed Origins: * (or your specific domain)
• Allowed Methods: PUT, GET, POST, DELETE, HEAD
• Allowed Headers: *
• Exposed Headers: ETag

2. Security (STS)

To avoid exposing your permanent accessKeyId and accessKeySecret in client-side code, use STS (Security Token Service) to grant temporary access.

3. Browser Compatibility

• Supported: IE >= 10, Edge, major versions of Chrome, Firefox, Safari, Android, iOS, and WP.
• Note: For browsers that do not support Promises (like IE10/11), you must provide a promise-polyfill.

<!-- Introducing online resources -->
<script src="http://gosspublic.alicdn.com/aliyun-oss-sdk-x.x.x.min.js"></script>
<!-- Introducing offline resources -->
<script src="./aliyun-oss-sdk-x.x.x.min.js"></script>

<script type="text/javascript">
  const store = new OSS({
    region: 'oss-cn-hangzhou',
    accessKeyId: '<access-key-id>',
    accessKeySecret: '<access-key-secret>',
    bucket: '<bucket-name>',
    stsToken: '<security-token'
  });

  store
    .list()
    .then(result => {
      console.log('objects: %j', result.objects);
      return store.put('my-obj', new OSS.Buffer('hello world'));
    })
    .then(result => {
      console.log('put result: %j', result);
      return store.get('my-obj');
    })
    .then(result => {
      console.log('get result: %j', result.content.toString());
    });
</script>