Notorious Preying Mantis

    @open-rpc/server-js
    TypeScript icon, indicating that this package has built-in type declarations

    1.9.3 • Public • Published

    OpenRPC Server JS

    CircleCI branch Dependabot status npm GitHub release GitHub commits since latest release

    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

    • [x] Multiple Transports
      • [x] HTTP
      • [x] HTTPS1/2
      • [x] WebSockets
      • [x] IPC
        • [x] UDP
        • [x] TCP
    • [x] Automatically Validate JSON Schemas for ContentDescriptor#schemas MethodObject#params.
    • [x] 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";
    export const methodMapping: MethodMapping = {
      addition: (a: number, b: number) => a + b,
      subtraction: (a: number, b: number) => a - b
    };
    export default methodMapping;

    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";
    import methodMapping from "./method-mapping";
    import doc from "./openrpc.json";
    
    export async function start() {
      const serverOptions: ServerOptions = {
        openrpcDocument: await parseOpenRPCDocument(doc as OpenrpcDocument),
        transportConfigs: [
          {
            type: "HTTPTransport",
            options: {
              port: 3330,
              middleware: [],
            } as HTTPServerTransportOptions,
          },
          {
            type: "WebSocketTransport",
            options: {
              port: 3331,
              middleware: [],
            } as WebSocketServerTransportOptions,
          },
        ],
        methodMapping,
      };
    
      console.log("Starting Server"); // tslint:disable-line
      const s = new Server(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";
    
    const openrpcDocument = {
      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" } }
          }
        }
      ]
    } as types.OpenRPC;
    
    const methodHandlerMapping = {
      addition: (a: number, b: number) => Promise.resolve(a + b)
    };
    
    const router = new Router(openrpcDocument, methodHandlerMapping);
    mock mode
    const router = new Router(openrpcDocument, { mockMode: true });
    Creating Transports
    IPC
    import { TCPIPCServerTranport, UDPIPCServerTranport } from "@open-rpc/server-js";
    
    const ipcOptions = { maxConnetions: 20 }; // https://www.npmjs.com/package/node-ipc#ipc-config
    const TCPIPCOptions = { ...ipcOptions, networkPort: 4343 };
    const UDPIPCOptions = { ...ipcOptions, networkPort: 4343, udp: true };
    
    const tcpIpcTransport = new IPCServerTranport(TCPIPCTransportOptions);
    const UdpIpcTransport = new IPCServerTranport(UDPIPCTransportOptions);
    HTTP/S
    import { HTTPServerTransport, HTTPSServerTransport } from "@open-rpc/server-js";
    
    const httpOptions = {
      middleware: [ cors({ origin: "*" }) ],
      port: 4345
    };
    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.

    Keywords

    none

    Install

    npm i @open-rpc/server-js

    DownloadsWeekly Downloads

    1,711

    Version

    1.9.3

    License

    Apache-2.0

    Unpacked Size

    44.6 kB

    Total Files

    24

    Last publish

    Collaborators

    • belfordz
    • shanejonas