fix(gateway): scope per-entity fault GET/DELETE by hosted-app FQNs

[bburda]

Summary

Per-entity fault routes (GET / DELETE /{entity-path}/faults/{fault_code}) leaked faults across entities. When the addressed entity had an empty namespace_path (host-derived or synthetic components, manifest components without a namespace field, Areas, Functions), the transport-level prefix filter short-circuited:

• GET returned faults reported by apps that lived in entirely different entities.
• DELETE cleared them too, because ClearFault.srv carries no scope argument and the handler issued the clear without checking ownership first.

Both handlers now resolve the addressed entity to the set of FQNs of every hosted app via a new HandlerContext::resolve_entity_source_fqns helper and apply a strict all-sources scope check: a fault is in scope iff every entry in its reporting_sources is owned by the entity. Per-fault routes return 404 for any fault that fails the check; per-entity collection responses omit it; per-entity DELETE skips it. DELETE additionally fetches the fault and verifies scope before issuing the clear so it can never clear a fault that does not belong to the entity, and uses the new ClearFault.srv skip_correlation_auto_clear request field to opt out of cascade-clearing correlated symptoms that may live outside the entity.

GetFault.srv is unchanged. ClearFault.srv gains the skip_correlation_auto_clear request field - this changes the service type hash and breaks out-of-tree callers that invoke /fault_manager/clear_fault directly (the ros2_medkit_fault_manager README documents that pattern). The in-tree gateway client and server are updated together. See CHANGELOG for the full client-visible behavior delta.

Issue

• closes [BUG] handle_get_fault returns cross-entity faults for synthetic components (scope leak) #395

Type

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

Testing

TDD red-green verified locally:

• test_faults_scope_isolation (new integration test, lidar_sensor + temp_sensor in hybrid mode with demo_nodes_manifest.yaml):
  • With the handler reverted, test_get_fault_returns_404_on_unrelated_component gets 200 with the leaked lidar fault body and test_clear_fault_returns_404_on_unrelated_component gets 204 (the unrelated component cleared the lidar fault).
  • With the fix in place, all 4 cases pass (404 on the unrelated component, 200 on the owning component, fault still present after the rejected DELETE). The 404 cases additionally assert the response body carries none of the success-shape keys (item, environment_data, reporting_sources, snapshots) and does not echo the owning app's FQN, so a future regression that flips the status code without sanitizing the body still fails.
• 10 unit tests on FaultHandlers::fault_in_source_scope covering exact-match, strict path-child, prefix collision, multi-source all-in-scope, multi-source partially-in-scope (the DELETE escalation case), empty scope, empty / missing / malformed reporting_sources, and a root-FQN edge.
• 7 unit tests on HandlerContext::resolve_entity_source_fqns covering App / Component / Area (with nested subarea recursion) / Function (with component-host expansion) / Unknown plus empty-effective-fqn and missing-from-cache edges.
• 2 routing tests pinning that per-entity DELETE sets skip_correlation_auto_clear=true and the global DELETE leaves it false.
• Full gateway unit suite passes; existing fault integration tests (test_faults_api, test_locking_faults, test_triggers_faults, test_scenario_fault_inspection, test_scenario_fault_lifecycle) pass.
• colcon test --packages-select ros2_medkit_gateway linters (clang_format, cppcheck, flake8, lint_cmake, pep257, xmllint) and clang-tidy build green.

Reviewer steps:

1. colcon build --packages-up-to ros2_medkit_integration_tests
2. colcon test --packages-select ros2_medkit_gateway ros2_medkit_integration_tests --ctest-args -R 'test_faults_scope_isolation|test_handler_context|test_fault_handlers|test_fault_manager_routing'

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

Backwards compatibility note

Three client-visible behavior changes are documented in the CHANGELOG:

