Caller component of SUGOS.

SUGO-Caller works as a client of SUGO-Hub and provides accessors for remote SUGO-Actor .

Table of Contents

• Requirements
• Installation
• Usage
• Tips
  • Restricting Connecting Modules
  • Describing a Module
  • Use auth
• License
• Links

Requirements

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

Installation

$ npm install sugo-caller --save

Usage

Create a caller instance with [SUGO-Hub][sugo_hub_url] url and connect to an [SUGO-Actor][sugo_actor_url] with key.

#!/usr/bin/env node

/**
 * This is an example to use caller to connect remote actor
 */
'use strict'

const sugoCaller = require('sugo-caller')

const TARGET_ACTOR_ID = 'my-actor-01'

async function tryExample () {
  let caller = sugoCaller({
    protocol: 'https',
    hostname: 'my-sugo-hub.example.com'
  })

// Connect to the target actor
  let actor = await caller.connect(TARGET_ACTOR_ID)
  let shell = actor.get('shell') // Get bash interface

  // Trigger ls command on remote actor
  {
    let lsResult = await shell.exec('ls -la /opt/shared')
    console.log(lsResult)
  }

  // Pipe std out
  {
    let out = (chunk) => process.stdout.write(chunk)
    shell.on('stdout', out)
    await shell.spawn('tail -f /var/log/app.log') // Trigger tailing without blocking
    await new Promise((resolve) => setTimeout(() => resolve(), 3000)) // Block for duration
    shell.off('stdout', out)
  }

  // Exec reboot command
  await shell.exec('reboot')
}

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

For more detail, see API Guide

Tips

Restricting Connecting Modules

Sometime you would like to make sure that the connecting actor has right modules as expected.

You can pass a JSON-Schema to expect option when accessing a modules. If the modules does not conform to the schema, it throws an error.

#!/usr/bin/env node

/**
 * This is an example to restrict a module with json schema
 */
'use strict'

const sugoCaller = require('sugo-caller')

// JSON-Schema for expected spec info
const shellSchemaV2 = {
  type: 'object',
  properties: {
    name: { enum: [ 'shell' ] }, // Should be shell
    version: { pattern: '^2\.' } // Major version must be 2
    /* ... */
  }
}

async function tryRestrictExample () {
  let caller = sugoCaller({ /* ... */ })
  let actor = await caller.connect('my-actor-01')

  let shell
  try {
    shell = actor.get('shell', {
      // Pass a JSON-Schema to validate the module. Throws an error if invalid
      expect: shellSchemaV2
    })
  } catch (err) {
    console.error('Failed to access!!')
  }
  /* ... */
}

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

Describing a Module

You can get module spec data via .describe(moduleName) of actor connection.

#!/usr/bin/env node

/**
 * This is an example to describe a module
 */
'use strict'

const sugoCaller = require('sugo-caller')

async function tryDescribeExample () {
  let caller = sugoCaller({ /* ... */ })
  let actor = await caller.connect('my-actor-01')

  {
    let description = actor.describe('shell')
    console.log(description) // -> { name: 'shell', desc: 'Shell interface', ... }
  }

  /* ... */
}

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

Use auth

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 sugoCaller = require('sugo-caller')

async function tryAutyExample () {
  let caller = sugoCaller({
    protocol: 'https',
    hostname: 'my-sugo-hub.example.com',
    // Auth for hub
    auth: {
      // The structure of this field depends on `authenticate` logic implemented on SUGO-Hub
      token: 'a!09jkl3A'
    }
  })

// Connect to the target actor
  let actor = await caller.connect('my-actor-01')
  let shell = actor.get('shell') // Get bash interface
  /* ... */
}

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

License

This software is released under the Apache-2.0 License.

Links

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