Skip to content

Add application scoped project link topics and targets API - #9079

Merged
Steve-Mcl merged 4 commits into
mainfrom
project-link-app-aware
Nov 3, 2026
Merged

Steve-Mcl merged 4 commits into
mainfrom
project-link-app-aware

Conversation

@Steve-Mcl

@Steve-Mcl Steve-Mcl commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Description

Platform side of making project link nodes application aware (FlowFuse/nr-project-nodes#30).

Broker ACLs (forge/ee/lib/projectComms, forge/comms/aclManager.js)

New topics. Team broadcasts (ff/v1/<team>/p/<source>/out/...) are unchanged.

Topic Use
ff/v1/<team>/a/<application>/p/<source>/out/<subtopic> Application broadcast. <source> is an instance id, or dev:<device> for an application owned device. Instance owned devices publish as their instance.
ff/v1/<team>/p/dev:<device>/in/<subtopic> Direct message to an application owned device
ff/v1/<team>/p/dev:<device>/res/<subtopic> Call response to an application owned device
  • New checkClientInApplication verify: the client must belong to the application in the topic, and on publish <source> must be its own id.
  • checkDeviceIsAssigned now honours deviceOwnerType. Before, it only compared ids, so an instance owned device could match rules meant for application owned devices.
  • A device answering a call from an HA instance can now publish to p/<instance>/res-<id>/.... That was denied before.
  • The existing a/<application>/command and a/<application>/created|updated|deleted topics are two levels deep after the application id, so the new rules can't match them.

Targets endpoint (GET /api/v1/teams/:teamId/project-link/targets)

Returns the caller's own { id, applicationId } and the team's applications, each with its instances and application owned devices. Ids and names only, enforced by a response schema. Project and device tokens only (403 for users and PATs), 404 when Project Communication is disabled, and hidden from the API docs.

Why a new endpoint rather than GET /teams/:teamId/applications: the nodes use the targets endpoint to detect whether the platform supports application scoping. It ships in the same change as the ACLs, so a 200 means the broker will accept the new topics. Older platforms return 404 (or 200 with index.html before 2.8.0) and the nodes keep their current behaviour. A flag on /applications was considered, but that response is shaped for the frontend and may change (pagination, default includes), and it sends machine tokens far more than they need.

Docs: docs/user/projectnodes.md gets an Applications section. The "hosted instances only" and "can't send to a remote instance" limitations are removed.

Compatibility

  • The current release of the nodes (0.7.9) keeps working against this branch: direct, broadcast and call between hosted instances and devices, including an application owned device broadcasting as dev:<id>. Tested live with 0.7.9 on a hosted instance and on an application owned device.
  • The new nodes (feat: Make project link nodes application aware nr-project-nodes#296) fall back to their current behaviour on platforms without this change, so the two can be released in either order. Releasing this one first is recommended, so the new features work as soon as the nodes are updated.
  • No launcher or device agent changes.

Testing

  • Unit: 22 new ACL cases in authRoutes_spec.js, and 10 in the new projectLink/index_spec.js (fields returned, identity for each owner type, other team, user session, PAT, no credentials, feature disabled).
  • Manual, on a local install with hosted instances and remote instances in two applications: direct and call to application owned devices, both channels, channel separation, offline start of a remote instance, old nodes against this branch, and the new nodes against main (404 fallback).
  • HA not tested live (localfs).

Related Issue(s)

Closes #9077
Part of FlowFuse/nr-project-nodes#30

Checklist

  • I have read the contribution guidelines
  • Suitable unit/system level tests have been added and they pass
  • Documentation has been updated
    • Upgrade instructions
    • Configuration details
    • Concepts
  • Changes flowforge.yml?
    • Issue/PR raised on FlowFuse/helm to update ConfigMap Template
    • Issue/PR raised on FlowFuse/CloudProject to update values for Staging/Production
  • Link to Changelog Entry PR, or note why one is not needed. Changelog: Add changelog entry announcing application aware project link nodes website#5995 (to go out with the nodes release)

Labels

  • Includes a DB migration? -> add the area:migration label

@Steve-Mcl

Copy link
Copy Markdown
Contributor Author

6d0d53e fixes the failing Broker Auth v2 API > Device > EE > assigned to application > can publish broadcast with dev: topic prefix test.

The test was relying on old behaviour. The assigned to application setup only set application on the device. The device was still assigned to ProjectA from the previous describe, so it stayed instance owned. Before this PR, checkDeviceIsAssigned allowed any assigned device, so the test passed anyway. This PR adds an owner type check (deviceOwnerType: 'application' on the dev: broadcast rule), so an instance owned device is now correctly denied publishing as dev:<deviceid>.

The setup now clears the instance before assigning the application and asserts the device is application owned. This matches the change already made to the same test in authRoutes_spec.js.

@codecov

codecov Bot commented Oct 29, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 98.55072% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 79.88%. Comparing base (60b8c5d) to head (99c4656).

Files with missing lines Patch % Lines
forge/comms/aclManager.js 95.65% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main    #9079      +/-   ##
==========================================
+ Coverage   79.82%   79.88%   +0.06%     
==========================================
  Files         475      476       +1     
  Lines       26095    26164      +69     
  Branches     6955     6972      +17     
==========================================
+ Hits        20831    20902      +71     
+ Misses       5264     5262       -2     
Flag Coverage Δ
backend 79.88% <98.55%> (+0.06%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@Steve-Mcl

Copy link
Copy Markdown
Contributor Author

@andypalmi here is a suggested test plan for reviewing this locally.

Test plan (local dev-env)

Branches

In dev-env, hosted instances load the local nr-project-nodes through the launcher. Devices load it through the device-agent dev override (see "Starting the device agents" below).

Setup

  • A team on a tier with Project Communication (project nodes) enabled
  • Create 2 applications, "App Aware App A" and "App Aware App B"
  • Add instances
    • app-aware-instance-a in App Aware App A
    • app-aware-instance-b in App Aware App B
  • Add devices
    • "App Aware Device C", assigned to App Aware App A (application owned)
    • "App Aware Device D", assigned to app-aware-instance-a (instance owned). Instance owned devices only get the modules in their target snapshot, so take a snapshot of app-aware-instance-a with nr-project-nodes in its modules and set it as the device target
  • Use sub-topics without spaces (spaces are a separate bug, nr-project-nodes#294)

Prompting

If you use an AI assistant with the FlowFuse MCP server to build the setup, this prompt covers it:

In my FlowFuse team <team>, create two applications named "App Aware App A" and "App Aware App B". Create a hosted instance app-aware-instance-a in App Aware App A and app-aware-instance-b in App Aware App B, using the default stack and template. Create two devices: "App Aware Device C" assigned to App Aware App A, and "App Aware Device D" assigned to instance app-aware-instance-a. For each device, give me the device configuration (device.yml) so I can start a device agent. Then take a snapshot of app-aware-instance-a and set it as the target snapshot for its devices. Do not change or delete anything that already exists in the team. If an item with one of these names already exists, stop and tell me instead of reusing it.

Starting the device agents (macOS)

The agent only loads your local nr-project-nodes when NODE_ENV=development is set and nr-project-nodes sits next to device-agent in the same folder (as it does in dev-env's packages/).

  1. Make sure nr-project-nodes is on the PR branch and installed:
    cd <dev-env>/packages/nr-project-nodes
    git checkout project-link-app-aware
    npm install
  2. Install the device agent (current main is fine):
    cd <dev-env>/packages/device-agent
    npm install
  3. Create a working folder per device and save each device.yml from the assistant (or from the device's "Download configuration" in the UI) into it:
    mkdir -p ~/ff-app-aware/device-c ~/ff-app-aware/device-d
    # save App Aware Device C's config as ~/ff-app-aware/device-c/device.yml
    # save App Aware Device D's config as ~/ff-app-aware/device-d/device.yml
  4. Start each device in its own terminal, from the device-agent folder, on its own port:
    cd <dev-env>/packages/device-agent
    NODE_ENV=development node index.js -d ~/ff-app-aware/device-c -p 1890
    cd <dev-env>/packages/device-agent
    NODE_ENV=development node index.js -d ~/ff-app-aware/device-d -p 1891
  5. Once a device has its snapshot, check it is using the local nodes:
    grep nr-project-nodes ~/ff-app-aware/device-c/project/package.json
    # expect: "@flowfuse/nr-project-nodes": "file:<dev-env>/packages/nr-project-nodes"
    If it still shows a version number, the package.json was written before NODE_ENV was set. Restart the agent with NODE_ENV=development and deploy a new snapshot to the device (the agent only rewrites package.json on a snapshot update).
  6. Open each device's editor from FlowFuse (Device > "Developer Mode" > Open Editor) to build the test flows.

Checks

Editor

  1. On app-aware-instance-a, a Project Link Out node set to "send to a specific instance" has an application filter listing App Aware App A and App Aware App B
  2. The instance list is grouped by application and includes "App Aware Device C (remote)"
  3. App Aware Device D is not listed (instance owned devices are reached through their instance)
  4. A Project Link In node set to broadcast has a Channel option (Team / Application)

Direct messages to an application owned device (new)

Out node on app-aware-instance-a, direct to App Aware Device C, sub-topic direct. In node on Device C, "sent to this instance", sub-topic direct.

  1. Inject on app-aware-instance-a. Device C receives it
  2. msg.projectLink.applicationId is App Aware App A's id

Link call to an application owned device (new)

Call node on app-aware-instance-b, target App Aware Device C, sub-topic call. On Device C, an In node (call) wired to an Out node in "return" mode.

  1. Inject on app-aware-instance-b. The reply comes back to the Call node, no timeout
  2. A Call node on Device C targeting app-aware-instance-b also gets a reply

Application channel broadcast (new)

  • Out node on app-aware-instance-a, broadcast, Channel = Application, sub-topic app
  • Device C: In node, broadcast, Channel = Application, from all, sub-topic app
  • Device C: second In node, broadcast, Channel = Team, from all, sub-topic app
  • app-aware-instance-b: In node, broadcast, Channel = Application, from all, sub-topic app
  1. Inject on app-aware-instance-a. Device C's Application In receives it, with msg.projectLink.scope === "application"
  2. Device C's Team In does NOT receive it
  3. app-aware-instance-b does NOT receive it (different application)
  4. An Out node on Device D (Application channel) reaches Device C, and the source is app-aware-instance-a

Team broadcast (unchanged behaviour)

Out node on Device C, broadcast, Channel = Team, sub-topic team. In node on app-aware-instance-b, broadcast, Channel = Team, from all, sub-topic team.

  1. Inject on Device C. app-aware-instance-b receives it, with msg.projectLink.scope === "team"

Older nodes

  1. With nr-project-nodes main (current release) on an instance or device, existing team broadcasts and link calls work as before against this flowfuse branch
  2. An Out node saved with the Application channel, then run on the current release, shows "invalid target" and sends nothing (it does not fall back to a team broadcast)

@andypalmi

Copy link
Copy Markdown
Contributor

Thanks Steve, this works well locally. Setup: two applications, hosted instances in each, an application owned device, an instance owned device, a device in a device group and an unassigned device, with the nodes from FlowFuse/nr-project-nodes#296 plus one device on 0.7.9.

Works as described

  1. Direct messages and calls to and from application owned devices, in both directions.
  2. Application broadcasts reach instances and devices in the same application only, including an instance owned device, and team listeners do not receive them.
  3. 0.7.9 nodes keep working against this branch: team broadcasts and calls.

To address
4. #9083 needs to land together with this one. Can you confirm that's the plan? I ran 56 ACL cases against /api/comms/v2/acls. On this branch alone, 6 fail, all on the team channel:

  • an application owned device can subscribe to p/<instance>/in and p/<instance>/res of any instance in the team, including instances in other applications
  • an application owned device can publish p/<instance>/out, so it can broadcast as a hosted instance
  • an instance owned device can read another instance's inbox and broadcast as it

With #9083 checked out, all 56 pass. Without it, the application scoping this PR adds can be bypassed on the team channel.
5. Small one: the "Calls need the target to be up" paragraph appears twice, at docs/user/projectnodes.md#L82 and #L88.

@Steve-Mcl

Copy link
Copy Markdown
Contributor Author
  1. Limit project link device ACLs to the device's own instance #9083 needs to land together with this one. Can you confirm that's the plan? I ran 56 ACL cases against /api/comms/v2/acls. On this branch alone, 6 fail, all on the team channel:
  • an application owned device can subscribe to p/<instance>/in and p/<instance>/res of any instance in the team, including instances in other applications
  • an application owned device can publish p/<instance>/out, so it can broadcast as a hosted instance
  • an instance owned device can read another instance's inbox and broadcast as it

Yes. I have assigned you are reviewer. I'll switch it out of draft

@Steve-Mcl
Steve-Mcl added this pull request to stack #9085 October 30, 2026 17:08
@Steve-Mcl

Copy link
Copy Markdown
Contributor Author

Small one: the "Calls need the target to be up" paragraph appears twice, at docs/user/projectnodes.md#L82 and #L88.

done in last commit

@andypalmi andypalmi left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Retested the stack (#9079 + #9083) after the latest pushes: docs duplicate is gone, unit tests pass, and the full runtime matrix (direct, call, both broadcast channels, instance owned, application owned, device group and unassigned devices, 0.7.9 interop) behaves as described. Approving as part of the stack with #9083.

@Steve-Mcl

Copy link
Copy Markdown
Contributor Author

@andypalmi and I ran variation tests with 0.7.9 flows upgraded to 0.8.0 node and vice versa (and across instances with mixed version). Topics both ways continue to work as 0.7.9

Steve-Mcl and others added 4 commits November 3, 2026 10:47
Broker ACLs for application scoped project link broadcasts
(ff/v1/<team>/a/<application>/p/<source>/out/...) and for direct
messages and call responses to application owned devices
(ff/v1/<team>/p/dev:<device>/in|res/...).

New GET /api/v1/teams/:teamId/project-link/targets for project and
device tokens: the team's applications with their instances and
application owned devices, plus the caller's own identity. Ids and
names only, hidden from the API docs. The nodes use it to detect
platform support.

Also:
- checkDeviceIsAssigned honours deviceOwnerType
- a device can reply to a call from an HA instance (res-<id>)
@Steve-Mcl
Steve-Mcl force-pushed the project-link-app-aware branch from f2a0b1e to 99c4656 Compare November 3, 2026 10:47
@Steve-Mcl
Steve-Mcl enabled stacked auto-merge (squash) November 3, 2026 10:47
@Steve-Mcl
Steve-Mcl merged commit 579b2a5 into main Nov 3, 2026
34 checks passed
@Steve-Mcl
Steve-Mcl deleted the project-link-app-aware branch November 3, 2026 10:55

This branch was previously deployed

1 inactive deployment
staging — 99c4656f Deployed Nov 3, 2026 by Steve-Mcl via Remove application #12860
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Project link: broker ACLs and targets API for application aware project nodes

2 participants