Upload Object

The SDK methods listed in this section will allow you to upload objects to the bucket in various manners. You can upload objects as a string or as a stream. The Bucket reference used in the below code snippet is the component instance.

If you do not have Versioning enabled for your object, and if Stratus gets multiple write requests for the same object, the object will be continuously overwritten. The latest upload of the object will be the only object that is stored.

However, with Versioning enabled, each upload will be considered a version of the object, and all of them will be stored in the bucket, each with a unique versionId.

Upload Object as a Stream

Using this SDK method, you can upload objects to a bucket as a stream. Store the stream in a variable and then pass that variable in the upload method; putObject()

    

        
copy
        

            

        
    
    

         // create a read stream for upload the object
const file = fs.createReadStream("file_path");
// call the upload method
const res = await bucket.putObject("sam/out/sample.txt", file);
console.log(res);
    

Upload Object as a String

Using this SDK method, you can upload the object as a string. You will pass the object name, and the data to be stored in the object in string format in the upload method; putObject()

    

        
copy
        

            

        
    
    

         //Upload object as a string
const res = await bucket.putObject("sam/out/sample.txt", "Content of the file");
console.log(res);
    

Upload Object with Options

Using this SDK method, you can use the following options while you upload an object.

• overwrite: This is an option you can use, if Versioning for your bucket is not enabled for your bucket. Without versioning, you need to use this option if you wish to overwrite a resource. The default value is ‘false’.

• ttl: This is an option you can use to set Time-to-Live (TTL) in seconds for an object. Value should be greater than or equal to 60 seconds.

• metaData: This is an option you can use to upload meta details of the object that is being uploaded.

    

        
copy
        

            

        
    
    

         const options = {
    'overwrite': true, //This will overwrite your existing object
    'ttl': '300', //time to live in seconds
    'metaData': {
        'author': 'John'
    }
};
const file = fs.createReadStream("filePath");
const uploadRes = await bucket.putObject("sam/out/sample.txt", file, options);
console.log(uploadRes);
    

Upload Object Using Multipart

In this section we are going to go over the SDK methods that will allow you to successfully upload a large object to a bucket in Stratus.

The multipart upload feature will upload a large file to the bucket in multiple HTTPS requests. All of these requests will be combined into a single object once all the individual parts have been uploaded.

Initiate Upload

To perform multipart operations, you need to get a multipart object instance. We will refer to this component instance in various code snippets where we work with multipart operations being performed on objects stored in a bucket in Stratus.

Parameter Used

bucket: This is the bucket instance you need to have initialized earlier using this SDK method.

    

        
copy
        

            

        
    
    

         const initRes = await bucket.initiateMultipartUpload("sam/out/sample.txt");
console.log(initRes);
    

Example Response

    

        
copy
        

            

        
    
    

         {
  "bucket": "zcstratus123-development",
  "key": "sam/out/sample.txt",
  "upload_id": "01j7xbm4vm5750zbedxqgc4q6m",
  "status": "PENDING"
}
    

Upload Parts of the Object

In the following SDK method, we are going to perform uploads of the individual parts of the object. Each part will have a distinct partNumber ranging anywhere between 1 and 1000. While this represents the ordering of the parts, these parts will not necessarily be uploaded in sequence. These parts will be combined in sequence once the upload of all the parts of the objects is complete.

    

        
copy
        

            

        
    
    

         let partNumber = 1;
const file = fs.createReadStream("filePath");
const uploadPartRes = await bucket.uploadPart("sam/out/sample.txt", "uploadId", file, partNumber);
console.log(uploadPartRes);
    

Get Multipart Upload Summary

The following SDK method can be used to obtain an operational summary of all the uploaded parts. To view the summary, we will use the getMultipartUploadSummary() method.

    

        
copy
        

            

        
    
    

         const uploadSummaryRes = await bucket.getMultipartUploadSummary("sam/out/sample.txt", "upload_id");
console.log(uploadSummaryRes);
    

Example Response

    

        
copy
        

            

        
    
    

         {
    "bucket": "zcstratus12345-development",
    "key": "sam/out/sample.txt",
    "upload_id": "01hyfyeazrrstmt7k5fa7ej726",
    "status": "PENDING",
    "parts": [
        {
            "part_number": 1,
            "size": 0,
            "uploaded_at": 1716374678999
        },
        {
            "part_number": 2,
            "size": 2797094,
            "uploaded_at": 1716374678576
        },
        {
            "part_number": 4,
            "size": 0,
            "uploaded_at": 1716374679136
        }
    ]
}
    

Complete Multipart Upload of the Object

The following method allows us to terminate the multipart process once all the parts have been successfully uploaded. To complete the process we will pass the uploadId to the completeMultipartUpload() method.

    

        
copy
        

            

        
    
    

         const completeUploadRes = await bucket.completeMultipartUpload("sam/out/sample.txt", "uploadId");
console.log(completeUploadRes);
    

Example SDK Implementation

    

        
copy
        

            

        
    
    

         const catalyst = require('zcatalyst-sdk-node');
