rpc-broker
v1.0.0-rc.2
Published
RPC-Broker is a transport-layer-agnostic RPC communication library. Additionally to routing RPC calls it supports transmitting [Preact Signals](https://github.com/preactjs/signals) between the clients.
Downloads
4
Readme
RPC-Broker (WIP)
RPC-Broker is a transport-layer-agnostic RPC communication library. Additionally to routing RPC calls it supports transmitting Preact Signals between the clients.
It is built on WebStreams, MessagePack and Zod. It is developed using Deno.js, but also runs in Node.js and Browsers.
Adapters for WebSockets are builtin, but it works over any transport layer that is able to transmit binary data (raw TCP streams, serial/RS232, WebRTC DataChannels, ...). If the transport layer directly supports JS object cloning (e.g worker processes) the binary serialization can be skipped.
Usage
RPC-Broker does not implement the classic client/server concept. It does not distinguish between RPC callers and RPC provider, between signal source and signal sink. The classic RPC provider is just a regular client of the broker server.
If the RPC provider and the broker server run in the same process, RPCServer.client
can be used. It is an
automatically connected RPCClient
, without any intermediary serialization.
The following examples use the simplest API possible, for more detailed information, please refer to the API section.
RPC Client
const client = new WebsocketClient(new RPCClient(), new URL(`ws://example.com/socket`));
For custom transport layers, please refer to the API section
RPC Calls
RPC calls consist of three parts: mod
(to which you can subscribe, equivalent the the HTTP path), sub
(equivalent to
the HTTP method) and (optionally) arg
. mod
and sub
are strings, arg
is any object MessagePack can handle. It is
HIGHLY RECOMMENDED to ALWAYS validate the arg
. When using TypeScript, DO NOT USE the as
operator,
this is UNSAFE. Use FULL type checks. Do this either manually (not recommended) or using a library like
zod (recommended, internally used) or TypeBox
client.subscribe(`my.api`, (sub: string, arg: unknown) => {
// validate and handle the call
});
client.call(`my.api`, "delete", { id: 5 });
RPC Signals
- Use
RPCClient.signal
to obtain aRPCSignal
handle. - Use the
RPCSignal.transmit
method to transmit a signal - Use the
RPCSignal.request
method to start receiving value updates - Access the current value with
RPCSignal.value
- Call
release
when you do not need the signal anymore (saves resources and bandwidth)
It is HIGHLY RECOMMENDED to ALWAYS validate the signal value. When using TypeScript, DO NOT USE the
as
operator, this is UNSAFE. Use FULL type checks. Do this either manually (not recommended) or using a
library like zod (recommended, internally used) or
TypeBox. The Signal can become SIGNAL_INVALID
at any time (no signal
sender, network connection lost, ...)
const mySignal = signal("foo");
client.signal(`my.signal`).transmit(mySignal);
const myReceivedSignal = client.signal(`my.signal`);
const release = myReceivedSignal.request();
effect(() => {
console.log(myReceivedSignal.value);
});
The library provides wrapper functions to easily access signals from Preact Components (React support is underway). These include type checks and data fallbacks.
function MyComponent() {
const value = client.useStringSignal("my.signal", "loading...");
return (
<div>
{value}
</div>
);
}
RPCServer
To build a WebSocket RPCServer, use serve_websocket
from helpers/websocket_server.ts
. If you need more granular
control, use upgrade_websocket
. If you want to use a custom transport layer, refer to the API Section.
API
// TODO
License
Copyright (C) 2024 Hans Schallmoser
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.