Observing Resources in the Constrained Application Protocol (CoAP)

Observable resource semantics (what constitutes a state change, at what granularity) are defined entirely by the server rather than by protocol-level trigger or threshold mechanisms. This allows application designers to choose the appropriate level of complexity, from raw sensor polling to complex parameterized queries.

The 24-bit sequence number was chosen to allow up to 32768 notifications per second after halving the theoretical maximum of 65536 to tolerate combined clock inaccuracies of up to −50/+100% on constrained nodes. The 128-second reordering threshold is a round number larger than MAX_LATENCY (RFC 7252 Section 4.8.2).

The protocol intentionally uses best-effort, eventually-consistent delivery rather than guaranteeing every state change is delivered. This bounded inconsistency model is enforced via the Max-Age Option and is necessary given congestion control constraints and the lossy nature of constrained networks.

The Observe Option is not part of the Cache-Key, so a cacheable response obtained with or without an Observe Option in the request can satisfy the other type of request. A stored response carrying an Observe Option MUST have the option stripped before being returned in reply to a normal GET.

A 2.xx notification MUST include an Observe Option with a sequence number; a non-2.xx notification MUST NOT include an Observe Option.

A client MUST aggregate observation requests for the same target resource and MUST NOT register more than once for that resource. The target resource is identified by all options in the request that are part of the Cache-Key, including the full request URI and the Accept Option.

A client MUST consider the notification sent most recently as the freshest regardless of arrival order. An incoming notification V2 is more recent than the current freshest V1 when (V1 < V2 and V2 − V1 < 2^23), or (V1 > V2 and V1 − V2 > 2^23), or the client timestamp difference exceeds 128 seconds.

A server that is unwilling or unable to add a client to its observer list MAY silently ignore the Observe Option and process the GET normally. The resulting response MUST NOT include an Observe Option, signalling to the client that it will not be notified and should poll instead.

A server that transmits notifications mostly in non-confirmable messages MUST send at least one confirmable notification every 24 hours to prevent stale clients from remaining on the observer list indefinitely.

Each notification MUST echo the token specified by the client in the GET request. When a resource change would cause a normal GET to return a non-2.xx response, the server SHOULD send a notification with an appropriate error code (e.g., 4.04 Not Found) and MUST subsequently remove the client's entry from the observer list.

If a client does not recognize the token in a confirmable notification, it MUST NOT acknowledge the message and SHOULD reject it with a Reset message. If the token is recognized, the client MUST acknowledge the message as usual.

If the age of the latest notification becomes greater than its indicated Max-Age value, the client MUST NOT assume that the enclosed representation reflects the actual resource state.

Intermediaries MUST generate their own Observe Option sequence number values for notifications and MUST set Max-Age according to the age of their local current representation. If multiple clients observe the same resource via an intermediary, the intermediary MUST register itself only once with the next hop and fan out received notifications.

Servers MUST strictly limit simultaneous outstanding notifications/responses to a given client to NSTART (1 by default). The server SHOULD NOT send more than one non-confirmable notification per RTT; without an RTT estimate it SHOULD NOT send more than one every 3 seconds.

congestion

The Content-Format in a 2.xx notification MUST be the same as in the initial response to the GET request. If the server cannot continue sending in that format, it SHOULD send a 4.06 (Not Acceptable) notification and MUST remove the entry from the observer list.

The server MUST ensure that a client eventually observes the latest resource state if the resource does not undergo a new change. When a client rejects a notification with Reset or the last retransmission of a confirmable notification times out, the server MUST remove the associated entry from the observer list.

The server MUST include the Max-Age Option in every notification to indicate an age up to which inconsistency between observed and actual state is acceptable. This value is application-dependent.

The server MUST set the Observe Option in each notification to the 24 least significant bits of a strictly increasing sequence number; the sequence number MUST NOT increase by more than 2^23 within less than 256 seconds. On retransmission, the server MUST update the Observe Option to the sequence number current at the time of retransmission.

Upon successful registration the server MUST keep the resource representation updated as long as the client is on the observer list. If an entry with a matching endpoint/token pair already exists, the server MUST NOT add a new entry but MUST replace or update the existing one.

When a stored response that contains an Observe Option is used to satisfy a normal GET request, the Observe Option MUST be removed before the response is returned to the requester.

The 'obs' target attribute in a web link (RFC 5988 / RFC 6690) is a hint that the linked resource supports observation. It MUST NOT carry a value; any value present MUST be ignored by parsers. It MUST NOT appear more than once in a link-value.

The Observe Option (option number 6) is of type 'uint', 0–3 bytes, with no default value. In a GET request it registers (value 0) or deregisters (value 1) client interest in a resource; in a response it identifies the message as a notification and carries a sequence number for reordering detection.

registry

The CoAP Option Numbers registry has been updated to add option number 6 with the name 'Observe', referencing RFC 7641.

registry

All notifications resulting from a GET request with an Observe Option over a DTLS-secured connection MUST be returned within the same DTLS epoch and connection as the original request. Stale state may be a security threat for sensitive resources, so clients must not use representations after Max-Age expires.

security, tls

Attackers may attempt to exhaust server resources by filling the observer list. Servers SHOULD apply access controls to observer-list state creation and MAY fall back to normal GET processing (without Observe) if resources are exhausted or nearing exhaustion.

security

Observing resources can dramatically amplify reflection attacks: notifications may be much larger than the registration request, and many can be generated. Without client authentication, servers MUST strictly limit non-confirmable notifications and MUST intersperse them with confirmable messages that confirm the client's continued interest.

security

A client enters the observer list when it sends GET Observe:0 and receives a 2.xx response containing an Observe Option. It is removed when: it sends GET Observe:1 (explicit deregister), it rejects a notification with a Reset message, or the last retransmission of a confirmable notification times out without acknowledgement.

The Observe Option value is encoded as an unsigned integer in network byte order using a variable number of bytes ('uint' option format per RFC 7252 Section 3.2), occupying 0–3 bytes. In notifications, the 24 least significant bits of a strictly increasing sequence number are placed in this field.