libshv-js 3.11.0 → 3.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libshv-js",
-  "version": "3.11.0",
+  "version": "3.12.0",
   "description": "Typescript implementation of libshv",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
@@ -31,12 +31,12 @@
     "zod": "^3.25.67"
   },
   "devDependencies": {
-    "@typescript-eslint/parser": "^8.27.0",
-    "eslint": "^9.22.0",
-    "eslint-config-xo": "^0.46.0",
+    "@typescript-eslint/parser": "^8.35.0",
+    "eslint": "^9.29.0",
+    "eslint-config-xo": "^0.47.0",
     "eslint-formatter-unix": "^8.40.0",
-    "eslint-plugin-unicorn": "^57.0.0",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.27.0"
+    "eslint-plugin-unicorn": "^59.0.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.35.0"
   }
 }

package/src/rpcmessage.ts

@@ -9,6 +9,7 @@ export const RPC_MESSAGE_PARAMS = 1;
 export const RPC_MESSAGE_RESULT = 2;
 export const RPC_MESSAGE_ERROR = 3;
 export const RPC_MESSAGE_DELAY = 4;
+export const RPC_MESSAGE_ABORT = 5;
 
 export const ERROR_CODE = 1;
 export const ERROR_MESSAGE = 2;
@@ -46,7 +47,9 @@ const RpcRequestMetaZod = z.metamap({
 
 const RpcRequestValueZod = z.imap({
     [RPC_MESSAGE_PARAMS]: z.rpcvalue().optional(),
-});
+}).or(z.imap({
+    [RPC_MESSAGE_ABORT]: z.boolean(),
+}));
 
 const RpcResponseMetaZod = z.metamap({
     [RPC_MESSAGE_CALLER_IDS]: z.int().or(z.array(z.int())).optional(),

package/src/rpcvalue.ts

@@ -137,7 +137,9 @@ const makeMap = <T extends Record<string, RpcValue> = Record<string, RpcValue>,
 });
 
 class RpcValueWithMetaData<MetaSchema extends MetaMap = MetaMap, ValueSchema extends RpcValueType = RpcValueType> {
-    constructor(public meta: MetaSchema, public value: ValueSchema) {}
+    constructor(public meta: MetaSchema, public value: ValueSchema) {
+        /* nothing */
+    }
 }
 
 export type RpcValue = RpcValueType | RpcValueWithMetaData;

package/src/ws-client.ts

@@ -1,6 +1,6 @@
 import {ChainPackReader, CHAINPACK_PROTOCOL_TYPE, ChainPackWriter, toChainPack} from './chainpack';
 import {type CponReader, CPON_PROTOCOL_TYPE, toCpon} from './cpon';
-import {ERROR_MESSAGE, ErrorCode, ERROR_CODE, RpcMessageZod, type RpcMessage, isSignal, isRequest, type RpcRequest, isResponse, ERROR_DATA, type ErrorMap, RPC_MESSAGE_METHOD, RPC_MESSAGE_SHV_PATH, RPC_MESSAGE_REQUEST_ID, RPC_MESSAGE_PARAMS, RPC_MESSAGE_ERROR, RPC_MESSAGE_RESULT, RPC_MESSAGE_CALLER_IDS, RpcResponseValue, RPC_MESSAGE_DELAY} from './rpcmessage';
+import {ERROR_MESSAGE, ErrorCode, ERROR_CODE, RpcMessageZod, type RpcMessage, isSignal, isRequest, type RpcRequest, isResponse, ERROR_DATA, type ErrorMap, RPC_MESSAGE_METHOD, RPC_MESSAGE_SHV_PATH, RPC_MESSAGE_REQUEST_ID, RPC_MESSAGE_PARAMS, RPC_MESSAGE_ERROR, RPC_MESSAGE_RESULT, RPC_MESSAGE_CALLER_IDS, RpcResponseValue, RPC_MESSAGE_DELAY, RPC_MESSAGE_ABORT, RpcSignal, RpcResponse} from './rpcmessage';
 import {type RpcValue, type Null, type Int, type IMap, type ShvMap, makeMap, makeIMap, RpcValueWithMetaData, makeMetaMap, Double} from './rpcvalue';
 
 const DEFAULT_TIMEOUT = 5000;
@@ -50,6 +50,16 @@ type WsClientOptionsCommon = {
     wsUri: string;
 };
 
