CoapEndpointConfig

How a CoapEndpoint runs its messaging layers.

Build one with the DSL, CoapEndpointConfig { separateResponseDelay = 500.milliseconds }, or with a Builder (CoapEndpointConfig.Builder(), set its properties, build()), which reads the same from Swift; Default has every default, and toBuilder starts from an existing configuration. The configuration itself is immutable, and every value is checked when it is built. Options added later go into the builder, so code that builds a configuration keeps compiling, and compiled code keeps linking.

Resource bounds. Everything a peer can make the endpoint keep or do is bounded, in total and per peer, with defaults sized for a server. Over UDP the source address of a datagram proves nothing (RFC 7252 §11.4), so a flood of spoofed messages must cost bounded memory and CPU, and RFC 7252 §11.3 warns that answering it can turn the endpoint into an amplifier against the address it names. At a bound the endpoint first forgets what the RFCs let it forget, then drops or refuses only the extra work, answers with at most a few bytes more than it received (a refusal's Max-Age), keeps serving what it already has, and reports what it refused as EndpointEvent.LimitReached so the condition can be counted:

BoundDefaultAt the bound
maxDeduplicationEntries, maxDeduplicationEntriesPerPeer50 000, 10 000forgets the oldest message that may be processed again (RFC 7252 §4.5), else drops the new one
maxReservedMessageIds, maxReservedMessageIdsPerPeer262 144, 65 536refuses the message that needs a new Message ID (§4.4 forbids reuse), a response to a Non-confirmable request already at three quarters
maxExchanges, maxExchangesPerPeer16 384, 256forgets the oldest Non-confirmable message kept for a Reset, else gives up the oldest Confirmable one unacknowledged after a retransmission, else refuses
maxConcurrentRequests2565.03 with Max-Age to a Confirmable request, drops a Non-confirmable one

The server's observer bounds are in CoapServerConfig, the bounds on connections in ReliableTransportConfig.

Types

Link copied to clipboard
class Builder

Collects the values of a CoapEndpointConfig; every property starts at its default, documented on the property of the same name. Not thread safe: build on one thread, then share the configuration.

Link copied to clipboard
object Companion

Properties

Link copied to clipboard
Link copied to clipboard

The message interceptor chain, in order; a copy of the list given.

Link copied to clipboard

Where the endpoint's loggers come from.

Link copied to clipboard

The most request handlers running at once, over every transport. Beyond it a Confirmable request is answered with a piggybacked 5.03 Service Unavailable with a Max-Age of 2 seconds, when to try again (RFC 7252 §5.9.3.4). That answer is at most 3 bytes larger than the request, an amplification factor below 2 (§11.3), and duplicates of the request get the same answer from the deduplication cache; a Non-confirmable request is dropped; a request on a connection gets the 5.03. Requests never queue, and the receive loop never waits for a free handler.

Link copied to clipboard

The most received messages remembered for deduplication (RFC 7252 §4.5), each for EXCHANGE_LIFETIME or NON_LIFETIME together with the reply it got. Any new message from any source address adds one, so this bounds what a flood of spoofed datagrams makes the endpoint remember. When it is full, a new message takes the place of the oldest repeatable one, a message §4.5 lets the endpoint process again because that ends the same way: a request with an idempotent method (GET, PUT, DELETE, FETCH, iPATCH) once answered or acknowledged, a message answered with a Reset, or a request answered or dropped before anything acted on it (a message-security failure, an access refusal, an unknown path, an unrecognized critical option, an overload refusal). A request message security verified is never repeatable: OSCORE records its Partial IV in the replay window (RFC 8613 §7.4), so processing it again would end in a replay error. A duplicate of a forgotten message is processed as a new one (§4.5 "relaxed" deduplication). When nothing repeatable is left, a new message is dropped silently, without state and without an answer that would go to a possibly spoofed source (§11.3), and reported as EndpointEvent.LimitReached with DEDUPLICATION_ENTRIES; its sender retransmits a Confirmable one, and duplicates of remembered messages are still answered. A quarter of the bound is kept for repeatable messages: a new non-idempotent request is dropped once three quarters hold messages that must be remembered, so a flood of POSTs never keeps a GET out, nor the responses to the endpoint's own requests, which do not count against that share (a response that matches no exchange, all a forged source can send, is reset at once).

Link copied to clipboard

The most received messages remembered from one peer, out of maxDeduplicationEntries, so one source, such as one flooding address, cannot take the whole cache. When a peer has this many, its own oldest repeatable message is forgotten for a new one, else the new one is dropped and reported with DEDUPLICATION_ENTRIES_PER_PEER. A peer that sends more than about 40 non-idempotent requests a second for EXCHANGE_LIFETIME reaches it with the default.

Link copied to clipboard

The most exchanges in progress with all peers together, counted as for maxExchangesPerPeer: requests of this endpoint awaiting their response and its observations, and over datagrams every message the messaging layer keeps, also each Non-confirmable one kept for NON_LIFETIME so that a Reset can match it. At the bound a new datagram message first takes the place of the oldest Non-confirmable message kept only for a Reset (RFC 7252 §4.3 lets a sender ignore a Reset), then of the oldest Confirmable message that is still unacknowledged after a retransmission, which is given up early as if it had timed out and reported with EXCHANGES: a peer that answers acknowledges within ACK_TIMEOUT, while a spoofed source only draws retransmissions (§11.3). Otherwise a request fails with CoapException.Reason.IDENTIFIERS_EXHAUSTED, a separate response is not sent, and a notification is sent later with the latest state while the observer stays (RFC 7641 §4.5), each reported with EXCHANGES.

Link copied to clipboard

The most exchanges in progress with one peer: requests of this endpoint awaiting their response and its observations, and over datagrams also every Confirmable message awaiting its ACK or queued behind NSTART (RFC 7252 §4.7), separate responses and notifications included, and every Non-confirmable Q-Block body holding or awaiting its NSTART slot. A request beyond it fails at once with CoapException.Reason.IDENTIFIERS_EXHAUSTED; a separate response or notification beyond it is not sent. It bounds the queue that a peer which never acknowledges, such as a spoofed one, can build up (§11.3).

Link copied to clipboard

The most Message IDs reserved at once, towards all peers together. Every message the endpoint sends with a new Message ID (a request, a separate response, a notification, every message of a Q-Block body) reserves it for EXCHANGE_LIFETIME, since RFC 7252 §4.4 forbids reusing it towards that peer before, and a flood of spoofed Non-confirmable requests makes the endpoint send one response, and so reserve one ID, each. Beyond the bound such a message is refused instead: a request fails with CoapException.Reason.IDENTIFIERS_EXHAUSTED, a separate response is not sent, a notification is sent later with the latest state while the observer stays (RFC 7641 §4.5), and each is reported with MESSAGE_IDS. A quarter of the bound, and of maxReservedMessageIdsPerPeer, is kept from Non-confirmable responses to Non-confirmable requests, which a client may lose anyway (§5.2.3) and a flood from forged addresses makes the endpoint send: they are refused at three quarters, so the rest is left for the endpoint's own requests, notifications and separate responses to Confirmable requests. Piggybacked responses reuse the request's ID and are never refused. The default allows four peers at the most RFC 7252 §4.4 allows one (65 536 per EXCHANGE_LIFETIME), about 1 000 messages a second in all, and takes about 26 MB when full.

Link copied to clipboard

The most Message IDs reserved at once towards one peer, 1..65 536: by default the whole ID space, so the bound is the one RFC 7252 §4.4 sets, about 265 messages a second to one peer. Beyond it a message to that peer that needs a new ID is refused as for maxReservedMessageIds, reported with MESSAGE_IDS_PER_PEER.

Link copied to clipboard

RFC 7252 §4.8 transmission parameters, for datagram transports.

Link copied to clipboard

Randomness for retransmission jitter and the first Message ID. Tokens come from tokenGenerator, which uses a secure generator by default.

Link copied to clipboard

CSM settings and connection management for CoAP over reliable transports (RFC 8323).

Link copied to clipboard

How long a Confirmable request may wait for its response before the endpoint sends an Empty ACK and the response follows separately (RFC 7252 §5.2.2). It should stay below ACK_TIMEOUT so the client does not retransmit; null disables it, so a slow handler makes the client retransmit.

Link copied to clipboard

The clock every timer reads (architecture rule 5: one shared clock). Timers wait with the delays of the endpoint scope's dispatcher, so this time source must advance with that dispatcher's clock: the default TimeSource.Monotonic with a real dispatcher, and under runTest testScheduler.timeSource, so retransmissions and lifetimes run on virtual time. The endpoint logs a warning when it sees the two disagree.

Link copied to clipboard

Chooses request tokens. Null, the default, gives every endpoint a TokenGenerator.sessionSequence of its own, so one configuration can serve several endpoints, such as a server's and a client's. A generator given here that keeps state must not be shared between endpoints.

Functions

Link copied to clipboard

A Builder holding this configuration's values, to build a changed copy.

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