Configure single-connection bandwidth throttling for object uploads and downloads using the Node.js SDK - Object Storage Service

Set a per-connection bandwidth limit on object uploads and downloads so that OSS transfers don't starve other applications sharing the network.

Prerequisites

Before you begin, ensure that you have:

Node.js installed with the ali-oss package (npm install ali-oss)
An OSS bucket
AccessKey ID and AccessKey Secret stored in the environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET

How it works

OSS accepts bandwidth limits in bits per second (bit/s). To convert a human-friendly KB/s value: multiply by 8 x 1024. For example, 100 KB/s = 100 x 1024 x 8 = 819,200 bit/s.

Parameter	Where to set it	Unit	Example (100 KB/s)
`x-oss-traffic-limit`	Request header	bit/s	`8 * 1024 * 100` = 819,200
`trafficLimit`	`signatureUrl()` options	bit/s	`8 * 1024 * 100` = 819,200

Important

When bandwidth throttling is active, transfers take longer than the SDK's default timeout allows. Increase the timeout value (in milliseconds) based on object size and throttle rate. If the timeout is too short, the request fails with a timeout error before the transfer completes.

Throttle simple uploads and downloads

Use the x-oss-traffic-limit request header with putStream() and get() to apply bandwidth throttling to standard uploads and downloads.

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

const client = new OSS({
  // Region where the bucket is located, for example: oss-cn-hangzhou
  region: '<your-region>',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<your-bucket-name>',
});

// Bandwidth limit via request header.
// Unit: bit/s. 100 KB/s = 100 x 1024 x 8 = 819,200 bit/s.
const headers = {
  'x-oss-traffic-limit': 8 * 1024 * 100,
};

// Upload with bandwidth throttling
async function put() {
  const filePath = 'D:\\localpath\\examplefile.txt';
  const fileStream = fs.createReadStream(filePath);
  const result = await client.putStream('file-name', fileStream, {
    headers,
    timeout: 60000, // Increase if large objects time out during throttled uploads
  });
  console.log(result);
}

// Download with bandwidth throttling
async function get() {
  const result = await client.get('file-name', {
    headers,
    timeout: 60000, // Increase if large objects time out during throttled downloads
  });
  console.log(result);
}

put();
get();

Throttle uploads and downloads via signed URLs

Use the trafficLimit option in signatureUrl() to embed the bandwidth limit in the URL itself. This lets clients without OSS credentials upload or download objects while staying within a defined bandwidth cap — useful when you need to grant temporary access to external users or services.

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

const client = new OSS({
  // Region where the bucket is located, for example: oss-cn-hangzhou
  region: '<your-region>',
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  bucket: '<your-bucket-name>',
});

// Upload via signed URL with bandwidth throttling
async function putByQuery() {
  const url = client.signatureUrl('file-name', {
    trafficLimit: 8 * 1024 * 100, // 100 KB/s in bit/s
    method: 'PUT',
  });

  const filePath = 'D:\\localpath\\examplefile.txt';
  const fileStream = fs.createReadStream(filePath);

  const result = await client.urllib.request(url, {
    method: 'PUT',
    stream: fileStream,
    timeout: 60000, // Increase if large objects time out during throttled uploads
  });
  console.log(result);
}

// Download via signed URL with bandwidth throttling
async function getByQuery() {
  const url = client.signatureUrl('file-name', {
    trafficLimit: 8 * 1024 * 100, // 100 KB/s in bit/s
  });

  const result = await client.urllib.request(url, {
    timeout: 60000, // Increase if large objects time out during throttled downloads
  });
  console.log(result);
}

putByQuery();
getByQuery();

References

For the complete sample code, see ali-oss on GitHub.