api.md

Classes

VrpcAdapter

Generates an adapter layer for existing code and enables further VRPC-based communication.

VrpcAgent ⇐ EventEmitter

Agent capable of making existing code available to remote control by clients.

VrpcClient ⇐ EventEmitter

Client capable of creating proxy objects and remotely calling functions as provided through one or more (distributed) agents.

VrpcNative

Client capable of creating proxy classes and objects to locally call functions as provided through native addons.

Typedefs

MetaData : Object.<String, Func>

Associates meta data to any function

Func

Param : Object

Ret : Object

VrpcAdapter

Generates an adapter layer for existing code and enables further VRPC-based communication.

Kind: global class

• VrpcAdapter
  • instance
    • "create"
    • "delete"
  • static
    • .addPluginPath(dirPath, [maxLevel])
    • .register(code, [options])
    • .registerInstance(obj, options)
    • .create(options) ⇒ Object
    • .delete(instance) ⇒ Boolean
    • .getInstance(instance) ⇒ Object
    • .getAvailableClasses() ⇒ Array.<String>
    • .getAvailableInstances(className) ⇒ Array.<String>

---

"create"

Event 'create'

Emitted on creation of shared instance

Kind: event emitted by VrpcAdapter
Properties

Name	Type	Description
className	String	The class name of the create instance
instance	String	The instance name
args	Array.<Any>	The constructor arguments

---

"delete"

Event 'delete'

Emitted on deletion of shared instance

Kind: event emitted by VrpcAdapter
Properties

Name	Type	Description
className	String	The class name of the deleted instance
instance	String	The instance name

---

VrpcAdapter.addPluginPath(dirPath, [maxLevel])

Automatically requires .js files for auto-registration.

Kind: static method of VrpcAdapter
Params

• dirPath String - Relative path to start the auto-registration from
• [maxLevel] Number - Maximum search depth (default: unlimited)

---

VrpcAdapter.register(code, [options])

Registers existing code and makes it (remotely) callable

Kind: static method of VrpcAdapter
Params

• code Any - Existing code to be registered, can be a class or function object or a relative path to a module
• [options] Object
  • [.onlyPublic] Boolean = true - If true, only registers functions that do not begin with an underscore
  • [.withNew] Boolean = true - If true, class will be constructed using the new operator
  • [.schema] Object = - If provided is used to validate ctor parameters (only works if registered code reflects a single class)
  • .jsdocPath String - if provided, parses documentation and provides it as meta information

NOTE: This function currently only supports registration of classes (either when provided as object or when exported on the provided module path)

---

VrpcAdapter.registerInstance(obj, options)

Registers an existing instance and make it (remotely) callable

Kind: static method of VrpcAdapter
Params

• obj Object - The instance to be registered
• options Object
  • .className String - Class name of the instance
  • .instance String - Name of the instance
  • [.onlyPublic] Boolean = true - If true, only registers functions that do not begin with an underscore
  • [.jsdocPath] String - if provided, parses documentation and provides it as meta information

---

VrpcAdapter.create(options) ⇒ Object

Creates a new instance

Kind: static method of VrpcAdapter
Returns: Object - The real instance (not a proxy!)
Params

• options Object
  • .className String - Name of the class which should be instantiated
  • [.instance] String - Name of the created instance. If not provided an id will be generated
  • [.args] Array - Positional arguments for the constructor call
  • [.isIsolated] bool = false - If true the created instance will be visible only to the client who created it

---

VrpcAdapter.delete(instance) ⇒ Boolean

Deletes an instance

Kind: static method of VrpcAdapter
Returns: Boolean - True in case of success, false otherwise
Params

• instance String | Object - Instance (name or object itself) to be deleted

---

VrpcAdapter.getInstance(instance) ⇒ Object

Retrieves an existing instance by name

Kind: static method of VrpcAdapter
Returns: Object - The real instance (not a proxy!)
Params

• instance String - Name of the instance to be acquired

---

VrpcAdapter.getAvailableClasses() ⇒ Array.<String>

