Skip to content

fix(gateway): peer aggregation routes by the entity a request names and bounds what a peer can send - #771

Draft
bburda wants to merge 122 commits into
mainfrom
fix/aggregation-peer-routing
Draft

bburda wants to merge 122 commits into
mainfrom
fix/aggregation-peer-routing

Conversation

@bburda

@bburda bburda commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Pull Request

Summary

Fixes in peer aggregation, found while running a primary gateway that aggregates another gateway as a peer. Each
change is its own commit with its docs.

Routing and ids:

  • An entity is its type and its id. A peer entity whose id a local entity of another type holds is served under
    <peer>__<id> and never gets that id in the routing table. Before, a peer Area with the id of a local App took that
    App's requests, writes included. Routing and fan-out are decided from the cached entity the request validated
    (routed_to, the entity's own contributors), read against the merge generation the request was validated in, so a
    request for a local entity does not reach a peer while a new merge is being published.
  • Generated ids are unique across the local entities, everything a peer declares (any type) and every id generated
    for another entity. A peer entity that cannot get a free, valid id is dropped with a warning, and every reference to
    it is removed (hosts, depends_on, Area, parent, subarea parent), in the cache and in forwarded responses.
  • Each peer is addressed by the id it knows an entity by, from the recorded renames only, on forwarding, fan-out,
    member dispatch and the ROS 2 fault service. Plugin entities are injected before the peers merge, so a peer entity
    with a plugin entity's id is renamed too.
  • Members, locks, cyclic subscriptions, resource samplers, plugin entity ownership and the entity of every resource
    route are resolved by type and id; the cache's id-only lookups are removed. Before, /functions/x/data listed the
    data of an Area x, a lock on Component x showed on App x, and a plugin App x took the routes of a local
    Component x. A plugin that introspects one id under two types keeps the first and drops the second with a
    warning. An id that two entity types hold is logged once, at INFO, since both are served.

A peer that stops answering:

  • Every Area item carries x-medkit.source, as Components, Apps and Functions do, so a peer's declared Areas are
    recognized as declared.
  • While a peer is silent, what it declared (source: manifest) stays in the tree marked unreachable:
    x-medkit.available: false on Areas, Functions, Components and Apps (Apps also is_online: false). What it
    discovered at runtime leaves. Nothing is forwarded to the silent peer: a retained Area or Function serves its detail
    and structural routes from the declaration (200) and its resource collections through its members (504
    not-responding); a retained App or Component answers GET .../status with notReady, transitions with 504.
    Before, a peer-only Area or Function answered 502 and a declared Area was dropped.
  • A chain head reads the flag back from the middle gateway, so a silent leaf no longer makes the head discard every
    refresh of the middle.
  • A merged Component's availability is that of the peer its requests route to; a grouping entity stays available
    while any contributor is live.

Forwarded responses:

  • Discovery responses name entities by their served ids and names (id, self and resource links, relationship items,
    Location), and a peer's absolute entity links are served as paths on this gateway. A detail that names no type
    is rewritten by its route's type; a relationship item that names no type is typed by its relationship.
  • A forwarded detail of another entity than the one asked for is refused (502 vendor-error), and references to
    entities the peer did not declare are dropped.
  • A forwarded discovery response carries this gateway's x-medkit.source and x-medkit.contributors for every
    entity it describes, read from the same merge generation as the served ids. Before, a peer-only entity's forwarded
    detail said contributors: ["local"] and the peer's own source, so it disagreed with its list item.
  • Fan-out items name their members by the ids served here, so a configuration write through a grouping entity reaches
    the peer's member, not a local one of the same id.

Executions and triggers:

  • Execution follow-ups (status, cancel, stop) of an entity a peer owns whole are forwarded to that peer, resolved
    against the entity type of the route.
  • A tracked goal belongs to the entity it was started through (type and id) and to its operation: it answers only
    under an id that names that operation (its name, its ROS path, or qualified by the member that holds it), and keeps
    answering while the operation's server is gone.
  • A resource change names its entity by type and id, and a trigger matches on both, so an Area and a Function that
    share an id no longer fire or list each other's triggers.

What a peer can send:

  • Every answer stops at 10 MB of body, /health included; JSON nested deeper than 64 levels or holding more than
    1,000,000 values is refused before parsing. A deeply nested peer body crashed the gateway before.
  • One refresh keeps at most 250,000 records and 16 MiB of text of one peer (1000 operations and topics per App, 1000
    dependencies per Component or Function, each host and dependency once); past that the refresh of that peer is
    discarded and its last complete declaration stays. A wrong-typed field fails that peer's fetch, not the whole cache
    refresh.
  • Rewriting a forwarded response to served ids has an output budget, and a served name is cut to 512 bytes.
  • Nested Area and Component walks check the entity cap before each child, read down to 8 levels and stop on cycles;
    a peer's nested failures are read in one pass, at most 1024 names and 64 KiB per answer.
  • A peer's entity-not-found 404 means it holds nothing by that id, not that it failed, so a local entity no longer
    logs partial peer fan-out on every call. A health answer the gateway refuses to read counts as a failed check.

Deadlines and shutdown:

  • Every request to a peer runs for at most aggregation.request_deadline_ms (new, default 30000) from connect to
    the last byte, however steadily the peer drips. A forward then answers 504, a fan-out names the peer timeout.
  • The gateway resolves a peer's host name itself within the connect budget (capped at 1 s), on its own thread, so a
    resolver that does not answer no longer stalls peer calls or their cancellation.
  • Shutdown cancels every peer call in flight through the call's socket, a TLS handshake sent a byte at a time
    included; starting a peer call and shutdown are exclusive, and a forward shutdown refuses answers 503.
  • Peers are read from the executor after startup, not in the gateway's constructor, so a slow peer no longer holds
    startup or SIGTERM.

Discovery and faults:

  • A peer entity's description, namespace, node, translation id, Function depends-on, and a subarea's description
    and tags are read from the keys a gateway serves.
  • A Component this gateway declares is described from the merged view; its resource collections still go to the
    peer.
  • list_entity_faults (ROS 2 service and HTTP) asks only the peers that contributed the entity.
  • Each id collision is logged once, and again only after it went away and came back.
  • config/examples/multi_robot_manifest.yaml loads again (its subarea ids collided with App ids).
  • The gateway's own nodes are no longer reported as orphans in hybrid mode. A manifest that gives two entity types one
    id is still refused, and the message now names both kinds.

Build and tests:

  • clang_format lists each package's sources relative to the package. The gateway's test command line was 72 KB with
    absolute paths; colcon stops reading a line at 64 KiB and then waited forever for ./scripts/test.sh lint from a
    long checkout path. It is 26 KB now.
  • Every test keeps its DDS discovery on its own host (ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST, ROS_LOCALHOST_ONLY=1
    on Humble). The test domain allocation separated tests from each other but not from another ROS process on the
    same network: one on the same domain received a test's fault reports.
  • The OPC UA alarm server smoke test runs in CI (asyncua in a venv); certificate files are read without the GCC 13
    -Wnull-dereference false positives.

The SOVD REST API keeps its routes, schemas and error codes. Behavior a client can see changes as documented in
docs/api/rest.rst and docs/config/aggregation.rst: renamed peer entities carry served ids in forwarded responses;
a locally declared merged Component's detail is served locally; a peer is offline and its entities answer 404 until
the first merge after startup; an oversized or unreadable /health marks the peer unhealthy; an execution answers 404
under another operation's id or through another entity type with the same id; triggers, locks and cyclic subscriptions
are per entity type and id; Areas carry x-medkit.source; entities of a silent peer are served as described above
instead of answering 502.

Breaking change for plugins: PLUGIN_API_VERSION goes from 7 to 8. ResourceChange and NotifierFilter carry
entity_type (SovdEntityType, UNKNOWN for a change that names no entity type), and ResourceChangeNotifier::notify()
takes the entity type before the entity id. Plugins are rebuilt against the new headers; a plugin built for 7 is
refused at load, as for every version bump. Also in 8: ResourceSamplerFn receives the entity type; Area and
Function gain available; PluginContext gains typed get_entity, list_entity_faults, register_entity_capability,
get_entity_capabilities, check_lock, acquire_lock and release_lock beside the id-only forms, which stay
source compatible and resolve only when exactly one entity holds the id (otherwise they are refused with a warning; a
lock is never taken on an id no entity holds). The sovd_service_interface ROS services apply the same rule, so
ros2_medkit_msgs is unchanged. A host that embeds the core passes MemberRef (type and id) to
PluginManager::register_entity_ownership. docs/tutorials/plugin-system.rst describes the changes.


Issue

  • None.

Type

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

Testing

  • Build of the whole workspace: 0 warnings, also per commit; clang-tidy clean on every changed
    file; lint presets 18/18; docs build with sphinx-build -W.
  • Lint 2370 tests, 0 failures (the skips are ament_cppcheck's own skip on cppcheck 2.13). Unit: 4690 tests, 0
    failures. Integration: 1717 tests, 0 failures, run twice. OPC UA package: 530 tests, 0 failures; OpenPLC suites
    29/29 read-only and 26/26 write-capable; the alarm suite and its smoke test pass.
  • ASan+UBSan on the aggregation unit (37) and integration (44) suites with FastDDS and CycloneDDS: 0 reports. TSan
    with FastDDS, as CI runs it: 0 reports. TSan with CycloneDDS reports races inside libddsc and
    librmw_cyclonedds_cpp only, about as many on the base branch as here (108 and 106), none in this PR's code; no
    suppression is added for them.
  • Each fix was reproduced on two live gateways before and after, for example: a peer Area with a local App's id and a
    configuration write to that App; peer bodies of 300 MB, 100000 nesting levels and 3M empty objects; a peer dripping
    its answer or its TLS handshake past the deadline (SIGTERM 30 s+ before, 0.3 s after); a resolver that never
    answers; an execution followed through a qualified id after its action server stopped (404 before, 200 after);
    a trigger on a Component that shares its id with an App (the App's trigger fired before, the Component's after);
    a peer stopped behind a primary and in a three-gateway chain (502 and 10 discarded refreshes in 20 s before; 200
    with available: false, notReady and 0 discarded refreshes after); locks, subscriptions and plugin entities on
    ids two entity types share; a DDS participant in another container on a test's domain (reached before, not after).
  • A downstream gateway that embeds the core and aggregates its peers ran its full end-to-end battery on this branch.

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

bburda added 30 commits October 24, 2026 15:30
The SSE fault handler consumes a ROS-free fault event source built on the
shared fault types. Fault JSON keeps 64-bit seconds.
Build the HTTP layer into the ROS-free gateway core library. The core
reuses httplib::httplib and handles ENABLE_SWAGGER_UI. The core compiles and is
tested without ROS and without DDS setup. scripts/check_cores_without_ros
serves gateway health over HTTP from the core.
…ersion

RestConfig gains server_name, vendor_name and server_version, so a program that hosts the core names its own server on GET /, GET /version-info and in the OpenAPI documents. The defaults are the values the ROS 2 node reports, and the node sets nothing.
The Swagger UI page title now takes the server name from the server identity, HTML-escaped, and keeps the API Documentation suffix.
…n samplers

register_builtin_samplers() registers data, faults, configurations, logs and updates from GatewayServices, so a program that hosts the core gets samplers without the ROS node. The data sampler reads through the same provider resolution as GET /{entity}/data/{item}, so plugin-served data can be subscribed to.
…he categories the host serves

BulkDataConfig and make_bulk_data_store() build the store from the bulk_data settings, and the node uses them. The rosbags category is listed only when the fault manager transport serves rosbags, and GET / reports bulk_data and cyclic_subscriptions only when the host provides a store or rosbags, and a transport and a sampler.
…an unknown category

The bulk-data list and download routes take the rosbags path only when the fault manager serves rosbags. Otherwise the category falls through to the store check and answers 404 Unknown category.
A program that hosts the core attaches FreezeFrameCapture to its own fault events and gets freeze frames in the fault detail, read through the same plugin data path as GET /{entity}/data. The ROS node keeps its parameters and frames and feeds the same class from the fault manager's events topic.
…ateway-core-10-core-freeze-frames

# Conflicts:
#	src/ros2_medkit_gateway/README.md
FaultEventFanOut subscribes upstream once and gives each consumer its own branch, so the fault SSE stream and the freeze-frame capture can share a host's single FaultEventSource. The ROS-free check drives both from one source and requires the confirmation in the SSE stream and as a freeze frame.
LockReaper calls LockManager::cleanup_expired() on a thread it owns and removes the cyclic subscriptions in an expired lock's scope, so a host without a ROS timer no longer keeps expired locks. The ROS 2 node starts the same class in place of its wall timer, and the ROS-free check requires the lock and its subscription to be gone after the expiry.
make_script_host() returns a ScriptManager backed by the plugin provider, or by a DefaultScriptProvider built from ScriptsConfig when a scripts directory is set. The ROS 2 node reads its parameters and manifest scripts into the same config and calls it, and the ROS-free check uploads a script over HTTP, runs it and reads its output.
AggregationHost builds the AggregationManager and the mDNS discovery from an AggregationConfig, and merge_peers() merges the peers' entities and publishes the routing table, leaf warnings and contributors. The ROS 2 node keeps its parameter parsing and uses the class, and the ROS-free check starts a second server in the same process as a peer and reads its entity through the first.
A host passes a null LifecycleStateReader: the status route then reports readiness from graph presence and a transition answers 501 without a LifecycleProvider. The ROS-free check pins both answers, also for an app that exposes the lifecycle services.
…s deleted

The branch is held by pointer and registered by address, so copying or moving it is never valid.
A host builds the trigger store and manager from a neutral config, feeds fault triggers from a FaultEventSource and reads data items of plugin-served entities by polling. The ROS 2 node uses the same builder and keeps its topic transport and fault subscriber as adapters.
The check program creates a fault trigger and a data trigger over HTTP on a host with one fault event source and a plugin-served data item, and checks the trigger count limit. The docs describe the builder, the sources and the new host-only polling interval.
A program that hosts the core builds a plugin context from GatewayServices and gives it to PluginManager::set_context(). Its node() is null, and the ROS 2 node derives its context from the same class and overrides only node().
A host builds the threshold-rule engine and its evaluation thread from a config with the fault_triggers.* names and defaults. The ROS 2 node uses the same builder and keeps its gate on the parameter and on loaded plugins.
The warning for a data trigger whose resource path has no source now reads the same on a host without topics. The status and the error code of the responses do not change.
docker build -q hides the compiler output behind an exit code. When it fails, run.sh now repeats the build with the full log.
…thout ROS

The check loads a plugin built without ROS through the core PluginManager and drives the fault-trigger engine through the host's single fault event source. The Dockerfile builds with four jobs and checks the plugin for rclcpp too.
…gger engine

The gateway README and the design index describe the two builders and the null node of a host without ROS. The check README lists what the new check covers.
…r does

The polling source delivers the data field of the item body, the same value a topic trigger gets, so one trigger path works on both hosts. A body with no data field is delivered whole.
…ore-13-core-plugin-context

# Conflicts:
#	src/ros2_medkit_gateway/README.md
The context takes a nullable GatewayServices pointer, so make_gateway_plugin_context(nullptr, ...) no longer binds a reference to a null node. Without services it answers no entities and locking as disabled, and capabilities and samplers still work.
bburda added 28 commits November 4, 2026 19:07
…failed check

A 200 /health whose body nested past the depth bound, or held more
values than the value bound, was judged before it was parsed and then
not read - and the peer still counted as healthy, though an oversized
body counts as a failed check. A peer answering its health check with a
body nested 100 levels deep was online, its entities fetched and served.

Such an answer is now a failed health check, like an oversized one. Text
that is not JSON is judged the same way and stays a healthy 200.
…was started through

A tracked goal recorded only the id of the entity its POST addressed, and
its follow-ups and the executions listing compared that id alone. Ids are
unique per type only: with a manifest Area and a namespace Function of one
name, a goal started through /areas/<id> was read, stopped and cancelled
through /functions/<id>/operations/<anything>/executions/<goal>.

The goal now records the entity type with the id, and a follow-up or a
listing keeps it only when both match the route's entity. The member a
qualified operation id names still reaches the goals started on it, as one
of the grouping's members by its own type: the aggregated operations record
the type of each contributing member next to its id, since an App and a
Component may share one too.
…slash removed

Every route's pattern ends with an optional slash, so /apps/x/ and
/apps/y/depends-on/ route to the detail and the relationship, and a peer
gateway answers them so too. The rewrite of a forwarded answer classified
the path as sent, which made both a resource after the id: the answer
skipped the rewrite to served ids and the detail identity check, and
reached the client in the peer's ids, naming local namesakes, with a detail
type the check refuses passed through.

The path is now classified without that one slash, for the detail check, the
discovery route test and the relationship's item type.
…ed it

An execution's routes checked the entity a goal was started through and not
its operation, so /areas/x/operations/missing/executions/<goal> - or the
executions of another operation of the entity - read, stopped and cancelled
the goal.

The operation id of the route now has to name the goal's operation, by its
name or its ROS path; a member-qualified id has to name the member that
holds it, the one the goal was started on or the recorded owner of its
action. The goal's own action is matched rather than the operations the
cache lists now, so the execution of an action server that has gone stays
answerable. The executions listing keeps a goal by the same rule.
A resource change named its entity by id alone, and a trigger matched it,
was listed, read, updated, deleted and streamed by that id alone. Ids are
unique per type only: with a manifest Area and a namespace Function of one
name, a goal started through the Area fired the Function's triggers, and the
Function's routes listed, changed and deleted the Area's. Topic resolution
for a data trigger and the orphan sweep looked the entity up by id as well.

ResourceChange and NotifierFilter now carry the entity type, and notify()
takes it: operations give the goal's entity, faults and logs the node's
App, data triggers their own entity, and an update's status, which names no
entity type, is matched by its update id. A trigger matches a change of its
own entity by type and id, and through the hierarchy the changes of the
Apps under it. The trigger routes act only on a trigger of the entity they
name, and topic resolution and the orphan sweep look the entity up by type.

ResourceChange and NotifierFilter cross the plugin boundary, so the plugin
API version goes to 8.
… executor

The long_calibration demo server joined the running goal's thread in
handle_accepted before starting the next goal's. That callback runs on the
node's executor, so a second goal held the executor until the first ended:
the server answered no cancel and no other request meanwhile, and a cancel
of the first goal timed out.

Each goal now runs on a thread of its own. Finished threads are joined when
the next goal is accepted, and every thread at shutdown. The server's
callbacks are lambdas taking their handles by reference, and the node
declares its copy and move operations deleted, as its destructor joins
threads that hold `this`.
…is sent

A qualified execution id names the member that holds the operation, and the
routes of a goal started through a grouping entity looked that member up in
the operations the cache lists now. Once the action's server had gone and
discovery dropped the action, the goal's own Location under
/areas/<id>/operations/<member>:<op>/executions/<goal> answered 404 to its
status, stop and cancel, while its unqualified address still answered.

The member that owns the action is now recorded with the goal when it is
sent through a grouping entity, and a qualified id is judged against that
record, so every address of the goal stays answerable after its server is
gone.
…tity

The log entry a trigger's log_settings write when it fires was notified as
an App's whatever the trigger's entity was. With the notification matched by
type and id, the entry of a Component, Area or Function trigger missed that
entity's logs triggers and fired those of an App sharing its id.

LogManager::add_log_entry takes the entity type, and the trigger passes its
own. The other notifications carry a type their producer knows: a goal's
entity, the trigger's own entity for data, the node's App for node logs and
faults, and none for an update's status.
The plugin tutorial still gave 7 as the current API version. It now gives 8
and says what 8 changes for a plugin author: the entity type in
ResourceChange, NotifierFilter and notify(), and the rebuild every plugin
needs. The graph watchdog design names the ABI by its constant rather than a
number that goes stale.
No route served an Area's source, so a gateway aggregating this one read
every peer Area with an empty origin, never took it for a declaration, and
dropped it while the peer was not answering, although it kept the
Components, Apps and Functions the same peer declared.

Serve area.source in the Area x-medkit on the list, the detail, the
subareas items and the resolved belongs-to item, omitted when empty. On an
aggregating gateway it is the source the merge assigned, as for the other
entity types. Document the Area x-medkit fields and what a retained Area
looks like.
Every package that globs its clang_format file list passed absolute
paths, so the test's command line grew with the checkout path as well as
with the file count. `ctest -V` prints that command on one line, and
colcon stops reading a ctest output line longer than 64 KiB; with enough
output after it, `colcon test` never returns. From a long checkout path
the gateway's line was 72,697 bytes and `./scripts/test.sh lint` hung.

ament_clang_format has no exclude option on Humble or Jazzy, so the
directories cannot be passed instead. Glob relative to the package
directory, which is where the test runs: the gateway's line is now
25,741 bytes from the same checkout, independent of where it is, and
every package checks the same files as before.
Reachability, member dispatch and the peer a member belongs to were read
by id alone: an App first, then a Component. An App and a Component may
share an id, so a check could read the other entity's state.

Members are now a type and an id (MemberRef). The owner recorded per
operation path, the contributors of an entity's data (source_types beside
source_ids) and ThreadSafeEntityCache::get_members carry the type;
dispatch_to_member, is_member_available and peer_source_of_member look
the member up as that type; the validator reads the reachability of the
entity it found for the route. A member half on the wire carries only an
id and is resolved against the entity's typed members, an App winning
over a Component that shares its id, since topics and parameters belong
to Apps.
…d to a silent peer

When a peer stopped answering, its declared Areas and Functions stayed in
the tree with nothing saying so, and their detail and resource routes
were forwarded to the silent peer and answered 502. In a chain, the
middle gateway's 502 on a retained Function's detail made the head
discard every refresh of the middle, so the head kept serving its view
from before the leaf died.

The tree now shows the current runtime. The refresh that finds a peer
unreachable marks every entity of its replayed declaration, and every
entity routed to it, unavailable: Areas and Functions gain an available
flag like Apps and Components, served as x-medkit.available false on
their list items and details. A grouping a live gateway also contributes
stays available, and a Component merged from this gateway and a peer
takes the peer's reachability unless it is served here as a parent.

Nothing is forwarded to an unavailable entity. A retained Area or
Function answers its detail and structural routes here from the retained
declaration, and its resource collections through its members, 504
not-responding when none can be reached. A retained App or Component
answers GET status with notReady and no transition URIs; everything else
keeps answering 504 not-responding. The peer client reads available back
on Areas and Functions, so a chain head keeps the flag the middle reports
and goes on reading the middle whole while the leaf is down.
The data and configuration routes, their OpenAPI sub-documents and the
fault trigger owner check found the route's entity by id alone, trying
Component, App, Area and Function in turn. An Area and a Function may
share an id, so GET /functions/x/data and /functions/x/configurations
listed the data and parameters of Area x's members.

ThreadSafeEntityCache gains get_entity_data and get_entity_configurations
taking the entity type; the handlers pass the type of the route's entity,
the capability generator the type of the documented route for data and
operations, and the fault trigger host looks the owner up as an App.
…serves it

A leaf Component that several peers declare is routed to the last of them
(last-writer-wins), but its availability was the AND across every
contributor. With two reachable peers A and B, where A reports the Component
unavailable and B serves it, requests went to B while the Component stayed
available: false, so /data answered 504 without asking B and /status
answered notReady. A merged Component now takes the availability of the peer
it is routed to. The local-parent rule and the marking of Components routed
to a silent peer are unchanged.

A peer that stops answering has its declaration retained and replayed after
the live peers, which made it the last writer: a Component a live peer still
served was routed to the silent one and answered 504. A replayed declaration
now yields a Component a live peer contributes - it is listed among the
contributors but claims no route and does not set the availability. A
Component only silent peers declare stays routed to the last of them and is
marked unavailable, as before.

Areas and Functions keep the documented rule (available while any
contributor is); Apps never merge (a colliding App is prefixed).
… by type and id

An entity id is unique within its type only: an App and a Component, or an
Area and a Function, may share one. Several per-entity records and lookups
were still keyed by the id alone and answered for whichever entity of that
id they found first.

- Locks: LockManager keys a lock, its lock-id index and its configuration by
  the route's entity type and id. The type default is the route type's, a
  manifest lock override configures the entity that declares it (manifest
  lock_overrides and LockConfig::entity_overrides are keyed by type and id),
  and the parent walk follows the type (App -> Component -> Area). A lock on
  /components/x is no longer listed, acquired over, broken or released
  through /apps/x. LockInfo and ExpiredLockInfo carry the type.
- Cyclic subscriptions: SubscriptionManager::list takes the type, the lock
  reaper removes the expired lock's entity's subscriptions only, and every
  subscription route checks the subscription's type as well as its id.
- Samplers: ResourceSamplerFn takes the entity type of the subscription; the
  built-in samplers read the entity as that type, and the graph sampler
  answers for Functions only. A subscription on /functions/x beside an Area x
  samples the Function.
- Plugin entities: PluginManager owns an entity by type and id, and every
  provider, owner and x-plc-data route lookup passes the route's or member's
  type. A local entity sharing an id with a plugin entity of another type is
  served by the gateway, not by the plugin's providers. One plugin may not
  introspect two entities of different types under one id (its providers are
  called with the id alone): the later is dropped, in both discovery paths,
  with one WARN naming the plugin, both types and the id.
- PluginContext gains typed get_entity, list_entity_faults,
  register_entity_capability, get_entity_capabilities and the lock calls,
  answered through protected hooks so a context overriding only the id-only
  forms still builds. The id-only forms resolve a bare id only while one
  entity holds it, and refuse it otherwise with one WARN per ambiguity; an
  entity capability registered by id is resolved when looked up. Entity
  capabilities are stored by type and id. A plugin route validates the
  entity of its route's type.
- sovd_service_interface: its requests carry an id only; an id held by more
  than one entity is refused with an error naming the types.
- Trigger data items of plugin entities are watched by type and id.

The test data provider plugin uses the typed calls, registers one capability
of each form, and can introspect a cross-type duplicate (cross_type_duplicate).
The v8 notes and the plugin, locking and service interface docs say what the
typed calls are and what an ambiguous id answers.
Nothing outside the tests resolves an entity by its id alone any more, so the
lookups that did are removed rather than left to be called again:

- ThreadSafeEntityCache::find_entity, get_entity_type, and the id-only
  get_entity_data and get_entity_configurations overloads. Every lookup names
  the type; has_entity(type, id) answers whether one exists.
- AggregationService::get_operations_by_id.
- AggregationManager::find_peer_for_entity with update_routing_table and the
  routing table copy it read. A request reads its route off the entity it
  found (find_owning_peer); the table, keyed by id alone, cannot say which
  entity an entry belongs to.

Their tests move to the typed calls; the concurrency tests that used the
routing table publish leaf warnings instead, which take the same lock.
…reference

The service callbacks and the handlers they call took their request and
response shared pointers by value, copying both on every call. Take them
by const reference, as the other service callbacks in the repository do.
Reserve the thread vectors in the subscription manager concurrency tests.
GCC 13 at -O2 inlines value() with a string default into a from_json path
it then reports as a potential null pointer dereference (-Wnull-dereference).
Check the member and compare it directly instead.
An id held by entities of two types is legitimate: every route names the
entity type, so each entity is served on its own. The merge pipeline still
logged it as an ERROR "ID collision" on every refresh. Log each pair at INFO
when it appears, and again only after it went away and came back. The merge
report keeps counting the pairs in id_collisions.
In hybrid mode the linker reported the gateway node and its parameter client
node, /_param_client_node, as nodes the manifest does not declare. With the
warn policy that is two warnings on every refresh, and with the error policy a
standing /health warning that asks for the gateway to be declared.

The gateway's own node is never an orphan: the manifest describes the stack
the gateway diagnoses. It is still unlinked, so the ignore policy keeps hiding
its namespace. The parameter client node is skipped while
filter_internal_nodes is on, as the helper nodes are, since it is then never
an App.
Building the string from istreambuf_iterators made GCC 13 report a potential
null pointer dereference (-Wnull-dereference) in every target that compiles
opcua_client.cpp. Read the file through its stream buffer instead; an empty
or unreadable file still gives an empty ByteString.
test_alarm_server_smoke needs asyncua and exits 77 without it. The unit job,
which runs ctest, never installed it, so the test was always skipped, while
the alarm job installed asyncua and never used it.

Install asyncua in the unit job, into a venv created on top of the system
packages, and run the smoke test in a step of its own with the venv's
packages on its path and ROS2_MEDKIT_OPCUA_SMOKE_REQUIRE set, so a missing
client fails the test instead of skipping it. The main ctest run leaves it
out. Drop the unused install from the alarm job.
…es an id

A manifest may not give two entity types the same id, so that a reference
names one entity. The finding said "Duplicate function ID: x" for a Function
that shares its id with an Area, which reads as two Functions. Name both
kinds, "ID 'x' is used by both Area and Function", and keep the old message
for a true duplicate within one type.
A held domain keeps the tests apart from each other, but the lock reaches one
network namespace only. A ROS stack in another container on the same Docker
bridge, or on the same LAN, that uses the domain saw the test's nodes and
answered its services: a demo stack's fault_manager took a test's
/fault_manager/report_fault calls, and the test timed out waiting for its own.

The domain wrappers now also set ROS_AUTOMATIC_DISCOVERY_RANGE=LOCALHOST, or
ROS_LOCALHOST_ONLY=1 on Humble, which reads only the older variable. Nothing
a test starts needs discovery beyond its host.
An id-only plugin lock call on an id no entity held resolved to no type and
acquired the lock under an unknown type, returning success. The routes check
the entity's own type and id, so once App x appeared the lock protected
nothing, and an id-only release then answered lock-not-found. Before locks
were kept by type and id, the id-keyed lock covered the later App.

acquire_lock and release_lock on such an id now answer what the lock routes
answer for an unknown entity, entity-not-found with 404, and check_lock
answers allowed, since nobody can hold a lock on it. The typed calls answer
the same for an unknown or server type, and LockManager::acquire refuses a
lock without an entity type.
…teway does

A discovery response forwarded to the peer that serves an entity came back
with the peer's own provenance. The peer declares the entity itself, so its
detail said "contributors": ["local"] and its own source, and on the
aggregating gateway "local" names that gateway. The same detail served from
the retained declaration while the peer is silent says ["peer:<name>"] and
"peer:<name>", as the listings do, so the answer changed with the peer's
health.

The rewrite that names every entity of a forwarded response by its served id
now also gives each entity it describes this gateway's x-medkit.source and
x-medkit.contributors. The detail takes both, as a local detail serves them;
a relationship item takes the ones it carries. The values come from the peer
id index, which now records the provenance of every served entity a peer
contributes, so they are read from the same generation as the ids.

The integration tests that read the peer's own provenance off a forwarded
detail now expect this gateway's. The REST and aggregation docs say what a
forwarded response carries, and that contributors appear once a peer is
configured or discovered.
@bburda
bburda force-pushed the feat/gateway-core-13-core-plugin-context branch from 9e3cadb to 05c6e68 Compare November 7, 2026 12:38
Base automatically changed from feat/gateway-core-13-core-plugin-context to main November 7, 2026 16:09

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.

1 participant