@pezkuwi/rpc-provider 16.5.5 → 16.5.6

package/{build → cjs}/ws/index.d.ts

@@ -4,7 +4,7 @@ interface SubscriptionHandler {
     type: string;
 }
 /**
- * # @polkadot/rpc-provider/ws
+ * # @pezkuwi/rpc-provider/ws
  *
  * @name WsProvider
  *

package/cjs/ws/index.js

@@ -0,0 +1,529 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WsProvider = void 0;
+const tslib_1 = require("tslib");
+const eventemitter3_1 = require("eventemitter3");
+const util_1 = require("@pezkuwi/util");
+const x_global_1 = require("@pezkuwi/x-global");
+const x_ws_1 = require("@pezkuwi/x-ws");
+const index_js_1 = require("../coder/index.js");
+const defaults_js_1 = tslib_1.__importDefault(require("../defaults.js"));
+const lru_js_1 = require("../lru.js");
+const errors_js_1 = require("./errors.js");
+const ALIASES = {
+    chain_finalisedHead: 'chain_finalizedHead',
+    chain_subscribeFinalisedHeads: 'chain_subscribeFinalizedHeads',
+    chain_unsubscribeFinalisedHeads: 'chain_unsubscribeFinalizedHeads'
+};
+const RETRY_DELAY = 2_500;
+const DEFAULT_TIMEOUT_MS = 60 * 1000;
+const TIMEOUT_INTERVAL = 5_000;
+const l = (0, util_1.logger)('api-ws');
+/** @internal Clears a Record<*> of all keys, optionally with all callback on clear */
+function eraseRecord(record, cb) {
+    Object.keys(record).forEach((key) => {
+        if (cb) {
+            cb(record[key]);
+        }
+        delete record[key];
+    });
+}
+/** @internal Creates a default/empty stats object */
+function defaultEndpointStats() {
+    return { bytesRecv: 0, bytesSent: 0, cached: 0, errors: 0, requests: 0, subscriptions: 0, timeout: 0 };
+}
+/**
+ * # @pezkuwi/rpc-provider/ws
+ *
+ * @name WsProvider
+ *
+ * @description The WebSocket Provider allows sending requests using WebSocket to a WebSocket RPC server TCP port. Unlike the [[HttpProvider]], it does support subscriptions and allows listening to events such as new blocks or balance changes.
+ *
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import Api from '@pezkuwi/api/promise';
+ * import { WsProvider } from '@pezkuwi/rpc-provider/ws';
+ *
+ * const provider = new WsProvider('ws://127.0.0.1:9944');
+ * const api = new Api(provider);
+ * ```
+ *
+ * @see [[HttpProvider]]
+ */
+class WsProvider {
+    #callCache;
+    #coder;
+    #endpoints;
+    #headers;
+    #eventemitter;
+    #handlers = {};
+    #isReadyPromise;
+    #stats;
+    #waitingForId = {};
+    #cacheCapacity;
+    #ttl;
+    #autoConnectMs;
+    #endpointIndex;
+    #endpointStats;
+    #isConnected = false;
+    #subscriptions = {};
+    #timeoutId = null;
+    #websocket;
+    #timeout;
+    /**
+     * @param {string | string[]} endpoint The endpoint url. Usually `ws://ip:9944` or `wss://ip:9944`, may provide an array of endpoint strings.
+     * @param {number | false} autoConnectMs Whether to connect automatically or not (default). Provided value is used as a delay between retries.
+     * @param {Record<string, string>} headers The headers provided to the underlying WebSocket
+     * @param {number} [timeout] Custom timeout value used per request . Defaults to `DEFAULT_TIMEOUT_MS`
+     * @param {number} [cacheCapacity] Custom size of the WsProvider LRUCache. Defaults to `DEFAULT_CAPACITY` (1024)
+     * @param {number} [cacheTtl] Custom TTL of the WsProvider LRUCache. Determines how long an object can live in the cache. Defaults to DEFAULT_TTL` (30000)
+     */
+    constructor(endpoint = defaults_js_1.default.WS_URL, autoConnectMs = RETRY_DELAY, headers = {}, timeout, cacheCapacity, cacheTtl) {
+        const endpoints = Array.isArray(endpoint)
+            ? endpoint
+            : [endpoint];
+        if (endpoints.length === 0) {
+            throw new Error('WsProvider requires at least one Endpoint');
+        }
+        endpoints.forEach((endpoint) => {
+            if (!/^(wss|ws):\/\//.test(endpoint)) {
+                throw new Error(`Endpoint should start with 'ws://', received '${endpoint}'`);
+            }
+        });
+        const ttl = cacheTtl === undefined ? lru_js_1.DEFAULT_TTL : cacheTtl;
+        this.#callCache = new lru_js_1.LRUCache(cacheCapacity === 0 ? 0 : cacheCapacity || lru_js_1.DEFAULT_CAPACITY, ttl);
+        this.#ttl = cacheTtl;
+        this.#cacheCapacity = cacheCapacity || lru_js_1.DEFAULT_CAPACITY;
+        this.#eventemitter = new eventemitter3_1.EventEmitter();
+        this.#autoConnectMs = autoConnectMs || 0;
+        this.#coder = new index_js_1.RpcCoder();
+        this.#endpointIndex = -1;
+        this.#endpoints = endpoints;
+        this.#headers = headers;
+        this.#websocket = null;
+        this.#stats = {
+            active: { requests: 0, subscriptions: 0 },
+            total: defaultEndpointStats()
+        };
+        this.#endpointStats = defaultEndpointStats();
+        this.#timeout = timeout || DEFAULT_TIMEOUT_MS;
+        if (autoConnectMs && autoConnectMs > 0) {
+            this.connectWithRetry().catch(util_1.noop);
+        }
+        this.#isReadyPromise = new Promise((resolve) => {
+            this.#eventemitter.once('connected', () => {
+                resolve(this);
+            });
+        });
+    }
+    /**
+     * @summary `true` when this provider supports subscriptions
+     */
+    get hasSubscriptions() {
+        return !!true;
+    }
+    /**
+     * @summary `true` when this provider supports clone()
+     */
+    get isClonable() {
+        return !!true;
+    }
+    /**
+     * @summary Whether the node is connected or not.
+     * @return {boolean} true if connected
+     */
+    get isConnected() {
+        return this.#isConnected;
+    }
+    /**
+     * @description Promise that resolves the first time we are connected and loaded
+     */
+    get isReady() {
+        return this.#isReadyPromise;
+    }
+    get endpoint() {
+        return this.#endpoints[this.#endpointIndex];
+    }
+    /**
+     * @description Returns a clone of the object
+     */
+    clone() {
+        return new WsProvider(this.#endpoints);
+    }
+    selectEndpointIndex(endpoints) {
+        return (this.#endpointIndex + 1) % endpoints.length;
+    }
+    /**
+     * @summary Manually connect
+     * @description The [[WsProvider]] connects automatically by default, however if you decided otherwise, you may
+     * connect manually using this method.
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async connect() {
+        if (this.#websocket) {
+            throw new Error('WebSocket is already connected');
+        }
+        try {
+            this.#endpointIndex = this.selectEndpointIndex(this.#endpoints);
+            // the as here is Deno-specific - not available on the globalThis
+            this.#websocket = typeof x_global_1.xglobal.WebSocket !== 'undefined' && (0, util_1.isChildClass)(x_global_1.xglobal.WebSocket, x_ws_1.WebSocket)
+                ? new x_ws_1.WebSocket(this.endpoint)
+                // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+                // @ts-ignore - WS may be an instance of ws, which supports options
+                : new x_ws_1.WebSocket(this.endpoint, undefined, {
+                    headers: this.#headers
+                });
+            if (this.#websocket) {
+                this.#websocket.onclose = this.#onSocketClose;
+                this.#websocket.onerror = this.#onSocketError;
+                this.#websocket.onmessage = this.#onSocketMessage;
+                this.#websocket.onopen = this.#onSocketOpen;
+            }
+            // timeout any handlers that have not had a response
+            this.#timeoutId = setInterval(() => this.#timeoutHandlers(), TIMEOUT_INTERVAL);
+        }
+        catch (error) {
+            l.error(error);
+            this.#emit('error', error);
+            throw error;
+        }
+    }
+    /**
+     * @description Connect, never throwing an error, but rather forcing a retry
+     */
+    async connectWithRetry() {
+        if (this.#autoConnectMs > 0) {
+            try {
+                await this.connect();
+            }
+            catch {
+                setTimeout(() => {
+                    this.connectWithRetry().catch(util_1.noop);
+                }, this.#autoConnectMs);
+            }
+        }
+    }
+    /**
+     * @description Manually disconnect from the connection, clearing auto-connect logic
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async disconnect() {
+        // switch off autoConnect, we are in manual mode now
+        this.#autoConnectMs = 0;
+        try {
+            if (this.#websocket) {
+                // 1000 - Normal closure; the connection successfully completed
+                this.#websocket.close(1000);
+            }
+        }
+        catch (error) {
+            l.error(error);
+            this.#emit('error', error);
+            throw error;
+        }
+    }
+    /**
+     * @description Returns the connection stats
+     */
+    get stats() {
+        return {
+            active: {
+                requests: Object.keys(this.#handlers).length,
+                subscriptions: Object.keys(this.#subscriptions).length
+            },
+            total: this.#stats.total
+        };
+    }
+    /**
+    * @description Returns the connection stats
+    */
+    get ttl() {
+        return this.#ttl;
+    }
+    get endpointStats() {
+        return this.#endpointStats;
+    }
+    /**
+     * @summary Listens on events after having subscribed using the [[subscribe]] function.
+     * @param  {ProviderInterfaceEmitted} type Event
+     * @param  {ProviderInterfaceEmitCb}  sub  Callback
+     * @return unsubscribe function
+     */
+    on(type, sub) {
+        this.#eventemitter.on(type, sub);
+        return () => {
+            this.#eventemitter.removeListener(type, sub);
+        };
+    }
+    /**
+     * @summary Send JSON data using WebSockets to configured HTTP Endpoint or queue.
+     * @param method The RPC methods to execute
+     * @param params Encoded parameters as applicable for the method
+     * @param subscription Subscription details (internally used)
+     */
+    send(method, params, isCacheable, subscription) {
+        this.#endpointStats.requests++;
+        this.#stats.total.requests++;
+        const [id, body] = this.#coder.encodeJson(method, params);
+        if (this.#cacheCapacity === 0) {
+            return this.#send(id, body, method, params, subscription);
+        }
+        const cacheKey = isCacheable ? `${method}::${(0, util_1.stringify)(params)}` : '';
+        let resultPromise = isCacheable
+            ? this.#callCache.get(cacheKey)
+            : null;
+        if (!resultPromise) {
+            resultPromise = this.#send(id, body, method, params, subscription);
+            if (isCacheable) {
+                this.#callCache.set(cacheKey, resultPromise);
+            }
+        }
+        else {
+            this.#endpointStats.cached++;
+            this.#stats.total.cached++;
+        }
+        return resultPromise;
+    }
+    async #send(id, body, method, params, subscription) {
+        return new Promise((resolve, reject) => {
+            try {
+                if (!this.isConnected || this.#websocket === null) {
+                    throw new Error('WebSocket is not connected');
+                }
+                const callback = (error, result) => {
+                    error
+                        ? reject(error)
+                        : resolve(result);
+                };
+                l.debug(() => ['calling', method, body]);
+                this.#handlers[id] = {
+                    callback,
+                    method,
+                    params,
+                    start: Date.now(),
+                    subscription
+                };
+                const bytesSent = body.length;
+                this.#endpointStats.bytesSent += bytesSent;
+                this.#stats.total.bytesSent += bytesSent;
+                this.#websocket.send(body);
+            }
+            catch (error) {
+                this.#endpointStats.errors++;
+                this.#stats.total.errors++;
+                const rpcError = error;
+                const failedRequest = `\nFailed WS Request: ${JSON.stringify({ method, params })}`;
+                // Provide WS Request alongside the error
+                rpcError.message = `${rpcError.message}${failedRequest}`;
+                reject(rpcError);
+            }
+        });
+    }
+    /**
+     * @name subscribe
+     * @summary Allows subscribing to a specific event.
+     *
+     * @example
+     * <BR>
+     *
+     * ```javascript
+     * const provider = new WsProvider('ws://127.0.0.1:9944');
+     * const rpc = new Rpc(provider);
+     *
+     * rpc.state.subscribeStorage([[storage.system.account, <Address>]], (_, values) => {
+     *   console.log(values)
+     * }).then((subscriptionId) => {
+     *   console.log('balance changes subscription id: ', subscriptionId)
+     * })
+     * ```
+     */
+    subscribe(type, method, params, callback) {
+        this.#endpointStats.subscriptions++;
+        this.#stats.total.subscriptions++;
+        // subscriptions are not cached, LRU applies to .at(<blockHash>) only
+        return this.send(method, params, false, { callback, type });
+    }
+    /**
+     * @summary Allows unsubscribing to subscriptions made with [[subscribe]].
+     */
+    async unsubscribe(type, method, id) {
+        const subscription = `${type}::${id}`;
+        // FIXME This now could happen with re-subscriptions. The issue is that with a re-sub
+        // the assigned id now does not match what the API user originally received. It has
+        // a slight complication in solving - since we cannot rely on the send id, but rather
+        // need to find the actual subscription id to map it
+        if ((0, util_1.isUndefined)(this.#subscriptions[subscription])) {
+            l.debug(() => `Unable to find active subscription=${subscription}`);
+            return false;
+        }
+        delete this.#subscriptions[subscription];
+        try {
+            return this.isConnected && !(0, util_1.isNull)(this.#websocket)
+                ? this.send(method, [id])
+                : true;
+        }
+        catch {
+            return false;
+        }
+    }
+    #emit = (type, ...args) => {
+        this.#eventemitter.emit(type, ...args);
+    };
+    #onSocketClose = (event) => {
+        const error = new Error(`disconnected from ${this.endpoint}: ${event.code}:: ${event.reason || (0, errors_js_1.getWSErrorString)(event.code)}`);
+        if (this.#autoConnectMs > 0) {
+            l.error(error.message);
+        }
+        this.#isConnected = false;
+        if (this.#websocket) {
+            this.#websocket.onclose = null;
+            this.#websocket.onerror = null;
+            this.#websocket.onmessage = null;
+            this.#websocket.onopen = null;
+            this.#websocket = null;
+        }
+        if (this.#timeoutId) {
+            clearInterval(this.#timeoutId);
+            this.#timeoutId = null;
+        }
+        // reject all hanging requests
+        eraseRecord(this.#handlers, (h) => {
+            try {
+                h.callback(error, undefined);
+            }
+            catch (err) {
+                // does not throw
+                l.error(err);
+            }
+        });
+        eraseRecord(this.#waitingForId);
+        // Reset stats for active endpoint
+        this.#endpointStats = defaultEndpointStats();
+        this.#emit('disconnected');
+        if (this.#autoConnectMs > 0) {
+            setTimeout(() => {
+                this.connectWithRetry().catch(util_1.noop);
+            }, this.#autoConnectMs);
+        }
+    };
+    #onSocketError = (error) => {
+        l.debug(() => ['socket error', error]);
+        this.#emit('error', error);
+    };
+    #onSocketMessage = (message) => {
+        l.debug(() => ['received', message.data]);
+        const bytesRecv = message.data.length;
+        this.#endpointStats.bytesRecv += bytesRecv;
+        this.#stats.total.bytesRecv += bytesRecv;
+        const response = JSON.parse(message.data);
+        return (0, util_1.isUndefined)(response.method)
+            ? this.#onSocketMessageResult(response)
+            : this.#onSocketMessageSubscribe(response);
+    };
+    #onSocketMessageResult = (response) => {
+        const handler = this.#handlers[response.id];
+        if (!handler) {
+            l.debug(() => `Unable to find handler for id=${response.id}`);
+            return;
+        }
+        try {
+            const { method, params, subscription } = handler;
+            const result = this.#coder.decodeResponse(response);
+            // first send the result - in case of subs, we may have an update
+            // immediately if we have some queued results already
+            handler.callback(null, result);
+            if (subscription) {
+                const subId = `${subscription.type}::${result}`;
+                this.#subscriptions[subId] = (0, util_1.objectSpread)({}, subscription, {
+                    method,
+                    params
+                });
+                // if we have a result waiting for this subscription already
+                if (this.#waitingForId[subId]) {
+                    this.#onSocketMessageSubscribe(this.#waitingForId[subId]);
+                }
+            }
+        }
+        catch (error) {
+            this.#endpointStats.errors++;
+            this.#stats.total.errors++;
+            handler.callback(error, undefined);
+        }
+        delete this.#handlers[response.id];
+    };
+    #onSocketMessageSubscribe = (response) => {
+        if (!response.method) {
+            throw new Error('No method found in JSONRPC response');
+        }
+        const method = ALIASES[response.method] || response.method;
+        const subId = `${method}::${response.params.subscription}`;
+        const handler = this.#subscriptions[subId];
+        if (!handler) {
+            // store the JSON, we could have out-of-order subid coming in
+            this.#waitingForId[subId] = response;
+            l.debug(() => `Unable to find handler for subscription=${subId}`);
+            return;
+        }
+        // housekeeping
+        delete this.#waitingForId[subId];
+        try {
+            const result = this.#coder.decodeResponse(response);
+            handler.callback(null, result);
+        }
+        catch (error) {
+            this.#endpointStats.errors++;
+            this.#stats.total.errors++;
+            handler.callback(error, undefined);
+        }
+    };
+    #onSocketOpen = () => {
+        if (this.#websocket === null) {
+            throw new Error('WebSocket cannot be null in onOpen');
+        }
+        l.debug(() => ['connected to', this.endpoint]);
+        this.#isConnected = true;
+        this.#resubscribe();
+        this.#emit('connected');
+        return true;
+    };
+    #resubscribe = () => {
+        const subscriptions = this.#subscriptions;
+        this.#subscriptions = {};
+        Promise.all(Object.keys(subscriptions).map(async (id) => {
+            const { callback, method, params, type } = subscriptions[id];
+            // only re-create subscriptions which are not in author (only area where
+            // transactions are created, i.e. submissions such as 'author_submitAndWatchExtrinsic'
+            // are not included (and will not be re-broadcast)
+            if (type.startsWith('author_')) {
+                return;
+            }
+            try {
+                await this.subscribe(type, method, params, callback);
+            }
+            catch (error) {
+                l.error(error);
+            }
+        })).catch(l.error);
+    };
+    #timeoutHandlers = () => {
+        const now = Date.now();
+        const ids = Object.keys(this.#handlers);
+        for (let i = 0, count = ids.length; i < count; i++) {
+            const handler = this.#handlers[ids[i]];
+            if ((now - handler.start) > this.#timeout) {
+                try {
+                    handler.callback(new Error(`No response received from RPC endpoint in ${this.#timeout / 1000}s`), undefined);
+                }
+                catch {
+                    // ignore
+                }
+                this.#endpointStats.timeout++;
+                this.#stats.total.timeout++;
+                delete this.#handlers[ids[i]];
+            }
+        }
+    };
+}
+exports.WsProvider = WsProvider;

