Hub server of SUGOS

SUGO-Hub works as a hub to connect SUGO-Actors and SUGO-Callers.

Table of Contents

• Requirements
• Installation
• Usage
• Advanced Usage
  • Using Redis Server
  • Define HTTP Endpoints
  • Define HTTP Middlewares
  • Use Authentication
  • Register Local Actors
• License
• Links

Requirements

• Node.js ( >=7.6 )
• npm ( >=4 )

Installation

$ npm install sugo-hub --save

Usage

#!/usr/bin/env node

/**
 * This is an example to setup hub server
 */

'use strict'

const sugoHub = require('sugo-hub')

async function tryExample () {
  // Start sugo-hub server
  let hub = sugoHub({
    // Options here
  })

  await hub.listen(3000)

  console.log(`SUGO Cloud started at port: ${hub.port}`)
}

tryExample().catch((err) => console.error(err))

By default, SUGOS-Cloud provides WebSocket interfaces with following URLs:

URL	Description
/actors	WebSocket namespace for [SUGO-Actors][sugo_actor_url]
/callers	WebSocket namespace for [SUGO-Callers][sugo_caller_url]
/observers	WebSocket namespace for [SUGO-Observers][sugo_observer_url]

For more detail, see API Guide

Advanced Usage

SUGO cloud also provide bunch of options for building more complex applications.

Using Redis Server

By default, SUGO-Hub save state to json files. This may cause performance slow down on production. It is recommended to setup redis server for storage.

#!/usr/bin/env node

/**
 * This is an example to setup hub server with redis
 */

'use strict'

const sugoHub = require('sugo-hub')

async function tryRedisExample () {
  let hub = sugoHub({
    // Using redis server as storage
    storage: {
      // Redis setup options (see https://github.com/NodeRedis/node_redis)
      redis: {
        host: '127.0.0.1',
        port: '6379',
        db: 1
      }
    },
    endpoints: { /* ... */ },
    middlewares: [ /* ... */ ],
    static: [ /* ... */ ]
  })

  await hub.listen(3000)

  console.log(`SUGO Cloud started at port: ${hub.port}`)
}
tryRedisExample().catch((err) => console.error(err))

Define HTTP Endpoints

SUGO-Hub uses Koa as http framework. You can define custom koa handlers on endpoints field.

#!/usr/bin/env node

/**
 * This is an example to setup hub server with endpoints
 */

'use strict'

const sugoHub = require('sugo-hub')

async function tryExample () {
  let hub = sugoHub({
    storage: { /* ... */ },
    // HTTP route handler with koa
    endpoints: {
      '/api/user/:id': {
        'GET': (ctx) => {
          let { id } = ctx.params
          /* ... */
          ctx.body = { /* ... */ }
        }
      }
    },
    middlewares: [ /* ... */ ],
    static: [ /* ... */ ]
  })

  await hub.listen(3000)

  console.log(`SUGO Cloud started at port: ${hub.port}`)
}
tryExample().catch((err) => console.error(err))

Define HTTP Middlewares

For cross-endpoint handling, add koa middleware function to middlewares field.

Note that static middlewares are provided as build-in middleware and you can serve static files by just setting directory names to static field.

#!/usr/bin/env node

/**
 * This is an example to setup hub server with middlewares
 */

'use strict'

const sugoHub = require('sugo-hub')

async function tryMiddleareExample () {
  let hub = sugoHub({
    storage: { /* ... */ },
    // HTTP route handler with koa
    endpoints: { /* ... */ },
    // Custom koa middlewares
    middlewares: [
      async function customMiddleware (ctx, next) {
        /* ... */
        await next()
      }
    ],
    // Directory names to server static files
    static: [
      'public'
    ]
  })

  await hub.listen(3000)

  console.log(`SUGO Cloud started at port: ${hub.port}`)
}
tryMiddleareExample().catch((err) => console.error(err))

Use Authentication

By providing authenticate filed, you can authenticate sockets connecting.

#!/usr/bin/env node

/**
 * This is an example to setup hub server with aut
 */

'use strict'

const sugoHub = require('sugo-hub')

async function tryAuthExample () {
  let hub = sugoHub({
    storage: { /* ... */ },
    endpoints: { /* ... */ },
    /**
     * Auth function
     * @param {Object} socket - A socket connecting
     * @param {Object} data - Socket auth data
     * @returns {Promise.<boolean>} - OK or not
     */
    authenticate (socket, data) {
      let tokenStates = { /* ... */ }
      let ok = !!tokenStates[ data.token ]
      return Promise.resolve(ok)
    },
    middlewares: [ /* ... */ ],
    static: [ /* ... */ ]
  })

  await hub.listen(3000)

  console.log(`SUGO Cloud started at port: ${hub.port}`)
}

tryAuthExample().catch((err) => console.error(err))

Register Local Actors

If you want to use actors on the same environment with hub, pass actors instances to localActors option of hub.

#!/usr/bin/env node

/**
 * This is an example to setup hub server with local actors
 */

'use strict'

const sugoHub = require('sugo-hub')
const sugoActor = require('sugo-actor')

async function tryLocalExample () {
  let hub = sugoHub({
    storage: { /* ... */ },
    endpoints: { /* ... */ },
    middlewares: [ /* ... */ ],
    static: [ /* ... */ ],

    /**
     * Local actors for the hub
     * @type {Object<string, SugoActor>}
     */
    localActors: {
      'my-actor-01': sugoActor({
        modules: {
          say: {
            sayYes: () => 'Yes from actor01'
          }
        }
      })
    }
  })

  // Local actors automatically connect to the hub when it start listening
  await hub.listen(3000)

  console.log(`SUGO Cloud started at port: ${hub.port}`)
}

tryLocalExample().catch((err) => console.error(err))

License

This software is released under the Apache-2.0 License.

Links

• SUGO-Actor
• SUGO-Caller
• SUGO-Observer
• Koa
• SUGOS
• Realglobe, Inc.