diff --git a/SCRATCHPAD.txt b/SCRATCHPAD.txt new file mode 100644 index 000000000..a0ad26945 --- /dev/null +++ b/SCRATCHPAD.txt @@ -0,0 +1,24 @@ +RPC stuff that needs to be written in the architecture book: + +## General +- diagram showing full pipeline from input to output with crate responsibilities listed along the line + +## The handler +- {json-rpc, binary, other} handler functions implemented in `cuprated` +- handler -> helper function -> internal component's `Service` + +## Unsupported RPC calls / RPC calls with different behavior +- https://github.com/Cuprate/cuprate/issues/278 +- binary strings -> full JSON: `get_transaction_pool_backlog`, `get_output_distribution` +- not in `monerod` yet: `get_tx_ids_loose` + +## Differences with monerod (Request strictness) +Some of `monerod`'s RPC request types contain fields not for users to provide, +but for internal usage within the RPC handlers and `monerod` itself, some examples: +- + +Unless one of these actually allows something unintentionally bad to happen, this is mostly an unimportant detail. + + +Practically, it means users can provide these fields and `monerod` will deserialize them +and accept them fine, while `cuprated` will not because they are not part of the type. diff --git a/books/architecture/src/appendix/crates.md b/books/architecture/src/appendix/crates.md index 5124180fb..9f9935aa6 100644 --- a/books/architecture/src/appendix/crates.md +++ b/books/architecture/src/appendix/crates.md @@ -52,7 +52,6 @@ cargo doc --open --package cuprate-blockchain | [`cuprate-json-rpc`](https://doc.cuprate.org/cuprate_json_rpc) | [`rpc/json-rpc/`](https://github.com/Cuprate/cuprate/tree/main/rpc/json-rpc) | JSON-RPC 2.0 implementation | [`cuprate-rpc-types`](https://doc.cuprate.org/cuprate_rpc_types) | [`rpc/types/`](https://github.com/Cuprate/cuprate/tree/main/rpc/types) | Monero RPC types and traits | [`cuprate-rpc-interface`](https://doc.cuprate.org/cuprate_rpc_interface) | [`rpc/interface/`](https://github.com/Cuprate/cuprate/tree/main/rpc/interface) | RPC interface & routing -| [`cuprate-rpc-handler`](https://doc.cuprate.org/cuprate_rpc_handler) | [`rpc/handler/`](https://github.com/Cuprate/cuprate/tree/main/rpc/handler) | RPC inner handlers ## ZMQ | Crate | In-tree path | Purpose | diff --git a/books/architecture/src/rpc/handler/intro.md b/books/architecture/src/rpc/handler/intro.md index e664f5bb9..e420a5c7c 100644 --- a/books/architecture/src/rpc/handler/intro.md +++ b/books/architecture/src/rpc/handler/intro.md @@ -1,2 +1,8 @@ # The handler -> TODO: fill after `cuprate-rpc-handler` is created. \ No newline at end of file +The handlers (functions that map requests into responses) are / can be generic with `cuprate-rpc-interface`. + +The main handlers used by Cuprate is implemented in `cuprated` itself, it implements the standard RPC handlers modeled after `monerod`. + +- JSON-RPC handlers: +- Binary handlers: +- Other JSON handlers: \ No newline at end of file diff --git a/books/architecture/src/rpc/interface.md b/books/architecture/src/rpc/interface.md index 3557ffbb1..6992bdd48 100644 --- a/books/architecture/src/rpc/interface.md +++ b/books/architecture/src/rpc/interface.md @@ -29,8 +29,7 @@ async fn json_rpc( ``` and you provide the function body. -The main handler crate is [`cuprate-rpc-handler`](https://doc.cuprate.org/cuprate_rpc_handler). -This crate implements the standard RPC behavior, i.e. it mostly mirrors `monerod`. +The main handler crate is `cuprated` itself, it implements the standard RPC behavior, i.e. it mostly mirrors `monerod`. Although, it's worth noting that other implementations are possible, such as an RPC handler that caches blocks, or an RPC handler that only accepts certain endpoints, or any combination. \ No newline at end of file diff --git a/books/architecture/src/rpc/intro.md b/books/architecture/src/rpc/intro.md index acfc60456..dbdd68d4c 100644 --- a/books/architecture/src/rpc/intro.md +++ b/books/architecture/src/rpc/intro.md @@ -27,4 +27,29 @@ The main components that make up Cuprate's RPC are noted below, alongside the eq | [`cuprate-json-rpc`](https://doc.cuprate.org/cuprate_json_rpc) | [`jsonrpc_structs.h`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/contrib/epee/include/net/jsonrpc_structs.h), [`http_server_handlers_map2.h`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/contrib/epee/include/net/http_server_handlers_map2.h) | JSON-RPC 2.0 implementation | `monerod`'s JSON-RPC 2.0 handling is spread across a few files. The first defines some data structures, the second contains macros that (essentially) implement JSON-RPC 2.0. | [`cuprate-rpc-types`](https://doc.cuprate.org/cuprate_rpc_types) | [`core_rpc_server_commands_defs.h`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/src/rpc/core_rpc_server_commands_defs.h) | RPC request/response type definitions and (de)serialization | | | [`cuprate-rpc-interface`](https://doc.cuprate.org/cuprate_rpc_interface) | [`core_rpc_server.h`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/src/rpc/core_rpc_server.h) | RPC interface, routing, endpoints | | -| [`cuprate-rpc-handler`](https://doc.cuprate.org/cuprate_rpc_handler) | [`core_rpc_server.cpp`](https://github.com/monero-project/monero/blob/caa62bc9ea1c5f2ffe3ffa440ad230e1de509bfd/src/rpc/core_rpc_server.cpp) | RPC request/response handling | These are the "inner handler" functions that turn requests into responses | \ No newline at end of file + +`cuprated` utilizes these crates and contains the actual functions that handle the request -> response mappings. + +## Diagram +A diagram of the crate's responsibilities in `cuprated`'s RPC system. +``` + cuprate-rpc-types + + + cuprate-json-rpc + + + cuprate-rpc-interface + │ │ +┌───────────────────────────┤ ├───────────────────┐ +▼ ▼ ▼ ▼ +CLIENT ─► ROUTE ─► REQUEST ─► HANDLER ─► RESPONSE ─► CLIENT + ▲ ▲ + └───┬───┘ + │ + cuprated's handler functions +``` + +`cuprated` only contains the: +- handler functions (the functions that map requests into responses) +- glue code with the rest of Cuprate to make the above happen + +All the other details are handled in other crates. \ No newline at end of file diff --git a/rpc/interface/README.md b/rpc/interface/README.md index fa5496c10..7e5deab87 100644 --- a/rpc/interface/README.md +++ b/rpc/interface/README.md @@ -21,7 +21,7 @@ This is where your [`RpcHandler`] turns this `Request` into a `Response`. You hand this `Response` back to `cuprate-rpc-interface` and it will take care of sending it back to the client. -The main handler used by Cuprate is implemented in the `cuprate-rpc-handler` crate; +The main handler used by Cuprate is implemented in `cuprated` itself, it implements the standard RPC handlers modeled after `monerod`. # Purpose