Retrieves an array of all available classes (names only)

Kind: static method of VrpcAdapter
Returns: Array.<String> - Array of class names

---

VrpcAdapter.getAvailableInstances(className) ⇒ Array.<String>

Provides the names of all currently running instances.

Kind: static method of VrpcAdapter
Returns: Array.<String> - Array of instance names
Params

• className String - Name of class to retrieve the instances for

---

VrpcAgent ⇐ EventEmitter

Agent capable of making existing code available to remote control by clients.

Kind: global class
Extends: EventEmitter

• VrpcAgent ⇐ EventEmitter
  • new VrpcAgent(obj)
  • instance
    • .serve() ⇒ Promise
    • .end([obj], [unregister]) ⇒ Promise
    • .create(options) ⇒ Object
    • "connect"
    • "reconnect"
    • "close"
    • "offline"
    • "error"
    • "end"
    • "clientGone"
  • static
    • .fromCommandline(defaults) ⇒ Agent

---

new VrpcAgent(obj)

Constructs an agent instance

Params

• obj Object
  • [.username] String - MQTT username
  • [.password] String - MQTT password (if no token is provided)
  • [.token] String - Access token
  • [.domain] String = 'vrpc' - The domain under which the agent-provided code is reachable
  • [.agent] String = '<user>-<pathId>@<hostname>-<platform>-js' - This agent's name
  • [.broker] String = 'mqtts://vrpc.io:8883' - Broker url in form: <scheme>://<host>:<port>
  • [.log] Object = console - Log object (must support debug, info, warn, and error level)
  • [.bestEffort] String = true - If true, message will be sent with best effort, i.e. no caching if offline
  • [.version] String = '' - The (user-defined) version of this agent
  • [.mqttClientId] String = '<generated()>' - Explicitly set the mqtt client id.

Example

const agent = new Agent({
  domain: 'vrpc'
  agent: 'myAgent'
})

---

vrpcAgent.serve() ⇒ Promise

Starts the agent

The returned promise will only resolve once the agent is connected to the broker. If the connection can't be established it will try connecting forever. You may want to listen to the 'offline' (initial connect attempt failed) or 'reconnect' (any further fail) event and call agent.end() to stop trying to connect and resolve the returned promise.

If the connection could not be established because of authorization failure, the 'error' event will be emitted.

Kind: instance method of VrpcAgent
Returns: Promise - Resolves once connected or explicitly ended, never rejects

---

vrpcAgent.end([obj], [unregister]) ⇒ Promise

Stops the agent

Kind: instance method of VrpcAgent
Returns: Promise - Resolves when disconnected and ended
Params

• [obj] Object
• [unregister] Boolean = false - If true, fully un-registers agent from broker

---

vrpcAgent.create(options) ⇒ Object

Creates a new instance locally

NOTE: The instance must previously be registered by the local VrpcAdapter

Kind: instance method of VrpcAgent
Returns: Object - The real instance (not a proxy!)
Params

• options Object
  • .className String - Name of the class which should be instantiated
  • [.instance] String - Name of the created instance. If not provided an id will be generated
  • [.args] Array - Positional arguments for the constructor call
  • [.isIsolated] bool = false - If true the created instance will be visible only to the client who created it

---

"connect"

Event 'connect'

Emitted on successful (re)connection (i.e. connack rc=0).

Kind: event emitted by VrpcAgent
Properties

Name	Type	Description
sessionPresent	Boolean	A session from a previous connection is already present

---

"reconnect"

Event 'reconnect'

Emitted when a reconnect starts.

Kind: event emitted by VrpcAgent

---

"close"

Event 'close'

Emitted after a disconnection.

Kind: event emitted by VrpcAgent

---

"offline"

Event 'offline'

Emitted when the client goes offline.

Kind: event emitted by VrpcAgent

---

"error"

Event 'error'

Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs. The following TLS errors will be emitted as an error event:

• ECONNREFUSED
• ECONNRESET
• EADDRINUSE
• ENOTFOUND

Kind: event emitted by VrpcAgent

