nitowa 2915a19af4 generated from tag 2.4.2		1 year ago
classes	generated from tag 2.4.0	2 years ago
interfaces	generated from tag 2.3.1	2 years ago
LICENSE.md	generated from tag 1.4.5	3 years ago
README.md	generated from tag 2.4.2	1 year ago
globals.md	generated from tag 2.4.2	1 year ago

Overview

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 => {
    
})

Version

2.4.2

Classes

Interfaces

Socket

Type aliases

Variables

Functions

Object literals

Type aliases

AccessFilter

Ƭ AccessFilter: function

Type declaration:

▸ (sesame: string | undefined, exporter: I.RPCExporter‹InterfaceT, keyof InterfaceT›): Promise‹boolean› | boolean

Parameters:

Name	Type
`sesame`	string \| undefined
`exporter`	I.RPCExporter‹InterfaceT, keyof InterfaceT›

AnyFunction

Ƭ AnyFunction: function

Type declaration:

▸ (…args: any): any

Parameters:

Name	Type
`...args`	any

AsyncAnyFunction

Ƭ AsyncAnyFunction: AsyncAnyFunction

AsyncIfc

Ƭ AsyncIfc: object

Type declaration:

BaseInfo

Ƭ BaseInfo: object

Type declaration:

argNames: string[]
name: string
owner: string

CallInfo

Ƭ CallInfo: BaseInfo & object

CallRPC

Ƭ CallRPC: object

Type declaration:

call: Func
name: Name

ClientConfig

Ƭ ClientConfig: ConnectOpts & object

CloseHandler

Ƭ CloseHandler: function

Type declaration:

▸ (socket: Socket): void

Parameters:

Name	Type
`socket`	Socket

ConnectedSocket

Ƭ ConnectedSocket: RPCSocket & AsyncIfc‹T›

ConnectionHandler

Ƭ ConnectionHandler: function

Type declaration:

▸ (socket: Socket): void

Parameters:

Name	Type
`socket`	Socket

ErrorHandler

Ƭ ErrorHandler: function

Type declaration:

▸ (socket: Socket, error: any, rpcName: string, args: any[]): void

Parameters:

Name	Type
`socket`	Socket
`error`	any
`rpcName`	string
`args`	any[]

ErrorResponse

Ƭ ErrorResponse: Respose‹T› & object

ExporterArray

Ƭ ExporterArray: I.RPCExporter‹RPCInterface‹InterfaceT›, keyof InterfaceT›[]

ExtendedRpcInfo

Ƭ ExtendedRpcInfo: RpcInfo & object

FrontEndHandlerType

Ƭ FrontEndHandlerType: object

Type declaration:

close(): function
- (): void
error(): function
- (e: any): void

HookCloseFunction

Ƭ HookCloseFunction: function

Type declaration:

▸ (res: T, rpc: HookRPC‹any, any›): any

Parameters:

Name	Type
`res`	T
`rpc`	HookRPC‹any, any›

HookFunction

Ƭ HookFunction: AnyFunction

HookInfo

Ƭ HookInfo: BaseInfo & object

HookRPC

Ƭ HookRPC: object

Type declaration:

hook: Func
name: Name
onCallback? : AnyFunction
onDestroy? : HookCloseFunction‹ReturnType extends Promise ? T : ReturnType›

OnFunction

Ƭ OnFunction: function

Type declaration:

▸ <T>(type: T, f: FrontEndHandlerType[T]): void

Type parameters:

▪ T: “error” | “close”

Parameters:

Name	Type
`type`	T
`f`	FrontEndHandlerType[T]

Outcome

Ƭ Outcome: “Success” | “Error”

PioBindListener

Ƭ PioBindListener: function

Type declaration:

▸ (…args: any): void

Parameters:

Name	Type
`...args`	any

PioHookListener

Ƭ PioHookListener: AnyFunction

RPC

Ƭ RPC: HookRPC‹Name, Func› | CallRPC‹Name, Func› | Func

RPCDefinitions

Ƭ RPCDefinitions: object

Type declaration:

RPCExporter

Ƭ RPCExporter: object

Type declaration:

RPCs: RPCDefinitions[Name] | function
name: Name

RPCInterface

Ƭ RPCInterface: object & Impl

RPCType

Ƭ RPCType: “Hook” | “Unhook” | “Call”

ResponseType

