Bump to v7.13.0

CHANGELOG.md

@@ -1,5 +1,16 @@
 ## CHANGE LOG
 
+## 7.13.0
+- 对象存储，新增空间级别上传加速开关
+- 对象存储，优化断点续传开启方式
+- 对象存储，优化回调签名验证函数，新增兼容 Qiniu 签名
+- 对象存储，修复上传失败无法完成自动重试
+  - 在 Node.js 18 及以上触发
+  - 7.12.0 引入
+- 对象存储，新增空间的创建、删除、按标签列举
+- 对象存储，调整查询区域主备域名
+- 修复内部 HttpClient 部分方法参数类型声明不正确
+
 ## 7.12.0
 - 对象存储，新增支持 Promise 风格异步
 - 对象存储，修复分片上传 v1 在特定条件可能无法从断点继续上传

index.d.ts

@@ -148,6 +148,14 @@ export declare namespace conf {
         useHttpsDomain?: boolean;
 
         /**
+         * 在使用前需要提前开通加速域名
+         * 详见：https://developer.qiniu.com/kodo/12656/transfer-acceleration
+         * @default false
+         */
+        accelerateUploading?: boolean;
+
+        /**
+         * @deprecated 实际已无加速上传能力，使用 accelerateUploading 代替
          * @default true
          */
         useCdnDomain?: boolean;
@@ -181,10 +189,15 @@ export declare namespace conf {
     }
     class Config {
         useHttpsDomain: boolean;
+        accelerateUploading: boolean;
+        /**
+         * @deprecated 实际已无加速上传能力，使用 accelerateUploading 代替
+         */
         useCdnDomain: boolean;
         ucEndpointsProvider?: httpc.EndpointsProvider | null;
         queryRegionsEndpointsProvider?: httpc.EndpointsProvider | null;
         regionsProvider?: httpc.RegionsProvider | null;
+        regionsQueryResultCachePath?: string | null;
         zone?: Zone | null;
         zoneExpire?: number;
 
@@ -337,7 +350,7 @@ export declare namespace form_up {
 export declare namespace resume_up {
     type UploadResult = {
         data: any;
-        resp: IncomingMessage;
+        resp: Omit<IncomingMessage, 'url'> & { requestUrls: string[] };
     }
 
     class ResumeUploader {
@@ -412,13 +425,14 @@ export declare namespace resume_up {
 
         /**
          * @default null
+         * @deprecated 使用 `resumeRecorder` 与 `resumeKey` 代替
          */
-        resumeRecordFile?: string
+        resumeRecordFile?: string | null
 
         /**
          * @default null
          */
-        progressCallback?: (uploadBytes: number, totalBytes: number) => void
+        progressCallback?: ((uploadBytes: number, totalBytes: number) => void) | null
 
         /**
          * @default v1
@@ -435,6 +449,18 @@ export declare namespace resume_up {
          */
         metadata?: Record<string, string>
 
+        /**
+         * 断点续传记录器，请通过 `createResumeRecorder` 或 `createResumeRecorderSync` 获取，优先级比 `resumeRecordFile` 低
+         * @default null
+         */
+        resumeRecorder?: ResumeRecorder
+
+        /**
+         * 断点续传记录文件的具体文件名，不设置时会由当次上传自动生成
+         * @default null
+         */
+        resumeKey?: string | null
+
         /**
          * 上传可选参数
          * @param fname 请求体中的文件的名称
@@ -445,11 +471,32 @@ export declare namespace resume_up {
          * @param partSize 分片上传v2必传字段 默认大小为4MB 分片大小范围为1 MB - 1 GB
          * @param version 分片上传版本 目前支持v1/v2版本 默认v1
          * @param metadata 元数据设置，参数名称必须以 x-qn-meta-${name}: 开头
+         * @param resumeRecorder 断点续传记录器，请通过 `createResumeRecorder` 或 `createResumeRecorderSync` 获取，优先级比 `resumeRecordFile` 低
+         * @param resumeKey 断点续传记录文件的具体文件名，不设置时会由当次上传自动生成，推荐不设置
          */
         constructor(fname?: string, params?: Record<string, string>, mimeType?: string, resumeRecordFile?: string,
                     progressCallback?: (uploadBytes: number, totalBytes: number) => void,
-                    partSize?:number, version?:string, metadata?: Record<string, string>);
+                    partSize?:number, version?:string, metadata?: Record<string, string>,
+                    resumeRecorder?: ResumeRecorder, resumeKey?: string);
+    }
+
+    /**
+     * 历史原因其方法当前仅支持了同步调用这一不推荐的使用方式，暂不公开具体内部信息，仅供 TypeScript 类型检查使用。
+     * 实际不存在这个类，未来会变更为 interface。
+     */
+    abstract class ResumeRecorder {
     }
+
+    /**
+     *
+     * @param baseDirPath 默认值为 `os.tmpdir()`，该方法若 baseDirPath 不存在将自动创建
+     */
+    function createResumeRecorder (baseDirPath?: string): Promise<ResumeRecorder>
+
+    /**
+     * `createResumeRecorder` 的同步版本，不推荐使用
+     */
+    function createResumeRecorderSync (baseDirPath?: string): ResumeRecorder
 }
 
 export declare namespace util {
@@ -514,8 +561,22 @@ export declare namespace util {
      * @param requestURI 回调的URL中的requestURI
      * @param reqBody 回调的URL中的requestURI 请求Body，仅当请求的ContentType为application/x-www-form-urlencoded时才需要传入该参数
      * @param callbackAuth 回调时请求的Authorization头部值
+     * @param extra 当回调为 Qiniu 签名时需要传入
+     * @param extra.reqMethod 请求方法，例如 GET，POST
+     * @param extra.reqContentType 请求类型，例如 application/json 或者  application/x-www-form-urlencoded
+     * @param extra.reqHeaders 请求头部
      */
-    function isQiniuCallback(mac: auth.digest.Mac, requestURI: string, reqBody: string | null, callbackAuth: string): boolean;
+    function isQiniuCallback(
+        mac: auth.digest.Mac,
+        requestURI: string,
+        reqBody: string | null,
+        callbackAuth: string,
+        extra?: {
+            reqMethod: string,
+            reqContentType?: string,
+            reqHeaders?: Record<string, string>
+        }
+    ): boolean;
 }
 
 export declare namespace httpc {
@@ -531,7 +592,7 @@ export declare namespace httpc {
     // responseWrapper.js
     interface ResponseWrapperOptions<T = any> {
         data: T;
-        resp: IncomingMessage;
+        resp: Omit<IncomingMessage, 'url'> & { requestUrls: string[] };
     }
 
     interface ResponseError {
@@ -541,7 +602,7 @@ export declare namespace httpc {
 
     class ResponseWrapper<T = any> {
         data: T extends void ? undefined | ResponseError : T & ResponseError;
-        resp: IncomingMessage;
+        resp: Omit<IncomingMessage, 'url'> & { requestUrls: string[] };
         constructor(options: ResponseWrapperOptions);
         ok(): boolean;
         needRetry(): boolean;
@@ -643,17 +704,17 @@ export declare namespace httpc {
         middlewares?: middleware.Middleware[];
     }
 
-    interface GetOptions<T = any> extends ReqOpts<T> {
+    interface GetOptions<T = any> extends Omit<ReqOpts<T>, 'urllibOptions'> {
         params: Record<string, string>;
         headers: Record<string, string>;
     }
 
-    interface PostOptions<T = any> extends ReqOpts<T> {
+    interface PostOptions<T = any> extends Omit<ReqOpts<T>, 'urllibOptions'> {
         data: string | Buffer | Readable;
         headers: Record<string, string>;
     }
 
-    interface PutOptions<T = any> extends ReqOpts<T> {
+    interface PutOptions<T = any> extends Omit<ReqOpts<T>, 'urllibOptions'> {
         data: string | Buffer | Readable;
         headers: Record<string, string>
     }
@@ -664,9 +725,9 @@ export declare namespace httpc {
         middlewares: middleware.Middleware[];
         constructor(options: HttpClientOptions)
         sendRequest(requestOptions: ReqOpts): Promise<ResponseWrapper>
-        get(getOptions: GetOptions): Promise<ResponseWrapper>
-        post(postOptions: PostOptions): Promise<ResponseWrapper>
-        put(putOptions: PutOptions): Promise<ResponseWrapper>
+        get(getOptions: GetOptions, urllibOptions?: RequestOptions): Promise<ResponseWrapper>
+        post(postOptions: PostOptions, urllibOptions?: RequestOptions): Promise<ResponseWrapper>
+        put(putOptions: PutOptions, urllibOptions?: RequestOptions): Promise<ResponseWrapper>
     }
 
     // endpoint.js
@@ -688,12 +749,15 @@ export declare namespace httpc {
         getValue(options?: {scheme?: string}): string;
 
         getEndpoints(): Promise<httpc.Endpoint[]>;
+
+        clone(): Endpoint;
     }
 
     // region.js
     enum SERVICE_NAME {
         UC = 'uc',
         UP = 'up',
+        UP_ACC = 'up_acc',
         IO = 'io',
         RS = 'rs',
         RSF = 'rsf',
@@ -764,6 +828,7 @@ export declare namespace httpc {
     class Region implements RegionsProvider {
         static fromZone(zone: conf.Zone, options?: RegionFromZoneOptions): Region;
         static fromRegionId(regionId: string, options?: RegionFromRegionIdOptions): Region;
+        static merge(...r: Region[]): Region;
 
         // non-unique
         regionId?: string;
@@ -777,6 +842,10 @@ export declare namespace httpc {
 
         getRegions(): Promise<httpc.Region[]>;
 
+        clone(): Region;
+
+        merge(...r: Region[]): Region;
+
         get isLive(): boolean;
     }
 
@@ -1288,6 +1357,32 @@ export declare namespace rs {
          * @param callbackFunc
          */
         listBucket(callbackFunc?: callback): Promise<httpc.ResponseWrapper<GetBucketsResult>>
+        listBucket(options: { shared: string, tagCondition: Record<string, string> }, callbackFunc?: callback): Promise<httpc.ResponseWrapper<GetBucketsResult>>
+
+        /**
+         * 创建空间
+         * @param bucket 空间名
+         * @param options 选项
+         * @param options.regionId 区域 ID
+         * @param callbackFunc 回调函数
+         */
+        createBucket(
+            bucket: string,
+            options: {
+                regionId: string
+            },
+            callbackFunc?: callback
+        ): Promise<httpc.ResponseWrapper<void>>
+
+        /**
+         * 删除空间
+         * @param bucket 空间名
+         * @param callbackFunc 回调函数
+         */
+        deleteBucket(
+            bucket: string,
+            callbackFunc?: callback
+        ): Promise<httpc.ResponseWrapper<void>>
 
         /**
          * 获取空间详情

package.json

@@ -1,6 +1,6 @@
 {
   "name": "qiniu",
-  "version": "7.12.0",
+  "version": "7.13.0",
   "description": "Node wrapper for Qiniu Resource (Cloud) Storage API",
   "main": "index.js",
   "directories": {
@@ -58,6 +58,7 @@
     "encodeurl": "^1.0.1",
     "formstream": "^1.1.0",
     "mime": "^2.4.4",
+    "mkdirp": "^0.5.5",
     "mockdate": "^3.0.5",
     "tunnel-agent": "^0.6.0",
     "typescript": "^4.9.4",

qiniu/conf.js

@@ -27,28 +27,30 @@ exports.FormMimeRaw = 'application/octet-stream';
 exports.RS_HOST = 'rs.qiniu.com';
 exports.RPC_TIMEOUT = 600000; // 600s
 let QUERY_REGION_BACKUP_HOSTS = [
-    'uc.qbox.me',
-    'api.qiniu.com'
+    'kodo-config.qiniuapi.com',
+    'uc.qbox.me'
 ];
 Object.defineProperty(exports, 'QUERY_REGION_BACKUP_HOSTS', {
     get: () => QUERY_REGION_BACKUP_HOSTS,
     set: v => {
         QUERY_REGION_BACKUP_HOSTS = v;
     }
 });
-let QUERY_REGION_HOST = 'kodo-config.qiniuapi.com';
+let QUERY_REGION_HOST = 'uc.qiniuapi.com';
 Object.defineProperty(exports, 'QUERY_REGION_HOST', {
     get: () => QUERY_REGION_HOST,
     set: v => {
         QUERY_REGION_HOST = v;
         QUERY_REGION_BACKUP_HOSTS = [];
     }
 });
-let UC_HOST = 'uc.qbox.me';
+let UC_BACKUP_HOSTS = QUERY_REGION_BACKUP_HOSTS.slice();
+let UC_HOST = QUERY_REGION_HOST;
 Object.defineProperty(exports, 'UC_HOST', {
     get: () => UC_HOST,
     set: v => {
         UC_HOST = v;
+        UC_BACKUP_HOSTS = [];
         QUERY_REGION_HOST = v;
         QUERY_REGION_BACKUP_HOSTS = [];
     }
@@ -64,27 +66,37 @@ const Config = (function () {
      * @constructor
      * @param {Object} [options]
      * @param {boolean} [options.useHttpsDomain]
-     * @param {boolean} [options.useCdnDomain]
+     * @param {boolean} [options.accelerateUploading] enable accelerate uploading. should active the domains in portal before using
      * @param {EndpointsProvider} [options.ucEndpointsProvider]
      * @param {EndpointsProvider} [options.queryRegionsEndpointsProvider]
      * @param {RegionsProvider} [options.regionsProvider]
-     * @param {Zone} [options.zone]
-     * @param {number} [options.zoneExpire]
+     * @param {string} [options.regionsQueryResultCachePath]
+     *
+     * @param {boolean} [options.useCdnDomain] DEPRECATED: use accelerateUploading instead
+     * @param {Zone} [options.zone] DEPRECATED: use RegionsProvider instead
+     * @param {number} [options.zoneExpire] DEPRECATED
      */
     function Config (options) {
         options = options || {};
         // use http or https protocol
         this.useHttpsDomain = !!(options.useHttpsDomain || false);
-        // use cdn accelerated domains, this is not work with auto query region
-        this.useCdnDomain = !!(options.useCdnDomain && true);
+
+        // use accelerate upload domains
+        this.accelerateUploading = !!(options.accelerateUploading || false);
+
         // custom uc endpoints
         this.ucEndpointsProvider = options.ucEndpointsProvider || null;
         // custom query region endpoints
         this.queryRegionsEndpointsProvider = options.queryRegionsEndpointsProvider || null;
         // custom regions
         this.regionsProvider = options.regionsProvider || null;
+        // custom cache persisting path for regions query result
+        // only worked with default CachedRegionsProvider
+        this.regionsQueryResultCachePath = options.regionsQueryResultCachePath;
 
         // deprecated
+        // use cdn accelerated domains, this is not work with auto query region
+        this.useCdnDomain = !!(options.useCdnDomain && true);
         // zone of the bucket
         this.zone = options.zone || null;
         this.zoneExpire = options.zoneExpire || -1;
@@ -98,11 +110,10 @@ const Config = (function () {
             return this.ucEndpointsProvider;
         }
 
-        return new Endpoint(
-            UC_HOST,
-            {
+        return new StaticEndpointsProvider(
+            [UC_HOST].concat(UC_BACKUP_HOSTS).map(h => new Endpoint(h, {
                 defaultScheme: this.useHttpsDomain ? 'https' : 'http'
-            }
+            }))
         );
     };
 
@@ -216,9 +227,11 @@ const Config = (function () {
                 const cacheKey = [
                     endpointsMd5,
                     accessKey,
-                    bucketName
+                    bucketName,
+                    this.accelerateUploading.toString()
                 ].join(':');
                 return new CachedRegionsProvider({
+                    persistPath: this.regionsQueryResultCachePath,
                     cacheKey,
                     baseRegionsProvider: new QueryRegionsProvider({
                         accessKey: accessKey,