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 require the fault's reporting_sources to intersect that set. An empty set means "no app is in scope" -> 404. DELETE additionally fetches the fault and verifies scope before issuing the clear, so a per-entity DELETE can never clear a fault that does not belong to the entity.

The GetFault.srv / ClearFault.srv contracts are unchanged.

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).
• 7 new unit tests for HandlerContext::resolve_entity_source_fqns covering App / Component / Area / Unknown plus empty-effective-fqn and missing-from-cache edges.
• 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'

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

Clients that previously received 200 / 204 for a fault outside an entity's scope now get 404. This is a behavior change for any client that was relying on the leaked response. The CHANGELOG entry documents the contract change.

[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},