fix(issue-74): enforce left-side publish authority mapping and add reproducible CLI validation

[PLeVasseur]

Summary

• Fix issue Pubsub messages are being forwarded even if different subject mappings are specified in subscription.json #74 by enforcing left-side/topic authority constraints for publish forwarding in up-streamer.
• Keep request/response/notification forwarding behavior unchanged while tightening publish listener registration.
• Add deterministic regression tests for allowed, blocked, wildcard, and unregister-cleanup cases.
• Parameterize all example binaries for CLI URI overrides and add reproducible issue-74 runbook docs.
• Align integration harness unregister behavior with UTransport register/unregister symmetry.

Stacked Branch Context

• This branch was developed as a stacked branch on top of perf/ci-pr-latency-reduction.
• That base branch is not present upstream, so this PR intentionally targets main and therefore includes inherited parent commits.
• Issue-74 review focus is the top 6 commits on this branch:
  • 0d441dc add shared CLI parsing helpers for example binaries
  • b134d5a parameterize MQTT and Zenoh pubsub binaries
  • 08b3c0e parameterize remaining example binaries for CLI overrides
  • c026489 fix publish forwarding authority matching in streamer
  • c51bfc8 document issue74 runbook and CLI override usage
  • a553a37 fix integration harness listener unregister symmetry
• Inherited parent commits (CI/dependency groundwork) are included because of the stacked-base constraint.

Issue #74 Scope and Semantics

• Enforce mapping semantics as: left side of subscription_data.json = allowed publish source filter; right side = subscriber URIs.
• Register publish listeners only when topic authority matches in_authority or left-side wildcard *.
• Keep right-side wildcard behavior unchanged (out of scope for this fix).

Addendum: Issue #74 Baseline + Follow-up Validation Matrix (Scope-Only)

This addendum intentionally focuses on routing semantics and validation only. It excludes MSRV and CI-improvement topics.

Base Issue #74 changes

1. Base Issue Pubsub messages are being forwarded even if different subject mappings are specified in subscription.json #74: left-side publish authority enforcement

• Change: publish listener registration is constrained by left-side mapping authority; publish source is eligible only when topic authority is in_authority or *.
• Rationale: enforce map semantics so publish forwarding only occurs for intended source authorities.
• Source refs: up-streamer/src/ustreamer.rs:194
• Test refs: up-streamer/src/ustreamer.rs:1600, up-streamer/src/ustreamer.rs:1642, up-streamer/src/ustreamer.rs:1677, up-streamer/src/ustreamer.rs:2018

2. Base Issue Pubsub messages are being forwarded even if different subject mappings are specified in subscription.json #74: reproducible CLI override surface for example binaries

• Change: shared parsing/build helpers and common override behavior were added for example binaries.
• Rationale: make issue-74 reproduction and transport validation deterministic from CLI inputs.
• Source refs: example-streamer-uses/src/bin/common/cli.rs:13, example-streamer-uses/src/bin/common/cli.rs:53, example-streamer-uses/src/bin/common/cli.rs:65, example-streamer-uses/src/bin/zenoh_client.rs:80, example-streamer-uses/src/bin/someip_client.rs:88
• Test refs: example-streamer-uses/src/bin/common/cli.rs:94, example-streamer-uses/src/bin/common/cli.rs:100, example-streamer-uses/src/bin/common/cli.rs:115, example-streamer-uses/src/bin/common/cli.rs:124, example-streamer-uses/src/bin/common/cli.rs:146

3. Base Issue Pubsub messages are being forwarded even if different subject mappings are specified in subscription.json #74: integration harness unregister symmetry

• Change: harness unregister behavior is symmetric with register semantics for authority/topic listener paths.
• Rationale: prevent false negatives in integration behavior due to harness-side listener bookkeeping mismatch.
• Source refs: utils/integration-test-utils/src/up_client_foo.rs:235, utils/integration-test-utils/src/up_client_foo.rs:294, utils/integration-test-utils/src/up_client_foo.rs:310
• Test refs: up-streamer/tests/single_local_two_remote_add_remove_rules.rs:40

Follow-up changes

4. Follow-up: right-side wildcard subscriber-authority expansion (rule-bound)

• Change: forwarding lookup now merges exact out_authority and wildcard subscriber authority (*) rows.
• Rationale: support //*/... subscriber-authority entries without bypassing forwarding-rule topology.
• Source refs: subscription-cache/src/lib.rs:153, up-streamer/src/ustreamer.rs:327, up-streamer/src/ustreamer.rs:450
• Test refs: up-streamer/src/ustreamer.rs:1724, up-streamer/src/ustreamer.rs:1775

5. Follow-up: effective publish listener-key dedupe on insert/remove

• Change: publish listener keys are normalized into a unique set before register and before unregister.
• Rationale: overlapping rows can resolve to the same effective publish source; dedupe prevents duplicate register/unregister attempts and duplicate-driven rollback side effects.
• Source refs: up-streamer/src/ustreamer.rs:225, up-streamer/src/ustreamer.rs:340, up-streamer/src/ustreamer.rs:465
• Test refs: up-streamer/src/ustreamer.rs:1903

6. Follow-up: add_forwarding_rule rollback consistency

• Change: on listener insertion failure, the just-added forwarding-rule entry and acquired transport-forwarder reference are rolled back.
• Rationale: failed adds must leave no stale control-plane state and allow clean retry.
• Source refs: up-streamer/src/ustreamer.rs:819, up-streamer/src/ustreamer.rs:851, up-streamer/src/ustreamer.rs:878
• Test refs: up-streamer/src/ustreamer.rs:1962

7. Follow-up DG-1 Path A: subscription identity semantics (topic + subscriber)

• Change: cache row identity was updated from subscriber-only to topic + subscriber.
• Rationale: preserve topic-distinct rows for a shared subscriber and correctly reflect rebuilt-cache removals.
• Source refs: subscription-cache/src/lib.rs:40, subscription-cache/src/lib.rs:46
• Test refs: subscription-cache/src/lib.rs:214, subscription-cache/src/lib.rs:238, subscription-cache/src/lib.rs:269

[sophokles73]

this can be done with a lot less code/effort using the clap-num crate:

Suggested change

	#[arg(long, default_value = DEFAULT_UENTITY)]
	uentity: String,
	#[arg(long, default_value = DEFAULT_UENTITY, value_parser = clap_num::maybe_hex::<u32>)]
	uentity: u32,

[sophokles73]

Given that all you need these args for is creating the source and sink UUris, I guess it would be much easier to simply define args source and sink having type UUri and using UUri::from_str as the value parser function ...

[PLeVasseur]

Oh, nice :)

[PLeVasseur]

I'm interested in doing this. Maybe not in this PR though?

There's a follow-up PR which does a lot of refactoring:
#78

Perhaps after that one?