+export class RequestHandler {
+    constructor(public options: {
+        result: Promise<RpcValue>;
+        onAbort?: () => void;
+        onProgressQuery?: () => number | Promise<number>;
+    }) {
+        /* nothing */
+    }
+}
+
 type WsClientOptionsLogin = WsClientOptionsCommon & {
     mountPoint?: string;
     login: Login;
@@ -58,7 +68,7 @@ type WsClientOptionsLogin = WsClientOptionsCommon & {
     onConnected: () => void;
     onConnectionFailure: (error: Error) => void;
     onDisconnected: () => void;
-    onRequest: (shvPath: string, method: string, param: RpcValue, delay: (progress: number) => void) => RpcValue | Promise<RpcValue>;
+    onRequest: (shvPath: string, method: string, param: RpcValue, delay: (progress: number) => void) => RpcValue | Promise<RpcValue> | RequestHandler;
 };
 
 type WsClientOptionsWorkflows = WsClientOptionsCommon & {
@@ -137,13 +147,30 @@ export const UserIDRequired = createErrorClass(ErrorCode.UserIDRequired);
 export const NotImplemented = createErrorClass(ErrorCode.NotImplemented);
 /* eslint-enable @typescript-eslint/naming-convention */
 
+const makeTimeout = (ms: number, resolve: RpcResponseResolver) => globalThis.setTimeout(() => {
+    resolve(new MethodCallTimeout(makeIMap({
+        [ERROR_CODE]: ErrorCode.MethodCallTimeout,
+        [ERROR_MESSAGE]: `Shv call timeout after: ${ms} msec.`,
+        [ERROR_DATA]: undefined,
+    })));
+}, ms);
+
+class RpcRequestPromise<Result> extends Promise<Result> {
+    constructor(executor: (resolve: (value: Result | PromiseLike<Result>) => void, reject: (reason?: unknown) => void) => void, public readonly abort: () => void, public readonly progressQuery: () => void) {
+        super(executor);
+    }
+}
+
 class WsClient {
     private requestId = 1;
     private pingTimerId: ReturnType<typeof globalThis.setInterval> | undefined = undefined;
     private rpcHandlers: Array<{
         resolve: RpcResponseResolver;
+        delayCallback?: (progress: number) => void;
         timeout_handle: ReturnType<typeof globalThis.setTimeout>;
     }> = [];
+    private requestHandlers: RequestHandler[] = [];
+    private abortedRequests = new Set<number>();
     private readonly subscriptions: Subscription[] = [];
     private readonly websocket: WebSocket;
     private readonly options: WsClientOptions;
@@ -160,105 +187,166 @@ class WsClient {
         this.websocket = new WebSocket(options.wsUri);
         this.websocket.binaryType = 'arraybuffer';
 
-        this.websocket.addEventListener('message', async (evt: MessageEvent<ArrayBuffer>) => {
-            const rpcVal = dataToRpcValue(evt.data);
+        const handleSignal = (signal: RpcSignal) => {
+            for (const sub of this.subscriptions) {
+                const shvPath = signal.meta[RPC_MESSAGE_SHV_PATH];
+                const method = signal.meta[RPC_MESSAGE_METHOD];
 
-            const rpcMsg = RpcMessageZod.parse(rpcVal);
-            this.logDebug(`message received: ${toCpon(rpcMsg)}`);
+                if (shvPath.startsWith(sub.path) && method === sub.method) {
+                    sub.callback(shvPath, method, signal.value[RPC_MESSAGE_PARAMS]);
+                }
+            }
+        };
+
+        const handleRequest = async (request: RpcRequest) => {
+            if ('onRequest' in this.options) {
+                const requestId = request.meta[RPC_MESSAGE_REQUEST_ID];
+                const respond = (value: RpcResponseValue) => {
+                    this.sendRpcMessage(new RpcValueWithMetaData(
+                        makeMetaMap({
+                            [RPC_MESSAGE_CALLER_IDS]: request.meta[RPC_MESSAGE_CALLER_IDS],
+                            [RPC_MESSAGE_REQUEST_ID]: requestId,
+                        }),
+                        value,
+                    ));
+                };
 
-            if (isSignal(rpcMsg)) {
-                for (const sub of this.subscriptions) {
-                    const shvPath = rpcMsg.meta[RPC_MESSAGE_SHV_PATH];
-                    const method = rpcMsg.meta[RPC_MESSAGE_METHOD];
+                const sendDelay = (progress: number) => {
+                    respond(makeIMap({
+                        [RPC_MESSAGE_DELAY]: new Double(progress),
+                    }));
+                };
+
+                if (RPC_MESSAGE_ABORT in request.value) {
+                    const requestHandler = this.requestHandlers[requestId];
 
-                    if (shvPath.startsWith(sub.path) && method === sub.method) {
-                        sub.callback(shvPath, method, rpcMsg.value[RPC_MESSAGE_PARAMS]);
+                    if (request.value[RPC_MESSAGE_ABORT] === true && requestHandler?.options.onAbort !== undefined) {
+                        this.abortedRequests.add(requestId);
+                        requestHandler.options.onAbort();
                     }
+
+                    if (request.value[RPC_MESSAGE_ABORT] === false && requestHandler?.options.onProgressQuery !== undefined) {
+                        const progress = requestHandler.options.onProgressQuery();
+                        sendDelay(progress instanceof Promise ? await progress : progress);
+                    }
+
+                    return;
                 }
-            } else if (isRequest(rpcMsg)) {
-                if ('onRequest' in this.options) {
-                    const respond = (value: RpcResponseValue) => {
-                        this.sendRpcMessage(new RpcValueWithMetaData(
-                            makeMetaMap({
-                                [RPC_MESSAGE_CALLER_IDS]: rpcMsg.meta[RPC_MESSAGE_CALLER_IDS],
-                                [RPC_MESSAGE_REQUEST_ID]: rpcMsg.meta[RPC_MESSAGE_REQUEST_ID],
-                            }),
-                            value,
-                        ));
-                    };
 
-                    try {
-                        const sendDelay = (progress: number) => {
-                            respond(makeIMap({
-                                [RPC_MESSAGE_DELAY]: new Double(progress),
-                            }));
-                        };
+                try {
+                    let result = this.options.onRequest(request.meta[RPC_MESSAGE_SHV_PATH], request.meta[RPC_MESSAGE_METHOD], request.value[RPC_MESSAGE_PARAMS], sendDelay);
+                    if (result instanceof RequestHandler) {
+                        this.requestHandlers[requestId] = result;
+                        result = result.options.result;
+                    }
+
+                    const resultOrError = makeIMap({
+                        [RPC_MESSAGE_RESULT]: result instanceof Promise ? await result : result,
+                    });
+
+                    if (!this.abortedRequests.has(requestId)) {
+                        respond(resultOrError);
+                    } else {
+                        this.abortedRequests.delete(requestId);
+                    }
 
-                        const result = this.options.onRequest(rpcMsg.meta[RPC_MESSAGE_SHV_PATH], rpcMsg.meta[RPC_MESSAGE_METHOD], rpcMsg.value[RPC_MESSAGE_PARAMS], sendDelay);
+                    if (requestId in this.requestHandlers) {
+                        // eslint-disable-next-line @typescript-eslint/no-array-delete
+                        delete this.requestHandlers[requestId];
+                    }
+                } catch (error: unknown) {
+                    const sendError = (error: RpcError) => {
                         respond(makeIMap({
-                            [RPC_MESSAGE_RESULT]: result instanceof Promise ? await result : result,
+                            [RPC_MESSAGE_ERROR]: error.err_info,
                         }));
-                    } catch (error: unknown) {
-                        const sendError = (error: RpcError) => {
-                            respond(makeIMap({
-                                [RPC_MESSAGE_ERROR]: error.err_info,
-                            }));
-                        };
-
-                        switch (true) {
-                            case error instanceof RpcError:
-                                sendError(error);
-                                break;
-                            case error instanceof Error:
-                                sendError(new InternalError(error.message));
-                                break;
-                            default:
-                                sendError(new InternalError('Unknown error'));
-                                break;
-                        }
+                    };
+
+                    switch (true) {
+                        case error instanceof RpcError:
+                            sendError(error);
+                            break;
+                        case error instanceof Error:
+                            sendError(new InternalError(error.message));
+                            break;
+                        default:
+                            sendError(new InternalError('Unknown error'));
+                            break;
                     }
                 }
-            } else if (isResponse(rpcMsg)) {
-                const requestId = rpcMsg.meta[RPC_MESSAGE_REQUEST_ID];
-
-                if (this.rpcHandlers[Number(requestId)] !== undefined) {
-                    const handler = this.rpcHandlers[Number(requestId)];
-                    clearTimeout(handler.timeout_handle);
-                    handler.resolve((() => {
-                        if (RPC_MESSAGE_ERROR in rpcMsg.value) {
-                            const code = rpcMsg.value[RPC_MESSAGE_ERROR][ERROR_CODE] as unknown;
-                            // eslint-disable-next-line @typescript-eslint/naming-convention
-                            const ErrorTypeCtor = (() => {
-                                switch (code) {
-                                    case ErrorCode.InvalidRequest: return InvalidRequest;
-                                    case ErrorCode.MethodNotFound: return MethodNotFound;
-                                    case ErrorCode.InvalidParams: return InvalidParams;
-                                    case ErrorCode.InternalError: return InternalError;
-                                    case ErrorCode.ParseError: return ParseError;
-                                    case ErrorCode.MethodCallTimeout: return MethodCallTimeout;
-                                    case ErrorCode.MethodCallCancelled: return MethodCallCancelled;
-                                    case ErrorCode.MethodCallException: return MethodCallException;
-                                    case ErrorCode.Unknown: return Unknown;
-                                    case ErrorCode.LoginRequired: return LoginRequired;
-                                    case ErrorCode.UserIDRequired: return UserIDRequired;
-                                    case ErrorCode.NotImplemented: return NotImplemented;
-                                    default: return Unknown;
-                                }
-                            })();
-
-                            return new ErrorTypeCtor(rpcMsg.value[RPC_MESSAGE_ERROR]);
-                        }
-
-                        if (RPC_MESSAGE_RESULT in rpcMsg.value) {
-                            return rpcMsg.value[RPC_MESSAGE_RESULT];
-                        }
-
-                        // If both result and error are missing, the result is implicitly Null.
-                        // https://silicon-heaven.github.io/shv-doc/rpcmessage.html#response
-                    })());
-                    // eslint-disable-next-line @typescript-eslint/no-array-delete
-                    delete this.rpcHandlers[Number(requestId)];
+            }
+        };
+
+        const handleResponse = (response: RpcResponse) => {
+            const requestId = response.meta[RPC_MESSAGE_REQUEST_ID];
+
+            if (this.rpcHandlers[Number(requestId)] !== undefined) {
+                const handler = this.rpcHandlers[Number(requestId)];
+                clearTimeout(handler.timeout_handle);
+
+                if (RPC_MESSAGE_DELAY in response.value) {
+                    if (handler.delayCallback !== undefined) {
+                        handler.delayCallback(response.value[RPC_MESSAGE_DELAY].value);
+                    }
+
+                    handler.timeout_handle = makeTimeout(this.timeout, handler.resolve);
+                    return;
                 }
+
+                handler.resolve((() => {
+                    if (RPC_MESSAGE_ERROR in response.value) {
+                        const code = response.value[RPC_MESSAGE_ERROR][ERROR_CODE] as unknown;
+                        // eslint-disable-next-line @typescript-eslint/naming-convention
+                        const ErrorTypeCtor = (() => {
+                            switch (code) {
+                                case ErrorCode.InvalidRequest: return InvalidRequest;
+                                case ErrorCode.MethodNotFound: return MethodNotFound;
+                                case ErrorCode.InvalidParams: return InvalidParams;
+                                case ErrorCode.InternalError: return InternalError;
+                                case ErrorCode.ParseError: return ParseError;
+                                case ErrorCode.MethodCallTimeout: return MethodCallTimeout;
+                                case ErrorCode.MethodCallCancelled: return MethodCallCancelled;
+                                case ErrorCode.MethodCallException: return MethodCallException;
+                                case ErrorCode.Unknown: return Unknown;
+                                case ErrorCode.LoginRequired: return LoginRequired;
+                                case ErrorCode.UserIDRequired: return UserIDRequired;
+                                case ErrorCode.NotImplemented: return NotImplemented;
+                                default: return Unknown;
+                            }
+                        })();
+
+                        return new ErrorTypeCtor(response.value[RPC_MESSAGE_ERROR]);
+                    }
+
+                    if (RPC_MESSAGE_RESULT in response.value) {
+                        return response.value[RPC_MESSAGE_RESULT];
+                    }
+
+                    // At this point, the RpcResponse either has:
+                    // - no keys, which means that the response has an implicit Null result.
+                    // - has some unknown keys, in which case we will produce an error for the client.
+                    // https://silicon-heaven.github.io/shv-doc/rpcmessage.html#response
+                    const rpcMessageKeys = Object.keys(response.value);
+                    if (rpcMessageKeys.length !== 0) {
+                        return new NotImplemented(`Got an RpcResponse with unsupported keys: ${rpcMessageKeys.join(' ')}`);
+                    }
+                })());
+                // eslint-disable-next-line @typescript-eslint/no-array-delete
+                delete this.rpcHandlers[Number(requestId)];
+            }
+        };
+
+        this.websocket.addEventListener('message', async (evt: MessageEvent<ArrayBuffer>) => {
+            const rpcVal = dataToRpcValue(evt.data);
+
+            const rpcMsg = RpcMessageZod.parse(rpcVal);
+            this.logDebug(`message received: ${toCpon(rpcMsg)}`);
+
+            if (isSignal(rpcMsg)) {
+                handleSignal(rpcMsg);
+            } else if (isRequest(rpcMsg)) {
+                await handleRequest(rpcMsg);
+            } else if (isResponse(rpcMsg)) {
+                handleResponse(rpcMsg);
             }
         });
 
@@ -274,31 +362,34 @@ class WsClient {
         }
     }
 
-    callRpcMethod(shvPath: '.broker/currentClient', method: 'accessGrantForMethodCall', params: [string, string]): Promise<ResultOrError<string>>;
-    callRpcMethod(shvPath: string | undefined, method: 'dir', params?: RpcValue): Promise<ResultOrError<DirResult>>;
-    callRpcMethod(shvPath: string | undefined, method: 'ls', params?: RpcValue): Promise<ResultOrError<LsResult>>;
-    callRpcMethod(shvPath: string | undefined, method: string, params?: RpcValue): Promise<ResultOrError>;
-    callRpcMethod(shvPath: string | undefined, method: string, params?: RpcValue): Promise<ResultOrError> {
+    callRpcMethod(shvPath: '.broker/currentClient', method: 'accessGrantForMethodCall', params: [string, string], delayCallback?: (progress: number) => void): RpcRequestPromise<ResultOrError<string>>;
+    callRpcMethod(shvPath: string | undefined, method: 'dir', params?: RpcValue, delayCallback?: (progress: number) => void): RpcRequestPromise<ResultOrError<DirResult>>;
+    callRpcMethod(shvPath: string | undefined, method: 'ls', params?: RpcValue, delayCallback?: (progress: number) => void): RpcRequestPromise<ResultOrError<LsResult>>;
+    callRpcMethod(shvPath: string | undefined, method: string, params?: RpcValue, delayCallback?: (progress: number) => void): RpcRequestPromise<ResultOrError>;
+    callRpcMethod(shvPath: string | undefined, method: string, params?: RpcValue, delayCallback?: (progress: number) => void): RpcRequestPromise<ResultOrError> {
         const rqId = this.requestId++;
-        const rq: RpcRequest = new RpcValueWithMetaData(makeMetaMap({
+        const makeRq = (value: IMap) => new RpcValueWithMetaData(makeMetaMap({
             [RPC_MESSAGE_CALLER_IDS]: undefined,
             [RPC_MESSAGE_REQUEST_ID]: rqId,
             [RPC_MESSAGE_METHOD]: method ?? '',
             [RPC_MESSAGE_SHV_PATH]: shvPath ?? '',
-        }), makeIMap({
+        }), value);
+        const rq: RpcRequest = makeRq(makeIMap({
             [RPC_MESSAGE_PARAMS]: params,
         }));
 
         this.sendRpcMessage(rq);
 
-        const promise = new Promise<ResultOrError>(resolve => {
-            this.rpcHandlers[rqId] = {resolve, timeout_handle: globalThis.setTimeout(() => {
-                resolve(new MethodCallTimeout(makeIMap({
-                    [ERROR_CODE]: ErrorCode.MethodCallTimeout,
-                    [ERROR_MESSAGE]: `Shv call timeout after: ${this.timeout} msec.`,
-                    [ERROR_DATA]: undefined,
-                })));
-            }, this.timeout)};
+        const promise = new RpcRequestPromise<ResultOrError>(resolve => {
+            this.rpcHandlers[rqId] = {resolve, timeout_handle: makeTimeout(this.timeout, resolve), delayCallback};
+        }, () => {
+            this.sendRpcMessage(makeRq(makeIMap({
+                [RPC_MESSAGE_ABORT]: true,
+            })));
+        }, () => {
+            this.sendRpcMessage(makeRq(makeIMap({
+                [RPC_MESSAGE_ABORT]: false,
+            })));
         });
 
         return promise;