idnits 2.17.1 draft-ietf-core-observe-15.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 27, 2014) is 3468 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFCXXXX' is mentioned on line 923, but not defined ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) -- Obsolete informational reference (is this intentional?): RFC 5405 (Obsoleted by RFC 8085) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group K. Hartke 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Standards Track October 27, 2014 5 Expires: April 30, 2015 7 Observing Resources in CoAP 8 draft-ietf-core-observe-15 10 Abstract 12 The Constrained Application Protocol (CoAP) is a RESTful application 13 protocol for constrained nodes and networks. The state of a resource 14 on a CoAP server can change over time. This document specifies a 15 simple protocol extension for CoAP that enables CoAP clients to 16 "observe" resources, i.e., to retrieve a representation of a resource 17 and keep this representation updated by the server over a period of 18 time. The protocol follows a best-effort approach for sending new 19 representations to clients and provides eventual consistency between 20 the state observed by each client and the actual resource state at 21 the server. 23 Status of This Memo 25 This Internet-Draft is submitted in full conformance with the 26 provisions of BCP 78 and BCP 79. 28 Internet-Drafts are working documents of the Internet Engineering 29 Task Force (IETF). Note that other groups may also distribute 30 working documents as Internet-Drafts. The list of current Internet- 31 Drafts is at http://datatracker.ietf.org/drafts/current/. 33 Internet-Drafts are draft documents valid for a maximum of six months 34 and may be updated, replaced, or obsoleted by other documents at any 35 time. It is inappropriate to use Internet-Drafts as reference 36 material or to cite them other than as "work in progress." 38 This Internet-Draft will expire on April 30, 2015. 40 Copyright Notice 42 Copyright (c) 2014 IETF Trust and the persons identified as the 43 document authors. All rights reserved. 45 This document is subject to BCP 78 and the IETF Trust's Legal 46 Provisions Relating to IETF Documents 47 (http://trustee.ietf.org/license-info) in effect on the date of 48 publication of this document. Please review these documents 49 carefully, as they describe your rights and restrictions with respect 50 to this document. Code Components extracted from this document must 51 include Simplified BSD License text as described in Section 4.e of 52 the Trust Legal Provisions and are provided without warranty as 53 described in the Simplified BSD License. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.1. Background . . . . . . . . . . . . . . . . . . . . . . . . 3 59 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 3 60 1.3. Consistency Model . . . . . . . . . . . . . . . . . . . . 5 61 1.4. Observable Resources . . . . . . . . . . . . . . . . . . . 6 62 1.5. Requirements Notation . . . . . . . . . . . . . . . . . . 7 63 2. The Observe Option . . . . . . . . . . . . . . . . . . . . . . 7 64 3. Client-side Requirements . . . . . . . . . . . . . . . . . . . 8 65 3.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 8 66 3.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 8 67 3.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 3.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 10 69 3.5. Transmission . . . . . . . . . . . . . . . . . . . . . . . 11 70 3.6. Cancellation . . . . . . . . . . . . . . . . . . . . . . . 11 71 4. Server-side Requirements . . . . . . . . . . . . . . . . . . . 12 72 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 12 73 4.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 13 74 4.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 13 75 4.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 14 76 4.5. Transmission . . . . . . . . . . . . . . . . . . . . . . . 15 77 5. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 18 78 6. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 19 79 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 80 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 81 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 20 82 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 21 83 10.1. Normative References . . . . . . . . . . . . . . . . . . . 21 84 10.2. Informative References . . . . . . . . . . . . . . . . . . 21 85 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 22 86 A.1. Client/Server Examples . . . . . . . . . . . . . . . . . . 22 87 A.2. Proxy Examples . . . . . . . . . . . . . . . . . . . . . . 26 88 Appendix B. Changelog . . . . . . . . . . . . . . . . . . . . . . 28 90 1. Introduction 92 1.1. Background 94 The Constrained Application Protocol (CoAP) [RFC7252] is intended to 95 provide RESTful services [REST] not unlike HTTP [RFC7230] while 96 reducing the complexity of implementation as well as the size of 97 packets exchanged in order to make these services useful in a highly 98 constrained network of themselves highly constrained nodes [RFC7228]. 100 The model of REST is that of a client exchanging representations of 101 resources with a server, where a representation captures the current 102 or intended state of a resource and the server is the authority for 103 representations of the resources in its namespace. A client 104 interested in the state of a resource initiates a request to the 105 server; the server then returns a response with a representation of 106 the resource that is current at the time of the request. 108 This model does not work well when a client is interested in having a 109 current representation of a resource over a period of time. Existing 110 approaches from HTTP, such as repeated polling or HTTP long polling 111 [RFC6202], generate significant complexity and/or overhead and thus 112 are less applicable in a constrained environment. 114 The protocol specified in this document extends the CoAP core 115 protocol with a mechanism for a CoAP client to "observe" a resource 116 on a CoAP server: the client retrieves a representation of the 117 resource and requests this representation be updated by the server 118 as long as the client is interested in the resource. 120 The protocol keeps the architectural properties of REST. It enables 121 high scalability and efficiency through the support of caches and 122 proxies. There is no intention, though, to solve the full set of 123 problems that the existing HTTP solutions solve, or to replace 124 publish/subscribe networks that solve a much more general problem 125 [RFC5989]. 127 1.2. Protocol Overview 129 The protocol is based on the well-known observer design pattern 130 [GOF]. In this design pattern, components called "observers" 131 register at a specific, known provider called the "subject" that they 132 are interested in being notified whenever the subject undergoes a 133 change in state. The subject is responsible for administering its 134 list of registered observers. If multiple subjects are of interest 135 to an observer, the observer must register separately for all of 136 them. 138 Observer Subject 139 | | 140 | Registration | 141 +------------------->| 142 | | 143 | Notification | 144 |<-------------------+ 145 | | 146 | Notification | 147 |<-------------------+ 148 | | 149 | Notification | 150 |<-------------------+ 151 | | 153 Figure 1: The Observer Design Pattern 155 The observer design pattern is realized in CoAP as follows: 157 Subject: In the context of CoAP, the subject is a resource in the 158 namespace of a CoAP server. The state of the resource can change 159 over time, ranging from infrequent updates to continuous state 160 transformations. 162 Observer: An observer is a CoAP client that is interested in having 163 a current representation of the resource at any given time. 165 Registration: A client registers its interest in a resource by 166 initiating an extended GET request to the server. In addition to 167 returning a representation of the target resource, this request 168 causes the server to add the client to the list of observers of 169 the resource. 171 Notification: Whenever the state of a resource changes, the server 172 notifies each client in the list of observers of the resource. 173 Each notification is an additional CoAP response sent by the 174 server in reply to the single extended GET request, and includes a 175 complete, updated representation of the new resource state. 177 Figure 2 below shows an example of a CoAP client registering its 178 interest in a resource and receiving three notifications: the first 179 with the current state upon registration, and then two upon changes 180 to the resource state. Both the registration request and the 181 notifications are identified as such by the presence of the Observe 182 Option defined in this document. In notifications, the Observe 183 Option additionally provides a sequence number for reordering 184 detection. All notifications carry the token specified by the 185 client, so the client can easily correlate them to the request. 187 Client Server 188 | | 189 | GET /temperature | 190 | Token: 0x4a | Registration 191 | Observe: register | 192 +------------------->| 193 | | 194 | 2.05 Content | 195 | Token: 0x4a | Notification of 196 | Observe: 12 | the current state 197 | Payload: 22.9 Cel | 198 |<-------------------+ 199 | | 200 | 2.05 Content | 201 | Token: 0x4a | Notification upon 202 | Observe: 44 | a state change 203 | Payload: 22.8 Cel | 204 |<-------------------+ 205 | | 206 | 2.05 Content | 207 | Token: 0x4a | Notification upon 208 | Observe: 60 | a state change 209 | Payload: 23.1 Cel | 210 |<-------------------+ 211 | | 213 Figure 2: Observing a Resource in CoAP 215 A client remains on the list of observers as long as the server can 216 determine the client's continued interest in the resource. The 217 server may send a notification in a confirmable CoAP message to 218 request an acknowledgement by the client. When the client 219 deregisters, rejects a notification, or the transmission of a 220 notification times out after several transmission attempts, the 221 client is considered no longer interested and is removed by the 222 server from the list of observers. 224 1.3. Consistency Model 226 While a client is in the list of observers of a resource, the goal of 227 the protocol is to keep the resource state observed by the client as 228 closely in sync with the actual state at the server as possible. 230 It cannot be avoided that the client and the server become out of 231 sync at times: First, there is always some latency between the change 232 of the resource state and the receipt of the notification. Second, 233 CoAP messages with notifications can get lost, which will cause the 234 client to assume an old state until it receives a new notification. 236 And third, the server may erroneously come to the conclusion that the 237 client is no longer interested in the resource, which will cause the 238 server to stop sending notifications and the client to assume an old 239 state until it eventually registers its interest again. 241 The protocol addresses this issue as follows: 243 o It follows a best-effort approach for sending the current 244 representation to the client after a state change: Clients should 245 see the new state after a state change as soon as possible, and 246 they should see as many states as possible. This is limited by 247 congestion control, however, so a client cannot rely on observing 248 every single state that a resource might go through. 250 o It labels notifications with a maximum duration up to which it is 251 acceptable for the observed state and the actual state to be out 252 of sync. When the age of the notification received reaches this 253 limit, the client cannot use the enclosed representation until it 254 receives a new notification. 256 o It is designed on the principle of eventual consistency: The 257 protocol guarantees that, if the resource does not undergo a new 258 change in state, eventually all registered observers will have a 259 current representation of the latest resource state. 261 1.4. Observable Resources 263 A CoAP server is the authority for determining under what conditions 264 resources change their state and thus when observers are notified of 265 new resource states. The protocol does not offer explicit means for 266 setting up triggers or thresholds; it is up to the server to expose 267 observable resources that change their state in a way that is useful 268 in the application context. 270 For example, a CoAP server with an attached temperature sensor could 271 expose one or more of the following resources: 273 o , which changes its state every few 274 seconds to a current reading of the temperature sensor; 276 o , which changes its state to 277 "COLD" whenever the temperature reading drops below a certain pre- 278 configured threshold, and to "WARM" whenever the reading exceeds a 279 second, slightly higher threshold; 281 o , which changes its 282 state based on the client-specified parameter value: every few 283 seconds to the current temperature reading if the temperature 284 exceeds the threshold, or to "OK" when the reading drops below; 286 o , which accepts expressions of arbitrary complexity 288 and changes its state accordingly. 290 Thus, by designing CoAP resources that change their state on certain 291 conditions, it is possible to update the client only when these 292 conditions occur instead of supplying it continuously with raw sensor 293 data. By parameterizing resources, this is not limited to conditions 294 defined by the server, but can be extended to arbitrarily complex 295 queries specified by the client. The application designer therefore 296 can choose exactly the right level of complexity for the application 297 envisioned and devices involved, and is not constrained to a "one 298 size fits all" mechanism built into the protocol. 300 1.5. Requirements Notation 302 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 303 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 304 document are to be interpreted as described in RFC 2119 [RFC2119]. 306 2. The Observe Option 308 +-----+---+---+---+---+---------+--------+--------+---------+ 309 | No. | C | U | N | R | Name | Format | Length | Default | 310 +-----+---+---+---+---+---------+--------+--------+---------+ 311 | 6 | | x | - | | Observe | uint | 0-3 B | (none) | 312 +-----+---+---+---+---+---------+--------+--------+---------+ 314 C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable 316 Table 1: The Observe Option 318 The Observe Option, when present in a request, extends the GET method 319 so it does not only retrieve a current representation of the target 320 resource, but also requests the server to add or remove an entry in 321 the list of observers of the resource, where the entry consists of 322 the client endpoint and the token specified in the request. 324 'register' (0) adds the entry to the list, if not present; 326 'deregister' (1) removes the entry from the list, if present. 328 The Observe Option is not critical for processing the request. If 329 the server is unwilling or unable to add a new entry to the list of 330 observers, then the request falls back to a normal GET request, and 331 the response does not include the Observe Option. 333 In a response, the Observe Option identifies the message as a 334 notification. This implies that the server has added an entry with 335 the client endpoint and request token to the list of observers and 336 that it will notify the client of changes to the resource state. The 337 option value is a 24-bit sequence number for reordering detection 338 (see Section 3.4 and Section 4.4). 340 The value of the Observe Option is encoded as an unsigned integer in 341 network byte order using a variable number of bytes ('uint' option 342 format); see Section 3.2 of RFC 7252 [RFC7252]. 344 The Observe Option is not part of the cache-key: a cacheable response 345 obtained with an Observe Option in the request can be used to satisfy 346 a request without an Observe Option, and vice versa. When a stored 347 response with an Observe Option is used to satisfy a normal GET 348 request, the option MUST be removed before the response is returned. 350 3. Client-side Requirements 352 3.1. Request 354 A client registers its interest in a resource by issuing a GET 355 request with an Observe Option set to 'register' (0). If the server 356 returns a 2.xx response that includes an Observe Option as well, the 357 server has successfully added an entry with the client endpoint and 358 request token to the list of observers of the target resource and the 359 client will be notified of changes to the resource state. 361 Like a fresh response can be used to satisfy a request without 362 contacting the server, the stream of updates resulting from one 363 observation request can be used to satisfy another (observation or 364 normal GET) request if the target resource is the same. A client 365 MUST aggregate such requests and MUST NOT register more than once for 366 the same target resource. The target resource is identified by all 367 options in the request that are part of the cache-key. This 368 includes, for example, the full request URI and the Accept Option. 370 3.2. Notifications 372 Notifications are additional responses sent by the server in reply to 373 the single extended GET request that created the registration. Each 374 notification includes the token specified by the client in the 375 request. The only difference between a notification and a normal 376 response is the presence of the Observe Option. 378 Notifications typically have a 2.05 (Content) response code. They 379 include an Observe Option with a sequence number for reordering 380 detection (see Section 3.4), and a payload in the same Content-Format 381 as the initial response. If the client included one or more ETag 382 Options in the GET request (see Section 3.3), notifications can have 383 a 2.03 (Valid) response code rather than a 2.05 (Content) response 384 code. Such notifications include an Observe Option with a sequence 385 number but no payload. 387 In the event that the resource changes in a way that would cause a 388 normal GET request at that time to return a non-2.xx response (for 389 example, when the resource is deleted), the server sends a 390 notification with an appropriate response code (such as 4.04 Not 391 Found) and removes the client's entry from the list of observers of 392 the resource. Non-2.xx responses do not include an Observe Option. 394 3.3. Caching 396 As notifications are just additional responses to a GET request, 397 notifications partake in caching as defined in Section 5.6 of RFC 398 7252 [RFC7252]. Both the freshness model and the validation model 399 are supported. 401 3.3.1. Freshness 403 A client MAY store a notification like a response in its cache and 404 use a stored notification that is fresh without contacting the 405 server. Like a response, a notification is considered fresh while 406 its age is not greater than the value indicated by the Max-Age Option 407 (and no newer notification/response has been received). 409 The server will do its best to keep the resource state observed by 410 the client as closely in sync with the actual state as possible. 411 However, a client cannot rely on observing every single state that a 412 resource might go through. For example, if the network is congested 413 or the state changes more frequently than the network can handle, the 414 server can skip notifications for any number of intermediate states. 416 The server uses the Max-Age Option to indicate an age up to which it 417 is acceptable that the observed state and the actual state are 418 inconsistent. If the age of the latest notification becomes greater 419 than its indicated Max-Age, then the client MUST NOT assume that the 420 enclosed representation reflects the actual resource state. 422 To make sure it has a current representation and/or to re-register 423 its interest in a resource, a client MAY issue a new GET request with 424 the same token as the original at any time. All options MUST be 425 identical to those in the original request, except for the set of 426 ETag Options. It is RECOMMENDED that the client does not issue the 427 request while it still has a fresh notification/response for the 428 resource in its cache. Additionally, the client SHOULD at least wait 429 for a random amount of time between 5 and 15 seconds after Max-Age 430 expired to reduce collisions with other clients. 432 3.3.2. Validation 434 When a client has one or more notifications stored in its cache for a 435 resource, it can use the ETag Option in the GET request to give the 436 server an opportunity to select a stored notification to be used. 438 The client MAY include an ETag Option for each stored response that 439 is applicable in the GET request. Whenever the observed resource 440 changes to a representation identified by one of the ETag Options, 441 the server can select a stored response by sending a 2.03 (Valid) 442 notification with an appropriate ETag Option instead of a 2.05 443 (Content) notification. 445 A client implementation needs to keep all candidate responses in its 446 cache until it is no longer interested in the target resource or it 447 re-registers with a new set of entity-tags. 449 3.4. Reordering 451 Messages with notifications can arrive in a different order than they 452 were sent. Since the goal is to keep the observed state as closely 453 in sync with the actual state as possible, a client MUST consider the 454 notification that was sent most recently as the freshest, regardless 455 of the order of arrival. 457 To provide an order among notifications for the client, the server 458 sets the value of the Observe Option in each notification to the 24 459 least-significant bits of a strictly increasing sequence number. An 460 incoming notification was sent more recently than the freshest 461 notification so far when one of the following conditions is met: 463 (V1 < V2 and V2 - V1 < 2^23) or 464 (V1 > V2 and V1 - V2 > 2^23) or 465 (T2 > T1 + 128 seconds) 467 where V1 is the value of the Observe Option in the freshest 468 notification so far, V2 the value of the Observe Option in the 469 incoming notification, T1 a client-local timestamp for the freshest 470 notification so far, and T2 a client-local timestamp for the incoming 471 notification. 473 Design Note: The first two conditions verify that V1 is less than V2 474 in 24-bit serial number arithmetic [RFC1982]. The third condition 475 ensures that the time elapsed between the two incoming messages is 476 not so large that the difference between V1 and V2 has become 477 larger than the largest integer that it is meaningful to add to a 478 24-bit serial number; in other words, after 128 seconds have 479 elapsed without any notification, a client does not need to check 480 the sequence numbers to assume that an incoming notification was 481 sent more recently than the freshest notification it has received 482 so far. 484 The duration of 128 seconds was chosen as a nice round number 485 greater than MAX_LATENCY (Section 4.8.2 of RFC 7252 [RFC7252]). 487 3.5. Transmission 489 A notification can be confirmable or non-confirmable, i.e., it can be 490 sent in a confirmable or a non-confirmable message. The message type 491 used for a notification is independent of the type used for the 492 request and of any previous notification. 494 If a client does not recognize the token in a confirmable 495 notification, it MUST NOT acknowledge the message and SHOULD reject 496 it with a Reset message; otherwise, the client MUST acknowledge the 497 message as usual. In the case of a non-confirmable notification, 498 rejecting the message with a Reset message is OPTIONAL. 500 An acknowledgement message signals to the server that the client is 501 alive and interested in receiving further notifications; if the 502 server does not receive an acknowledgement in reply to a confirmable 503 notification, it will assume that the client is no longer interested 504 and will eventually remove the associated entry from the list of 505 observers. 507 3.6. Cancellation 509 A client that is no longer interested in receiving notifications for 510 a resource can simply "forget" the observation. When the server then 511 sends the next notification, the client will not recognize the token 512 in the message and thus will return a Reset message. This causes the 513 server to remove the associated entry from the list of observers. 514 The entries in lists of observers are effectively "garbage collected" 515 by the server. 517 Implementation Note: Due to potential message loss, the Reset 518 message may not reach the server. The client may therefore have 519 to reject multiple notifications, each with one Reset message, 520 until the server finally removes the associated entry from the 521 list of observers and stops sending notifications. 523 In some circumstances, it may be desirable to cancel an observation 524 and release the resources allocated by the server to it more eagerly. 525 In this case, a client MAY explicitly deregister by issuing a GET 526 request which has the Token field set to the token of the observation 527 to be cancelled and includes an Observe Option with the value set to 528 'deregister' (1). All other options MUST be identical to those in 529 the registration request, except for the set of ETag Options. When 530 the server receives such a request, it will remove any matching entry 531 from the list of observers and process the GET request as usual. 533 4. Server-side Requirements 535 4.1. Request 537 A GET request with an Observe Option set to 'register' (0) requests 538 the server not only to return a current representation of the target 539 resource, but also to add the client to the list of observers of that 540 resource. Upon success, the server returns a current representation 541 of the resource and MUST keep this representation updated (as 542 described in Section 1.3) as long as the client is on the list of 543 observers. 545 The entry in the list of observers is keyed by the client endpoint 546 and the token specified by the client in the request. If an entry 547 with a matching endpoint/token pair is already present in the list 548 (which, for example, happens when the client wishes to reinforce its 549 interest in a resource), the server MUST NOT add a new entry but MUST 550 replace or update the existing one. 552 A server that is unable or unwilling to add a new entry to the list 553 of observers of a resource MAY silently ignore the registration 554 request and process the GET request as usual. The resulting response 555 MUST NOT include an Observe Option, the absence of which signals to 556 the client that it will not be notified of changes to the resource 557 and, e.g., needs to poll the resource for its state instead. 559 If the Observe Option in a request is set to any other value than 560 'register' (0), then the server MUST remove any entry with a matching 561 endpoint/token pair from the list of observers and process the GET 562 request as usual. The resulting response MUST NOT include an Observe 563 Option. 565 4.2. Notifications 567 A client is notified of changes to the resource state by additional 568 responses sent by the server in reply to the GET request. Each such 569 notification response (including the initial response) MUST echo the 570 token specified by the client in the GET request. If there are 571 multiple entries in the list of observers, the order in which the 572 clients are notified is not defined; the server is free to use any 573 method to determine the order. 575 A notification SHOULD have a 2.05 (Content) or 2.03 (Valid) response 576 code. However, in the event that the state of a resource changes in 577 a way that would cause a normal GET request at that time to return a 578 non-2.xx response (for example, when the resource is deleted), the 579 server SHOULD notify the client by sending a notification with an 580 appropriate response code (such as 4.04 Not Found) and subsequently 581 MUST remove the associated entry from the list of observers of the 582 resource. 584 The Content-Format specified in a 2.xx notification MUST be the same 585 as the one used in the initial response to the GET request. If the 586 server is unable to continue sending notifications in this format, it 587 SHOULD send a notification with a 4.06 (Not Acceptable) response code 588 and subsequently MUST remove the associated entry from the list of 589 observers of the resource. 591 A 2.xx notification MUST include an Observe Option with a sequence 592 number as specified in Section 4.4 below; a non-2.xx notification 593 MUST NOT include an Observe Option. 595 4.3. Caching 597 As notifications are just additional responses sent by the server in 598 reply to a GET request, they are subject to caching as defined in 599 Section 5.6 of RFC 7252 [RFC7252]. 601 4.3.1. Freshness 603 After returning the initial response, the server MUST keep the 604 resource state that is observed by the client as closely in sync with 605 the actual resource state as possible. 607 Since becoming out of sync at times cannot be avoided, the server 608 MUST indicate for each representation an age up to which it is 609 acceptable that the observed state and the actual state are 610 inconsistent. This age is application-dependent and MUST be 611 specified in notifications using the Max-Age Option. 613 When the resource does not change and the client has a current 614 representation, the server does not need to send a notification. 615 However, if the client does not receive a notification, the client 616 cannot tell if the observed state and the actual state are still in 617 sync. Thus, when the age of the latest notification becomes greater 618 than its indicated Max-Age, the client no longer has a usable 619 representation of the resource state. The server MAY wish to prevent 620 that by sending a new notification with the unchanged representation 621 and a new Max-Age just before the Max-Age indicated earlier expires. 623 4.3.2. Validation 625 A client can include a set of entity-tags in its request using the 626 ETag Option. When a observed resource changes its state and the 627 origin server is about to send a 2.05 (Content) notification, then, 628 whenever that notification has an entity-tag in the set of entity- 629 tags specified by the client, the server MAY send a 2.03 (Valid) 630 response with an appropriate ETag Option instead. 632 4.4. Reordering 634 Because messages can get reordered, the client needs a way to 635 determine if a notification arrived later than a newer notification. 636 For this purpose, the server MUST set the value of the Observe Option 637 of each notification it sends to the 24 least-significant bits of a 638 strictly increasing sequence number. The sequence number MAY start 639 at any value and MUST NOT increase so fast that it increases by more 640 than 2^23 within less than 256 seconds. 642 The sequence number selected for a notification MUST be greater than 643 that of any preceding notification sent to the same client with the 644 same token for the same resource. The value of the Observe Option 645 MUST be current at the time of transmission; if a notification is 646 retransmitted, the server MUST update the value of the option to the 647 sequence number that is current at that time before retransmission. 649 Implementation Note: A simple implementation that satisfies the 650 requirements is to obtain a timestamp from a local clock. The 651 sequence number then is the timestamp in ticks, where 1 tick = 652 (256 seconds)/(2^23) = 30.52 microseconds. It is not necessary 653 that the clock reflects the current time/date. 655 Another valid implementation is to store a 24-bit unsigned integer 656 variable per resource and increment this variable each time the 657 resource undergoes a change of state (provided that the resource 658 changes its state less than 2^23 times in the first 256 seconds 659 after every state change). This removes the need to update the 660 value of the Observe Option on retransmission when the resource 661 state did not change. 663 Design Note: The choice of a 24-bit option value and a time span of 664 256 seconds theoretically allows for a notification rate of up to 665 65536 notifications per second. Constrained nodes often have 666 rather imprecise clocks, though, and inaccuracies of the client 667 and server side may cancel out or add in effect. Therefore, the 668 maximum notification rate is reduced to 32768 notifications per 669 second. This is still well beyond the highest known design 670 objective of around 1 kHz (most CoAP applications will be several 671 orders of magnitude below that), but allows total clock 672 inaccuracies of up to -50/+100 %. 674 4.5. Transmission 676 A notification can be sent in a confirmable or a non-confirmable 677 message. The message type used is typically application-dependent 678 and may be determined by the server for each notification 679 individually. 681 For example, for resources that change in a somewhat predictable or 682 regular fashion, notifications can be sent in non-confirmable 683 messages; for resources that change infrequently, notifications can 684 be sent in confirmable messages. The server can combine these two 685 approaches depending on the frequency of state changes and the 686 importance of individual notifications. 688 A server MAY choose to skip sending a notification if it knows that 689 it will send another notification soon, for example, when the state 690 of a resource is changing frequently. It also MAY choose to send 691 more than one notification for the same resource state. However, 692 above all, the server MUST ensure that a client in the list of 693 observers of a resource eventually observes the latest state if the 694 resource does not undergo a new change in state. 696 For example, when state changes occur in bursts, the server can skip 697 some notifications, send the notifications in non-confirmable 698 messages, and make sure that the client observes the latest state 699 change by repeating the last notification in a confirmable message 700 when the burst is over. 702 The client's acknowledgement of a confirmable notification signals 703 that the client is interested in receiving further notifications. If 704 a client rejects a confirmable or non-confirmable notification with a 705 Reset message, or if the last attempt to retransmit a confirmable 706 notification times out, then the client is considered no longer 707 interested and the server MUST remove the associated entry from the 708 list of observers. 710 Implementation Note: To properly process a Reset message that 711 rejects a non-confirmable notification, a server needs to remember 712 the message IDs of the non-confirmable notifications it sends. 713 This may be challenging for a server with constrained resources. 714 However, since Reset messages are transmitted unreliably, the 715 client must be prepared that its Reset messages aren't received by 716 the server. A server thus can always pretend that a Reset message 717 rejecting a non-confirmable notification was lost. If a server 718 does this, it could accelerate cancellation by sending the 719 following notifications to that client in confirmable messages. 721 A server that transmits notifications mostly in non-confirmable 722 messages MUST send a notification in a confirmable message instead of 723 a non-confirmable message at least every 24 hours. This prevents a 724 client that went away or is no longer interested from remaining in 725 the list of observers indefinitely. 727 4.5.1. Congestion Control 729 Basic congestion control for CoAP is provided by the exponential 730 back-off mechanism in Section 4.2 of RFC 7252 [RFC7252] and the 731 limitations in Section 4.7 of RFC 7252 [RFC7252]. However, CoAP 732 places the responsibility of congestion control for simple request/ 733 response interactions only on the clients: rate limiting request 734 transmission implicitly controls the transmission of the responses. 735 When a single request yields a potentially infinite number of 736 notifications, additional responsibility needs to be placed on the 737 server. 739 In order not to cause congestion, servers MUST strictly limit the 740 number of simultaneous outstanding notifications/responses that they 741 transmit to a given client to NSTART (1 by default; see Section 4.7 742 of RFC 7252 [RFC7252]). An outstanding notification/response is 743 either a confirmable message for which an acknowledgement has not yet 744 been received and whose last retransmission attempt has not yet timed 745 out, or a non-confirmable message for which the waiting time that 746 results from the following rate limiting rules has not yet elapsed. 748 The server SHOULD NOT send more than one non-confirmable notification 749 per round-trip time (RTT) to a client on average. If the server 750 cannot maintain an RTT estimate for a client, it SHOULD NOT send more 751 than one non-confirmable notification every 3 seconds, and SHOULD use 752 an even less aggressive rate when possible (see also Section 3.1.2 of 753 RFC 5405 [RFC5405]). 755 Further congestion control optimizations and considerations are 756 expected in the future with advanced CoAP congestion control 757 mechanisms. 759 4.5.2. Advanced Transmission 761 The state of an observed resource may change while the number of the 762 number of simultaneous outstanding notifications/responses to a 763 client on the list of observers is greater than or equal to NSTART. 764 In this case, the server cannot notify the client of the new resource 765 state immediately but has to wait for an outstanding notification/ 766 response to complete first. 768 If there exists an outstanding notification/response that the server 769 transmits to the client and that pertains to the changed resource, 770 then it is desirable for the server to stop working towards getting 771 the representation of the old resource state to the client, and to 772 start transmitting the current representation to the client instead, 773 so the resource state observed by the client stays closer in sync 774 with the actual state at the server. 776 For this purpose, the server MAY optimize the transmission process by 777 aborting the transmission of the old notification (but not before the 778 current transmission attempt completed) and starting a new 779 transmission for the new notification (but with the retransmission 780 timer and counter of the aborted transmission retained). 782 In more detail, a server MAY supersede an outstanding transmission 783 that pertains to an observation as follows: 785 1. Wait for the current (re-)transmission attempt to be 786 acknowledged, rejected or to time out (confirmable transmission); 787 or wait for the waiting time to elapse or the transmission to be 788 rejected (non-confirmable transmission). 790 2. If the transmission is rejected or it was the last attempt to 791 retransmit a notification, remove the associated entry from the 792 list of observers of the observed resource. 794 3. If the entry is still in the list of observers, start to transmit 795 a new notification with a representation of the current resource 796 state. Should the resource have changed its state more than once 797 in the meantime, the notifications for the intermediate states 798 are silently skipped. 800 4. The new notification is transmitted with a new Message ID and the 801 following transmission parameters: If the previous 802 (re-)transmission attempt timed out, retain its transmission 803 parameters, increment the retransmission counter and double the 804 timeout; otherwise, initialize the transmission parameters as 805 usual (see Section 4.2 of RFC 7252 [RFC7252]). 807 It is possible that the server later receives an acknowledgement for 808 a confirmable notification that it superseded this way. Even though 809 this does not signal consistency, it is valuable in that it signals 810 the client's further interest in the resource. The server therefore 811 should avoid inadvertently removing the associated entry from the 812 list of observers. 814 5. Intermediaries 816 A client may be interested in a resource in the namespace of a server 817 that is reached through a chain of one or more CoAP intermediaries. 818 In this case, the client registers its interest with the first 819 intermediary towards the server, acting as if it was communicating 820 with the server itself, as specified in Section 3. It is the task of 821 this intermediary to provide the client with a current representation 822 of the target resource and to keep the representation updated upon 823 changes to the resource state, as specified in Section 4. 825 To perform this task, the intermediary SHOULD make use of the 826 protocol specified in this document, taking the role of the client 827 and registering its own interest in the target resource with the next 828 hop towards the server. If the response returned by the next hop 829 doesn't include an Observe Option, the intermediary MAY resort to 830 polling the next hop or MAY itself return a response without an 831 Observe Option. 833 The communication between each pair of hops is independent; each hop 834 in the server role MUST determine individually how many notifications 835 to send, of which message type, and so on. Each hop MUST generate 836 its own values for the Observe Option in notifications, and MUST set 837 the value of the Max-Age Option according to the age of the local 838 current representation. 840 If two or more clients have registered their interest in a resource 841 with an intermediary, the intermediary MUST register itself only once 842 with the next hop and fan out the notifications it receives to all 843 registered clients. This relieves the next hop from sending the same 844 notifications multiple times and thus enables scalability. 846 An intermediary is not required to act on behalf of a client to 847 observe a resource; an intermediary MAY observe a resource, for 848 example, just to keep its own cache up to date. 850 See Appendix A.2 for examples. 852 6. Web Linking 854 A web link [RFC5988] to a resource accessible over CoAP (for example, 855 in a link-format document [RFC6690]) MAY include the target attribute 856 "obs". 858 The "obs" attribute, when present, is a hint indicating that the 859 destination of a link is useful for observation and thus, for 860 example, should have a suitable graphical representation in a user 861 interface. Note that this is only a hint; it is not a promise that 862 the Observe Option can actually be used to perform the observation. 863 A client may need to resort to polling the resource if the Observe 864 Option is not returned in the response to the GET request. 866 A value MUST NOT be given for the "obs" attribute; any present value 867 MUST be ignored by parsers. The "obs" attribute MUST NOT appear more 868 than once in a given link-value; occurrences after the first MUST be 869 ignored by parsers. 871 7. Security Considerations 873 The security considerations in Section 11 of the CoAP specification 874 [RFC7252] apply. 876 Observing resources can dramatically increase the negative effects of 877 amplification attacks. That is, not only can notifications messages 878 be much larger than the request message, but the nature of the 879 protocol can cause a significant number of notifications to be 880 generated. Without client authentication, a server therefore MUST 881 strictly limit the number of notifications that it sends between 882 receiving acknowledgements that confirm the actual interest of the 883 client in the data; i.e., any notifications sent in non-confirmable 884 messages MUST be interspersed with confirmable messages. (An 885 attacker may still spoof the acknowledgements if the confirmable 886 messages are sufficiently predictable.) 888 The protocol follows a best-effort approach for keeping the state 889 observed by a client and the actual resource state at a server in 890 sync. This may have the client and the server become out of sync at 891 times. Depending on the sensitivity of the observed resource, 892 operating on an old state might be a security threat. The client 893 therefore must be careful not to use a representation after its Max- 894 Age expires, and the server must set the Max-Age Option to a sensible 895 value. 897 As with any protocol that creates state, attackers may attempt to 898 exhaust the resources that the server has available for maintaining 899 the list of observers for each resource. Servers may want to apply 900 access controls to this creation of state. As degraded behavior, the 901 server can always fall back to processing the request as a normal GET 902 request (without an Observe Option) if it is unwilling or unable to 903 add a client to the list of observers of a resource, including if 904 system resources are exhausted or nearing exhaustion. 906 Intermediaries must be careful to ensure that notifications cannot be 907 employed to create a loop. A simple way to break any loops is to 908 employ caches for forwarding notifications in intermediaries. 910 Resources can be observed over DTLS-secured CoAP using any of the 911 security modes described in Section 9 of RFC 7252. The use of DTLS 912 is indicated by the "coaps" URI scheme. All notifications resulting 913 from a GET request with an Observe Option MUST be returned within the 914 same epoch of the same connection as the request. 916 8. IANA Considerations 918 The following entry is added to the CoAP Option Numbers registry: 920 +--------+---------+-----------+ 921 | Number | Name | Reference | 922 +--------+---------+-----------+ 923 | 6 | Observe | [RFCXXXX] | 924 +--------+---------+-----------+ 926 [Note to RFC Editor: Please replace XXXX with the RFC number of this 927 specification.] 929 9. Acknowledgements 931 Carsten Bormann was an original author of this draft and is 932 acknowledged for significant contribution to this document. 934 Thanks to Daniele Alessandrelli, Jari Arkko, Peter A. Bigot, Angelo 935 P. Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank, 936 Bert Greevenbosch, Jeroen Hoebeke, Cullen Jennings, Matthias 937 Kovatsch, Barry Leiba, Salvatore Loreto, Charles Palmer, Akbar 938 Rahman, Zach Shelby, and Floris Van den Abeele for helpful comments 939 and discussions that have shaped the document. 941 This work was supported in part by Klaus Tschira Foundation, Intel, 942 Cisco, and Nokia. 944 10. References 945 10.1. Normative References 947 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 948 Requirement Levels", BCP 14, RFC 2119, March 1997. 950 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 952 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 953 Application Protocol (CoAP)", RFC 7252, June 2014. 955 10.2. Informative References 957 [GOF] Gamma, E., Helm, R., Johnson, R., and J. Vlissides, 958 "Design Patterns: Elements of Reusable Object-Oriented 959 Software", Addison-Wesley, Reading, MA, USA, 960 November 1994. 962 [REST] Fielding, R., "Architectural Styles and the Design of 963 Network-based Software Architectures", Ph.D. Dissertation, 964 University of California, Irvine, 2000, . 968 [RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982, 969 August 1996. 971 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 972 for Application Designers", BCP 145, RFC 5405, 973 November 2008. 975 [RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes 976 to an HTTP Resource", RFC 5989, October 2010. 978 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 979 "Known Issues and Best Practices for the Use of Long 980 Polling and Streaming in Bidirectional HTTP", RFC 6202, 981 April 2011. 983 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 984 Format", RFC 6690, August 2012. 986 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 987 Constrained-Node Networks", RFC 7228, May 2014. 989 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 990 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 991 June 2014. 993 Appendix A. Examples 995 A.1. Client/Server Examples 997 Observed CLIENT SERVER Actual 998 t State | | State 999 ____________ | | ____________ 1000 1 | | 1001 2 unknown | | 18.5 Cel 1002 3 +----->| Header: GET 0x41011633 1003 4 | GET | Token: 0x4a 1004 5 | | Uri-Path: temperature 1005 6 | | Observe: 0 (register) 1006 7 | | 1007 8 | | 1008 9 ____________ |<-----+ Header: 2.05 0x61451633 1009 10 | 2.05 | Token: 0x4a 1010 11 18.5 Cel | | Observe: 9 1011 12 | | Max-Age: 15 1012 13 | | Payload: "18.5 Cel" 1013 14 | | 1014 15 | | ____________ 1015 16 ____________ |<-----+ Header: 2.05 0x51457b50 1016 17 | 2.05 | 19.2 Cel Token: 0x4a 1017 18 19.2 Cel | | Observe: 16 1018 29 | | Max-Age: 15 1019 20 | | Payload: "19.2 Cel" 1020 21 | | 1022 Figure 3: A client registers and receives one notification of the 1023 current state and one of a new state upon a state change 1024 Observed CLIENT SERVER Actual 1025 t State | | State 1026 ____________ | | ____________ 1027 22 | | 1028 23 19.2 Cel | | 19.2 Cel 1029 24 | | ____________ 1030 25 | X----+ Header: 2.05 0x51457b51 1031 26 | 2.05 | 19.7 Cel Token: 0x4a 1032 27 | | Observe: 25 1033 28 | | Max-Age: 15 1034 29 | | Payload: "19.7 Cel" 1035 30 | | 1036 31 ____________ | | 1037 32 | | 1038 33 19.2 Cel | | 1039 34 (stale) | | 1040 35 | | 1041 36 | | 1042 37 | | 1043 38 +----->| Header: GET 0x41011634 1044 39 | GET | Token: 0xb2 1045 40 | | Uri-Path: temperature 1046 41 | | Observe: 0 (register) 1047 42 | | 1048 43 | | 1049 44 ____________ |<-----+ Header: 2.05 0x61451634 1050 45 | 2.05 | Token: 0xb2 1051 46 19.7 Cel | | Observe: 44 1052 47 | | Max-Age: 15 1053 48 | | ETag: 0x78797a7a79 1054 49 | | Payload: "19.7 Cel" 1055 50 | | 1057 Figure 4: The client re-registers after Max-Age ends 1059 Observed CLIENT SERVER Actual 1060 t State | | State 1061 ____________ | | ____________ 1062 51 | | 1063 52 19.7 Cel | | 19.7 Cel 1064 53 | | 1065 54 | | ____________ 1066 55 | crash 1067 56 | 1068 57 | 1069 58 | 1070 59 ____________ | 1071 60 | 1072 61 19.7 Cel | 1073 62 (stale) | 1074 63 | reboot____________ 1075 64 | | 1076 65 | | 20.0 Cel 1077 66 | | 1078 67 +----->| Header: GET 0x41011635 1079 68 | GET | Token: 0xf9 1080 69 | | Uri-Path: temperature 1081 70 | | Observe: 0 (register) 1082 71 | | ETag: 0x78797a7a79 1083 72 | | 1084 73 | | 1085 74 ____________ |<-----+ Header: 2.05 0x61451635 1086 75 | 2.05 | Token: 0xf9 1087 76 20.0 Cel | | Observe: 74 1088 77 | | Max-Age: 15 1089 78 | | Payload: "20.0 Cel" 1090 79 | | 1091 80 | | ____________ 1092 81 ____________ |<-----+ Header: 2.03 0x5143aa0c 1093 82 | 2.03 | 19.7 Cel Token: 0xf9 1094 83 19.7 Cel | | Observe: 81 1095 84 | | ETag: 0x78797a7a79 1096 85 | | Max-Age: 15 1097 86 | | 1099 Figure 5: The client re-registers and gives the server the 1100 opportunity to select a stored response 1102 Observed CLIENT SERVER Actual 1103 t State | | State 1104 ____________ | | ____________ 1105 87 | | 1106 88 19.7 Cel | | 19.7 Cel 1107 89 | | 1108 90 | | ____________ 1109 91 ____________ |<-----+ Header: 2.05 0x4145aa0f 1110 92 | 2.05 | 19.3 Cel Token: 0xf9 1111 93 19.3 Cel | | Observe: 91 1112 94 | | Max-Age: 15 1113 95 | | Payload: "19.3 Cel" 1114 96 | | 1115 97 | | 1116 98 +- - ->| Header: 0x7000aa0f 1117 99 | | 1118 100 | | 1119 101 | | 1120 102 | | ____________ 1121 103 | | 1122 104 | | 19.0 Cel 1123 105 | | 1124 106 ____________ | | 1125 107 | | 1126 108 19.3 Cel | | 1127 109 (stale) | | 1128 110 | | 1130 Figure 6: The client rejects a notification and thereby cancels the 1131 observation 1133 A.2. Proxy Examples 1135 CLIENT PROXY SERVER 1136 | | | 1137 | +----->| Header: GET 0x41015fb8 1138 | | GET | Token: 0x1a 1139 | | | Uri-Host: sensor.example 1140 | | | Uri-Path: status 1141 | | | Observe: 0 (register) 1142 | | | 1143 | |<-----+ Header: 2.05 0x61455fb8 1144 | | 2.05 | Token: 0x1a 1145 | | | Observe: 42 1146 | | | Max-Age: 60 1147 | | | Payload: "ready" 1148 | | | 1149 +----->| | Header: GET 0x41011633 1150 | GET | | Token: 0x9a 1151 | | | Proxy-Uri: coap://sensor.example/status 1152 | | | 1153 |<-----+ | Header: 2.05 0x61451633 1154 | 2.05 | | Token: 0x9a 1155 | | | Max-Age: 53 1156 | | | Payload: "ready" 1157 | | | 1158 | |<-----+ Header: 2.05 0x514505fc0 1159 | | 2.05 | Token: 0x1a 1160 | | | Observe: 135 1161 | | | Max-Age: 60 1162 | | | Payload: "busy" 1163 | | | 1164 +----->| | Header: GET 0x41011634 1165 | GET | | Token: 0x9b 1166 | | | Proxy-Uri: coap://sensor.example/status 1167 | | | 1168 |<-----+ | Header: 2.05 0x61451634 1169 | 2.05 | | Token: 0x9b 1170 | | | Max-Age: 49 1171 | | | Payload: "busy" 1172 | | | 1174 Figure 7: A proxy observes a resource to keep its cache up to date 1176 CLIENT PROXY SERVER 1177 | | | 1178 +----->| | Header: GET 0x41011635 1179 | GET | | Token: 0x6a 1180 | | | Proxy-Uri: coap://sensor.example/status 1181 | | | Observe: 0 (register) 1182 | | | 1183 |<- - -+ | Header: 0x60001635 1184 | | | 1185 | +----->| Header: GET 0x4101af90 1186 | | GET | Token: 0xaa 1187 | | | Uri-Host: sensor.example 1188 | | | Uri-Path: status 1189 | | | Observe: 0 (register) 1190 | | | 1191 | |<-----+ Header: 2.05 0x6145af90 1192 | | 2.05 | Token: 0xaa 1193 | | | Observe: 67 1194 | | | Max-Age: 60 1195 | | | Payload: "ready" 1196 | | | 1197 |<-----+ | Header: 2.05 0x4145af94 1198 | 2.05 | | Token: 0x6a 1199 | | | Observe: 17346 1200 | | | Max-Age: 60 1201 | | | Payload: "ready" 1202 | | | 1203 +- - ->| | Header: 0x6000af94 1204 | | | 1205 | |<-----+ Header: 2.05 0x51455a20 1206 | | 2.05 | Token: 0xaa 1207 | | | Observe: 157 1208 | | | Max-Age: 60 1209 | | | Payload: "busy" 1210 | | | 1211 |<-----+ | Header: 2.05 0x5145af9b 1212 | 2.05 | | Token: 0x6a 1213 | | | Observe: 17436 1214 | | | Max-Age: 60 1215 | | | Payload: "busy" 1216 | | | 1218 Figure 8: A client observes a resource through a proxy 1220 Appendix B. Changelog 1222 [Note to RFC Editor: Please remove this section before publication.] 1224 Changes from ietf-14 to ietf-15: 1226 o Clarified several points based on AD, GenART, IESG, and Secdir 1227 reviews. 1229 Changes from ietf-13 to ietf-14: 1231 o Updated references. 1233 Changes from ietf-12 to ietf-13: 1235 o Extended the Observe Option in requests to not only add but also 1236 remove an entry in the list of observers, depending on the option 1237 value. 1239 Note: The value of the Observe Option in a registration request 1240 may now be any sequence of bytes that encodes the unsigned 1241 integer 0, i.e., 0x'', 0x'00', 0x'00 00' or 0x'00 00 00'. 1243 o Removed the 7.31 Code for cancellation. 1245 Changes from ietf-11 to ietf-12: 1247 o Introduced the 7.31 Code to request the cancellation of a pending 1248 request. 1250 o Made the algorithm for superseding an outstanding transmission 1251 OPTIONAL. 1253 o Clarified that the entry in the list of observers is removed if 1254 the client fails to acknowledge a confirmable notification before 1255 the last retransmission attempt times out (#350). 1257 o Simplified the text on cancellation (#352) and the handling of 1258 Reset messages (#353). 1260 Changes from ietf-10 to ietf-11: 1262 o Pointed out that client and server clocks may differ in their 1263 realization of the SI second, and added robustness to the existing 1264 reordering scheme by reducing the maximum notification rate to 1265 32768 notifications per second (#341). 1267 Changes from ietf-09 to ietf-10: 1269 o Required consistent sequence numbers across requests (#333). 1271 o Clarified that a server needs to update the entry in the list of 1272 observers instead of adding a new entry if the endpoint/token pair 1273 is already present. 1275 o Allowed that a client uses a token that is currently in use to 1276 ensure that it's still in the list of observers. This is possible 1277 because sequence numbers are now consistent across requests and 1278 servers won't add a new entry for the same token. 1280 o Improved text on the transmission of non-confirmable notifications 1281 to match Section 3.1.2 of RFC 5405 more closely. 1283 o Updated examples to use UCUM units. 1285 o Moved Appendix B into the introduction. 1287 Changes from ietf-08 to ietf-09: 1289 o Removed the side effects of requests on existing observations. 1290 This includes removing that 1292 * the client can use a GET request to cancel an observation; 1294 * the server updates the entry in the list of observers instead 1295 of adding a new entry if the client is already present (#258, 1296 #281). 1298 o Clarified that a resource (and hence an observation relationship) 1299 is identified by the request options that are part of the Cache- 1300 Key (#258). 1302 o Clarified that a non-2.xx notification MUST NOT include an Observe 1303 Option. 1305 o Moved block-wise transfer of notifications to [I-D.ietf-core- 1306 block]. 1308 Changes from ietf-07 to ietf-08: 1310 o Expanded text on transmitting a notification while a previous 1311 transmission is pending (#242). 1313 o Changed reordering detection to use a fixed time span of 128 1314 seconds instead of EXCHANGE_LIFETIME (#276). 1316 o Removed the use of the freshness model to determine if the client 1317 is still on the list of observers. This includes removing that 1319 * the client assumes that it has been removed from the list of 1320 observers when Max-Age ends; 1322 * the server sets the Max-Age Option of a notification to a value 1323 that indicates when the server will send the next notification; 1325 * the server uses a number of retransmit attempts such that 1326 removing a client from the list of observers before Max-Age 1327 ends is avoided (#235); 1329 * the server may remove the client from all lists of observers 1330 when the transmission of a confirmable notification ultimately 1331 times out. 1333 o Changed that an unrecognized critical option in a request must 1334 actually have no effect on the state of any observation 1335 relationship to any resource, as the option could lead to a 1336 different target resource. 1338 o Clarified that client implementations must be prepared to receive 1339 each notification equally as a confirmable or a non-confirmable 1340 message, regardless of the message type of the request and of any 1341 previous notification. 1343 o Added a requirement for sending a confirmable notification at 1344 least every 24 hours before continuing with non-confirmable 1345 notifications (#221). 1347 o Added congestion control considerations from [I-D.bormann-core- 1348 congestion-control-02]. 1350 o Recommended that the client waits for a randomized time after the 1351 freshness of the latest notification expired before re- 1352 registering. This prevents that multiple clients observing a 1353 resource perform a GET request at the same time when the need to 1354 re-register arises. 1356 o Changed reordering detection from 'MAY' to 'SHOULD', as the goal 1357 of the protocol (to keep the observed state as closely in sync 1358 with the actual state as possible) is not optional. 1360 o Fixed the length of the Observe Option (3 bytes) in the table in 1361 Section 2. 1363 o Replaced the 'x' in the No-Cache-Key column in the table in 1364 Section 2 with a '-', as the Observe Option doesn't have the No- 1365 Cache-Key flag set, even though it is not part of the cache key. 1367 o Updated examples. 1369 Changes from ietf-06 to ietf-07: 1371 o Moved to 24-bit sequence numbers to allow for up to 15000 1372 notifications per second per client and resource (#217). 1374 o Re-numbered option number to use Unsafe/Safe and Cache-Key 1375 compliant numbers (#241). 1377 o Clarified how to react to a Reset message that is sent in reply to 1378 a non-confirmable notification (#225). 1380 o Clarified the semantics of the "obs" link target attribute (#236). 1382 Changes from ietf-05 to ietf-06: 1384 o Improved abstract and introduction to say that the protocol is 1385 about best effort and eventual consistency (#219). 1387 o Clarified that the value of the Observe Option in a request must 1388 have zero length. 1390 o Added requirement that the sequence number must be updated each 1391 time a server retransmits a notification. 1393 o Clarified that a server must remove a client from the list of 1394 observers when it receives a GET request with an unrecognized 1395 critical option. 1397 o Updated the text to use the endpoint concept from [I-D.ietf-core- 1398 coap] (#224). 1400 o Improved the reordering text (#223). 1402 Changes from ietf-04 to ietf-05: 1404 o Recommended that a client does not re-register while a new 1405 notification from the server is still likely to arrive. This is 1406 to avoid that the request of the client and the last notification 1407 after max-age cross over each other (#174). 1409 o Relaxed requirements when sending a Reset message in reply to non- 1410 confirmable notifications. 1412 o Added an implementation note about careless GET requests (#184). 1414 o Updated examples. 1416 Changes from ietf-03 to ietf-04: 1418 o Removed the "Max-OFE" Option. 1420 o Allowed a Reset message in reply to non-confirmable notifications. 1422 o Added a section on cancellation. 1424 o Updated examples. 1426 Changes from ietf-02 to ietf-03: 1428 o Separated client-side and server-side requirements. 1430 o Fixed uncertainty if client is still on the list of observers by 1431 introducing a liveliness model based on Max-Age and a new option 1432 called "Max-OFE" (#174). 1434 o Simplified the text on message reordering (#129). 1436 o Clarified requirements for intermediaries. 1438 o Clarified the combination of blockwise transfers with 1439 notifications (#172). 1441 o Updated examples to show how the state observed by the client 1442 becomes eventually consistent with the actual state on the server. 1444 o Added examples for parameterization of observable resource. 1446 Changes from ietf-01 to ietf-02: 1448 o Removed the requirement of periodic refreshing (#126). 1450 o The new "Observe" Option replaces the "Lifetime" Option. 1452 o Introduced a new mechanism to detect message reordering. 1454 o Changed 2.00 (OK) notifications to 2.05 (Content) notifications. 1456 Changes from ietf-00 to ietf-01: 1458 o Changed terminology from "subscriptions" to "observation 1459 relationships" (#33). 1461 o Changed the name of the option to "Lifetime". 1463 o Clarified establishment of observation relationships. 1465 o Clarified that an observation is only identified by the URI of the 1466 observed resource and the identity of the client (#66). 1468 o Clarified rules for establishing observation relationships (#68). 1470 o Clarified conditions under which an observation relationship is 1471 terminated. 1473 o Added explanation on how clients can terminate an observation 1474 relationship before the lifetime ends (#34). 1476 o Clarified that the overriding objective for notifications is 1477 eventual consistency of the actual and the observed state (#67). 1479 o Specified how a server needs to deal with clients not 1480 acknowledging confirmable messages carrying notifications (#69). 1482 o Added a mechanism to detect message reordering (#35). 1484 o Added an explanation of how notifications can be cached, 1485 supporting both the freshness and the validation model (#39, #64). 1487 o Clarified that non-GET requests do not affect observation 1488 relationships, and that GET requests without "Lifetime" Option 1489 affecting relationships is by design (#65). 1491 o Described interaction with blockwise transfers (#36). 1493 o Added Resource Discovery section (#99). 1495 o Added IANA Considerations. 1497 o Added Security Considerations (#40). 1499 o Added examples (#38). 1501 Author's Address 1503 Klaus Hartke 1504 Universitaet Bremen TZI 1505 Postfach 330440 1506 Bremen D-28359 1507 Germany 1509 Phone: +49-421-218-63905 1510 EMail: hartke@tzi.org