@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);
});

Handlers

Call Request "args" Validation

The RPC server will vaidate the CallRequest.args received by client requests. The format is JSON-schema (using the AJV library). Anytime a handler is registered with a JSON-schema object in the args property, that schema will be used to perform validation, example:

const server = new RPCServer({ ... });

const argsJsonSchema = {
    type: 'object',
    properties: {
        location_id: { type: 'string' }
    },
    required: ['location_id'],
    additionalProperties: false
}

server.registerHandler(
    {
        args: argsJsonSchema,
        procedure: 'get-users-for-location', 
        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