Global /faults/stream SSE events lack entity context for downstream consumers

[mfaferek93]

Problem

Consumers subscribing to the gateway-wide /api/v1/faults/stream receive a fault payload (fault_code, severity, reporting_sources, description, ...) but no explicit SOVD entity identifier. reporting_sources contains ROS node names which follow a different convention than SOVD entity IDs (for example /bridge/diagnostic_bridge vs diagnostic-bridge), so a consumer that wants to pull the associated bulk-data/rosbags/{fault_code} has to enumerate apps + components and HEAD-probe each one until a 200 comes back.

Surfaced while building the first external integration (bridge to an Apache Arrow Flight data platform): see resolve_entity_for_download() in the demo bridge, which does O(N) HEAD probes on apps + components as the pragmatic workaround. That works fine at ~10 entities but is wasteful latency-wise and conceptually wrong - the gateway already knows which entity owns the bag, it just doesn't tell the SSE consumer.

Options

A. x-medkit extension in SSE payload

Add x-medkit-entity-type and x-medkit-entity-id fields inside the SSE fault event JSON. The consumer reads them directly and issues one request to bulk-data.

• Pros: zero extra round-trips, backward compatible (vendor extension, existing SOVD consumers ignore it).
• Cons: introduces a new x-medkit-* extension just as Replace x-medkit response extensions with dedicated REST resources #140 proposes moving away from them to dedicated REST resources.

B. Per-entity fault streams

Consumers subscribe to /api/v1/{entity_type}/{id}/faults/stream instead of the gateway-wide stream. Entity context is implicit in the URL path.

• Pros: SOVD-native shape, aligns with the direction of Replace x-medkit response extensions with dedicated REST resources #140.
• Cons: consumer needs to enumerate entities upfront (but that's a one-time discovery, not per-fault). For a global 'catch everything across the gateway' use case the consumer has to fan out into N subscriptions.

Related

• Replace x-medkit response extensions with dedicated REST resources #140 - Replace x-medkit response extensions with dedicated REST resources (tension with option A)
• feat(graph): x-medkit-graph vendor resource schema proposal for live pipeline topology #248 / Add x-medkit-graph provider and function cyclic subscriptions #270 - x-medkit-graph extension precedent (shows option A is workable if we accept more x-medkit)
• Rethink runtime discovery entity mapping to align with SOVD entity model #325 - Rethink runtime discovery entity mapping to align with SOVD entity model

Ask

Confirm a direction (A, B, or a third option) so the demo bridge can replace the HEAD-probe workaround with something the gateway explicitly supports.

[bburda]

Worth surfacing a related symptom of the same root cause we hit during a synthetic-component audit:

GET /api/v1/components/{id}/faults/{fault_code} for synthetic / runtime-discovered components returns any fault with that fault_code in the system, not just faults reported by apps hosted by that component. Cause is the same string-matching layer this issue calls out.

FaultHandlers::handle_get_fault passes entity_info.namespace_path as source_id to FaultManager::get_fault_with_env. The match logic in fault_manager.cpp is guarded by if (!source_id.empty()) and uses rfind(src, 0) == 0 against fault.reporting_sources. For a synthetic component both fqn and namespace_path are empty, the guard short-circuits, and the scope check is skipped entirely - the handler then returns whichever fault has that code, regardless of which entity actually reported it. Quiet scope leak between components on the per-entity read path.

Both options proposed here happen to fix this too, just from different angles:

• Option A (x-medkit fields in fault payload): if the gateway also persists the x-medkit-entity-id on the fault when it's first ingested, both the SSE stream consumer and the per-entity GET handler can do exact entity-id comparison instead of prefix-string match against reporting_sources.
• Option B (per-entity streams): the URL path already implies the scope, so SSE side is fine - but handle_get_fault (and handle_clear_fault) still need a non-string-match scope check, otherwise the per-entity GET stays leaky regardless of which stream model wins.

So whichever option lands, the gateway-side fault model probably needs an explicit entity_id field captured at ingest time, otherwise the per-entity faults handlers stay coupled to FQN string matching and synthetic components break the same way.

Will track this in a follow-up bug specifically for the GET / DELETE per-entity path; mentioning here so the design decision on this issue accounts for both consumers.