Allocate authenticated SOCKS bridge ports automatically

[bbottema]

Problem

Each Mailer configured with an authenticated SOCKS proxy owns a temporary loopback bridge because Jakarta Mail only speaks to an unauthenticated SOCKS endpoint. The bridge uses the configured port, currently 1081 by default.

Concurrent operations through one Mailer share and coordinate that Mailer's bridge. Separate Mailers do not: if two authenticated-proxy Mailers use the same bridge port while their operations overlap, the second bridge cannot bind.

The documentation now requires a distinct withProxyBridgePort(...) value for every concurrently active authenticated-proxy Mailer. That avoids the collision, but makes applications allocate local ports manually.

Proposed direction

Allow Simple Java Mail to ask the operating system for an available loopback port and connect Jakarta Mail to the actual port selected for that bridge.

Simply configuring port 0 is not sufficient today. The Jakarta Mail Session receives mail.smtp.socks.port or mail.smtps.socks.port before the bridge starts, while the operating system only chooses the real port when the bridge socket binds.

A robust implementation therefore needs to:

• bind the bridge before the SMTP transport connects;
• obtain its actual loopback port;
• write that port into the effective Session immediately before connection;
• repeat that update if a stopped bridge later restarts on another ephemeral port;
• coordinate concurrent sends, open-connection work, batching, pooling, and custom Sessions;
• preserve explicit bridge ports for callers who require one.

Design questions

• Should automatic allocation become the default, or be enabled explicitly?
• Should withProxyBridgePort(0) request an ephemeral port, or should the API use a separate method?
• Which runtime diagnostics should expose the selected local port?
• How should Session updates be synchronized with pooled transport creation and reconnects?

History

• Add support for Proxy (HTTP, SOCKS, authenticated) #38 introduced the authenticated-proxy bridge architecture.
• Authenticated SOCKS bridge listens on wildcard interfaces #676 restricted the temporary bridge to loopback and aligned Jakarta Mail with that address.

This issue concerns collision-free port allocation only; the loopback security fix is already complete.

Acceptance criteria

• Two separate authenticated-proxy Mailers can connect concurrently without manually assigning bridge ports.
• The bridge remains loopback-only.
• Jakarta Mail always receives the actual bound port before connecting.
• Bridge stop/restart cycles update the Session when the ephemeral port changes.
• Explicitly configured ports retain their current behavior.
• Direct, open-connection, batch, pooled, and custom-Session paths are covered.