frodovdr/node-red
1
0
Fork 0
mirror of https://github.com/node-red/node-red.git synced 2023-10-10 13:36:53 +02:00
Code Issues Releases Wiki Activity
Page: Runtime Editor Comms protocol
Pages
API Reference Architecture Overview Architecture: Cluster Multi Process Contribution Process Dashboard layout tool Definitions Deprecated: Message properties overriding set node properties Design Notes Design: dynamic palette Design: API Token management Design: CLI tool to produce a node skeleton Design: Concurrent editing Design: Custom Node admin route handling Design: Dynamic MQTT node Design: Dynamic node's icon Design: Editable port labels Design: Editor Events Design: Editor Themes Design: Editor UI Customisation Design: Encryption of credentials Design: Enhancements to Split Join nodes Design: Flow Linter Design: Flow Manipulation API Design: Flow file format v2 Design: Function Library node Design: Library Sidebar Design: Logging Framework Design: Node Generator Design: Node Messaging API Design: Node blacklist whitelist function Design: Node module lifecycle Design: Node settings Design: Palette Management UI Design: Persistable Context Design: Platform Specific Nodes Design: Projects Design: Runnable Project Design: Runtime Editor Split Design: Runtime Events Design: Runtime extension points Design: Subflow Enhancements Design: Subflow Instance properties Design: Subflow Node modules Design: Usage telemetry Design: Using environment variables Design: Version Control Design: adminAuth User Management Design: external file for function and templates nodes Design: i18n de Design: i18n Design: msg.parts description of usage Design: multiuser Design: subflows vNext Design: subflows Design:Shared Global Context Editor Mouse Actions Editor Runtime API Flow Format Flow testing Home Input node feature definitions Live runtime information Node Design Guidelines Node documentation guide Node msg Conventions Output node feature definitions Pluggable Message Routing Query node feature definitions ReadMe Raspberry Pi Advanced Runtime Editor Comms protocol Technical Interchange 2018 04 13 Technical Interchange Meetings Testing UI testing Watch node feature definitions Web Nodes outline adminAuth Credential Authentication dynamic palette join in auto mode npm installable nodes
3 Runtime Editor Comms protocol
Nick O'Leary edited this page 2018-03-09 13:04:20 +00:00
Table of Contents

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.

Authentication

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

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.

Notifications

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.

Debug

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.