Perform a resumable upload by using checkpoints in the Node.js SDK - Object Storage Service

Resumable upload splits a file into multiple parts, uploads them separately, and merges them into a complete object. Use resumable upload when working in unreliable network conditions — if an upload fails, you can resume from the last checkpoint instead of restarting from scratch.

The sample code uses ES6 Promise and async/await syntax. For SDK installation instructions, see Install the Node.js SDK. For background information, see Resumable upload. To avoid storage costs from incomplete uploads, configure lifecycle rules to delete unused fragments. See Delete fragments.

How it works

The multipartUpload method accepts a progress callback that receives two parameters:

Parameter	Type	Description
`percentage`	Number	Upload completion percentage
`cpt`	Object	Checkpoint object containing the state needed to resume the upload

Save the checkpoint during the upload. If an error occurs, pass the saved checkpoint back to multipartUpload to resume from where the upload stopped.

`multipartUpload` options

Option	Type	Description
`checkpoint`	Object	Checkpoint object from a previous upload attempt. If provided, the upload resumes from the saved position.
`progress`	Function	Async callback invoked after each part completes. Receives `percentage` and `cpt` as parameters.

Upload with checkpoint

The following example retries the upload up to five times, saving the checkpoint on each progress update.

const OSS = require('ali-oss')

const client = new OSS({
  // Set region to the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set region to oss-cn-hangzhou.
  region: 'yourregion',
  // Obtain access credentials from environment variables. Before running this sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // Specify the bucket name.
  bucket: 'examplebucket',
});

// Set yourfilepath to the local path of the file to upload.
const filePath = "yourfilepath";

let checkpoint;
async function resumeUpload() {
  // Retry five times.
  for (let i = 0; i < 5; i++) {
    try {
      const result = await client.multipartUpload('object-name', filePath, {
        checkpoint,
        async progress(percentage, cpt) {
          checkpoint = cpt;
        },
      });
      console.log(result);
      break; // Break the current loop.
    } catch (e) {
      console.log(e);
    }
  }
}

resumeUpload();

This example saves the checkpoint to an in-memory variable. If the process crashes, the checkpoint is lost.

Persist the checkpoint to a file

To survive process restarts, write the checkpoint to a file and read it back on startup.

const OSS = require('ali-oss');
const fs = require('fs');

const client = new OSS({
  region: 'yourregion',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: 'examplebucket',
});

const filePath = 'yourfilepath';
const checkpointFile = 'checkpoint.json';

// Load a previously saved checkpoint, if any.
function loadCheckpoint() {
  if (fs.existsSync(checkpointFile)) {
    return JSON.parse(fs.readFileSync(checkpointFile, 'utf8'));
  }
  return null;
}

// Save the checkpoint to a local file.
function saveCheckpoint(cpt) {
  fs.writeFileSync(checkpointFile, JSON.stringify(cpt));
}

async function resumeUpload() {
  let checkpoint = loadCheckpoint();

  for (let i = 0; i < 5; i++) {
    try {
      const result = await client.multipartUpload('object-name', filePath, {
        checkpoint,
        async progress(percentage, cpt) {
          checkpoint = cpt;
          saveCheckpoint(cpt);
        },
      });
      console.log(result);
      // Remove the checkpoint file after a successful upload.
      if (fs.existsSync(checkpointFile)) {
        fs.unlinkSync(checkpointFile);
      }
      break;
    } catch (e) {
      console.log(e);
    }
  }
}

resumeUpload();

References

For the complete sample code for resumable upload, see the GitHub example.

How it works

multipartUpload options

Upload with checkpoint

Persist the checkpoint to a file

References

`multipartUpload` options