From 6b0500e02db667677f4a57e39bf4c1c8972e411b Mon Sep 17 00:00:00 2001 From: yukang Date: Thu, 12 Oct 2023 17:21:46 +0800 Subject: [PATCH] add openrpc links --- devtools/doc/rpc-gen/src/gen.rs | 34 +++++++++---- rpc/README.md | 85 +++++++++++++-------------------- rpc/src/module/subscription.rs | 4 +- 3 files changed, 61 insertions(+), 62 deletions(-) diff --git a/devtools/doc/rpc-gen/src/gen.rs b/devtools/doc/rpc-gen/src/gen.rs index 3243a31b07..4af594b8f7 100644 --- a/devtools/doc/rpc-gen/src/gen.rs +++ b/devtools/doc/rpc-gen/src/gen.rs @@ -14,9 +14,10 @@ impl RpcModule { let mut res = String::new(); let capitlized = self.module_title.to_string(); res.push_str(&format!( - " * [Module {}](#module-{})\n", + " * [Module {}](#module-{}) {}\n", capitlized, - self.module_title.to_lowercase() + self.module_title.to_lowercase(), + gen_module_openrpc_playground(&capitlized) )); let mut method_names = self .module_methods @@ -42,6 +43,10 @@ impl RpcModule { let description = self.module_description.replace("##", "#####"); res.push_str(&format!("### Module {}\n", capitlized)); + res.push_str(&format!( + "- {}\n\n", + gen_module_openrpc_playground(&capitlized) + )); res.push_str(&format!("{}\n\n", description)); for method in &self.module_methods { @@ -77,7 +82,7 @@ impl RpcModule { name, signatures, desc, )); } - res + res + "\n" } } @@ -165,13 +170,13 @@ impl RpcDocGenerator { // generate module methods content for rpc_module in self.rpc_module_methods.iter() { - let content = format!("{}\n", rpc_module.gen_module_content()); - res.push_str(&content); + if rpc_module.module_title == "Subscription" { + gen_subscription_rpc_doc(&mut res); + } else { + res.push_str(&rpc_module.gen_module_content()); + } } - // generate subscription module - gen_subscription_rpc_doc(&mut res); - // generate type content res.push_str("## RPC Types\n"); self.gen_type_content(&mut res); @@ -404,6 +409,19 @@ fn gen_subscription_rpc_doc(res: &mut String) { res.push_str(format!("{}\n", sub_desc).as_str()); } +/// generate openrpc playground urls +fn gen_module_openrpc_playground(module: &str) -> String { + let logo = "https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg"; + let title = format!("CKB-{}", capitlize(module)); + let json_url = format!( + "https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/{}_rpc_doc.json", + module.to_lowercase() + ); + + format!("[👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]={}&uiSchema[appBar][ui:splitView]=false", title) + + format!("&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]={}&schemaUrl={})", logo, json_url).as_str() +} + #[cfg(test)] mod tests { use super::*; diff --git a/rpc/README.md b/rpc/README.md index 94fa30ea9d..4e7cdc2f12 100644 --- a/rpc/README.md +++ b/rpc/README.md @@ -31,9 +31,9 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1. * [RPC Methods](#rpc-methods) - * [Module Alert](#module-alert) + * [Module Alert](#module-alert) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Alert&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/alert_rpc_doc.json) * [Method `send_alert`](#method-send_alert) - * [Module Chain](#module-chain) + * [Module Chain](#module-chain) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Chain&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/chain_rpc_doc.json) * [Method `get_block`](#method-get_block) * [Method `get_block_by_number`](#method-get_block_by_number) * [Method `get_header`](#method-get_header) @@ -57,19 +57,19 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1. * [Method `estimate_cycles`](#method-estimate_cycles) * [Method `get_fee_rate_statics`](#method-get_fee_rate_statics) * [Method `get_fee_rate_statistics`](#method-get_fee_rate_statistics) - * [Module Debug](#module-debug) + * [Module Debug](#module-debug) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Debug&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/debug_rpc_doc.json) * [Method `jemalloc_profiling_dump`](#method-jemalloc_profiling_dump) * [Method `update_main_logger`](#method-update_main_logger) * [Method `set_extra_logger`](#method-set_extra_logger) - * [Module Experiment](#module-experiment) + * [Module Experiment](#module-experiment) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Experiment&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/experiment_rpc_doc.json) * [Method `dry_run_transaction`](#method-dry_run_transaction) * [Method `calculate_dao_maximum_withdraw`](#method-calculate_dao_maximum_withdraw) - * [Module Indexer](#module-indexer) + * [Module Indexer](#module-indexer) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Indexer&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/indexer_rpc_doc.json) * [Method `get_indexer_tip`](#method-get_indexer_tip) * [Method `get_cells`](#method-get_cells) * [Method `get_transactions`](#method-get_transactions) * [Method `get_cells_capacity`](#method-get_cells_capacity) - * [Module Integration_test](#module-integration_test) + * [Module Integration_test](#module-integration_test) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Integration_test&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/integration_test_rpc_doc.json) * [Method `process_block_without_verify`](#method-process_block_without_verify) * [Method `truncate`](#method-truncate) * [Method `generate_block`](#method-generate_block) @@ -77,10 +77,10 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1. * [Method `notify_transaction`](#method-notify_transaction) * [Method `generate_block_with_template`](#method-generate_block_with_template) * [Method `calculate_dao_field`](#method-calculate_dao_field) - * [Module Miner](#module-miner) + * [Module Miner](#module-miner) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Miner&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/miner_rpc_doc.json) * [Method `get_block_template`](#method-get_block_template) * [Method `submit_block`](#method-submit_block) - * [Module Net](#module-net) + * [Module Net](#module-net) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Net&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/net_rpc_doc.json) * [Method `local_node_info`](#method-local_node_info) * [Method `get_peers`](#method-get_peers) * [Method `get_banned_addresses`](#method-get_banned_addresses) @@ -91,17 +91,17 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1. * [Method `add_node`](#method-add_node) * [Method `remove_node`](#method-remove_node) * [Method `ping_peers`](#method-ping_peers) - * [Module Pool](#module-pool) + * [Module Pool](#module-pool) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Pool&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/pool_rpc_doc.json) * [Method `send_transaction`](#method-send_transaction) * [Method `remove_transaction`](#method-remove_transaction) * [Method `tx_pool_info`](#method-tx_pool_info) * [Method `clear_tx_pool`](#method-clear_tx_pool) * [Method `get_raw_tx_pool`](#method-get_raw_tx_pool) * [Method `tx_pool_ready`](#method-tx_pool_ready) - * [Module Stats](#module-stats) + * [Module Stats](#module-stats) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Stats&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/stats_rpc_doc.json) * [Method `get_blockchain_info`](#method-get_blockchain_info) * [Method `get_deployments_info`](#method-get_deployments_info) - * [Module Subscription](#module-subscription) + * [Module Subscription](#module-subscription) [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Subscription&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/subscription_rpc_doc.json) * [Method `subscribe`](#method-subscribe) * [Method `unsubscribe`](#method-unsubscribe) * [RPC Types](#rpc-types) @@ -200,6 +200,8 @@ The crate `ckb-rpc`'s minimum supported rustc version is 1.71.1. * [Type `UncleTemplate`](#type-uncletemplate) * [RPC Errors](#rpc-errors) ### Module Alert +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Alert&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/alert_rpc_doc.json) + RPC Module Alert for network alerts. An alert is a message about critical problems to be broadcast to all nodes via the p2p network. @@ -263,6 +265,8 @@ Response ``` ### Module Chain +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Chain&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/chain_rpc_doc.json) + RPC Module Chain for methods related to the canonical chain. This module queries information about the canonical chain. @@ -1854,6 +1858,8 @@ Response ``` ### Module Debug +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Debug&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/debug_rpc_doc.json) + RPC Module Debug for internal RPC methods. **This module is for CKB developers and will not guarantee compatibility.** The methods here @@ -1893,6 +1899,8 @@ they only append logs to their log files. Removes the logger when this is null. ### Module Experiment +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Experiment&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/experiment_rpc_doc.json) + RPC Module Experiment for experimenting methods. **EXPERIMENTAL warning** @@ -2042,6 +2050,8 @@ Response ``` ### Module Indexer +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Indexer&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/indexer_rpc_doc.json) + RPC Module Indexer. #### Method `get_indexer_tip` @@ -2902,6 +2912,8 @@ Response ``` ### Module Integration_test +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Integration_test&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/integration_test_rpc_doc.json) + RPC for Integration Test. #### Method `process_block_without_verify` @@ -3394,6 +3406,8 @@ Response ``` ### Module Miner +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Miner&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/miner_rpc_doc.json) + RPC Module Miner for miners. A miner gets a template from CKB, optionally selects transactions, resolves the PoW puzzle, and @@ -3605,6 +3619,8 @@ Response ``` ### Module Net +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Net&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/net_rpc_doc.json) + RPC Module Net for P2P network. #### Method `local_node_info` @@ -4141,6 +4157,8 @@ Response ``` ### Module Pool +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Pool&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/pool_rpc_doc.json) + RPC Module Pool for transaction memory pool. #### Method `send_transaction` @@ -4421,6 +4439,8 @@ Response ``` ### Module Stats +- [👉 OpenRPC spec](http://playground.open-rpc.org/?uiSchema[appBar][ui:title]=CKB-Stats&uiSchema[appBar][ui:splitView]=false&uiSchema[appBar][ui:examplesDropdown]=false&uiSchema[appBar][ui:logoUrl]=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/ckb-logo.jpg&schemaUrl=https://raw.githubusercontent.com/chenyukang/ckb-rpc-resources/main/json/stats_rpc_doc.json) + RPC Module Stats for getting various statistic data. #### Method `get_blockchain_info` @@ -4514,50 +4534,11 @@ Response } ``` -### Module Subscription - RPC Module Subscription that CKB node will push new messages to subscribers. - - RPC subscriptions require a full duplex connection. CKB offers such connections in the form of - TCP (enable with rpc.tcp_listen_address configuration option) and WebSocket (enable with - rpc.ws_listen_address). - - ############### Examples - - TCP RPC subscription: - - ```bash - telnet localhost 18114 - > {"id": 2, "jsonrpc": "2.0", "method": "subscribe", "params": ["new_tip_header"]} - < {"jsonrpc":"2.0","result":"0x0","id":2} - < {"jsonrpc":"2.0","method":"subscribe","params":{"result":"...block header json...", -"subscription":0}} - < {"jsonrpc":"2.0","method":"subscribe","params":{"result":"...block header json...", -"subscription":0}} - < ... - > {"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x0"]} - < {"jsonrpc":"2.0","result":true,"id":2} - ``` - - WebSocket RPC subscription: - - ```javascript - let socket = new WebSocket("ws://localhost:28114") - - socket.onmessage = function(event) { - console.log(`Data received from server: ${event.data}`); - } - - socket.send(`{"id": 2, "jsonrpc": "2.0", "method": "subscribe", "params": ["new_tip_header"]}`) - - socket.send(`{"id": 2, "jsonrpc": "2.0", "method": "unsubscribe", "params": ["0x0"]}`) - ``` - - RPC Module Subscription that CKB node will push new messages to subscribers. RPC subscriptions require a full duplex connection. CKB offers such connections in the form of -TCP (enable with rpc.tcp_listen_address configuration option) and WebSocket (enable with -rpc.ws_listen_address). +TCP (enable with `rpc.tcp_listen_address` configuration option) and WebSocket (enable with +`rpc.ws_listen_address`). ###### Examples diff --git a/rpc/src/module/subscription.rs b/rpc/src/module/subscription.rs index f08518647b..64567bc342 100644 --- a/rpc/src/module/subscription.rs +++ b/rpc/src/module/subscription.rs @@ -10,8 +10,8 @@ use tokio::sync::broadcast; /// RPC Module Subscription that CKB node will push new messages to subscribers. /// /// RPC subscriptions require a full duplex connection. CKB offers such connections in the form of -/// TCP (enable with rpc.tcp_listen_address configuration option) and WebSocket (enable with -/// rpc.ws_listen_address). +/// TCP (enable with `rpc.tcp_listen_address` configuration option) and WebSocket (enable with +/// `rpc.ws_listen_address`). /// /// ###### Examples ///