439 lines
16 KiB
TypeScript
439 lines
16 KiB
TypeScript
// Copyright 2017-2019 @polkadot/rpc-core authors & contributors
|
|
// This software may be modified and distributed under the terms
|
|
// of the Apache-2.0 license. See the LICENSE file for details.
|
|
|
|
import { ProviderInterface } from '@polkadot/rpc-provider/types';
|
|
import { RpcMethod, RpcSection, RpcParam } from '@polkadot/jsonrpc/types';
|
|
import { AnyJson, Codec } from '@polkadot/types/types';
|
|
import { RpcInterface } from './jsonrpc.types';
|
|
import { RpcInterfaceMethod, UserRpc } from './types';
|
|
|
|
import memoizee from 'memoizee';
|
|
import { combineLatest, from, Observable, Observer, of, throwError } from 'rxjs';
|
|
import { catchError, map, publishReplay, refCount, switchMap } from 'rxjs/operators';
|
|
import jsonrpc from '@polkadot/jsonrpc';
|
|
import jsonrpcMethod from '@polkadot/jsonrpc/create/method';
|
|
import jsonrpcParam from '@polkadot/jsonrpc/create/param';
|
|
import { Option, StorageKey, Vec, createClass } from '@polkadot/types';
|
|
import { createTypeUnsafe } from '@polkadot/types/codec';
|
|
import { assert, isFunction, isNull, isNumber, logger, u8aToU8a } from '@polkadot/util';
|
|
|
|
import { drr } from './rxjs';
|
|
|
|
type UserRpcConverted = Record<string, Record<string, RpcMethod>>;
|
|
|
|
const l = logger('rpc-core');
|
|
|
|
const EMPTY_META = {
|
|
fallback: undefined,
|
|
modifier: { isOptional: true },
|
|
type: {
|
|
asMap: { linked: { isTrue: false } },
|
|
isMap: false
|
|
}
|
|
};
|
|
|
|
/**
|
|
* @name Rpc
|
|
* @summary The API may use a HTTP or WebSockets provider.
|
|
* @description It allows for querying a Polkadot Client Node.
|
|
* WebSockets provider is recommended since HTTP provider only supports basic querying.
|
|
*
|
|
* ```mermaid
|
|
* graph LR;
|
|
* A[Api] --> |WebSockets| B[WsProvider];
|
|
* B --> |endpoint| C[ws://127.0.0.1:9944]
|
|
* ```
|
|
*
|
|
* @example
|
|
* <BR>
|
|
*
|
|
* ```javascript
|
|
* import Rpc from '@polkadot/rpc-core';
|
|
* import WsProvider from '@polkadot/rpc-provider/ws';
|
|
*
|
|
* const provider = new WsProvider('ws://127.0.0.1:9944');
|
|
* const rpc = new Rpc(provider);
|
|
* ```
|
|
*/
|
|
export default class Rpc implements RpcInterface {
|
|
private _storageCache = new Map<string, string | null>();
|
|
|
|
public readonly provider: ProviderInterface;
|
|
|
|
public readonly mapping: Map<string, RpcMethod> = new Map();
|
|
|
|
public readonly sections: string[] = [];
|
|
|
|
// Ok, this is quite horrible - we really should not be using the ! here, but we are actually assigning
|
|
// these via the createInterfaces inside the constructor. However... this is not quite visible. The reason
|
|
// why we don't do for individual assignments is to allow user-defined RPCs to also be defined
|
|
|
|
public readonly account!: RpcInterface['account'];
|
|
|
|
public readonly author!: RpcInterface['author'];
|
|
|
|
public readonly chain!: RpcInterface['chain'];
|
|
|
|
public readonly contracts!: RpcInterface['contracts'];
|
|
|
|
public readonly rpc!: RpcInterface['rpc'];
|
|
|
|
public readonly state!: RpcInterface['state'];
|
|
|
|
public readonly system!: RpcInterface['system'];
|
|
|
|
/**
|
|
* @constructor
|
|
* Default constructor for the Api Object
|
|
* @param {ProviderInterface} provider An API provider using HTTP or WebSocket
|
|
*/
|
|
constructor (provider: ProviderInterface, userRpc: UserRpc = {}) {
|
|
// eslint-disable-next-line @typescript-eslint/unbound-method
|
|
assert(provider && isFunction(provider.send), 'Expected Provider to API create');
|
|
|
|
this.provider = provider;
|
|
|
|
this.createInterfaces(jsonrpc, userRpc);
|
|
}
|
|
|
|
/**
|
|
* @name signature
|
|
* @summary Returns a string representation of the method with inputs and outputs.
|
|
* @description
|
|
* Formats the name, inputs and outputs into a human-readable string. This contains the input parameter names input types and output type.
|
|
*
|
|
* @example
|
|
* <BR>
|
|
*
|
|
* ```javascript
|
|
* import Api from '@polkadot/rpc-core';
|
|
*
|
|
* Api.signature({ name: 'test_method', params: [ { name: 'dest', type: 'Address' } ], type: 'Address' }); // => test_method (dest: Address): Address
|
|
* ```
|
|
*/
|
|
public static signature ({ method, params, type }: RpcMethod): string {
|
|
const inputs = params.map(({ name, type }): string => `${name}: ${type}`).join(', ');
|
|
|
|
return `${method} (${inputs}): ${type}`;
|
|
}
|
|
|
|
/**
|
|
* @description Manually disconnect from the attached provider
|
|
*/
|
|
public disconnect (): void {
|
|
this.provider.disconnect();
|
|
}
|
|
|
|
private createErrorMessage (method: RpcMethod, error: Error): string {
|
|
return `${Rpc.signature(method)}:: ${error.message}`;
|
|
}
|
|
|
|
private createInterfaces<Section extends keyof RpcInterface> (interfaces: Record<string, RpcSection>, userBare: UserRpc): void {
|
|
// these are the base keys (i.e. part of jsonrpc)
|
|
this.sections.push(...Object.keys(interfaces));
|
|
|
|
// add any extra user-defined sections
|
|
this.sections.push(...Object.keys(userBare).filter((key): boolean => !this.sections.includes(key)));
|
|
|
|
// convert the user inputs into the same format as used in jsonrpc
|
|
const user = Object.entries(userBare).reduce((user: UserRpcConverted, [sectionName, methods]): UserRpcConverted => {
|
|
user[sectionName] = methods.reduce((section: Record<string, RpcMethod>, def): Record<string, RpcMethod> => {
|
|
const { description = 'User defined', name, params, type } = def;
|
|
|
|
section[name] = jsonrpcMethod(sectionName, name, {
|
|
description,
|
|
params: params.map(({ isOptional, name, type }): RpcParam =>
|
|
jsonrpcParam(name, type as any, { isOptional })),
|
|
type: type as any
|
|
});
|
|
|
|
return section;
|
|
}, {});
|
|
|
|
return user;
|
|
}, {});
|
|
|
|
// decorate the sections with base and user methods
|
|
this.sections.forEach((sectionName): void => {
|
|
(this as any)[sectionName as Section] = {
|
|
...this.createInterface(sectionName, interfaces[sectionName] ? interfaces[sectionName].methods : {}),
|
|
...this.createInterface(sectionName, user[sectionName] || {})
|
|
};
|
|
});
|
|
}
|
|
|
|
private createInterface<Section extends keyof RpcInterface> (section: string, methods: Record<string, RpcMethod>): RpcInterface[Section] {
|
|
return Object
|
|
.keys(methods)
|
|
.reduce((exposed, method): RpcInterface[Section] => {
|
|
const def = methods[method];
|
|
|
|
this.mapping.set(`${section}_${method}`, def);
|
|
|
|
// FIXME Remove any here
|
|
// To do so, remove `RpcInterfaceMethod` from './types.ts', and refactor
|
|
// every method inside this class to take:
|
|
// `<S extends keyof RpcInterface, M extends keyof RpcInterface[S]>`
|
|
// Not doing so, because it makes this class a little bit less readable,
|
|
// and leaving it as-is doesn't harm much
|
|
(exposed as any)[method] = def.isSubscription
|
|
? this.createMethodSubscribe(def)
|
|
: this.createMethodSend(def);
|
|
|
|
return exposed;
|
|
}, {} as unknown as RpcInterface[Section]);
|
|
}
|
|
|
|
private createMethodSend (method: RpcMethod): RpcInterfaceMethod {
|
|
const rpcName = `${method.section}_${method.method}`;
|
|
|
|
const call = (...values: any[]): Observable<any> => {
|
|
// TODO Warn on deprecated methods
|
|
|
|
// Here, logically, it should be `of(this.formatInputs(method, values))`.
|
|
// However, formatInputs can throw, and when it does, the above way
|
|
// doesn't throw in the "Observable loop" (which is internally wrapped in
|
|
// a try/catch block). So we:
|
|
// - first do `of(1)` - won't throw
|
|
// - then do `map(()=>this.formatInputs)` - might throw, but inside Observable.
|
|
return of(1).pipe(
|
|
map((): Codec[] => this.formatInputs(method, values)),
|
|
switchMap((params): Observable<[Codec[], any]> =>
|
|
combineLatest([
|
|
of(params),
|
|
from(this.provider.send(rpcName, params.map((param): AnyJson => param.toJSON())))
|
|
])
|
|
),
|
|
map(([params, result]): any => this.formatOutput(method, params, result)),
|
|
catchError((error): any => {
|
|
const message = this.createErrorMessage(method, error);
|
|
|
|
// don't scare with old nodes, this is handled transparently
|
|
rpcName !== 'rpc_methods' && l.error(message);
|
|
|
|
return throwError(new Error(message));
|
|
}),
|
|
publishReplay(1), // create a Replay(1)
|
|
refCount() // Unsubscribe WS when there are no more subscribers
|
|
);
|
|
};
|
|
|
|
// We voluntarily don't cache the "one-shot" RPC calls. For example,
|
|
// `getStorage('123')` returns the current value, but this value can change
|
|
// over time, so we wouldn't want to cache the Observable.
|
|
return call as RpcInterfaceMethod;
|
|
}
|
|
|
|
// create a subscriptor, it subscribes once and resolves with the id as subscribe
|
|
private createSubscriber ({ subType, subName, paramsJson, update }: { subType: string; subName: string; paramsJson: AnyJson[]; update: (error?: Error, result?: any) => void }, errorHandler: (error: Error) => void): Promise<number> {
|
|
return new Promise((resolve, reject): void => {
|
|
this.provider
|
|
.subscribe(subType, subName, paramsJson, update)
|
|
.then(resolve)
|
|
.catch((error): void => {
|
|
errorHandler(error);
|
|
reject(error);
|
|
});
|
|
});
|
|
}
|
|
|
|
private createMethodSubscribe (method: RpcMethod): RpcInterfaceMethod {
|
|
const [updateType, subMethod, unsubMethod] = method.pubsub;
|
|
const subName = `${method.section}_${subMethod}`;
|
|
const unsubName = `${method.section}_${unsubMethod}`;
|
|
const subType = `${method.section}_${updateType}`;
|
|
|
|
const call = (...values: any[]): Observable<any> => {
|
|
return new Observable((observer: Observer<any>): VoidCallback => {
|
|
// Have at least an empty promise, as used in the unsubscribe
|
|
let subscriptionPromise: Promise<number | void> = Promise.resolve();
|
|
const errorHandler = (error: Error): void => {
|
|
const message = this.createErrorMessage(method, error);
|
|
|
|
l.error(message);
|
|
|
|
observer.error(new Error(message));
|
|
};
|
|
|
|
try {
|
|
const params = this.formatInputs(method, values);
|
|
const paramsJson = params.map((param): AnyJson => param.toJSON());
|
|
const update = (error?: Error, result?: any): void => {
|
|
if (error) {
|
|
l.error(this.createErrorMessage(method, error));
|
|
return;
|
|
}
|
|
|
|
observer.next(this.formatOutput(method, params, result));
|
|
};
|
|
|
|
subscriptionPromise = this.createSubscriber({ subType, subName, paramsJson, update }, errorHandler);
|
|
} catch (error) {
|
|
errorHandler(error);
|
|
}
|
|
|
|
// Teardown logic
|
|
return (): void => {
|
|
// Delete from cache
|
|
// Reason:
|
|
// ```
|
|
// const s = api.query.system.accountNonce(addr1).subscribe(); // let's say it's 6
|
|
// s.unsubscribe();
|
|
// // wait a bit, for the nonce to increase to 7
|
|
// api.query.system.accountNonce(addr1).subscribe(); // will output 6 instead of 7 if we don't clear cache
|
|
// // that's because all our observables are replay(1)
|
|
// ```
|
|
// eslint-disable-next-line @typescript-eslint/no-use-before-define
|
|
memoized.delete(...values);
|
|
|
|
// Unsubscribe from provider
|
|
subscriptionPromise
|
|
.then((subscriptionId): Promise<boolean> =>
|
|
isNumber(subscriptionId)
|
|
? this.provider.unsubscribe(subType, unsubName, subscriptionId)
|
|
: Promise.resolve(false)
|
|
)
|
|
.catch((error: Error): void => l.error(this.createErrorMessage(method, error)));
|
|
};
|
|
}).pipe(drr());
|
|
};
|
|
|
|
const memoized = memoizee(call, {
|
|
// Dynamic length for argument
|
|
length: false,
|
|
// Normalize args so that different args that should be cached
|
|
// together are cached together.
|
|
// E.g.: `query.my.method('abc') === query.my.method(createType('AccountId', 'abc'));`
|
|
// eslint-disable-next-line @typescript-eslint/unbound-method
|
|
normalizer: JSON.stringify
|
|
});
|
|
|
|
return memoized;
|
|
}
|
|
|
|
private formatInputs (method: RpcMethod, inputs: any[]): Codec[] {
|
|
const reqArgCount = method.params.filter(({ isOptional }): boolean => !isOptional).length;
|
|
const optText = reqArgCount === method.params.length
|
|
? ''
|
|
: ` (${method.params.length - reqArgCount} optional)`;
|
|
|
|
assert(inputs.length >= reqArgCount && inputs.length <= method.params.length, `Expected ${method.params.length} parameters${optText}, ${inputs.length} found instead`);
|
|
|
|
return inputs.map((input, index): Codec =>
|
|
createTypeUnsafe(method.params[index].type, [input])
|
|
);
|
|
}
|
|
|
|
private treatAsHex (key: StorageKey): boolean {
|
|
// :code is problematic - it does not have the length attached, which is
|
|
// unlike all other storage entries where it is indeed properly encoded
|
|
return ['0x3a636f6465'].includes(key.toHex());
|
|
}
|
|
|
|
private formatOutput (method: RpcMethod, params: Codec[], result?: any): Codec | Codec[] {
|
|
if (method.type === 'StorageData') {
|
|
const key = params[0] as StorageKey;
|
|
|
|
try {
|
|
return this.formatStorageData(key, result);
|
|
} catch (error) {
|
|
console.error(`Unable to decode storage ${key.section}.${key.method}:`, error.message);
|
|
|
|
throw error;
|
|
}
|
|
} else if (method.type === 'StorageChangeSet') {
|
|
// For StorageChangeSet, the changes has the [key, value] mappings
|
|
const changes: [string, string | null][] = result.changes;
|
|
const keys = params[0] as Vec<StorageKey>;
|
|
const withCache = keys.length !== 1;
|
|
|
|
// multiple return values (via state.storage subscription), decode the values
|
|
// one at a time, all based on the query types. Three values can be returned -
|
|
// - Codec - There is a valid value, non-empty
|
|
// - null - The storage key is empty
|
|
return keys.reduce((results, key: StorageKey): Codec[] => {
|
|
try {
|
|
results.push(this.formatStorageSet(key, changes, withCache));
|
|
} catch (error) {
|
|
console.error(`Unable to decode storage ${key.section}.${key.method}:`, error.message);
|
|
|
|
throw error;
|
|
}
|
|
|
|
return results;
|
|
}, [] as Codec[]);
|
|
}
|
|
|
|
return createTypeUnsafe(method.type, [result]);
|
|
}
|
|
|
|
private formatStorageData (key: StorageKey, value: string | null): Codec {
|
|
// single return value (via state.getStorage), decode the value based on the
|
|
// outputType that we have specified. Fallback to Data on nothing
|
|
const type = key.outputType || 'Data';
|
|
const meta = key.meta || EMPTY_META;
|
|
const isEmpty = isNull(value);
|
|
|
|
// we convert to Uint8Array since it maps to the raw encoding, all
|
|
// data will be correctly encoded (incl. numbers, excl. :code)
|
|
const input = isEmpty
|
|
? null
|
|
: this.treatAsHex(key)
|
|
? value
|
|
: u8aToU8a(value);
|
|
|
|
if (meta.modifier.isOptional) {
|
|
return new Option(
|
|
createClass(type),
|
|
isEmpty
|
|
? null
|
|
: createTypeUnsafe(type, [input], true)
|
|
);
|
|
}
|
|
|
|
return createTypeUnsafe(type, [isEmpty ? meta.fallback : input], true);
|
|
}
|
|
|
|
private formatStorageSet (key: StorageKey, changes: [string, string | null][], witCache: boolean): Codec {
|
|
// Fallback to Data (i.e. just the encoding) if we don't have a specific type
|
|
const type = key.outputType || 'Data';
|
|
const hexKey = key.toHex();
|
|
const meta = key.meta || EMPTY_META;
|
|
|
|
// if we don't find the value, this is our fallback
|
|
// - in the case of an array of values, fill the hole from the cache
|
|
// - if a single result value, don't fill - it is not an update hole
|
|
// - fallback to an empty option in all cases
|
|
const emptyVal = (witCache && this._storageCache.get(hexKey)) || null;
|
|
|
|
// see if we have a result value for this specific key, fallback to the cache value
|
|
// when the value in the set is not available, or is null/empty.
|
|
const [, value] = changes.find(([key, value]): boolean =>
|
|
!isNull(value) && key === hexKey
|
|
) || [null, emptyVal];
|
|
const isEmpty = isNull(value);
|
|
const input = isEmpty
|
|
? null
|
|
: this.treatAsHex(key)
|
|
? value
|
|
: u8aToU8a(value);
|
|
|
|
// store the retrieved result - the only issue with this cache is that there is no
|
|
// clearing of it, so very long running processes (not just a couple of hours, longer)
|
|
// will increase memory beyond what is allowed.
|
|
this._storageCache.set(hexKey, value);
|
|
|
|
if (meta.modifier.isOptional) {
|
|
return new Option(
|
|
createClass(type),
|
|
isEmpty
|
|
? null
|
|
: createTypeUnsafe(type, [input], true)
|
|
);
|
|
}
|
|
|
|
return createTypeUnsafe(type, [isEmpty ? meta.fallback : input], true);
|
|
}
|
|
}
|