Skip to content

Hybrid discovery: bind a manifest app by its ros_binding only, and keep the status of apps the manifest does not declare - #770

Open
bburda wants to merge 6 commits into
mainfrom
fix/manifest-app-foreign-binding
Open

bburda wants to merge 6 commits into
mainfrom
fix/manifest-app-foreign-binding

Conversation

@bburda

@bburda bburda commented Nov 2, 2026 •

Copy link
Copy Markdown
Collaborator

Pull Request

Summary

Two fixes in hybrid discovery, in how the merge pipeline and RuntimeLinker settle an app's node binding and online state.

1. A manifest app no longer takes a same-named node it is not bound to. The merge joins apps by id, and the runtime layer is authoritative for status and live data. A running node whose runtime app id equals a manifest app's id (the bare node name) therefore handed that app its bound_fqn, is_online, topics, services and actions, whatever the app's ros_binding said. With the declared node down and a node of the same name in another namespace, the app showed the foreign node in x-medkit.ros2.node, and configurations, operations, faults and logs went to it.

RuntimeLinker::link now takes the ids of the apps the manifest declares (MergePipeline passes them; there is no default). For those apps it clears bound_fqn and is_online before matching, and takes back the same-id node's resources when that node actually supplied them (and inherit_runtime_resources is on). A binding match then sets the state as before, so the common case - an app named after its node and bound to it - is unchanged. A manifest app without ros_binding is never linked.

2. Apps the manifest does not declare keep their own status. The linker treated every merged app as a manifest app: it set is_online = false on each and counted those without a binding as unlinked. In hybrid mode the gap-fill app of a running unmanifested node and every plugin app (OPC UA, graph_watchdog, ...) were served offline. They now pass through the linker unchanged, and an external manifest app keeps the status of the plugin that serves it.

