EndpointEvent

sealed interface EndpointEvent(source)

Something that happened on a CoapEndpoint, for metrics and diagnostics. Messages themselves are seen through a MessageInterceptor; events cover what has no message of its own.

New subtypes may be added before 1.0, so a when over events should have an else branch.

Inheritors

Types

Link copied to clipboard
class AbortReceived(val peer: Endpoint, val badCsmOption: Int?, val diagnostic: String?) : EndpointEvent

The peer aborted the connection (RFC 8323 §5.6).

Link copied to clipboard
class AbortSent(val peer: Endpoint, val diagnostic: String, val badCsmOption: Int?) : EndpointEvent

This endpoint aborted the connection (RFC 8323 §5.6), for example after a missing CSM, a message format error, a message above its Max-Message-Size or an unknown critical signaling option.

Link copied to clipboard
class ConnectionClosed(val peer: Endpoint, val reason: String) : EndpointEvent

The connection to peer closed. Its exchanges failed with CoapException.Reason.CONNECTION_CLOSED and its observations ended (RFC 8323 §3.4, §7.4).

Link copied to clipboard
class ConnectionOpened(val peer: Endpoint, val isInitiator: Boolean) : EndpointEvent

A connection to peer was opened (isInitiator) or accepted (RFC 8323); the CSM exchange follows.

Link copied to clipboard
class CsmReceived(val peer: Endpoint, val maxMessageSize: Long, val blockWiseTransfer: Boolean) : EndpointEvent

The peer sent a CSM (RFC 8323 §5.3). The values are the settings in force after it, since CSM options are cumulative: its Max-Message-Size, and whether it announced Block-Wise-Transfer.

Link copied to clipboard
class DuplicateReceived(val peer: Endpoint, val messageId: Int) : EndpointEvent

A message arrived again within its deduplication lifetime (RFC 7252 §4.5).

Link copied to clipboard

A resource bound was reached, so the endpoint dropped or refused something peer sent or asked for instead of keeping more state (RFC 7252 §11.3). limit says which bound and so what happened; the configuration property it names documents both.

Link copied to clipboard
class MalformedMessage(val peer: Endpoint, val reason: EndpointEvent.MalformedMessage.Reason, val detail: String? = null) : EndpointEvent

What peer sent was not a well-formed message. A datagram was answered with a Reset if its header showed a Confirmable message, and dropped otherwise (RFC 7252 §4.2, §4.3); a connection was aborted (RFC 8323 §5.6). reason is a bounded set fit for counting; detail is what the parser said, for a log.

Link copied to clipboard
class MessageRejected(val peer: Endpoint, val messageId: Int, val reason: EndpointEvent.MessageRejected.Reason, val detail: String? = null) : EndpointEvent

A well-formed message from peer was rejected with a Reset, dropped or ignored, because it broke a rule of the messaging layer or this endpoint lacked the context to process it; or a datagram was dropped unparsed because no answer could reach its source (Reason.INVALID_SOURCE). On reliable transports, which have no Message IDs, messageId is 0. reason is a bounded set fit for counting; detail, when there is one, adds what a log needs, such as the numbers of unrecognized options.

Link copied to clipboard
class ObserverAdded(val peer: Endpoint, val path: String) : EndpointEvent

A client was added to the observers of path (RFC 7641 §4.1).

Link copied to clipboard
class ObserverRemoved(val peer: Endpoint, val path: String, val reason: EndpointEvent.ObserverRemoved.Reason, val detail: String? = null) : EndpointEvent

A client was removed from the observers of path; reason says why, a bounded set fit for counting, and detail, when there is one, adds what a log needs, such as the exception of a failed notification.

Link copied to clipboard
class PartialBodyDropped(val peer: Endpoint, val reason: String) : EndpointEvent

A partially received Q-Block body from peer, an upload on a server or a response body on a client, was given up and its state dropped (RFC 9177 §4.3, §4.4, §7.2): its missing blocks were asked for NON_MAX_RETRANSMIT times without success, no block came for NON_PARTIAL_TIMEOUT, the peer answered a 4.08 with a Reset, or the peer's session ended; reason says which. On a client the request fails.

