@pezkuwi/rpc-provider 16.5.16 → 16.5.18

package/src/coder/error.ts

@@ -0,0 +1,66 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { RpcErrorInterface } from '../types.js';
+
+import { isFunction } from '@pezkuwi/util';
+
+const UNKNOWN = -99999;
+
+function extend<Data, K extends keyof RpcError<Data>> (that: RpcError<Data>, name: K, value: RpcError<Data>[K]): void {
+  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<T = never> extends Error implements RpcErrorInterface<T> {
+  public code!: number;
+
+  public data?: T;
+
+  public override message!: string;
+
+  public override name!: string;
+
+  public override stack!: string;
+
+  public constructor (message = '', code: number = UNKNOWN, data?: T) {
+    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);
+    }
+  }
+
+  public static CODES = {
+    ASSERT: -90009,
+    INVALID_JSONRPC: -99998,
+    METHOD_NOT_FOUND: -32601, // Rust client
+    UNKNOWN
+  };
+}

package/src/coder/index.ts

@@ -0,0 +1,88 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { JsonRpcRequest, JsonRpcResponse, JsonRpcResponseBaseError } from '../types.js';
+
+import { isNumber, isString, isUndefined, stringify } from '@pezkuwi/util';
+
+import RpcError from './error.js';
+
+function formatErrorData (data?: string | number): string {
+  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?: JsonRpcResponseBaseError): void {
+  if (error) {
+    const { code, data, message } = error;
+
+    throw new RpcError(`${code}: ${message}${formatErrorData(data)}`, code, data);
+  }
+}
+
+/** @internal */
+export class RpcCoder {
+  #id = 0;
+
+  public decodeResponse <T> (response?: JsonRpcResponse<T>): T {
+    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;
+  }
+
+  public encodeJson (method: string, params: unknown[]): [number, string] {
+    const [id, data] = this.encodeObject(method, params);
+
+    return [id, stringify(data)];
+  }
+
+  public encodeObject (method: string, params: unknown[]): [number, JsonRpcRequest] {
+    const id = ++this.#id;
+
+    return [id, {
+      id,
+      jsonrpc: '2.0',
+      method,
+      params
+    }];
+  }
+}

package/src/defaults.ts

@@ -0,0 +1,10 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+const HTTP_URL = 'http://127.0.0.1:9933';
+const WS_URL = 'ws://127.0.0.1:9944';
+
+export default {
+  HTTP_URL,
+  WS_URL
+};

package/src/http/index.spec.ts

