README.md

FBP Network Protocol

Tests, schemas, and specifications for the Flow Based Programming Network Protocol.

You can find a built version of the specification at flowbased.github.io/fbp-protocol.

The included test suite provide an easy way for developers to test their runtimes for compatibility with the protocol. Also included are files useful to runtime developers, such as message schemas.

The test suite currently works for runtimes based on the Websocket transport.

Installing the test suite

1. Install Node.js using their installer or a package manager

2. Install this package.

   You can install it within your project, which will place the executables in ./node_modules/.bin:

   cd /path/to/my/project
   npm install fbp-protocol
   

   Or globally, which should put executables on the PATH:

   sudo npm install fbp-protocol -g
   

Testing a runtime

1. Before you can run the tests (successfully), your runtime needs to provide a few basic components. These are currently Repeat, Drop, and Output.

   By default, the tests will look for these in the "core" collection, however this is configurable. For example, if you want to implement these components as a one-off just for the tests, you can place them in a "tests" collection and pass --collection tests to fbp-init.

2. Use fbp-init to save a configuration file for your runtime into the current directory (keep in mind that if you used the local install method, you'll need to run ./node_modules/.bin/fbp-init). Use fbp-init -h to see the available options and their defaults.

   Here's an example:

   fbp-init --name protoflo --port 3569 --command "python -m protoflo runtime"
   

   This will produce the file fbp-protocol.json in the current directory. Its location within your project is not important, but it needs to be in the current working directory when you run the tests.

3. Run the tests:

   fbp-test
   

If the runtime execution requires a secret to be sent, define it using the FBP_PROTOCOL_SECRET environment variable.

Examples

A Node.js package using grunt: https://github.com/chadrik/noflo-runtime-websocket/tree/fbp-protocol

Contributing

JSON schemas are built from YAML schemas in schema/yaml. Improvements and additions to the schemas should be added there. The JSON schemas use json-schema to validate protocol messages. To run tests, use grunt test, which will run unit tests for the schemas and fbp-test. To build the schemas after updating the YAML files, run grunt build, which will create the JSON schemas, put them together for easy usage in schema/schemas.js, and update the docs with the latest schema definitions.

TODO

• handle fbp-test -h
• capture server output to a log
• isolate tests, so that one failure does not cause subsequent tests to fail
• don't test capabilities that the runtime does not claim to support (as returned by getruntime)
• add more tests:
  • getsource / source
  • topology restrictions
  • capturing output
  • existing tests from other projects:
    • https://github.com/jonnor/imgflo/blob/master/spec/websocket.coffee
    • https://github.com/jonnor/sndflo/blob/master/spec/runtime.coffee
    • https://github.com/jonnor/javafbp-runtime/blob/master/spec/protocol.coffee
    • https://github.com/microflo/microflo/blob/master/test/websocketapi.js
• add examples (https://github.com/flowbased/protocol-examples)
• add tests for fpb-test
• add separate, optional tests for "classical" or "noflo" behaviors
• use library for more flexible json comparison?
  • joi
  • chai-json-schema
• dynamically build tests based on sidecar json command / response files?
• validate options read from fbp-config.json
• make fbp-init prompt-based?
• allow fbp-test /path/to/fbp-config.json
• make init and test subcommands of a fbp command?