From 58cd83bd963aa5bf4b6fe96a7a5d6bea5d28e435 Mon Sep 17 00:00:00 2001 From: Dimitrie Hoekstra Date: Wed, 5 Aug 2026 13:57:28 +0200 Subject: [PATCH] docs: document the project node limitations The page presents calling a shared instance's flows as the headline use case without stating that only hosted instances can be addressed directly, that a remote instance can send but never receive, or that a call waits 30 seconds for a target that has to be running. Also fixes a typo and the implication that remote instances are symmetric peers. --- docs/user/projectnodes.md | 33 ++++++++++++++++++++++++++++++--- 1 file changed, 30 insertions(+), 3 deletions(-) diff --git a/docs/user/projectnodes.md b/docs/user/projectnodes.md index acf3f49f4b..362ec93160 100644 --- a/docs/user/projectnodes.md +++ b/docs/user/projectnodes.md @@ -9,12 +9,15 @@ very quick and easy to securely send and receive messages between different instances in a team. The nodes act in a similar way to the Node-RED Link nodes, but by allowing the -links to extended between different instances and devices, they open up a wide -range of possibilities. +links to extend between different instances, they open up a wide range of +possibilities. Remote instances can take part too, with the limitations described +below. For example, a single Node-RED instance may contain a set of utility flows that you want to reuse in other instances. Rather than copy the flows around, the -Project Nodes allow you to easily call those flows and get the result back. +Project Nodes allow you to easily call those flows and get the result back. The +flows stay in one place, so a change to them applies to every caller at once, +with the trade-offs covered in [Limitations](#limitations). The project nodes are only available in the Enterprise tier of FlowFuse. @@ -48,6 +51,30 @@ and then wait for a response, with a built-in timeout if it doesn't arrive. The response is sent back using a Project Out node configured to respond to the call node. +### Limitations + +**Only hosted instances can be addressed directly.** The list of targets and sources +offered by the nodes is the hosted instances in your team. This applies to the +`Project Out` node when sending to a specific instance, the `Project In` node when +listening to a specific source, and the `Project Call` node's target. + +**A remote instance can send, but cannot be sent to.** Flows on a remote instance can +use `Project Out` and `Project Call` to reach a hosted instance, and can receive +broadcasts. They cannot be named as a target, so shared logic being called by others +has to live on a hosted instance. A remote instance assigned to an application cannot +receive direct messages at all, and can only listen for broadcasts. + +**Calls need the target to be up.** The `Project Call` node waits for the default +timeout of 30 seconds, then logs an error that can be caught with a Catch node. The +target instance must be running and have a `Project In` node listening on the same +topic. Because every call travels through the platform's broker, logic called this +way is unavailable to a caller whose connection to the platform is down. + +**Load is shared only in HA mode.** The instance holding the called flows serves every +caller from a single Node-RED runtime. In [High Availability mode](./high-availability.md) +the nodes automatically switch to MQTT shared subscriptions, so calls are distributed +between the copies. + ### GitHub The nodes are published under an Apache-2.0 license and available on [GitHub](https://github.com/FlowFuse/nr-project-nodes).