1. Per-entity fault routes: clients that previously received 200 / 204 for a fault outside an entity's scope now get 404. The all-sources rule also rejects mixed-source faults that include any out-of-entity reporter - use the global GET /api/v1/faults to see those.
2. ClearFault.srv service hash change: adding the skip_correlation_auto_clear request field changes the service type hash. Out-of-tree callers that invoke /fault_manager/clear_fault directly must rebuild against the new ros2_medkit_msgs.
3. Per-entity collection responses no longer include the global muted_count / cluster_count / muted_faults / clusters correlation metadata; that remains on the global GET /api/v1/faults route.

[Copilot]

Pull request overview

This PR fixes per-entity fault scoping so fault reads and clears are based on hosted app FQNs instead of empty or overly broad namespace prefixes.

Changes:

• Adds HandlerContext::resolve_entity_source_fqns() and uses it in fault handlers.
• Updates per-entity fault GET/list/DELETE paths to apply hosted-app source filtering.
• Adds regression tests plus API/changelog documentation for the behavior change.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
src/ros2_medkit_gateway/src/http/handlers/fault_handlers.cpp	Applies FQN-based fault scoping before returning or clearing faults.
src/ros2_medkit_gateway/src/http/handlers/handler_context.cpp	Adds helper to resolve entity-owned source FQNs.
src/ros2_medkit_gateway/include/ros2_medkit_gateway/http/handlers/handler_context.hpp	Declares and documents the new source-FQN resolver.
src/ros2_medkit_gateway/test/test_handler_context.cpp	Adds unit coverage for source-FQN resolution.
src/ros2_medkit_integration_tests/test/features/test_faults_scope_isolation.test.py	Adds integration regression coverage for cross-component fault leakage.
src/ros2_medkit_gateway/CHANGELOG.rst	Documents the fault scoping behavior change.
docs/api/rest.rst	Updates fault endpoint response-code documentation.

Comments suppressed due to low confidence (2)

src/ros2_medkit_gateway/src/http/handlers/fault_handlers.cpp:610

• This uses the existing prefix-based collection filter with exact app FQNs. For an app /ns/node, a fault reported by /ns/node_extra will be included because it starts with the owned FQN, so the collection route can still leak similarly named nodes' faults. The collection filtering should use exact FQN membership (or a path-boundary-aware match) when the filter set contains app FQNs.

    const auto & cache = ctx_.node()->get_thread_safe_cache();
    auto app_fqns = HandlerContext::resolve_entity_source_fqns(cache, entity_info);
    auto result = fault_mgr->list_faults("", filter.include_pending, filter.include_confirmed, filter.include_cleared,
                                         filter.include_healed, include_muted, include_clusters);

    if (result.success) {
      json filtered_faults = filter_faults_by_sources(result.data["faults"], app_fqns);

src/ros2_medkit_gateway/src/http/handlers/fault_handlers.cpp:1029

• faults_to_clear is selected by intersection, but the later clear call is still by fault_code only. A fault with one reporting source in this app and another source outside it will be selected here and then cleared globally, including the out-of-scope source. Exclude or reject mixed-scope faults before issuing unscoped clears.

      const auto & cache = ctx_.node()->get_thread_safe_cache();
      auto app_fqns = HandlerContext::resolve_entity_source_fqns(cache, entity_info);
      faults_to_clear = filter_faults_by_sources(result.data["faults"], app_fqns);

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (1)

src/ros2_medkit_gateway/src/http/handlers/fault_handlers.cpp:844

• With the new all-sources scope rule, this error also fires for mixed-source faults where one reporting source is inside the entity and another is outside. The message says the fault is not reported by any app in scope, which is inaccurate for that case and makes 404s misleading; it should describe that not all reporting sources are within the entity scope.

      HandlerContext::send_error(res, 404, ERR_RESOURCE_NOT_FOUND, "Fault not found",
                                 {{"details", "Fault is not reported by any app within this entity's scope"},
                                  {entity_info.id_field, entity_id},