From 81aad9641f32053b9fd61f4b12445bb1da65357c Mon Sep 17 00:00:00 2001 From: "hinto.janai" Date: Wed, 12 Jun 2024 16:16:09 -0400 Subject: [PATCH] docs --- rpc/monero-rpc-types/Cargo.toml | 4 +- rpc/monero-rpc-types/README.md | 61 +++++++++++++++++++ rpc/monero-rpc-types/src/json.rs | 2 +- rpc/monero-rpc-types/src/lib.rs | 34 ++++++----- rpc/monero-rpc-types/src/macros.rs | 4 +- rpc/monero-rpc-types/src/other.rs | 2 +- .../src/{misc.rs => status.rs} | 52 +++++++++++----- 7 files changed, 123 insertions(+), 36 deletions(-) create mode 100644 rpc/monero-rpc-types/README.md rename rpc/monero-rpc-types/src/{misc.rs => status.rs} (65%) diff --git a/rpc/monero-rpc-types/Cargo.toml b/rpc/monero-rpc-types/Cargo.toml index 71ca4ed..ca7c827 100644 --- a/rpc/monero-rpc-types/Cargo.toml +++ b/rpc/monero-rpc-types/Cargo.toml @@ -9,12 +9,12 @@ repository = "https://github.com/Cuprate/cuprate/tree/main/rpc/monero-rpc-types keywords = ["monero", "rpc", "types"] [features] -default = ["serde"] +default = [] [dependencies] monero-serai = { workspace = true } paste = { workspace = true } -serde = { workspace = true, optional = true } +serde = { workspace = true } strum = { workspace = true, features = ["derive"] } [dev-dependencies] diff --git a/rpc/monero-rpc-types/README.md b/rpc/monero-rpc-types/README.md new file mode 100644 index 0000000..9b37895 --- /dev/null +++ b/rpc/monero-rpc-types/README.md @@ -0,0 +1,61 @@ +Monero RPC types. + +# What +This crate ports the types used in Monero's RPC interface, including: +- JSON types +- Binary (epee) types +- Mixed types +- Other commonly used RPC types + +# Modules +This crate's types are split in the following manner: + +1. This crate has 3 modules: + - The root module (`monero_rpc_types`) + - [`req`] (request types) + - [`resp`] (response types) +1. Miscellaneous types are found in the root module, e.g. [`Status`] +1. The `req` and `resp` modules perfectly mirror each-other, and are split into 3 modules: + - `json` (JSON types from the `/json_rpc` endpoint) + - `bin` (Binary types from the binary endpoints) + - `other` (Misc JSON types from other endpoints) +1. Each type in `req` has a corresponding type in `resp` and vice-versa with an identical name, e.g. [`req::json::GetBlockCount`] and [`resp::json::GetBlockCount`] + +# Documentation +The documentation for types within [`req`] and [`resp`] are omitted, +as they can be found in [Monero's RPC documentation](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#on_get_block_hash). + +However, each type will document: +- The exact type definition location in `monerod` +- The Monero RPC documentation link + +# Naming +The naming for types within [`req`] and [`resp`] follow the following scheme: +- Convert the endpoint or method name into `UpperCamelCase` +- Remove any suffix extension + +For example: + +| Endpoint/method | Crate location and name | +|-----------------|-------------------------| +| [`get_block_count`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_block_count) | [`req::json::GetBlockCount`] & [`resp::json::GetBlockCount`] +| [`/get_blocks.bin`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_blockbin) | `req::bin::GetBlocks` & `resp::bin::GetBlocks` +| [`/get_height`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_height) | `req::other::GetHeight` & `resp::other::GetHeight` + +TODO: fix doc links when types are ready. + +# Mixed types +Note that some types within [`resp::other`] mix JSON & binary, i.e., +the message overall is JSON, however some fields contain binary +values, for example: + +```json +{ + "string": "", + "float": 30.0, + "integer": 30, + "binary": /* serialized binary */ +} +``` + +TODO: list the specific types. \ No newline at end of file diff --git a/rpc/monero-rpc-types/src/json.rs b/rpc/monero-rpc-types/src/json.rs index 38b673d..1918200 100644 --- a/rpc/monero-rpc-types/src/json.rs +++ b/rpc/monero-rpc-types/src/json.rs @@ -32,7 +32,7 @@ define_monero_rpc_struct! { // The struct generated and all fields are `pub`. count: u64, - status: crate::misc::Status, + status: crate::Status, untrusted: bool, } } diff --git a/rpc/monero-rpc-types/src/lib.rs b/rpc/monero-rpc-types/src/lib.rs index c45a6c4..e3bcf2b 100644 --- a/rpc/monero-rpc-types/src/lib.rs +++ b/rpc/monero-rpc-types/src/lib.rs @@ -1,7 +1,4 @@ -//! Monero RPC types. -//! -//! TODO. - +#![doc = include_str!("../README.md")] //---------------------------------------------------------------------------------------------------- Lints // Forbid lints. // Our code, and code generated (e.g macros) cannot overrule these. @@ -98,11 +95,16 @@ )] //---------------------------------------------------------------------------------------------------- Use -mod bin; -mod data; -mod json; +// Misc types. +mod status; +pub use status::Status; + +// Internal modules. mod macros; -pub mod misc; + +// Request/response JSON/binary/other types. +mod bin; +mod json; mod other; /// TODO @@ -130,23 +132,23 @@ macro_rules! re_export_request_and_response_types { )* } ) => { paste::paste! { - /// TODO + /// RPC request types. pub mod req { - /// TODO + /// JSON types from the [`/json_rpc`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#json-rpc-methods) endpoint. pub mod json { $( pub use $crate::json::[] as $json_type; )* } - /// TODO + /// Binary types from [binary](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_blocksbin) endpoints. pub mod bin { $( pub use $crate::bin::[] as $binary_type; )* } - /// TODO + /// JSON types from the [`other`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#other-daemon-rpc-calls) endpoints. pub mod other { $( pub use $crate::other::[] as $other_type; @@ -154,23 +156,23 @@ macro_rules! re_export_request_and_response_types { } } - /// TODO + /// RPC response types. pub mod resp { - /// TODO + /// JSON types from the [`/json_rpc`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#json-rpc-methods) endpoint. pub mod json { $( pub use $crate::json::[] as $json_type; )* } - /// TODO + /// Binary types from [binary](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#get_blocksbin) endpoints. pub mod bin { $( pub use $crate::bin::[] as $binary_type; )* } - /// TODO + /// JSON types from the [`other`](https://www.getmonero.org/resources/developer-guides/daemon-rpc.html#other-daemon-rpc-calls) endpoints. pub mod other { $( pub use $crate::other::[] as $other_type; diff --git a/rpc/monero-rpc-types/src/macros.rs b/rpc/monero-rpc-types/src/macros.rs index b7327bd..35befa2 100644 --- a/rpc/monero-rpc-types/src/macros.rs +++ b/rpc/monero-rpc-types/src/macros.rs @@ -43,7 +43,7 @@ macro_rules! define_monero_rpc_struct { ) => { paste::paste! { #[allow(dead_code)] #[allow(missing_docs)] - #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] + #[derive(serde::Serialize, serde::Deserialize)] #[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] $( #[$request_type_attr] )* #[doc = concat!( @@ -81,7 +81,7 @@ macro_rules! define_monero_rpc_struct { #[allow(dead_code)] #[allow(missing_docs)] - #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] + #[derive(serde::Serialize, serde::Deserialize)] #[derive(Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] $( #[$response_type_attr] )* #[doc = concat!( diff --git a/rpc/monero-rpc-types/src/other.rs b/rpc/monero-rpc-types/src/other.rs index dbc1367..858ff73 100644 --- a/rpc/monero-rpc-types/src/other.rs +++ b/rpc/monero-rpc-types/src/other.rs @@ -13,7 +13,7 @@ define_monero_rpc_struct! { #[derive(Copy)] Request {}, Response { - status: crate::misc::Status, + status: crate::Status, untrusted: bool, } } diff --git a/rpc/monero-rpc-types/src/misc.rs b/rpc/monero-rpc-types/src/status.rs similarity index 65% rename from rpc/monero-rpc-types/src/misc.rs rename to rpc/monero-rpc-types/src/status.rs index 456c0fd..b822172 100644 --- a/rpc/monero-rpc-types/src/misc.rs +++ b/rpc/monero-rpc-types/src/status.rs @@ -1,19 +1,24 @@ -//! TODO. +//! RPC response status type. //---------------------------------------------------------------------------------------------------- Import +use serde::{Deserialize, Serialize}; use strum::{ AsRefStr, Display, EnumCount, EnumIs, EnumIter, EnumMessage, EnumProperty, EnumString, EnumTryAs, FromRepr, IntoStaticStr, VariantArray, VariantNames, }; //---------------------------------------------------------------------------------------------------- TODO -/// TODO +/// RPC response status. /// -/// . +/// This type represents `monerod`'s frequently appearing string field, `status`. /// -/// ## String formatting +/// This field appears within RPC [JSON response](crate::resp::json) types. +/// +/// Reference: . +/// +/// ## Serialization and string formatting /// ```rust -/// # use monero_rpc_types::misc::*; +/// # use monero_rpc_types::*; /// use serde_json::to_string; /// use strum::AsRefStr; /// @@ -70,30 +75,49 @@ use strum::{ IntoStaticStr, VariantArray, VariantNames, + Serialize, + Deserialize, )] -#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))] pub enum Status { - /// TODO + /// Successful RPC response, everything is OK. #[strum(serialize = "OK")] - #[cfg_attr(feature = "serde", serde(rename = "OK"))] + #[serde(rename = "OK", alias = "Ok", alias = "ok")] #[default] Ok, - /// TODO + #[serde(alias = "Retry", alias = "RETRY", alias = "retry")] + /// The RPC call failed and should be retried. + /// + /// TODO: confirm this. Retry, - /// TODO + #[serde(alias = "failed", alias = "FAILED")] + /// The RPC call failed. Failed, - /// TODO + /// The RPC call contained bad input, unknown method, unknown params, etc. #[strum(serialize = "Invalid request type")] - #[cfg_attr(feature = "serde", serde(rename = "Invalid request type"))] + #[serde( + rename = "Invalid request type", + alias = "invalid request type", + alias = "INVALID REQUEST TYPE" + )] BadRequest, - /// TODO + /// The RPC call contained malformed JSON. #[strum(serialize = "Malformed json")] - #[cfg_attr(feature = "serde", serde(rename = "Malformed json"))] + #[serde( + rename = "Malformed json", + alias = "malformed json", + alias = "MALFORMED JSON", + alias = "Malformed JSON", + alias = "malformed JSON" + )] BadJson, + // TODO: + // This may not be all the string `monerod` uses. + // We could use an `Other(String)` here just in case, + // otherwise deserialization would fail. } //---------------------------------------------------------------------------------------------------- Tests