package/coder/error.d.ts

@@ -0,0 +1,29 @@
+import type { RpcErrorInterface } from '../types.js';
+/**
+ * @name RpcError
+ * @summary Extension to the basic JS Error.
+ * @description
+ * The built-in JavaScript Error class is extended by adding a code to allow for Error categorization. In addition to the normal `stack`, `message`, the numeric `code` and `data` (any types) parameters are available on the object.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * const { RpcError } from '@pezkuwi/util');
+ *
+ * throw new RpcError('some message', RpcError.CODES.METHOD_NOT_FOUND); // => error.code = -32601
+ * ```
+ */
+export default class RpcError<T = never> extends Error implements RpcErrorInterface<T> {
+    code: number;
+    data?: T;
+    message: string;
+    name: string;
+    stack: string;
+    constructor(message?: string, code?: number, data?: T);
+    static CODES: {
+        ASSERT: number;
+        INVALID_JSONRPC: number;
+        METHOD_NOT_FOUND: number;
+        UNKNOWN: number;
+    };
+}

package/coder/error.js

@@ -0,0 +1,50 @@
+import { isFunction } from '@pezkuwi/util';
+const UNKNOWN = -99999;
+function extend(that, name, value) {
+    Object.defineProperty(that, name, {
+        configurable: true,
+        enumerable: false,
+        value
+    });
+}
+/**
+ * @name RpcError
+ * @summary Extension to the basic JS Error.
+ * @description
+ * The built-in JavaScript Error class is extended by adding a code to allow for Error categorization. In addition to the normal `stack`, `message`, the numeric `code` and `data` (any types) parameters are available on the object.
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * const { RpcError } from '@pezkuwi/util');
+ *
+ * throw new RpcError('some message', RpcError.CODES.METHOD_NOT_FOUND); // => error.code = -32601
+ * ```
+ */
+export default class RpcError extends Error {
+    code;
+    data;
+    message;
+    name;
+    stack;
+    constructor(message = '', code = UNKNOWN, data) {
+        super();
+        extend(this, 'message', String(message));
+        extend(this, 'name', this.constructor.name);
+        extend(this, 'data', data);
+        extend(this, 'code', code);
+        if (isFunction(Error.captureStackTrace)) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        else {
+            const { stack } = new Error(message);
+            stack && extend(this, 'stack', stack);
+        }
+    }
+    static CODES = {
+        ASSERT: -90009,
+        INVALID_JSONRPC: -99998,
+        METHOD_NOT_FOUND: -32601, // Rust client
+        UNKNOWN
+    };
+}