Behaviour changes to be aware of (hybrid mode only):

  • Gap-fill apps and plugin apps report is_online: true when their layer says so; /status of those apps and their components follows, and features that skip offline apps (node death detection, parameter beacon polling, graph provider reachability) now include them.
  • A manifest app without ros_binding whose id is a running node's name no longer shows that node's FQN, resources or online state. The docs already said the binding is required for linking.
  • The node absorbed by such an id is still reported as unmanifested (orphan_count) but has no app of its own; the docs now say so and recommend app ids that are not node names. An external app whose id a running ROS node also has reads offline with no resources (the merge has already replaced the plugin's state); the docs ask for external ids that no ROS node uses.
  • The "unlinked" count in the linking summary covers manifest apps only.
  • docs/config/manifest-schema.rst now gives the actual ros_binding.namespace default (*, any namespace) instead of /.

Also in this PR: test_peer_recovery case 8 counted the peer's topic in the merged Function list with a single read right after the peer's replacement came up. A freshly restarted gateway can have a running node missing from its ROS graph for a refresh or longer, so the read could find no item and fail with "offered 0 times" (seen once under TSan). The case now waits until the peer lists the topic itself and then requires exactly one copy; a retained copy kept beside the live one still fails it.

Nothing changes in the ROS-free core (App, effective_fqn(), handlers): hosts that set bound_fqn and is_online themselves are unaffected.


Issue


Type

  • Bug fix
  • New feature or tests
  • Breaking change
  • Documentation only

Testing

  • Unit (test_merge_pipeline, test_runtime_linker), with the shipped layer policies and the real linker: declared node down with a same-named node elsewhere; binding to another node while the same-id node runs (inherit on/off, overlapping topic names); app without binding and external app named after a running node; plugin-served external app with and without a same-id node; same-id node kept out of the merge by gap-fill; self-named app bound to its own node (unchanged); gap-fill and plugin apps keep their status; unlinked ids hold manifest apps only.
  • Integration: test_discovery_gap_fill gains a second hybrid gateway that checks over HTTP that the absorbed apps expose no foreign node, data or operations, and that an unmanifested node's app is online.
  • Every new test fails on main for the reason it names.
./scripts/test.sh unit --packages-select ros2_medkit_gateway   # 2970 tests, 0 failures
./scripts/test.sh test_discovery_gap_fill
./scripts/test.sh lint

Also run locally: the hybrid-mode integration tests (37, all passing), graph_watchdog tests, clang-tidy on the changed files, docs build with -W.


Checklist

  • Breaking changes are clearly described (and announced in docs / changelog if needed)
  • Tests were added or updated if needed
  • Docs were updated if behavior or public API changed

The merge joins apps by id and the runtime layer is authoritative for
status and live data, so a running node whose runtime app id equals a
manifest app's id handed that app its FQN, online flag, topics, services
and actions whatever the app's ros_binding said. With the declared node
down and a node of the same name in another namespace, the app named the
foreign node in x-medkit.ros2.node, resolved configurations and faults
to it, and offered its topics and operations.

RuntimeLinker::link now takes the ids of the apps the manifest declares
(MergePipeline passes its manifest layer's ids; there is no default).
Before matching it clears bound_fqn and is_online on those apps and
removes, by value, the resources of the runtime app with the same id. An
external app gives them back only when its merged FQN is that node's.
A binding match then sets the state as before, so the self-named app
bound to its own node is unchanged. The absorbed node stays an orphan
with no app of its own; the docs state that limitation.

The docs also give the ros_binding namespace default as "*", and the
merge comments say that the shipped policies replace live data rather
than union it.

Refs #769
RuntimeLinker treated every merged app as a manifest app: it set is_online
to false on each one and counted those without a ros_binding as unlinked.
In hybrid mode the gap-fill app of a running unmanifested node and every
plugin app were therefore served offline, and the "unlinked" count in the
linking summary included them.

Apps whose id the manifest does not declare now pass through the linker
unchanged and are never counted as unlinked; they still go through the
duplicate suppression. An external manifest app keeps the is_online of
the plugin that serves it, unless the merged state came from a node with
its id. Plugin apps that share an id with a runtime node keep the merged
result, so beacon contributions are unaffected.

The docs, the LinkingResult and App comments, and the hybrid gap-fill
integration test describe the new status of unmanifested and plugin apps.

Refs #769
… them

RuntimeLinker removed the resources of the runtime app sharing a manifest
app's id by value even when that runtime app never entered the merge
(gap-fill kept it out with allow_heuristic_apps=false or a namespace
filter) and even with inherit_runtime_resources=false, where the pipeline
has already restored the declared collections. Either way it could drop a
declared entry or one a plugin contributed, only because the node exposes
something of the same name.

The linker now reads, before clearing anything, whether the merged
bound_fqn is that node's FQN, and removes the node's resources only then
and only while inherit_runtime_resources is on. bound_fqn and is_online
are still cleared on every manifest app that is not external.

The docs and comments no longer say that an external app always keeps
the state of the plugin serving it. When a running ROS node's app has
the same id, the merge has already replaced the plugin's status and live
data with the node's, and the app reads offline with no resources; the
docs ask for external app ids that no ROS node uses, and a test pins it.

Refs #769
The linker inferred that a same-id node had contributed to a manifest app
from the merged bound_fqn being that node's FQN. That reads the STATUS
group, while the resources it then removes come from LIVE_DATA. With a
documented status override (layers.manifest.status: authoritative, or
manifest enrichment with runtime fallback) the FQN stays off the app,
the node's topics, services and actions still come in, and nothing took
them back: an offline, unbound app served the foreign node's resources.
A plugin FQN equal to a node's FQN could also pass for a contribution.

MergePipeline now passes the runtime layer's apps that entered the merge
(its output after gap-fill). A same-id runtime app counts as contributed
only when it is in that set, and its resources are removed by value
from that app. Non-external manifest apps still always lose bound_fqn
and is_online; external apps keep the merged state unless such an app
went into the merge; removal still needs inherit_runtime_resources.

The docs say that with inherit_runtime_resources off the declared
collections replace a plugin's resources on every manifest app, external
ones included, that gap-fill keeping the node out leaves an external
app's plugin status in place, and that the merged outcomes described
hold with the default merge policies.

Refs #769
…ritance on

The merge-policy note in discovery-options said the linker gives a
manifest app the status and resources of the node its ros_binding
matches. With inherit_runtime_resources off the app gets the node's
status but keeps only the collections the manifest declares; the note
now says so and links to the inherit_runtime_resources section.

Refs #769
@bburda bburda self-assigned this Nov 2, 2026
…ng copies

The duplicate check in case 8 read the merged Function's data list once,
right after the peer's replacement had come up. The peer lists what its
ROS graph shows, and a gateway that has just restarted can have a running
node missing from that graph for a refresh or longer. The read then found
no item for the peer's topic and failed with "offered 0 times", a reading
that says nothing about a retained copy lingering beside a live one.

The earlier cases wait for what they assert, and the read in case 7 does
not show the topic is listed: a read that names the member is forwarded
before the list is consulted. Case 8 now waits until the peer lists the
topic in its own Function data and the merged list holds a copy, then
requires exactly one. A retained copy kept beside the live one still makes
it fail, as before.

This branch has not been deployed

No deployments
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.

[BUG] Hybrid discovery: a manifest app takes a same-named node it is not bound to, and unmanifested and plugin apps are served offline

1 participant