Runtime Editor Comms protocol

Nick O'Leary edited this page Mar 9, 2018 · 3 revisions

The editor establishes a WebSocket connection back to the runtime in order to receive realtime events. It is not used to send control messages to the runtime; it is used for send events to the editor. Any sort of control message is done via the HTTP API.

This page documents the protocol used.

Message structure

All messages passed over the WebSocket are simple JSON strings. Aside from the authentication messages, each message has a topic and data property.


If adminAuth is enabled in the runtime, the WebSocket connection must go through an application-level authentication flow before any other data can be sent or received.

After the WebSocket connection is established, the editor must send an auth packet containing its auth token.

Editor  --->   { auth: "<auth-token>" }   ---> Runtime

The Runtime checks the token and if it is valid and returns:

Editor  <---   { auth: "ok" }   <--- Runtime

If the token is invalid, it returns the following packet and closes the websocket:

Editor  <---   { auth: "fail" }   <--- Runtime

If adminAuth is enabled and the first packet the received is not an auth packet, the runtime checks whether adminAuth has been configured with a default user and whether that user has the necessary permissions. If not, the connection is closed. In either case, no auth response packet is sent.

Subscribe events

After the editor establishes its comms link (and completes authentication) it then sends a set of 'subscribe' packets for the topics it cares about.

The original concept was for it to use very light-weight MQTT-like semantics for doing publish/subscribe. In reality, we never had a requirement for when an editor would unsubscribe from a topic. The end result is the editor will receive all messages regardless of whether they are subscribed or not.

But what the subscribe message does do is trigger the runtime to send any retained messages on those topics. This allows the editor to receive the last-known state for certain topics.

Editor  --->   { subscribe: "<topic>" }   ---> Runtime

The topic can use MQTT wildcards; + and # to pattern match.

Runtime events


Status events come from individual nodes calling the Node Status API

Editor  <---   { topic: "status/<node-id>", data: {<node-status object>} }   <--- Runtime

The topic includes the ID of the node. The data payload is the status object described in the Node Status API.


Notification events come from the runtime and indicate an event or change of state within the runtime.

Editor  <---   { topic: "notification/<event-id>", data: {<notification data>} }   <--- Runtime

The current list of runtime notifications is as follows. TODO: document each of their payload formats.

  • node/enabled - a node-set has been enabled via /node admin api
  • node/disabled - a node-set has been disabled via /node admin api
  • node/added - a node-set has been added via /node admin api
  • node/removed - a node-set has been removed via /node admin api
  • node/upgraded - a node-set has been upgraded via /node admin api
  • project-update - the active project has been updated and should be refreshed in the editor
  • restart-required - the runtime requires a manual restart - normally due to removing or upgrading a node
  • runtime-redeploy - new flows have been deployed to the runtime
  • runtime-state - a change to the state of the runtime. If the runtime has stopped due to an error state, the payload will have an error property to indicate the cause. Possible values are:
    • credentials_load_failed - failed to decrypt the credentials file
    • missing-types - the flow uses node types that are not present in the runtime
    • git_merge_conflict - the active project is in the middle of a merge conflict
    • missing_flow_file - the active project does not identify a flow file to use
    • project_empty - the active project is empty
  • runtime-unsupported-version - the node.js is old. Too Old.


The Debug node is an example of a node that makes use of Comms. In general we have not documented or encouraged 3rd party nodes to use comms.

The Debug node will publish a message when it receives a message within a flow. It also registers a log handler and publishes any WARN or ERROR messages so they will appear in the debug sidebar.

Debug messages are published to the debug topic.

Editor  <---   { topic: "debug", data: {<debug message>} }   <--- Runtime

The full format of the Debug message needs documenting.

   id: <debug node id>,
   name: <debug node name, if set>,
   topic: <msg.topic, if set>,
   msg: <the msg being passed to debug>,

Some further encoding of the msg being passed to Debug is done. It handles Buffers and other non-JSON encodable types, and also truncates big objects whilst maintaining their metadata so the Debug sidebar can indicate how big they were before being truncated.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.