Module vibe.web.rpc

Web based, bi-directional, concurrent RPC implementation.

This module implements a generic RPC mechanism that allows transparently calling remote functions over an HTTP based network connection. The current implementation is based on a WebSocket based protocol, serializing method arguments and return types as BSON.

The RPC API is defined using interfaces, very similar to the system in vibe.web.rest. It supports methods with or without a return value, normal, ref and out parameters, exceptions, properties returning interfaces, and properties returning Collection!I.

Authorization and authentication is supported via the vibe.web.auth framework. When using it, the authenticate method should be defined as @noRoute T authenticate(ref const WebRPCPerrInfo), where T is the type passed to the @requiresAuth UDA.

Any remote function calls can execute concurrently, so that the connection never gets blocked by an unfinished function call.

Note that this system will establish a bi-directional communication facility, allowing both, the client and the server, to initiate calls. This effectively forms a peer-to-peer connection instead of a client-server connection. The advantage of using HTTP as the basis is that this makes it easy to establish P2P connections where one of the peers is behind a firewall or NAT layer, but the other peer can be reached through a public port or through a (reverse) proxy server.

Defining a simple RPC interface

The API for the interface is defined as a normal D interface:

interface ExampleAPI {
	void performSomeAction();
	int getSomeInformation();
}

An implementation of this interface is required on both, the server and the client side:

class ExampleAPIImplementation : ExampleAPI {
	void performSomeAction() { ... }
	int getSomeInformation() { return ...; }
}

With this defined, this is the basic code needed to set up the server side:

void handleIncomingPeer(WebRPCPeer!ExampleAPI peer)
@safe nothrow {
	// this gets executed for any client that connects to the server
	try {
		peer.performSomeAction();
	} catch (Exception e) {
		logException(e, "Failed to perform peer action");
	}
}

auto r = new URLRouter;
r.registerWebRPC!ExampleAPI(r, "/rpc", new ExampleAPIImplementation, &handlePeer);
// could register other routes here, such as for a web or REST interface

auto l = listenHTTP("127.0.0.1:1234", r);

A client can now connect to the server and access the API as well:

auto peer = connectWebRPC(URL("http://127.0.0.1:1234/rpc"),
	new ExampleAPIImplementation);

peer.performSomeAction();

Functions

Name	Description
`connectWebRPC(url, implementation)`	Connects to a WebRPC endpoint.
`registerWebRPC(router, path, implementation, peer_callback)`	Registers a route for handling incoming WebRPC requests.

Classes

Name	Description
`WebRPCPeerImpl`

Structs

Name	Description
`WebRPCPeer`	Reference counted type used to access a peer's API.
`WebRPCPeerInfo`	Provides information about a peer;

Aliases

Name	Type	Description
`WebRPCPeerCallback`	`nothrow @safe void delegate(WebRPCPeer!I peer)`

Authors	Sönke Ludwig
Copyright	© 2024 Sönke Ludwig
License	Subject to the terms of the MIT license, as written in the included LICENSE.txt file.