@ch1/rpc-web-socket
    TypeScript icon, indicating that this package has built-in type declarations

    1.2.0 • Public • Published

    CH1 RPC

    CircleCI

    This is not well maintained

    This is not traditional RPC, but it is like it

    Installation

    yarn add @ch1/rpc-web-socket

    Dependencies

    This library has an external optional run time dependency for the server side portion, which leverages the excellent ws library.

    The dependency is optional in that this library will work with anything that satisfies the ws interface:

    export type WsWebSocket = {
      on: (message: string, callback: (data: any) => any) => any;
      send: (data: string) => any;
    };

    We do include ws as a devDependency since we use it for testing the library end to end.

    Usage

    Slightly easier API than in the raw @ch1/rpc

    Client JS Script (using the function foo on the server)

    const ws = new WebSocket('ws://localhost:8080');
    const rpc = wrpc.create({ socket: ws });
     
    rpc.ready.then(() => rpc.remote.foo()).then(result => {
      expect(result).toBe(7);
    });

    Server JS (sharing the function foo to the client)

    const WebSocket = require('ws');
    const wrpc = require('@ch1/rpc-web-socket');
    const wss = new WebSocket.Server({ port: 8080 });
     
    wss.on('connection', ws => {
      wrpc.create(
        { socket: ws },
        {
          foo: () => new Promise(resolve => resolve(7)),
        },
      );
    });

    Error Handling

    Due to the nature of state that could exist on client/server, this library takes the approach of terminating itself in the event of catastrophic failure.

    • Individual functions that fail are left up to the user to handle
    • Connection failures will result in the destruction of the object
    • Pending async requests will have their error handlers triggered

    best practice is to add an error listener:

    const wrpc = require('@ch1/rpc-web-socket');
    const wss = new WebSocket.Server({ port: 8080 });
     
    wss.on('connection', ws => {
      const rpc = wrpc.create(
        { socket: ws },
        {
          foo: () => new Promise(resolve => resolve(7)),
        },
      );
     
      // This is teh relevant bit
      rpc.onDestroy((reason?: string) => {
        // put your error handling logic here.
      });
    });

    Web Socket Connection Handling

    This library attempts to automatically handle all connection errors and fail fast where possible. This includes a server side "ping pong" to detect "unplug" events.

    Reconnection Is Left Up To The User of The Library, onDestroy is your friend

    Presumably the client will be responsible for the reconnection.

    API

    The create function will provide an RPC<RemoteType> object:

    export function create<RemoteType>(
      // required
      config: RPCSocketConfig,
     
      // functions (optionally nested) to provide to other side of the connection
      remote?: Remote<any>,
     
      // not used for now
      remoteDesc?: RemoteDesc,
    ) {

    The RPCSocketConfig object looks like:

    export interface RPCSocketConfig {
      // optionally configure the ping/pong delay the server uses
      // defaults to 10,000ms
      pingDelay?: number;
     
      // *mandatory* the socket to use, either WebSocket in the browser
      // or something _like_ `ws` on the server
      // (we're ws 6.x compatible)
      socket: NativeWebSocket | WsWebSocket;
    }

    The RPC<RemoteType> object is described in the documentation for @ch1/rpc

    License

    LGPL

    Install

    npm i @ch1/rpc-web-socket

    DownloadsWeekly Downloads

    10

    Version

    1.2.0

    License

    LGPL-3.0

    Unpacked Size

    40.7 kB

    Total Files

    24

    Last publish

    Collaborators

    • bennett000