@therms/rpc-server

@therms/rpc-server

A Remote Procedure Call framework for Javascript Node.js written in TS.

• JS/TS client (https://bitbucket.org/thermsio/rpc-client-ts)
• Android/Kotlin client (https://bitbucket.org/thermsio/rpc-client-kotlin)
• iOS/Swift client (https://bitbucket.org/thermsio/rpc-client-swift)

The goals of this RPC framework:

Done:

✅ Provide a simple endpoint for clients to make RPC calls

✅ Provide a simple distributed server network of RPC handlers with minimal configuration

✅ Provide clients the ability to connect via WebSocket

Todo:

❌ Provide clients with the ability to subscribe to back-end pushed updates for Procedures (over WebSocket)

❌ Provide debugging & telemetry on all server info, statistics, status and processes via endpoint

❌ Provide automatic RPC handler API docs for client developers (via telemetry data)

❌ Can optionally serve a telemetry client (html site)

npm i @therms/rpc-server

Gateway Server (Node.js)

A "gateway server" is an entry-point server. In a distributed cluster of RPC servers, gateway servers are used to provide a transport, HTTP or WebSocket, for clients (ie: browser, mobile app) to make RPC calls.

HTTP

A basic server that responds on HTTP to requests:

const { CallResponse, CallRequest, RPCServer } = require('@therms/rpc-server');

const server = new RPCServer({
  displayName: 'rpc-gateway-1',
  gatewayServer: {
    http: { bind: 'localhost', port: 9876 },
  },
});

server.registerHandler({ procedure: 'login' }, async (request) => {
  if (
    request.args.email === '[e-mail]' &&
    request.args.password === 'secret'
  ) {
    return new CallResponse({
      code: 200,
      data: { user: { name: 'Test' } },
      success: true,
    }, request);
  } else {
    return new CallResponse({
      code: 403,
      message: 'Auth failed',
      success: false,
    }, request);
  }
});

server.start();

The RPC gateway server will now be available for RPC clients to make HTTP requests at:

POST http://localhost:9876/ body = { procedure: 'test' }

WebSocket

RPC clients can also connect to a RPC gateway server via WebSocket:

const server = new RPCServer({
  displayName: 'rpc-gateway-1',
  gatewayServer: {
    websocket: { bind: 'localhost', port: 9876 },
  },
});

Note: Http & WebSocket servers cannot share the same port since the HttpServer in this framework uses Http2 by default. WebSocket's aren't easily supported over Http2, at this time.

Handler Server

A handler server is used in a distributed configuration to provide procedure handlers to handle a specific RPC. Handler servers sit usually behind the firewall and their only communication method with other servers is via message broker. Our example uses RabbitMQ as the message broker.

Note: If a gateway server is running and you expect the gateway server to manage calls to a handler server then the gateway server must be provided with messageBroker.amqpURI string so it can connect to the same message broker to communicate with the handler servers.

const { CallResponse, RPCServer } = require('@therms/rpc-server')

const server = new RPCServer({
  displayName: 'rpc-handler-1',
  messageBroker: {
    amqpURI: 'http://my-rabbit-mq-host.com'
  }
});

server.registerHandler({ procedure: 'get-some-data', scope: 'some-specific-scope' }, async (request) => {
    const data = [...] // do some data fetching...

    return new CallResponse({
      code: 200,
      data,
      success: true,
    }, request);
});

Debug Logs

This project uses the npm debug package. Set your env VAR to check debug logs:

export DUBUG=rpc:*

or DUBUG=rpc:* nodemon server.js