dolphindb 2.0.944 → 2.0.945

package/browser.d.ts

@@ -257,7 +257,7 @@ export declare class DdbObj<TValue extends DdbValue = DdbValue> {
     /** 自动转换 js string, boolean 为 DdbObj */
     static to_ddbobj(value: DdbObj | string | boolean): DdbObj;
     /** 转换 js 数组为 DdbObj[] */
-    static to_ddbobjs(values: any[]): DdbObj<DdbValue>[];
+    static to_ddbobjs(values: (DdbObj | string | boolean)[]): DdbObj<DdbValue>[];
     to_cols(): {
         title: string;
         dataIndex: string;
@@ -345,7 +345,7 @@ export declare class DdbVectorString extends DdbObj<string[]> {
     constructor(strings: string[], name?: string);
 }
 export declare class DdbVectorAny extends DdbObj {
-    constructor(objs: (DdbObj | string | boolean | ArrayBuffer)[], name?: string);
+    constructor(objs: (DdbObj | string | boolean)[], name?: string);
 }
 export declare class DdbVectorSymbol extends DdbObj<DdbSymbolExtendedValue> {
     constructor(strings: string[], name?: string);
@@ -464,7 +464,7 @@ type DdbRpcType = 'script' | 'function' | 'variable' | 'connect';
 export interface DdbRpcOptions {
     script?: string;
     func?: string;
-    args?: (DdbObj | string | boolean | ArrayBuffer)[];
+    args?: (DdbObj | string | boolean)[];
     vars?: string[];
     urgent?: boolean;
     listener?: DdbMessageListener;
@@ -515,12 +515,19 @@ export declare class DDB {
     print_message: boolean;
     parse_object: boolean;
     pnode_run_defined: boolean;
+    /** 在 websocket 收到的第一个 error 时，
+        在 connect_websocket 的 on_error 回调中构造 DdbConnectionError 并保存到 DDB 对象上，
+        这个 error 的错误信息最准确
+        this.errored 为 true 时建议 throw this.error || new DdbConnectionError(this) */
+    error: DdbConnectionError;
     /** DdbMessage listeners */
     listeners: DdbMessageListener[];
-    pconnect: import("xshell/utils.browser.js").Deferred<void>;
-    ppnoderun: import("xshell/utils.browser.js").Deferred<void>;
-    presult: import("xshell/utils.browser.js").Deferred<DdbObj<DdbValue>>;
+    /** 为所有 websocket 操作加锁，包括设置 this.on_message, this.on_error, websocket.send */
+    pwebsocket: import("xshell/utils.browser.js").Deferred<void>;
+    /** 为定义 pnode_run 函数加锁，避免重复定义 */
+    ppnode_run: import("xshell/utils.browser.js").Deferred<void>;
     get connected(): boolean;
+    get errored(): boolean | DdbConnectionError;
     /**
         使用 WebSocket URL 初始化连接到 DolphinDB 的实例（不建立实际的网络连接）
         Initialize an instance of DolphinDB Client using the WebSocket URL (without establishing an actual network connection)
@@ -555,9 +562,19 @@ export declare class DDB {
     });
     private on_message;
     private on_error;
-    /** 建立实际的 WebSocket 连接到 URL 对应的 DolphinDB  Establish a actual websocket connection to the DolphindB corresponding to the URL
-        是幂等的，调用后会确保已连接到数据库 (确保 websocket.readyState 为 open)，否则报错  After calling, it will ensure that it has been connected to the database (ensure that websocket.ReadyState is open), otherwise an error will be reported
-        this.autologin 为 true 时自动登录  this.autologin automatically log in when it is true */
+    /** 调用后会确保和数据库的连接是正常的 (this.connected === true && this.errored === false)，否则抛出错误
+        这个方法是幂等的，首次调用建立实际的 WebSocket 连接到 URL 对应的 DolphinDB，后续调用检查上面的条件
+        连接断开后禁止再次调用 connect 重连原有 ddb 对象，应该通过 new DDB() 的方式新建连接对象，原因是：
+        1. on_error 回调和某个 websocket 绑定了，不方便解绑后重新绑定
+        2. session 是有状态的，重连也无法恢复之前的状态
+        3. 断线后所有之前的 ddb.call, ddb.eval 都应该抛出连接错误
+        
+        After calling, it will ensure that the connection with the database is normal (this.connected === true && this.errored === false), otherwise an error will be thrown
+        This method is idempotent, the first call establishes an actual WebSocket connection to the DolphinDB corresponding to the URL, and subsequent calls check the above conditions
+        After the connection is disconnected, it is forbidden to call connect again to reconnect the original ddb object. You should use new DDB() to create a new connection object because:
+        1. The on_error callback is bound to a certain websocket, and it is inconvenient to unbind and rebind
+        2. The session is stateful, and the previous state cannot be restored even after reconnection
+        3. After disconnection, all previous ddb.call, ddb.eval should throw a connection error */
     connect(): Promise<void>;
     get_rpc_options({ urgent, secondary, async: _async, pickle, clear, api, compress, cancellable, priority, parallelism, root_id, limit, }?: {
         urgent?: boolean;
@@ -583,10 +600,10 @@ export declare class DDB {
         limit?: boolean;
     }): string;
     disconnect(): void;
-    /** rpc through websocket (function/script/variable command)
+    /** (内部使用的方法) rpc through websocket (function/script/variable command)
         未连接到 DDB 时调用会自动连接，连接断开时调用会抛出 DdbConnectionError
         When the DDB is not connected, the call will be automatically connected. When the connection is disconnected, the call will throw the DdbConnectionError
-        - type: API 类型: 'script' | 'function' | 'variable'
+        - type: API 类型: 'script' | 'function' | 'variable' | 'connect'
         - options:
             - urgent?: 决定 `行为标识` 那一行字符串的取值（只适用于 script 和 function）
             - vars?: type === 'variable' 时必传，variable 指令中待上传的变量名
@@ -634,7 +651,7 @@ export declare class DDB {
                 When it is false, the returned DdbObj only contains buffer and le without parsing,
                 so as to facilitate subsequent forwarding and serialization
     */
-    call<TResult extends DdbObj>(func: string, args?: (DdbObj | string | boolean | ArrayBuffer)[], { urgent, node, nodes, func_type, add_node_alias, listener, parse_object, }?: {
+    call<TResult extends DdbObj>(func: string, args?: (DdbObj | string | boolean)[], { urgent, node, nodes, func_type, add_node_alias, listener, parse_object, }?: {
         urgent?: boolean;
         node?: string;
         nodes?: string[];
@@ -672,7 +689,7 @@ export interface DdbObjectMessage {
 }
 export interface DdbErrorMessage {
     type: 'error';
-    data: Error;
+    data: DdbDatabaseError;
 }
 export type DdbMessage = DdbPrintMessage | DdbObjectMessage | DdbErrorMessage;
 export declare let ddb: DDB;

package/browser.js

@@ -1691,6 +1691,7 @@ export class DdbNanoTimeStamp extends DdbObj {
 }
 export class DdbBlob extends DdbObj {
     constructor(value) {
+        assert(value, t('new DdbBlob 不能传空的 value'));
         super({
             form: DdbForm.scalar,
             type: DdbType.blob,
@@ -2204,13 +2205,22 @@ export class DDB {
     print_message = true;
     parse_object = true;
     pnode_run_defined = false;
+    /** 在 websocket 收到的第一个 error 时，
+        在 connect_websocket 的 on_error 回调中构造 DdbConnectionError 并保存到 DDB 对象上，
+        这个 error 的错误信息最准确
+        this.errored 为 true 时建议 throw this.error || new DdbConnectionError(this) */
+    error;
     /** DdbMessage listeners */
     listeners = [];
-    pconnect = defer(null);
-    ppnoderun = defer(null);
-    presult = defer(null);
+    /** 为所有 websocket 操作加锁，包括设置 this.on_message, this.on_error, websocket.send */
+    pwebsocket = defer(null);
+    /** 为定义 pnode_run 函数加锁，避免重复定义 */
+    ppnode_run = defer(null);
     get connected() {
-        return this.websocket?.readyState === WebSocket.OPEN;
+        return !this.error && this.websocket?.readyState === WebSocket.OPEN;
+    }
+    get errored() {
+        return this.error || (this.websocket && this.websocket.readyState !== WebSocket.OPEN);
     }
     /**
         使用 WebSocket URL 初始化连接到 DolphinDB 的实例（不建立实际的网络连接）
@@ -2237,16 +2247,14 @@ export class DDB {
         })
     */
     constructor(url, options = {}) {
-        const _url = new URL(location.href);
-        const { searchParams, pathname } = _url;
-        if (url)
-            this.url = url;
-        else {
+        const { searchParams, pathname } = new URL(location.href);
+        if (!url) {
             const dev = pathname.endsWith('/console/');
             const hostname = searchParams.get('hostname') || (dev ? '127.0.0.1' : location.hostname);
             const port = searchParams.get('port') || (dev ? '8848' : location.port);
             url = `${dev ? (searchParams.get('tls') === '1' ? 'wss' : 'ws') : (location.protocol === 'https:' ? 'wss' : 'ws')}://${hostname}${port ? `:${port}` : ''}/`;
         }
+        this.url = url;
         this.verbose = options.verbose === undefined ?
             searchParams.get('verbose') === '1'
             :
@@ -2263,61 +2271,85 @@ export class DDB {
             this.streaming = options.streaming;
     }
     on_message(buffer, websocket) {
-        // 这里的实现一定会被 connect, rpc 中的实现覆盖
+        throw t('这是在调用 this.rpc 之前默认的 on_message, 不应该被调用到，除非建立连接后 server 先推送了 message');
     }
-    on_error(error, websocket) {
+    on_error() {
         // 这里的实现一定会被 connect, rpc 中的实现覆盖
     }
-    /** 建立实际的 WebSocket 连接到 URL 对应的 DolphinDB  Establish a actual websocket connection to the DolphindB corresponding to the URL
-        是幂等的，调用后会确保已连接到数据库 (确保 websocket.readyState 为 open)，否则报错  After calling, it will ensure that it has been connected to the database (ensure that websocket.ReadyState is open), otherwise an error will be reported
-        this.autologin 为 true 时自动登录  this.autologin automatically log in when it is true */
+    /** 调用后会确保和数据库的连接是正常的 (this.connected === true && this.errored === false)，否则抛出错误
+        这个方法是幂等的，首次调用建立实际的 WebSocket 连接到 URL 对应的 DolphinDB，后续调用检查上面的条件
+        连接断开后禁止再次调用 connect 重连原有 ddb 对象，应该通过 new DDB() 的方式新建连接对象，原因是：
+        1. on_error 回调和某个 websocket 绑定了，不方便解绑后重新绑定
+        2. session 是有状态的，重连也无法恢复之前的状态
+        3. 断线后所有之前的 ddb.call, ddb.eval 都应该抛出连接错误
+        
+        After calling, it will ensure that the connection with the database is normal (this.connected === true && this.errored === false), otherwise an error will be thrown
+        This method is idempotent, the first call establishes an actual WebSocket connection to the DolphinDB corresponding to the URL, and subsequent calls check the above conditions
+        After the connection is disconnected, it is forbidden to call connect again to reconnect the original ddb object. You should use new DDB() to create a new connection object because:
+        1. The on_error callback is bound to a certain websocket, and it is inconvenient to unbind and rebind
+        2. The session is stateful, and the previous state cannot be restored even after reconnection
+        3. After disconnection, all previous ddb.call, ddb.eval should throw a connection error */
     async connect() {
+        if (this.errored)
+            throw this.error || new DdbConnectionError(this);
         if (this.connected)
             return;
-        const ptail = this.pconnect;
-        const pconnect = this.pconnect = defer();
-        await ptail;
+        // 准备进入 websocket 临界区
+        const ptail = this.pwebsocket;
+        let pwebsocket = this.pwebsocket = defer();
+        // 避免 pwebsocket.reject 后出现 triggerUncaughtException
+        pwebsocket.catch(() => { });
+        // 上一个请求出现了 websocket 错误，那么直接抛出异常，且通过 reject 当前锁 (pwebsocket)，安全退出临界区
         try {
-            if (!this.connected) {
-                this.on_error = (error, websocket) => {
-                    pconnect.reject(new DdbConnectionError(this, error));
-                };
-                this.on_message = (buffer, websocket) => {
-                    assert(false, t('这是在调用 this.rpc 之前默认的 on_message, 不应该被调用到，除非建立连接后 server 先推送了 message'));
-                };
-                this.presult = defer(null);
-                this.pnode_run_defined = false;
-                try {
-                    this.websocket = await connect_websocket(this.url, {
-                        protocols: (() => {
-                            if (this.streaming)
-                                return 'streaming';
-                            if (this.python)
-                                return 'python';
-                        })(),
-                        on_message: (buffer, websocket) => {
-                            this.on_message(buffer, websocket);
-                        },
-                        on_error: (error, websocket) => {
-                            this.on_error(error, websocket);
-                        }
-                    });
-                }
-                catch (error) {
-                    throw new DdbConnectionError(this, error);
-                }
-                if (this.streaming)
-                    await this.subscribe();
-                else {
-                    await this.rpc('connect', {});
-                    if (this.autologin)
-                        await this.call('login', [this.username, this.password], { urgent: true });
+            await ptail;
+            // 已进入 websocket 临界区
+        }
+        catch (error) {
+            pwebsocket.reject(error);
+            throw error;
+        }
+        if (this.errored) {
+            const error = this.error || new DdbConnectionError(this);
+            pwebsocket.reject(error);
+            throw error;
+        }
+        if (this.connected) {
+            pwebsocket.resolve();
+            return;
+        }
+        this.on_error = () => {
+            pwebsocket.reject(this.error /* 一定有，不需要再 || new DdbConnectionError(this)  */);
+        };
+        try {
+            this.websocket = await connect_websocket(this.url, {
+                protocols: (() => {
+                    if (this.streaming)
+                        return 'streaming';
+                    if (this.python)
+                        return 'python';
+                })(),
+                on_message: (buffer, websocket) => {
+                    this.on_message(buffer, websocket);
+                },
+                on_error: error => {
+                    this.error ??= new DdbConnectionError(this, error);
+                    this.on_error();
                 }
-            }
+            });
         }
-        finally {
-            pconnect.resolve();
+        catch (error) {
+            this.error ??= new DdbConnectionError(this, error);
+            pwebsocket.reject(error);
+            throw this.error;
         }
+        assert(this.connected);
+        pwebsocket.resolve();
+        // websocket 临界区结束
+        await this.rpc('connect', {});
+        if (this.autologin)
+            await this.call('login', [this.username, this.password], { urgent: true });
+        if (this.streaming)
+            await this.subscribe();
     }
     get_rpc_options({ urgent = false, secondary = false, async: _async = false, pickle = false, clear = false, api = false, compress = false, cancellable = true, priority = urgent ? 8 : 4, parallelism = 8, root_id = '', limit, } = {}) {
         let flag = 0;
@@ -2354,10 +2386,10 @@ export class DDB {
         if (this.connected)
             this.websocket.close(1000);
     }
-    /** rpc through websocket (function/script/variable command)
+    /** (内部使用的方法) rpc through websocket (function/script/variable command)
         未连接到 DDB 时调用会自动连接，连接断开时调用会抛出 DdbConnectionError
         When the DDB is not connected, the call will be automatically connected. When the connection is disconnected, the call will throw the DdbConnectionError
-        - type: API 类型: 'script' | 'function' | 'variable'
+        - type: API 类型: 'script' | 'function' | 'variable' | 'connect'
         - options:
             - urgent?: 决定 `行为标识` 那一行字符串的取值（只适用于 script 和 function）
             - vars?: type === 'variable' 时必传，variable 指令中待上传的变量名
@@ -2365,19 +2397,27 @@ export class DDB {
             - parse_object?: 在本次 rpc 期间设置 parse_object, 结束后恢复原有
                 为 false 时返回的 DdbObj 仅含有 buffer 和 le，不做解析，以便后续转发、序列化 */
     async rpc(type, options) {
-        if (!this.websocket)
-            await this.connect();
-        if (!this.connected)
-            throw new DdbConnectionError(this);
-        const { script, func, vars = [], urgent, listener, } = options;
-        let { args = [] } = options;
+        // 保留调用栈信息
+        let error = new DdbDatabaseError('', this, type, options);
+        await this.connect();
+        const { script, func, args: _args = [], vars = [], urgent, listener, } = options;
         if (func === 'pnode_run' && !this.pnode_run_defined) {
-            // 保证并发调用 rpc 时只定义一次 pnode_run
-            const ptail = this.ppnoderun;
-            const ppnoderun = this.ppnoderun = defer();
-            await ptail;
+            // 准备进入 pnode_run 临界区，保证并发调用 rpc 时只定义一次 pnode_run
+            const ptail = this.ppnode_run;
+            let ppnode_run = this.ppnode_run = defer();
+            // 避免 ppnode_run.reject 后出现 triggerUncaughtException
+            ppnode_run.catch(() => { });
+            // 如果之前的定义失败了，再定义一次也会失败，直接抛出之前的错误，且安全地退出临界区
             try {
-                if (!this.pnode_run_defined)
+                await ptail;
+                // 已进入 pnode_run 临界区
+            }
+            catch (error) {
+                ppnode_run.reject(error);
+                throw error;
+            }
+            if (!this.pnode_run_defined)
+                try {
                     await this.eval(this.python ?
                         'def pnode_run (nodes, func_name, args, add_node_alias):\n' +
                             '    nargs = size(args)\n' +
@@ -2413,95 +2453,108 @@ export class DDB {
                                 '        add_node_alias\n' +
                                 '    )\n' +
                                 '}\n', { urgent: true });
-            }
-            finally {
-                ppnoderun.resolve();
-            }
+                    this.pnode_run_defined = true;
+                    ppnode_run.resolve();
+                }
+                catch (error) {
+                    // 这次失败了，之后的执行肯定也会失败
+                    ppnode_run.reject(error);
+                    throw error;
+                }
         }
         // this 上的当前配置需要在 message 到达后使用，先保存起来
-        const _handlers = [...this.listeners].reverse();
-        let error = new DdbDatabaseError('', this, type, options);
-        // 临界区：保证多个 rpc 并发时形成 promise 链
+        const _listeners = [...this.listeners].reverse();
+        // websocket 临界区：保证多个 rpc 并发时形成 promise 链
         // ddb 世界观：需要等待上一个 rpc 结果从 server 返回之后才能发起下一个调用  
         // 违反世界观可能造成:  
         // 1. 并发多个请求只返回第一个结果（阻塞，需后续请求疏通）
         // 2. windows 下 ddb server 返回多个相同的结果
-        const ptail = this.presult;
-        const presult = this.presult = defer();
+        const ptail = this.pwebsocket;
+        let pwebsocket = this.pwebsocket = defer();
+        // 避免 pwebsocket.reject 后出现 triggerUncaughtException
+        pwebsocket.catch(() => { });
+        // 上一个请求出现了 websocket 错误，那么直接抛出异常，且通过 reject 当前锁 (pwebsocket)，安全退出临界区
         try {
             await ptail;
+            // 已进入临界区，只有一个 rpc 函数调用运行到这里，可以独占 this.on_message 然后写 WebSocket
         }
-        catch { }
-        // 临界区结束，只有一个 rpc 函数调用运行到这里，可以独占 this.on_message 然后写 WebSocket
-        if (!this.connected) {
-            presult.reject(new DdbConnectionError(this));
-            return presult;
+        catch (error) {
+            pwebsocket.reject(error);
+            throw error;
         }
-        this.on_error = (error, websocket) => {
-            presult.reject(new DdbConnectionError(this, error));
-        };
-        this.on_message = buffer => {
-            try {
-                const buf = new Uint8Array(buffer);
-                if (this.print_message_buffer)
-                    console.log(buf);
-                const message = this.parse_message(buf, error);
-                listener?.(message, this);
-                for (const listener of _handlers)
-                    listener(message, this);
-                const { type, data } = message;
+        // 既然上一个请求没有出现 websocket error，且函数开头已经调用了 await this.connect() 检查过，
+        // 这里也乐观的认为 this.connected && !this.errored 为 true
+        return new Promise((resolve, reject) => {
+            this.on_error = () => {
+                pwebsocket.reject(this.error /* 这里一定有了 this.error, 不需要再 || new DdbConnectionError(this) */);
+                reject(this.error);
+            };
+            this.on_message = buffer => {
+                try {
+                    const buf = new Uint8Array(buffer);
+                    if (this.print_message_buffer)
+                        console.log(buf);
+                    const message = this.parse_message(buf, error);
+                    listener?.(message, this);
+                    for (const listener of _listeners)
+                        listener(message, this);
+                    const { type, data } = message;
+                    switch (type) {
+                        case 'print':
+                            if (this.print_message)
+                                console.log(data);
+                            break;
+                        case 'object':
+                            pwebsocket.resolve();
+                            resolve(data);
+                            break;
+                        case 'error':
+                            pwebsocket.resolve();
+                            reject(data);
+                            break;
+                    }
+                }
+                catch (error) {
+                    pwebsocket.resolve();
+                    // 这里的错误并非 websocket 错误，而是 rpc 错误
+                    reject(error);
+                }
+            };
+            const args = DdbObj.to_ddbobjs(_args);
+            const command = this.enc.encode((() => {
                 switch (type) {
-                    case 'print':
-                        if (this.print_message)
-                            console.log(data);
-                        return;
-                    case 'object':
-                        presult.resolve(data);
-                        return;
-                    case 'error':
-                        presult.reject(data);
-                        return;
+                    case 'function':
+                        if (this.verbose)
+                            console.log(func + args.map(arg => arg.toString()).join(', ').bracket());
+                        return 'function\n' +
+                            `${func}\n` +
+                            `${args.length}\n` +
+                            `${Number(DDB.le_client)}\n`;
+                    case 'script':
+                        if (this.verbose)
+                            console.log(script);
+                        return 'script\n' +
+                            script;
+                    case 'variable':
+                        if (this.verbose)
+                            for (let i = 0; i < vars.length; i++)
+                                console.log(`${vars[i]} = ${args[i].toString()}`);
+                        return 'variable\n' +
+                            `${vars.join(',')}\n` +
+                            `${vars.length}\n` +
+                            `${Number(DDB.le_client)}\n`;
+                    case 'connect':
+                        if (this.verbose)
+                            console.log('connect()');
+                        return 'connect\n';
                 }
-            }
-            catch (error) {
-                presult.reject(error);
-            }
-        };
-        args = DdbObj.to_ddbobjs(args);
-        const command = this.enc.encode((() => {
-            switch (type) {
-                case 'function':
-                    if (this.verbose)
-                        console.log(func + args.map(arg => arg.toString()).join(', ').bracket());
-                    return 'function\n' +
-                        `${func}\n` +
-                        `${args.length}\n` +
-                        `${Number(DDB.le_client)}\n`;
-                case 'script':
-                    if (this.verbose)
-                        console.log(script);
-                    return 'script\n' +
-                        script;
-                case 'variable':
-                    if (this.verbose)
-                        for (let i = 0; i < vars.length; i++)
-                            console.log(`${vars[i]} = ${args[i].toString()}`);
-                    return 'variable\n' +
-                        `${vars.join(',')}\n` +
-                        `${vars.length}\n` +
-                        `${Number(DDB.le_client)}\n`;
-                case 'connect':
-                    if (this.verbose)
-                        console.log('connect()');
-                    return 'connect\n';
-            }
-        })());
-        this.websocket.send(concat([
-            this.enc.encode(`API2 ${this.sid} ${command.length} / ${this.get_rpc_options({ urgent })}\n`),
-            command,
-            ...args.map((arg) => arg.pack())
-        ]));
-        return presult;
+            })());
+            this.websocket.send(concat([
+                this.enc.encode(`API2 ${this.sid} ${command.length} / ${this.get_rpc_options({ urgent })}\n`),
+                command,
+                ...args.map(arg => arg.pack())
+            ]));
+        });
     }
     /** eval script through websocket (script command)
         - script?: 执行的脚本  Script to execute
@@ -2653,9 +2706,6 @@ export class DDB {
     }
     /** 内部的流订阅方法  Internal stream subscription method */
     async subscribe() {
-        await this.rpc('connect', {});
-        if (this.autologin)
-            await this.call('login', [this.username, this.password]);
         console.log(t('订阅流表成功') + ', colnames:', 
         // string[3](['time', 'stock', 'price'])
         this.streaming.colnames = (await this.call('publishTable', [