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
• Usage
• Advanced Usage
  • Using EventEmitter Interface
  • Description with $spec
  • Declare a Single Function as Module
  • Add Auth Configuration
  • Detect Caller Join/Leave
• License
• Links

Requirements

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

Installation

$ npm install sugo-actor --save

Usage

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.

Links

• SUGO-Hub
• SUGO-Caller
• SUGOS
• Realglobe, Inc.