[![Build Status][bd_travis_shield_url]][bd_travis_url]
[![npm Version][bd_npm_shield_url]][bd_npm_url]
[![JS Standard][bd_standard_shield_url]][bd_standard_url]
[bd_repo_url]: https://github.com/realglobe-Inc/sugo-hub
[bd_travis_url]: http://travis-ci.org/realglobe-Inc/sugo-hub
[bd_travis_shield_url]: http://img.shields.io/travis/realglobe-Inc/sugo-hub.svg?style=flat
[bd_travis_com_url]: http://travis-ci.com/realglobe-Inc/sugo-hub
[bd_travis_com_shield_url]: https://api.travis-ci.com/realglobe-Inc/sugo-hub.svg?token=
[bd_license_url]: https://github.com/realglobe-Inc/sugo-hub/blob/master/LICENSE
[bd_codeclimate_url]: http://codeclimate.com/github/realglobe-Inc/sugo-hub
[bd_codeclimate_shield_url]: http://img.shields.io/codeclimate/github/realglobe-Inc/sugo-hub.svg?style=flat
[bd_codeclimate_coverage_shield_url]: http://img.shields.io/codeclimate/coverage/github/realglobe-Inc/sugo-hub.svg?style=flat
[bd_gemnasium_url]: https://gemnasium.com/realglobe-Inc/sugo-hub
[bd_gemnasium_shield_url]: https://gemnasium.com/realglobe-Inc/sugo-hub.svg
[bd_npm_url]: http://www.npmjs.org/package/sugo-hub
[bd_npm_shield_url]: http://img.shields.io/npm/v/sugo-hub.svg?style=flat
[bd_standard_url]: http://standardjs.com/
[bd_standard_shield_url]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
Hub server of SUGOS
SUGO-Hub works as a hub to connect [SUGO-Actor][s_u_g_o_actor_url]s and [SUGO-Caller][s_u_g_o_caller_url]s.
Table of Contents
----------------
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Advanced Usage](#advanced-usage)
* [Using Redis Server](#using-redis-server)
* [Define HTTP Endpoints](#define-http-endpoints)
* [Define HTTP Middlewares](#define-http-middlewares)
* [Use Authentication](#use-authentication)
* [Register Local Actors](#register-local-actors)
- [License](#license)
- [Links](#links)
Requirements
-----
+ [Node.js ( >=7.6 )][node_download_url]
+ [npm ( >=4 )][npm_url]
[node_download_url]: https://nodejs.org/en/download/
[npm_url]: https://docs.npmjs.com/
Installation
-----
```bash
$ npm install sugo-hub --save
```
Usage
---------
```javascript
#!/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](./doc/api/api.md)
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.
```javascript
#!/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][koa_url] as http framework. You can define custom koa handlers on `endpoints` field.
```javascript
#!/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.
```javascript
#!/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.
```javascript
#!/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.} - 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.
```javascript
#!/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}
*/
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](https://github.com/realglobe-Inc/sugo-hub/blob/master/LICENSE).
Links
------
+ [SUGO-Actor][s_u_g_o_actor_url]
+ [SUGO-Caller][s_u_g_o_caller_url]
+ [SUGO-Observer][s_u_g_o_observer_url]
+ [Koa][koa_url]
+ [SUGOS][sugos_url]
+ [Realglobe, Inc.][realglobe,_inc__url]
[s_u_g_o_actor_url]: https://github.com/realglobe-Inc/sugo-actor
[s_u_g_o_caller_url]: https://github.com/realglobe-Inc/sugo-caller
[s_u_g_o_observer_url]: https://github.com/realglobe-Inc/sugo-observer
[koa_url]: https://github.com/koajs/koa
[sugos_url]: https://github.com/realglobe-Inc/sugos
[realglobe,_inc__url]: http://realglobe.jp