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.

  • Targetsjs, wasmJs
  • TransportWebSocket client, on npm ws
  • CryptographyWebCrypto
  • UDP and TCPDeferred

Prerequisites

  • A Kotlin Multiplatform project with a js or wasmJs target and the nodejs() 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

Usable from Kotlin only

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

  1. 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 with fs.promises and 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-ktor has no variant for js
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 coap at /.well-known/coap, as RFC 8323 requires.

Next steps