[tracking] RPC refactoring wishlist

[aatifsyed]

The motivating use-case is #4038.
While we're in the area we can do a lot of cleanup.

• feat: trait RpcMethod for server, client, and schema #4067
• refactor: remove duplicate JsonRpcError and Request objects #4081
• Improve jsonrpsee RpcModule ergonomics #4007
• refactor: consolidate crate::rpc_api into crate::rpc #4134
• refactor: rpc module organisation #4172
• Introduce crate::rpc::Client, remove crate::rpc_client::ApiInfo.
  • feat: rpc::Client #4140
  • refactor: remove rpc_client::ApiInfo #4280
• misc: doc lotus_json usage in rpc, and remove the OpenRPC snapshot #4231
• refactor: LotusJson for IPLD, Claim, BitField, ActorState and label lotus_json tech debt #4234
• Migrate handlers to trait RpcMethod.
  • Migration guide for RPC call sites is as follows. Deviations from this SHOULD be checked with me, and please add me as a reviewer to your PR
    • Use the snippets file to scaffold your implementation
      • Make sure the method name matches!
      • You may need to narrow the bounds on Ctx
    • Ensure rpc::types are minimal - any structs used by only one e.g gas API should live in gas.rs, not in types.rs. types.rs is only for types that are shared across APIs
    • Migrate the parameters, dropping LotusJson where possible.
    • Implement JsonSchema where necessary.
    • Add or amend the for_each_method macro in gas.rs.
      • It should be called to expose methods in the prelude
      • It should be called to register methods
    • RpcTest constructors should use RpcTest::basic_raw, and RpcMethodExt::request like this.
    • forest-cli calls should rpc::Client::from(api: ApiInfo) and then RpcMethodExt::call on that.
      In the limit, ApiInfo can be removed, and replaced by an rpc::Client::from_env method
    • forest-cli attach calls should be removed, and tracked under Define pattern for calling trait RpcMethod in forest-cli attach #4141
  • Progress:
    • refactor: migrate mpool_api to use trait RpcMethod #4139
    • refactor: migrate auth_api to use trait RpcMethod #4154
    • refactor: migrate beacon_api to use trait RpcMethod #4155
    • refactor: migrate chain_api to use trait RpcMethod (part 1) #4158
    • refactor: migrate chain_api to use trait RpcMethod (part 2/2)  #4168
    • refactor: migrate rpc::common to use trait RpcMethod #4175
    • feat: fix and verify GasEstimateGasLimit #4187
    • refactor: migrate wallet api to trait RpcEndpoint #4191
    • refactor: migrate net to trait RpcEndpoint #4200
    • refactor: migrate sync to trait RpcMethod #4203
    • refactor: migrate node to trait RpcEndpoint #4204
    • refactor: migrate state to trait RpcMethod (part 1) #4225
    • refactor: migrate MinerGetBaseInfo, StateCall to trait RpcMethod #4244
    • refactor: migrate StateNetworkName, StateReplay to trait RpcMethod #4248
• Define pattern for calling trait RpcMethod in forest-cli attach #4141 / refactor!: remove forest-cli attach #4358
• Support aliases: refactor: migrate beacon_api to use trait RpcMethod #4155 (comment)
• crate::rpc_client::RpcRequest::params should be Vec<Value> or RequestParameters, and should have better error handling.
• Remove inappropriate impls of HasLotusJson
  • Tuples should NOT implement HasLotusJson
  • Most types should NOT implement HasLotusJson

    • forest/src/rpc/mpool_api.rs

      Line 136 in f58b629

      type Params = (LotusJson<Message>, Option<MessageSendSpec>);

      
      Note that only the first parameter is wrapped in LotusJson - it has separate CBOR and JSON representations.
      MessageSendSpec, on the other hand, can just be deserialized normally.
      A misapplication of the HasLotusJson API has lead to the proliferation of lotus_json_with_self! calls
  • LotusJson<Vec<T>> should NOT recurse: users should use LotusJson<Vec<LotusJson<T>>
  • LotusJson<ApiTipsetKey> is wrong
• refactor: trait RpcMethod { const PERMISSION: ... } #4277
• Reconsider const generic on trait RpcMethod
• Make type names in OpenRPC document nice.
• Unconsolidate crate::rpc::types
• Autogenerate CLI, maybe JS bindings
  • rfc: generate client stubs from openrpc definitions #4295
• Autogenerate implementation report as discussed in Document RPC implementation status #4129

[aatifsyed]

Code snippets file for VSCode:

// This should live somewhere like `${workspaceDir}/.vscode/rpc.code-snippets`
{
	"rpc method": {
		"prefix": "impl RpcMethod",
		"body": [
			"pub enum ${1:MethodName} {}",
			"impl RpcMethod<${2:ARITY}> for $1 {",
			"const NAME: &'static str = \"Filecoin.$1\";",
			"const PARAM_NAMES: [&'static str; $2] = [$3];",
			"const API_VERSION: ApiVersion = ApiVersion::${7:V0};",
			"",
			"type Params = ($4);",
			"type Ok = $6;",
			"",
			"async fn handle(ctx: Ctx<impl Blockstore $8>, ($5): Self::Params) -> Result<Self::Ok, ServerError> {",
			"$0",
			"}", // fn handle
			"}", // impl RpcMethod
		]
	},
	"imports": {
		"prefix": "use",
		"body": [
			"use crate::rpc::{reflect::SelfDescribingRpcModule, ApiVersion, Ctx, RPCState, RpcMethod, RpcMethodExt as _, ServerError};",
			"use schemars::JsonSchema;"
		]
	},
}