const fs = require('fs');
module.exports = async (req, res) => {
	url = req.url;
	switch (url) {
 	case '/':
  	const app = catalyst.initialize(req);
 		const stratus = app.stratus();

 		/** create a bucket instance  */
 		const bucket = stratus.bucket("bucket_name");

 		/** multipart upload */
 		const key = 'sample.mp4';

			// initiate multipart upload
 		const initRes = await bucket.initiateMultipartUpload(key);
			
			// get upload Id from initiate upload response.
 		const uploadId = initRes['upload_id'];
 		const filePath = '/Users/Aliza//sam.mp4';
 		const partSize = 50 * 1024 * 1024; // in Mb
 		const fileStream = fs.createReadStream(
					filePath,
					{ highWaterMark: partSize }
			);
 		let partNumber = 1;
 		const uploadPromises = [];

 		fileStream.on('data', async (partData) => {
 			// Push each part upload to the promises array for parallel upload
 			const partUploadPromise = bucket.uploadPart(
							key,
 							uploadId,
							partData,
							partNumber
				);
 			uploadPromises.push(partUploadPromise);
 			console.log('Part Number: ', partNumber);
 			partNumber++;
 		});

 		// Wait for all parts to be uploaded in parallel
 	fileStream.on('end', async () => {
 			
 		await Promise.all(uploadPromises);

 		// Complete the multipart upload
 		await bucket.completeMultipartUpload(key, uploadId);
			console.log('Successfully Uploaded');
 	});
 		res.end();
 		break;
	default:
 		res.writeHead(404);
 		res.write('You might find the page you are looking for at "/" path');
 		break;
	}
}
    

Upload an Object Using Transfer Manager

Ensure the following packages are imported

    

        
copy
        

            

        
    
    

         const { TransferManager } = require('zcatalyst-sdk-node/lib/stratus');

    

Create Transfer Manager Instance

    

        
copy
        

            

        
    
    

          const transferManager = new TransferManager(bucket); // create transfer manager instance

    

Multipart Upload

Create Multipart Upload Instance

The following SDK method will create a multipart instance by initiating multipart upload.

    

        
copy
        

            

        
    
    

         const multipart = await transferManager.createMultipartInstance("sam/out/sample.txt"); // create multipart instance
    

If you are required to create an instance for an already initialized multipart upload operation, then copy and use the code snippet given below

    

        
copy
        

            

        
    
    

         const multipart = await transferManager.createMultipartInstance("sam/out/sample.txt", "uploadId");
    

Upload Part

In the following SDK method we are going to be using the multipart instance we initalized in the Create Multipart Upload Instance section.

    

        
copy
        

            

        
    
    

         const uploadRes = await multipart.uploadPart(fs.createReadStream("filePath"), partNumber);
console.log(uploadRes);
    

Upload Summary

    

        
copy
        

            

        
    
    

         const summaryRes = await multipart.getUploadSummary();
console.log(summaryRes);
    

Complete Upload

    

        
copy
        

            

        
    
    

         const completeRes = await multipart.completeUpload();
console.log(completeRes);

    

Upload Object Using Wrapper

The following SDK method acts as a wrapper, where the entire multipart upload operation is carried out without employing multiple steps. Using this method, the object is split into multiple parts, uploaded to the bucket in multiple parts, and then combined once all the parts are uploaded.

    

        
copy
        

            

        
    
    

         const file = fs.createReadStream("filePath");
const partSize = 50 // in MB
const objectPartUploadRes = await transferManager.putObjectAsParts("sam/out/sample.txt",file, partSize);
console.log(objectPartUploadRes);
    

Generate Presigned URL to Upload an Object

Presigned URLs are secure URLs that authenticated users can share to their non-authenticated users. This URL will provide non-authenticated users with temporary authorization to access objects. The Bucket reference used in the below code snippet is the component instance.

Parameters Used

    

        
copy
        

            

        
    
    

         const signedURLRes = await bucket.generatePreSignedUrl("sam/out/sample.txt", 'PUT', {
    'expiryIn': 100, // expiry time in seconds
    'activeFrom':'12334454327', // activate the url in the given date
});
console.log(signedURLRes);

    

Example Response for Generating a Presigned URL for Upload

    

        
copy
        

            

        
    
    

         {
  signature: "https://sadi-development.zohostratus.com/_signed/text.txt?organizationId=96862383&stsCredential=96858154-96862383&stsDate=1747896279887&stsExpiresAfter=300&stsSignedHeaders=host&stsSignature=3YBUX1HFSxNQzQJjFrln82AyJsEEuC5T9dsZwWxGyEE"
}

    

Example Snippet Illustrating Usage of Presigned URL to Upload an Object

    

        
copy
        

            

        
    
    

         const axios = require('axios');
const fs = require('fs');

// Replace this with the actual pre-signed URL generated for your upload.
const url = 'https://sadi-development.zohostratus.com/_signed/text.txt?organizationId=96862383&stsCredential=96858154-96862383&stsDate=1747911331272&stsExpiresAfter=300&stsSignedHeaders=host&stsSignature=K9vuqC7JaATLeM3TX4xXWx0OHcSflbYQ2jCrbKSAAIE';

// Replace 'file_path' with your actual file path
const data = fs.createReadStream('/Users/ranjitha-18338/Documents/NODE-SDK/Stratus/sam.py');

// Optional headers; content type may vary depending on the file type
const headers = {
    // 'Content-Type': 'application/json', // adjust if uploading non-JSON files (e.g., 'text/plain' or 'application/octet-stream')
    // 'overwrite': 'true', // optional header
};

(async () => {
    try {
        const response = await axios.put(url, data, { headers });

        if (response.status === 200) {
            console.log('Object uploaded successfully');
        } else {
            console.log('⚠️ Error uploading object:', response.data);
        }
    } catch (error) {
        console.error('Upload failed:', error.response?.data || error.message);
    }
})();