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 === 'test@test.com' &&
    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 are not easily supported over Http2, at this time.

WebSocket Connection Events

Listen when clients connect/disconnect:

const server = new RPCServer({
  displayName: 'rpc-gateway-1',
  
  gatewayServer: {
    websocket: {
      bind: 'localhost',

      onClientConnect: ({ connectionId, identity, ip }) => {},

      onClientDisconnect: ({ connectionId, identity, ip }) => {},

      port: 9876,
    },
  },
})

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

Handler - Making Internal Calls

Registered RPC handlers can make RPC calls to other RPC handlers in the same network. A second param is passed to the request handler to be used as a "client" making a RPC call. These calls are marked as internal so they can access internal only handlers.

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

server.registerHandler(
  {
    internal: true, // this means that this RPC handler can only be accessed from internal calls
    procedure: 'get-all-locations',
    scope: 'internal'
  },
  async (request) => {
    return {
      code: 200,
      data: [...],
      success: true,
    };
  }
);

server.registerHandler(
    {
        procedure: 'get-list-of-locations',
        scope: 'public'
    },
    async (request, call) => {
        const { data } = call({ procedure: 'get-all-locations', scope: 'internal' })

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

Listing for Error Events

You can optionally listen for error events in the server and/or your registered handlers.

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

server.on(RPCServer.events.handler_error, payload => {
  // log to Sentry/Bugsnag/etc.
})

server.on(RPCServer.events.rpc_server_error, payload => {
  // log to Sentry/Bugsnag/etc.
})

Client Identity

The RPC server accepts an identity property with all RPC calls that contains information about the client's authentication info.

The identity property schema:

{
  authorization: string
  deviceName?: string
  metadata?: { [string]: any }
}

Http Client Requests

All HTTP RPC requests are stateless on the server. The server implementation requires the identity prop to be sent with every RPC call (when the identity information is required for a specific procedure).

WebSocket Connections

WebSocket connections are long-lived and remain open. For this reason, the identity information only needs to be sent once per WebSocket connection. The server will keep the identity information for the client WebSocket connection for as long as the connection remains active. The client connection must re-send the identity information if the WebSocket is disconnected and reconnected.

The client can set the WebSocket connection identity over WebSocket by sending this payload:

{
  identity: {
    authorization: 'some-jwt-string'
  }
}

When the server's WebSocket connection handler receives a message with only the identity property, it will assume the client is setting it's identity and does not expect a valid scope, procedure or version.

After the identity is set by the client for the WebSocket connection, all sebsequent RPC's are not required to send the identity property as long as the connection WebSocket remains alive.

Handlers & Identity

The client's identity for each request is available in the handler, example:

server.registerHandler(
  { procedure: 'do-something-restricted', scope: 'restricted' },
  (request) => {
        const { authorization, deviceName, metadata } = request.identity

        if (!authorization || jwtService.isValid(authorization)) {
            throw new CallResponse({ code: 401, message: 'unauthorized', success: false }, request)
        }

        ...
    }
)

Note: Regarding the Client library implementations (Javascript, Kotlin, Swift) of WebSocket transports -- The lib implementation only needs to send the Identity once, after the WebSocket connects to the remote. The remote will remember the WS identity. If the WS disconnects and reconnects, the client lib must immediately send the identity again.

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

FAQs

What is @therms/rpc-server?

Is @therms/rpc-server popular?

Is @therms/rpc-server well maintained?

Package last updated on 11 Feb 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@therms/rpc-server