FBP Network Protocol

The Flow-Based Programming network protocol (FBP protocol) has been designed primarily for flow-based programming interfaces like the Flowhub to communicate with various FBP runtimes. However, it can also be utilized for communication between different runtimes, for example server-to-server or server-to-microcontroller.

Implementations

Clients

• noflo-ui is an open source visual IDE, which powers Flowhub
• fbp-spec is a data-driven testing tool for FBP components/graphs.
• fbp-protocol-client is a low-level JavaScript client library supporting all the common FBP protocol transports
• fbp-client is a higher-level JavaScript client library supporting all the common FBP protocol transports

Runtimes

• noflo-runtime-base is a transport-independent implementation of the protocol for NoFlo, client-side and server-side JavaScript programming. WebSocket, WebRTC and iFrame implementations exists.
• microflo is a WebSocket implementation of the protocol in JS/C++, for microcontrollers and embedded systems
• Elixir FBP is a WebSocket implementation in Elixir, for programming with systems in Elixir runnin on the Erlang VM.
• imgflo is a WebSocket implementation in C, for image processing
• javafbp-runtime is a Websocket implementation in Java for JavaFBP, for JRE and Android development
• sndflo is a WebSocket implementation for the SuperCollider audio programming environment
• MsgFlo is a Websocket implementation in Node.js for heterogenous distributed systems communicating via message queues
• rill is a Python FBP runtime implementation, with support for the protocol over WebSocket.

Some examples have also been created, to help implementors.

Test suite

The fbp-protocol tool provides a set of tests for FBP protocol implementations.

Changes

• 2018-03-27:
  • Added schema for network:edges output message
  • Modified subgraph key of network:data and other network packet events to be an array as specified in the text
• 2018-03-26:
  • Fixed documentation for component:setsource to use component:source input, and component:component output
  • Added schema for trace:error message
  • Added :error output to all capabilities where user can perform actions that may fail
• 2018-03-23:
  • Added optional graph key to network:error payloads
• 2018-03-22: Version 0.7
  • Added network:debug and network:getstatus to the network:control permission
• 2018-03-21:
  • Fixed signature of runtime:packet.payload, runtime:packetsent.payload, and port definition default to accept any payload type
  • Added values and default keys for port definitions
  • Added schema for component:componentsready output message
  • Added schema for graph:clear output message
  • Added packetsent response for runtime:packet input message
• 2017-09-17:
  • Added schema support for ports and packets
  • Documented known metadata keys for various graph entities
• 2017-04-09: Version 0.6
  • Version 0.6. No breaking changes over 0.5.
  • Added additional capabilities graph:readonly, network:control, network:data, network:status. Especially useful for read-only access.
  • Deprecated the protocol:network capability in favor of the new fine-gained network:* capabilities.
  • Each capability now defines the set of messages contained in it. Available as inputs and outputs in the schema /shared/capabilities.
• 2017-05-04:
  • Fixed protocol errors (graph:error, component:error and runtime:error) to have mandatory message string payload.
  • Fixed missing required markers in some JSON schemas for graph protocol. Affected messages: graph:renamegroup, graph:renameinport, graph:removeinport, graph:addinitial, graph:changeedge
  • More readable HTML output, including property value types and examples
• 2017-05-03:
  • Added more optional metadata to runtime:runtime message: repository, repositoryVersion and namespace
• 2017-02-20:
  • Fixed payload definition of network:edges missing mandatory graph key
• 2016-07-01:
  • network:error payload may now contain an optional stacktrace
• 2016-06-23:
  • Trace subprotocol also available in machine-readable format
• 2016-06-17:
  • Protocol definition available as machine-readable JSON schemas.
  • The human-readable HTML documentation is generated from this defintion.
  • The npm package fbp-protocol contains the schemas as YAML, JSON and .js modules.
• 2015-11-20:
  • Initial trace subprotocol, for Flowtrace support
• 2015-03-27:
  • Documented network persist and component componentsready messages
• 2015-03-26: Version 0.5
  • All messages sent to runtime should include the secret in payload
  • Runtime description message includes an allCapabilities array describing capabilities of the runtime, including ones not available to current user
• 2014-10-23
  • added clarifications to network running state in status, started, and stopped messages
• 2014-09-26
  • Add secret as payload to getruntime to support access levels
• 2014-08-05:
  • Add get, list, graph, graphsdone commands to the graph protocol
  • Add list, network commands to the network protocol
• 2014-07-15:
  • Add changenode, changeedge, addgroup, removegroup, renamegroup, changegroup commands to the graph protocol
