@pezkuwi/rpc-provider 16.5.5 → 16.5.8

package/build/ws/index.js

@@ -0,0 +1,524 @@
+import { EventEmitter } from 'eventemitter3';
+import { isChildClass, isNull, isUndefined, logger, noop, objectSpread, stringify } from '@pezkuwi/util';
+import { xglobal } from '@pezkuwi/x-global';
+import { WebSocket } from '@pezkuwi/x-ws';
+import { RpcCoder } from '../coder/index.js';
+import defaults from '../defaults.js';
+import { DEFAULT_CAPACITY, DEFAULT_TTL, LRUCache } from '../lru.js';
+import { getWSErrorString } from './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 = 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]]
+ */
+export 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.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 ? DEFAULT_TTL : cacheTtl;
+        this.#callCache = new LRUCache(cacheCapacity === 0 ? 0 : cacheCapacity || DEFAULT_CAPACITY, ttl);
+        this.#ttl = cacheTtl;
+        this.#cacheCapacity = cacheCapacity || DEFAULT_CAPACITY;
+        this.#eventemitter = new EventEmitter();
+        this.#autoConnectMs = autoConnectMs || 0;
+        this.#coder = new 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(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 xglobal.WebSocket !== 'undefined' && isChildClass(xglobal.WebSocket, WebSocket)
+                ? new 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 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(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}::${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 (isUndefined(this.#subscriptions[subscription])) {
+            l.debug(() => `Unable to find active subscription=${subscription}`);
+            return false;
+        }
+        delete this.#subscriptions[subscription];
+        try {
+            return this.isConnected && !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 || 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(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 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] = 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]];
+            }
+        }
+    };
+}

package/build-deno/README.md

@@ -0,0 +1,66 @@
+# @pezkuwi/rpc-provider
+
+Generic transport providers to handle the transport of method calls to and from Pezkuwi clients from applications interacting with it. It provides an interface to making RPC calls and is generally, unless you are operating at a low-level and taking care of encoding and decoding of parameters/results, it won't be directly used, rather only passed to a higher-level interface.
+
+## Provider Selection
+
+There are three flavours of the providers provided, one allowing for using HTTP as a transport mechanism, the other using WebSockets, and the third one uses bizinikiwi light-client through @bizinikiwi/connect. It is generally recommended to use the [[WsProvider]] since in addition to standard calls, it allows for subscriptions where all changes to state can be pushed from the node to the client.
+
+All providers are usable (as is the API), in both browser-based and Node.js environments. Polyfills for unsupported functionality are automatically applied based on feature-detection.
+
+## Usage
+
+Installation -
+
+```
+yarn add @pezkuwi/rpc-provider
+```
+
+WebSocket Initialization -
+
+```javascript
+import { WsProvider } from 'https://deno.land/x/pezkuwi/rpc-provider/mod.ts';
+
+const provider = new WsProvider('ws://127.0.0.1:9944');
+const version = await provider.send('client_version', []);
+
+console.log('client version', version);
+```
+
+HTTP Initialization -
+
+```javascript
+import { HttpProvider } from 'https://deno.land/x/pezkuwi/rpc-provider/mod.ts';
+
+const provider = new HttpProvider('http://127.0.0.1:9933');
+const version = await provider.send('chain_getBlockHash', []);
+
+console.log('latest block Hash', hash);
+```
+
+@bizinikiwi/connect Initialization -
+
+Instantiating a Provider for the Pezkuwi Relay Chain:
+```javascript
+import { ScProvider } from 'https://deno.land/x/pezkuwi/rpc-provider/mod.ts';
+import * as Sc from 'https://esm.sh/@bizinikiwi/connect@2.1.9';
+
+const provider = new ScProvider(Sc, Sc.WellKnownChain.pezkuwi);
+
+await provider.connect();
+
+const version = await provider.send('chain_getBlockHash', []);
+```
+
+Instantiating a Provider for a Pezkuwi teyrchain:
+```javascript
+import { ScProvider } from 'https://deno.land/x/pezkuwi/rpc-provider/mod.ts';
+import * as Sc from 'https://esm.sh/@bizinikiwi/connect@2.1.9';
+
+const pezkuwiProvider = new ScProvider(Sc, Sc.WellKnownChain.pezkuwi);
+const teyrchainProvider = new ScProvider(Sc, teyrchainSpec, pezkuwiProvider);
+
+await teyrchainProvider.connect();
+
+const version = await teyrchainProvider.send('chain_getBlockHash', []);
+```