This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git
The following commit(s) were added to refs/heads/main by this push:
new 5a4d3901b6 Document migration from removed SSLConfig convenience APIs
(#3660)
5a4d3901b6 is described below
commit 5a4d3901b646e48453dc42b666c64b33f7d416ea
Author: He-Pin(kerr) <[email protected]>
AuthorDate: Fri Oct 23 21:22:10 2026 +0800
Document migration from removed SSLConfig convenience APIs (#3660)
* Document migration from removed SSLConfig convenience APIs
Motivation:
The migration guide mentions removing the ssl-config dependency but omits
the replacement for PekkoSSLConfig and the old TLS convenience overloads.
Modification:
Describe configured javax.net.ssl.SSLEngine factories and link the current
Scala and Java TLS/TCP entry points next to the existing removal notice.
Result:
Users can migrate to the current APIs without restoring removed
dependencies or changing the existing TLS engine implementation.
Tests:
- Tests: Not run - docs only.
- Passed: `docs/paradox`.
- Passed: `+headerCheckAll`.
- Full `validatePullRequest` is left to remote CI.
References:
- Refs [akka/akka-core#32071](https://github.com/akka/akka-core/pull/32071).
- Upstream commit:
[997068c16638c22f78fc127816eb3c6b7df835e2](https://github.com/akka/akka-core/commit/997068c16638c22f78fc127816eb3c6b7df835e2).
- Source snapshot: Akka `v2.9.0`
(`bf20e967571574994ccb3cae411401f5a9021ab9`). Its
[license](https://github.com/akka/akka-core/blob/v2.9.0/LICENSE) names
2026-10-23 as the Change Date and Apache License 2.0 as the Change License.
`LICENSE` and `NOTICE` record the source, and original copyright notices are
retained. Headers were generated/checked with the project sbt tasks.
* Keep licensing metadata outside the migration change
Motivation:
Keep PR #3660 scoped to its code or documentation change.
Modification:
Restore the root LICENSE and NOTICE files to main.
Result:
The migration diff retains its source headers without repository-level
licensing edits.
Tests:
- git diff --check passed.
- Verified every other file is unchanged; prior focused validation still
applies.
References:
Refs #3660.
* Preserve TLS settings in migration guidance #3660
Motivation:
Replacing the removed convenience APIs requires client identity checks and
session settings to be configured explicitly.
Modification:
Move the migration guidance to breaking API changes, explain hostname
verification and DNS SNI alongside engine settings, link the TLS examples, and
scope bindAndHandle guidance to Scala.
Result:
Callers have a documented path to the engine-factory APIs that preserves
their TLS configuration.
Tests:
Validation used a local integration checkout with current main and the
other review fixes.
- Runtime tests: Not run - docs only.
- docs/paradox, headerCreateAll, +headerCheckAll, and git diff --check:
passed.
- Verified the generated Scala/Java API links, Scala-only bind-and-handle
guidance, and TLS example link.
- Full validation is delegated to remote CI.
References:
Refs #3660, Refs #2127.
---
.../main/paradox/migration/migration-guide-1.x-2.x.md | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
b/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
index fa6332d521..8947550241 100644
--- a/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
+++ b/docs/src/main/paradox/migration/migration-guide-1.x-2.x.md
@@ -82,6 +82,23 @@ release. The fork is a drop-in replacement with important
bug fixes. If your bui
* The `ssl-config` library is no longer a dependency of Pekko and the
`ssl-config` configuration sections have
been removed (see Removed configuration below).
([PR2127](https://github.com/apache/pekko/pull/2127))
+* The deprecated `PekkoSSLConfig` convenience API and the stream methods
accepting it were removed.
+Initialize an `SSLContext` with the required key and trust managers, and
supply a factory that creates a new
+`javax.net.ssl.SSLEngine` for each connection. Set its client or server mode
and apply the cipher suites,
+protocols and client-authentication settings previously passed in
`NegotiateNewSession` directly to the engine
+or its `SSLParameters`.
+Client factories must preserve peer identity checks: use
`sslContext.createSSLEngine(host, port)`, call
+`setUseClientMode(true)`, and enable hostname verification with
`setEndpointIdentificationAlgorithm("HTTPS")`
+on the engine's `SSLParameters`. For DNS names, also configure SNI with
`SSLParameters.setServerNames`
+containing an `SNIHostName` for that hostname. Apply those parameters with
`SSLEngine.setSSLParameters` before returning the engine.
+The factory is accepted by
+@scala[@scaladoc[TLS.apply](org.apache.pekko.stream.scaladsl.TLS$)]@java[@javadoc[TLS.create](org.apache.pekko.stream.javadsl.TLS)]
+and the current @apidoc[Tcp](stream.*.Tcp) TLS methods.
+Replace `outgoingTlsConnection` with `outgoingConnectionWithTls` and `bindTls`
with `bindWithTls`.
+@scala[Also replace `bindAndHandleTls` with `bindAndHandleWithTls`.]
+See the Scala and Java @ref:[TLS examples](../stream/stream-io.md#tls) for
general engine setup,
+adding the client hostname-verification and SNI settings described above.
([PR2127](https://github.com/apache/pekko/pull/2127))
+
## Configuration Changes in Pekko 2.x
The `reference.conf` defaults have changed in a number of places. If you
override any of the settings
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
