CoapServerConfig

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)(source)

How a CoapServer processes requests.

Constructors

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

Types

Link copied to clipboard
object Companion

Properties

Link copied to clipboard

which responses wait until the client's address is verified (RFC 9175 §2.4 item 3, §2.6): a client that neither OSCORE nor DTLS authenticated, on a datagram transport, gets a 4.01 Unauthorized with an Echo option instead, piggybacked or Non-confirmable, never as a separate Confirmable response, whose retransmissions would amplify again. Each such answer is reported as dev.kcoap.coap.stack.EndpointEvent.LimitReached with AMPLIFICATION_FACTOR. Under AmplificationPolicy.ALL_RESPONSES every separate response to an address not yet verified is Non-confirmable for the same reason. The response to a POST or PATCH, which must not take effect twice, is kept for the repeat of that request with the Echo value, which gets it without running the handler again; maxConcurrentTransfers bounds how many are kept, and one evicted for room is reported with HELD_BACK_RESPONSES (its repeat then runs the handler again).

Link copied to clipboard

the largest response, as a multiple of the size of its request, that goes to an address not yet verified (RFC 9175 §2.4 item 3 takes 3 from QUIC, RFC 9000 §8, as acceptable for unconstrained applications). Sizes are those of the CoAP messages, header, token and options included; the 4-byte Empty ACK that precedes a separate response is not counted.

Link copied to clipboard

the longest a client goes without a Confirmable notification (RFC 7641 §4.5: at least every 24 hours).

Link copied to clipboard

the AccessPolicy of every resource that has none and whose ancestors have none (ADR 0008). By default AccessPolicy.MessageSecurityRequired when security is set, so a server with message security fails closed, and AccessPolicy.Public otherwise. /.well-known/core and kcoap-edhoc-oscore's EdhocResource are AccessPolicy.Public of their own. A server that also takes DTLS-authenticated requests without OSCORE sets AccessPolicy.Authenticated.

Link copied to clipboard

the largest block the server sends or asks for (RFC 7959), 16..1024. The transport's datagram size may force smaller blocks.

Link copied to clipboard

how many partial Block1 uploads and cached Block2 representations the server keeps; the least recently used is dropped first (RFC 9175 §3.3).

Link copied to clipboard

the most observers of all resources together (RFC 7641 §4.1). Every observer turns each change into a notification plus its retransmissions towards an address that, over UDP, may be spoofed: the amplification RFC 7641 §7 and RFC 7252 §11.3 warn about, so the list is bounded. A registration beyond this bound, beyond maxObserversPerPeer or beyond maxObserversPerResource, is served as a plain GET or FETCH without Observe, as RFC 7641 §4.1 allows a server unwilling to add an observer, and reported as dev.kcoap.coap.stack.EndpointEvent.LimitReached. Re-registrations of an observer (same client endpoint and token) do not count again.

Link copied to clipboard

the most observers one client endpoint (address and port, or DTLS session) may have across all resources. One source, over UDP possibly a spoofed one, registering with ever new tokens would otherwise take all of maxObservers, and every other client would then be served without Observe until those observers end.

Link copied to clipboard

the most observers of one resource, which bounds the notifications one change sends at once and keeps one resource from taking the whole of maxObservers.

Link copied to clipboard

the largest request body the server assembles from Block1 transfers; larger ones get 4.13 Request Entity Too Large with Size1 (RFC 7959 §2.9.3).

Link copied to clipboard

the most client addresses the server remembers as verified, and, separately, the most Echo challenges it keeps outstanding. Verified addresses come only from clients that received an Echo value, so they fill slowly; challenges can come from spoofed requests, so the oldest gives way to a new one. Either eviction is reported as dev.kcoap.coap.stack.EndpointEvent.LimitReached (VERIFIED_ADDRESSES, ADDRESS_CHALLENGES); the address is challenged again when it next needs to be verified.

Link copied to clipboard

how long a Non-confirmable notification counts as outstanding, so a client gets at most one per interval (RFC 7641 §4.5.1: one every 3 seconds without an RTT estimate). Changes in between are coalesced into the latest state.

Link copied to clipboard

whether and how the server serves Q-Block (RFC 9177); off by default, see QBlockServerConfig.

Link copied to clipboard

message security (OSCORE) for incoming requests, called between the messaging layer and block-wise/Observe processing (RFC 8613 Figure 1); null serves unprotected requests only. With it set, defaultAccess refuses requests it did not verify, so configuring it protects every resource that does not say otherwise (ADR 0008).

Link copied to clipboard

bytes kept free in every message for security's overhead when choosing block sizes.

Link copied to clipboard

how long an address stays verified after it returned an Echo value, not extended by use: a NAT may hand the address to another host, and a spoofer must not keep it verified by sending in its name. RFC 9175 sets no lifetime; it needs the check once per endpoint.

Link copied to clipboard

whether to serve /.well-known/core (RFC 6690 §4: MUST on the default port).

Functions

Link copied to clipboard
open override fun toString(): String