sugo-actor
v7.0.8
Published
Actor component of SUGOS.
Readme
Actor component of SUGOS.
SUGO-Actor works as a client of SUGO-Hub and provides modules to remote SUGO-Caller .
Table of Contents
Requirements
Installation
$ npm install sugo-actor --saveUsage
Create an actor instance and connect it to a [SUGO-Hub][sugo_hub_url] server.
#!/usr/bin/env node
/**
* This is an example to use an actor
*/
'use strict'
const sugoActor = require('sugo-actor')
const { Module } = sugoActor
async function tryExample () {
let actor = sugoActor({
/** Protocol to connect hub */
protocol: 'https',
/** Host name of hub */
hostname: 'my-sugo-hub.example.com',
/** Key to identify the actor */
key: 'my-actor-01',
/** Modules to load */
modules: {
tableTennis: new Module({
// Declare custom function
async ping (pong) {
/* ... */
return pong // Return value to pass caller
}
}),
// Use module plugin
shell: require('sugo-module-shell')({})
}
})
// Connect to hub
await actor.connect()
}
tryExample().catch((err) => console.error(err))
For more detail, see API Guide
Advanced Usage
Using EventEmitter Interface
The Module class provide EventEmitter interface like .on(), .off(), .emit() to communicate with remote callers.
#!/usr/bin/env node
/**
* This is an example for use event interface
*/
'use strict'
const sugoActor = require('sugo-actor')
const { Module } = sugoActor
const fs = require('fs')
async function tryEventExample () {
let actor = sugoActor({
protocol: 'https',
hostname: 'my-sugo-hub.example.com',
key: 'my-actor-01',
modules: {
sample01: new Module({
// File watch with event emitter
async watchFile (pattern) {
const s = this
// "this" is has interface of EventEmitter class
let watcher = fs.watch(pattern, (event, filename) => {
// Emit event to remote terminal
s.emit('change', { event, filename })
})
// Receive event from remote terminal
s.on('stop', () => watcher.close())
},
/**
* Module specification.
* @see https://github.com/realglobe-Inc/sg-schemas/blob/master/lib/module_spec.json
*/
$spec: { /* ... */ }
})
}
})
// Connect to hub
await actor.connect()
}
tryEventExample().catch((err) => console.error(err))
Description with $spec
You can describe a module with $spec property.
The spec object must conform to module_spec.json, a JSON-Schema.
#!/usr/bin/env node
/**
* This is an example to define spec on module
*
* @see https://github.com/realglobe-Inc/sg-schemas/blob/master/lib/module_spec.json
*/
'use strict'
const sugoActor = require('sugo-actor')
const { Module } = sugoActor
const fs = require('fs')
async function tryExample () {
let actor = sugoActor({
protocol: 'https',
hostname: 'my-sugo-hub.example.com',
key: 'my-actor-01',
modules: {
sample01: new Module({
async watchFile (pattern) { /* ... */ },
/**
* Module specification.
* @see https://github.com/realglobe-Inc/sg-schemas/blob/master/lib/module_spec.json
*/
get $spec () {
return {
name: 'sugo-demo-actor-sample',
version: '1.0.0',
desc: 'A sample module',
methods: {
watchFile: {
params: [
{ name: 'pattern', desc: 'Glob pattern files to watch' }
]
}
}
}
}
})
}
})
// Connect to hub
await actor.connect()
}
tryExample().catch((err) => console.error(err))
Declare a Single Function as Module
Sometimes you do not want multiple module methods, but only one function. Just declaring a function as module would do this.
#!/usr/bin/env node
/**
* This is an example to use a function module
*/
'use strict'
const sugoActor = require('sugo-actor')
const { Module } = sugoActor
const fs = require('fs')
async function tryFuncExample () {
let actor = sugoActor({
protocol: 'https',
hostname: 'my-sugo-hub.example.com',
key: 'my-actor-01',
modules: {
sample01: new Module({ /* ... */ }),
// A function as module
sample02: new Module(async function (foo) {
/* ... */
return 'say yo!'
})
}
})
// Connect to hub
await actor.connect()
}
tryFuncExample().catch((err) => console.error(err))
Add Auth Configuration
You can pass auth config to SUGO-Hub by setting auth field on the constructor.
#!/usr/bin/env node
/**
* This is an example to use an auth
* @see https://github.com/realglobe-Inc/sugo-hub#use-authentication
*/
'use strict'
const sugoActor = require('sugo-actor')
const { Module } = sugoActor
const fs = require('fs')
async function tryAuthExample () {
let actor = sugoActor({
protocol: 'https',
hostname: 'my-sugo-hub.example.com',
key: 'my-actor-01',
modules: { /* ... */ },
// Auth for hub
auth: {
// The structure of this field depends on `authenticate` logic implemented on SUGO-Hub
token: 'a!09jkl3A'
}
})
// Connect to hub
await actor.connect()
}
tryAuthExample().catch((err) => console.error(err))
Detect Caller Join/Leave
Actor emits CallerEvents.JOIN and CallerEvents.LEAVE events each time a caller connected/disconnected.
#!/usr/bin/env node
/**
* This is an example to detect caller join/leave
*/
'use strict'
const sugoActor = require('sugo-actor')
const { CallerEvents } = sugoActor
const { JOIN, LEAVE } = CallerEvents
async function tryJoinLeaveExample () {
let actor = sugoActor({ /* ... */ })
actor.on(JOIN, ({ caller, messages }) => {
console.log(`Caller ${caller.key} joined with messages: ${messages}`)
})
actor.on(LEAVE, ({ caller, messages }) => {
console.log(`Caller ${caller.key} leaved with messages: ${messages}`)
})
// Connect to hub
await actor.connect()
}
tryJoinLeaveExample().catch((err) => console.error(err))
License
This software is released under the Apache-2.0 License.