@@ -0,0 +1,72 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { TEST_HTTP_URL } from '../mock/mockHttp.js';
+import { HttpProvider } from './index.js';
+
+describe('Http', (): void => {
+  let http: HttpProvider;
+
+  beforeEach((): void => {
+    http = new HttpProvider(TEST_HTTP_URL);
+  });
+
+  it('requires an http:// prefixed endpoint', (): void => {
+    expect(
+      () => new HttpProvider('ws://')
+    ).toThrow(/with 'http/);
+  });
+
+  it('allows https:// endpoints', (): void => {
+    expect(
+      () => new HttpProvider('https://')
+    ).not.toThrow();
+  });
+
+  it('allows custom headers', (): void => {
+    expect(
+      () => new HttpProvider('https://', { foo: 'bar' })
+    ).not.toThrow();
+  });
+
+  it('should throw error on negative cache capacity or TTL', () => {
+    expect(() =>
+      new HttpProvider(TEST_HTTP_URL, {}, -5, 30000)
+    ).toThrow(/'capacity' must be a non-negative integer/);
+
+    expect(() =>
+      new HttpProvider(TEST_HTTP_URL, {}, 1024, -1000)
+    ).toThrow(/'ttl' must be between 0 and 1800000 ms or null to disable/);
+  });
+
+  it('allow clone', (): void => {
+    const clone = http.clone();
+    /* eslint-disable */
+    expect((clone as any)['#endpoint']).toEqual((http as any)['#endpoint']);
+    expect((clone as any)['#headers']).toEqual((http as any)['#headers']);
+    /* eslint-enable */
+  });
+
+  it('always returns isConnected true', (): void => {
+    expect(http.isConnected).toEqual(true);
+  });
+
+  it('does not (yet) support subscribe', async (): Promise<void> => {
+    await http.subscribe('', '', [], (cb): void => {
+      // eslint-disable-next-line jest/no-conditional-expect
+      expect(cb).toEqual(expect.anything());
+    }).catch((error): void => {
+      // eslint-disable-next-line jest/no-conditional-expect
+      expect((error as Error).message).toMatch(/does not have subscriptions/);
+    });
+  });
+
+  it('does not (yet) support unsubscribe', async (): Promise<void> => {
+    await http.unsubscribe('', '', 0).catch((error): void => {
+      // eslint-disable-next-line jest/no-conditional-expect
+      expect((error as Error).message).toMatch(/does not have subscriptions/);
+    });
+  });
+});

package/src/http/index.ts

@@ -0,0 +1,238 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type RpcError from '../coder/error.js';
+import type { JsonRpcResponse, ProviderInterface, ProviderInterfaceCallback, ProviderInterfaceEmitCb, ProviderInterfaceEmitted, ProviderStats } from '../types.js';
+
+import { logger, noop, stringify } from '@pezkuwi/util';
+import { fetch } from '@pezkuwi/x-fetch';
+
+import { RpcCoder } from '../coder/index.js';
+import defaults from '../defaults.js';
+import { DEFAULT_CAPACITY, DEFAULT_TTL, LRUCache } from '../lru.js';
+
+const ERROR_SUBSCRIBE = 'HTTP Provider does not have subscriptions, use WebSockets instead';
+
+const l = logger('api-http');
+
+/**
+ * # @pezkuwi/rpc-provider
+ *
+ * @name HttpProvider
+ *
+ * @description The HTTP Provider allows sending requests using HTTP to a HTTP RPC server TCP port. It does not support subscriptions so you won't be able to listen to events such as new blocks or balance changes. It is usually preferable using the [[WsProvider]].
+ *
+ * @example
+ * <BR>
+ *
+ * ```javascript
+ * import Api from '@pezkuwi/api/promise';
+ * import { HttpProvider } from '@pezkuwi/rpc-provider';
+ *
+ * const provider = new HttpProvider('http://127.0.0.1:9933');
+ * const api = new Api(provider);
+ * ```
+ *
+ * @see [[WsProvider]]
+ */
+export class HttpProvider implements ProviderInterface {
+  readonly #callCache: LRUCache;
+  readonly #cacheCapacity: number;
+  readonly #coder: RpcCoder;
+  readonly #endpoint: string;
+  readonly #headers: Record<string, string>;
+  readonly #stats: ProviderStats;
+  readonly #ttl: number | null | undefined;
+
+  /**
+   * @param {string} endpoint The endpoint url starting with http://
+   * @param {Record<string, string>} headers The headers provided to the underlying Http Endpoint
+   * @param {number} [cacheCapacity] Custom size of the HttpProvider LRUCache. Defaults to `DEFAULT_CAPACITY` (1024)
+   * @param {number} [cacheTtl] Custom TTL of the HttpProvider LRUCache. Determines how long an object can live in the cache. Defaults to `DEFAULT_TTL` (30000)
+   */
+  constructor (endpoint: string = defaults.HTTP_URL, headers: Record<string, string> = {}, cacheCapacity?: number, cacheTtl?: number | null) {
+    if (!/^(https|http):\/\//.test(endpoint)) {
+      throw new Error(`Endpoint should start with 'http://' or 'https://', received '${endpoint}'`);
+    }
+
+    this.#coder = new RpcCoder();
+    this.#endpoint = endpoint;
+    this.#headers = headers;
+    this.#cacheCapacity = cacheCapacity === 0 ? 0 : cacheCapacity || DEFAULT_CAPACITY;
+
+    const ttl = cacheTtl === undefined ? DEFAULT_TTL : cacheTtl;
+
+    this.#callCache = new LRUCache(cacheCapacity === 0 ? 0 : cacheCapacity || DEFAULT_CAPACITY, ttl);
+    this.#ttl = cacheTtl;
+
+    this.#stats = {
+      active: { requests: 0, subscriptions: 0 },
+      total: { bytesRecv: 0, bytesSent: 0, cached: 0, errors: 0, requests: 0, subscriptions: 0, timeout: 0 }
+    };
+  }
+
+  /**
+   * @summary `true` when this provider supports subscriptions
+   */
+  public get hasSubscriptions (): boolean {
+    return !!false;
+  }
+
+  /**
+   * @description Returns a clone of the object
+   */
+  public clone (): HttpProvider {
+    return new HttpProvider(this.#endpoint, this.#headers);
+  }
+
+  /**
+   * @description Manually connect from the connection
+   */
+  public async connect (): Promise<void> {
+    // noop
+  }
+
+  /**
+   * @description Manually disconnect from the connection
+   */
+  public async disconnect (): Promise<void> {
+    // noop
+  }
+
+  /**
+   * @description Returns the connection stats
+   */
+  public get stats (): ProviderStats {
+    return this.#stats;
+  }
+
+  /**
+  * @description Returns the connection stats
+  */
+  public get ttl (): number | null | undefined {
+    return this.#ttl;
+  }
+
+  /**
+   * @summary `true` when this provider supports clone()
+   */
+  public get isClonable (): boolean {
+    return !!true;
+  }
+
+  /**
+   * @summary Whether the node is connected or not.
+   * @return {boolean} true if connected
+   */
+  public get isConnected (): boolean {
+    return !!true;
+  }
+
+  /**
+   * @summary Events are not supported with the HttpProvider, see [[WsProvider]].
+   * @description HTTP Provider does not have 'on' emitters. WebSockets should be used instead.
+   */
+  public on (_type: ProviderInterfaceEmitted, _sub: ProviderInterfaceEmitCb): () => void {
+    l.error('HTTP Provider does not have \'on\' emitters, use WebSockets instead');
+
+    return noop;
+  }
+
+  /**
+   * @summary Send HTTP POST Request with Body to configured HTTP Endpoint.
+   */
+  public async send <T> (method: string, params: unknown[], isCacheable?: boolean): Promise<T> {
+    this.#stats.total.requests++;
+
+    const [, body] = this.#coder.encodeJson(method, params);
+
+    if (this.#cacheCapacity === 0) {
+      return this.#send(body);
+    }
+
+    const cacheKey = isCacheable ? `${method}::${stringify(params)}` : '';
+    let resultPromise: Promise<T> | null = isCacheable
+      ? this.#callCache.get(cacheKey)
+      : null;
+
+    if (!resultPromise) {
+      resultPromise = this.#send(body);
+
+      if (isCacheable) {
+        this.#callCache.set(cacheKey, resultPromise);
+      }
+    } else {
+      this.#stats.total.cached++;
+    }
+
+    return resultPromise;
+  }
+
+  async #send <T> (body: string): Promise<T> {
+    this.#stats.active.requests++;
+    this.#stats.total.bytesSent += body.length;
+
+    try {
+      const response = await fetch(this.#endpoint, {
+        body,
+        headers: {
+          Accept: 'application/json',
+          'Content-Length': `${body.length}`,
+          'Content-Type': 'application/json',
+          ...this.#headers
+        },
+        method: 'POST'
+      });
+
+      if (!response.ok) {
+        throw new Error(`[${response.status}]: ${response.statusText}`);
+      }
+
+      const result = await response.text();
+
+      this.#stats.total.bytesRecv += result.length;
+
+      const decoded = this.#coder.decodeResponse(JSON.parse(result) as JsonRpcResponse<T>);
+
+      this.#stats.active.requests--;
+
+      return decoded;
+    } catch (e) {
+      this.#stats.active.requests--;
+      this.#stats.total.errors++;
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const { method, params } = JSON.parse(body);
+
+      const rpcError: RpcError = e as RpcError;
+
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+      const failedRequest = `\nFailed HTTP Request: ${JSON.stringify({ method, params })}`;
+
+      // Provide HTTP Request alongside the error
+      rpcError.message = `${rpcError.message}${failedRequest}`;
+
+      throw rpcError;
+    }
+  }
+
+  /**
+   * @summary Subscriptions are not supported with the HttpProvider, see [[WsProvider]].
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  public async subscribe (_types: string, _method: string, _params: unknown[], _cb: ProviderInterfaceCallback): Promise<number> {
+    l.error(ERROR_SUBSCRIBE);
+
+    throw new Error(ERROR_SUBSCRIBE);
+  }
+
+  /**
+   * @summary Subscriptions are not supported with the HttpProvider, see [[WsProvider]].
+   */
+  // eslint-disable-next-line @typescript-eslint/require-await
+  public async unsubscribe (_type: string, _method: string, _id: number): Promise<boolean> {
+    l.error(ERROR_SUBSCRIBE);
+
+    throw new Error(ERROR_SUBSCRIBE);
+  }
+}

