feat(recorder): tune ROS2 QoS and recorder compression behavior

[Nauyix]

Pull Request Checklist

Please ensure your PR meets the following requirements:

• Code follows the style guidelines
• Tests pass locally (make test or make docker-test)
• Code is formatted (make format)
• Documentation updated if needed
• Commit messages follow conventional commits
• PR description is complete and clear

---

Summary

This PR keeps recorder compression level 3 aligned with the documented default preset, adds configurable ROS2 subscription QoS depth, and copies ROS2 serialized payloads before returning from subscription callbacks.

---

Motivation

• Recorder YAML/CLI documentation describes compression_level: 3 as the balanced default, but directly casting to MCAP's enum made it Slow.
• High-rate ROS2 topics need a subscription-level history depth knob that is separate from Axon's worker queue size.
• Retaining rclcpp::SerializedMessage buffers in Axon's queues can hold DDS/rclcpp receive buffers longer than the ROS callback lifetime, throttling high-rate topics under recorder backlog.

---

Changes

Modified Files

• core/axon_mcap/mcap_writer_wrapper.cpp - Adds legacy recorder/CLI compression-level translation before resolving MCAP writer options.
• core/axon_mcap/mcap_writer_wrapper.hpp - Exposes compression_level_from_legacy_int() and documents the compatibility mapping.
• core/axon_mcap/test/test_mcap_writer.cpp - Covers the legacy integer-to-preset mapping, including the documented 3 -> Default case.
• apps/axon_recorder/src/core/recorder.hpp - Adds per-subscription qos_depth with default depth 10.
• apps/axon_recorder/src/config/config_parser.cpp - Parses, saves, and validates qos_depth values.
• apps/axon_recorder/src/core/recorder.cpp - Passes qos_depth into middleware subscribe options.
• apps/axon_recorder/test/unit/test_config_parser.cpp - Covers qos_depth parsing, defaults, validation, and save/load behavior.
• apps/axon_recorder/config/README.md - Documents qos_depth and the updated compression-level mapping.
• apps/axon_recorder/config/default_config_ros1.yaml - Updates compression-level comments.
• apps/axon_recorder/config/default_config_ros2.yaml - Documents qos_depth and updates compression-level comments.
• apps/axon_recorder/config/default_config_udp.yaml - Updates compression-level comments.
• apps/axon_recorder/axon_recorder.cpp - Updates CLI help text for compression-level presets.
• middlewares/ros2/include/ros2_subscription_wrapper.hpp - Declares subscribe QoS option application and updates v2 callback ownership comments.
• middlewares/ros2/src/ros2_plugin_export.cpp - Applies qos_depth / legacy queue_size and reliability options for ROS2 subscriptions.
• middlewares/ros2/src/ros2_subscription_wrapper.cpp - Copies serialized payloads into plugin-owned storage before invoking Axon's v2 callback.
• middlewares/ros2/test/test_ros2_plugin.cpp - Covers QoS depth and reliability option handling.

Added Files

N/A

Deleted Files

N/A

---

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update (documentation changes only)
• Refactoring (code improvement without functional changes)
• Performance improvement (code changes that improve performance)
• Test changes (adding, modifying, or removing tests)

---

Impact Analysis

Breaking Changes

None.

Backward Compatibility

• Existing configs without qos_depth keep the default ROS2 subscription history depth of 10.
• Existing middleware option key queue_size is accepted as a fallback for QoS depth.
• Existing recorder/CLI integer compression levels remain accepted, with 3 restored to the documented Default behavior and values >=5 mapped to Slowest.

---

Testing

Test Environment

• ROS Distribution: ROS 2 Jazzy
• OS: Ubuntu 24.04.4 LTS, Linux 6.17.0-29-generic, x86_64
• Build Type: existing local build directory
• Base: origin/main at e347f0aff25b315d4ba34c6ed5ed1d194b2a6a4b
• Head tested/pushed: 8d6ab51484326dcca5dab47d3eb9b8276617560e

Test Cases

• Unit tests pass locally
• Integration tests pass locally
• E2E tests pass (if applicable)
• Manual testing completed

Manual Testing Steps

Automated focused validation run locally:

1. git diff origin/main..feat/recorder-runtime-qos-mcap-ros2 --check - passed.
2. cmake --build build --target axon_recorder test_config_parser test_ros2_plugin test_mcap_writer test_mcap_batch_and_async test_recording_session -j8 - passed.
3. ./build/axon_recorder/test/test_config_parser - passed, 54/54 tests.
4. ./build/middlewares/ros2_plugin/test_ros2_plugin - passed, 36/36 tests.
5. ./build/axon_mcap/test_mcap_writer - passed, 39/39 tests.
6. ./build/axon_mcap/test_mcap_batch_and_async - passed, 12/12 tests.
7. ./build/axon_recorder/test/test_recording_session - passed, 37/37 tests.

Full ./scripts/ci-all-local.sh, WS RPC client E2E, format/reuse, Zenoh, and full ROS/E2E CI matrix were not run locally for this draft PR.

Test Coverage

• New tests added
• Existing tests updated
• Coverage maintained or improved

---

Screenshots / Recordings

N/A

---

Performance Impact

• Memory usage: Increased by one owned serialized payload copy per queued ROS2 v2 message; this avoids retaining DDS/rclcpp receive buffers in Axon's queues.
• CPU usage: Slightly increased on ROS2 v2 subscription callbacks due to payload copying.
• Recording throughput: Expected to improve stability for high-rate topics under backlog by releasing ROS receive buffers promptly.
• Lock contention: No change.

---

Documentation

• README.md updated
• ARCHITECTURE.md updated
• CONTRIBUTING.md updated
• API documentation updated
• Design docs updated in docs/designs/
• No documentation changes needed beyond recorder config docs and example config comments updated in this PR

---

Related Issues

N/A

---

Additional Notes

This is intentionally opened as a draft because only focused local validation has been run, not the full remote-equivalent CI gate required for ready-for-review.

---

Reviewers

N/A

---

Notes for Reviewers

• Please review the recorder compression compatibility mapping in core/axon_mcap/mcap_writer_wrapper.cpp.
• Please review the QoS option contract between recorder config and ROS2 plugin subscribe options.
• Please review the ROS2 v2 serialized payload ownership change and its CPU/memory tradeoff.

---

Checklist for Reviewers

• Code changes are correct and well-implemented
• Tests are adequate and pass
• Documentation is updated and accurate
• No unintended side effects
• Performance impact is acceptable
• Backward compatibility maintained (if applicable)

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.