Add --content-filter support to ros2 topic echo|hz|bw

[PavelGuzenfeld]

Summary

Closes #1126

Adds DDS content filter expression support to ros2 topic echo, ros2 topic hz, and ros2 topic bw commands via new --content-filter and --content-filter-params CLI arguments.

Content filters are applied at the middleware level (via rclpy.subscription_content_filter_options.ContentFilterOptions), so only matching messages are delivered to the subscriber — reducing bandwidth and CPU usage compared to client-side Python --filter expressions.

Usage examples:

# Echo only messages where data contains "Hello"
ros2 topic echo /chatter --content-filter "data LIKE '%Hello%'"

# Measure hz of messages matching a filter with parameters
ros2 topic hz /sensor --content-filter "temperature > %0" --content-filter-params 30.0

# Measure bandwidth of filtered messages
ros2 topic bw /camera/image --content-filter "header.frame_id = %0" --content-filter-params camera_front

Changes:

• echo.py: Add --content-filter and --content-filter-params arguments, pass ContentFilterOptions to create_subscription
• hz.py: Same additions, passed through _rostopic_hz
• bw.py: Same additions, passed through _rostopic_bw

Test plan

• ros2 topic echo --help shows new --content-filter and --content-filter-params options
• ros2 topic hz --help shows new options
• ros2 topic bw --help shows new options
• E2E: echo with matching filter (data LIKE '%Hello%') receives messages
• E2E: echo with non-matching filter (data LIKE '%NOMATCH%') receives no messages
• E2E: echo/hz/bw without --content-filter works unchanged

[christophebedard]

Thank you for the PR! Please see my note here: ros2/rclcpp#3109 (comment)

[PavelGuzenfeld]

Thanks for the review!

AI disclosure: This PR was authored with the assistance of Claude (Anthropic) as a generative AI coding tool. I have reviewed and validated the changes.

Branch target: Will retarget to rolling now.

[PavelGuzenfeld]

Correction on the AI disclosure: the model used was Claude Opus (Anthropic).

[PavelGuzenfeld]

Rebased onto rolling as requested. The diff is now clean (1 commit, 3 files changed).

The original feature request (#1126) applies to jazzy and humble as well. Would appreciate a backport to those distros once this is merged into rolling.

[PavelGuzenfeld]

The CI failure is a flaky test, not caused by this PR:

FAIL: test_topic_echo_field_invalid[rmw_fastrtps_cpp]

The test uses strict=True output matching and expects only the error message, but a DDS "message was lost" event fired during discovery, adding unexpected output:

"A message was lost!!!\n\ttotal count change:1\n\ttotal count: 1---\n
Invalid field '/': 'Arrays' object has no attribute '/'\n"

This PR only adds --content-filter / --content-filter-params arguments and does not modify the --field processing path or the subscribe_and_spin message-lost callback (which already existed). The flaky failure is a DDS-level race condition unrelated to content filtering.

Could a maintainer please re-trigger the CI?

[christophebedard]

It seems like the content filtering feature might be able to replace the Python expression-based filtering above (--filter), which has security implications.

@fujitatomoya since you're familiar with content filtering, what do you think?

[christophebedard]

Can you add tests to the commands you've added these new options to? At least just to exercise the happy path and check that it does filter with a simpler filter, nothing complicated.

[PavelGuzenfeld]

Added tests in the latest push:

test_echo_pub.py — test_echo_content_filter (match + no-match), test_echo_content_filter_once (with --once), test_echo_content_filter_combined_with_filter (DDS + Python --filter together)

test_bw_delay_hz.py — test_hz_content_filter, test_bw_content_filter (happy path), plus _no_match variants for both

test_content_filter_contract.py — arg parsing and ContentFilterOptions construction for all three verbs, including --content-filter-params

Note: Fast DDS doesn't support bare string %0 parameter substitution — DDSFilterParameter::set_value() requires values to be valid SQL literals (strings need single quotes). Filed a fix for that in the rmw layer: ros2/rmw_fastrtps#873