feat: restore object api and support to create archvie bucket (#450)

* feat: add restore object api

* feat:support create archive bucket

* test:add restore object api test case

* docs:add restore object and modify  putBucket docs

* test: add test case about creating archive bucket

Author: luozhang002

README.md

@@ -93,6 +93,7 @@ OSS, Object Storage Service. Equal to well known Amazon [S3](http://aws.amazon.c
   - [.signatureUrl(name[, options])](#signatureurlname-options)
   - [.putACL*(name, acl[, options])](#putaclname-acl-options)
   - [.getACL*(name[, options])](#getaclname-options)
+  - [.restore*(name[, options])](#restorename-options)
   - [.initMultipartUpload*(name[, options])](#initmultipartuploadname-options)
   - [.uploadPart*(name, uploadId, partNo, file, start, end[, options])](#uploadpartname-uploadid-partno-file-start-end-options)
   - [.uploadPartCopy*(name, uploadId, partNo, range, sourceData[, options])](#uploadpartcopyname-uploadid-partno-range-sourcedata-options)
@@ -242,6 +243,7 @@ parameters:
   If region value invalid, will throw InvalidLocationConstraintError.
 - [options] {Object} optional parameters
   - [timeout] {Number} the operation timeout
+  - [StorageClass] {String} the storeage type include (Standard,IA,Archive)
 
 Success will return the bucket name on `bucket` properties.
 
@@ -262,6 +264,14 @@ yield store.putBucket('helloworld', 'oss-cn-hongkong');
 store.useBucket('helloworld', 'oss-cn-hongkong');
 ```
 
+- Create a bucket name `helloworld` location on HongKong StorageClass `Archive`
+
+```js
+yield store.putBucket('helloworld', 'oss-cn-hongkong', { StorageClass: 'Archive' });
+// use it by default
+store.useBucket('helloworld', 'oss-cn-hongkong');
+```
+
 ### .deleteBucket*(name, region[, options])
 
 Delete an empty bucket.
@@ -1568,6 +1578,33 @@ var result = yield store.getACL('ossdemo.txt');
 console.log(result.acl);
 ```
 
+### .restore*(name[, options])
+
+Restore Object.
+
+parameters:
+
+- name {String} object name
+- [options] {Object} optional parameters
+  - [timeout] {Number} the operation timeout
+
+Success will return:
+
+- res {Object} response info, including
+  - status {Number} response status
+  - headers {Object} response headers
+  - size {Number} response size
+  - rt {Number} request total use time (ms)
+
+example:
+
+- Restore an object
+
+```js
+var result = yield store.restore('ossdemo.txt');
+console.log(result.status);
+```
+
 ### .initMultipartUpload(name[, options])
 Before transmitting data in the Multipart Upload mode,
 you must call the Initiate Multipart Upload interface to notify the OSS to initiate a Multipart Upload event.
@@ -2923,6 +2960,7 @@ Will put to all clients.
 - `client.copy()`
 - `client.putMeta()`
 - `client.putACL()`
+- `client.restore()`
 
 ## Wrapper Usage
 
@@ -3049,6 +3087,8 @@ name | code | status | message | message in Chinese
 AccessDeniedError | AccessDenied | 403 | Access Denied | 拒绝访问
 BucketAlreadyExistsError | BucketAlreadyExists | 409 | Bucket already exists | Bucket 已经存在
 BucketNotEmptyError | BucketNotEmpty | 409 | Bucket is not empty | Bucket 不为空
+RestoreAlreadyInProgressError | RestoreAlreadyInProgress | 409 | The restore operation is in progress. | restore 操作正在进行中
+OperationNotSupportedError | OperationNotSupported | 400 | The operation is not supported for this resource | 该资源暂不支持restore操作
 EntityTooLargeError | EntityTooLarge | 400 | Entity too large | 实体过大
 EntityTooSmallError | EntityTooSmall | 400 | Entity too small | 实体过小
 FileGroupTooLargeError | FileGroupTooLarge | 400 | File group too large | 文件组过大

lib/browser/bucket.js

@@ -80,7 +80,7 @@ proto.putBucket = function* putBucket(name, region, options) {
   if (region) {
     params.mime = 'xml';
     params.content = `${'<?xml version="1.0" encoding="UTF-8"?>\n' +
-      '<CreateBucketConfiguration><LocationConstraint>'}${region
+        '<CreateBucketConfiguration><LocationConstraint>'}${region
     }</LocationConstraint></CreateBucketConfiguration>`;
   }
   params.successStatuses = [200];

lib/browser/object.js

@@ -429,6 +429,25 @@ proto.getACL = function* getACL(name, options) {
   };
 };
 
+/**
+ * Restore Object
+ * @param {String} name the object key
+ * @param {Object} options
+ * @returns {{res}}
+ */
+proto.restore = function* restore(name, options) {
+  options = options || {}
+  options.subres = 'restore';
+  const params = this._objectRequestParams('POST', name, options);
+  params.successStatuses = [202];
+
+  const result = yield this.request(params);
+
+  return {
+    res: result.res,
+  };
+}
+
 proto.signatureUrl = function (name, options) {
   options = options || {};
   name = this._objectName(name);

lib/bucket.js

@@ -43,6 +43,7 @@ proto.listBuckets = function* listBuckets(query, options) {
         name: item.Name,
         region: item.Location,
         creationDate: item.CreationDate,
+        StorageClass: item.StorageClass,
       }));
     }
     return {
@@ -75,13 +76,28 @@ proto.getBucket = function getBucket() {
 };
 
 proto.putBucket = function* putBucket(name, region, options) {
+  options = options || {};
   const params = this._bucketRequestParams('PUT', name, '', options);
-  if (region) {
+
+  const startTag = '<?xml version="1.0" encoding="UTF-8"?>\n<CreateBucketConfiguration>'
+  const endTag = '</CreateBucketConfiguration>'
+  let paramlXML = '';
+
+  // server not support
+  // if (region) {
+  //   paramlXML += `<LocationConstraint>${region}</LocationConstraint>`;
+  //   params.content = `${startTag}${paramlXML}${endTag}`;
+  // }
+
+  if (options.StorageClass) {
+    paramlXML += `<StorageClass>${options.StorageClass}</StorageClass>`;
+  }
+
+  if (paramlXML) {
     params.mime = 'xml';
-    params.content = `${'<?xml version="1.0" encoding="UTF-8"?>\n' +
-      '<CreateBucketConfiguration><LocationConstraint>'}${region
-    }</LocationConstraint></CreateBucketConfiguration>`;
+    params.content = `${startTag}${paramlXML}${endTag}`;
   }
+
   params.successStatuses = [200];
   const result = yield this.request(params);
   return {

lib/object.js

@@ -429,6 +429,25 @@ proto.getACL = function* getACL(name, options) {
   };
 };
 
+/**
+ * Restore Object
+ * @param {String} name the object key
+ * @param {Object} options
+ * @returns {{res}}
+ */
+proto.restore = function* restore(name, options) {
+  options = options || {}
+  options.subres = 'restore';
+  const params = this._objectRequestParams('POST', name, options);
+  params.successStatuses = [202];
+
+  const result = yield this.request(params);
+
+  return {
+    res: result.res,
+  };
+}
+
 proto.signatureUrl = function (name, options) {
   options = options || {};
   name = this._objectName(name);

test/node/bucket.test.js

@@ -39,10 +39,16 @@ describe('test/bucket.test.js', () => {
     const result = yield this.store.putBucket(this.bucket, this.region);
     assert.equal(result.bucket, this.bucket);
     assert.equal(result.res.status, 200);
+
+    // just for archive bucket test
+    this.archvieBucket = `ali-oss-archive-bucket-${prefix.replace(/[/.]/g, '-')}`;
+    this.archvieBucket = this.bucket.substring(0, this.bucket.length - 1);
+    yield this.store.putBucket(this.archvieBucket, this.region, { StorageClass: 'Archive' });
   });
 
   after(function* () {
     yield utils.cleanBucket(this.store, this.bucket, this.region);
+    // yield utils.cleanBucket(this.store, this.archvieBucket, this.region);
   });
 
   describe('putBucket()', () => {
@@ -62,8 +68,22 @@ describe('test/bucket.test.js', () => {
       assert.equal(result2.bucket, this.name);
     });
 
+    it('should create an archive bucket', function* () {
+      const result2 = yield this.store.listBuckets();
+      const { buckets } = result2;
+      const m = buckets.some(item => item.name === this.archvieBucket);
+      assert(m === true);
+      buckets.map((item) => {
+        if (item.name === this.archvieBucket) {
+          assert(item.StorageClass === 'Archive');
+        }
+        return 1;
+      });
+    });
+
     after(function* () {
       const result = yield this.store.deleteBucket(this.name);
+      yield this.store.deleteBucket(this.archvieBucket);
       assert(result.res.status === 200 || result.res.status === 204);
     });
   });

test/node/object.test.js

@@ -27,6 +27,11 @@ describe('test/object.test.js', () => {
     this.store = oss(config);
     this.bucket = `ali-oss-test-object-bucket-${prefix.replace(/[/.]/g, '-')}`;
     this.bucket = this.bucket.substring(0, this.bucket.length - 1);
+
+    // just for archive bucket test
+    this.archvieBucket = `oss-archvie-bucket-${prefix.replace(/[/.]/g, '-')}`;
+    this.archvieBucket = this.archvieBucket.substring(0, this.archvieBucket.length - 1);
+
     this.region = config.region;
     // console.log('current buckets: %j',
     //   (yield this.store.listBuckets()).buckets.map(function (item) {
@@ -35,10 +40,14 @@ describe('test/object.test.js', () => {
     // );
     yield this.store.putBucket(this.bucket, this.region);
     this.store.useBucket(this.bucket, this.region);
+
+    yield this.store.putBucket(this.archvieBucket, this.region, { StorageClass: 'Archive' });
+    // this.store.useBucket(this.archvieBucket, this.region);
   });
 
   after(function* () {
     yield utils.cleanBucket(this.store, this.bucket, this.region);
+    yield utils.cleanBucket(this.store, this.archvieBucket, this.region);
   });
 
   describe('putStream()', () => {
@@ -1566,4 +1575,34 @@ describe('test/object.test.js', () => {
       assert(res.headers['x-oss-next-append-position'] === '9');
     });
   });
+
+  describe('restore()', () => {
+    it('Should return OperationNotSupportedError when the type of bucket is not archive', function* () {
+      const name = '/oss/restore.js';
+      yield this.store.put(name, __filename);
+
+      try {
+        yield this.store.restore(name);
+        throw new Error('should not run this');
+      } catch (err) {
+        assert.equal(err.name, 'OperationNotSupportedError');
+      }
+    });
+    it('Should return 202 when restore is called first', function* () {
+      yield this.store.useBucket(this.archvieBucket, this.region);
+
+      const name = '/oss/restore.js';
+      yield this.store.put(name, __filename);
+
+      const info = yield this.store.restore(name);
+      assert.equal(info.res.status, 202);
+
+      // in 1 minute veriy RestoreAlreadyInProgressError
+      try {
+        yield this.store.restore(name);
+      } catch (err) {
+        assert.equal(err.name, 'RestoreAlreadyInProgressError');
+      }
+    });
+  });
 });