golioth / xk6-coap

A k6 extension for CoAP.

xk6-coap

xk6-coap is a k6 extension for the Constrained Application Protocol (CoAP).

MATURITY NOTICE: xk6-coap is under active development and breaking API changes are to be expected. The project has been open sourced early to ensure that external consumers have an opportunity to influence and contribute to its future direction.

Getting Started

To get started, either build the k6 binary or use the golioth/xk6-coap image.

Using the OCI Image

The quickest way to get started is by using the golioth/xk6-coap image, which is built from this repository and published to DockerHub. Tests can be supplied when creating a container from the image via a bind mount. For example, the following command would run the simple example from this repository.

docker run -it --rm -e COAP_PSK_ID=<YOUR-PSK-ID> -e COAP_PSK=<YOUR-PSK> -v $(pwd)/examples/simple.js:/simple.js golioth/xk6-coap k6 run /simple.js --vus 10 --duration 5s

xk6-coap supports authentication via pre-shared keys (PSKs) and client certificates. The former is provided by specifying environment variables, while the latter is provided by specifying file paths. The simple.js example passes COAP_PSK_ID and COAP_PSK to the instantiated Client, which will cause it use use the respective values for PSK authentication. If a Client is instantiated with both PSK environment variables and certificate file paths, certificate authentication will take precedence.

client = new Client(
	"coap.golioth.io:5684",
	"COAP_PSK_ID",
	"COAP_PSK",
);

Only PSK is provided and it will be used for authentication.

client = new Client(
	"coap.golioth.io:5684",
	"",
	"",
	"path/to/client/crt.pem",
	"path/to/client/key.pem",
);

Only certificate is provided and it will be used for authentication.

client = new Client(
	"coap.golioth.io:5684",
	"COAP_PSK_ID",
	"COAP_PSK",
	"path/to/client/crt.pem",
	"path/to/client/key.pem",
);

Both are provided but certificate takes precedence.

Building a k6 Binary

Using k6 extentions requires including the extension(s) in a k6 build. The xk6 tool will handle executing the build, and the Makefile in this repository will ensure that xk6 is installed and produces a valid build.

make build

This will produce a k6 binary in the current working directory. To execute a test with 2 virtual users making connections and sending GET messages for 5 seconds, the following command could be run.

./k6 run ./examples/simple.js --vus 10 --duration 5s

Reference the k6 documentation for more information on how to configure and run tests.

Attribution

xk6-coap is essentially glue machinery that allows for plgd-dev/go-coap / pion/dtls functionality to be exposed to k6 tests. This project would not be possible without the work done by contributors (some of whom are on the Golioth team!) on both of those projects.

xk6-coap's Issues

Move from `goliothiot/xk6-coap` to `golioth/xk6-coap`

The golioth Dockerhub account is now our official organization. We should update to publish there.

Empty PSK_ID

I tried this simple example with current main branch:

import { fail } from 'k6';
import { setTimeout } from "k6/x/timers"
import { Client } from 'k6/x/coap';


export default function() {
	try {
		// Create new client and connect.
        	let client = new Client(
			"localhost:5684",
			"Client_identity",
			"secretPSK",
			// path/to/client/crt.pem,
			// path/to/client/key.pem,
		);

		// Verify connection.
		let res = client.get("/keep-alive", 10);
		console.log(String.fromCharCode(...res.body));
	} catch (e) {
		fail(e);
	}
}

And it resulted in an empty identity in my DTLS exchange:

Setup prettier for examples

We should setup prettier and lint our example scripts in CI to ensure new contributions are formatted correctly.

Publish images with `xk6-coap` `k6` builds

In order to avoid requiring users to build their own k6 distribution when just running CoAP load tests, we should publish an image with a k6 build including xk6-coap for public consumption.

Add support for handling `Observe` messages

Currently the Observe method is implemented, but there is no mechanism for handling messages. Consumers should be able to pass a callback that is invoked on new messages arriving.

Add support for certificate authentication

Currently only pre-shared keys (PSKs) are supported. Support should be added for certificate-based authentication as well.

Setup CI

We should be ensuring that all PRs are tested before merge. We can setup an initial GitHub workflow to do so.

Add `CONTRIBUTING.md`

We should ensure that appropriate documentation is provided for folks to be able to contribute to xk6-coap.

Cut `v0.1.0` release

In order to be included in the k6 extensions marketplace, we need to create an initial release of xk6-coap.

Setup golangci-lint

We should add golangci-lint configuration and run it in CI.

binary/Hexadecimal PSK support

The Client expects the PSK value to be a string, so I tried to set my hex string there, but debugging it, I saw the string is converted to bytes before being sent to the DTLS implementation.

I would expect the PSK value to be entered as Hex and not a string, as mandated by rfc4279: https://datatracker.ietf.org/doc/html/rfc4279#section-5.4
Also, how the current implementation would cope with non-ASCII/UTF8 generated binary PSKs?

Support CoAP without DTLS

Even if deploying CoAP without DTLs is not a good idea, skipping the DTLS layer can be valuable for perf testing to isolate the CPU/memory usage of DTLS vs the COAP server.
Also, CoAP + OSCORE without DTLS is used on some deployments.