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

Runtimes

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

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:

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:

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

protocol:network

can control and introspect its running networks using the Network protocol. DEPRECATED. Instead the individual network:... capabilities should be used. Implies capabilities network:status, network:data, network:control. Does not imply capability network:persist.

input messages
output messages

network:persist

can *flash* a running graph setup to the runtime, making it persistent across restarts

input messages
output messages

network:status

can get and follow changes to network status

input messages
output messages

network:data

can listen to data flowing through the network and processes

input messages
output messages

network:control

can start and stop networks

input messages
output messages

protocol:component

can list components of the runtime using the component:list message.

input messages
output messages

component:getsource

read and send component source code back to client

input messages
output messages

component:setsource

runtime is able to compile and run custom components sent as source code strings

input messages
output messages

protocol:runtime

can expose ports of main graph and transmit packet information to/from them

input messages
output messages

graph:readonly

read and follow changes to runtime graphs (but not modify)

input messages
output messages

protocol:graph

read & modify runtime graphs using the Graph protocol.

input messages
output messages

protocol:trace

runtime is able to record and send over flowtraces, used for retroactive debugging.

input messages
output messages

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:

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.

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.

error

Error response to a command on runtime protocol

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.

runtime

Response from the runtime to the getruntime request.

Graph protocol

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

clear

Initialize an empty graph.

addnode

Add node to a graph.

removenode

Remove a node from a graph.

renamenode

Change the ID of a node in the graph

changenode

Change the metadata associated to a node in the graph

addedge

Add an edge to the graph

removeedge

Remove an edge from the graph

changeedge

Change an edge's metadata

addinitial

Add an IIP to the graph

removeinitial

Remove an IIP from the graph

addinport

Add an exported inport to the graph.

removeinport

Remove an exported port from the graph

renameinport

Rename an exported port in the graph

addoutport

Add an exported outport to the graph.

removeoutport

Remove an exported port from the graph

renameoutport

Rename an exported port in the graph

addgroup

Add a group to the graph

removegroup

Remove a group from the graph

renamegroup

Rename a group in the graph.

changegroup

Change a group's metadata

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.

getsource

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

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.

error

Error response to a command on component protocol

component

Transmit the metadata about a component instance.

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.

getstatus

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

stop

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

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.

debug

Set a network into debug mode

edges

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

stopped

Inform that a given network has stopped.

started

Inform that a given network has been started.

status

Response to a getstatus message.

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

error

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

processerror

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

icon

Icon of a component instance has changed.

connect

Beginning of transmission on an edge.

begingroup

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

data

Data transmission on an edge.

endgroup

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

disconnect

End of transmission on an edge.

Trace protocol

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

start

Tracing was started

stop

Tracing was stopped

dump

undefined

clear

Tracing buffer was cleared