Struct HttpServerBuilder

pub struct HttpServerBuilder<M = ()> { /* private fields */ }

Builder to create JSON-RPC HTTP server.

Implementations

impl Builder

pub fn new() -> Self

Create a default server builder.

impl<M> Builder<M>

pub fn set_middleware<T: Middleware>(self, middleware: T) -> Builder<T>

Add a middleware to the builder Middleware.

use std::{time::Instant, net::SocketAddr};

use jsonrpsee_core::middleware::{HttpMiddleware, Headers, MethodKind, Params};
use jsonrpsee_http_server::HttpServerBuilder;

#[derive(Clone)]
struct MyMiddleware;

impl HttpMiddleware for MyMiddleware {
    type Instant = Instant;

    // Called once the HTTP request is received, it may be a single JSON-RPC call
    // or batch.
    fn on_request(&self, _remote_addr: SocketAddr, _headers: &Headers) -> Instant {
        Instant::now()
    }

    // Called once a single JSON-RPC method call is processed, it may be called multiple times
    // on batches.
    fn on_call(&self, method_name: &str, params: Params, kind: MethodKind) {
        println!("Call to method: '{}' params: {:?}, kind: {}", method_name, params, kind);
    }

    // Called once a single JSON-RPC call is completed, it may be called multiple times
    // on batches.
    fn on_result(&self, method_name: &str, success: bool, started_at: Instant) {
        println!("Call to '{}' took {:?}", method_name, started_at.elapsed());
    }

    // Called the entire JSON-RPC is completed, called on once for both single calls or batches.
    fn on_response(&self, result: &str, started_at: Instant) {
        println!("complete JSON-RPC response: {}, took: {:?}", result, started_at.elapsed());
    }
}

let builder = HttpServerBuilder::new().set_middleware(MyMiddleware);

pub fn max_request_body_size(self, size: u32) -> Self

Sets the maximum size of a request body in bytes (default is 10 MiB).

pub fn max_response_body_size(self, size: u32) -> Self

Sets the maximum size of a response body in bytes (default is 10 MiB).

pub fn set_access_control(self, acl: AccessControl) -> Self

Sets access control settings.

pub fn batch_requests_supported(self, supported: bool) -> Self

Enables or disables support of batch requests. By default, support is enabled.

pub fn register_resource( self, label: &'static str, capacity: u16, default: u16, ) -> Result<Self, Error>

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 resource_limiting for details.

pub fn custom_tokio_runtime(self, rt: Handle) -> Self

Configure a custom tokio::runtime::Handle to run the server on.

Default: tokio::spawn

pub fn health_api( self, path: impl Into<String>, method: impl Into<String>, ) -> Result<Self, Error>

Enable health endpoint. Allows you to expose one of the methods under GET / The method will be invoked with no parameters. Error returned from the method will be converted to status 500 response. Expects a tuple with (, ).

Fails if the path is missing /.

pub fn build_from_hyper( self, listener: Builder<AddrIncoming>, local_addr: SocketAddr, ) -> Result<Server<M>, Error>

Finalizes the configuration of the server with customized TCP settings on the socket and on hyper.

use jsonrpsee_http_server::HttpServerBuilder;
use socket2::{Domain, Socket, Type};
use std::net::TcpListener;

#[tokio::main]
async fn main() {
  let addr = "127.0.0.1:0".parse().unwrap();
  let domain = Domain::for_address(addr);
  let socket = Socket::new(domain, Type::STREAM, None).unwrap();
  socket.set_nonblocking(true).unwrap();

  let address = addr.into();
  socket.bind(&address).unwrap();
  socket.listen(4096).unwrap();

  let listener: TcpListener = socket.into();
  let local_addr = listener.local_addr().ok();

  // hyper does some settings on the provided socket, ensure that nothing breaks our "expected settings".

  let listener = hyper::Server::from_tcp(listener)
    .unwrap()
    .tcp_sleep_on_accept_errors(true)
    .tcp_keepalive(None)
    .tcp_nodelay(true);

  let server = HttpServerBuilder::new().build_from_hyper(listener, addr).unwrap();
}

pub fn build_from_tcp( self, listener: impl Into<StdTcpListener>, ) -> Result<Server<M>, Error>

Finalizes the configuration of the server with customized TCP settings on the socket. Note, that hyper might overwrite some of the TCP settings on the socket if you want full-control of socket settings use Builder::build_from_hyper instead.

use jsonrpsee_http_server::HttpServerBuilder;
use socket2::{Domain, Socket, Type};
use std::time::Duration;

#[tokio::main]
async fn main() {
  let addr = "127.0.0.1:0".parse().unwrap();
  let domain = Domain::for_address(addr);
  let socket = Socket::new(domain, Type::STREAM, None).unwrap();
  socket.set_nonblocking(true).unwrap();

  let address = addr.into();
  socket.bind(&address).unwrap();

  socket.listen(4096).unwrap();

  let server = HttpServerBuilder::new().build_from_tcp(socket).unwrap();
}

pub async fn build(self, addrs: impl ToSocketAddrs) -> Result<Server<M>, Error>

Finalizes the configuration of the server.

#[tokio::main]
async fn main() {
  let listener = std::net::TcpListener::bind("127.0.0.1:0").unwrap();
  let occupied_addr = listener.local_addr().unwrap();
  let addrs: &[std::net::SocketAddr] = &[
      occupied_addr,
      "127.0.0.1:0".parse().unwrap(),
  ];
  assert!(jsonrpsee_http_server::HttpServerBuilder::default().build(occupied_addr).await.is_err());
  assert!(jsonrpsee_http_server::HttpServerBuilder::default().build(addrs).await.is_ok());
}

Trait Implementations

impl<M: Debug> Debug for Builder<M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Builder

fn default() -> Self

Returns the “default value” for a type.