• 2014-03-13: Version 0.4
  • Capability discovery support
  • Network exported port messaging for remote subgraphs
• 2014-02-18: Version 0.3
  • Support for exported graph ports
• 2014-01-09: Version 0.2
  • Multi-graph support via the graph key in payload
  • Harmonization with JSON format by renaming from/to in edges to src/tgt
  • Network edges message

Basics

The FBP protocol is a message-based protocol that can be handled using various different transport mechanisms. The messages are designed to be independent, and not to form a request-response cycle in order to allow highly asynchronous operations and situations where multiple protocol clients talk with the same runtime.

There are currently three transports utilized commonly:

• Web Messaging (postMessage) for communication between different web pages or WebWorkers running inside the same browser instance
• WebSocket for communicating between a browser and a server, or between two server instances
• WebRTC for peer-to-peer communications between a runtime and a client

Different transports can be utilized as needed. It could be interesting to implement the FBP protocol using MQTT, for instance.

Sub-protocols

The FBP protocol is divided into sub-protocols for each of the major resources that can be manipulated:

• runtime: communications about runtime capabilities and its exported ports
• graph: communications about graph changes
• component: communications about available components and changes to them
• network: communications related to running a FBP graph
• trace: communications related to tracing a FBP network

Capabilities

Not all runtimes implementation supports all features of the protocol. Also, a runtime may restrict access to features, either to all clients based on configuration, or based on the secret provided in the messages. To support this a set of capabilities are defined, which are reported by the runtime in the runtime:runtime message.

When receiving a message, the runtime should check for the associated capability. If the capability is not supported, or the client does not have access to the capability, the runtime should respond with an error reply on the relevant protocol.

A few commands do not require any capabilities: the runtime info request/response (runtime:getruntime and runtime:runtime), and the error responses (runtime:error, graph:error, network:error, component:error).

Message structure

This document describes all messages as the data structures that are passed. The way these are encoded depends on the transport being used. For example, with WebSockets all messages are encoded as stringified JSON.

All messages consist of three parts:

• Sub-protocol identifier (graph, component, or network)
• Topic (for example, addnode)
• Message payload (typically a data structure specific to the sub-protocol and topic)

The keys listed in specific messages are for the message payload.

An example message

"protocol": "graph",
"command": "addnode",
"payload": {
	"component": "canvas/Draw",
	"graph": "hello-canvas-example",
	"id": "draw",
	"metadata": {
		"label": "Draw onto canvas element"
	}
}

Runtime protocol

When a client connects to a FBP procotol it may choose to discover the capabilities and other information about the runtime.

getruntime

Request the information about the runtime. When receiving this message the runtime should response with a runtime message. If the runtime is currently running a graph and it is able to speak the full Runtime protocol, it should follow up with a ports message.

• secretstringaccess token to authorize user

packet

Runtimes that can be used as remote subgraphs (i.e. ones that have reported supporting the protocol:runtime capability) need to be able to receive and transmit information packets at their exposed ports. These packets can be send from the client to the runtimes input ports, or from runtimes output ports to the client.

• portstringport name for the input or output port
• eventstringpacket event
• typestringThe basic datatype sent"array"
• schemastringLink to JSON schema describing the format of the data"https://example.net/schemas/person.json"
• graphstringgraph the action targets
• payloadanypayload for the packet. Used only with begingroup (for group names) and data packets
• secretstringaccess token to authorize user

error

Error response to a command on runtime protocol

• messagestringError message describing what went wrong

ports

Message sent by the runtime to signal its available ports. The runtime is responsible for sending the up-to-date list of available ports back to client whenever it changes.

• graphstringID of the currently configured main graph running on the runtime
• inPortsarraylist of input ports of the runtime
Each item contains:
• idstringport name
• typestringport datatype"boolean"
• schemastringLink to JSON schema for data on this port"https://example.net/schemas/person.json"
• requiredbooleanwhether the port needs to be connected for the component to worktrue
• addressablebooleanwhether the port is an ArrayPortfalse
• descriptionstringtextual description of the port
• valuesarraylist of values accepted for the port
• defaultanydefault value for the port
• outPortsarraylist of output ports of the runtime
Each item contains:
• idstringport name
• typestringport datatype"boolean"
• schemastringLink to JSON schema for data on this port"https://example.net/schemas/person.json"
• requiredbooleanwhether the port needs to be connected for the component to worktrue
• addressablebooleanwhether the port is an ArrayPortfalse
• descriptionstringtextual description of the port
• valuesarraylist of values accepted for the port
• defaultanydefault value for the port

runtime