package/coder/index.d.ts

@@ -0,0 +1,8 @@
+import type { JsonRpcRequest, JsonRpcResponse } from '../types.js';
+/** @internal */
+export declare class RpcCoder {
+    #private;
+    decodeResponse<T>(response?: JsonRpcResponse<T>): T;
+    encodeJson(method: string, params: unknown[]): [number, string];
+    encodeObject(method: string, params: unknown[]): [number, JsonRpcRequest];
+}

package/coder/index.js

@@ -0,0 +1,58 @@
+import { isNumber, isString, isUndefined, stringify } from '@pezkuwi/util';
+import RpcError from './error.js';
+function formatErrorData(data) {
+    if (isUndefined(data)) {
+        return '';
+    }
+    const formatted = `: ${isString(data)
+        ? data.replace(/Error\("/g, '').replace(/\("/g, '(').replace(/"\)/g, ')').replace(/\(/g, ', ').replace(/\)/g, '')
+        : stringify(data)}`;
+    // We need some sort of cut-off here since these can be very large and
+    // very nested, pick a number and trim the result display to it
+    return formatted.length <= 256
+        ? formatted
+        : `${formatted.substring(0, 255)}…`;
+}
+function checkError(error) {
+    if (error) {
+        const { code, data, message } = error;
+        throw new RpcError(`${code}: ${message}${formatErrorData(data)}`, code, data);
+    }
+}
+/** @internal */
+export class RpcCoder {
+    #id = 0;
+    decodeResponse(response) {
+        if (!response || response.jsonrpc !== '2.0') {
+            throw new Error('Invalid jsonrpc field in decoded object');
+        }
+        const isSubscription = !isUndefined(response.params) && !isUndefined(response.method);
+        if (!isNumber(response.id) &&
+            (!isSubscription || (!isNumber(response.params.subscription) &&
+                !isString(response.params.subscription)))) {
+            throw new Error('Invalid id field in decoded object');
+        }
+        checkError(response.error);
+        if (response.result === undefined && !isSubscription) {
+            throw new Error('No result found in jsonrpc response');
+        }
+        if (isSubscription) {
+            checkError(response.params.error);
+            return response.params.result;
+        }
+        return response.result;
+    }
+    encodeJson(method, params) {
+        const [id, data] = this.encodeObject(method, params);
+        return [id, stringify(data)];
+    }
+    encodeObject(method, params) {
+        const id = ++this.#id;
+        return [id, {
+                id,
+                jsonrpc: '2.0',
+                method,
+                params
+            }];
+    }
+}

package/defaults.d.ts

@@ -0,0 +1,5 @@
+declare const _default: {
+    HTTP_URL: string;
+    WS_URL: string;
+};
+export default _default;