---

"end"

Event 'end'

Emitted when mqtt.Client#end() is called. If a callback was passed to mqtt.Client#end(), this event is emitted once the callback returns.

Kind: event emitted by VrpcAgent

---

"clientGone"

Event 'clientGone'

Emitted when a tracked VRPC client exited.

Kind: event emitted by VrpcAgent

---

VrpcAgent.fromCommandline(defaults) ⇒ Agent

Constructs an agent by parsing command line arguments

Kind: static method of VrpcAgent
Returns: Agent - Agent instance
Params

• defaults Object - Allows to specify defaults for the various command line options
  • .domain String - The domain under which the agent-provided code is reachable
  • .agent String - This agent's name
  • .username String - MQTT username (if no token is used)
  • .password String - MQTT password (if no token is provided)
  • .token String - Access token as generated by: https://app.vrpc.io
  • .broker String - Broker url in form: <scheme>://<host>:<port>
  • .version String - The (user-defined) version of this agent

Example

const agent = VrpcAgent.fromCommandline()

---

VrpcClient ⇐ EventEmitter

Client capable of creating proxy objects and remotely calling functions as provided through one or more (distributed) agents.

Kind: global class
Extends: EventEmitter

• VrpcClient ⇐ EventEmitter
  • new VrpcClient(options)
  • .getClientId() ⇒ String
  • .connect() ⇒ Promise
  • .create(options) ⇒ Promise.<Proxy>
  • .getInstance(instance, [options]) ⇒ Promise.<Proxy>
  • .delete(instance, [options]) ⇒ Promise.<Boolean>
  • .callStatic(options) ⇒ Promise.<Any>
  • .callAll(options) ⇒ Promise.<Array.<Object>>
  • .getSystemInformation() ⇒ Object
  • .getAvailableAgents([options]) ⇒ Array
  • .getAvailableClasses([options]) ⇒ Array
  • .getAvailableInstances([options]) ⇒ Array
  • .getAvailableMemberFunctions([options]) ⇒ Array
  • .getAvailableStaticFunctions([options]) ⇒ Array
  • .reconnectWithToken(token, [options]) ⇒ Promise
  • .unregisterAgent(agent) ⇒ Promise.<Boolean>
  • .end() ⇒ Promise
  • "agent" (info)
  • "class" (info)
  • "instanceNew" (addedInstances, info)
  • "instanceGone" (removedInstances, info)
  • "connect"
  • "reconnect"
  • "close"
  • "offline"
  • "error"
  • "end"

---

new VrpcClient(options)

Constructs a remote client, able to communicate with any distributed agents

NOTE: Each instance creates its own physical connection to the broker.

Params

• options Object
  • [.username] String - MQTT username
  • [.password] String - MQTT password (if no token is provided)
  • [.token] String - Access token
  • .domain String - Sets the domain
  • [.agent] String = "*" - Sets default agent
  • [.broker] String = "mqtts://vrpc.io:8883" - Broker url in form: <scheme>://<host>:<port>
  • [.timeout] Number = 12000 - Maximum time in ms to wait for a RPC answer
  • [.log] Object = console - Log object (must support debug, info, warn, and error level)
  • [.bestEffort] Boolean = true - If true, message will be sent with best effort, i.e. no caching if offline
  • [.mqttClientId] String = '<generated()>' - Explicitly sets the mqtt client id
  • [.identity] String - Explicitly sets a vrpc client identity
  • [.keepalive] String - Sets the MQTT keepalive interval (in seconds)
  • [.requiresSchema] Boolean = false - If true, any available schema information is shipped

Example

const client = new VrpcClient({
  domain: 'vrpc',
  broker: 'mqtt://vrpc.io'
})

---

vrpcClient.getClientId() ⇒ String

Provides a unique id for this client instance

Kind: instance method of VrpcClient
Returns: String - clientId

---

vrpcClient.connect() ⇒ Promise

Actually connects to the MQTT broker.

