loopback-socket
v0.4.6
Published
Loopback module for create Socket.io connections and allow call methods and make subscriptions
Downloads
104
Maintainers
Readme
loopback-socket
Loopback module for create Socket.io connections and allow call methods.
Installation
npm install loopback-socket --save
Usage
Server side
Include
const LoopbackSocket = require('loopback-socket');
LoopbackSocket.get(name, [timeout])
Create or get a instance with a specific name.
Arguments
Name | Type | Description
-------------|-----------|-------------
name
| string
| Name to instance. Required
[timeout]
| integer
| Time to wait authentication after establish connection before disconnect the socket. Optional.
Example
const loopbackSocket = LoopbackSocket.get('name');
const loopbackSocket = LoopbackSocket.get('name', 2000);
loopbackSocket.start(io)
Configure authentication, callbacks and methods with a server socket.
Arguments
Name | Type | Description
------|----------|-------------
io
| object
| Server Socket IO instance. Required.
Example
const server = require('http').createServer();
const io = require('socket.io')(server);
loopbackSocket.start(io);
loopbackSocket.auth(authentication)
Set the function to authenticate connected sockets.
Arguments
Name | Type | Description
------------------|--------------------------------------|-------------
authentication
| autentication function
or object
| Function called with (socket, credentials, [cb])
arguments or object like { model: Model, method: methodName }
where Model
is a class and methodName
is one of its methods (defined or to be defined) like autentication function
.
Authentication function
If an error is thrown in this function or it return a false value then authentication fails. If argument cb
is not defined then the returned value will be a the authentication response, and if this value is a promise, then it will be resolved before.
Name | Type | Description
---------------|------------|-------------
socket
| object
| Socket connected. Required.
credentials
| object
| Credentials received. Required.
[cb]
| function
| Callback with (err, success)
arguments to async return value with NodeJs callback style. Optional.
Example
// Authentication function with NodeJs callback style
function customAuthentication(socket, credentials, cb) {
User.getUserByCredentials(credentials, cb);
}
// Authentication function with direct value returned o Promise style
function customAuthentication(socket, credentials) {
return User.getUserByCredentials(credentials); // return data or a promise
}
// Direct setting
loopbackSocket.auth(customAuthentication);
// Setting through a Model
function MyModel() {};
loopbackSocket.auth({
model: MyModel,
method: 'customAuthentication'
});
MyModel.customAuthentication = authentication;
loopbackSocket.onConnected(handler)
Add a on connected handler.
Arguments
Name | Type | Description
-----------|-------------------------------|-------------
handler
| handler function
or object
| Function called with (socket, credentials, [cb])
arguments or object like { model: Model, method: methodName }
where Model
is a class and methodName
is one of its methods (defined or to be defined) with like handler function
.
Handler function
If argument cb
is not defined then the returned value will be a the handler response, and if this value is a promise, then it will be resolved before.
Name | Type | Description
---------------|------------|-------------
socket
| object
| Socket connected. Required.
credentials
| object
| Credentials received. Required.
[cb]
| function
| Callback with (err, success)
arguments to async return value with NodeJs callback style. Optional.
Example
// Authentication function with NodeJs callback style
function customOnConnectedHandler(socket, credentials, cb) {
User.getUserByCredentials(credentials, cb);
}
// Authentication function with direct value returned o Promise style
function customOnConnectedHandler(socket, credentials) {
return User.getUserByCredentials(credentials); // return data or a promise
}
// Direct adding
loopbackSocket.onConnected(customOnConnectedHandler);
// Adding through a Model
function MyModel() {};
loopbackSocket.onConnected({
model: MyModel,
method: 'customOnConnectedHandler'
});
MyModel.customOnConnectedHandler = customOnConnectedHandler;
loopbackSocket.removeOnConnected(handler)
Remove a connected handler
Arguments
Name | Type | Description
-----------|------------------------|-------------
handler
| function
or object
| Function called with (socket, credentials, [cb])
arguments or object like { model: Model, method: methodName }
where Model
is a class and methodName
is one of its methods (defined or to be defined) with like handler function
.
Example
// Direct remove
loopbackSocket.onConnected(customOnConnectedHandler);
// Remove Model method
function MyModel() {};
loopbackSocket.removeOnConnected({
model: MyModel,
method: 'customOnConnectedHandler'
});
loopbackSocket.defineMethod(methodName, method)
Define a method to call by socket connection or replace one existing.
Arguments
Name | Type | Description
--------------|-------------------------------|-------------
methodName
| string
| Method name.
method
| method function
or object
| Function called with (socket, credentials, args, [cb])
arguments or object like { model: Model, method: methodName }
where Model
is a class and methodName
is one of its methods (defined or to be defined) with like method function
.
Method function
If argument cb
is not defined then the returned value will be the method called reponse, and if this value is a promise, then it will be resolved before.
Name | Type | Description
---------------|------------|-------------
socket
| object
| Socket connected. Required.
credentials
| object
| Credentials received. Required.
args
. | object
| Arguments to call method. Required.
[cb]
| function
| Callback with (err, success)
arguments to async return value with NodeJs callback style. Optional.
Example
/// Method function with NodeJs callback style
function customMethod(socket, credentials, args, cb) {
let data;
// Option 1
cb(null, data); // Client receives { result: data }
// Option 2
cb('myError'); // Client receives { error: 'myError' }
}
/// Method function with direct value returned o Promise style
function customMethod(socket, credentials, args) {
let dataOrPromise;
// Option 1
return dataOrPromise; // Client receives { result: dataOrPromiseResolvedValue }
// Option 2
throw 'myError'; // Client receives { error: 'myError' }
}
// Direct definition
loopbackSocket.defineMethod('customMethod', customMethod);
// Definition through a Model
function MyModel() {};
loopbackSocket.defineMethod('customMethod', {
model: MyModel,
method: 'customMethod',
});
MyModel.customMethod = customMethod;
loopbackSocket.removeMethod(methodName)
Remove a method of socket.
Arguments
Name | Type | Description
-----------|-------------|-------------
methodName
| string
| Method name to remove.
Example
// Direct remove
loopbackSocket.onConnected('customMethod');
Client side sample
const socket = io('http://localhost');
socket.on('connect', (socket) => {
// send credentials
socket.emit('authentication', credentials);
});
socket.on('authenticated', (socket) => {
// socket authenticated
});
socket.on('unauthorized', (socket) => {
// socket failed authentication
});
function callMyMethod() {
// Call a defined socket method
socket.emit('myMethod', {}, (response) => {
if (response.error) {
// Method return a error;
return;
}
// Method success;
console.log(response.result);
});
}
Samples
Loopback + AngularJS:
https://github.com/arondn2/loopback-socket/tree/master/examples/loopback
Troubles
If you have any kind of trouble with it, just let me now by raising an issue on the GitHub issue tracker here:
https://github.com/arondn2/loopback-socket/issues
Also, you can report the orthographic errors in the READMEs files or comments. Sorry for that, I do not speak English.
Tests
npm test
or npm run cover
Contributing
In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code.