kcoap-transport-ktor-websocket
The WebSocket client transport for coap+ws and coaps+ws (RFC 8323 §4) on the ktor client. It builds for every kcoap target (the UNIVERSAL tier), browsers and Node.js included, and is common code except for one line per platform that names the default client's engine. WebSockets are the one transport a browser allows, so this is how a browser reaches CoAP.
The default client (KtorWebSocketConnector()) runs on the engine this module brings for the platform. It names that engine instead of leaving the choice to ktor's lookup, which on native takes whichever linked engine registered first: an iOS app that also links ktor-client-cio for its own HTTP calls still gets URLSession here.
| Platform | Engine | Why | coaps+ws |
|---|---|---|---|
| JVM, Android | CIO | ktor's engine on plain sockets | no: CIO's TLS, ktor-network-tls, accepts a certificate without DNS names for any host name, and CIO checks an IP literal by its reverse DNS name |
| iOS, macOS | Darwin (ktor-client-darwin) | URLSession's WebSocket task: it brings up the cellular radio and honours VPN On Demand, which BSD sockets do not | yes, on URLSession's TLS |
| Linux | CIO | no: CIO has no TLS on Linux native | |
js, wasmJs | JS (in ktor-client-core) | the browser's or Node.js's own WebSocket | yes, on the runtime's wss |
An application that wants another engine passes its own HttpClient.
coaps+ws needs a client that authenticates the server (RFC 8323 §9.2): a chain its trust store accepts that names the URI's host (RFC 9525 §6). The connector lists coaps+ws among its schemes, the connector's word that it runs TLS for it, only where its default client does that (last column); elsewhere a CoapClient on it fails a coaps+ws URI with TRANSPORT_UNAVAILABLE before resolving it, and the connector refuses a wss endpoint itself. A connector on an HttpClient the application passes serves coaps+ws everywhere: passing one is the application's word that its engine authenticates servers. A CIO client on the JVM or Android has the name check above, so give it a trust manager for an authority that issues only DNS names for your servers, or use an engine whose TLS checks names, such as one on the JDK's own TLS (not tested in kcoap).
KtorWebSocketConnector: aConnectorfor the CoAP client. The opening handshake asks for the subprotocolcoapat/.well-known/coapof the URI's authority, and the connector fails unless the server selects it (§4.1, §8.3). Every engine reports the selected subprotocol as the response'sSec-WebSocket-Protocol; the JS engine takes it fromWebSocket.protocol, having asked through the WebSocket constructor'sprotocolsargument.wssforcoaps+wsruns on the engine's TLS, as above. Construct it with no arguments for a client of its own, or pass anHttpClientthat has the WebSockets plugin, preferably without a ping interval (§4.4).KtorWebSocketConnection: any ktorWebSocketSessionas aMessageConnection. One CoAP message per binary frame (§4.2), fragmented frames reassembled, and a text frame closes the WebSocket with 1003.
The adapter only moves frames; Len 0 framing is common code in kcoap-coap-message, and the CSM, signaling, block-wise and Observe are in kcoap-coap.
val client = CoapClient(listOf(KtorWebSocketConnector()), scope)
println(client.get("coap+ws://example.org/sensors/temperature?u=Cel").payloadAsText())The server side is kcoap-transport-ktor-websocket-server, a module of its own so that a browser client never depends on ktor-server.
Verified by
-----------KtorWebSocketConnectionTest: frames, fragmentation, text frames, on every target.KtorWebSocketTransportTest(JVM): real loopback sockets, the subprotocol required both ways, mounting in an application.NativeWebSocketLoopbackTest(native): the default client against the listener on loopback sockets, and refused by a server that selects no subprotocol. On Linux it is CIO. On macOS and the iOS simulator it is the Darwin engine, in CI's macOS job (scripts/test apple): pending the first apple-job run. Until then the Apple test binaries have only been compiled, and Darwin's subprotocol negotiation is unverified (see ../docs/testing.md#continuous-integration for the fallback to CIO if that job fails).DefaultEngineTest: the default client's engine on the JVM, Linux, and onjsandwasmJs(webTest, on Node.js), where an application'sHttpClient()also finds the Js engine; on Apple, in a test binary that links ktor-client-cio too, pending the first apple-job run.KtorWebSocketConnectorTest:KtorWebSocketConnector()builds its client and refuses non-WebSocket endpoints, on every target; it listscoaps+wsexactly where its engine authenticates servers, and a connector on the application's client lists it everywhere.DefaultConnectorCoapsWsTest(JVM) andLinuxSecureWebSocketTest(Linux): aCoapClienton the default connector failscoaps+wswithTRANSPORT_UNAVAILABLEbefore resolving it, and the connector refuses awssendpoint before opening a socket.LinuxSecureWebSocketTestalso pins that CIO has no TLS on Linux native, andCioWebSocketNameCheckTestin kcoap-transport-ktor pins CIO's name check on the JVM;DefaultEngineTestchecks that the default connector listscoaps+wsonjsandwasmJs, and on Apple (pending the first apple-job run).JsWebSocketSubprotocolTest(js, on Node.js): an npmwsserver whosehandleProtocolsrecords the offered subprotocols seescoaprequested alone, and the connector readscoapback from the negotiated protocol and exchanges a message; a server that selects none is refused.BrowserAgainstJvmListenerTest(JVM, with-Pkcoap.browser): the js tests above in a headless browser against aKtorWebSocketListeneron the JVM, which accepts only handshakes that ask forcoap. CI's browser job runs them in Chrome, pending its first run; so far they have passed in headless Firefox (scripts/test browser firefox). The page loads the compiled js tests with a small AMD loader and runs them with mocha, both served by the test; no bundler and no extra npm packages are involved.The libcoap interop tests over
coap+wsinkcoap-coap/src/jvmTest, and overcoaps+wson a CIO client that trusts the test authority (KcoapClientAgainstLibcoapTlsTest): a GET, the platform store's refusal, and a certificate for another host name refused.
Not covered: the wasmJs engine against a real server (only the in-memory tests and the engine checks run there), and coaps+ws on the Darwin and Js engines against a real TLS server.