Kind: instance method of VrpcClient
Returns: Promise - Resolves once connected within [timeout], rejects otherwise
Emits: event:connected
Example

try {
  await client.connect()
} catch (err) {
  console.error(`Could not connect because: ${err.message}`)
}

---

vrpcClient.create(options) ⇒ Promise.<Proxy>

Creates a new remote instance and provides a proxy to it.

Remote instances can be "shared" or "isolated". Shared instances are visible and re-attachable across clients as long as they are not explicitly deleted. Life-cycle changes of shared instances are available under the class, instanceNew, and instanceGone events. A shared instance is created by default (isIsolated: false).

When the isIsolated option is true, the remote instance stays invisible to other clients and the corresponding proxy object is the only way to issue commands.

NOTE When creating an instance that already exists, the new proxy will simply attach to (and not re-create) it - just like getInstance() was called.

Kind: instance method of VrpcClient
Returns: Promise.<Proxy> - Object reflecting a proxy to the original object which is handled by the agent
Params

• options Object
  • .className String - Name of the class which should be instantiated
  • [.instance] String - Name of the created instance. If not provided an id will be generated
  • [.args] Array - Positional arguments for the constructor call
  • [.agent] String - Agent name. If not provided class default is used
  • [.cacheProxy] bool = false - If true the proxy object for a given instance is cached and (re-)used in subsequent calls
  • [.isIsolated] bool = false - If true the created proxy will be visible only to the client who created it

Example

// create isolated instance
const proxy1 = await client.create({
  className: 'Foo',
  instance: 'myPersonalInstance',
  isIsolated: true
})
// create shared instance
const proxy2 = await client.create({
  className: 'Foo',
  instance: 'aSharedFooInstance'
})
// create shared instance providing three constructor arguments
const proxy3 = await client.create({
  className: 'Bar',
  instance: 'mySharedBarInstance',
  args: [42, "second argument", { some: 'option' }]
})

---

vrpcClient.getInstance(instance, [options]) ⇒ Promise.<Proxy>

Get a remotely existing instance.

Either provide a string only, then VRPC tries to find the instance using client information, or additionally provide an object with explicit meta data.

Kind: instance method of VrpcClient
Returns: Promise.<Proxy> - Proxy object reflecting the remotely existing instance
Params

• instance String - The instance to be retrieved
• [options] Object - Explicitly define agent and class
  • [.className] String - Name of the instance's class
  • [.agent] String - Agent name. If not provided class default is used as priority hit
  • [.noWait] bool = false - If true immediately fail if instance could not be found in local cache

---

vrpcClient.delete(instance, [options]) ⇒ Promise.<Boolean>

Delete a remotely existing instance

Either provide a string only, then VRPC tries to find the instance using client information, or provide an object with explicit meta data.

Kind: instance method of VrpcClient
Returns: Promise.<Boolean> - true if successful, false otherwise
Params

• instance String - The instance to be deleted
• [options] Object - Explicitly define agent and class
  • .className String - Name of the instance's class
  • .agent String - Agent name. If not provided class default is used as priority hit

---

vrpcClient.callStatic(options) ⇒ Promise.<Any>

Calls a static function on a remote class

Kind: instance method of VrpcClient
Returns: Promise.<Any> - Return value of the remotely called function
Params

• options Object
  • .className String - Name of the static function's class
  • .functionName String - Name of the static function to be called
  • [.args] Array - Positional arguments of the static function call
  • [.agent] String - Agent name. If not provided class default is used

---

vrpcClient.callAll(options) ⇒ Promise.<Array.<Object>>

Calls the same function on all instances of a given class and returns an aggregated result. It as well allows for batch event and callback registrations. In this case the instanceId of the emitter is injected as first argument of any event callback.

NOTE: When no agent was specified as class default and no agent is specified when calling this function, callAll will act on the requested class across all available agents. The same is true when explicitly using a wildcard (*) as agent value.

Kind: instance method of VrpcClient
Returns: Promise.<Array.<Object>> - An array of objects { id, val, err } carrying the instance id, the return value and potential errors
Params

