Document resource limiting

http-server/Cargo.toml

@@ -26,3 +26,4 @@ unicase = "2.6.0"
 [dev-dependencies]
 env_logger = "0.9"
 jsonrpsee-test-utils = { path = "../test-utils" }
+jsonrpsee = { path = "../jsonrpsee", features=["full"] }

http-server/src/server.rs

@@ -84,8 +84,11 @@ impl Builder {
 		self
 	}
 
-	/// Register a new resource kind. Errors if `label` is already registered, or if number of
-	/// registered resources would exceed 8.
+	/// Register a new resource kind. Errors if `label` is already registered, or if the number of
+	/// registered resources on this server instance would exceed 8.
+	///
+	/// See the module documentation for [`resurce_limiting`](../jsonrpsee_utils/server/resource_limiting/index.html#resource_limiting)
+	/// for details.
 	pub fn register_resource(mut self, label: &'static str, capacity: u16, default: u16) -> Result<Self, Error> {
 		self.resources.register(label, capacity, default)?;
 

proc-macros/src/attributes.rs

@@ -25,7 +25,7 @@
 // DEALINGS IN THE SOFTWARE.
 
 use proc_macro2::{Span, TokenStream as TokenStream2, TokenTree};
-use std::fmt;
+use std::{fmt, iter};
 use syn::parse::{Parse, ParseStream, Parser};
 use syn::punctuated::Punctuated;
 use syn::{spanned::Spanned, Attribute, Error, Token};
@@ -51,15 +51,14 @@ impl Parse for Argument {
 	fn parse(input: ParseStream) -> syn::Result<Self> {
 		let label = input.parse()?;
 
-		let mut tokens = TokenStream2::new();
 		let mut scope = 0usize;
 
 		// Need to read to till either the end of the stream,
 		// or the nearest comma token that's not contained
 		// inside angle brackets.
-		loop {
+		let tokens = iter::from_fn(move || {
 			if scope == 0 && input.peek(Token![,]) {
-				break;
+				return None;
 			}
 
 			if input.peek(Token![<]) {
@@ -68,11 +67,9 @@ impl Parse for Argument {
 				scope = scope.saturating_sub(1);
 			}
 
-			match input.parse::<TokenTree>() {
-				Ok(token) => tokens.extend([token]),
-				Err(_) => break,
-			}
-		}
+			input.parse::<TokenTree>().ok()
+		})
+		.collect();
 
 		Ok(Argument { label, tokens })
 	}

utils/src/server/mod.rs

@@ -28,7 +28,6 @@
 
 /// Helpers.
 pub mod helpers;
-/// Resource limiting helpers
 pub mod resource_limiting;
 /// JSON-RPC "modules" group sets of methods that belong together and handles method/subscription registration.
 pub mod rpc_module;

utils/src/server/resource_limiting.rs

@@ -1,3 +1,75 @@
+// Copyright 2019-2021 Parity Technologies (UK) Ltd.
+//
+// Permission is hereby granted, free of charge, to any
+// person obtaining a copy of this software and associated
+// documentation files (the "Software"), to deal in the
+// Software without restriction, including without
+// limitation the rights to use, copy, modify, merge,
+// publish, distribute, sublicense, and/or sell copies of
+// the Software, and to permit persons to whom the Software
+// is furnished to do so, subject to the following
+// conditions:
+//
+// The above copyright notice and this permission notice
+// shall be included in all copies or substantial portions
+// of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+// ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+// TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+// SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+// DEALINGS IN THE SOFTWARE.
+
+//! # Resource Limiting
+//!
+//! This module handles limiting the capacity of the server to respond to requests.
+//!
+//! Each method will claim the specified number of units (or the default) for the duration of its execution
+//! Any method execution that would cause the total sum of claimed resource units to exceed
+//! the `capacity` of that resource will be denied execution, immediately returning JSON-RPC error object with code `-32604`.
+//!
+//! Resources can be defined directly using the [`WsServerBuilder::register_resource`](../../../jsonrpsee_ws_server/struct.WsServerBuilder.html#method.register_resource)
+//! or [`HttpServerBuilder::register_resource`](../../../jsonrpsee_ws_server/struct.WsServerBuilder.html#method.register_resource) method.
+//!
+//! To specify a different than default number of units a method should use, use the `resources` argument in the
+//! `#[method]` attribute:
+//!
+//! ```
+//! # use jsonrpsee::{types::RpcResult, proc_macros::rpc};
+//! #
+//! #[rpc(server)]
+//! pub trait Rpc {
+//!     #[method(name = "my_expensive_method", resources("cpu" = 5, "mem" = 2))]
+//!     async fn my_expensive_method(&self) -> RpcResult<&'static str> {
+//! 	    // Do work
+//!         Ok("hello")
+//!     }
+//! }
+//! ```
+//!
+//! Alternatively, you can use the `resource` method when creating a module manually without the help of the macro:
+//!
+//! ```
+//! # use jsonrpsee::{RpcModule, types::RpcResult};
+//! #
+//! # fn main() -> RpcResult<()> {
+//! #
+//!	let mut module = RpcModule::new(());
+//!
+//! module
+//!     .register_async_method("my_expensive_method", |_, _| async move {
+//!         // Do work
+//!         Ok("hello")
+//!     })?
+//!	    .resource("cpu", 5)?
+//!	    .resource("mem", 2)?;
+//! # Ok(())
+//! # }
+
 use std::sync::Arc;
 
 use arrayvec::ArrayVec;

utils/src/server/rpc_module.rs

@@ -254,7 +254,7 @@ impl Methods {
 		Arc::make_mut(&mut self.callbacks)
 	}
 
-	/// Merge two [`Methods`]'s by adding all [`MethodKind`]s from `other` into `self`.
+	/// Merge two [`Methods`]'s by adding all [`MethodCallback`]s from `other` into `self`.
 	/// Fails if any of the methods in `other` is present already.
 	pub fn merge(&mut self, other: impl Into<Methods>) -> Result<(), Error> {
 		let mut other = other.into();

ws-server/Cargo.toml

@@ -24,3 +24,4 @@ tokio-util = { version = "0.6", features = ["compat"] }
 anyhow = "1"
 env_logger = "0.9"
 jsonrpsee-test-utils = { path = "../test-utils" }
+jsonrpsee = { path = "../jsonrpsee", features=["full"] }

ws-server/src/server.rs

@@ -402,11 +402,13 @@ impl Builder {
 		self
 	}
 
-	/// Register a new resource kind. Errors if `label` is already registered, or if number of
-	/// registered resources would exceed 8.
+	/// Register a new resource kind. Errors if `label` is already registered, or if the number of
+	/// registered resources on this server instance would exceed 8.
+	///
+	/// See the module documentation for [`resurce_limiting`](../jsonrpsee_utils/server/resource_limiting/index.html#resource_limiting)
+	/// for details.
 	pub fn register_resource(mut self, label: &'static str, capacity: u16, default: u16) -> Result<Self, Error> {
 		self.resources.register(label, capacity, default)?;
-
 		Ok(self)
 	}