fbp-client

fbp-client
==========

This library provides a higher level client for interacting with FBP Protocol runtimes. Underneath it utilizes the transport abstractions provided by fbp-protocol-client.

Features

* Fully Promise-based API for interacting with the runtime
* Responses to requests sent to runtime are handled via Promise resolving or rejection
* Messages unrelated to current requests are provided via signal events
* Protocol API is autogenerated from FBP Protocol JSON schemas, ensuring that it changes up to date with protocol features
* All messages to and from runtime are validated against FBP Protocol specification

Installation

Install this library via NPM:

``shell
$ npm install fbp-client --save
`

Please note that this library is shipped as ES6 code and utilizes native JavaScript Promises. If needed, you can install a Promise polyfill and transpile the code to ES5.

Usage

Create a client instance for a FBP Protocol runtime definition with:

`javascript
const fbpClient = require('fbp-client');

fbpClient({
address: 'wss://localhost:3569',
protocol: 'websocket',
secret: 'keyboard-cat',
})
.then((client) => {
// Use this client instance for further interactions
});
`

Connect to runtime:

`javascript
client.connect()
.then(() => {
// Connected to runtime
});
`

Send protocol messages:

`javascript
client.protocol.runtime.packet({
graph: 'some-graph-id',
port: 'in',
event: 'data',
payload: 'Hello World!',
})
.then(() => {
// Packet was sent
});
`

Signals

Events coming from the runtime that are not direct responses to requests made by user are considered to be "signals". To subscribe to all signals coming from the client, use:

`javascript
client.on('signal', signal => console.log(signal));
`

You can also subscribe to signals for only one particular subprotocol with:

`javascript
// Only listen to network protocol
client.on('network', signal => console.log(signal));
`

Messages sent as responses to a request are not emitted as signals.

$3

It is also possible to work with signals in a promisifed way by using observers:

`javascript
// Register observer for all network events
const observer client.observe(['network:*']);
// Start the network
client.protocol.network.start({
graph: 'my-graph',
})
.then(() => {
// Receive all network signals on stopped, or failure with errors
return observer.until(['network:stopped'], ['network:error', 'network:processerror']);
});
`

Debugging

It is possible to see the internal workings of the library by setting the DEBUG environment variable to one or multiple of the following:

* fbp-client:adapter:signal: Signals received by the runtime
* fbp-client:adapter:request: Requests sent to the runtime
* fbp-client:adapter:response: Responses received by the runtime
* fbp-client:observer: Observer results
* fbp-client:observer:ignored: Signals ignored by an observer

Changes

* 0.4.3 (2020-10-02)
- Updated fbp-protocol-client to include improved connection error handling
* 0.4.2 (2020-09-29)
- Updated fbp-protocol-client to include WebRTC support also on Node.js
* 0.4.1 (2020-09-01)
- Updated fbp-protocol schemas to the latest versions
* 0.4.0 (2019-02-26)
- graph.properties.project is no longer sent as the graph's "library identifier"
* 0.3.3 (2018-04-06)
- Ensured that connection failures are sent as Error objects instead of WebSocket error events
* 0.3.2 (2018-03-29)
- Schema validation can be disabled with skipValidation: true option. Validation failures still cause protocolError events to be emitted but not longer fail requests or observers
- When sending graphs, the graph library property will be preferred as the library name
- disconnected event will fire also if the connection is lost by other means that calling disconnect()
* 0.3.1 (2018-03-26)
- Added connected and disconnected events
* 0.3.0 (2018-03-26)
- Added support for checking capabilities.
- Disallowed messages cause requests to be rejected
- Disallowed signals trigger protocol error
- Permission checking can be disabled with skipPermissions: true option
* 0.2.2 (2018-03-24)
- Fixed observer until failure handling on protocol validation errors
- Improved test coverage
* 0.2.1 (2018-03-23)
- Observer until` also fails on protocol validation errors
- Clearer observer error messages on error packets
* 0.2.0 (2018-03-23)
- Added support for promisified signal observation
- Added debugging support via the debug module
* 0.1.0 (2018-03-22)
- Initial version, support for FBP Protocol version 0.7 and earlier