Ƭ ResponseType: “Subscribe” | “Success” | “Error”

Respose

Ƭ Respose: T & object

RpcInfo

Ƭ RpcInfo: HookInfo | CallInfo

ServerConf

Ƭ ServerConf: object & SesameConf

SesameConf

Ƭ SesameConf: object

Type declaration:

sesame? : string | SesameFunction

SesameFunction

Ƭ SesameFunction: function

Type declaration:

▸ (sesame: string): boolean

Parameters:

Name	Type
`sesame`	string

SuccessResponse

Ƭ SuccessResponse: Respose‹T› & object

Visibility

Ƭ Visibility: “127.0.0.1” | “0.0.0.0”

exportT

Ƭ exportT: object

Type declaration:

Variables

`Const` BAD_CONFIG_PARAM

• BAD_CONFIG_PARAM: “RPCServer options were passed to listen(..) after attach(..) was called. Please pass them to attach(..) instead. Ignoring.” = “RPCServer options were passed to listen(..) after attach(..) was called. Please pass them to attach(..) instead. Ignoring.”

`Const` SOCKET_NOT_CONNECTED

• SOCKET_NOT_CONNECTED: “The socket is not connected! Use socket.connect() first” = “The socket is not connected! Use socket.connect() first”

`Const` UNKNOWN_RPC_IDENTIFIER

• UNKNOWN_RPC_IDENTIFIER: ”$UNKNOWNRPC$” = “$UNKNOWNRPC$”

Functions

`Const` CALL_NOT_FOUND

▸ CALL_NOT_FOUND(callName: any): string

Parameters:

Name	Type
`callName`	any

Returns: string

`Const` RPC_BAD_TYPE

▸ RPC_BAD_TYPE(type: any): string

Parameters:

Name	Type
`type`	any

Returns: string

`Const` RPC_NO_NAME

▸ RPC_NO_NAME(name: any): string

Parameters:

Name	Type
`name`	any

Returns: string

`Const` UNKNOWN_RPC_SERVER

▸ UNKNOWN_RPC_SERVER(name: any): string

Parameters:

Name	Type
`name`	any

Returns: string

`Const` USER_DEFINED_TIMEOUT

▸ USER_DEFINED_TIMEOUT(ms: any): string

Parameters:

Name	Type
`ms`	any

Returns: string

appendComma

▸ appendComma(s?: undefined | string, turnToString: boolean): string

Parameters:

Name	Type	Default
`s?`	undefined \| string	-
`turnToString`	boolean	true

Returns: string

`Const` callGenerator

▸ callGenerator(rpcName: string, $__socket__$ : Socket, rpcFunction: T.AnyFunction, errorHandler: T.ErrorHandler): T.AnyFunction

Parameters:

Name	Type	Description
`rpcName`	string	-
$__socket__$	Socket	-
`rpcFunction`	T.AnyFunction	the function to decorate
`errorHandler`	T.ErrorHandler	-

Returns: T.AnyFunction

`Const` extractArgs

▸ extractArgs(f: Function): string[]

Parameters:

Name	Type	Description
`f`	Function	The source function

Returns: string[]

fixNames

▸ fixNames(o: Object): void

Parameters:

Name	Type
`o`	Object

Returns: void

`Const` hookGenerator

▸ hookGenerator(rpc: T.HookRPC‹any, any›, errorHandler: T.ErrorHandler, sesameFn?: T.SesameFunction, injectSocket?: undefined | false | true): function

Parameters:

Name	Type	Description
`rpc`	T.HookRPC‹any, any›	The RPC to transform
`errorHandler`	T.ErrorHandler	-
`sesameFn?`	T.SesameFunction	-
`injectSocket?`	undefined \| false \| true	-

Returns: function

A HookFunction

▸ (socket?: I.Socket): function

Parameters:

Name	Type
`socket?`	I.Socket

▸ (…args: any[]): SubresT

Parameters:

Name	Type
`...args`	any[]

`Const` isError

▸ isError(e: any): boolean

Parameters:

Name	Type
`e`	any

Returns: boolean

`Const` makeError

▸ makeError(callName: string): Error

Parameters:

Name	Type
`callName`	string

Returns: Error

`Const` makePioSocket

▸ makePioSocket(socket: any): Socket

Parameters:

Name	Type	Description
`socket`	any	A socket.io socket