Link copied to clipboard
class QBlockFallback(val peer: Endpoint, val reason: String) : EndpointEvent

A client with Q-Block on (QBlockClientConfig) uses RFC 7959 block-wise transfer instead of Q-Block towards peer (RFC 9177 §4.1), for reason: the probe was answered with 4.02 Bad Option, a Reset or a response without Q-Block, or not at all, or the server rejected a Q-Block request with 4.02 or a Reset before answering anything else, in which case that request is sent again with RFC 7959. Reported once per finding, not per request.

Link copied to clipboard
class QBlockRecovery(val peer: Endpoint, val isRequestedByPeer: Boolean, val blocks: List<Long>) : EndpointEvent

Missing blocks of a Q-Block body (RFC 9177 §4.3, §4.4, §5) were asked for, by a server or a client with Q-Block on. isRequestedByPeer is true when peer asked, with a 4.08 Request Entity Incomplete listing blocks of an upload or a request for missing Q-Block2 blocks of a response, and this endpoint sends blocks again; false when this endpoint asked peer for blocks the same ways. Many of these towards one peer show a lossy path, for which RFC 9177 §7.2 suggests a smaller MAX_PAYLOADS.

Link copied to clipboard
class ReleaseReceived(val peer: Endpoint, val alternativeAddresses: List<String>, val holdOff: Duration?, val diagnostic: String?) : EndpointEvent

The peer sent a Release (RFC 8323 §5.5): the connection takes no new requests and closes once the requests in progress are answered. Clients do not reconnect to peer for holdOff. The alternativeAddresses are reported, not followed: a connection there would not inherit the security properties of this one (§10.1), so following them is the application's decision.

Link copied to clipboard
class RequestCompleted(val peer: Endpoint, val method: CoapCode, val resourcePath: String?, val responseCode: CoapCode?, val isSuppressed: Boolean, val securityIdentity: SecurityIdentity?, val duration: Duration) : EndpointEvent

A CoapServer finished a request from peer: one event per request message, each block of a Block1 or Q-Block1 body included, also for a request that message security rejected or challenged, so it counts OSCORE traffic, whose outer codes are all a MessageInterceptor sees.

Link copied to clipboard
class ResetReceived(val peer: Endpoint, val messageId: Int) : EndpointEvent

The peer answered one of our messages with a Reset.

Link copied to clipboard
class ResponseRejected(val peer: Endpoint, val reason: EndpointEvent.ResponseRejected.Reason, val detail: String? = null) : EndpointEvent

A response from peer to a request message security protected, which the client did not act on because it was not verified. Nothing else shows it to an observation, whose collectors a failure would end, which RFC 8613 §8.4.2 forbids for one bad notification. reason is a bounded set fit for counting; detail is what the security layer said, for a log.

Link copied to clipboard
class Retransmitted(val peer: Endpoint, val messageId: Int, val attempt: Int) : EndpointEvent

A Confirmable message was sent again (RFC 7252 §4.2); attempt counts from 1.

Link copied to clipboard
class SecurityRejected(val peer: Endpoint, val reason: EndpointEvent.SecurityRejected.Reason, val responseCode: CoapCode, val error: MessageSecurityException? = null) : EndpointEvent

Message security on a CoapServer did not let a request from peer reach a resource, for reason, and answered it with responseCode. Its RequestCompleted follows. error is what the security layer threw for a request that failed verification; with kcoap-oscore its cause is the OscoreException, whose OscoreError can be counted.

Link copied to clipboard

The DTLS session to peer ended; its exchanges and observations were failed (RFC 7252 §9.1.1).

Link copied to clipboard
class TransmissionTimedOut(val peer: Endpoint, val messageId: Int) : EndpointEvent

A Confirmable message was not acknowledged after MAX_RETRANSMIT retransmissions.

Properties

Link copied to clipboard
abstract val peer: Endpoint

The peer the event concerns.