Get started · Node.js
Node.js
The same js and wasmJs artifacts as in browsers run on Node.js, with the WebSocket client and Node.js’s WebCrypto. Every common test runs there in CI. UDP and TCP adapters for Node.js are deferred.
- Targets
js,wasmJs - TransportWebSocket client, on npm
ws - CryptographyWebCrypto
- UDP and TCPDeferred
Prerequisites
- A Kotlin Multiplatform project with a
jsorwasmJstarget and thenodejs()environment, on Kotlin 2.3 or newer; the samples use 2.4.21, the version kcoap is built with. - A JDK 17 or newer, to run Gradle.
- The build sets no minimum Node.js version. kcoap’s tests run on the Node.js the Kotlin Gradle plugin downloads.
Install status
kcoap 0.1.0 is on Maven Central, its js and wasmJs artifacts included. There is no npm package and there are no TypeScript declarations: your Node.js code is Kotlin/JS or Kotlin/Wasm. CI runs every common test on Node.js, as JavaScript and as Wasm, and the WebSocket client against an npm ws server.
Set up
-
Create the build file
The bill of materials,
kcoap-bom, sets one version for every kcoap module, so the modules name none.Kotlin DSL
build.gradle.kts
plugins { kotlin("multiplatform") version "2.4.21" } repositories { mavenCentral() } kotlin { js { nodejs() binaries.executable() } sourceSets { commonMain.dependencies { val bom = "dev.kcoap:kcoap-bom:0.1.0" implementation(project.dependencies.platform(bom)) implementation("dev.kcoap:kcoap-coap") implementation("dev.kcoap:kcoap-transport-ktor-websocket") // WebCrypto underneath implementation("dev.kcoap:kcoap-crypto-default") // EDHOC, and OSCORE with it implementation("dev.kcoap:kcoap-edhoc-oscore") } } }Version catalog
gradle/libs.versions.toml
[versions] kotlin = "2.4.21" kcoap = "0.1.0" [libraries] kcoap-bom = { module = "dev.kcoap:kcoap-bom", version.ref = "kcoap" } kcoap-coap = { module = "dev.kcoap:kcoap-coap" } kcoap-transport-ktor-websocket = { module = "dev.kcoap:kcoap-transport-ktor-websocket" } kcoap-crypto-default = { module = "dev.kcoap:kcoap-crypto-default" } kcoap-edhoc-oscore = { module = "dev.kcoap:kcoap-edhoc-oscore" } [bundles] kcoap-web = [ "kcoap-coap", "kcoap-transport-ktor-websocket", "kcoap-crypto-default", "kcoap-edhoc-oscore", ] [plugins] kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }build.gradle.kts
plugins { alias(libs.plugins.kotlin.multiplatform) } repositories { mavenCentral() } kotlin { js { nodejs() binaries.executable() } sourceSets { commonMain.dependencies { implementation(project.dependencies.platform(libs.kcoap.bom)) implementation(libs.bundles.kcoap.web) } } }A standard Kotlin Multiplatform build file; kcoap’s coordinates are checked. A
wasmJs { nodejs() }target works the same way in kcoap’s own tests.
First client and server
Node.js runs the client. The server is a kcoap server with a WebSocket listener on the JVM or Linux, as in the browser guide, or any CoAP server that speaks WebSockets, such as libcoap’s.
src/commonMain/kotlin/Main.kt
import dev.kcoap.coap.client.CoapClient
import dev.kcoap.transport.ktor.websocket.KtorWebSocketConnector
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.SupervisorJob
import kotlinx.coroutines.launch
fun main() {
val scope = CoroutineScope(Dispatchers.Default + SupervisorJob())
scope.launch {
val client = CoapClient(listOf(KtorWebSocketConnector()), scope)
// Hello over WebSocket
println(client.get("coap+ws://127.0.0.1:8080/hello").payloadAsText())
client.close() // closes the connection, so the process can exit
}
}The kcoap names are checked against the sources, and the calls are the guide’s. The entry point, a scope launched from a plain main, is not exercised by kcoap’s repository.
The Kotlin Gradle plugin adds tasks that run a Node.js executable; ./gradlew tasks lists the ones your Kotlin version has. To observe a resource, collect the cold Flow that client.observe(uri) returns: it registers when collected and deregisters when the collector stops.
Keys and state
- EDHOC derives new keys for each session and needs no durable store. Cipher suite 2 (P-256) runs on every platform; Node.js’s WebCrypto has the same gaps as browsers.
- Pre-shared OSCORE keys need a durable
SequenceNumberStore. The Node.js recipe writes withfs.promisesand syncs the file handle before the rename. It is not compiled or tested yet.
Platform notes
Transports
KtorWebSocketConnector() uses ktor’s Js engine, which on Node.js runs on the npm ws package that ktor brings. Node.js has UDP and TCP sockets, but kcoap has no adapter for them yet: one js artifact serves browsers too, where sockets cannot ship. The Node.js socket adapters (dgram, net and tls) are deferred. An application can write its own DatagramTransport: four members, maxDatagramSize, send, receive and close.
No server on Node.js
The WebSocket server module builds for the JVM and native targets only. A CoapServer runs on Node.js over a DatagramTransport the application supplies, as the in-memory tests do.
Not done yet on Node.js
- UDP and TCP adapters for Node.js (deferred).
- An npm package with TypeScript declarations, for use from JavaScript.
- Post-quantum EDHOC: ML-KEM and ML-DSA come only from
kcoap-crypto-bc, which is for the JVM and Android.
Troubleshooting
- The process does not exit
- An open client keeps its connection, and so the event loop, alive. Call
client.close()when you are done. kcoap-transport-ktorhas no variant forjs- kcoap has no UDP or TCP adapter for Node.js yet. Use the WebSocket client.
- The WebSocket connection fails
- The server must accept the subprotocol
coapat/.well-known/coap, as RFC 8323 requires.
Next steps
- The client and server guide: the same client API on every platform.
- The transport interfaces, for a
DatagramTransportof your own. - Features: what kcoap implements and how it is checked.