API Gateway service for Moleculer framework using SocketCluster
Switch branches/tags
Nothing to show
Clone or download
Latest commit 0120a9a Jun 26, 2018
Permalink
Failed to load latest commit information.
examples 0.8.0 Jun 5, 2018
lib v0.9.0 Jun 16, 2018
src v0.9.0 Jun 16, 2018
test Fix getMeta error Jun 6, 2018
.babelrc Add babel to support node 6.x Aug 31, 2017
.gitignore Initial commit Aug 29, 2017
LICENSE Initial commit Aug 29, 2017
README.md Update readme Jun 26, 2018
package-lock.json v0.9.0 Jun 16, 2018
package.json v0.9.0 Jun 16, 2018
transporter.js Update doc Jun 4, 2018

README.md

LOGO GitHub license npm

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 => moleculer ctx.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.js
const SCWorker = require('socketcluster/scworker');
const { ServiceBroker } = require('moleculer')
const SocketClusterService = require('moleculer-sc')
class Worker extends SCWorker {
  run() {
    console.log('   >> Worker PID:', process.pid);
    var environment = this.options.environment;
    let broker = new ServiceBroker({
      logger: console
    })
    broker.createService({
      name:'sc-gw',
      mixins:[SCService(this)], //create SCService with worker.
    })
    broker.start()
  }
}

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.createService({
  name:'sc-gw', // SocketCluster GateWay
  mixins:[SocketClusterService(worker)],
  settings: {
    routes: [{
      event: "call",
      whitelist: [
        // Access to any actions in 'posts' service
        "posts.*",
        // Access to call only the `users.list` action
        "users.list",
        // Access to any actions in 'math' service
        /^math\.\w+$/
      ]
    }]
    }
})

Multiple routes

You can create multiple routes with different whitelist, calling options & authorization.

broker.createService({
  mixins: [SocketClusterService(worker)],
  settings: {
    routes: [
      {
        event: "adminCall",
        whitelist: [
          "$node.*",
          "users.*",
        ]
      },
      {
        event: "call",
        whitelist: [
          "posts.*",
          "math.*",
        ]
      }
    ]
  }
});

Authorization

You can implement authorization. For this you need to do 2 things.

  1. Define the authorization handler in SocketCluster.
  2. Rewrite the getMeta method of sc-gw service. (Optional)

Example authorization:

socket.on('login', function (credentials, respond) {
  broker.call('v1.account.login', data).then(res=>{
    socket.setAuthToken(res) //success
    callback(null,res)
  }).catch(err=>{
    const errObj = _.pick(err, ["name", "message", "code", "type", "data"])
    callback(errObj)
  }) //error
})

For convenience, we did this for you. You could set a handler with login type:

broker.createService({
  mixins: [SocketClusterService(worker)],
  settings: {
    routes: [
      {
        event: "login",
        type:'login', //Set route type to login, when calling success, you are logged in!
        whitelist: [
          "login.password",
          "login.google",
          "login.github"
        ]
      }
    ]
  }
});
// Add an handler service
broker.createService({
  name:'login',
  actions: {
    password(ctx) {
      if(ctx.params.user == 'tiaod' && ctx.params.password == 'pass'){
        return {id: 'tiaod'}
      }else{
        throw new Error('UNAUTH')
      }
    }
  }
})

Then:

socket.emit('login', {action:'login.password', params: {user: 'tiaod', password:'pass'}}, function(err, data){
  console.log('call login.passoword:',data)
  console.log(socket.authToken.id == 'tiaod') //true
})

Also you could overwrite the getMeta method to add more addition meta info. The default getMeta method is:

getMeta(socket){
  return {
    user: socket.authToken
  }
}

Example to add more additional info:

broker.createService({
  name:'sc-gw',
  mixins:[SocketClusterService(worker)],
  methods:{
    getMeta(socket){ //construct the meta object.
      return {
        user: socket.authToken,
        socketId: socket.id
      }
    }
  }
})

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.createService({
  mixins: [SocketClusterService(worker)],
  settings: {
    routes: [{
      event:'call',
      whitelist: [
        "posts.*",
        "math.*",
      ],
      callOptions: {
        timeout: 500,
        retryCount: 0,
        fallbackResponse(ctx, err) { ... }
      }
    }]		
  }
});

Note: If you provie a meta field here, it replace the getMeta method's result.

broker.createService({
  mixins: [SocketClusterService(worker)],
  settings: {
    routes: [{
      event:'call',
      callOptions: {
        meta: { abc:123 }
      }
    }]		
  },
  methods:{
    getMeta(socket){
      return {
        user: socket.authToken
      } //This will be replaced by callOptions.meta
    }
  }
});

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 = require('acl')
acl = new acl(new acl.memoryBackend())
acl.allow('admin', 'math', 'add') // allow admin to call
acl.addUserRoles('user id here', 'admin')
scServer.addMiddleware(scServer.MIDDLEWARE_EMIT,
  async function (req, next) {
    if(!data || typeof data.action !== 'string') next(new Error('invaild request'))
    let [service, action] = req.data.action.split('.', 2)
    if (!await acl.isAllowed(req.socket.authToken.id, service, action)) {
      next(); // Allow
    } else {
      var err = MyCustomEmitFailedError(req.socket.id + ' is not allowed to call action ' + req.event);
      next(err); // Block
      // next(true); // Passing true to next() blocks quietly (without raising a warning on the server-side)
    }
  }
);

Error parser

You can rewrite global-level error handler:

In handler, you must call the respond. Otherwise, the request is unhandled.

broker.createService({
  mixins: [SocketClusterService(worker)],
  settings: {
    routes: [{
      event:'call',
      callOptions: {
        meta: { abc:123 }
      }
    }]		
  },
  methods:{
    onError(err, respond){ //This is the default handler
      const errObj = _.pick(err, ["name", "message", "code", "type", "data"]);
      return respond(errObj)
    }
  }
});

SocketCluster transporter

You can also use SocketCluster as moleculer's transporter!

// worker.js
const { ServiceBroker } = require('moleculer')
const SCTransporter = require('moleculer-sc/transporter')
let broker = new ServiceBroker({
  nodeID: "node-1",
  logger: console,
  transporter: new SCTransporter({
    exchange:this.exchange
  })
})
broker.createService({
  name:'math',
  actions: {
    add(ctx) {
      return Number(ctx.params.a) + Number(ctx.params.b);
    }
  }
})
broker.start().then(()=>{
  console.log('broker1 started!')
})
// external-service.js
const { ServiceBroker } = require('moleculer')
const SCTransporter = require('moleculer-sc/transporter')
let broker2 = new ServiceBroker({
  nodeID: "node-2",
  logger: console,
  transporter: new SCTransporter({
    hostname:'localhost',
    port:8000
  })
})
broker2.start()
  .then(() => broker2.call("math.add", { a: 5, b: 3 }))
  .then(res => console.log("5 + 3 =", res))

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:

new SCTransporter({
  socket:socket
})
// or
new SCTransporter({
  exchange:exchange
})

Publish to scChannel

Just do:

let data = {
  hello: 'world'
}
broker.call('sc-gw.publish',{
  topic: 'your.topic.here',
  data: data
})

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.createService({
  name:'sc-gw', // SocketCluster GateWay
  mixins:[SCService], //This will not work anymore
  settings:{
    worker,
  }
})
// new:
broker.createService({
  name:'sc-gw',
  mixins:[SCService(worker)], //create SCService with worker.
})

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.