diff --git a/binaries/cuprated/src/rpc/bin.rs b/binaries/cuprated/src/rpc/bin.rs index a03808d7..6a3a781f 100644 --- a/binaries/cuprated/src/rpc/bin.rs +++ b/binaries/cuprated/src/rpc/bin.rs @@ -1,4 +1,4 @@ -use cuprate_rpc_interface::{RpcError, RpcResponse}; +use cuprate_rpc_interface::RpcError; use cuprate_rpc_types::{ bin::{ BinRequest, BinResponse, GetBlocksByHeightRequest, GetBlocksByHeightResponse, diff --git a/binaries/cuprated/src/rpc/handler.rs b/binaries/cuprated/src/rpc/handler.rs index 2e15a5df..b475f29a 100644 --- a/binaries/cuprated/src/rpc/handler.rs +++ b/binaries/cuprated/src/rpc/handler.rs @@ -15,7 +15,7 @@ use tower::Service; use cuprate_blockchain::service::BlockchainReadHandle; use cuprate_helper::asynch::InfallibleOneshotReceiver; use cuprate_json_rpc::Id; -use cuprate_rpc_interface::{RpcError, RpcHandler, RpcRequest, RpcResponse}; +use cuprate_rpc_interface::{RpcError, RpcHandler}; use cuprate_txpool::service::TxpoolReadHandle; use crate::rpc::{bin, json, other}; diff --git a/binaries/cuprated/src/rpc/json.rs b/binaries/cuprated/src/rpc/json.rs index 70a9e497..34c95342 100644 --- a/binaries/cuprated/src/rpc/json.rs +++ b/binaries/cuprated/src/rpc/json.rs @@ -1,6 +1,6 @@ use std::sync::Arc; -use cuprate_rpc_interface::{RpcError, RpcResponse}; +use cuprate_rpc_interface::RpcError; use cuprate_rpc_types::json::{ AddAuxPowRequest, AddAuxPowResponse, BannedRequest, BannedResponse, CalcPowRequest, CalcPowResponse, FlushCacheRequest, FlushCacheResponse, FlushTransactionPoolRequest, diff --git a/binaries/cuprated/src/rpc/other.rs b/binaries/cuprated/src/rpc/other.rs index 6a84c650..49d8415a 100644 --- a/binaries/cuprated/src/rpc/other.rs +++ b/binaries/cuprated/src/rpc/other.rs @@ -1,4 +1,4 @@ -use cuprate_rpc_interface::{RpcError, RpcResponse}; +use cuprate_rpc_interface::RpcError; use cuprate_rpc_types::other::{ GetAltBlocksHashesRequest, GetAltBlocksHashesResponse, GetHeightRequest, GetHeightResponse, GetLimitRequest, GetLimitResponse, GetNetStatsRequest, GetNetStatsResponse, GetOutsRequest, diff --git a/rpc/interface/README.md b/rpc/interface/README.md index 3a63ac46..2d3faa75 100644 --- a/rpc/interface/README.md +++ b/rpc/interface/README.md @@ -17,7 +17,7 @@ CLIENT ─► ROUTE ─► REQUEST ─► HANDLER ─► RESPONSE ─► CLIENT Everything coming _in_ from a client is handled by this crate. -This is where your [`RpcHandler`] turns this [`RpcRequest`] into a [`RpcResponse`]. +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. @@ -33,7 +33,7 @@ This crate simply handles: - Defining handler function signatures - (De)serialization of requests/responses (JSON-RPC, binary, JSON) -The actual server details are all handled by the [`axum`] and [`tower`] ecosystem. +The actual server details are all handled by the [`axum`] and [`tower`] ecosystem.a The proper usage of this crate is to: 1. Implement a [`RpcHandler`] @@ -42,16 +42,18 @@ The proper usage of this crate is to: 3. Do whatever with it # The [`RpcHandler`] -This is your [`tower::Service`] that converts [`RpcRequest`]s into [`RpcResponse`]s, +This is your [`tower::Service`] that converts `Request`s into `Response`s, i.e. the "inner handler". -Said concretely, `RpcHandler` is a `tower::Service` where the associated types are from this crate: -- [`RpcRequest`] -- [`RpcResponse`] +Said concretely, `RpcHandler` is 3 `tower::Service`s where the associated types are +the 3 endpoint enums from [`cuprate_rpc_types`] and the error type from this crate: +- [`JsonRpcRequest`](cuprate_rpc_types::json::JsonRpcRequest) & [`JsonRpcResponse`](cuprate_rpc_types::json::JsonRpcResponse) +- [`BinRequest`](cuprate_rpc_types::bin::BinRequest) & [`BinResponse`](cuprate_rpc_types::bin::BinRequest) +- [`OtherRequest`](cuprate_rpc_types::other::OtherRequest) & [`OtherResponse`](cuprate_rpc_types::other::OtherRequest) - [`RpcError`] `RpcHandler`'s [`Future`](std::future::Future) is generic, _although_, -it must output `Result`. +it must output `Result<$RESPONSE, RpcError>`. The `RpcHandler` must also hold some state that is required for RPC server operation. @@ -83,7 +85,7 @@ use cuprate_rpc_types::{ json::{JsonRpcRequest, JsonRpcResponse, GetBlockCountResponse}, other::{OtherRequest, OtherResponse}, }; -use cuprate_rpc_interface::{RouterBuilder, RpcHandlerDummy, RpcRequest}; +use cuprate_rpc_interface::{RouterBuilder, RpcHandlerDummy, Request}; // Send a `/get_height` request. This endpoint has no inputs. async fn get_height(port: u16) -> OtherResponse { diff --git a/rpc/interface/src/lib.rs b/rpc/interface/src/lib.rs index d4376979..f3e2988e 100644 --- a/rpc/interface/src/lib.rs +++ b/rpc/interface/src/lib.rs @@ -7,16 +7,18 @@ mod rpc_error; mod rpc_handler; #[cfg(feature = "dummy")] mod rpc_handler_dummy; -mod rpc_request; -mod rpc_response; +// mod rpc_request; +// mod rpc_response; +mod rpc_service; pub use router_builder::RouterBuilder; pub use rpc_error::RpcError; pub use rpc_handler::RpcHandler; #[cfg(feature = "dummy")] pub use rpc_handler_dummy::RpcHandlerDummy; -pub use rpc_request::RpcRequest; -pub use rpc_response::RpcResponse; +// pub use rpc_request::RpcRequest; +// pub use rpc_response::RpcResponse; +pub use rpc_service::RpcService; // false-positive: used in `README.md`'s doc-test. #[cfg(test)] diff --git a/rpc/interface/src/route/bin.rs b/rpc/interface/src/route/bin.rs index c636d9c0..45447caf 100644 --- a/rpc/interface/src/route/bin.rs +++ b/rpc/interface/src/route/bin.rs @@ -7,7 +7,7 @@ use tower::ServiceExt; use cuprate_epee_encoding::from_bytes; use cuprate_rpc_types::bin::{BinRequest, BinResponse, GetTransactionPoolHashesRequest}; -use crate::{rpc_handler::RpcHandler, rpc_request::RpcRequest, rpc_response::RpcResponse}; +use crate::rpc_handler::RpcHandler; //---------------------------------------------------------------------------------------------------- Routes /// This macro generates route functions that expect input. diff --git a/rpc/interface/src/route/json_rpc.rs b/rpc/interface/src/route/json_rpc.rs index db7749ec..bf3d937d 100644 --- a/rpc/interface/src/route/json_rpc.rs +++ b/rpc/interface/src/route/json_rpc.rs @@ -15,7 +15,7 @@ use cuprate_rpc_types::{ RpcCallValue, }; -use crate::{rpc_handler::RpcHandler, rpc_request::RpcRequest, rpc_response::RpcResponse}; +use crate::rpc_handler::RpcHandler; //---------------------------------------------------------------------------------------------------- Routes /// The `/json_rpc` route function used in [`crate::RouterBuilder`]. diff --git a/rpc/interface/src/route/other.rs b/rpc/interface/src/route/other.rs index 26413820..129ddd59 100644 --- a/rpc/interface/src/route/other.rs +++ b/rpc/interface/src/route/other.rs @@ -25,7 +25,7 @@ use cuprate_rpc_types::{ RpcCall, }; -use crate::{rpc_handler::RpcHandler, rpc_request::RpcRequest, rpc_response::RpcResponse}; +use crate::rpc_handler::RpcHandler; //---------------------------------------------------------------------------------------------------- Routes /// This macro generates route functions that expect input. diff --git a/rpc/interface/src/rpc_handler.rs b/rpc/interface/src/rpc_handler.rs index b956586a..f4c9fb56 100644 --- a/rpc/interface/src/rpc_handler.rs +++ b/rpc/interface/src/rpc_handler.rs @@ -1,60 +1,42 @@ //! RPC handler trait. //---------------------------------------------------------------------------------------------------- Use -use std::future::Future; - use cuprate_rpc_types::{ bin::{BinRequest, BinResponse}, json::{JsonRpcRequest, JsonRpcResponse}, other::{OtherRequest, OtherResponse}, }; -use tower::Service; -use crate::{rpc_error::RpcError, rpc_request::RpcRequest, rpc_response::RpcResponse}; +use crate::RpcService; //---------------------------------------------------------------------------------------------------- RpcHandler /// An RPC handler. /// -/// This trait represents a type that can turn [`RpcRequest`]s into [`RpcResponse`]s. +/// This trait represents a type that can turn `Request`s into `Response`s. /// -/// Implementors of this trait must be [`tower::Service`]s that use: -/// - [`RpcRequest`] as the generic `Request` type -/// - [`RpcResponse`] as the associated `Response` type -/// - [`RpcError`] as the associated `Error` type -/// - A generic [`Future`] that outputs `Result` +/// Implementors of this trait must be: +/// - A [`tower::Service`]s that use [`JsonRpcRequest`] & [`JsonRpcResponse`] +/// - A [`tower::Service`]s that use [`BinRequest`] & [`BinResponse`] +/// - A [`tower::Service`]s that use [`OtherRequest`] & [`OtherResponse`] +/// +/// In other words, an [`RpcHandler`] is a type that implements [`tower::Service`] 3 times, +/// one for each endpoint enum type found in [`cuprate_rpc_types`]. +/// +/// The error type must always be [`RpcError`](crate::RpcError). /// /// See this crate's `RpcHandlerDummy` for an implementation example of this trait. /// /// # Panics -/// Your [`RpcHandler`] must reply to [`RpcRequest`]s with the correct -/// [`RpcResponse`] or else this crate will panic during routing functions. +/// Your [`RpcHandler`] must reply to `Request`s with the correct +/// `Response` or else this crate will panic during routing functions. /// -/// For example, upon a [`RpcRequest::Binary`] must be replied with -/// [`RpcRequest::Binary`]. If an [`RpcRequest::Other`] were returned instead, -/// this crate would panic. +/// For example, upon a [`JsonRpcRequest::GetBlockCount`] must be replied with +/// [`JsonRpcResponse::GetBlockCount`]. If anything else is returned, +/// this crate may panic. pub trait RpcHandler: - Clone - + Send - + Sync - + 'static - + Service< - JsonRpcRequest, - Response = JsonRpcResponse, - Error = RpcError, - Future: Future> + Send + Sync + 'static, - > - + Service< - OtherRequest, - Response = OtherResponse, - Error = RpcError, - Future: Future> + Send + Sync + 'static, - > - + Service< - BinRequest, - Response = BinResponse, - Error = RpcError, - Future: Future> + Send + Sync + 'static, - > + RpcService + + RpcService + + RpcService { /// Is this [`RpcHandler`] restricted? /// diff --git a/rpc/interface/src/rpc_handler_dummy.rs b/rpc/interface/src/rpc_handler_dummy.rs index b01106ba..06fa4608 100644 --- a/rpc/interface/src/rpc_handler_dummy.rs +++ b/rpc/interface/src/rpc_handler_dummy.rs @@ -15,10 +15,7 @@ use tower::Service; use cuprate_helper::asynch::InfallibleOneshotReceiver; -use crate::{ - rpc_error::RpcError, rpc_handler::RpcHandler, rpc_request::RpcRequest, - rpc_response::RpcResponse, -}; +use crate::{rpc_error::RpcError, rpc_handler::RpcHandler}; //---------------------------------------------------------------------------------------------------- RpcHandlerDummy /// An [`RpcHandler`] that always returns [`Default::default`]. diff --git a/rpc/interface/src/rpc_service.rs b/rpc/interface/src/rpc_service.rs new file mode 100644 index 00000000..cd250035 --- /dev/null +++ b/rpc/interface/src/rpc_service.rs @@ -0,0 +1,49 @@ +//! RPC [`tower::Service`] trait. + +//---------------------------------------------------------------------------------------------------- Use +use std::future::Future; + +use tower::Service; + +use crate::rpc_error::RpcError; + +//---------------------------------------------------------------------------------------------------- RpcService +/// An RPC [`tower::Service`]. +/// +/// This trait solely exists to encapsulate the traits needed +/// to handle RPC requests and respond with responses - **it is +/// not meant to be used directly.** +/// +/// The `Request` and `Response` are generic and +/// are used in the [`tower::Service`] bounds. +/// +/// The error type is always [`RpcError`]. +/// +/// See [`RpcHandler`](crate::RpcHandler) for more information. +pub trait RpcService: + Clone + + Send + + Sync + + 'static + + Service< + Request, + Response = Response, + Error = RpcError, + Future: Future> + Send + Sync + 'static, + > +{ +} + +impl RpcService for T where + Self: Clone + + Send + + Sync + + 'static + + Service< + Request, + Response = Response, + Error = RpcError, + Future: Future> + Send + Sync + 'static, + > +{ +}