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