Package-level declarations

Types

Link copied to clipboard
fun interface AccessPolicy

Who may use a resource (ADR 0008). A CoapServer asks the policy that governs the resource a request is for right after it found the resource, before it does any work for the request: a refused request gets 4.01 Unauthorized, or 4.03 Forbidden when message security authenticated it (RFC 7252 §5.9.2.2, §5.9.2.4), and reaches no handler, buffers no Block1 or Q-Block1 body, registers, replaces or cancels no observation and gets no Q-Block2 burst. The refusal is protected when the request was.

Link copied to clipboard
class AccessRequest(val method: CoapCode, val path: List<String>, val resource: CoapResource?, val peer: Endpoint, val securityIdentity: SecurityIdentity?, val peerIdentity: PeerIdentity)

What an AccessPolicy decides on: a request, before the server did any work for it, or for /.well-known/core a GET of a resource it would list.

Link copied to clipboard

Which responses a CoapServer holds back from a client whose address it has not verified, answering with a short 4.01 Unauthorized carrying an Echo option instead (RFC 9175 §2.4 item 3). RFC 9175 §2.6 updates RFC 7252 §11.3: a server SHOULD mitigate amplification this way towards unauthenticated clients, since over UDP the source address of a request proves nothing and a large answer to a spoofed one lands on the victim the address names.

Link copied to clipboard
abstract class CoapResource(val name: String)

A resource of a CoapServer, identified by its path from the root. Subclass it and override the handlers for the methods it supports; the others answer 4.05 Method Not Allowed (RFC 7252 §5.9.2.6). For resources defined inline, see the DSL in ResourceBuilder.

Link copied to clipboard

Thrown by a resource handler to answer its request with response, a 4.xx or 5.xx error (RFC 7252 §5.9.2, §5.9.3), as if the handler had returned it, from however deep in the application's code: a validation, a repository that finds nothing, an authorization check. The client gets response as it is, diagnostic payload and options included, and the server logs it at DEBUG only, since it is an ordinary outcome and not a failure.

Link copied to clipboard

A CoAP server: routes requests on a CoapEndpoint to a tree of CoapResources.

Link copied to clipboard
class CoapServerConfig(val security: ServerMessageSecurity? = null, val maxBlockSize: Int = 1024, val maxRequestBodySize: Int = 1 shl 20, val maxConcurrentTransfers: Int = 64, val confirmableNotificationInterval: Duration = 24.hours, val nonConfirmableNotificationInterval: Duration = 3.seconds, val securityReserve: Int = 64, val wellKnownCore: Boolean = true, val maxObservers: Int = DEFAULT_MAX_OBSERVERS, val maxObserversPerResource: Int = DEFAULT_MAX_OBSERVERS_PER_RESOURCE, val maxObserversPerPeer: Int = DEFAULT_MAX_OBSERVERS_PER_PEER, val amplification: AmplificationPolicy = AmplificationPolicy.Q_BLOCK_BURSTS, val amplificationFactor: Int = DEFAULT_AMPLIFICATION_FACTOR, val maxVerifiedAddresses: Int = DEFAULT_MAX_VERIFIED_ADDRESSES, val verifiedAddressLifetime: Duration = DEFAULT_VERIFIED_ADDRESS_LIFETIME, val qBlock: QBlockServerConfig = QBlockServerConfig(), val defaultAccess: AccessPolicy = if (security == null) AccessPolicy.Public else AccessPolicy.MessageSecurityRequired)

How a CoapServer processes requests.

Link copied to clipboard
annotation class CoapServerDsl

Marks the resource DSL, so nested blocks do not see the outer builder's members.

Link copied to clipboard
abstract class ObservableResource(name: String) : CoapResource

A resource clients can observe (RFC 7641). A GET or FETCH with Observe 0 that the handler answers with 2.xx adds the client to the observers; call notifyObservers whenever the state changes, and every observer gets a notification produced by calling the handler again with its registration request.

Link copied to clipboard
class QBlockServerConfig(val isEnabled: Boolean = false, val withMessageSecurity: Boolean = false, val onReliableTransports: Boolean = true, val maxPartialBodies: Int = DEFAULT_MAX_BODIES, val maxCachedBodies: Int = DEFAULT_MAX_BODIES, val maxBodiesPerPeer: Int = DEFAULT_MAX_BODIES_PER_PEER)

Whether and how a CoapServer serves Q-Block (RFC 9177): Q-Block1 uploads and Q-Block2 bodies, sent and repaired in bursts of MAX_PAYLOADS Non-confirmable blocks (dev.kcoap.coap.stack.TransmissionParameters).

Link copied to clipboard

A request as a resource handler sees it: verified by message security, reassembled from Block1 transfers, and with who sent it. This is the server's application model, the counterpart of the client's CoapRequest: method, path, query, options and payload, without the messaging-layer fields (type, Message ID, token), which differ by transport and mean nothing to a handler.

Link copied to clipboard

A request handler in the DSL: the RequestContext is the receiver.

Link copied to clipboard
class ResourceAttributes(resourceTypes: List<String> = emptyList(), interfaces: List<String> = emptyList(), contentFormats: List<Int> = emptyList(), val maximumSize: Long? = null, val title: String? = null, extra: List<Pair<String, String?>> = emptyList())

What /.well-known/core says about a resource (RFC 6690 §3, RFC 7252 §7.2.1). The obs hint (RFC 7641 §6) is added for observable resources automatically. Immutable: the lists given are copied.

Link copied to clipboard

Defines resources inline, as an alternative to subclassing CoapResource:

Link copied to clipboard

How much a CoapServer holds at the moment CoapServer.stats was called, for gauges in metrics and for diagnostics; set each against the bound of CoapServerConfig it names. What its endpoint holds is CoapEndpoint.stats(), and what happened is counted from its EndpointEvents.