Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 26 additions & 13 deletions docs/user/projectnodes.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
navTitle: FlowFuse Project Nodes
meta:
description: Send messages and call flows between Node-RED instances in a team with the Project In, Out and Call nodes, and the limits for remote instances.
description: Send messages and call flows between Node-RED instances and remote instances in a team or application with the Project In, Out and Call nodes.
---

# FlowFuse Project Nodes
Expand All @@ -12,8 +12,7 @@ instances in a team.

The nodes act in a similar way to the Node-RED Link nodes, but by allowing the
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.
possibilities. Remote instances can take part too.

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
Expand Down Expand Up @@ -53,18 +52,32 @@ 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
### Applications

The list of targets and sources offered by the nodes is grouped by application,
and can be filtered to a single application. It contains the hosted instances in
your team and the remote instances assigned to an application.

Broadcast messages are sent on one of two channels:

- **Team broadcast** - received by any instance or remote instance in the team
whose `Project In` node listens for team broadcasts. This is the default.
- **Application broadcast** - only received by instances and remote instances in
the same application whose `Project In` node listens for application broadcasts.
Instances outside the application cannot send or receive these messages.

**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.
The channels are separate. A `Project In` node listening for team broadcasts does
not receive application broadcasts, even from an instance in the same application.

Received messages include `msg.projectLink.applicationId`, the application of the
sender, and for broadcasts `msg.projectLink.scope`, the channel it was sent on.

### Limitations

**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.
**Remote instances assigned to an instance are reached through that instance.** They
share the identity of the instance they are assigned to, so they are not listed
separately. A message or call sent to the instance is also received by its remote
instances that are listening on the same topic.

