Custom Session proxy configuration does not apply the promised SOCKS route

[bbottema]

Summary

MailerBuilder.usingSession(session).withProxy(...) does not configure the supplied Jakarta Mail Session for the proxy unless that session contains Simple Java Mail's private transport-strategy marker.

A normal caller-created Session has no such marker. As a result:

• anonymous proxy configuration leaves the session's SOCKS route unchanged;
• authenticated proxy configuration starts Simple Java Mail's local bridge, but leaves the session unable to reach that bridge unless the caller also sets the low-level SOCKS properties manually.

This contradicts the public builder contract and the website examples, both of which present proxy configuration as the deliberate exception to the otherwise-preconfigured custom-session path.

Lineage and bug provenance

1. #38 introduced anonymous and authenticated SOCKS support in 4.0.0. The original implementation in d61baa63 documented a caller-supplied session as preconfigured for connection details, but explicitly said that proxy settings would still be added. It wrote mail.smtp.socks.host and mail.smtp.socks.port into custom sessions.

2. #111 corrected SMTP/SMTPS-specific property names. Commit b1d789bb changed proxy setup to require a known TransportStrategy. When no strategy was available, it stopped writing SOCKS properties and only logged that the supplied session was expected to contain them. This behavior first shipped in 5.0.0.

3. #115 introduced the current builder API. Commit eaa76777 retained the contract that all SMTP details are preconfigured on a custom session while “only proxy can be configured optionally.” The website likewise continued to show usingSession(session).withProxy(...) as complete configuration.

The #111 protocol-prefix correction therefore created a long-standing regression in the custom-session proxy exception; it did not establish an immutable-session contract. Simple Java Mail still deliberately applies generic operational settings to a supplied session.

Expected behavior

For a normal caller-supplied session:

• host, port, authentication, TLS, transport and SSL settings remain caller-owned;
• withProxy(host, port) writes only the supported mail.smtp.socks.host and mail.smtp.socks.port route;
• authenticated withProxy(...) points those properties at Simple Java Mail's local bridge while retaining the provided upstream proxy credentials;
• no full TransportStrategy is inferred and no other protocol defaults are applied;
• existing unsupported SMTPS proxy behavior remains unsupported.

Acceptance criteria

• Anonymous proxy configuration works with an ordinary caller-created Session.
• Authenticated proxy configuration wires an ordinary caller-created Session to the local bridge.
• Unrelated caller-supplied session properties remain unchanged.
• Existing internally-created-session behavior remains unchanged.
• Regression tests cover both anonymous and authenticated custom-session cases.
• Public Javadoc clearly describes the narrow proxy override.

[bbottema]

Implemented in fb4f1945.

For a caller-supplied Session, withProxy(...) now updates only the supported mail.smtp.socks.host and mail.smtp.socks.port route. Anonymous proxying points directly at the upstream proxy; authenticated proxying points at Simple Java Mail’s local authentication bridge. The Session’s remaining SMTP, TLS, authentication, transport, and custom properties stay caller-owned.

[bbottema]

Available in Simple Java Mail 9.1.8. Custom-session proxy configuration now updates the supported mail.smtp.socks.* route while leaving the remaining Session settings caller-owned.