book/architecture: RPC handlers and related

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` <CODE_LINK>
+- 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:
+- <LINK_TO_INTERNAL_FIELDS_IN_REQUEST_TYPE>
+
+Unless one of these actually allows something unintentionally bad to happen, this is mostly an unimportant detail.
+<CHECK_THAT_ONE_OF_THESE_FIELDS_ISNT_A_SECURITY_FLAW>
+
+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.

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 |

books/architecture/src/rpc/handler/intro.md

@@ -1,2 +1,8 @@
 # The handler
-> TODO: fill after `cuprate-rpc-handler` is created.
+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: <LINK_TO_FILE>
+- Binary handlers: <LINK_TO_FILE>
+- Other JSON handlers: <LINK_TO_FILE>

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.

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 |
+
+`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.

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