Response from the runtime to the getruntime request.

• idstringunique runtime ID. Must be a UUID, version 4"f18a4924-9d4f-414d-a37c-cd24b39bba10"
• labelstringHuman-readable description of the runtime
• versionstringversion of the runtime protocol that the runtime supports"0.6"
• allCapabilitiesarraycapability strings for things the runtime is able to do. May include things not permitted for this client.
• capabilitiesarraycapability strings for things the runtime is able to do for this client.
• graphstringID of the currently configured main graph running on the runtime, if any"service-main"
• typestringtype of the runtime"microflo"
• namespacestringLibrary namespace of the project running on the runtime, if any. Must match that of components belonging to the (top-level) of project."my-project-foo"
• repositorystringSource-code repository URL of the project running on the runtime, if any"https://github.com/flowbased/fbp-protocol.git"
• repositoryVersionstringUnique version identifier of the source code of the project, if known. The version should be available in @repository."0.6.3-8-g90edcfc"

packetsent

Confirmation that a packet has been sent

• portstringport name for the input port
• eventstringpacket event
• typestringThe basic datatype sent"array"
• schemastringLink to JSON schema describing the format of the data"https://example.net/schemas/person.json"
• graphstringgraph the action targeted
• payloadanypayload for the packet. Used only with begingroup (for group names) and data packets

Graph protocol

This protocol is utilized for communicating about graph changes in both directions.

clear

Initialize an empty graph.

• idstringidentifier for the graph being created. Used for all subsequent messages related to the graph instance
• namestringHuman-readable label for the graph
• librarystringComponent library identifier
• mainbooleanIdentifies the graph as a main graph of a project that should not be registered as a component Graphs registered in this way should also be available for use as subgraphs in other graphs. Therefore a graph registration and later changes to it may cause component messages of the Component protocol to be sent back to the client informing of possible changes in the ports of the subgraph component.
• iconstringIcon to use for the graph when used as a component
• descriptionstringDescription to use for the graph when used as a component
• secretstringaccess token to authorize user

addnode

Add node to a graph.

• idstringidentifier for the node
• componentstringcomponent name used for the node
• metadataobjectstructure of key-value pairs for graph node metadata
• xintegerX coordinate of a graph entity
• yintegerY coordinate of a graph entity
• graphstringgraph the action targets
• secretstringaccess token to authorize user

removenode

Remove a node from a graph.

• idstringidentifier for the node
• graphstringgraph the action targets
• secretstringaccess token to authorize user

renamenode

Change the ID of a node in the graph

• fromstringoriginal identifier for the node
• tostringnew identifier for the node
• graphstringgraph the action targets
• secretstringaccess token to authorize user

changenode

Change the metadata associated to a node in the graph

• idstringidentifier for the node
• metadataobjectstructure of key-value pairs for graph node metadata
• xintegerX coordinate of a graph entity
• yintegerY coordinate of a graph entity
• graphstringgraph the action targets
• secretstringaccess token to authorize user

addedge

Add an edge to the graph

• srcobjectsource node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• tgtobjecttarget node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• metadataobjectstructure of key-value pairs for graph edge metadata
• routeintegerRoute identifier of a graph entity
• schemastringJSON schema associated with a graph entity
• securebooleanWhether graph entity data should be treated as secure
• graphstringgraph the action targets
• secretstringaccess token to authorize user

removeedge

Remove an edge from the graph

• graphstringgraph the action targets
• srcobjectsource node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• tgtobjecttarget node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• secretstringaccess token to authorize user

changeedge

Change an edge's metadata

• graphstringgraph the action targets
• metadataobjectstructure of key-value pairs for graph edge metadata
• routeintegerRoute identifier of a graph entity
• schemastringJSON schema associated with a graph entity
• securebooleanWhether graph entity data should be treated as secure
• srcobjectsource node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• tgtobjecttarget node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• secretstringaccess token to authorize user

addinitial

Add an IIP to the graph

• graphstringgraph the action targets
• metadataobjectstructure of key-value pairs for graph edge metadata
• routeintegerRoute identifier of a graph entity
• schemastringJSON schema associated with a graph entity
• securebooleanWhether graph entity data should be treated as secure
• srcobjectsource data for the edge
• dataobject,array,string,number,integer,boolean,nullIIP value in its actual data type
• tgtobjecttarget node/port for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• secretstringaccess token to authorize user

removeinitial

Remove an IIP from the graph

• srcobjectIIP data
• dataobject,array,string,number,integer,boolean,nullIIP value in its actual data type
• tgtobjecttarget node/port for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• graphstringgraph the action targets
• secretstringaccess token to authorize user

