[ryanolson]

What

A TCP or QUIC transport can advertise socket addresses, ports included, that differ from its bind address. A peer that reaches the transport through a proxy, a NAT, or an overlay that maps another port then dials the mapped address.

• TcpTransportBuilder::advertise_addrs and QuicTransportBuilder::advertise_addrs. The given addresses replace the interface_filter result in the WorkerAddress. The transport still listens on its bind address.
• InterfaceFilter::Explicit keeps its behavior: it replaces each port with the bound port. Existing callers can depend on that, so this PR adds a builder method and does not change the variant. The change is additive. The semver gate accepts it under the 0.21.0 bump that main already carries.
• QUIC: with advertised addresses, the entry lists no per-socket ports. Every lane of a peer then dials the advertised port, because a mapping covers one port. Lanes from one peer share one server socket in this mode.
• QuicTransport::bound_addr gives the first server socket address, which is where such a mapping forwards.
• QUIC register keeps only the advertised addresses that the dial sockets reach. These are IPv4 for an IPv4 transport. For an IPv6 transport, they are IPv6, and also IPv4 if its sockets are dual-stack. A peer with no reachable address is refused at registration. Before this, the transport registered the peer, and every frame then failed.

Out of scope

The per-stream TCP listener that VeloBuilder starts does not use advertise_addrs. Behind a proxy, use .mux_only(). The book says this.

Tests

lib/velo/tests/advertised_address.rs:

• Two TCP nodes, each behind its own proxy on its own port, each advertising its proxy. A unary request crosses the server's proxy and the response crosses the client's proxy. Both proxies count more than 0 bytes.
• Two QUIC transports, each behind its own UDP relay. The client sends on two lanes, and the relay of the server sees one source for each lane. The relay forwards to the first server socket only, so a lane that dialed another socket does not arrive.
• The advertised TCP entry holds the given address and port, and not the bound port.

With advertise_addrs ignored in both builders, all three tests fail.

Conflicts

git merge-tree against #154 (QUIC mTLS) shows conflicts in README.md (both add a paragraph above the lanes paragraph) and in lib/velo/src/transports/quic/transport.rs (register and the struct fields). builder.rs, Cargo.toml and the book merge cleanly. Whichever PR merges second needs a small rebase. The hub TLS PR (#155) merges cleanly with both.

Review ledger

An independent reviewer did three rounds (rust-code-review).

Round	Finding	Ruling	Change
1	Medium. IPv4-bound QUIC nodes behind IPv6 proxies register, and then every frame fails with "invalid remote address".	Partly valid. The defect is real. The cause is wider than this PR: QUIC dial sockets take the family of the bind address, so any peer whose first or only address is of the other family fails.	register keeps only the reachable addresses, and refuses a peer with none (InvalidEndpoint). Two tests, which failed first.
2	Medium. The round 1 filter refuses IPv4 peers that a dual-stack IPv6 dialer reaches.	Valid. The round 1 fix caused this regression.	The builder records whether the dial sockets reach IPv4 (IPV6_V6ONLY off). Test a_dual_stack_dialer_reaches_an_ipv4_peer fails with the round 1 filter.
3	None		Verdict: ready

The dial sockets were not made dual-stack. That would change every QUIC dialer, and it fails on hosts with IPv6 off.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: ai-dynamo/velo
• Branch: ai/advertise-addrs
• File: .coderabbit.yaml
• Commit: 04cf9e8
• Layers: Repository YAML
• Review profile: CHILL
• Plan: Enterprise
• Run ID: c87d6f5d-ae12-49ef-8ba0-42a70c74bb14

📥 Commits

Reviewing files that changed from the base of the PR and between cee2834 and 04cf9e8.

📒 Files selected for processing: 10

• README.md
• docs/src/concepts/transports.md
• lib/velo/Cargo.toml
• lib/velo/src/transports/quic/endpoint.rs
• lib/velo/src/transports/quic/tests.rs
• lib/velo/src/transports/quic/transport.rs
• lib/velo/src/transports/quic/transport/builder.rs
• lib/velo/src/transports/tcp/transport/builder.rs
• lib/velo/src/transports/utils/interfaces.rs
• lib/velo/tests/advertised_address.rs

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

Walkthrough

