feat(transport): add TLS trust hook to WebSocketTransportFactory (#108)

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: jamesarich

AGENTS.md

@@ -43,17 +43,20 @@ check; see `core/build.gradle.kts` `verifyModuleBoundary`). Everything in `:core
                                         integration tests (testImplementation project(":transport-tcp"))
 :transport-tcp             commonMain (TcpTransport) + jvm/android/native PlatformTls expect/actual.
                            Targets: jvm, android, apple (ios/macos), linux, mingw — NO wasmJs.
-:transport-ws              commonMain (WebSocketTransport) + per-platform Ktor engine deps.
-                           Targets: all, incl. wasmJs.
+:transport-ws              commonMain (WebSocketTransport) + cioMain (CIO engine + TLS trust hook)
+                           + per-platform Ktor engine deps. Targets: all, incl. wasmJs.
 :bom (mqtt-client-bom)     java-platform BOM pinning every artifact to one version.
 build-logic/convention     mqtt.kmp.library + mqtt.publishing convention plugins (shared KMP target
                            set + per-module publishing coordinates derived from the module name).
 ```
 
 Each library module applies `applyDefaultHierarchyTemplate()` (via `mqtt.kmp.library`), so
 `nativeMain`/`appleMain`/`linuxMain`/`mingwMain` are auto-created. macosArm64 only (macosX64
-deprecated in Kotlin 2.3.20). There is **no** custom `nonWebMain` source set any more: `:transport-tcp`
-simply omits the wasmJs target, so its `commonMain` is effectively the old "non-web" set.
+deprecated in Kotlin 2.3.20). The one custom intermediate source set is `:transport-ws`'s `cioMain`
+(jvm + android + apple + linux), which holds the single CIO `HttpClient` builder and the TLS trust
+plumbing (`applyWsTls` and the `configurePlatformTrust` expect/actuals). The old `nonWebMain` set is
+gone: `:transport-tcp` simply omits the wasmJs target, so its `commonMain` is effectively the old
+"non-web" set.
 
 ### Packet codec pipeline
 

CHANGELOG.md

@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `WebSocketTransportFactory` now accepts an optional TLS customisation lambda, the WebSocket
+  counterpart to the `TcpTransportFactory` hook added in 0.6.0. Both take the same
+  `TLSConfigBuilder` receiver, so a single trust manager can serve `ssl://` and `wss://` brokers
+  behind a private or self-signed CA — scoped to the MQTT connection, with no app-wide
+  `network_security_config.xml` anchor. The lambda runs on JVM, Android, Apple, and Linux; ignored
+  on Windows (WinHttp exposes no TLS-configuration surface) and in the browser. The private-CA
+  trust manager itself is available only on JVM and Android, where `TLSConfigBuilder` exposes
+  `trustManager` — on Apple and Linux the lambda still runs but has no equivalent property to set.
+  The existing no-arg constructor is unchanged (#107).
+
+### Changed
+
+- `:transport-ws` now selects its Ktor engine explicitly per platform (CIO on JVM/Android/Apple/
+  Linux, WinHttp on Windows, Js on wasmJs) instead of relying on auto-detection. These are the
+  engines the library itself ships for each target; auto-detection resolves via `ServiceLoader`
+  over the *consuming app's* classpath, not the library's, so an app that also pulls in another
+  Ktor engine (e.g. `ktor-client-okhttp`, common on Android) may previously have had its WebSocket
+  MQTT connection served by that engine instead of CIO, with different proxy, DNS, and socket
+  defaults. Such an app will now always get CIO for this transport.
+
 ## [0.6.1] - 2026-07-26
 
 **The published library artifacts are unchanged from 0.6.0.** `mqtt-client-core`,

README.md

@@ -334,9 +334,11 @@ Log levels from most to least verbose: `TRACE` → `DEBUG` → `INFO` → `WARN`
 
 ### Custom TLS trust
 
-By default the TCP transport validates the broker certificate against the platform CA store. To
-reach a broker behind a private or self-signed CA, pass a TLS customisation lambda to
-`TcpTransportFactory`. It runs against ktor's `TLSConfigBuilder`:
+By default both transports validate the broker certificate against the platform CA store. To
+reach a broker behind a private or self-signed CA, pass a TLS customisation lambda to the
+transport factory you use — `TcpTransportFactory`, `WebSocketTransportFactory`, or both, since a
+factory without the lambda keeps validating against the platform store alone. It runs against
+ktor's `TLSConfigBuilder`:
 
 ```kotlin
 import org.meshtastic.mqtt.transport.tcp.TcpTransportFactory
@@ -377,18 +379,21 @@ This scopes the extra trust to the MQTT connection alone. It replaces the app-wi
 adding `<certificates src="user"/>` to `network_security_config.xml`, which would affect every
 HTTPS connection the app makes.
 
-The hook composes with transport selection as usual:
+The hook composes with transport selection as usual, and both transports take the same lambda type,
+so one trust manager can serve both:
 
 ```kotlin
 transportFactory = TcpTransportFactory { trustManager = myPrivateCaTrustManager } +
-    WebSocketTransportFactory()
+    WebSocketTransportFactory { trustManager = myPrivateCaTrustManager }
 ```
 
-`TLSConfigBuilder` comes from `io.ktor:ktor-network-tls`, exposed transitively by
-`mqtt-client-transport-tcp` — no extra dependency needed. The WebSocket transport has no equivalent
-hook yet. `trustManager` specifically is available on the JVM and Android actuals of
-`TLSConfigBuilder`; on Apple, Linux, and Windows targets the hook still runs, but `TLSConfigBuilder`
-exposes a different set of properties there.
+`TLSConfigBuilder` comes from `io.ktor:ktor-network-tls`, exposed transitively by both
+`mqtt-client-transport-tcp` and `mqtt-client-transport-ws` — no extra dependency needed.
+`trustManager` specifically is available on the JVM and Android actuals of `TLSConfigBuilder`; on
+Apple and Linux the hook still runs, but `TLSConfigBuilder` exposes a different set of properties
+there. The WebSocket hook is additionally ignored on Windows (the WinHttp engine has no
+TLS-configuration surface) and in the browser (which cannot influence trust) — see
+`transport-ws/Module.md` for the per-target table.
 
 ## Android / KMP Integration