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

• 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

Install this library via NPM:

$ 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.

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

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:

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

Send protocol messages:

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

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:

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

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

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

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

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

// 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']);
  });

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

• 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