sugo-actor

7.0.8 • Public • Published

Title Banner

Build Status npm Version JS Standard

Actor component of SUGOS.

SUGO-Actor works as a client of SUGO-Hub and provides modules to remote SUGO-Caller .

Table of Contents

Requirements

banner banner

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

Readme

Keywords

Package Sidebar

Install

npm i sugo-actor

Weekly Downloads

17

Version

7.0.8

License

Apache-2.0

Unpacked Size

199 kB

Total Files

35

Last publish

Collaborators

  • okunishinishi
  • realglobe