TCP and QUIC builders now accept explicit advertised socket addresses while transports listen on their bound addresses. QUIC registration filters peer endpoints by address-family reachability. Documentation and integration tests cover address configuration and traffic through proxies and relays.

Changes

Advertised transport addresses

Layer / File(s)	Summary
Advertised address configuration lib/velo/src/transports/utils/interfaces.rs, lib/velo/src/transports/tcp/transport/builder.rs, lib/velo/src/transports/quic/transport/builder.rs, lib/velo/src/transports/quic/endpoint.rs, README.md, docs/src/concepts/transports.md	TCP and QUIC builders accept explicit socket addresses, including ports, for peer advertisement. QUIC endpoint information omits per-socket ports when explicit addresses are supplied. The documentation describes the settings and address-family behavior.
QUIC endpoint reachability lib/velo/src/transports/quic/transport.rs, lib/velo/src/transports/quic/transport/builder.rs, lib/velo/src/transports/quic/tests.rs	QUIC registration filters advertised endpoints by the dial transport’s address-family reachability. Tests cover IPv4 selection, unreachable endpoints, and IPv4 access through eligible dual-stack IPv6 sockets.
Proxy and relay integration tests lib/velo/Cargo.toml, lib/velo/tests/advertised_address.rs	Integration tests verify advertised TCP addresses through proxies and QUIC traffic through UDP relays, including traffic across multiple client lanes.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant ClientLane
  participant ServerUdpRelay
  participant QUICServer
  participant ClientUdpRelay
  ClientLane->>ServerUdpRelay: Send datagrams to the advertised endpoint
  ServerUdpRelay->>QUICServer: Forward datagrams to the bound server socket
  QUICServer->>ClientUdpRelay: Send reply to the advertised client endpoint
  ClientUdpRelay->>ClientLane: Relay reply to the client source

Loading

Suggested reviewers: jthomson04

Merge Risk: ⚪ Minimal · up to 04cf9

The advertised-address changes have no identified merge-blocking issue after normal checks.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 69.70% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 33 functions across 7 files. (3 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: allowing TCP and QUIC transports to advertise an address and port different from their bound address.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

Docstring coverage is 69.70% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 33 functions across 7 files. (3 skipped: 3 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

✨ Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 93.10345% with 4 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
lib/velo/src/transports/quic/transport/builder.rs	88.88%	0 Missing and 2 partials ⚠️
lib/velo/src/transports/quic/transport.rs	94.44%	1 Missing ⚠️
lib/velo/src/transports/tcp/transport/builder.rs	87.50%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

🔵 Needs a closer look

Moderate issues remain for unused QUIC server sockets and loss of scoped IPv6 address information.

No open issues 🎉

What changed in this PR

Adds support for TCP and QUIC transports to advertise externally reachable addresses and ports while continuing to bind locally, enabling proxy, NAT, and overlay deployments.

Changes:

• Adds advertise_addrs builder APIs for TCP and QUIC.
• Filters QUIC peer endpoints by dial-socket address-family reachability and exposes bound_addr().
• Adds proxy/relay integration tests and documentation for advertised-address behavior.

File	Reviewed changes
README.md	Links to advertised-address documentation.
lib/​velo/​tests/​advertised_address.rs	Tests TCP proxy traversal, QUIC relay traversal, advertised ports, and lane behavior.
lib/​velo/​src/​transports/​utils/​interfaces.rs	Converts advertised socket addresses into transport endpoints; scoped IPv6 address handling requires changes.
lib/​velo/​src/​transports/​tcp/​transport/​builder.rs	Adds TCP advertised-address configuration.
lib/​velo/​src/​transports/​quic/​transport/​builder.rs	Adds QUIC advertised-address configuration and dial-family detection; extra server sockets remain live in advertised-address mode.
lib/​velo/​src/​transports/​quic/​transport.rs	Exposes the bound address and filters unreachable QUIC endpoints during registration.
lib/​velo/​src/​transports/​quic/​tests.rs	Tests QUIC address-family selection and dual-stack behavior.
lib/​velo/​src/​transports/​quic/​endpoint.rs	Documents advertised endpoint behavior; descriptions need updating for proxy/NAT addresses.
lib/​velo/​Cargo.toml	Registers the advertised-address integration test target.
docs/​src/​concepts/​transports.md	Documents advertised addresses, QUIC lane behavior, and stream limitations.

_{Review effort: Lite}