nitowa ec158e6090 npm version bump(again) | преди 1 година | |
---|---|---|
src | преди 1 година | |
test | преди 1 година | |
.drone.yml | преди 4 години | |
.gitignore | преди 5 години | |
Index.ts | преди 2 години | |
LICENSE.md | преди 5 години | |
README.md | преди 4 години | |
package-lock.json | преди 1 година | |
package.json | преди 1 година | |
tsconfig.json | преди 1 година |
rpclibrary is a simple to use websocket RPC library.
npm i rpclibrary
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))
}
})
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)
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))
}
})
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(_ => { /* ... */})
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)
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)
})
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 => {
})