OpenRPC Server JS

JSON-RPC 2.0 + OpenRPC Server implementation that supports multiple transport protocols. Built to run with node 10+.

Need help or have a question? Join us on Discord!

Features

• Multiple Transports
  • HTTP
  • HTTPS1/2
  • WebSockets
  • IPC
    • UDP
    • TCP
• Automatically Validate JSON Schemas for ContentDescriptor#schemasMethodObject#params.
• CLI to start a server by configuration

How to Use

install server, and optionally schema-utils-js if you want to dereference/validate the open-rpc document before running.

npm install --save @open-rpc/server-js @open-rpc/schema-utils-js

Write an open-rpc document describing your service ./src/openrpc.json see: https://raw.githubusercontent.com/open-rpc/examples/master/service-descriptions/simple-math-openrpc.json or write your own in playground.

For each of the methods, create a function that has the same name src/method-mapping

import{MethodMapping}from"@open-rpc/server-js/build/router";exportconstmethodMapping: MethodMapping={addition: (a: number,b: number)=>a+b,subtraction: (a: number,b: number)=>a-b};exportdefaultmethodMapping;

Create a server with the methods and the document, serve it over http and websocket src/server.ts

import{Server,ServerOptions}from"@open-rpc/server-js";import{HTTPServerTransportOptions}from"@open-rpc/server-js/build/transports/http";import{WebSocketServerTransportOptions}from"@open-rpc/server-js/build/transports/websocket";import{OpenrpcDocument}from"@open-rpc/meta-schema";import{parseOpenRPCDocument}from"@open-rpc/schema-utils-js";importmethodMappingfrom"./method-mapping";importdocfrom"./openrpc.json";exportasyncfunctionstart(){constserverOptions: ServerOptions={openrpcDocument: awaitparseOpenRPCDocument(docasOpenrpcDocument),transportConfigs: [{type: "HTTPTransport",options: {port: 3330,middleware: [],}asHTTPServerTransportOptions,},{type: "WebSocketTransport",options: {port: 3331,middleware: [],}asWebSocketServerTransportOptions,},],
methodMapping,};console.log("Starting Server");// tslint:disable-lineconsts=newServer(serverOptions);s.start();}

Lower Level Bits

Creating Routers

using method mapping and OpenRPC document

import{types}from"@open-rpc/meta-schema";import{Router}from"@open-rpc/server-js";constopenrpcDocument={openrpc: "1.0.0",info: {title: "node-json-rpc-server example",version: "1.0.0"},methods: [{name: "addition",params: [{name: "a",schema: {type: "integer"}},{name: "b",schema: {type: "integer"}}],result: {{name: "c",schema: {type: "integer"}}}}]}astypes.OpenRPC;constmethodHandlerMapping={addition: (a: number,b: number)=>Promise.resolve(a+b)};constrouter=newRouter(openrpcDocument,methodHandlerMapping);

mock mode

constrouter=newRouter(openrpcDocument,{mockMode: true});

Creating Transports

IPC

import{TCPIPCServerTranport,UDPIPCServerTranport}from"@open-rpc/server-js";constipcOptions={maxConnetions: 20};// https://www.npmjs.com/package/node-ipc#ipc-configconstTCPIPCOptions={ ...ipcOptions,networkPort: 4343};constUDPIPCOptions={ ...ipcOptions,networkPort: 4343,udp: true};consttcpIpcTransport=newIPCServerTranport(TCPIPCTransportOptions);constUdpIpcTransport=newIPCServerTranport(UDPIPCTransportOptions);

HTTP/S

import { HTTPServerTransport, HTTPSServerTransport } from "@open-rpc/server-js";
import express from "express";
const existingApp = express();
const httpOptions = {
middleware: [ cors({ origin: "*" }) ],
port: 4345,
app: existingApp, // optional existing express/connect app
};
const httpsOptions = { // extends https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener
middleware: [ cors({ origin: "*" }) ],
port: 4346,
key: await fs.readFile("test/fixtures/keys/agent2-key.pem"),
cert: await fs.readFile("test/fixtures/keys/agent2-cert.pem"),
ca: fs.readFileSync("ssl/ca.crt")
};
const httpTransport = new HTTPServerTransport(httpOptions);
const httpsTransport = new HTTPSServerTransport(httpsOptions); // Defaults to using HTTP2, allows HTTP1.

WebSockets

import { WebSocketServerTransport } from "@open-rpc/server-js";
const webSocketFromHttpsOptions = { // extends https://github.com/websockets/ws/blob/master/doc/ws.md#new-websocketserveroptions-callback
server: httpsTransport.server
};
const webSocketOptions = { // extends https://github.com/websockets/ws/blob/master/doc/ws.md#new-websocketserveroptions-callback
port: 4347
};
const wsFromHttpsTransport = new WebSocketServerTransport(webSocketFromHttpsOptions); // Accepts http transport as well.
const wsTransport = new WebSocketServerTransport(webSocketOptions); // Accepts http transport as well.

Add components as you go

const server = new Server();
server.start();
server.addTransport(httpsTransport); // will be started immediately
server.setRouter(router);
server.addTransports([ wsTransport, wsFromHttpsTransport, httpsTransport ]); // will be started immediately.

Contributing

How to contribute, build and release are outlined in CONTRIBUTING.md, BUILDING.md and RELEASING.md respectively. Commits in this repository follow the CONVENTIONAL_COMMITS.md specification.