package/src/http/send.spec.ts

@@ -0,0 +1,61 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import type { Mock } from '../mock/types.js';
+
+import { mockHttp, TEST_HTTP_URL } from '../mock/mockHttp.js';
+import { HttpProvider } from './index.js';
+
+// Does not work with Node 18 (native fetch)
+// See https://github.com/nock/nock/issues/2397
+// eslint-disable-next-line jest/no-disabled-tests
+describe.skip('send', (): void => {
+  let http: HttpProvider;
+  let mock: Mock;
+
+  beforeEach((): void => {
+    http = new HttpProvider(TEST_HTTP_URL);
+  });
+
+  afterEach(async () => {
+    if (mock) {
+      await mock.done();
+    }
+  });
+
+  it('passes the body through correctly', (): Promise<void> => {
+    mock = mockHttp([{
+      method: 'test_body',
+      reply: {
+        result: 'ok'
+      }
+    }]);
+
+    return http
+      .send('test_body', ['param'])
+      .then((): void => {
+        expect(mock.body['test_body']).toEqual({
+          id: 1,
+          jsonrpc: '2.0',
+          method: 'test_body',
+          params: ['param']
+        });
+      });
+  });
+
+  it('throws error when !response.ok', async (): Promise<any> => {
+    mock = mockHttp([{
+      code: 500,
+      method: 'test_error'
+    }]);
+
+    return http
+      .send('test_error', [])
+      .catch((error): void => {
+        // eslint-disable-next-line jest/no-conditional-expect
+        expect((error as Error).message).toMatch(/\[500\]/);
+      });
+  });
+});

