kcoap-common

The base every kcoap module builds on: logging, the root of kcoap's exceptions, byte helpers for secrets, and the two opt-in markers. It has no dependencies, not even kotlinx-coroutines, and is common Kotlin only, so it builds for every target. kcoap-transport, kcoap-cbor and kcoap-crypto export it (api), so an application reaches it through any kcoap module and rarely names it.

PackageTypeWhat it is
dev.kcoap.logKcoapLogging, LogConfigThe global logging configuration: a threshold, levels per dot-separated tag, the sink, whether payloads are dumped (off by default), the clock for timestamps. LogConfig.build { ... } or KcoapLogging.configure { ... }
LoggerFactory, LoggerWhat every component that logs takes (loggerFactory = LoggerFactory.Global, or a factory of its own for one component); messages are lambdas, evaluated only at an enabled level
LogSink, ConsoleSink, RingBufferSink, CompositeSink, LogFormatter, LogRecordWhere records go: a one-method interface, the console, the latest records in memory for diagnostics, several sinks at once (sink + other, sink.atLeast(level))
LogTagsThe catalogue of tags kcoap logs under (coap.message, oscore, edhoc, transport, ...)
dev.kcoap.commonKcoapExceptionThe root of every protocol's exception: CoapException, OscoreException, EdhocException and its subtypes, CborException, CertificateFormatException. One catch handles the runtime failures of any kcoap call, and the public suspend entry points list it in @Throws for Swift
constantTimeEquals, ByteArray.wipe()Comparison in time that depends only on the lengths, for MACs, tags and other secret-derived values; overwriting a secret once it is no longer needed
Hex, toHex(), hexToBytes()Lower-case hex, for test vectors and logs
@ExperimentalKcoapApiMarks a published SPI that nothing implements yet (DatagramSecurity); using it needs @OptIn (../docs/versioning.md#api-tiers)
@InternalKcoapApiMarks plumbing between kcoap's modules (ByteArrayBuilder, minimalUnsignedBytes, readUnsigned, OptionCodec, ...); not API, left out of the ABI dumps, and applications must not use it

Using it

--------

Logging is configured once, globally, or per component through the loggerFactory it takes; ../docs/logging.md has the levels, the tags, the sinks, and how a sink forwards records to SLF4J, Logcat or OSLog:

KcoapLogging.configure {
level = LogLevel.INFO // lifecycle too; the default is WARN
level(LogTags.OSCORE, LogLevel.DEBUG)
sink = ConsoleSink()
}

Every protocol's exception extends KcoapException, so code that runs EDHOC and then sends requests handles kcoap's runtime failures in one place, and a mistake of the caller still surfaces as IllegalArgumentException or IllegalStateException:

try {
val (_, protection) = EdhocClientHandshake.over(client, server, initiatorConfig, crypto).runCombined()
security.install(client, server, protection)
client.get("coap://192.0.2.1/lights")
} catch (e: KcoapException) {
when (e) {
is CoapException -> log.warn { "CoAP failed: ${e.reason}" }
is EdhocException -> log.warn { "EDHOC failed: ${e.error}" }
else -> log.warn(e) { "kcoap failed" }
}
}

The signals of the SPIs between kcoap's layers (MessageSecurityException, CoapFormatException, SessionEndedException, AeadAuthenticationException, UnsupportedAlgorithmException, CertificateValidationException) do not extend it: each layer translates them at its boundary (../docs/architecture.md#the-coap-endpoint-as-built, "Errors").

Verified by

-----------

TestWhat
LoggerTestthe WARN default on the console sink, levels inherited along tags and cleared again, OFF, messages not built when disabled, fields and child tags, payloads as hex only when enabled, a sink that throws, a global change reaching existing loggers
SinkTestthe ring buffer (newest records in order, a capacity it needs), composite and threshold sinks, the formatter with an error, the console sink
BytesTesthex both ways and bad hex, constantTimeEquals, wipe, the unsigned big-endian helpers
KcoapExceptionTesta subtype keeps its message and cause, the cause is optional, one catch handles every subtype

They run on every target: the JVM, Linux native, Apple native (on macOS), and Node.js as JavaScript and as Wasm. That every protocol's exception is a KcoapException, and no SPI signal is, is checked where all of them are visible, by ErrorModelTest in kcoap-edhoc-oscore.

Packages

Link copied to clipboard
common
Link copied to clipboard
common