addinport

Add an exported inport to the graph.

• publicstringthe exported name of the port
• nodestringnode identifier
• portstringinternal port name
• metadataobjectstructure of key-value pairs for graph node metadata
• xintegerX coordinate of a graph entity
• yintegerY coordinate of a graph entity
• graphstringgraph the action targets
• secretstringaccess token to authorize user

removeinport

Remove an exported port from the graph

• publicstringthe exported name of the port to remove
• graphstringgraph the action targets
• secretstringaccess token to authorize user

renameinport

Rename an exported port in the graph

• fromstringoriginal exported port name
• tostringnew exported port name
• graphstringgraph the action targets
• secretstringaccess token to authorize user

addoutport

Add an exported outport to the graph.

• publicstringthe exported name of the port
• nodestringnode identifier
• portstringinternal port name
• metadataobjectstructure of key-value pairs for graph node metadata
• xintegerX coordinate of a graph entity
• yintegerY coordinate of a graph entity
• graphstringgraph the action targets
• secretstringaccess token to authorize user

removeoutport

Remove an exported port from the graph

• publicstringthe exported name of the port to remove
• graphstringgraph the action targets
• secretstringaccess token to authorize user

renameoutport

Rename an exported port in the graph

• fromstringoriginal exported port name
• tostringnew exported port name
• graphstringgraph the action targets
• secretstringaccess token to authorize user

addgroup

Add a group to the graph

• namestringthe group name
• nodesarrayan array of node ids part of the group
• metadataobjectstructure of key-value pairs for graph group metadata
• descriptionstringLonger textual description of the group
• graphstringgraph the action targets
• secretstringaccess token to authorize user

removegroup

Remove a group from the graph

• namestringthe group name
• graphstringgraph the action targets
• secretstringaccess token to authorize user

renamegroup

Rename a group in the graph.

• fromstringoriginal group name
• tostringnew group name
• graphstringgraph the action targets
• secretstringaccess token to authorize user

changegroup

Change a group's metadata

• namestringthe group name
• metadataobjectstructure of key-value pairs for graph group metadata
• descriptionstringLonger textual description of the group
• graphstringgraph the action targets
• secretstringaccess token to authorize user

Component protocol

Protocol for handling the component registry.

list

Request a list of currently available components. Will be responded with a set of `component` messages.

• secretstringaccess token to authorize user

getsource

Request for the source code of a given component. Will be responded with a `source` message.

• namestringName of the component to for which to get source code. Should contain the library prefix"my-project/SomeComponent"
• secretstringaccess token to authorize user

source

Source code for a component. In cases where a runtime receives a `source` message, it should do whatever operations are needed for making that component available for graphs, including possible compilation.

• namestringName of the component. Must not contain library prefix"MyComponent"
• languagestringThe programming language used for the component code"c++"
• librarystringComponent library identifier"components-common"
• codestringComponent source code
• testsstringunit tests for the component

error

Error response to a command on component protocol

• messagestringError message describing what went wrong

component

Transmit the metadata about a component instance.

• namestringcomponent name in format that can be used in graphs. Should contain the component library prefix."my-project/MyComponent"
• descriptionstringtextual description on what the component does
• iconstringVisual icon for the component, matching icon names in Font Awesome
• subgraphbooleanboolean telling whether the component is a subgraph
• inPortsarraylist of input ports of the component
Each item contains:
• idstringport name
• typestringport datatype"boolean"
• schemastringLink to JSON schema for data on this port"https://example.net/schemas/person.json"
• requiredbooleanwhether the port needs to be connected for the component to worktrue
• addressablebooleanwhether the port is an ArrayPortfalse
• descriptionstringtextual description of the port
• valuesarraylist of values accepted for the port
• defaultanydefault value for the port
• outPortsarraylist of output ports of the component
Each item contains:
• idstringport name
• typestringport datatype"boolean"
• schemastringLink to JSON schema for data on this port"https://example.net/schemas/person.json"
• requiredbooleanwhether the port needs to be connected for the component to worktrue
• addressablebooleanwhether the port is an ArrayPortfalse
• descriptionstringtextual description of the port
• valuesarraylist of values accepted for the port
• defaultanydefault value for the port

componentsready

Indication that a component listing has finished

Network protocol

Protocol for starting and stopping FBP networks, and finding out about their state.

start

Start execution of a FBP network based on a given graph.

• graphstringgraph the action targets
• secretstringaccess token to authorize user

getstatus

Get the current status of the runtime. The runtime should respond with a status message.

