jsonrpc2-ws

A simple implementation of JSON-RPC 2.0 over WebSocket for Node.js

Install

1npm i @c10k/jsonrpc2-ws

Usage

Server

JsonRpcWsServer constructor params same as WebSocketServer.

1const port = 8080;
2const server = new JsonRpcWsServer({port});
3
4const sleep = async (ms) => new Promise(resolve => setTimeout(resolve, ms));
5const echo = (params) => params;
6const error = (params) => {
7    throw new Error(`${params[0]}`)
8};
9const time = () => Date.now();
10
11server.setMethod('echo', echo);
12server.setMethod('sleep', sleep);
13server.setMethod('error', error);
14server.setMethod('time', time);

Client

JsonRpcWsClient constructor params same as WebSocket.

1const url = `ws://localhost:8080`;
2const client = await JsonRpcWsClient.connect(url);
3
4const timeFromServer = await client.request('time');
5console.info(`${timeFromServer}`);

Use case

Stream

1const port = 8080;
2const server = new JsonRpcWsServer({port}, () => {
3    setInterval(async () => {
4        for (const ws of server.wss.clients) {
5            // you can check ws context here
6            server.notification(ws, 'ping', [Date.now]);
7        }
8    }, 1000);
9});

1const url = `ws://localhost:8080`;
2const client = await JsonRpcWsClient.connect(url);
3client.setMethod('ping', (params) => {
4    const [time] = params;
5    console.info(`client receive server time=${time}`);
6});

Batch

1const port = 8080;
2const server = new JsonRpcWsServer({port});
3
4let count = 0;
5server.setMethod('counter', () => ++count);

1const url = `ws://localhost:8080`;
2const client = await JsonRpcWsClient.connect(url);
3
4const pipeline = client.createPipeline();
5await pipeline.request('counter');
6await pipeline.request('counter');
7await pipeline.request('counter');
8const responses = await pipeline.execute();
9for (const response of responses) {
10    const {id, result, error} = response;
11    // do something
12}

Define ID generator

1const url = `ws://localhost:8080`;
2const client = await JsonRpcWsClient.connect(url);
3
4client.idGenerator = () => uuid();

Auth

1const port = 8080;
2const server = new JsonRpcWsServer({port});
3server.handler.getMethod = async ({id, method, params}, socket) => {
4    const auth = await socket.getContext('auth');
5    if (!auth && method.startsWith('private')) {
6        return () => {
7            throw new JsonRpcError(JSON_RPC_ERROR, 'Need auth', undefined);
8        }
9    }
10    return server.handler.methods.get(method);
11};
12
13const login = async (params, socket) => {
14    const [username, password] = params;
15    const auth = password === username;
16    socket.setContext('auth', auth);
17    if (auth) {
18        await socket.setContext('username', username);
19    } else {
20        await socket.deleteContext('username');
21    }
22    return auth;
23};
24
25const whoami = async (params, socket) => {
26    return await socket.getContext('username');
27}
28
29server.setMethod('public.login', login);
30server.setMethod('private.whoami', whoami);

1const url = `ws://localhost:8080`;
2const client = await JsonRpcWsClient.connect(url);
3await client.request('public.login', ['hello', 'hello']);
4await client.request('private.whoami');

Authentication before connection, see https://github.com/websockets/ws/tree/8.6.0#client-authentication, example see authenticate-when-upgrade

Dependencies

• https://github.com/websockets/ws
• https://jestjs.io/zh-Hans/docs/getting-started
• https://jestjs.io/zh-Hans/docs/expect#expectclosetonumber-numdigits
• https://github.com/sindresorhus/get-port

Ref

• https://github.com/jershell/simple-jsonrpc-js/blob/master/simple-jsonrpc-js.js#L230-L275

binary data

1. Binary Data in JSON String. Something better than Base64
   1. https://en.wikipedia.org/wiki/Ascii85
   2. https://github.com/bwaldvogel/base91/blob/main/src/main/java/de/bwaldvogel/base91/Base91.java
   3. https://github.com/kevinAlbs/Base122
2. https://en.wikipedia.org/wiki/Binary-to-text_encoding