diff options
Diffstat (limited to 'rfc/draft-ietf-core-observe-16.txt')
-rw-r--r-- | rfc/draft-ietf-core-observe-16.txt | 1904 |
1 files changed, 1904 insertions, 0 deletions
diff --git a/rfc/draft-ietf-core-observe-16.txt b/rfc/draft-ietf-core-observe-16.txt new file mode 100644 index 0000000..2494f43 --- /dev/null +++ b/rfc/draft-ietf-core-observe-16.txt @@ -0,0 +1,1904 @@ + + + +CoRE Working Group K. Hartke +Internet-Draft Universitaet Bremen TZI +Intended status: Standards Track December 30, 2014 +Expires: July 3, 2015 + + + Observing Resources in CoAP + draft-ietf-core-observe-16 + +Abstract + + The Constrained Application Protocol (CoAP) is a RESTful application + protocol for constrained nodes and networks. The state of a resource + on a CoAP server can change over time. This document specifies a + simple protocol extension for CoAP that enables CoAP clients to + "observe" resources, i.e., to retrieve a representation of a resource + and keep this representation updated by the server over a period of + time. The protocol follows a best-effort approach for sending new + representations to clients and provides eventual consistency between + the state observed by each client and the actual resource state at + the server. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at http://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on July 3, 2015. + +Copyright Notice + + Copyright (c) 2014 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + + + +Hartke Expires July 3, 2015 [Page 1] + +Internet-Draft Observing Resources in CoAP December 2014 + + + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Background . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 3 + 1.3. Consistency Model . . . . . . . . . . . . . . . . . . . . 5 + 1.4. Observable Resources . . . . . . . . . . . . . . . . . . . 6 + 1.5. Requirements Notation . . . . . . . . . . . . . . . . . . 7 + 2. The Observe Option . . . . . . . . . . . . . . . . . . . . . . 7 + 3. Client-side Requirements . . . . . . . . . . . . . . . . . . . 8 + 3.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 8 + 3.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 8 + 3.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 9 + 3.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 10 + 3.5. Transmission . . . . . . . . . . . . . . . . . . . . . . . 11 + 3.6. Cancellation . . . . . . . . . . . . . . . . . . . . . . . 11 + 4. Server-side Requirements . . . . . . . . . . . . . . . . . . . 12 + 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 4.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 13 + 4.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 4.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 14 + 4.5. Transmission . . . . . . . . . . . . . . . . . . . . . . . 15 + 5. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 18 + 6. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 + 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20 + 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 + 10.1. Normative References . . . . . . . . . . . . . . . . . . . 21 + 10.2. Informative References . . . . . . . . . . . . . . . . . . 21 + Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 22 + A.1. Client/Server Examples . . . . . . . . . . . . . . . . . . 22 + A.2. Proxy Examples . . . . . . . . . . . . . . . . . . . . . . 26 + Appendix B. Changelog . . . . . . . . . . . . . . . . . . . . . . 28 + + + + + + + + + + + +Hartke Expires July 3, 2015 [Page 2] + +Internet-Draft Observing Resources in CoAP December 2014 + + +1. Introduction + +1.1. Background + + The Constrained Application Protocol (CoAP) [RFC7252] is intended to + provide RESTful services [REST] not unlike HTTP [RFC7230] while + reducing the complexity of implementation as well as the size of + packets exchanged in order to make these services useful in a highly + constrained network of themselves highly constrained nodes [RFC7228]. + + The model of REST is that of a client exchanging representations of + resources with a server, where a representation captures the current + or intended state of a resource. The server is the authority for + representations of the resources in its namespace. A client + interested in the state of a resource initiates a request to the + server, the server then returns a response with a representation of + the resource that is current at the time of the request. + + This model does not work well when a client is interested in having a + current representation of a resource over a period of time. Existing + approaches from HTTP, such as repeated polling or HTTP long polling + [RFC6202], generate significant complexity and/or overhead and thus + are less applicable in a constrained environment. + + The protocol specified in this document extends the CoAP core + protocol with a mechanism for a CoAP client to "observe" a resource + on a CoAP server: the client retrieves a representation of the + resource and requests this representation be updated by the server + as long as the client is interested in the resource. + + The protocol keeps the architectural properties of REST. It enables + high scalability and efficiency through the support of caches and + proxies. There is no intention, though, to solve the full set of + problems that the existing HTTP solutions solve, or to replace + publish/subscribe networks that solve a much more general problem + [RFC5989]. + +1.2. Protocol Overview + + The protocol is based on the well-known observer design pattern + [GOF]. In this design pattern, components called "observers" + register at a specific, known provider called the "subject" that they + are interested in being notified whenever the subject undergoes a + change in state. The subject is responsible for administering its + list of registered observers. If multiple subjects are of interest + to an observer, the observer must register separately for all of + them. + + + + +Hartke Expires July 3, 2015 [Page 3] + +Internet-Draft Observing Resources in CoAP December 2014 + + + Observer Subject + | | + | Registration | + +------------------->| + | | + | Notification | + |<-------------------+ + | | + | Notification | + |<-------------------+ + | | + | Notification | + |<-------------------+ + | | + + Figure 1: The Observer Design Pattern + + The observer design pattern is realized in CoAP as follows: + + Subject: In the context of CoAP, the subject is a resource in the + namespace of a CoAP server. The state of the resource can change + over time, ranging from infrequent updates to continuous state + transformations. + + Observer: An observer is a CoAP client that is interested in having + a current representation of the resource at any given time. + + Registration: A client registers its interest in a resource by + initiating an extended GET request to the server. In addition to + returning a representation of the target resource, this request + causes the server to add the client to the list of observers of + the resource. + + Notification: Whenever the state of a resource changes, the server + notifies each client in the list of observers of the resource. + Each notification is an additional CoAP response sent by the + server in reply to the single extended GET request, and includes a + complete, updated representation of the new resource state. + + Figure 2 below shows an example of a CoAP client registering its + interest in a resource and receiving three notifications: the first + with the current state upon registration, and then two upon changes + to the resource state. Both the registration request and the + notifications are identified as such by the presence of the Observe + Option defined in this document. In notifications, the Observe + Option additionally provides a sequence number for reordering + detection. All notifications carry the token specified by the + client, so the client can easily correlate them to the request. + + + +Hartke Expires July 3, 2015 [Page 4] + +Internet-Draft Observing Resources in CoAP December 2014 + + + Client Server + | | + | GET /temperature | + | Token: 0x4a | Registration + | Observe: 0 | + +------------------->| + | | + | 2.05 Content | + | Token: 0x4a | Notification of + | Observe: 12 | the current state + | Payload: 22.9 Cel | + |<-------------------+ + | | + | 2.05 Content | + | Token: 0x4a | Notification upon + | Observe: 44 | a state change + | Payload: 22.8 Cel | + |<-------------------+ + | | + | 2.05 Content | + | Token: 0x4a | Notification upon + | Observe: 60 | a state change + | Payload: 23.1 Cel | + |<-------------------+ + | | + + Figure 2: Observing a Resource in CoAP + + A client remains on the list of observers as long as the server can + determine the client's continued interest in the resource. The + server may send a notification in a confirmable CoAP message to + request an acknowledgement from the client. When the client + deregisters, rejects a notification, or the transmission of a + notification times out after several transmission attempts, the + client is considered no longer interested in the resource and is + removed by the server from the list of observers. + +1.3. Consistency Model + + While a client is in the list of observers of a resource, the goal of + the protocol is to keep the resource state observed by the client as + closely in sync with the actual state at the server as possible. + + It cannot be avoided that the client and the server become out of + sync at times: First, there is always some latency between the change + of the resource state and the receipt of the notification. Second, + CoAP messages with notifications can get lost, which will cause the + client to assume an old state until it receives a new notification. + + + +Hartke Expires July 3, 2015 [Page 5] + +Internet-Draft Observing Resources in CoAP December 2014 + + + And third, the server may erroneously come to the conclusion that the + client is no longer interested in the resource, which will cause the + server to stop sending notifications and the client to assume an old + state until it eventually registers its interest again. + + The protocol addresses this issue as follows: + + o It follows a best-effort approach for sending the current + representation to the client after a state change: Clients should + see the new state after a state change as soon as possible, and + they should see as many states as possible. This is limited by + congestion control, however, so a client cannot rely on observing + every single state that a resource might go through. + + o It labels notifications with a maximum duration up to which it is + acceptable for the observed state and the actual state to be out + of sync. When the age of the notification received reaches this + limit, the client cannot use the enclosed representation until it + receives a new notification. + + o It is designed on the principle of eventual consistency: The + protocol guarantees that, if the resource does not undergo a new + change in state, eventually all registered observers will have a + current representation of the latest resource state. + +1.4. Observable Resources + + A CoAP server is the authority for determining under what conditions + resources change their state and thus when observers are notified of + new resource states. The protocol does not offer explicit means for + setting up triggers or thresholds; it is up to the server to expose + observable resources that change their state in a way that is useful + in the application context. + + For example, a CoAP server with an attached temperature sensor could + expose one or more of the following resources: + + o <coap://server/temperature>, which changes its state every few + seconds to a current reading of the temperature sensor; + + o <coap://server/temperature/felt>, which changes its state to + "COLD" whenever the temperature reading drops below a certain pre- + configured threshold, and to "WARM" whenever the reading exceeds a + second, slightly higher threshold; + + o <coap://server/temperature/critical?above=42>, which changes its + state based on the client-specified parameter value: every few + seconds to the current temperature reading if the temperature + + + +Hartke Expires July 3, 2015 [Page 6] + +Internet-Draft Observing Resources in CoAP December 2014 + + + exceeds the threshold, or to "OK" when the reading drops below; + + o <coap://server/?query=select+avg(temperature)+from+Sensor.window: + time(30sec)>, which accepts expressions of arbitrary complexity + and changes its state accordingly. + + Thus, by designing CoAP resources that change their state on certain + conditions, it is possible to update the client only when these + conditions occur instead of supplying it continuously with raw sensor + data. By parameterizing resources, this is not limited to conditions + defined by the server, but can be extended to arbitrarily complex + queries specified by the client. The application designer therefore + can choose exactly the right level of complexity for the application + envisioned and devices involved, and is not constrained to a "one + size fits all" mechanism built into the protocol. + +1.5. Requirements Notation + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + +2. The Observe Option + + The Observe Option has the following properties. Its meaning depends + on whether it is included in a GET request or in a response. + + +-----+---+---+---+---+---------+--------+--------+---------+ + | No. | C | U | N | R | Name | Format | Length | Default | + +-----+---+---+---+---+---------+--------+--------+---------+ + | 6 | | x | - | | Observe | uint | 0-3 B | (none) | + +-----+---+---+---+---+---------+--------+--------+---------+ + + C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable + + Table 1: The Observe Option + + When included in a GET request, the Observe Option extends the GET + method so it does not only retrieve a current representation of the + target resource, but also requests the server to add or remove an + entry in the list of observers of the resource, depending on the + option value. The list entry consists of the client endpoint and the + token specified by the client in the request. Possible values are: + + 0 (register) adds the entry to the list, if not present; + + 1 (deregister) removes the entry from the list, if present. + + + + +Hartke Expires July 3, 2015 [Page 7] + +Internet-Draft Observing Resources in CoAP December 2014 + + + The Observe Option is not critical for processing the request. If + the server is unwilling or unable to add a new entry to the list of + observers, then the request falls back to a normal GET request, and + the response does not include the Observe Option. + + The Observe Option is not part of the cache-key: a cacheable response + obtained with an Observe Option in the request can be used to satisfy + a request without an Observe Option, and vice versa. When a stored + response with an Observe Option is used to satisfy a normal GET + request, the option MUST be removed before the response is returned. + + When included in a response, the Observe Option identifies the + message as a notification. This implies that a matching entry exists + in the list of observers and that the server will notify the client + of changes to the resource state. The option value is a sequence + number for reordering detection (see Section 3.4 and Section 4.4). + + The value of the Observe Option is encoded as an unsigned integer in + network byte order using a variable number of bytes ('uint' option + format); see Section 3.2 of RFC 7252 [RFC7252]. + +3. Client-side Requirements + +3.1. Request + + A client registers its interest in a resource by issuing a GET + request with an Observe Option set to 0 (register). If the server + returns a 2.xx response that includes an Observe Option as well, the + server has successfully added an entry with the client endpoint and + request token to the list of observers of the target resource and the + client will be notified of changes to the resource state. + + Like a fresh response can be used to satisfy a request without + contacting the server, the stream of updates resulting from one + observation request can be used to satisfy another (observation or + normal GET) request if the target resource is the same. A client + MUST aggregate such requests and MUST NOT register more than once for + the same target resource. The target resource is identified by all + options in the request that are part of the cache-key. This + includes, for example, the full request URI and the Accept Option. + +3.2. Notifications + + Notifications are additional responses sent by the server in reply to + the single extended GET request that created the registration. Each + notification includes the token specified by the client in the + request. The only difference between a notification and a normal + response is the presence of the Observe Option. + + + +Hartke Expires July 3, 2015 [Page 8] + +Internet-Draft Observing Resources in CoAP December 2014 + + + Notifications typically have a 2.05 (Content) response code. They + include an Observe Option with a sequence number for reordering + detection (see Section 3.4), and a payload in the same Content-Format + as the initial response. If the client included one or more ETag + Options in the GET request (see Section 3.3), notifications can have + a 2.03 (Valid) response code rather than a 2.05 (Content) response + code. Such notifications include an Observe Option with a sequence + number but no payload. + + In the event that the resource changes in a way that would cause a + normal GET request at that time to return a non-2.xx response (for + example, when the resource is deleted), the server sends a + notification with an appropriate response code (such as 4.04 Not + Found) and removes the client's entry from the list of observers of + the resource. Non-2.xx responses do not include an Observe Option. + +3.3. Caching + + As notifications are just additional responses to a GET request, + notifications partake in caching as defined in Section 5.6 of RFC + 7252 [RFC7252]. Both the freshness model and the validation model + are supported. + +3.3.1. Freshness + + A client MAY store a notification like a response in its cache and + use a stored notification that is fresh without contacting the + server. Like a response, a notification is considered fresh while + its age is not greater than the value indicated by the Max-Age Option + (and no newer notification/response has been received). + + The server will do its best to keep the resource state observed by + the client as closely in sync with the actual state as possible. + However, a client cannot rely on observing every single state that a + resource might go through. For example, if the network is congested + or the state changes more frequently than the network can handle, the + server can skip notifications for any number of intermediate states. + + The server uses the Max-Age Option to indicate an age up to which it + is acceptable that the observed state and the actual state are + inconsistent. If the age of the latest notification becomes greater + than its indicated Max-Age, then the client MUST NOT assume that the + enclosed representation reflects the actual resource state. + + To make sure it has a current representation and/or to re-register + its interest in a resource, a client MAY issue a new GET request with + the same token as the original at any time. All options MUST be + identical to those in the original request, except for the set of + + + +Hartke Expires July 3, 2015 [Page 9] + +Internet-Draft Observing Resources in CoAP December 2014 + + + ETag Options. It is RECOMMENDED that the client does not issue the + request while it still has a fresh notification/response for the + resource in its cache. Additionally, the client SHOULD at least wait + for a random amount of time between 5 and 15 seconds after Max-Age + expired to reduce collisions with other clients. + +3.3.2. Validation + + When a client has one or more notifications stored in its cache for a + resource, it can use the ETag Option in the GET request to give the + server an opportunity to select a stored notification to be used. + + The client MAY include an ETag Option for each stored response that + is applicable in the GET request. Whenever the observed resource + changes to a representation identified by one of the ETag Options, + the server can select a stored response by sending a 2.03 (Valid) + notification with an appropriate ETag Option instead of a 2.05 + (Content) notification. + + A client implementation needs to keep all candidate responses in its + cache until it is no longer interested in the target resource or it + re-registers with a new set of entity-tags. + +3.4. Reordering + + Messages with notifications can arrive in a different order than they + were sent. Since the goal is to keep the observed state as closely + in sync with the actual state as possible, a client MUST consider the + notification that was sent most recently as the freshest, regardless + of the order of arrival. + + To provide an order among notifications for the client, the server + sets the value of the Observe Option in each notification to the 24 + least-significant bits of a strictly increasing sequence number. An + incoming notification was sent more recently than the freshest + notification so far when one of the following conditions is met: + + (V1 < V2 and V2 - V1 < 2^23) or + (V1 > V2 and V1 - V2 > 2^23) or + (T2 > T1 + 128 seconds) + + where V1 is the value of the Observe Option in the freshest + notification so far, V2 the value of the Observe Option in the + incoming notification, T1 a client-local timestamp for the freshest + notification so far, and T2 a client-local timestamp for the incoming + notification. + + + + + +Hartke Expires July 3, 2015 [Page 10] + +Internet-Draft Observing Resources in CoAP December 2014 + + + Design Note: The first two conditions verify that V1 is less than V2 + in 24-bit serial number arithmetic [RFC1982]. The third condition + ensures that, if the server is generating serial numbers based on + a local clock, the time elapsed between the two incoming messages + is not so large that the difference between V1 and V2 has become + larger than the largest integer that it is meaningful to add to a + 24-bit serial number; in other words, after 128 seconds have + elapsed without any notification, a client does not need to check + the sequence numbers to assume that an incoming notification was + sent more recently than the freshest notification it has received + so far. + + The duration of 128 seconds was chosen as a nice round number + greater than MAX_LATENCY (Section 4.8.2 of RFC 7252 [RFC7252]). + +3.5. Transmission + + A notification can be confirmable or non-confirmable, i.e., it can be + sent in a confirmable or a non-confirmable message. The message type + used for a notification is independent of the type used for the + request and of any previous notification. + + 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; otherwise, the client MUST acknowledge the + message as usual. In the case of a non-confirmable notification, + rejecting the message with a Reset message is OPTIONAL. + + An acknowledgement message signals to the server that the client is + alive and interested in receiving further notifications; if the + server does not receive an acknowledgement in reply to a confirmable + notification, it will assume that the client is no longer interested + and will eventually remove the associated entry from the list of + observers. + +3.6. Cancellation + + A client that is no longer interested in receiving notifications for + a resource can simply "forget" the observation. When the server then + sends the next notification, the client will not recognize the token + in the message and thus will return a Reset message. This causes the + server to remove the associated entry from the list of observers. + The entries in lists of observers are effectively "garbage collected" + by the server. + + + + + + + +Hartke Expires July 3, 2015 [Page 11] + +Internet-Draft Observing Resources in CoAP December 2014 + + + Implementation Note: Due to potential message loss, the Reset + message may not reach the server. The client may therefore have + to reject multiple notifications, each with one Reset message, + until the server finally removes the associated entry from the + list of observers and stops sending notifications. + + In some circumstances, it may be desirable to cancel an observation + and release the resources allocated by the server to it more eagerly. + In this case, a client MAY explicitly deregister by issuing a GET + request which has the Token field set to the token of the observation + to be cancelled and includes an Observe Option with the value set to + 1 (deregister). All other options MUST be identical to those in the + registration request, except for the set of ETag Options. When the + server receives such a request, it will remove any matching entry + from the list of observers and process the GET request as usual. + +4. Server-side Requirements + +4.1. Request + + A GET request with an Observe Option set to 0 (register) requests the + server not only to return a current representation of the target + resource, but also to add the client to the list of observers of that + resource. Upon success, the server returns a current representation + of the resource and MUST keep this representation updated (as + described in Section 1.3) as long as the client is on the list of + observers. + + The entry in the list of observers is keyed by the client endpoint + and the token specified by the client in the request. If an entry + with a matching endpoint/token pair is already present in the list + (which, for example, happens when the client wishes to reinforce its + interest in a resource), the server MUST NOT add a new entry but MUST + replace or update the existing one. + + A server that is unable or unwilling to add a new entry to the list + of observers of a resource MAY silently ignore the registration + request and process the GET request as usual. The resulting response + MUST NOT include an Observe Option, the absence of which signals to + the client that it will not be notified of changes to the resource + and, e.g., needs to poll the resource for its state instead. + + If the Observe Option in a GET request is set to 1 (deregister), then + the server MUST remove any existing entry with a matching endpoint/ + token pair from the list of observers and process the GET request as + usual. The resulting response MUST NOT include an Observe Option. + + + + + +Hartke Expires July 3, 2015 [Page 12] + +Internet-Draft Observing Resources in CoAP December 2014 + + +4.2. Notifications + + A client is notified of changes to the resource state by additional + responses sent by the server in reply to the GET request. Each such + notification response (including the initial response) MUST echo the + token specified by the client in the GET request. If there are + multiple entries in the list of observers, the order in which the + clients are notified is not defined; the server is free to use any + method to determine the order. + + A notification SHOULD have a 2.05 (Content) or 2.03 (Valid) response + code. However, in the event that the state of a resource changes in + a way that would cause a normal GET request at that time to return a + non-2.xx response (for example, when the resource is deleted), the + server SHOULD notify the client by sending a notification with an + appropriate response code (such as 4.04 Not Found) and subsequently + MUST remove the associated entry from the list of observers of the + resource. + + The Content-Format specified in a 2.xx notification MUST be the same + as the one used in the initial response to the GET request. If the + server is unable to continue sending notifications in this format, it + SHOULD send a notification with a 4.06 (Not Acceptable) response code + and subsequently MUST remove the associated entry from the list of + observers of the resource. + + A 2.xx notification MUST include an Observe Option with a sequence + number as specified in Section 4.4 below; a non-2.xx notification + MUST NOT include an Observe Option. + +4.3. Caching + + As notifications are just additional responses sent by the server in + reply to a GET request, they are subject to caching as defined in + Section 5.6 of RFC 7252 [RFC7252]. + +4.3.1. Freshness + + After returning the initial response, the server MUST keep the + resource state that is observed by the client as closely in sync with + the actual resource state as possible. + + Since becoming out of sync at times cannot be avoided, the server + MUST indicate for each representation an age up to which it is + acceptable that the observed state and the actual state are + inconsistent. This age is application-dependent and MUST be + specified in notifications using the Max-Age Option. + + + + +Hartke Expires July 3, 2015 [Page 13] + +Internet-Draft Observing Resources in CoAP December 2014 + + + When the resource does not change and the client has a current + representation, the server does not need to send a notification. + However, if the client does not receive a notification, the client + cannot tell if the observed state and the actual state are still in + sync. Thus, when the age of the latest notification becomes greater + than its indicated Max-Age, the client no longer has a usable + representation of the resource state. The server MAY wish to prevent + that by sending a new notification with the unchanged representation + and a new Max-Age just before the Max-Age indicated earlier expires. + +4.3.2. Validation + + A client can include a set of entity-tags in its request using the + ETag Option. When a observed resource changes its state and the + origin server is about to send a 2.05 (Content) notification, then, + whenever that notification has an entity-tag in the set of entity- + tags specified by the client, the server MAY send a 2.03 (Valid) + response with an appropriate ETag Option instead. + +4.4. Reordering + + Because messages can get reordered, the client needs a way to + determine if a notification arrived later than a newer notification. + For this purpose, the server MUST set the value of the Observe Option + of each notification it sends to the 24 least-significant bits of a + strictly increasing sequence number. The sequence number MAY start + at any value and MUST NOT increase so fast that it increases by more + than 2^23 within less than 256 seconds. + + The sequence number selected for a notification MUST be greater than + that of any preceding notification sent to the same client with the + same token for the same resource. The value of the Observe Option + MUST be current at the time of transmission; if a notification is + retransmitted, the server MUST update the value of the option to the + sequence number that is current at that time before retransmission. + + Implementation Note: A simple implementation that satisfies the + requirements is to obtain a timestamp from a local clock. The + sequence number then is the timestamp in ticks, where 1 tick = + (256 seconds)/(2^23) = 30.52 microseconds. It is not necessary + that the clock reflects the current time/date. + + Another valid implementation is to store a 24-bit unsigned integer + variable per resource and increment this variable each time the + resource undergoes a change of state (provided that the resource + changes its state less than 2^23 times in the first 256 seconds + after every state change). This removes the need to update the + value of the Observe Option on retransmission when the resource + + + +Hartke Expires July 3, 2015 [Page 14] + +Internet-Draft Observing Resources in CoAP December 2014 + + + state did not change. + + Design Note: The choice of a 24-bit option value and a time span of + 256 seconds theoretically allows for a notification rate of up to + 65536 notifications per second. Constrained nodes often have + rather imprecise clocks, though, and inaccuracies of the client + and server side may cancel out or add in effect. Therefore, the + maximum notification rate is reduced to 32768 notifications per + second. This is still well beyond the highest known design + objective of around 1 kHz (most CoAP applications will be several + orders of magnitude below that), but allows total clock + inaccuracies of up to -50/+100 %. + +4.5. Transmission + + A notification can be sent in a confirmable or a non-confirmable + message. The message type used is typically application-dependent + and may be determined by the server for each notification + individually. + + For example, for resources that change in a somewhat predictable or + regular fashion, notifications can be sent in non-confirmable + messages; for resources that change infrequently, notifications can + be sent in confirmable messages. The server can combine these two + approaches depending on the frequency of state changes and the + importance of individual notifications. + + A server MAY choose to skip sending a notification if it knows that + it will send another notification soon, for example, when the state + of a resource is changing frequently. It also MAY choose to send + more than one notification for the same resource state. However, + above all, the server MUST ensure that a client in the list of + observers of a resource eventually observes the latest state if the + resource does not undergo a new change in state. + + For example, when state changes occur in bursts, the server can skip + some notifications, send the notifications in non-confirmable + messages, and make sure that the client observes the latest state + change by repeating the last notification in a confirmable message + when the burst is over. + + The client's acknowledgement of a confirmable notification signals + that the client is interested in receiving further notifications. If + a client rejects a confirmable or non-confirmable notification with a + Reset message, or if the last attempt to retransmit a confirmable + notification times out, then the client is considered no longer + interested and the server MUST remove the associated entry from the + list of observers. + + + +Hartke Expires July 3, 2015 [Page 15] + +Internet-Draft Observing Resources in CoAP December 2014 + + + Implementation Note: To properly process a Reset message that + rejects a non-confirmable notification, a server needs to remember + the message IDs of the non-confirmable notifications it sends. + This may be challenging for a server with constrained resources. + However, since Reset messages are transmitted unreliably, the + client must be prepared that its Reset messages aren't received by + the server. A server thus can always pretend that a Reset message + rejecting a non-confirmable notification was lost. If a server + does this, it could accelerate cancellation by sending the + following notifications to that client in confirmable messages. + + A server that transmits notifications mostly in non-confirmable + messages MUST send a notification in a confirmable message instead of + a non-confirmable message at least every 24 hours. This prevents a + client that went away or is no longer interested from remaining in + the list of observers indefinitely. + +4.5.1. Congestion Control + + Basic congestion control for CoAP is provided by the exponential + back-off mechanism in Section 4.2 of RFC 7252 [RFC7252] and the + limitations in Section 4.7 of RFC 7252 [RFC7252]. However, CoAP + places the responsibility of congestion control for simple request/ + response interactions only on the clients: rate limiting request + transmission implicitly controls the transmission of the responses. + When a single request yields a potentially infinite number of + notifications, additional responsibility needs to be placed on the + server. + + In order not to cause congestion, servers MUST strictly limit the + number of simultaneous outstanding notifications/responses that they + transmit to a given client to NSTART (1 by default; see Section 4.7 + of RFC 7252 [RFC7252]). An outstanding notification/response is + either a confirmable message for which an acknowledgement has not yet + been received and whose last retransmission attempt has not yet timed + out, or a non-confirmable message for which the waiting time that + results from the following rate limiting rules has not yet elapsed. + + The server SHOULD NOT send more than one non-confirmable notification + per round-trip time (RTT) to a client on average. If the server + cannot maintain an RTT estimate for a client, it SHOULD NOT send more + than one non-confirmable notification every 3 seconds, and SHOULD use + an even less aggressive rate when possible (see also Section 3.1.2 of + RFC 5405 [RFC5405]). + + Further congestion control optimizations and considerations are + expected in the future with advanced CoAP congestion control + mechanisms. + + + +Hartke Expires July 3, 2015 [Page 16] + +Internet-Draft Observing Resources in CoAP December 2014 + + +4.5.2. Advanced Transmission + + The state of an observed resource may change while the number of the + number of simultaneous outstanding notifications/responses to a + client on the list of observers is greater than or equal to NSTART. + In this case, the server cannot notify the client of the new resource + state immediately but has to wait for an outstanding notification/ + response to complete first. + + If there exists an outstanding notification/response that the server + transmits to the client and that pertains to the changed resource, + then it is desirable for the server to stop working towards getting + the representation of the old resource state to the client, and to + start transmitting the current representation to the client instead, + so the resource state observed by the client stays closer in sync + with the actual state at the server. + + For this purpose, the server MAY optimize the transmission process by + aborting the transmission of the old notification (but not before the + current transmission attempt completed) and starting a new + transmission for the new notification (but with the retransmission + timer and counter of the aborted transmission retained). + + In more detail, a server MAY supersede an outstanding transmission + that pertains to an observation as follows: + + 1. Wait for the current (re-)transmission attempt to be + acknowledged, rejected or to time out (confirmable transmission); + or wait for the waiting time to elapse or the transmission to be + rejected (non-confirmable transmission). + + 2. If the transmission is rejected or it was the last attempt to + retransmit a notification, remove the associated entry from the + list of observers of the observed resource. + + 3. If the entry is still in the list of observers, start to transmit + a new notification with a representation of the current resource + state. Should the resource have changed its state more than once + in the meantime, the notifications for the intermediate states + are silently skipped. + + 4. The new notification is transmitted with a new Message ID and the + following transmission parameters: If the previous + (re-)transmission attempt timed out, retain its transmission + parameters, increment the retransmission counter and double the + timeout; otherwise, initialize the transmission parameters as + usual (see Section 4.2 of RFC 7252 [RFC7252]). + + + + +Hartke Expires July 3, 2015 [Page 17] + +Internet-Draft Observing Resources in CoAP December 2014 + + + It is possible that the server later receives an acknowledgement for + a confirmable notification that it superseded this way. Even though + this does not signal consistency, it is valuable in that it signals + the client's further interest in the resource. The server therefore + should avoid inadvertently removing the associated entry from the + list of observers. + +5. Intermediaries + + A client may be interested in a resource in the namespace of a server + that is reached through a chain of one or more CoAP intermediaries. + In this case, the client registers its interest with the first + intermediary towards the server, acting as if it was communicating + with the server itself, as specified in Section 3. It is the task of + this intermediary to provide the client with a current representation + of the target resource and to keep the representation updated upon + changes to the resource state, as specified in Section 4. + + To perform this task, the intermediary SHOULD make use of the + protocol specified in this document, taking the role of the client + and registering its own interest in the target resource with the next + hop towards the server. If the response returned by the next hop + doesn't include an Observe Option, the intermediary MAY resort to + polling the next hop or MAY itself return a response without an + Observe Option. + + The communication between each pair of hops is independent; each hop + in the server role MUST determine individually how many notifications + to send, of which message type, and so on. Each hop MUST generate + its own values for the Observe Option in notifications, and MUST set + the value of the Max-Age Option according to the age of the local + current representation. + + If two or more clients have registered their interest in a resource + with an intermediary, the intermediary MUST register itself only once + with the next hop and fan out the notifications it receives to all + registered clients. This relieves the next hop from sending the same + notifications multiple times and thus enables scalability. + + An intermediary is not required to act on behalf of a client to + observe a resource; an intermediary MAY observe a resource, for + example, just to keep its own cache up to date. + + See Appendix A.2 for examples. + + + + + + + +Hartke Expires July 3, 2015 [Page 18] + +Internet-Draft Observing Resources in CoAP December 2014 + + +6. Web Linking + + A web link [RFC5988] to a resource accessible over CoAP (for example, + in a link-format document [RFC6690]) MAY include the target attribute + "obs". + + The "obs" attribute, when present, is a hint indicating that the + destination of a link is useful for observation and thus, for + example, should have a suitable graphical representation in a user + interface. Note that this is only a hint; it is not a promise that + the Observe Option can actually be used to perform the observation. + A client may need to resort to polling the resource if the Observe + Option is not returned in the response to the GET request. + + A value MUST NOT be given for the "obs" attribute; any present value + MUST be ignored by parsers. The "obs" attribute MUST NOT appear more + than once in a given link-value; occurrences after the first MUST be + ignored by parsers. + +7. Security Considerations + + The security considerations in Section 11 of the CoAP specification + [RFC7252] apply. + + Observing resources can dramatically increase the negative effects of + amplification attacks. That is, not only can notifications messages + be much larger than the request message, but the nature of the + protocol can cause a significant number of notifications to be + generated. Without client authentication, a server therefore MUST + strictly limit the number of notifications that it sends between + receiving acknowledgements that confirm the actual interest of the + client in the data; i.e., any notifications sent in non-confirmable + messages MUST be interspersed with confirmable messages. (An + attacker may still spoof the acknowledgements if the confirmable + messages are sufficiently predictable.) + + The protocol follows a best-effort approach for keeping the state + observed by a client and the actual resource state at a server in + sync. This may have the client and the server become out of sync at + times. Depending on the sensitivity of the observed resource, + operating on an old state might be a security threat. The client + therefore must be careful not to use a representation after its Max- + Age expires, and the server must set the Max-Age Option to a sensible + value. + + As with any protocol that creates state, attackers may attempt to + exhaust the resources that the server has available for maintaining + the list of observers for each resource. Servers may want to apply + + + +Hartke Expires July 3, 2015 [Page 19] + +Internet-Draft Observing Resources in CoAP December 2014 + + + access controls to this creation of state. As degraded behavior, the + server can always fall back to processing the request as a normal GET + request (without an Observe Option) if it is unwilling or unable to + add a client to the list of observers of a resource, including if + system resources are exhausted or nearing exhaustion. + + Intermediaries must be careful to ensure that notifications cannot be + employed to create a loop. A simple way to break any loops is to + employ caches for forwarding notifications in intermediaries. + + Resources can be observed over DTLS-secured CoAP using any of the + security modes described in Section 9 of RFC 7252. The use of DTLS + is indicated by the "coaps" URI scheme. All notifications resulting + from a GET request with an Observe Option MUST be returned within the + same epoch of the same connection as the request. + +8. IANA Considerations + + The following entry is added to the CoAP Option Numbers registry: + + +--------+---------+-----------+ + | Number | Name | Reference | + +--------+---------+-----------+ + | 6 | Observe | [RFCXXXX] | + +--------+---------+-----------+ + + [Note to RFC Editor: Please replace XXXX with the RFC number of this + specification.] + +9. Acknowledgements + + Carsten Bormann was an original author of this draft and is + acknowledged for significant contribution to this document. + + Thanks to Daniele Alessandrelli, Jari Arkko, Peter A. Bigot, Angelo + P. Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank, + Bert Greevenbosch, Jeroen Hoebeke, Cullen Jennings, Matthias + Kovatsch, Barry Leiba, Salvatore Loreto, Charles Palmer, Akbar + Rahman, Zach Shelby, and Floris Van den Abeele for helpful comments + and discussions that have shaped the document. + + This work was supported in part by Klaus Tschira Foundation, Intel, + Cisco, and Nokia. + +10. References + + + + + + +Hartke Expires July 3, 2015 [Page 20] + +Internet-Draft Observing Resources in CoAP December 2014 + + +10.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. + + [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained + Application Protocol (CoAP)", RFC 7252, June 2014. + +10.2. Informative References + + [GOF] Gamma, E., Helm, R., Johnson, R., and J. Vlissides, + "Design Patterns: Elements of Reusable Object-Oriented + Software", Addison-Wesley, Reading, MA, USA, + November 1994. + + [REST] Fielding, R., "Architectural Styles and the Design of + Network-based Software Architectures", Ph.D. Dissertation, + University of California, Irvine, 2000, <http:// + www.ics.uci.edu/~fielding/pubs/dissertation/ + fielding_dissertation.pdf>. + + [RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982, + August 1996. + + [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines + for Application Designers", BCP 145, RFC 5405, + November 2008. + + [RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes + to an HTTP Resource", RFC 5989, October 2010. + + [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, + "Known Issues and Best Practices for the Use of Long + Polling and Streaming in Bidirectional HTTP", RFC 6202, + April 2011. + + [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link + Format", RFC 6690, August 2012. + + [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for + Constrained-Node Networks", RFC 7228, May 2014. + + [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol + (HTTP/1.1): Message Syntax and Routing", RFC 7230, + June 2014. + + + + +Hartke Expires July 3, 2015 [Page 21] + +Internet-Draft Observing Resources in CoAP December 2014 + + +Appendix A. Examples + +A.1. Client/Server Examples + + Observed CLIENT SERVER Actual + t State | | State + ____________ | | ____________ + 1 | | + 2 unknown | | 18.5 Cel + 3 +----->| Header: GET 0x41011633 + 4 | GET | Token: 0x4a + 5 | | Uri-Path: temperature + 6 | | Observe: 0 (register) + 7 | | + 8 | | + 9 ____________ |<-----+ Header: 2.05 0x61451633 + 10 | 2.05 | Token: 0x4a + 11 18.5 Cel | | Observe: 9 + 12 | | Max-Age: 15 + 13 | | Payload: "18.5 Cel" + 14 | | + 15 | | ____________ + 16 ____________ |<-----+ Header: 2.05 0x51457b50 + 17 | 2.05 | 19.2 Cel Token: 0x4a + 18 19.2 Cel | | Observe: 16 + 29 | | Max-Age: 15 + 20 | | Payload: "19.2 Cel" + 21 | | + + Figure 3: A client registers and receives one notification of the + current state and one of a new state upon a state change + + + + + + + + + + + + + + + + + + + + +Hartke Expires July 3, 2015 [Page 22] + +Internet-Draft Observing Resources in CoAP December 2014 + + + Observed CLIENT SERVER Actual + t State | | State + ____________ | | ____________ + 22 | | + 23 19.2 Cel | | 19.2 Cel + 24 | | ____________ + 25 | X----+ Header: 2.05 0x51457b51 + 26 | 2.05 | 19.7 Cel Token: 0x4a + 27 | | Observe: 25 + 28 | | Max-Age: 15 + 29 | | Payload: "19.7 Cel" + 30 | | + 31 ____________ | | + 32 | | + 33 19.2 Cel | | + 34 (stale) | | + 35 | | + 36 | | + 37 | | + 38 +----->| Header: GET 0x41011634 + 39 | GET | Token: 0xb2 + 40 | | Uri-Path: temperature + 41 | | Observe: 0 (register) + 42 | | + 43 | | + 44 ____________ |<-----+ Header: 2.05 0x61451634 + 45 | 2.05 | Token: 0xb2 + 46 19.7 Cel | | Observe: 44 + 47 | | Max-Age: 15 + 48 | | ETag: 0x78797a7a79 + 49 | | Payload: "19.7 Cel" + 50 | | + + Figure 4: The client re-registers after Max-Age ends + + + + + + + + + + + + + + + + + +Hartke Expires July 3, 2015 [Page 23] + +Internet-Draft Observing Resources in CoAP December 2014 + + + Observed CLIENT SERVER Actual + t State | | State + ____________ | | ____________ + 51 | | + 52 19.7 Cel | | 19.7 Cel + 53 | | + 54 | | ____________ + 55 | crash + 56 | + 57 | + 58 | + 59 ____________ | + 60 | + 61 19.7 Cel | + 62 (stale) | + 63 | reboot____________ + 64 | | + 65 | | 20.0 Cel + 66 | | + 67 +----->| Header: GET 0x41011635 + 68 | GET | Token: 0xf9 + 69 | | Uri-Path: temperature + 70 | | Observe: 0 (register) + 71 | | ETag: 0x78797a7a79 + 72 | | + 73 | | + 74 ____________ |<-----+ Header: 2.05 0x61451635 + 75 | 2.05 | Token: 0xf9 + 76 20.0 Cel | | Observe: 74 + 77 | | Max-Age: 15 + 78 | | Payload: "20.0 Cel" + 79 | | + 80 | | ____________ + 81 ____________ |<-----+ Header: 2.03 0x5143aa0c + 82 | 2.03 | 19.7 Cel Token: 0xf9 + 83 19.7 Cel | | Observe: 81 + 84 | | ETag: 0x78797a7a79 + 85 | | Max-Age: 15 + 86 | | + + Figure 5: The client re-registers and gives the server the + opportunity to select a stored response + + + + + + + + + +Hartke Expires July 3, 2015 [Page 24] + +Internet-Draft Observing Resources in CoAP December 2014 + + + Observed CLIENT SERVER Actual + t State | | State + ____________ | | ____________ + 87 | | + 88 19.7 Cel | | 19.7 Cel + 89 | | + 90 | | ____________ + 91 ____________ |<-----+ Header: 2.05 0x4145aa0f + 92 | 2.05 | 19.3 Cel Token: 0xf9 + 93 19.3 Cel | | Observe: 91 + 94 | | Max-Age: 15 + 95 | | Payload: "19.3 Cel" + 96 | | + 97 | | + 98 +- - ->| Header: 0x7000aa0f + 99 | | + 100 | | + 101 | | + 102 | | ____________ + 103 | | + 104 | | 19.0 Cel + 105 | | + 106 ____________ | | + 107 | | + 108 19.3 Cel | | + 109 (stale) | | + 110 | | + + Figure 6: The client rejects a notification and thereby cancels the + observation + + + + + + + + + + + + + + + + + + + + + +Hartke Expires July 3, 2015 [Page 25] + +Internet-Draft Observing Resources in CoAP December 2014 + + +A.2. Proxy Examples + + CLIENT PROXY SERVER + | | | + | +----->| Header: GET 0x41015fb8 + | | GET | Token: 0x1a + | | | Uri-Host: sensor.example + | | | Uri-Path: status + | | | Observe: 0 (register) + | | | + | |<-----+ Header: 2.05 0x61455fb8 + | | 2.05 | Token: 0x1a + | | | Observe: 42 + | | | Max-Age: 60 + | | | Payload: "ready" + | | | + +----->| | Header: GET 0x41011633 + | GET | | Token: 0x9a + | | | Proxy-Uri: coap://sensor.example/status + | | | + |<-----+ | Header: 2.05 0x61451633 + | 2.05 | | Token: 0x9a + | | | Max-Age: 53 + | | | Payload: "ready" + | | | + | |<-----+ Header: 2.05 0x514505fc0 + | | 2.05 | Token: 0x1a + | | | Observe: 135 + | | | Max-Age: 60 + | | | Payload: "busy" + | | | + +----->| | Header: GET 0x41011634 + | GET | | Token: 0x9b + | | | Proxy-Uri: coap://sensor.example/status + | | | + |<-----+ | Header: 2.05 0x61451634 + | 2.05 | | Token: 0x9b + | | | Max-Age: 49 + | | | Payload: "busy" + | | | + + Figure 7: A proxy observes a resource to keep its cache up to date + + + + + + + + + +Hartke Expires July 3, 2015 [Page 26] + +Internet-Draft Observing Resources in CoAP December 2014 + + + CLIENT PROXY SERVER + | | | + +----->| | Header: GET 0x41011635 + | GET | | Token: 0x6a + | | | Proxy-Uri: coap://sensor.example/status + | | | Observe: 0 (register) + | | | + |<- - -+ | Header: 0x60001635 + | | | + | +----->| Header: GET 0x4101af90 + | | GET | Token: 0xaa + | | | Uri-Host: sensor.example + | | | Uri-Path: status + | | | Observe: 0 (register) + | | | + | |<-----+ Header: 2.05 0x6145af90 + | | 2.05 | Token: 0xaa + | | | Observe: 67 + | | | Max-Age: 60 + | | | Payload: "ready" + | | | + |<-----+ | Header: 2.05 0x4145af94 + | 2.05 | | Token: 0x6a + | | | Observe: 17346 + | | | Max-Age: 60 + | | | Payload: "ready" + | | | + +- - ->| | Header: 0x6000af94 + | | | + | |<-----+ Header: 2.05 0x51455a20 + | | 2.05 | Token: 0xaa + | | | Observe: 157 + | | | Max-Age: 60 + | | | Payload: "busy" + | | | + |<-----+ | Header: 2.05 0x5145af9b + | 2.05 | | Token: 0x6a + | | | Observe: 17436 + | | | Max-Age: 60 + | | | Payload: "busy" + | | | + + Figure 8: A client observes a resource through a proxy + + + + + + + + +Hartke Expires July 3, 2015 [Page 27] + +Internet-Draft Observing Resources in CoAP December 2014 + + +Appendix B. Changelog + + [Note to RFC Editor: Please remove this section before publication.] + + Changes from ietf-15 to ietf-16: + + o Clarified several points based on AD, GenART, IESG, and Secdir + reviews. + + Changes from ietf-14 to ietf-15: + + o Clarified several points based on AD, GenART, IESG, and Secdir + reviews. + + Changes from ietf-13 to ietf-14: + + o Updated references. + + Changes from ietf-12 to ietf-13: + + o Extended the Observe Option in requests to not only add but also + remove an entry in the list of observers, depending on the option + value. + + Note: The value of the Observe Option in a registration request + may now be any sequence of bytes that encodes the unsigned + integer 0, i.e., 0x'', 0x'00', 0x'00 00' or 0x'00 00 00'. + + o Removed the 7.31 Code for cancellation. + + Changes from ietf-11 to ietf-12: + + o Introduced the 7.31 Code to request the cancellation of a pending + request. + + o Made the algorithm for superseding an outstanding transmission + OPTIONAL. + + o Clarified that the entry in the list of observers is removed if + the client fails to acknowledge a confirmable notification before + the last retransmission attempt times out (#350). + + o Simplified the text on cancellation (#352) and the handling of + Reset messages (#353). + + Changes from ietf-10 to ietf-11: + + + + + +Hartke Expires July 3, 2015 [Page 28] + +Internet-Draft Observing Resources in CoAP December 2014 + + + o Pointed out that client and server clocks may differ in their + realization of the SI second, and added robustness to the existing + reordering scheme by reducing the maximum notification rate to + 32768 notifications per second (#341). + + Changes from ietf-09 to ietf-10: + + o Required consistent sequence numbers across requests (#333). + + o Clarified that a server needs to update the entry in the list of + observers instead of adding a new entry if the endpoint/token pair + is already present. + + o Allowed that a client uses a token that is currently in use to + ensure that it's still in the list of observers. This is possible + because sequence numbers are now consistent across requests and + servers won't add a new entry for the same token. + + o Improved text on the transmission of non-confirmable notifications + to match Section 3.1.2 of RFC 5405 more closely. + + o Updated examples to use UCUM units. + + o Moved Appendix B into the introduction. + + Changes from ietf-08 to ietf-09: + + o Removed the side effects of requests on existing observations. + This includes removing that + + * the client can use a GET request to cancel an observation; + + * the server updates the entry in the list of observers instead + of adding a new entry if the client is already present (#258, + #281). + + o Clarified that a resource (and hence an observation relationship) + is identified by the request options that are part of the Cache- + Key (#258). + + o Clarified that a non-2.xx notification MUST NOT include an Observe + Option. + + o Moved block-wise transfer of notifications to [I-D.ietf-core- + block]. + + Changes from ietf-07 to ietf-08: + + + + +Hartke Expires July 3, 2015 [Page 29] + +Internet-Draft Observing Resources in CoAP December 2014 + + + o Expanded text on transmitting a notification while a previous + transmission is pending (#242). + + o Changed reordering detection to use a fixed time span of 128 + seconds instead of EXCHANGE_LIFETIME (#276). + + o Removed the use of the freshness model to determine if the client + is still on the list of observers. This includes removing that + + * the client assumes that it has been removed from the list of + observers when Max-Age ends; + + * the server sets the Max-Age Option of a notification to a value + that indicates when the server will send the next notification; + + * the server uses a number of retransmit attempts such that + removing a client from the list of observers before Max-Age + ends is avoided (#235); + + * the server may remove the client from all lists of observers + when the transmission of a confirmable notification ultimately + times out. + + o Changed that an unrecognized critical option in a request must + actually have no effect on the state of any observation + relationship to any resource, as the option could lead to a + different target resource. + + o Clarified that client implementations must be prepared to receive + each notification equally as a confirmable or a non-confirmable + message, regardless of the message type of the request and of any + previous notification. + + o Added a requirement for sending a confirmable notification at + least every 24 hours before continuing with non-confirmable + notifications (#221). + + o Added congestion control considerations from [I-D.bormann-core- + congestion-control-02]. + + o Recommended that the client waits for a randomized time after the + freshness of the latest notification expired before re- + registering. This prevents that multiple clients observing a + resource perform a GET request at the same time when the need to + re-register arises. + + o Changed reordering detection from 'MAY' to 'SHOULD', as the goal + of the protocol (to keep the observed state as closely in sync + + + +Hartke Expires July 3, 2015 [Page 30] + +Internet-Draft Observing Resources in CoAP December 2014 + + + with the actual state as possible) is not optional. + + o Fixed the length of the Observe Option (3 bytes) in the table in + Section 2. + + o Replaced the 'x' in the No-Cache-Key column in the table in + Section 2 with a '-', as the Observe Option doesn't have the No- + Cache-Key flag set, even though it is not part of the cache key. + + o Updated examples. + + Changes from ietf-06 to ietf-07: + + o Moved to 24-bit sequence numbers to allow for up to 15000 + notifications per second per client and resource (#217). + + o Re-numbered option number to use Unsafe/Safe and Cache-Key + compliant numbers (#241). + + o Clarified how to react to a Reset message that is sent in reply to + a non-confirmable notification (#225). + + o Clarified the semantics of the "obs" link target attribute (#236). + + Changes from ietf-05 to ietf-06: + + o Improved abstract and introduction to say that the protocol is + about best effort and eventual consistency (#219). + + o Clarified that the value of the Observe Option in a request must + have zero length. + + o Added requirement that the sequence number must be updated each + time a server retransmits a notification. + + o Clarified that a server must remove a client from the list of + observers when it receives a GET request with an unrecognized + critical option. + + o Updated the text to use the endpoint concept from [I-D.ietf-core- + coap] (#224). + + o Improved the reordering text (#223). + + Changes from ietf-04 to ietf-05: + + o Recommended that a client does not re-register while a new + notification from the server is still likely to arrive. This is + + + +Hartke Expires July 3, 2015 [Page 31] + +Internet-Draft Observing Resources in CoAP December 2014 + + + to avoid that the request of the client and the last notification + after max-age cross over each other (#174). + + o Relaxed requirements when sending a Reset message in reply to non- + confirmable notifications. + + o Added an implementation note about careless GET requests (#184). + + o Updated examples. + + Changes from ietf-03 to ietf-04: + + o Removed the "Max-OFE" Option. + + o Allowed a Reset message in reply to non-confirmable notifications. + + o Added a section on cancellation. + + o Updated examples. + + Changes from ietf-02 to ietf-03: + + o Separated client-side and server-side requirements. + + o Fixed uncertainty if client is still on the list of observers by + introducing a liveliness model based on Max-Age and a new option + called "Max-OFE" (#174). + + o Simplified the text on message reordering (#129). + + o Clarified requirements for intermediaries. + + o Clarified the combination of blockwise transfers with + notifications (#172). + + o Updated examples to show how the state observed by the client + becomes eventually consistent with the actual state on the server. + + o Added examples for parameterization of observable resource. + + Changes from ietf-01 to ietf-02: + + o Removed the requirement of periodic refreshing (#126). + + o The new "Observe" Option replaces the "Lifetime" Option. + + o Introduced a new mechanism to detect message reordering. + + + + +Hartke Expires July 3, 2015 [Page 32] + +Internet-Draft Observing Resources in CoAP December 2014 + + + o Changed 2.00 (OK) notifications to 2.05 (Content) notifications. + + Changes from ietf-00 to ietf-01: + + o Changed terminology from "subscriptions" to "observation + relationships" (#33). + + o Changed the name of the option to "Lifetime". + + o Clarified establishment of observation relationships. + + o Clarified that an observation is only identified by the URI of the + observed resource and the identity of the client (#66). + + o Clarified rules for establishing observation relationships (#68). + + o Clarified conditions under which an observation relationship is + terminated. + + o Added explanation on how clients can terminate an observation + relationship before the lifetime ends (#34). + + o Clarified that the overriding objective for notifications is + eventual consistency of the actual and the observed state (#67). + + o Specified how a server needs to deal with clients not + acknowledging confirmable messages carrying notifications (#69). + + o Added a mechanism to detect message reordering (#35). + + o Added an explanation of how notifications can be cached, + supporting both the freshness and the validation model (#39, #64). + + o Clarified that non-GET requests do not affect observation + relationships, and that GET requests without "Lifetime" Option + affecting relationships is by design (#65). + + o Described interaction with blockwise transfers (#36). + + o Added Resource Discovery section (#99). + + o Added IANA Considerations. + + o Added Security Considerations (#40). + + o Added examples (#38). + + + + + +Hartke Expires July 3, 2015 [Page 33] + +Internet-Draft Observing Resources in CoAP December 2014 + + +Author's Address + + Klaus Hartke + Universitaet Bremen TZI + Postfach 330440 + Bremen D-28359 + Germany + + Phone: +49-421-218-63905 + EMail: hartke@tzi.org + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Hartke Expires July 3, 2015 [Page 34] + |