• graphstringgraph the action targets
• secretstringaccess token to authorize user

stop

Stop execution of a FBP network based on a given graph.

• graphstringgraph the action targets
• secretstringaccess token to authorize user

persist

Tells the runtime to persist the current state of graphs and components so that they are available between restarts. Requires the network:persist capability.

• secretstringaccess token to authorize user

debug

Set a network into debug mode

• enablebooleantells whether to put the network in debug mode
• graphstringgraph the action targets
• secretstringaccess token to authorize the user

edges

List of edges user has selected for inspection in a user interface or debugger, sent from UI to a runtime.

• graphstringgraph the action targets
• edgesarraylist of selected edges
Each item contains:
• srcobjectsource node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• tgtobjecttarget node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• secretstringaccess token to authorize user

stopped

Inform that a given network has stopped.

• timestringtime when the network was stopped
• uptimenumbertime the network was running, in seconds
• graphstringgraph the action targets
• runningbooleanwhether or not network is currently running
• startedbooleanwhether or not network has been started
• debugbooleanwhether or not network is in debug mode

started

Inform that a given network has been started.

• timestringtime when the network was started
• graphstringgraph the action targets
• startedbooleanwhether or not network has started running
• runningbooleanwhether or not network is currently running
• debugbooleanwhether or not network is in debug mode

status

Response to a getstatus message.

• graphstringgraph the action targets
• uptimenumbertime the network has been running, in seconds
• startedbooleanwhether or not network has started running
• runningbooleanboolean tells whether the network is running or not
• debugbooleanwhether or not network is in debug mode

output

An output message from a running network, roughly similar to STDOUT output of a Unix process, or a line of console.log in JavaScript. Output can also be used for passing images from the runtime to the UI.'

• messagestringcontents of the output line
• typestringtype of output, either message or previewurl
• urlstringURL for an image generated by the runtime

error

An error from a running network, roughly similar to STDERR output of a Unix process, or a line of console.error in JavaScript.'

• messagestringcontents of the error message
• stackstringstack trace
• graphstringgraph the action targets

processerror

When in debug mode, a network can signal an error happening inside a process.

• idstringidentifier of the node
• errorstringerror from the component
• graphstringgraph the action targets

icon

Icon of a component instance has changed.

• idstringidentifier of the node
• iconstringnew icon for the component instance
• graphstringgraph the action targets

connect

Beginning of transmission on an edge.

• idstringtextual edge identifier, usually in form of a FBP language line
• srcobjectsource node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• tgtobjecttarget node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• graphstringgraph the action targets
• subgrapharraySubgraph identifier for the event. An array of node IDs.

begingroup

Beginning of a group (bracket IP) on an edge.

• idstringtextual edge identifier, usually in form of a FBP language line
• srcobjectsource node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• tgtobjecttarget node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• graphstringgraph the action targets
• subgrapharraySubgraph identifier for the event. An array of node IDs.

data

Data transmission on an edge.

• idstringtextual edge identifier, usually in form of a FBP language line
• srcobjectsource node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• tgtobjecttarget node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• graphstringgraph the action targets
• subgrapharraySubgraph identifier for the event. An array of node IDs.

endgroup

Ending of a group (bracket IP) on an edge.

• idstringtextual edge identifier, usually in form of a FBP language line
• srcobjectsource node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• tgtobjecttarget node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• graphstringgraph the action targets
• subgrapharraySubgraph identifier for the event. An array of node IDs.

disconnect

End of transmission on an edge.

• idstringtextual edge identifier, usually in form of a FBP language line
• srcobjectsource node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• tgtobjecttarget node for the edge
• nodestringnode identifier
• portstringport name
• indexstring,numberconnection index, for addressable ports
• graphstringgraph the action targets
• subgrapharraySubgraph identifier for the event. An array of node IDs.

Trace protocol

This protocol is utilized for triggering and transmitting [Flowtrace](https://github.com/flowbased/flowtrace)s

start

Enable/start tracing of a network.

• secretstringaccess token to authorize the client
• graphstringGraph identifier the message targets
• buffersizeintegerSize of tracing buffer to keep. In bytes

stop

Stop/disable tracing of a network.

• secretstringaccess token to authorize the client
• graphstringGraph identifier the message targets

dump

undefined

• graphstringGraph identifier the message targets
• typestringString describing type of trace.
• flowtracestringA Flowtrace file of `type`

clear

Clear current tracing buffer.

• secretstringaccess token to authorize the client
• graphstringGraph identifier the message targets

error

Error response to a command on trace protocol

• messagestringError message describing what went wrong