• options Object
  • .className String - Name of the static function's class
  • [.args] Array - Positional arguments of the static function call
  • [.agent] String - Agent name. If not provided class default is used

---

vrpcClient.getSystemInformation() ⇒ Object

Retrieves all information about the currently available components.

Kind: instance method of VrpcClient
Returns: Object - SystemInformation

type SystemInformation = {
  [agent].status: string, // 'offline' or 'online'
  [agent].hostname: string,
  [agent].version: string,
  [agent].classes[className].instances: string[],
  [agent].classes[className].memberFunctions: string[],
  [agent].classes[className].staticFunctions: string[],
  [agent].classes[className].meta?: MetaData
}

---

vrpcClient.getAvailableAgents([options]) ⇒ Array

Retrieves all available agents.

Kind: instance method of VrpcClient
Returns: Array - Array of agent names.
Params

• [options] Object
  • [.mustBeOnline] Boolean = true - Only retrieve currently online agents

---

vrpcClient.getAvailableClasses([options]) ⇒ Array

Retrieves all available classes on specific agent.

Kind: instance method of VrpcClient
Returns: Array - Array of class names.
Params

• [options] Object
  • [.agent] String - Agent name. If not provided class default is used.
  • [.mustBeOnline] Boolean = true - Only retrieve currently online classes

---

vrpcClient.getAvailableInstances([options]) ⇒ Array

Retrieves all (shared) instances on specific class and agent.

Kind: instance method of VrpcClient
Returns: Array - Array of instance names
Params

• [options] Object
  • .className String - Class name
  • [.agent] String - Agent name. If not provided class default is used
  • [.mustBeOnline] Boolean = true - Only retrieve currently online classes

---

vrpcClient.getAvailableMemberFunctions([options]) ⇒ Array

Retrieves all member functions of specific class and agent.

Kind: instance method of VrpcClient
Returns: Array - Array of member function names
Params

• [options] Object
  • .className String - Class name
  • [.agent] String - Agent name. If not provided class default is used
  • [.mustBeOnline] Boolean = true - Only retrieve currently online classes

---

vrpcClient.getAvailableStaticFunctions([options]) ⇒ Array

Retrieves all static functions of specific class and agent.

Kind: instance method of VrpcClient
Returns: Array - Array of static function names
Params

• [options] Object
  • .className String - Class name
  • [.agent] String - Agent name. If not provided class default is used
  • [.mustBeOnline] Boolean = true - Only retrieve currently online classes

---

vrpcClient.reconnectWithToken(token, [options]) ⇒ Promise

Reconnects to the broker by using a different token

Kind: instance method of VrpcClient
Returns: Promise - Promise that resolves once re-connected
Params

• token String - Access token as generated by: https://app.vrpc.io
• [options] Object
  • .agent String - Agent name. If not provided class default is used

---

vrpcClient.unregisterAgent(agent) ⇒ Promise.<Boolean>

Unregisters (= removal of persisted information) an offline agent

Kind: instance method of VrpcClient
Returns: Promise.<Boolean> - Resolves to true in case of success, false otherwise
Params

• agent - The agent to be unregistered

---

vrpcClient.end() ⇒ Promise

Ends the connection to the broker

Kind: instance method of VrpcClient
Returns: Promise - Resolves when ended

---

"agent" (info)

Event 'agent'

This event is fired whenever an agent is added or removed, or whenever an agent changes its status (switches between online or offline).

Kind: event emitted by VrpcClient
Params

• info Object
  • .domain String - Domain name
  • .agent String - Agent name
  • .status String - Agent status, can be 'offline' or 'online'
  • .hostname String - Name of the host running the agent
  • .version String - User-defined version of the agent

---

"class" (info)

Event 'class'

Emitted whenever a class is added or removed, or when instances or functions of this class have changed.

Kind: event emitted by VrpcClient
Params

• info Object
  • .domain String - Domain name
  • .agent String - Agent name
  • .className String - Class name
  • .instances Array.<String> - Array of instances
  • .memberFunctions Array.<String> - Array of member functions
  • .staticFunctions Array.<String> - Array of static functions
  • .meta MetaData - Object associating further information to functions

