docs+fix: update documentation and API responses for post-0.3.0 changes by bburda · Pull Request #258 · selfpatch/ros2_medkit

bburda · 2026-03-07T11:31:03Z

Pull Request

Summary

Fix outdated documentation, API response bugs, and a discovery bug after merge pipeline, logging, and plugin system changes landed on main. Extend entity capabilities for areas/functions and fix cyclic subscription sampler scoping.

Breaking changes:

GET /version-info response key renamed from sovd_info to SOVD-standard items
GET / root endpoint restructured: flat string endpoint list, new capabilities object, api_base/name/version fields
Default rosbag storage format changed from sqlite3 to mcap

Code fixes:

Fix MANIFEST_ONLY mode leaking topic-based components into entity cache (gateway_node.cpp)
Add missing endpoint categories to handle_root: logs, bulk-data, cyclic-subscriptions, updates
Add missing capabilities to handle_root: logs, bulk_data, cyclic_subscriptions, updates
Remove ghost snapshot endpoints from handle_root (listed but never route-registered)
Fix hardcoded version "0.1.0" -> "0.3.0"
Add bulk-data, logs, cyclic-subscriptions URI fields to entity capability responses
Extend entity capabilities: areas and functions now support all resource collections (DATA, OPERATIONS, CONFIGURATIONS, FAULTS, LOGS, BULK_DATA) with aggregation markers
Add log endpoints for areas/functions: 6 new routes (GET/PUT logs, logs/configuration for areas and functions)
Fix faults sampler scoping: AREA uses namespace, FUNCTION uses host FQNs, COMPONENT uses app FQNs (previously returned all faults unfiltered for areas/functions)
Fix logs sampler scoping: uses prefix/exact matching per entity type, matching REST handler logic (previously used exact matching for all)
Hoist duplicated validation in log_handlers.cpp (severity/context params)
Add area/function bulk-data endpoints to handle_root endpoint list
Add App::effective_fqn() workaround for manifest_only mode where bound_fqn is never set - derives FQN from ros_binding fallback. Replace all direct bound_fqn accesses in handlers, samplers, config aggregation, and plugin context (Set bound_fqn from ros_binding at manifest parse time #262)

Documentation fixes:

Add CHANGELOG 0.3.0 Breaking Changes section and new feature entries
Add /version-info example response in rest.rst
Fix self -> href in area/component list examples (matching actual code)
Remove stale area field from components list example
Fix jq commands in tutorials (.[] -> .items[])
Add merge pipeline reference (field groups, policies, gap-fill, health endpoint) to discovery-options.rst
Add .. contents:: TOC and case-sensitivity note for policy values
Fix strategy name HybridDiscoveryStrategy -> hybrid in health example
Fix Field Groups table (status, metadata) to match merge_types.hpp
Fix health endpoint JSON example to match MergeReport::to_json()
Fix gap-fill disabled description in manifest-discovery.rst
Add Logging and Rate Limiting sections to server.rst
Update plugin system tutorial: IntrospectionProvider wired via PluginLayer, add LogProvider
Remove LogProvider include/export from UpdateProvider example
Clarify IntrospectionProvider metadata is plugin-internal
Document DELETE /{entity}/faults, areas/functions resource collection notes
Add SOVD compliance philosophy section with resource collection support matrix
Fix SOVD Compliance RST heading level (h3 -> h2)
Update Logs Endpoints section to mention areas and functions with dispatch semantics
Restore See Also cross-references (authentication, server config)
Fix em dashes to hyphens in log configuration section
Fix copilot-instructions.md for effective code review
Add @verifies REQ_INTEROP_003 to test_plugin_vendor_extensions

Issue

closes docs+fix: update documentation and API responses for post-0.3.0 changes #257
Related: Set bound_fqn from ros_binding at manifest parse time #262 (proper fix for manifest_only bound_fqn)

Type

Bug fix
New feature or tests
Breaking change
Documentation only

Testing

All 1302 gateway unit tests pass (0 errors, 0 failures, 0 skipped)
Integration tests pass: test_bulk_data_api, test_scenario_discovery_manifest
sphinx-build completes with zero warnings
Linters pass (0 failures)
Pre-commit hooks pass on all commits

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

Follow-up issues

Security hardening: plugin safety and /health info leak #259 - Security hardening: plugin safety + /health info leak
Merge pipeline architecture improvements #260 - Merge pipeline architecture improvements
Test coverage gaps in merge pipeline and discovery #261 - Test coverage gaps in merge pipeline
Set bound_fqn from ros_binding at manifest parse time #262 - Set bound_fqn from ros_binding at manifest parse time
[BUG] VersionInfo type uses removed sovd_info key - gateway renamed to items sovd_web_ui#39 - sovd_info -> items rename in web UI
[BUG] VersionInfo type uses removed sovd_info key - gateway renamed to items ros2_medkit_foxglove_extension#2 - sovd_info -> items rename in Foxglove extension

Copilot

Pull request overview

Updates Sphinx documentation to reflect gateway behavior after post-0.3.0 changes (logging, hybrid discovery merge pipeline, and plugin providers), keeping tutorials and reference docs aligned with current configuration and APIs.

Changes:

Refresh plugin system tutorial to cover LogProvider and updated IntrospectionProvider wiring.
Replace outdated hybrid/manifest discovery guidance with merge-pipeline gap-fill configuration docs.
Extend server config reference with logging buffer and rate limiting options; update REST API examples.

Reviewed changes

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

Show a summary per file

File	Description
docs/tutorials/plugin-system.rst	Updates provider list and plugin export examples (adds `LogProvider`).
docs/tutorials/manifest-discovery.rst	Replaces unmanifested-node section with hybrid merge-pipeline gap-fill guidance.
docs/config/server.rst	Adds `logs.buffer_size` and `rate_limiting.*` configuration reference sections.
docs/config/discovery-options.rst	Adds merge pipeline concepts (field groups, policies, gap-fill) and health endpoint example.
docs/api/rest.rst	Updates `GET /api/v1/` server capabilities example response.

docs/tutorials/plugin-system.rst

docs/api/rest.rst

docs/config/discovery-options.rst

Copilot · 2026-03-07T11:36:24Z

docs/config/discovery-options.rst

+     - is_online, health, runtime state
+   * - ``metadata``
+     - source, category, custom metadata fields


The Field Groups table looks out of sync with the implementation. In merge_types.hpp / merge_pipeline.cpp, status is primarily is_online + bound_fqn (and external for apps); there is no merged health/"runtime state" field group, and metadata is described as source + vendor/custom fields (not category). Please adjust the table entries for status/metadata to match what the merge pipeline actually groups and merges today.

Suggested change

- is_online, health, runtime state

* - ``metadata``

- source, category, custom metadata fields

- is_online, bound_fqn (and external for apps)

* - ``metadata``

- source plus vendor/custom metadata fields

Fixed in 80091bc - Field Groups table updated: STATUS = is_online, bound_fqn; METADATA = source, x-medkit extensions, custom metadata fields.

docs/tutorials/manifest-discovery.rst

docs/tutorials/plugin-system.rst

Copilot

Pull request overview

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

docs/api/rest.rst

src/ros2_medkit_gateway/test/test_health_handlers.cpp

src/ros2_medkit_gateway/src/http/handlers/health_handlers.cpp

src/ros2_medkit_gateway/src/http/handlers/discovery_handlers.cpp

docs/api/rest.rst

Code fixes: - Remove areas/functions bulk-data from handle_root (validation rejects them) - Rename test HandleVersionInfoContainsSovdInfoArray -> HandleVersionInfoContainsItemsArray - Fix test_root_endpoint_includes_snapshots: verify legacy snapshot endpoints are NOT listed Docs fixes: - rest.rst: fix self -> href in area/component list examples - rest.rst: remove /bulk-data from areas and functions resource collections - plugin-system.rst: remove LogProvider include/export from UpdateProvider example - plugin-system.rst: clarify IntrospectionProvider metadata is plugin-internal - discovery-options.rst: fix Field Groups table (status, metadata fields) - discovery-options.rst: fix health endpoint JSON to match MergeReport::to_json() - manifest-discovery.rst: fix gap-fill disabled description

Copilot

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 6 comments.

src/ros2_medkit_gateway/src/http/handlers/discovery_handlers.cpp

src/ros2_medkit_gateway/src/http/handlers/health_handlers.cpp

src/ros2_medkit_gateway/test/test_health_handlers.cpp

src/ros2_medkit_gateway/src/gateway_node.cpp

…nodes section The param names in the launch/YAML/CLI examples were already correct (discovery.mode, discovery.manifest_path), so no changes needed there. Replaced the "Handling Unmanifested Nodes" section which documented the nonexistent config.unmanifested_nodes parameter (with ignore/warn/error/ include_as_orphan policies) with "Controlling Gap-Fill in Hybrid Mode" documenting the actual discovery.merge_pipeline.gap_fill.* parameters. Added a note block to the Runtime Linking section explaining the layered merge pipeline architecture.

…add LogProvider

…info format - Add missing endpoint categories to handle_root: logs, bulk-data, cyclic-subscriptions, updates (conditional), DELETE /faults (global) - Remove ghost snapshot endpoints (listed but never registered) - Add missing capabilities: logs, bulk_data, cyclic_subscriptions, updates - Fix hardcoded version "0.1.0" -> "0.3.0" in handle_root and version-info - Change version-info response key from "sovd_info" to "items" (SOVD standard) - Add bulk-data, logs, cyclic-subscriptions URIs to entity capability responses - Update rest.rst: fix Server Capabilities example format, remove phantom /manifest/status, document DELETE /{entity}/faults, update SOVD compliance section, add areas/functions resource collection notes - Update tests, integration tests, and Postman collection for sovd_info->items

Code fixes: - Remove areas/functions bulk-data from handle_root (validation rejects them) - Rename test HandleVersionInfoContainsSovdInfoArray -> HandleVersionInfoContainsItemsArray - Fix test_root_endpoint_includes_snapshots: verify legacy snapshot endpoints are NOT listed Docs fixes: - rest.rst: fix self -> href in area/component list examples - rest.rst: remove /bulk-data from areas and functions resource collections - plugin-system.rst: remove LogProvider include/export from UpdateProvider example - plugin-system.rst: clarify IntrospectionProvider metadata is plugin-internal - discovery-options.rst: fix Field Groups table (status, metadata fields) - discovery-options.rst: fix health endpoint JSON to match MergeReport::to_json() - manifest-discovery.rst: fix gap-fill disabled description

- rest.rst: add /version-info example response, remove stale `area` field from components list example - rest.rst: document sovd_info -> items rename in CHANGELOG as breaking change - discovery-options.rst: add local TOC, note case-sensitivity for policy values, fix strategy name "HybridDiscoveryStrategy" -> "hybrid" - manifest-discovery.rst, migration-to-manifest.rst: fix jq commands (.[] -> .items[]) - CHANGELOG.rst: add Breaking Changes section and new 0.3.0 features - test_plugin_vendor_extensions.test.py: add @verifies REQ_INTEROP_003

refresh_cache() was calling discover_topic_components() for both RUNTIME_ONLY and MANIFEST_ONLY modes. In manifest_only mode this added synthetic components from the runtime ROS 2 graph, violating the intent of "only manifest entities." Invert the condition so only RUNTIME_ONLY merges topic components. MANIFEST_ONLY and HYBRID both use discover_components() directly.

…ion test Rename 3 unit tests referencing old "SovdEntry" naming to "ItemsEntry" to match the sovd_info->items rename in handle_version_info. Add regression test verifying that topic-based components do not leak into the entity cache in manifest_only discovery mode (validates the fix in gateway_node.cpp discover_components).

…tions Enable resource collections (data, operations, configurations, faults, logs, bulk-data) on areas and functions. SOVD defines these only for apps/components - this is a pragmatic ros2_medkit extension. Add log routes for areas (namespace prefix match) and functions (aggregate from hosted apps). Update capability responses to include logs and bulk-data URIs. Fix entity_capabilities.cpp to match actual route registrations.

Document ros2_medkit's pragmatic approach to SOVD - we extend the spec where ROS 2 use cases benefit (resource collections on areas/functions, x-medkit vendor extensions). Add resource collection support matrix. Fix incorrect claims about areas supporting same collections as components. Add changelog entries for area/function log endpoints.

…t, docs Code fixes: - Fix faults sampler to scope by entity type (AREA: namespace, FUNCTION: host FQNs, COMPONENT: app FQNs) matching REST handler behavior - Fix logs sampler to use prefix/exact matching per entity type, matching log_handlers.cpp scoping logic - Hoist duplicated severity/context parameter validation in log_handlers - Add area/function bulk-data endpoints to handle_root endpoint list Docs fixes: - Fix SOVD Compliance RST heading level (~~~ -> --- for h2) - Update Logs Endpoints section to mention areas and functions - Restore See Also cross-references (authentication, server config) - Fix em dashes to hyphens in log configuration section

In manifest_only discovery mode, Apps never get bound_fqn set because runtime_linker only runs in hybrid mode. This caused handlers, samplers, and configuration aggregation to silently return empty results for all App-based lookups (logs, faults, configurations). Add App::effective_fqn() that prefers bound_fqn when available, falling back to deriving the FQN from ros_binding (namespace_pattern + node_name). Replace all direct bound_fqn accesses in handler_context, log_handlers, fault_handlers, gateway_node samplers, thread_safe_entity_cache config aggregation, and plugin_context with effective_fqn() calls. Update test_bulk_data_api for areas now returning 200 (entity capabilities extended) and test_scenario_discovery_manifest timeout for log aggregation.

Copilot AI review requested due to automatic review settings March 7, 2026 11:31

Copilot started reviewing on behalf of bburda March 7, 2026 11:31 View session

bburda self-assigned this Mar 7, 2026

bburda added the documentation Improvements or additions to documentation label Mar 7, 2026

Copilot AI reviewed Mar 7, 2026

View reviewed changes

bburda changed the title ~~docs: update documentation for post-0.3.0 changes~~ docs+fix: update documentation and API responses for post-0.3.0 changes Mar 7, 2026

bburda requested a review from Copilot March 7, 2026 12:12

Copilot started reviewing on behalf of bburda March 7, 2026 12:12 View session

bburda requested a review from mfaferek93 March 7, 2026 12:18

bburda added the bug Something isn't working label Mar 7, 2026

Copilot AI reviewed Mar 7, 2026

View reviewed changes

bburda requested a review from Copilot March 7, 2026 19:36

Copilot started reviewing on behalf of bburda March 7, 2026 19:36 View session

Copilot AI reviewed Mar 7, 2026

View reviewed changes

This was referenced Mar 13, 2026

fix: update VersionInfo type for gateway sovd_info->items rename selfpatch/sovd_web_ui#40

Open

fix: update VersionInfo type for gateway sovd_info->items rename selfpatch/ros2_medkit_foxglove_extension#3

Open

bburda added 9 commits March 13, 2026 08:36

docs(config): add Logging and Rate Limiting sections to server reference

4e7384e

docs(config): add merge pipeline reference to discovery options

494c36d

docs(api): update server capabilities example response

571a262

docs(tutorials): update plugin system - IntrospectionProvider wired, …

5e454b1

…add LogProvider

bburda added 4 commits March 13, 2026 08:36

bburda force-pushed the docs/update-post-0.3.0 branch from 2f3cd94 to 478233e Compare March 13, 2026 07:39

bburda mentioned this pull request Mar 13, 2026

Set bound_fqn from ros_binding at manifest parse time #262

Open

Conversation

bburda commented Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request

Summary

Issue

Type

Testing

Checklist

Follow-up issues

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

bburda Mar 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

bburda commented Mar 7, 2026 •

edited

Loading