moleculer-sc
An API Gateway service for Moleculer framework using SocketCluster
What is SocketCluster? SocketCluster is an open source real-time framework for Node.js. It supports both direct client-server communication and group communication via pub/sub channels. It is designed to easily scale to any number of processes/hosts and is ideal for building chat systems.
Features
- Call moleculer actions by emiting SocketCluster events.
- Support SocketCluster authorization (sc
socket.authToken
=> moleculerctx.meta.user
) - Whitelist.
Install
$ npm install moleculer-sc
Usage
SocketCluster is a fast, highly scalable HTTP + WebSockets server environment which lets you build multi-process real-time systems that make use of all CPU cores on a machine/instance.
Before you start, you have to create a SocketCluster project, and write the code in worker.js
. (See /examples/simple
)
Handle socket events
Create your own SocketCluster Gateway service.
// SocketCluster worker.jsconst SCWorker = ;const ServiceBroker = const SocketClusterService = { console; var environment = thisoptionsenvironment; let broker = logger: console broker brokerstart }
By default, moleculer-sc
will handle the call
event which proxy to moleculer's broker.call
Examples:
- Call
test.hello
action:socket.emit('call',{action:'test.hello'}, callback)
- Call
math.add
action with params:socket.emit('call',{action:'math.add', params:{a:25, b:13}}, callback)
- Get health info of node:
socket.emit('call',{ action: '$node.health' }, callback)
- List all actions:
socket.emit('call', { action: '$node.list'}, callback)
Whitelist
If you don’t want to public all actions, you can filter them with whitelist option. You can use match strings or regexp in list.
broker
Multiple routes
You can create multiple routes with different prefix, whitelist, alias, calling options & authorization.
broker;
Authorization
You can implement authorization. For this you need to do 2 things.
- Define the authorization handler in SocketCluster.
- Rewrite the
getMeta
method ofsc-gw
service. (Optional)
Example authorization:
socket
For convenience, we did this for you. You could set a handler with login
type:
broker;// Add an handler servicebroker
Then:
socket
Also you could overwrite the getMeta
method to add more addition meta info. The default getMeta
method is:
{ return user: socketauthToken }
Example to add more additional info:
broker
Calling options
The route has a callOptions property which is passed to broker.call. So you can set timeout, retryCount or fallbackResponse options for routes.
broker;
Note: If you provie a meta field here, it replace the getMeta
method's result.
broker;
Access control lists
If you want to do a role-based access control, you can do it on SocketCluster way. Here is an example using node_acl
:
let acl = acl = acl // allow admin to callaclscServer;
Error parser
You can rewrite global-level error handler:
In handler, you must call the
respond
. Otherwise, the request is unhandled.
broker;
SocketCluster transporter
You can also use SocketCluster as moleculer's transporter!
// worker.jsconst ServiceBroker = const SCTransporter = let broker = nodeID: "node-1" logger: console transporter: exchange:thisexchange brokerbrokerstart
// external-service.jsconst ServiceBroker = const SCTransporter = let broker2 = nodeID: "node-2" logger: console transporter: hostname:'localhost' port:8000 broker2start
Warning: You should add a SocketCluster middleware to apply access control with MOL.
channel prefix.
You can also pass an socket object or SCExchange instance:
socket:socket// orexchange:exchange
Publish to scChannel
Just do:
let data = hello: 'world'broker
Change logs
0.9.0 - Add publish
action.
0.8.1 - Fix getMeta
error.
0.8.0 - Add login
handler type.
0.7.0 - Add onError
handler
0.6.1 - You can pass socket
or exchange
object to SCTransporter now.
0.6.0 - Breaking change: Don't pass worker in settings anymore, you should pass the worker when initerlized the service.
// old:broker
// new:broker
This is because the settings is also obtainable on remote nodes, it is transferred during service discovering, which will cause a TypeError: Converting circular structure to JSON
when serializing it.
0.5.0 - Add transporter.
0.4.0 - Add multiple routes support.
0.3.0 - Doesn't integrate node_acl
anymore. If you need access control lists, you can do it on socketcluster side.