Numeric Production Mechanism
    Have ideas to improve npm?Join in the discussion! »

    rpclibrary
    TypeScript icon, indicating that this package has built-in type declarations

    2.4.1 • Public • Published

    Overview

    Build Status Current Version Weekly Downloads License Type

    rpclibrary is a simple to use websocket RPC library.

    How to install

    npm i rpclibrary
    

    Quickstart (TL;DR)

    import {RPCServer, RPCSocket} from 'rpclibrary' 
    
    const echo = (text) => text
    const add = (a, b) => a + b
    const subtract = (a, b) => a - b
    
    new RPCServer([
        {
            name: 'MyRPCGroup1',
            RPCs: [
                echo,
                add,
            ]
        },
            name: 'MyOtherRPCGroup',
            RPCs: [
                subtract
            ]
        }
    ]).listen(20000)
    
    new RPCSocket(20000, 'localhost').connect().then(async sock => {
        try{
            
            await sock['MyRPCGroup1'].echo("hello!").then(console.log)
            const sum = await sock['MyRPCGroup1'].add(1, Math.PI)
            const result = await sock['MyOtherRPCGroup'].subtract(sum, 4)
            
        }catch(e){
            console.log(String(e))
        }
    })

    Working with http.Server and express

    import {RPCServer, RPCSocket} from 'rpclibrary' 
    import {Server as httpServer} from 'http'
    import * as express from 'express'
    
    const app = express()
    //...do express things...
    const httpServer = new http.Server(app)
    
    const rpcServer = new RPCServer([ ... ])
    rpcServer.attach(httpServer)
    rpcServer.listen(8080) //identical to httpServer.listen(8080)

    Async and Callbacks?

    rpclibrary offers full support for callbacks and Promises. Please note that there may only be one callback per RPC and it has to be the last parameter

    const getAsync = async () => await new Promise((res, _) => {
        setTimeout(() => {
            res({
                topic: "Hey!!",
                message: "Hello World Async!"
            })
        }, 250)
    })
    
    const getCallback = (callback) => {
        setTimeout(() => {
            try{
                callback({
                    topic: "Hey!!",
                    message: "Hello World Callback!"
                })
            }catch(e){
                console.log(String(e))
            }
        }, 250)
        return "Please wait for a callback :)"
    }
    
    new RPCServer([{
        name: 'MyRPCGroup1',
        RPCs: [
            getAsync,
            {
                name: 'getCallback',
                hook: getCallback,
            }
        ]
    }]).listen(20000)
    
    new RPCSocket(20000, 'localhost').connect().then(async sock => {
        try{
            const RPCs = sock['MyRPCGroup1']
            await RPCs.getAsync().then(console.log)
            await RPCs.getCallback(console.log).then(console.log)
        }catch(e){
            console.log(String(e))
        }
    })

    Hooks and Events

    There are a many things you can hook into to manage your connections

    new RPCServer([{
        name: 'MyRPCGroup1',
        RPCs: [
            echo,
            {
                name: 'getCallback',
                hook: getCallback,
                onClose: (response, rpc) => { /* client disconnected */ },
                onCallback: (...callbackArgs) => { /* callback triggered */ }
            }
        ],
    }], {
        closeHandler: (socket) => { /* global close handler */ },
        connectionHandler: (socket) => { /* new connection made */ },
        errorHandler: (socket, error, rpcname, argArr) => { /* An error occured inside a RPC */ },
    }).listen(20001)
    
    const sock = new RPCSocket(20001, 'localhost')
    sock.on('error', (e) => { /* handle error */ })
    sock.on('close', () => { /* handle close event */ })
    
    sock.hook('RPCName', (/* arg0, arg1, ..., argN */) => { /* bind client-side RPCs */ }) 
    //Retrieve the socket from connectionHandler (Server-side) and trigger with 
    //socket.call('RPCName', arg0, arg1, ..., argN)
    
    sock.connect().then(_ => { /* ... */})

    Restricting access

    rpclibrary offers some minimalistic permission management in the form of a parameter prefix. The sesame option will decorate all functions with a check for the sesame password. If the wrong string is provided, the RPC will not be executed or respond.

    new RPCServer([ ... ], {
        sesame: "sesame open",
    }).listen(20002)
    
    new RPCSocket(20002, 'localhost').connect("sesame open").then(async sock => {
        /* use normally */
    })
    
    new RPCSocket(20002, 'localhost').connect("WRONG SESAME").then(async sock => {
        const RPCs = sock['MyRPCGroup1'] //undefined
    })

    The permissioning can also be performed dynamically with the accessfilter option and sesame function.

    new RPCServer([ ... ], {
        sesame: (sesame) => checkIfSesameTokenShouldHaveAnyAccess(sesame),
        accessFilter: (sesame, rpcGroupName) => checkIfSesameTokenShouldSeeRPCGroup(sesame, rpcGroupName),
    }).listen(20002)

    Typescript support

    rpclibrary is a typescript-first project and offers full support for typing your RPCs. NOTE that your function implementations and Group Names will usually have to be manually typed to make the compiler infer the correct types.

    First apply types to your functions:

    echo = (x) => x
    /*becomes*/
    echo = (x:string) : string => x
    
    /* A faulty implementation */
    badEcho = (x: boolean) : number => 3

    Next define a type matching the desired Group-to-RPC structure. This kind of type will be called pseudo-interface:

    type MyType = {
        MyRPCGroup1: {
            echo: (x: string) => string
            //...further RPC declarations
        },
        //... further Group declarations
    };

    If MyType is provided as generic parameter to RPCServer, RPCs becomes type-safe. TSC's stack traces may become very long when errors happen in this section. Don't be intimidated by this. The relevant information is usually found at the end in a clear manner.

    new RPCServer<MyType>([{
        name: 'MyRPCGroup1' as 'MyRPCGroup1', //Otherwise the compiler may infer type 'string'
        RPCs: [ badEcho ], //Type '(x: boolean) => number' is not assignable to type '(x: string) => string'
    }]).listen(20003)

    Finally also provide MyType to the client RPCSocket to gain type safety for the socket object.

    new RPCSocket<MyType>(20003, 'localhost').connect().then(async sock => {
        //TSC knows about MyRPCGroup1 and its members 
        await sock.MyRPCGroup1.echo("hello!").then(console.log) 
    })

    A class-based pattern for modular APIs

    Define a regular Interface. This will function as the source of truth for type definitions.

    interface IComponentA {
        echo: (x: string) => string
        add: (a: number, b: number) => number
    }
    
    interface IComponentB {
        getAsync: () => Promise<{ topic: string, message: string }>
        getCallback: (callback:Function) => string
    }

    Create an RPC pseudo-interface type that references the proper interface. This will make sure the types declared by your RPCs are consistent with their implementations.

    type TComponentA = {
        ComponentA: {
            echo: IComponentA['echo']
            add: IComponentA['add']
        }
    }
    
    type TComponentB = {
        ComponentB: {
            getAsync: IComponentB['getAsync']
            getCallback: IComponentB['getCallback']
        }
    }

    Create classes that implement the interfaces you declared alongside RPCExporter<MyType>, where MyType is the RPC pseudo-interface.

    class ComponentA implements IComponentA, RPCExporter<TComponentA> {
        name = "ComponentA" as "ComponentA"
    
        RPCs = [
            this.echo,
            this.add,
        ]
    
        echo = (text: string) => text
        add = (a: number, b: number) : number => a + b
    }
    
    class ComponentB implements IComponentB, RPCExporter<TComponentB> {
        name = "ComponentB" as "ComponentB"
    
        RPCs = [
            this.getAsync,
            {
                name: 'getCallback',
                hook: this.getCallback
            }
        ]
    
        getAsync = async () : Promise<{topic: string, message:string}> => {...}
        getCallback = (callback: Function) : string => {...}
    }

    Finally, merge all RPC pseudo-interfaces into a project-wide one:

    type TProject = TComponentA
                  & TComponentB
    
    new RPCServer<TProject>([new ComponentA(), new ComponentB()]).listen(port)
    
    new RPCSocket<TProject>(port, host).connect().then(async sock => {
        
    })

    Full documentation

    Install

    npm i rpclibrary

    DownloadsWeekly Downloads

    48

    Version

    2.4.1

    License

    MIT

    Unpacked Size

    336 kB

    Total Files

    22

    Last publish

    Collaborators

    • avatar