peer: manual port-forward override for UPnP-less networks

[myleshorton]

Summary

Two related changes to the manual-port-forward path that ship together:

1. Consolidates the implementation into the portforward package. The manual forwarder landed in peer/peer.go via peer: call /peer/verify after starting sing-box; fix doubled /v1 #466 to keep that PR's review surface small, but architecturally it belongs alongside the UPnP-based Forwarder — same interface, same package. This PR's first commit (22d1533) is a net-zero relocation: peer.manualPortForwarder → portforward.ManualForwarder, peer.manualPort → portforward.ParseManualPort, tests follow.

2. Adds the PeerManualPortKey setting so the Advanced UI in the Share My Connection screen can configure the port without an env var. The env-var path stays for developer / power-user use.

After both commits, the resolution order in peer.Client.Start's NewForwarder:

1. settings.PeerManualPortKey if non-zero (UI),
2. else RADIANCE_PEER_EXTERNAL_PORT if set + parseable (developer override),
3. else fall back to UPnP discovery (existing behavior).

A non-positive or malformed env-var value is logged and the resolution falls through to UPnP discovery rather than registering a non-listening port with lantern-cloud.

Why two configuration paths

• Setting (PeerManualPortKey) — for users on networks where UPnP is unavailable (ISP gateways with UPnP off, double-NAT, residential routers with the feature disabled). The Advanced section in the Share My Connection Flutter screen sets it; persists across restarts. Cleared by setting the value to 0.
• Env var (RADIANCE_PEER_EXTERNAL_PORT) — developer override for testing on macOS / CLI without a UI build. Same parser, same forwarder.

What's in this PR

Consolidation (commit 22d1533):

• portforward/manual.go (new) — ManualForwarder, NewManualForwarder(port uint16), ParseManualPort(s string) (uint16, error).
• portforward/manual_test.go (new) — TestParseManualPort (9 input cases including boundaries + invalid), TestManualForwarder (full portForwarder contract).
• peer/peer.go — drops manualPortForwarder + manualPort(); NewForwarder now calls portforward.NewManualForwarder / portforward.ParseManualPort. Drops the strconv import.
• peer/peer_test.go — drops the now-moved tests.
• ManualForwarder.MapPort reports "manual" as the method tag (was "manual-env" when it only served the env path; the suffix is wrong now that both paths feed in).

Setting integration (commit 0c84c5a):

• common/settings/settings.go — adds PeerManualPortKey (int; 0 = use UPnP).
• peer/peer.go — NewForwarder resolution order now checks the setting first, then the env var, then falls through.

ManualForwarder contract

• MapPort returns a Mapping with External == Internal == configured port and Method = "manual". No network roundtrip — the router rule is already in place.
• UnmapPort is a no-op (user owns the router rule and removes it manually).
• StartRenewal is a no-op (manually-configured rules don't carry a UPnP lease).
• ExternalIP returns the empty string deliberately. With a manual port forward we have no UPnP gateway to ask for the WAN address, and probing a public-IP service from the client adds a network roundtrip for information lantern-cloud already has — the server observes the peer's source address on the register call and uses that as the canonical external IP when this field is empty.

How this was sliced

Stacked on radiance #499 (fisk/peer-connection-events-A), itself stacked on #466 → #460 → #458. After cascade rebases through the stack, conflicts on peer/peer.go resolve cleanly — the consolidation commit moves code that other commits in the chain don't touch.

Test plan

• go test -race -count=1 ./peer/... ./portforward/... ./backend/... clean on the branch.
• Manual smoke (after build):
  • RADIANCE_PEER_EXTERNAL_PORT=5698 ./lantern-cli … → peer.Client binds 5698, skips UPnP probe, log line peer client using manual port forward port=5698 source=RADIANCE_PEER_EXTERNAL_PORT.
  • From Flutter Advanced → manual port = 5698 → toggle SmC on → same outcome with source=setting.
  • Empty setting + missing env var → falls back to UPnP discovery (regression check).
  • Malformed env var (RADIANCE_PEER_EXTERNAL_PORT=abc) → warning logged, falls through to UPnP rather than failing Start.

Dependencies

• radiance peer: stream samizdat ConnectionEvents through radiance to consumers #499 (fisk/peer-connection-events-A) — this PR's base.
• Foundation chain: Add peer module + portforward for Share My Connection (PR 1/4) #458 → Wire peer.Client into LocalBackend (Share My Connection PR 2/4) #460 → peer: call /peer/verify after starting sing-box; fix doubled /v1 #466.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a manual external-port override for peer sharing so users on UPnP-less networks can still run “Share My Connection” by configuring a router port-forward themselves, with precedence: persisted setting → env var → UPnP discovery.

Changes:

• Introduces portforward.ManualForwarder as a no-op forwarder that synthesizes a 1:1 mapping and returns empty ExternalIP for server-side observed-IP fallback.
• Adds settings.PeerManualPortKey to persist a user-specified external TCP port.
• Updates peer.Client forwarder selection to prefer the manual port (setting/env) before UPnP.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
portforward/manual.go	Adds ManualForwarder + ParseManualPort to support manual port-forward setups.
portforward/manual_test.go	Adds unit tests for ManualForwarder behavior and port parsing.
peer/peer.go	Adds forwarder selection logic to use manual port configuration before UPnP.
common/settings/settings.go	Adds PeerManualPortKey setting key and documentation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.