---

"instanceNew" (addedInstances, info)

Event 'instanceNew'

Emitted whenever a new instance was created.

Kind: event emitted by VrpcClient
Params

• addedInstances Array.<String> - An array of newly added instances
• info Object
  • .domain String - Domain name
  • .agent String - Agent name
  • .className String - Class name

---

"instanceGone" (removedInstances, info)

Event 'instanceGone'

Emitted whenever a new instance was removed.

Kind: event emitted by VrpcClient
Params

• removedInstances Array.<String> - An array of removed instances
• info Object
  • .domain String - Domain name
  • .agent String - Agent name
  • .className String - Class name

---

"connect"

Event 'connect'

Emitted on successful (re)connection (i.e. connack rc=0).

Kind: event emitted by VrpcClient
Properties

Name	Type	Description
sessionPresent	Boolean	A session from a previous connection is already present

---

"reconnect"

Event 'reconnect'

Emitted when a reconnect starts.

Kind: event emitted by VrpcClient

---

"close"

Event 'close'

Emitted after a disconnection.

Kind: event emitted by VrpcClient

---

"offline"

Event 'offline'

Emitted when the client goes offline.

Kind: event emitted by VrpcClient

---

"error"

Event 'error'

Emitted when the client cannot connect (i.e. connack rc != 0) or when a parsing error occurs. The following TLS errors will be emitted as an error event:

• ECONNREFUSED
• ECONNRESET
• EADDRINUSE
• ENOTFOUND

Kind: event emitted by VrpcClient

---

"end"

Event 'end'

Emitted when mqtt.Client#end() is called. If a callback was passed to mqtt.Client#end(), this event is emitted once the callback returns.

Kind: event emitted by VrpcClient

---

VrpcNative

Client capable of creating proxy classes and objects to locally call functions as provided through native addons.

Kind: global class

• VrpcNative
  • new VrpcNative(adapter)
  • .getClass(className) ⇒
  • .delete(proxy) ⇒
  • .callStatic(className, functionName, ...args) ⇒
  • .getAvailableClasses() ⇒ Array.<String>

---

new VrpcNative(adapter)

Constructs a local caller object, able to communicate to natively added C++

Params

• adapter Object - An adapter object, typically loaded as native addon

---

vrpcNative.getClass(className) ⇒

Provides a proxy class to an existing one in the native addon

You can use the returned class in the usual way. Static function calls are forwarded to the native addon, as are any instantiations and member function calls.

Kind: instance method of VrpcNative
Returns: Proxy Class
Params

• className String - The name of the class

---

vrpcNative.delete(proxy) ⇒

Deletes a proxy object and its underlying instance

Kind: instance method of VrpcNative
Returns: True in case of success, false otherwise
Params

• proxy Object - A proxy object

---

vrpcNative.callStatic(className, functionName, ...args) ⇒

Secondary option to call a static function (when creation of a proxy class seems to be too much overhead)

Kind: instance method of VrpcNative
Returns: The output of the underlying static function
Params

• className String - The class on which the static function should be called
• functionName String - Name of the static function
• ...args any - The function arguments

---

vrpcNative.getAvailableClasses() ⇒ Array.<String>

Retrieves an array of all available classes (names only)

Kind: instance method of VrpcNative
Returns: Array.<String> - Array of class names

---

MetaData : Object.<String, Func>

Associates meta data to any function

Kind: global typedef

---

Func

Kind: global typedef
Params

• description String - Function description
• params Array.<Param> - Array of parameter details in order of signature
• ret Ret - Object associating further information to return value

---

Param : Object

Kind: global typedef
Params

• name String - Parameter name
• optional Boolean - Whether parameter is optional
• description String - Parameter description
• [type] String - Parameter type
• [default] Any - The default to be injected when not provided

---

Ret : Object

Kind: global typedef
Params

• description String - Return value description
• [type] String - Return value type

---