package/src/http/types.ts

@@ -0,0 +1,11 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Logger } from '@pezkuwi/util/types';
+import type { RpcCoder } from '../coder/index.js';
+
+export interface HttpState {
+  coder: RpcCoder;
+  endpoint: string;
+  l: Logger;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+import './packageDetect.js';
+
+export * from './bundle.js';

package/src/lru.spec.ts

@@ -0,0 +1,74 @@
+// Copyright 2017-2025 @pezkuwi/rpc-provider authors & contributors
+// SPDX-License-Identifier: Apache-2.0
+
+/// <reference types="@pezkuwi/dev-test/globals.d.ts" />
+
+import { LRUCache } from './lru.js';
+
+describe('LRUCache', (): void => {
+  let lru: LRUCache | undefined;
+
+  beforeEach((): void => {
+    lru = new LRUCache(4, 500);
+  });
+
+  it('allows getting of items below capacity', (): void => {
+    const keys = ['1', '2', '3', '4'];
+
+    keys.forEach((k) => lru?.set(k, `${k}${k}${k}`));
+    const lruKeys = lru?.keys();
+
+    expect(lruKeys?.join(', ')).toBe(keys.reverse().join(', '));
+    expect(lru?.length === lru?.lengthData && lru?.length === lru?.lengthRefs).toBe(true);
+
+    keys.forEach((k) => expect(lru?.get(k)).toEqual(`${k}${k}${k}`));
+  });
+
+  it('drops items when at capacity', (): void => {
+    const keys = ['1', '2', '3', '4', '5', '6'];
+
+    keys.forEach((k) => lru?.set(k, `${k}${k}${k}`));
+
+    expect(lru?.keys().join(', ')).toEqual(keys.slice(2).reverse().join(', '));
+    expect(lru?.length === lru?.lengthData && lru?.length === lru?.lengthRefs).toBe(true);
+
+    keys.slice(2).forEach((k) => expect(lru?.get(k)).toEqual(`${k}${k}${k}`));
+  });
+
+  it('adjusts the order as they are used', (): void => {
+    const keys = ['1', '2', '3', '4', '5'];
+
+    keys.forEach((k) => lru?.set(k, `${k}${k}${k}`));
+
+    expect(lru?.entries()).toEqual([['5', '555'], ['4', '444'], ['3', '333'], ['2', '222']]);
+    expect(lru?.length === lru?.lengthData && lru?.length === lru?.lengthRefs).toBe(true);
+
+    lru?.get('3');
+
+    expect(lru?.entries()).toEqual([['3', '333'], ['5', '555'], ['4', '444'], ['2', '222']]);
+    expect(lru?.length === lru?.lengthData && lru?.length === lru?.lengthRefs).toBe(true);
+
+    lru?.set('4', '4433');
+
+    expect(lru?.entries()).toEqual([['4', '4433'], ['3', '333'], ['5', '555'], ['2', '222']]);
+    expect(lru?.length === lru?.lengthData && lru?.length === lru?.lengthRefs).toBe(true);
+
+    lru?.set('6', '666');
+
+    expect(lru?.entries()).toEqual([['6', '666'], ['4', '4433'], ['3', '333'], ['5', '555']]);
+    expect(lru?.length === lru?.lengthData && lru?.length === lru?.lengthRefs).toBe(true);
+  });
+
+  it('evicts items with TTL', (): void => {
+    const keys = ['1', '2', '3', '4', '5'];
+
+    keys.forEach((k) => lru?.set(k, `${k}${k}${k}`));
+
+    expect(lru?.entries()).toEqual([['5', '555'], ['4', '444'], ['3', '333'], ['2', '222']]);
+
+    setTimeout((): void => {
+      lru?.get('3');
+      expect(lru?.entries()).toEqual([['3', '333']]);
+    }, 800);
+  });
+});