**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
Expand Down
60 changes: 60 additions & 0 deletions forge/comms/aclManager.js
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,9 @@ module.exports = function (app) {
// check to see if the device is assigned to something?
const assignedTo = await app.db.models.Device.getOwnerTypeAndId(ids[2])
if (assignedTo && assignedTo.ownerType && assignedTo.ownerId) {
if (acl.deviceOwnerType && acl.deviceOwnerType !== assignedTo.ownerType) {
return false // rule does not apply to this type of device owner
}
return true
}
return false
Expand Down Expand Up @@ -132,6 +135,63 @@ module.exports = function (app) {
return false
}
},
checkClientInApplication: async function (requestParts, usernameParts, acl) {
// requestParts = [ _ , <teamid>, <applicationid>, <sourceid> ]
// the regex match of the requested topic (ff/v1/<team>/a/<application>/p/<source>/out/...),
// i.e. what the client is asking to sub/pub to
// usernameParts = [ 'project', <teamid>, <projectid> ] or [ 'device', <teamid>, <deviceid> ]
// the connecting client's broker username split on ':'
//
// Used by 4 ACLs (2 project, 2 device), all on the topic ff/v1/<team>/a/<application>/p/<source>/out/+/#
// a = the application the broadcast is scoped to
// p = the sender: an instance id, or dev:<deviceid> for an application owned device
//
// Receive application scoped broadcasts (project sub, device sub - ff/v1/<team>/a/<application>/p/+/out/+/#):
// A project node in application A may only receive broadcasts scoped to application A, i.e. the
// client (instance, or device via its owner) must belong to <application>. Any sender in A is allowed.
//
// Send application scoped broadcasts (project pub, device pub - ff/v1/<team>/a/<application>/p/<source>/out/+/#):
// As above, the client must belong to <application>, and acl.checkSource also requires <source>
// to be the client itself so it cannot publish as another member:
// - instance: <source> = its instance id
// - instance owned device: <source> = its owning instance's id (it broadcasts as its instance)
// - application owned device: <source> = dev:<deviceid>

// Do the simple team id check
if (requestParts[1] !== usernameParts[1]) {
return false
}
let applicationId
let sourceId
try {
if (usernameParts[0] === 'project') {
applicationId = await app.db.models.Project.getProjectApplicationId(usernameParts[2])
sourceId = usernameParts[2]
} else if (usernameParts[0] === 'device') {
const assignedTo = await app.db.models.Device.getOwnerTypeAndId(usernameParts[2])
if (assignedTo?.ownerType === 'instance') {
// An instance owned device is part of its instance's application
// and broadcasts using its instance id
applicationId = await app.db.models.Project.getProjectApplicationId(assignedTo.ownerId)
sourceId = assignedTo.ownerId
} else if (assignedTo?.ownerType === 'application') {
applicationId = assignedTo.ownerId
sourceId = `dev:${usernameParts[2]}`
}
}
} catch (err) {
// Any error likely means an id isn't a valid uuid - which
// postgres with throw over, unlike sqlite that returns no results.
return false
}
if (!applicationId || applicationId !== requestParts[2]) {
return false // not a member of this application
}
if (acl.checkSource && requestParts[3] !== sourceId) {
return false // can only publish as itself
}
return true
},
checkTeamUserSession: async function (requestParts, usernameParts) {
// requestParts = [ fullTopic , <teamHash> [, <userHash>] ] - v1
// requestParts = [ fullTopic , <teamHash>, <userHash>, <sessionId> ] - v2 (MCP)
Expand Down
11 changes: 11 additions & 0 deletions forge/db/models/Project.js
Original file line number Diff line number Diff line change
Expand Up @@ -727,6 +727,17 @@ module.exports = {
return project.TeamId
}
},
getProjectApplicationId: async (id) => {
const project = await this.findOne({
where: { id },
attributes: [
'ApplicationId'
]
})
if (project && project.ApplicationId) {
return M.Application.encodeHashid(project.ApplicationId)
}
},
generateCredentialSecret () {
return crypto.randomBytes(32).toString('hex')
},
Expand Down
66 changes: 62 additions & 4 deletions forge/ee/lib/projectComms/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,24 @@ module.exports.init = function (app) {
'pub',
{ topic: /^ff\/v1\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkTeamAndObjectIds' }
)
// Receive application scoped broadcasts from members of this project's application
// - ff/v1/<team>/a/<application>/p/+/out/+/#
// a = the application the broadcast is scoped to (must be this project's application)
// p = the sender: an instance id, or dev:<deviceid> for an application owned device
app.comms.aclManager.addACL(
'project',
'sub',
{ topic: /^ff\/v1\/([^/]+)\/a\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkClientInApplication', shared: true }
)
// Send application scoped broadcast messages
// - ff/v1/<team>/a/<application>/p/<project>/out/+/#
// a = this project's application
// p = this project's id (the sender)
app.comms.aclManager.addACL(
'project',
'pub',
{ topic: /^ff\/v1\/([^/]+)\/a\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkClientInApplication', checkSource: true }
)

// Device ACL

Expand All @@ -61,12 +79,19 @@ module.exports.init = function (app) {
'sub',
{ topic: /^ff\/v1\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkDeviceIsAssigned' }
)
// Receive messages sent to this device
// Receive messages sent to this device (instance owned)
// - ff/v1/<team>/p/<project>/in/+/#
app.comms.aclManager.addACL(
'device',
'sub',
{ topic: /^ff\/v1\/([^/]+)\/p\/([^/]+)\/in\/[^/]+($|\/.*$)$/, verify: 'checkDeviceCanAccessProject' }
{ topic: /^ff\/v1\/([^/]+)\/p\/(?!dev:)([^/]+)\/in\/[^/]+($|\/.*$)$/, verify: 'checkDeviceCanAccessProject' }
)
// Receive messages sent to this device (app owned)
// - ff/v1/<team>/p/dev:<deviceid>/in/+/#
app.comms.aclManager.addACL(
'device',
'sub',
{ topic: /^ff\/v1\/([^/]+)\/p\/dev:([^/]+)\/in\/[^/]+($|\/.*$)$/, verify: 'checkDeviceIsAssigned', deviceOwnerType: 'application' }
)
// Receive link-call response messages sent to this device (instance owned)
// - ff/v1/<team>/p/<project>/res/+/#
Expand All @@ -89,6 +114,13 @@ module.exports.init = function (app) {
'pub',
{ topic: /^ff\/v1\/([^/]+)\/p\/(?!dev:)([^/]+)\/in\/[^/]+($|\/.*$)/, verify: 'checkDeviceCanAccessProject', deviceOwnerType: 'instance' }
)
// Send message to specific app owned device
// - ff/v1/<team>/p/dev:<deviceid>/in/+/#
app.comms.aclManager.addACL(
'device',
'pub',
{ topic: /^ff\/v1\/([^/]+)\/p\/dev:([^/]+)\/in\/[^/]+($|\/.*$)/, verify: 'checkDeviceIsAssigned' }
)
// Send broadcast messages (from instance owned devices in the team)
// - ff/v1/<team>/p/<project>/out/+/#
app.comms.aclManager.addACL(
Expand All @@ -104,11 +136,37 @@ module.exports.init = function (app) {
{ topic: /^ff\/v1\/([^/]+)\/p\/dev:([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkDeviceIsAssigned', deviceOwnerType: 'application' }
)
// Send link-call response messages back to source instance
// - ff/v1/<team>/p/+/res/+/#
// - ff/v1/<team>/p/+/res[-id]/+/#
app.comms.aclManager.addACL(
'device',
'pub',
{ topic: /^ff\/v1\/([^/]+)\/p\/(?!dev:)([^/]+)\/res(?:-[^/]+)?\/[^/]+($|\/.*$)/, verify: 'checkDeviceCanAccessProject', deviceOwnerType: 'instance' }
)
// Send link-call response messages back to source app owned device
// - ff/v1/<team>/p/dev:<deviceid>/res/+/#
app.comms.aclManager.addACL(
'device',
'pub',
{ topic: /^ff\/v1\/([^/]+)\/p\/dev:([^/]+)\/res\/[^/]+($|\/.*$)/, verify: 'checkDeviceIsAssigned' }
)
// Receive application scoped broadcasts from members of this device's application
// - ff/v1/<team>/a/<application>/p/+/out/+/#
// a = the application the broadcast is scoped to (must be this device's application)
// p = the sender: an instance id, or dev:<deviceid> for an application owned device
app.comms.aclManager.addACL(
'device',
'sub',
{ topic: /^ff\/v1\/([^/]+)\/a\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkClientInApplication' }
)
// Send application scoped broadcast messages
// - ff/v1/<team>/a/<application>/p/<project | dev:deviceid>/out/+/#
// a = this device's application (via its instance, if instance owned)
// p = the sender: the owning instance's id for an instance owned device,
// or dev:<deviceid> for an application owned device
app.comms.aclManager.addACL(
'device',
'pub',
{ topic: /^ff\/v1\/([^/]+)\/p\/(?!dev:)([^/]+)\/res\/[^/]+($|\/.*$)/, verify: 'checkDeviceCanAccessProject', deviceOwnerType: 'instance' }
{ topic: /^ff\/v1\/([^/]+)\/a\/([^/]+)\/p\/([^/]+)\/out\/[^/]+($|\/.*$)/, verify: 'checkClientInApplication', checkSource: true }
)

// Team Broker ACLS - pub/sub to common topic space
Expand Down
1 change: 1 addition & 0 deletions forge/ee/routes/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,7 @@ module.exports = async function (app) {
await app.register(require('./pipeline'), { prefix: '/api/v1', logLevel: app.config.logging.http })
await app.register(require('./pipeline/teamPipelines.js'), { prefix: '/api/v1/teams/:teamId/pipelines', logLevel: app.config.logging.http })
await app.register(require('./deviceEditor'), { prefix: '/api/v1/devices/:deviceId/editor', logLevel: app.config.logging.http })
await app.register(require('./projectLink'), { prefix: '/api/v1/teams/:teamId/project-link', logLevel: app.config.logging.http })

await app.register(require('./flowBlueprints'), { prefix: '/api/v1/flow-blueprints', logLevel: app.config.logging.http })

Expand Down
Loading
Loading