Warning
This document is a work in progress and should not be taken as complete.
The CoAP specification defines a protocol, but does so with some terms that are not always used precisely, and others that are left undefined beyond the implications of their conventional meaning. The result is an incomplete and ambiguous specification that does not translate directly into a reference implementation such as CoAPy.
This document refines and redefines terminology to support a domain model for the communications patterns supported by CoAP. It is further informed by draft specifications for an observation capability (which relaxes the notion away from REST to allow a time series of responses to a single query) and a block transfer capabliity (which conveys large messages through a sequence of smaller message transmissions).
For the most part concepts and names introduced derive from those implicit in the CoAP specification. In a few cases CoAP concepts are refactored so the description of their behavior depends on more basic concepts rather than being defined independently.
Note
Within this document a reference to a technical term “concept” appears as concept. Generally use of a term that has a technical meaning should be take to be that meaning, even if the specific use is not so marked.
A technical term at its definition is denoted concept. Whether this is visibly distinct from its use form concept depends on the style used when formatting this document.
To avoid duplication, where a description supports multiple cases with slight variations, parentheses denote the alternatives. Thus a sentence “A confirmable (non-confirmable) message transmission expires after EXCHANGE_LIFETIME (NON_LIFETIME) seconds” identifies a general concept (that message transmissions have time limit on their relevance) and its specific characteristics (that the duration is EXCHANGE_LIFETIME for confirmable messages and NON_LIFETIME for non-confirmable messages).
This section provides a brief introduction to the basic domain concepts. They are described more completely in other sections.
CoAP envisions a two-layer protocol: a message layer and a request/response layer. Extension beyond base CoAP reveals the request/response layer is too abstract, resulting in a recursive concept of what a request/response exchange would be. In this domain model there are three CoAP layers, placed in context in this sequence (from higher to lower layer similar to the OSI model):
Working from the bottom layer up, a message transmission comprises:
The primitive component of a request/response exchange (or REST transaction) is an exchange, comprising:
In turn, a transaction comprises:
Depending on how the transaction is decomposed, it may consist of a single exchange, a sequence of exchanges (as per the -block extension), an initial exchange with additional response message transmissions (as per the -observe extension), or some other abstraction (as per the -groupcomm extension).
CoAP lacks the terminology to describe how exceptional behavior in lower layers impacts the behavior of higher layers. This domain model introduces a concept of resolution to success or failure that applies to message transmissions, exchanges, and transactions. Failure at a lower layer generally propagates to failure at a higher layer.
A message comprises various fields (CoAP Section 3) including:
CoAP defines a byte encoding of a message; the details of that are within the specification and are not relevant to the domain model.
An Option (CoAP Section 3.1) comprises:
An option number as an unsigned integer in the range 0..65535
Note
The ability to express an option number greater than 65535 within an encoded message is assumed to be a flaw in the specification.
An option format (CoAP Section 3.1) specified externally for a given option number
An option length specified in bytes (octets). Constraints on the length are defined externally for a specific option number
An option value within the domain of the format as constrained by the length
An Endpoint comprises:
Related concepts:
Other concepts related to endpoints may be derived when the groupcomm extension is considered.
The transmission parameters (CoAP Section 4.8) describe features related to congestion management, including number of outstanding interactions permitted, maximum data rate, etc. References to those parameters are denoted thus: EXCHANGE_LIFETIME.
Unlike transmission parameters, which are simple values, the domain model requires understanding of the means by which retransmission of confirmable messages is authorized. A Binary Exponential Back-Off (BEBO) state comprises:
The process by which these values are used is described in CoAP Section 4.2. This document refines the description to clarify what a transmission is at a given layer, and the conditions under which retransmission becomes unnecessary or disallowed.
Note
An empty message is a message with Code 0.00. A message that is not empty is a non-empty message.
Note
A request message is a message with Code in class 1.
A response message is a message with Code in class 2, 4, or 5. It is a message-layer component of a transaction-layer concept.
Note
Although a response message may also be a reply message, these concepts are orthogonal: there are response messages that are not reply messages, and reply messages that are not response messages.
There is no generic terminology for messages with Code in class 0, 3, 6, or 7.
In most uses an unqualified message is a message with type CON or NON. Where disambiguation is critical, such a message is called a CON/NON message, and the term “message” may include ACK and RST messages. Sender and receiver are generally used as roles defined relative to a CON/NON message. Take care when speaking of them in the context of a reply message.
A reply message is a message with type ACK or RST. It is coupled with the message to which it is a reply through a shared MID value. A reply message is transmitted by the receiver of a message to that message’s sender.
A (CoAP) message transmission is the act of sending a CON/NON message. The source endpoint is the message sender; the destination endpoint is the message receiver. The message transmission event occurs once for each message.
A (CoAP) message reply is the act of sending a reply message. A message of type CON may evoke a reply of type ACK or RST; a CoAP message of type NON may evoke a reply of type RST. Neither ACK nor RST may evoke replies. A CoAP message transmission will evoke at most one CoAP message reply.
The MID of a CON/NON message is determined by the sender. The sender of a message should not re-use a MID for another confirmable (non-confirmable) message until at least EXCHANGE_LIFETIME (NON_LIFETIME) seconds have passed since the first transport layer transmission of the message.
A transport layer transmission is the act of submitting to the transport layer a block of data that is to be conveyed to a destination endpoint. Messages of type NON, ACK, and RST normally have exactly one transport layer transmission (an exception occurs for reply messages under deduplication rules). Messages of type CON may be transmitted up to 1+MAX_RETRANSMIT transport layer transmissions per BEBO state rules while the message transmision remains unresolved.
To reduce unnecessary retransmissions, a received confirmable message should be acknowledged within ACK_TIMEOUT seconds, where the acknowledgement message is empty unless a response message is permitted and available.
A message transmission may be cancelled by the sender.
Note
The only mention of cancellation from outside the message layer is in CoAP Section 4.2 in the context of stopping retransmission of a request to which the client no longer needs a response, or when there is “some other indication that the CON message did arrive”. The effect of cancellation is not defined by CoAP.
The description here specifies cancellation for all messages regardless of type and does not attempt to restrict the situations where it may be appropriate. The decision that a cancelled confirmable message does not circumvent the message being outstanding is based on the fact that past transmissions are congestion-related actions and the decision to not to use BEBO-authorized transmissions should not circumvent congestion-based restrictions on when a new message may be transmitted. That cancellation does not immediately resolve the transmission to “failed” follows from the possibility a reply may yet arrive before the normal expiration of the transmission.
Message cancellation is an action performed by the sender. The receiver may not be able to determine that the transmission was cancelled.
A message transmission expires at a specific time to provide a deadline by which it will be resolved:
Note
CoAP Section 4.8.2 and CoAP Section 4.7 together imply the concept of an expiration time for message transmission, but leave the expiration for non-confirmable messages undefined. The text above provides values based on the principles underlying the defined expiration for confirmable messages.
A message transmission is resolved once its disposition is determined to be success or failure. Prior to that point the message transmission is unresolved. Be aware that the sender and the receiver of a message transmission may reach conflicting dispositions for a given transmission.
From the perspective of a message receiver, the disposition of the reception is either accept or reject. Rejecting a message is used as a technical term within the CoAP protocol description for situations where a particular disposition is required.
Note
Message rejection is an action performed by the receiver. The sender may not be able to determine whether rejection has occurred.
From the perspective of a message sender, the disposition of a transmission is success or failure. Success or failure of an message transmission is determined by a sender based on time, received reply message type, and information provided by other layers:
Note
CoAP Section 4.2 uses the uncapitalized term “acknowledgement” in a way that may variously be either an acknowledgement message or an external indication that the message transmission can be resolved as successful from external signals (e.g., the proposed case of receiving a response message signalling the success of a confirmable request message transmission). Contrariwise it uses “reset” rather than then entertaining the possibility of an external signal indicative of failure (such as transport-layer rejection).
Text in this section related to the need to keep for deduplication the transmitted acknowledgement replies for received requests even after a successful confirmable response message should not be read to suggest that the intent is that such external evidence does not eliminate the need to receive a reply message. Instead note the specific authorization to stop retransmission if there is “some other indication that the CON message did arrive”. However the ambiguity is reflected in the above use of “may succeed”, indicating that whether an acknowledgement (or failure) is inferred from any given external signal is left to the implementation of other layers.
A duplicate message is a confirmable (non-confirmable) message received from the same source endpoint within EXCHANGE_LIFETIME (NON_LIFETIME) seconds after receipt of another CON/NON message with the same MID.
If a duplicate message is received, then:
Note
This refactors CoAP Section 4.5 by leveraging more precise terminology, and eliminates the unnecessary text related to relaxed rules that explicitly authorize an implementation to do things that result in behavior that is externally indistinguishable from having satisfied the requirement.
A message transmission is outstanding (at the message layer) if it is unresolved.
An endpoint R responds to (or is responsive to) endpoint S with respect to a message transmission to R if
Note
Responsiveness of an endpoint affects whether congestion rules apply to transmissions destined for that endpoint, but is not explicitly defined in CoAP. The text here creates a definition consistent with the common use of the term “responsive”. On the theory that a transport layer might accept a message without properly conveying it to the CoAP server, confirmation from the transport layer is not a sign of responsiveness.
Warning
This section has not been completed. Only a few concepts are described, and they have not been verified.
Warning
This section has not been completed.
Note
This section is intended to refine the text of CoAP Section 4.7, paraphrased as:
An outstanding interaction is one of:
- an outstanding exchange; or
- an outstanding message transmission that is not the request message transmission of an outstanding exchange.
When congestion rules are in force:
Congestion rules apply to client requests to servers per CoAP Section 4.7
Congestion rules apply to -observe responses from servers per observe-11.
Warning
Or not; as of current writing it appears -observe will define its own rules for congestion management instead of sharing the principles used by CoAP Section 4.7.
Commentary:
The BEBO state of a confirmable message transmission specifies when additional transport layer transmissions may be allowed. The BEBO span for an initial timeout of ITO is:
((2 ** (1 + MAX_RETRANSMIT)) - 1) * ITO
The BEBO span shall not exceed MAX_TRANSMIT_WAIT.
Note
At this time it is unclear whether the BEBO span is a necessary domain concept.