Provides a struture for hosting RPC style APIs, supports both http and websocket access out of the box
Provides a structure for hosting RPC style APIs, supports both http and websocket access out of the box.
RPCAPI is designed to be used within a node.js server, generally alongside the client application (rpcapi-websocket-client) running in the web browser.
The server can then easily define 'endpoints' which are classes containing a collection of associated 'actions' These actions are simple javascript functions, which take parameters and return a value. Actions can then be called remotely, either using a websocket and the client SDK or via a web api.
Designed to solve the problem of constantly building project structures around socket.io to manage many endpoints as well as providing a much nicer way to communicate with the server (RPC instead of messaging).
Traditional socket.io code looks like this
socket.emit('userService.authenticateUser', email, password);
socket.on('userService.authenticateUser', function(err, isAuthenticated) {
if (err) { throw err; }
if (isAuthenticated) {
console.log('Yay we are authenticated');
} else {
console.log('Authentication failed :(');
}
});
If we want to handle connection dropouts, timeouts, invalid arguments, unexpected internal server errors etc, this code gets much larger.
Out of the box, RPC API provides a much neater syntax
const isAuthenticated = await userService.callAction('authenticateUser', { email, password });
if (isAuthenticated) {
console.log('Yay we are authenticated');
} else {
console.log('Authentication failed :(');
}
Timeouts, invalid arguments and server errors are all automatically handled.
This application is most useful with both RPCAPI on the server and RPCAPI-websocket-client on the client. This allows a client application to easily call endpoint actions.
To install:
npm install --save rpcapi
or using yarn
yarn add rpcapi
The best way to get started is to take a look at the examples directory, which includes a basic project with a few different endpoints designed to show how to create and register endpoints and actions.
There is also a client example application which demonstrates how to use rpcapi-websocket-client. This client expects the server example to be running.
To start the server navigate to examples/server then run npm start
This will start a local server on port 8080
To view an example endpoint via the webapi navigate to http://localhost:8081/api/calculator/add?a=1&b=2 in a web browser.
To start the client, open a new terminal window and navigate to examples/websocketClient and run npm start
The client will be served on port 8081 and can be viewed in a web browser.
The easiest way to start a server is to use the built in api.listen() method.
This will set up a web server and websocket server on the given port and respond to api requests.
const rpcapi = require('rpcapi');
//Create our API instance
//This is what will be given to our access methods, we will register all our endpoints against this object
const api = new rpcapi.API();
//Register your endpoint classes here
//api.registerEndpoint('test', TestEndpoint);
//server listen
api.listen(8081).then(() => {
console.log('Example API Server listening on port 8081');
});
If you want to manually manage your server, have a look at the advanced topic Manage express and socketio manually
Endpoints are defined as classes, extending rpcapi.APIEndpoint
Endpoints contain actions, which can be remotely called. Actions can define, which are passed to them when they are called
class ExampleEndpoint extends rpcapi.APIEndpoint {
constructor() {
super();
$sayHelloParams = { name: 'string' };
}
connect() {
//Runs when a client connects
}
disconnect() {
//Runs when a client disconnects
}
$sayHello({ name }) {
return {
greeting: `Hello ${name}!`
};
}
}
api.registerEndpoint('example', ExampleEndpoint);
Endpoint classes must be registered to the api. You can register many endpoints, but they must all have different names
api.registerEndpoint('example', ExampleEndpoint);
Lifecycle hooks fire when an endpoint is connected and disconnected. These functions can be used to subscribe to events that the client might be interested in (for example a redis pub/sub service) or setting timers. It is important to clean up and listeners and timers on disconnect to avoid wasting server time after a client has left. An error will be thrown if .emit() is called after disconnect.
class EmitterEndpoint extends rpcapi.APIEndpoint {
connect() {
//Runs when a client connects
this.emitTimer = setInterval(() => {
this.emit('randomNumber', Math.random());
});
}
disconnect() {
//Runs when a client disconnects
clearTimeout(this.emitTimer);
}
}
Actions are just functions on an endpoint class.
class ExampleEndpoint extends rpcapi.APIEndpoint {
$sayHello() {
return {
greeting: 'Hi!'
};
}
}
Action parameter objects are written in the format
$sayHelloParams = { name: 'string' }
When using javascript, these must be defined in the constructor of the class
class ExampleEndpoint extends rpcapi.APIEndpoint {
constructor() {
super();
$sayHelloParams = { name: 'string' };
}
$sayHello({ name }) {
return {
greeting: `Hello ${name}!`
};
}
}
If you are using typescript, these can be defined throughout the body of the class, which makes it easier to keep the params definition with the action function
class ExampleEndpoint extends rpcapi.APIEndpoint {
$sayHelloParams = { name: 'string' };
$sayHello({ name }: { name: string }) {
return {
greeting: `Hello ${name}!`
};
}
}
See further down for more details. There are 2 important functions to use when pushing data to the client
this.canEmit() - Boolean, returns true if the current connection method supports pushing, this.emit() will crash if called when this is false
this.emit(eventName, arg1, arg2, etc...) - Send an event to the client
See implementation details below at Pushing to the client (implementation)
By default the WebAPIAccessMethod binds to the path /api
This can be changed by passing in the prefix configuration parameter.
All actions must be called using the 'post' http method. parameters can either be given as json or in a url encoded format
const webApi = new rpcapi.WebAPIAccessMethod(api, { prefix: '/myApi' });
Once the server is running, you can access actions directly by requesting the url
/api/{endpoint name}/{action name}
param1={value1}¶m2={value2}
For example, an authentication action
/api/login/authenticateUser
username=admin&password=Qwerty1
When using the web api, values are automatically converted to the correct type (as specified in ${action}Params)
Types are checked and the endpoint will return an error if the parameters are not given correctly.
If an action requires an object or array for a parameter, you can use JSON to provide this value For example
/api/calculator/sumAll
values=[1, 2, 3, 4]
Because the web api does not involve a persistent connection, endpoints behave slightly differently to using the websocket client Anytime an action is called, a new instance of the appropriate action is created, and then destroyed when the request is complete. This means that every api call is executed in its own instance of the endpoint.
Another limitation is pushing data to the client, because http is not bidirectional the server cannot push data to the client in the background.
It is possible to check if the current connection supports pushing to the client using this.canEmit() within the endpoint.
See the PushToClientEndpoint.js file in the examples for reference.
The websocket client is the easiest way to call actions on the server from a web browser. There is an example of the websocket client in the examples directory, but the basic structure is straightforward.
const rpcapiClient = require('rpcapi-websocket-client');
const api = new rpcapiClient.APIClient('http://localhost:8081/');
api.connect()
.then(doMaths)
.catch(console.error);
async function doMaths() {
const calculatorEndpoint = await api.connectToEndpoint('calculator');
//Call a remote method on the CalculatorEndpoint instance
const addResult = await calculatorEndpoint.callAction('add', { a: 1, b: 2 });
console.log('1 + 2 =', addResult.value);
//Call another method on the same instance
const multiplyResult = await calculatorEndpoint.callAction('multiply', { a: 5, b: 4 });
console.log('5 * 4 =', multiplyResult.value);
calculatorEndpoint.disconnect();
}
It is important to note that when you call api.connectToEndpoint('calculator') you are creating a new instance of the CalculatorEndpoint on the server.
This is beneficial as this class instance can keep state across many action calls
For example
const adderEndpoint = await api.connectToEndpoint('adder');
console.log(await adderEndpoint.callAction('getValue')); //0
adderEndpoint.callAction('add', { number: 1 });
console.log(await adderEndpoint.callAction('getValue')); //1
adderEndpoint.callAction('add', { number: 5 });
console.log(await adderEndpoint.callAction('getValue')); //6
These instances are individual to each client, you can even create many instances/connections from the same client. For example
//Create 2 adder connections
const adder1Endpoint = await api.connectToEndpoint('adder');
const adder2Endpoint = await api.connectToEndpoint('adder');
console.log(await adder1Endpoint.callAction('getValue')); //0
console.log(await adder2Endpoint.callAction('getValue')); //0
adder1Endpoint.callAction('add', { number: 14 });
adder2Endpoint.callAction('add', { number: 2 });
console.log(await adder1Endpoint.callAction('getValue')); //14
console.log(await adder2Endpoint.callAction('getValue')); //2
One of the biggest advantages of sockets is the ability to push data from the server to the client without the client explicitly asking for data. This is possible using the websocket client.
Pushing data to the client requires a websocket conenction, it will not work over a webapi connection.
To ensure the current connection method supports pushing/emitting, call this.canEmit()
class PushToClientEndpoint extends rpcapi.APIEndpoint {
//Cleanup when the client disconnects
disconnect() {
clearTimeout(this.pushTimer);
}
$startPushing() {
if (!this.canEmit()) {
return { result: 'Cannot push, the connected method does not support pushing' };
}
clearTimeout(this.pushTimer);
this.pushTimer = setInterval(() => {
this.emit('time', Date.now()); //Will push to the client, the client can listen via apiEndpoint.on('time', cb);
}, 1000);
return { result: 'Pushing the current time every second (event: time)' };
}
}
const pushToClientEndpoint = api.connectToEndpoint('pushToClient');
//Register code to run when the server sends us a 'time' event
pushToClientEndpoint.on('time', (currentTime) => {
console.log('The server says the time is', currentTime);
});
//Call the startPushing action to request the server pushes the time to us every second
await pushToClientEndpoint.callAction('startPushing');
When connecting to an endpoint, you can optionally provide an accessKey, this is available to the endpoint class via this.accessKey
From the api endpoint on the class, throw AccessDeniedError to reject a request.
Generally this will be done after doing a lookup on the accessKey (this.accessKey) to determine whether the user has access to the requested resource.
AccessDeniedError can be thrown from connect() to prevent the connection being completed. It can also be thrown from a specific action.
Access keys are simply passed as url parameters eg.
http://localhost:8081/api/calculator/add?accessKey=qwer2134&a=1&b=2
When connecting to an endpoint, pass the access key as the second parameter to .connectToEndpoint()
const ep = await apiClient.connectToEndpoint('test', 'myAccessKey');
It is also possible to set a default access key at a connection level.
This is useful when using access keys to identify a user, the default access key can be set after they login and from then on all requests will be authenticated. (NOTE: Existing connections will remain unchanged)
apiClient.accessKey = 'myAccessKey';
const ep = await apiClient.connectToEndpoint('test');
By default, RPCAPI will register its own express app and socket io server on the port given when you call api.listen()
However, sometimes control is required over these services.
For example when,
The webapi access method is designed to be run with an express webserver, the websocket access method is designed to be run with a socket io instance.
These services need to be configured in order to provide access into your api endpoints.
const rpcapi = require('rpcapi');
const http = require('http');
const express = require('express');
const socketio = require('socket.io');
//Setup express web server
const app = express();
const server = new http.Server(app);
const io = socketio(server);
//Create our API instance
//This is what will be given to our access methods, we will register all our endpoints against this object
const api = new rpcapi.API();
//Setup websocket access method
const socketApi = new rpcapi.WebSocketAccessMethod(api);
socketApi.bind(io); //Bind socket access method to socket.io instance
//Setup webapi access method
const webApi = new rpcapi.WebAPIAccessMethod(api);
webApi.bind(app); //Bind webapi access method to express web server
//server listen
server.listen(8081, () => {
console.log('Example API Server listening on port 8081');
});
On the client it can be difficult to test modules that directly communicate with the server.
RPCAPI-websocket-client provides ready to go mocking classes for both
These classes do not establish any connection with the server, they simply simulate a predefined api structure for testing
const mockAPIClient = new MockAPIClient({
endpoints: {
testEndpoint: {
actions: {
testAction: () => {
return { someValue: 123 };
}
}
}
}
});
await mockAPIClient.connect();
const mockEP = await mockAPIClient.connectToEndpoint('testEndpoint');
const response = await mockEP.callAction('testAction');
console.log(response); // { someValue: 123 }
MockAPIEndpointClient is very similar to MockAPIClient, however it only mocks a single endpoint, and does not require 'connecting' (it simulates a single connected endpoint)
const mockAPIEndpointClient = new MockAPIEndpointClient({
actions: {
testAction: () => {
return { a: 1 };
},
otherAction: () => {
return { a: 2 };
}
}
});
const result1 = await mockAPIEndpointClient.callAction('testAction');
console.log(result1); //{ a: 1 }
const result2 = await mockAPIEndpointClient.callAction('otherAction');
console.log(result2); //{ a: 2 }
Access methods are nothing special, they are just a module that takes in an API instance. They can create new endpoint instances by calling api.getEndpoint(endpointName) to get an APIEndpoint instance
On this instance you can then call:
actionExists(actionName) - Boolean, if action existsactionParams(actionName) - Object, keyed list of parameters and their typesconnect() - Call this when the client is connected to this endpoint (generally immediately after creation). Only call this if the connection is long liveddisconnect() - Call when the client disconnects / the endpoint is not required anymore. Only call this if the connection is long livedregisterEmitHandler(handlerFunc) - Provide a function that will be called if the endpoint calls this.emit(), once you have provided a function this.canEmit() will return truecallAction(actionName, args) - Call an action by nameFAQs
Provides a struture for hosting RPC style APIs, supports both http and websocket access out of the box
The npm package rpcapi receives a total of 4 weekly downloads. As such, rpcapi popularity was classified as not popular.
We found that rpcapi demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.
Security News
Research
Attackers are impersonating Sindre Sorhus on npm with a fake 'chalk-node' package containing a malicious backdoor to compromise developers' projects.
Security News
The npm package for the LottieFiles Player web component was hit with a supply chain attack after a software engineer's npmjs credentials were compromised.