refactor(noq)!: open path by four tuple and replace open_path_ensure with OpenPathOpts

[Frando]

Description

Replaced #653
Improve the APIs to open paths on both noq and noq-proto.

• Connection::open_path now takes a FourTuple (allowing the caller to specify local_ip) instead of a bare SocketAddr remote.
• open_path_ensure is removed. Its duplicate-path semantics now live inside open_path, with a new OpenPathOpts::allow_duplicate flag (default false). When a path with a matching 4-tuple already exists, open_path returns the new PathError::PathExistsForNetworkPath(PathId).
• The initial_status argument is replaced with OpenPathOpts, which carries initial_status and allow_duplicate. We can add more fields without breaking changes this way too.
• noq::Connection::open_path now returns Result<OpenPath, PathError>. Thus immediate errors are surfaced at the call site instead of deferring them to the returned future. OpenPath becomes a struct instead of an enum, and we can use a oneshot instead of a watch channel now

Breaking Changes

• changed: noq_proto::Connection::open_path now takes(FourTuple, OpenPathOpts, Instant), with the initial_status being set on the OpenPathOpts
• removed: noq_proto::Connection::open_path_ensure. Use open_path
  with OpenPathOpts::default() (returns PathExistsForNetworkPath
  when a matching path exists) or OpenPathOpts::default().allow_duplicate(true).
• changed: noq::Connection::open_path signature is now(FourTuple, OpenPathOpts) -> Result<OpenPath, PathError>.
• removed: noq::Connection::open_path_ensure: removed. use open_path with OpenPathOpts::default().allow_duplicates(true) instead
• noq::OpenPath::path_id: returns PathId instead of Option<PathId>.

Change checklist

• Self-review.
• All breaking changes documented.

[github-actions]

Documentation for this PR has been generated and is available at: https://n0-computer.github.io/noq/pr/655/docs/noq/

Last updated: 2026-05-14T15:37:59Z

[github-actions]

Performance Comparison Report

14f50b33e32756cb7e28c24ae396c23d9ebd08d1 - artifacts

Netsim Benchmarks (network simulation)

Condition	noq	upstream	Delta
ideal	3178.2 Mbps	4148.9 Mbps	-23.4%
lan	782.4 Mbps	810.3 Mbps	-3.4%

Summary

noq is 20.1% slower on average

---

9a5b2f4db5b525860d40e8e243b4016872d11af5 - artifacts

Raw Benchmarks (localhost)

Scenario	noq	upstream	Delta	CPU (avg/max)
large-single	5551.1 Mbps	8016.4 Mbps	-30.8%	96.7% / 98.4%
medium-concurrent	5516.9 Mbps	7641.7 Mbps	-27.8%	96.2% / 97.8%
medium-single	4158.8 Mbps	4749.3 Mbps	-12.4%	96.1% / 98.0%
small-concurrent	3919.3 Mbps	5296.0 Mbps	-26.0%	97.8% / 99.8%
small-single	3564.1 Mbps	4771.6 Mbps	-25.3%	96.1% / 98.3%

Netsim Benchmarks (network simulation)

Condition	noq	upstream	Delta
ideal	3088.4 Mbps	3984.9 Mbps	-22.5%
lan	782.4 Mbps	810.3 Mbps	-3.4%
lossy	69.8 Mbps	55.9 Mbps	+25.0%
wan	83.8 Mbps	83.8 Mbps	~0%

Summary

noq is 24.5% slower on average

---

335b7b8921e6f345aa63e594371f3d6658f25dc2 - artifacts

Raw Benchmarks (localhost)

Scenario	noq	upstream	Delta	CPU (avg/max)
large-single	5458.4 Mbps	8068.0 Mbps	-32.3%	95.1% / 146.0%
medium-concurrent	5337.5 Mbps	7722.3 Mbps	-30.9%	95.7% / 147.0%
medium-single	4327.6 Mbps	4748.9 Mbps	-8.9%	98.3% / 149.0%
small-concurrent	3881.8 Mbps	5226.0 Mbps	-25.7%	94.3% / 102.0%
small-single	3476.5 Mbps	4822.1 Mbps	-27.9%	93.7% / 102.0%

Netsim Benchmarks (network simulation)

Condition	noq	upstream	Delta
ideal	3048.8 Mbps	4022.9 Mbps	-24.2%
lan	782.4 Mbps	810.4 Mbps	-3.4%
lossy	69.9 Mbps	69.8 Mbps	~0%
wan	83.8 Mbps	83.8 Mbps	~0%

Summary

noq is 25.6% slower on average

[flub]

did you have a motivation to have to keep this option?

[Frando]

• in handle_network_change, when opening replacement paths for non-recoverable paths, I currently set allow_duplicates(true). Reason: The replacement path wouldn't be opened otherwise, because we cleared the local_ip beforehand on all paths.
• Not a justification, but a reason in the initial PR: We need it in the noq test suite, because otherwise we couldn't open multiple paths over localhost reliably, which we do in the noq multipath tests.

Do you think it should be removed?