Returns: Socket

makeSesameFunction

▸ makeSesameFunction(sesame: T.SesameFunction | string): T.SesameFunction

Parameters:

Name	Type
`sesame`	T.SesameFunction \| string

Returns: T.SesameFunction

rpcHooker

▸ rpcHooker(socket: Socket, exporter: I.RPCExporter‹any, any›, errorHandler: T.ErrorHandler, sesame?: T.SesameFunction, makeUnique: boolean): T.ExtendedRpcInfo[]

Parameters:

Name	Type	Default	Description
`socket`	Socket	-	The websocket (implementation: socket.io) to hook on
`exporter`	I.RPCExporter‹any, any›	-	The exporter
`errorHandler`	T.ErrorHandler	-	-
`sesame?`	T.SesameFunction	-	-
`makeUnique`	boolean	true	@default true Attach a suffix to RPC names

Returns: T.ExtendedRpcInfo[]

`Const` rpcToRpcinfo

▸ rpcToRpcinfo(socket: Socket, rpc: T.RPC‹any, any›, owner: string, errorHandler: T.ErrorHandler, sesame?: T.SesameFunction): T.RpcInfo

Parameters:

Name	Type	Description
`socket`	Socket	-
`rpc`	T.RPC‹any, any›	The RPC to transform
`owner`	string	The owning RPC group’s name
`errorHandler`	T.ErrorHandler	The error handler to invoke when something goes wrong
`sesame?`	T.SesameFunction	optional sesame phrase to prepend before all RPC arguments

Returns: T.RpcInfo

stripAfterEquals

▸ stripAfterEquals(str: string): string

Parameters:

Name	Type	Description
`str`	string	The parameter to modify

Returns: string

Object literals

`Const` defaultClientConfig

▪ defaultClientConfig: object

callTimeoutMs

• callTimeoutMs: number = 0

protocol

• protocol: “http” = “http”

reconnection

• reconnection: false = false

reconnectionAttempts

• reconnectionAttempts: number = 2

reconnectionDelay

• reconnectionDelay: number = 200

timeout

• timeout: number = 450

`Const` defaultConfig

▪ defaultConfig: object

cookie

• cookie: false = false

path

• path: string = “/socket.io”

README.md

Overview

How to install

Quickstart (TL;DR)

Working with http.Server and express

Async and Callbacks?

Hooks and Events

Restricting access

Typescript support

A class-based pattern for modular APIs

Version

Classes

Interfaces

Type aliases

Variables

Functions

Object literals

Type aliases

AccessFilter

Type declaration:

AnyFunction

Type declaration:

AsyncAnyFunction

AsyncIfc

Type declaration:

BaseInfo

Type declaration:

CallInfo

CallRPC

Type declaration:

ClientConfig

CloseHandler

Type declaration:

ConnectedSocket

ConnectionHandler

Type declaration:

ErrorHandler

Type declaration:

ErrorResponse

ExporterArray

ExtendedRpcInfo

FrontEndHandlerType

Type declaration:

HookCloseFunction

Type declaration:

HookFunction

HookInfo

HookRPC

Type declaration:

OnFunction

Type declaration:

Outcome

PioBindListener

Type declaration:

PioHookListener

RPC

RPCDefinitions

Type declaration:

RPCExporter

Type declaration:

RPCInterface

RPCType

ResponseType

Respose

RpcInfo

ServerConf

SesameConf

Type declaration:

SesameFunction

Type declaration:

SuccessResponse

Visibility

exportT

Type declaration:

Variables

Const BAD_CONFIG_PARAM

Const SOCKET_NOT_CONNECTED

Const UNKNOWN_RPC_IDENTIFIER

Functions

Const CALL_NOT_FOUND

`Const` BAD_CONFIG_PARAM

`Const` SOCKET_NOT_CONNECTED

`Const` UNKNOWN_RPC_IDENTIFIER

`Const` CALL_NOT_FOUND

`Const` RPC_BAD_TYPE

`Const` RPC_NO_NAME

`Const` UNKNOWN_RPC_SERVER

`Const` USER_DEFINED_TIMEOUT

`Const` callGenerator

`Const` extractArgs

`Const` hookGenerator

`Const` isError

`Const` makeError

`Const` makePioSocket

`Const` rpcToRpcinfo

`Const` defaultClientConfig

`Const` defaultConfig