idnits 2.17.1 draft-ietf-core-observe-14.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 (June 30, 2014) is 3578 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 900, but not defined ** Obsolete normative reference: RFC 5405 (Obsoleted by RFC 8085) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) Summary: 2 errors (**), 0 flaws (~~), 2 warnings (==), 3 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 June 30, 2014 5 Expires: January 1, 2015 7 Observing Resources in CoAP 8 draft-ietf-core-observe-14 10 Abstract 12 CoAP is a RESTful application protocol for constrained nodes and 13 networks. The state of a resource on a CoAP server can change over 14 time. This document specifies a simple protocol extension for CoAP 15 that enables CoAP clients to "observe" resources, i.e., to retrieve 16 a representation of a resource and keep this representation updated 17 by the server over a period of time. The protocol follows a best- 18 effort approach for sending new representations to clients and 19 provides eventual consistency between the state observed by each 20 client and the actual resource state at the server. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 1, 2015. 39 Copyright Notice 41 Copyright (c) 2014 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Background . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 3 59 1.3. Consistency Model . . . . . . . . . . . . . . . . . . . . 5 60 1.4. Observable Resources . . . . . . . . . . . . . . . . . . . 6 61 1.5. Requirements Notation . . . . . . . . . . . . . . . . . . 7 62 2. The Observe Option . . . . . . . . . . . . . . . . . . . . . . 7 63 3. Client-side Requirements . . . . . . . . . . . . . . . . . . . 8 64 3.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 8 65 3.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 8 66 3.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 9 67 3.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 10 68 3.5. Transmission . . . . . . . . . . . . . . . . . . . . . . . 11 69 3.6. Cancellation . . . . . . . . . . . . . . . . . . . . . . . 11 70 4. Server-side Requirements . . . . . . . . . . . . . . . . . . . 12 71 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 12 72 4.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 12 73 4.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 13 74 4.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 14 75 4.5. Transmission . . . . . . . . . . . . . . . . . . . . . . . 14 76 5. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 17 77 6. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 18 78 7. Security Considerations . . . . . . . . . . . . . . . . . . . 19 79 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 80 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 19 81 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 20 82 10.1. Normative References . . . . . . . . . . . . . . . . . . . 20 83 10.2. Informative References . . . . . . . . . . . . . . . . . . 20 84 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 21 85 A.1. Client/Server Examples . . . . . . . . . . . . . . . . . . 21 86 A.2. Proxy Examples . . . . . . . . . . . . . . . . . . . . . . 25 87 Appendix B. Changelog . . . . . . . . . . . . . . . . . . . . . . 27 89 1. Introduction 91 1.1. Background 93 CoAP [RFC7252] is an application protocol for constrained nodes and 94 networks. It is intended to provide RESTful services [REST] not 95 unlike HTTP [RFC7230] while reducing the complexity of implementation 96 as well as the size of packets exchanged in order to make these 97 services useful in a highly constrained network of themselves highly 98 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 GET request and includes a complete, 175 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 upon registration with the current state, 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 interest is determined from the client's acknowledgement of 218 notifications sent in confirmable CoAP messages by the server. When 219 the client deregisters, rejects a notification, or the transmission 220 of a notification times out after several transmission attempts, the 221 client is considered no longer interested and is removed from the 222 list of observers by the server. 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 fully avoided that the client and the server become out 231 of sync at times: First, there is always some latency between the 232 change of the resource state and the receipt of the notification. 233 Second, CoAP messages with notifications can get lost, which will 234 cause the client to assume an old state until it receives a new 235 notification. And third, the server may erroneously come to the 236 conclusion that the client is no longer interested in the resource, 237 which will cause the server to stop sending notifications and the 238 client to assume an old state until it eventually registers its 239 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. However, a client 247 cannot rely on observing every single state that a resource might 248 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. 332 In a response, the Observe Option identifies the message as a 333 notification. This implies that the server has added an entry with 334 the client endpoint and request token to the list of observers and 335 that it will notify the client of changes to the resource state. The 336 option value is a 24-bit sequence number for reordering detection 337 (see Section 3.4 and Section 4.4). 339 The value of the Observe Option is encoded as an unsigned integer in 340 network byte order using a variable number of bytes ('uint' option 341 format); see Section 3.2 of RFC 7252 [RFC7252]. 343 The Observe Option is not part of the cache-key: a cacheable response 344 obtained with an Observe Option in the request can be used to satisfy 345 a request without an Observe Option, and vice versa. When a stored 346 response with an Observe Option is used to satisfy a normal GET 347 request, the option MUST be removed before the response is returned. 349 3. Client-side Requirements 351 3.1. Request 353 A client registers its interest in a resource by issuing a GET 354 request with an Observe Option set to 'register' (0). If the server 355 returns a 2.xx response that includes an Observe Option as well, the 356 server has successfully added an entry with the client endpoint and 357 request token to the list of observers of the target resource and the 358 client will be notified of changes to the resource state. 360 Like a fresh response can be used to satisfy a request without 361 contacting the server, the stream of updates resulting from one 362 observation request can be used to satisfy another (observation or 363 normal GET) request if the target resource is the same. A client 364 MUST aggregate such requests and MUST NOT register more than once for 365 the same target resource. The target resource SHALL be identified 366 for this purpose by all options in the request that are part of the 367 cache-key, such as the full request URI and the Accept Option. 369 3.2. Notifications 371 Notifications are additional responses sent by the server in reply to 372 the GET request. Each notification includes the token specified by 373 the client in the GET request. 375 Notifications typically have a 2.05 (Content) response code. They 376 include an Observe Option with a sequence number for reordering 377 detection (see Section 3.4), and a payload in the same Content-Format 378 as the initial response. If the client included one or more ETag 379 Options in the request (see Section 3.3), notifications can also have 380 a 2.03 (Valid) response code. Such notifications include an Observe 381 Option with a sequence number but no payload. 383 In the event that the resource changes in a way that would cause a 384 normal GET request at that time to return a non-2.xx response (for 385 example, when the resource is deleted), the server sends a 386 notification with an appropriate response code (such as 4.04 Not 387 Found) and removes all clients from the list of observers of the 388 resource. Non-2.xx responses do not include an Observe Option. 390 3.3. Caching 392 As notifications are just additional responses to a GET request, 393 notifications partake in caching as defined in Section 5.6 of RFC 394 7252 [RFC7252]. Both the freshness model and the validation model 395 are supported. 397 3.3.1. Freshness 399 A client MAY store a notification like a response in its cache and 400 use a stored notification that is fresh without contacting the 401 server. Like a response, a notification is considered fresh while 402 its age is not greater than the value indicated by the Max-Age Option 403 (and no newer notification/response has been received). 405 The server will do its best to keep the resource state observed by 406 the client as closely in sync with the actual state as possible. 407 However, a client cannot rely on observing every single state that a 408 resource might go through. For example, if the network is congested 409 or the state changes more frequently than the network can handle, the 410 server can skip notifications for any number of intermediate states. 412 The server uses the Max-Age Option to indicate an age up to which it 413 is acceptable that the observed state and the actual state are 414 inconsistent. If the age of the latest notification becomes greater 415 than its indicated Max-Age, then the client MUST NOT assume that the 416 enclosed representation reflects the actual resource state. 418 To make sure it has a current representation and/or to re-register 419 its interest in a resource, a client MAY issue a new GET request with 420 the same token as the original at any time. All options MUST be 421 identical to those in the original request, except for the set of 422 ETag Options. It is RECOMMENDED that the client does not issue the 423 request while it still has a fresh notification/response for the 424 resource in its cache. Additionally, the client SHOULD at least wait 425 for a random amount of time between 5 and 15 seconds after Max-Age 426 expired to avoid synchronicity with other clients. 428 3.3.2. Validation 430 When a client has one or more notifications stored in its cache for a 431 resource, it can use the ETag Option in the GET request to give the 432 server an opportunity to select a stored notification to be used. 434 The client MAY include an ETag Option for each stored response that 435 is applicable in the GET request. Whenever the observed resource 436 changes to a representation identified by one of the ETag Options, 437 the server can select a stored response by sending a 2.03 (Valid) 438 notification with an appropriate ETag Option instead of a 2.05 439 (Content) notification. 441 A client implementation needs to keep all candidate responses in its 442 cache until it is no longer interested in the target resource or it 443 re-registers with a new set of entity-tags. 445 3.4. Reordering 447 Messages with notifications can arrive in a different order than they 448 were sent. Since the goal is to keep the observed state as closely 449 in sync with the actual state as possible, a client MUST NOT consider 450 a notification fresh that arrives later than a newer notification. 452 For reordering detection, the server sets the value of the Observe 453 Option in each notification to the 24 least-significant bits of a 454 strictly increasing sequence number. An incoming notification is 455 newer than the newest notification received so far when one of the 456 following conditions is met: 458 (V1 < V2 and V2 - V1 < 2^23) or 459 (V1 > V2 and V1 - V2 > 2^23) or 460 (T2 > T1 + 128 seconds) 462 where V1 is the value of the Observe Option of the newest 463 notification received so far, V2 the value of the Observe Option of 464 the incoming notification, T1 a client-local timestamp of the newest 465 notification received so far, and T2 a client-local timestamp of the 466 incoming notification. 468 Design Note: The first two conditions verify that V1 is less than V2 469 in 24-bit serial number arithmetic [RFC1982]. The third condition 470 ensures that the time elapsed between the two incoming messages is 471 not so large that the difference between V1 and V2 has become 472 larger than the largest integer that it is meaningful to add to a 473 24-bit serial number; in other words, after 128 seconds have 474 elapsed without any notification, a client does not need to check 475 the sequence numbers to assume an incoming notification is new. 477 The duration of 128 seconds was chosen as a nice round number 478 greater than MAX_LATENCY (Section 4.8.2 of RFC 7252 [RFC7252]). 480 3.5. Transmission 482 A notification can be confirmable or non-confirmable, i.e., it can be 483 sent in a confirmable or a non-confirmable message. The message type 484 used for a notification is independent from the type used for the 485 request or for any previous notification. 487 If a client does not recognize the token in a confirmable 488 notification, it MUST NOT acknowledge the message and SHOULD reject 489 it with a Reset message; otherwise, the client MUST acknowledge the 490 message as usual. In the case of a non-confirmable notification, 491 rejecting the message with a Reset message is OPTIONAL. 493 An acknowledgement message signals to the server that the client is 494 alive and interested in receiving further notifications; if the 495 server does not receive an acknowledgement in reply to a confirmable 496 notification, it will assume that the client is no longer interested 497 and will eventually remove the associated entry from the list of 498 observers. 500 3.6. Cancellation 502 A client that is no longer interested in receiving notifications for 503 a resource can simply "forget" the observation. When the server then 504 sends the next notification, the client will not recognize the token 505 in the message and thus will return a Reset message. This causes the 506 server to remove the associated entry from the list of observers. 507 The entries in lists of observers are effectively "garbage collected" 508 by the server. 510 Implementation Note: Due to potential message loss, the Reset 511 message may not reach the server. The client may therefore have 512 to reject multiple notifications, each with one Reset message, 513 until the server finally removes the associated entry from the 514 list of observers and stops sending notifications. 516 In some circumstances, it may be desirable to cancel an observation 517 and release the resources allocated by the server to it more eagerly. 518 In this case, a client MAY explicitly deregister by issuing a GET 519 request which has the Token field set to the token of the observation 520 to be cancelled and includes an Observe Option with the value set to 521 'deregister' (1). All other options MUST be identical to those in 522 the registration request, except for the set of ETag Options. When 523 the server receives such a request, it will remove any matching entry 524 from the list of observers and processes the GET request as usual. 526 4. Server-side Requirements 528 4.1. Request 530 A GET request with an Observe Option set to 'register' (0) requests 531 the server not only to return a current representation of the target 532 resource, but also to add the client to the list of observers of that 533 resource. Upon success, the server returns a current representation 534 of the resource and MUST notify the client of subsequent changes to 535 the state as long as the client is on the list of observers. 537 The entry in the list of observers is keyed by the client endpoint 538 and the token specified by the client in the request. If an entry 539 with a matching endpoint/token pair is already present in the list 540 (which, for example, happens when the client wishes to reinforce its 541 interest in a resource), the server MUST NOT add a new entry but MUST 542 replace or update the existing one. 544 A server that is unable or unwilling to add a new entry to the list 545 of observers of a resource MAY silently ignore the registration 546 request and process the GET request as usual. The resulting response 547 MUST NOT include an Observe Option, the absence of which signals to 548 the client that it will not be notified of changes to the resource 549 and, e.g., needs to poll the resource for its state instead. 551 If the Observe Option in a request is set to any other value than 552 'register' (0), then the server MUST remove any entry with with a 553 matching endpoint/token pair from the list of observers and process 554 the GET request as usual. The resulting response MUST NOT include an 555 Observe Option. 557 4.2. Notifications 559 A client is notified of changes to the resource state by additional 560 responses sent by the server in reply to the GET request. Each such 561 notification response (including the initial response) MUST echo the 562 token specified by the client in the GET request. If there are 563 multiple entries in the list of observers, the order in which the 564 clients are notified is not defined; the server is free to use any 565 method to determine the order. 567 A notification SHOULD have a 2.05 (Content) or 2.03 (Valid) response 568 code. However, in the event that the state of a resource changes in 569 a way that would cause a normal GET request at that time to return a 570 non-2.xx response (for example, when the resource is deleted), the 571 server SHOULD notify the client by sending a notification with an 572 appropriate response code (such as 4.04 Not Found) and MUST remove 573 the associated entry from the list of observers of the resource. 575 The Content-Format specified in a 2.xx notification MUST be the same 576 as the one used in the initial response to the GET request. If the 577 server is unable to continue sending notifications in this format, it 578 SHOULD send a notification with a 4.06 (Not Acceptable) response code 579 and MUST remove the associated entry from the list of observers of 580 the resource. 582 A 2.xx notification MUST include an Observe Option with a sequence 583 number as specified in Section 4.4 below; a non-2.xx notification 584 MUST NOT include an Observe Option. 586 4.3. Caching 588 As notifications are just additional responses sent by the server in 589 reply to a GET request, they are subject to caching as defined in 590 Section 5.6 of RFC 7252 [RFC7252]. 592 4.3.1. Freshness 594 After returning the initial response, the server MUST try to keep the 595 returned representation current, i.e., it MUST keep the resource 596 state observed by the client as closely in sync with the actual 597 resource state as possible. 599 Since becoming out of sync at times cannot be avoided, the server 600 MUST indicate for each representation an age up to which it is 601 acceptable that the observed state and the actual state are 602 inconsistent. This age is application-dependent and MUST be 603 specified in notifications using the Max-Age Option. 605 When the resource does not change and the client has a current 606 representation, the server does not need to send a notification. 607 However, if the client does not receive a notification, the client 608 cannot tell if the observed state and the actual state are still in 609 sync. Thus, when the the age of the latest notification becomes 610 greater than its indicated Max-Age, the client no longer has a usable 611 representation of the resource state. The server MAY wish to prevent 612 that by sending a new notification with the unchanged representation 613 and a new Max-Age just before the Max-Age indicated earlier expires. 615 4.3.2. Validation 617 A client can include a set of entity-tags in its request using the 618 ETag Option. When a observed resource changes its state and the 619 origin server is about to send a 2.05 (Content) notification, then, 620 whenever that notification has an entity-tag in the set of entity- 621 tags specified by the client, the server MAY send a 2.03 (Valid) 622 response with an appropriate ETag Option instead. 624 4.4. Reordering 626 Because messages can get reordered, the client needs a way to 627 determine if a notification arrived later than a newer notification. 628 For this purpose, the server MUST set the value of the Observe Option 629 of each notification it sends to the 24 least-significant bits of a 630 strictly increasing sequence number. The sequence number MAY start 631 at any value and MUST NOT increase so fast that it increases by more 632 than 2^23 within less than 256 seconds. 634 The sequence number selected for a notification MUST be greater than 635 that of any preceding notification sent to the same client with the 636 same token for the same resource. The value of the Observe Option 637 MUST be current at the time of transmission; if a notification is 638 retransmitted, the server MUST update the value of the option to the 639 sequence number that is current at that time before retransmission. 641 Implementation Note: A simple implementation that satisfies the 642 requirements is to obtain a timestamp from a local clock. The 643 sequence number then is the timestamp in ticks, where 1 tick = 644 (256 seconds)/(2^23) = 30.52 microseconds. It is not necessary 645 that the clock reflects the current time/date. 647 Another valid implementation is to store a 24-bit unsigned integer 648 variable per resource and increment this variable each time the 649 resource undergoes a change of state (provided that the resource 650 changes its state less than 2^23 times in the first 256 seconds 651 after every state change). This removes the need to update the 652 value of the Observe Option on retransmission when the resource 653 state did not change. 655 Design Note: The choice of a 24-bit option value and a time span of 656 256 seconds theoretically allows for a notification rate of up to 657 65536 notifications per second. Constrained nodes often have 658 rather imprecise clocks, though, and inaccuracies of the client 659 and server side may cancel out or add in effect. Therefore, the 660 maximum notification rate is reduced to 32768 notifications per 661 second. This is still well beyond the highest known design 662 objective of around 1 kHz (most CoAP applications will be several 663 orders of magnitude below that), but allows total clock 664 inaccuracies of up to -50/+100 %. 666 4.5. Transmission 668 A notification can be sent in a confirmable or a non-confirmable 669 message. The message type used is typically application-dependent 670 and MAY be determined by the server for each notification 671 individually. 673 For example, for resources that change in a somewhat predictable or 674 regular fashion, notifications can be sent in non-confirmable 675 messages; for resources that change infrequently, notifications can 676 be sent in confirmable messages. The server can combine these two 677 approaches depending on the frequency of state changes and the 678 importance of individual notifications. 680 A server MAY choose to skip sending a notification if it knows that 681 it will send another notification soon, for example, when the state 682 of a resource is changing frequently. It also MAY choose to send 683 more than one notification for the same resource state. However, 684 above all, the server MUST ensure that a client in the list of 685 observers of a resource eventually observes the latest state if the 686 resource does not undergo a new change in state. 688 For example, when state changes occur in bursts, the server can skip 689 some notifications, send the notifications in non-confirmable 690 messages, and make sure that the client observes the latest state 691 change by repeating the last notification in a confirmable message 692 when the burst is over. 694 The client's acknowledgement of a confirmable notification signals 695 that the client is interested in receiving further notifications. If 696 a client rejects a confirmable or non-confirmable notification with a 697 Reset message, or if the last attempt to retransmit a confirmable 698 notification times out, then the client is considered no longer 699 interested and the server MUST remove the associated entry from the 700 list of observers. 702 Implementation Note: To properly process a Reset message that 703 rejects a non-confirmable notification, a server needs to remember 704 the message IDs of the non-confirmable notifications it sends. 705 This may be challenging for a server with constrained resources. 706 However, since Reset messages are transmitted unreliably, the 707 client must be prepared that its Reset messages aren't received by 708 the server. A server thus can always pretend that a Reset message 709 rejecting a non-confirmable notification was lost. If a server 710 does this, it could accelerate cancellation by sending the 711 following notifications to that client in confirmable messages. 713 A server that transmits notifications mostly in non-confirmable 714 messages MUST send a notification in a confirmable message instead of 715 a non-confirmable message at least every 24 hours. This prevents a 716 client that went away or is no longer interested from remaining in 717 the list of observers indefinitely. 719 4.5.1. Congestion Control 721 Basic congestion control for CoAP is provided by the exponential 722 back-off mechanism in Section 4.2 of RFC 7252 [RFC7252] and the 723 limitations in Section 4.7 of RFC 7252 [RFC7252]. However, CoAP 724 places the responsibility of congestion control for simple request/ 725 response interactions only on the clients: rate limiting request 726 transmission implicitly controls the transmission of the responses. 727 When a single request yields a potentially infinite number of 728 notifications, additional responsibility needs to be placed on the 729 server. 731 In order not to cause congestion, servers MUST strictly limit the 732 number of simultaneous outstanding notifications/responses that they 733 transmit to a given client to NSTART (1 by default; see Section 4.7 734 of RFC 7252 [RFC7252]). An outstanding notification/response is 735 either a confirmable message for which an acknowledgement has not yet 736 been received and whose last retransmission attempt has not yet timed 737 out, or a non-confirmable message for which the waiting time that 738 results from the following rate limiting rules has not yet elapsed. 740 The server SHOULD NOT send more than one non-confirmable notification 741 per round-trip time (RTT) to a client on average. If the server 742 cannot maintain an RTT estimate for a client, it SHOULD NOT send more 743 than one non-confirmable notification every 3 seconds, and SHOULD use 744 an even less aggressive rate when possible (see also Section 3.1.2 of 745 RFC 5405 [RFC5405]). 747 Further congestion control optimizations and considerations are 748 expected in the future with advanced CoAP congestion control 749 mechanisms. 751 4.5.2. Advanced Transmission 753 The state of an observed resource may change while the number of the 754 number of simultaneous outstanding notifications/responses to a 755 client on the list of observers is greater than or equal to NSTART. 756 In this case, the server cannot notify the client of the new resource 757 state immediately but has to wait for an outstanding notification/ 758 response to complete first. 760 If there exists an outstanding notification/response that the server 761 transmits to the client and that pertains to the changed resource, 762 then it is desirable for the server to stop working towards getting 763 the representation of the old resource state to the client, and to 764 start transmitting the current representation to the client instead, 765 so the resource state observed by the client stays closer in sync 766 with the actual state at the server. 768 For this purpose, the server MAY optimize the transmission process by 769 aborting the transmission of the old notification (but not before the 770 current transmission attempt completed) and starting a new 771 transmission for the new notification (but with the retransmission 772 timer and counter of the aborted transmission retained). 774 In more detail, a server MAY supersede an outstanding transmission 775 that pertains to an observation as follows: 777 1. Wait for the current (re-)transmission attempt to be 778 acknowledged, rejected or to time out (confirmable transmission); 779 or wait for the waiting time to elapse or the transmission to be 780 rejected (non-confirmable transmission). 782 2. If the transmission is rejected or it was the last attempt to 783 retransmit a notification, remove the associated entry from the 784 list of observers of the observed resource. 786 3. If the entry is still in the list of observers, start to transmit 787 a new notification with a representation of the current resource 788 state. Should the resource have changed its state more than once 789 in the meantime, the notifications for the intermediate states 790 are silently skipped. 792 4. The new notification is transmitted with a new Message ID and the 793 following transmission parameters: If the previous 794 (re-)transmission attempt timed out, retain its transmission 795 parameters, increment the retransmission counter and double the 796 timeout; otherwise, initialize the transmission parameters as 797 usual (see Section 4.2 of RFC 7252 [RFC7252]). 799 It is possible that the server later receives an acknowledgement for 800 a confirmable notification that it superseded this way. Even though 801 this does not signal consistency, it is valuable in that it signals 802 the client's further interest in the resource. The server therefore 803 should avoid inadvertently removing the associated entry from the 804 list of observers. 806 5. Intermediaries 808 A client may be interested in a resource in the namespace of a server 809 that is reached through a chain of one or more CoAP intermediaries. 810 In this case, the client registers its interest with the first 811 intermediary towards the server, acting as if it was communicating 812 with the server itself, as specified in Section 3. It is the task of 813 this intermediary to provide the client with a current representation 814 of the target resource and to keep the representation updated upon 815 changes to the resource state, as specified in Section 4. 817 To perform this task, the intermediary SHOULD make use of the 818 protocol specified in this document, taking the role of the client 819 and registering its own interest in the target resource with the next 820 hop towards the server. If the response returned by the next hop 821 doesn't include an Observe Option, the intermediary MAY resort to 822 polling the next hop or MAY itself return a response without an 823 Observe Option. 825 The communication between each pair of hops is independent; each hop 826 in the server role MUST determine individually how many notifications 827 to send, of which message type, and so on. Each hop MUST generate 828 its own values for the Observe Option in notifications, and MUST set 829 the value of the Max-Age Option according to the age of the local 830 current representation. 832 If two or more clients have registered their interest in a resource 833 with an intermediary, the intermediary MUST register itself only once 834 with the next hop and fan out the notifications it receives to all 835 registered clients. This relieves the next hop from sending the same 836 notifications multiple times and thus enables scalability. 838 An intermediary is not required to act on behalf of a client to 839 observe a resource; an intermediary MAY observe a resource, for 840 example, just to keep its own cache up to date. 842 See Appendix A.2 for examples. 844 6. Web Linking 846 A web link [RFC5988] to a resource accessible over CoAP (for example, 847 in a link-format document [RFC6690]) MAY include the target attribute 848 "obs". 850 The "obs" attribute, when present, is a hint indicating that the 851 destination of a link is useful for observation and thus, for 852 example, should have a suitable graphical representation in a user 853 interface. Note that this is only a hint; it is not a promise that 854 the Observe Option can actually be used to perform the observation. 855 A client may need to resort to polling the resource if the Observe 856 Option is not returned in the response to the GET request. 858 A value MUST NOT be given for the "obs" attribute; any present value 859 MUST be ignored by parsers. The "obs" attribute MUST NOT appear more 860 than once in a given link-value; occurrences after the first MUST be 861 ignored by parsers. 863 7. Security Considerations 865 The security considerations in Section 11 of RFC 7252 [RFC7252] 866 apply. 868 Observing resources can dramatically increase the negative effects of 869 amplification attacks. That is, not only can notifications messages 870 be much larger than the request message, but the nature of the 871 protocol can cause a significant number of notifications to be 872 generated. Without client authentication, a server therefore MUST 873 strictly limit the number of notifications that it sends between 874 receiving acknowledgements that confirm the actual interest of the 875 client in the data; i.e., any notifications sent in non-confirmable 876 messages MUST be interspersed with confirmable messages. (An 877 attacker may still spoof the acknowledgements if the confirmable 878 messages are sufficiently predictable.) 880 As with any protocol that creates state, attackers may attempt to 881 exhaust the resources that the server has available for maintaining 882 the list of observers for each resource. Servers may want to access- 883 control this creation of state. As degraded behavior, the server can 884 always fall back to processing the request as a normal GET request 885 (without an Observe Option) if it is unwilling or unable to add a 886 client to the list of observers of a resource, including if system 887 resources are exhausted or nearing exhaustion. 889 Intermediaries must be careful to ensure that notifications cannot be 890 employed to create a loop. A simple way to break any loops is to 891 employ caches for forwarding notifications in intermediaries. 893 8. IANA Considerations 895 The following entry is added to the CoAP Option Numbers registry: 897 +--------+---------+-----------+ 898 | Number | Name | Reference | 899 +--------+---------+-----------+ 900 | 6 | Observe | [RFCXXXX] | 901 +--------+---------+-----------+ 903 [Note to RFC Editor: Please replace XXXX with the RFC number of this 904 specification.] 906 9. Acknowledgements 908 Carsten Bormann was an original author of this draft and is 909 acknowledged for significant contribution to this document. 911 Thanks to Daniele Alessandrelli, Jari Arkko, Peter A. Bigot, Angelo 912 P. Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank, 913 Bert Greevenbosch, Jeroen Hoebeke, Cullen Jennings, Matthias 914 Kovatsch, Salvatore Loreto, Charles Palmer, Akbar Rahman, Zach 915 Shelby, and Floris Van den Abeele for helpful comments and 916 discussions that have shaped the document. 918 This work was supported in part by Klaus Tschira Foundation, Intel, 919 Cisco, and Nokia. 921 10. References 923 10.1. Normative References 925 [RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982, 926 August 1996. 928 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 929 Requirement Levels", BCP 14, RFC 2119, March 1997. 931 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 932 for Application Designers", BCP 145, RFC 5405, 933 November 2008. 935 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 937 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 938 Application Protocol (CoAP)", RFC 7252, June 2014. 940 10.2. Informative References 942 [GOF] Gamma, E., Helm, R., Johnson, R., and J. Vlissides, 943 "Design Patterns: Elements of Reusable Object-Oriented 944 Software", Addison-Wesley, Reading, MA, USA, 945 November 1994. 947 [REST] Fielding, R., "Architectural Styles and the Design of 948 Network-based Software Architectures", Ph.D. Dissertation, 949 University of California, Irvine, 2000, . 953 [RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes 954 to an HTTP Resource", RFC 5989, October 2010. 956 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 957 "Known Issues and Best Practices for the Use of Long 958 Polling and Streaming in Bidirectional HTTP", RFC 6202, 959 April 2011. 961 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 962 Format", RFC 6690, August 2012. 964 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 965 Constrained-Node Networks", RFC 7228, May 2014. 967 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 968 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 969 June 2014. 971 Appendix A. Examples 973 A.1. Client/Server Examples 975 Observed CLIENT SERVER Actual 976 t State | | State 977 ____________ | | ____________ 978 1 | | 979 2 unknown | | 18.5 Cel 980 3 +----->| Header: GET 0x41011633 981 4 | GET | Token: 0x4a 982 5 | | Uri-Path: temperature 983 6 | | Observe: 0 (register) 984 7 | | 985 8 | | 986 9 ____________ |<-----+ Header: 2.05 0x61451633 987 10 | 2.05 | Token: 0x4a 988 11 18.5 Cel | | Observe: 9 989 12 | | Max-Age: 15 990 13 | | Payload: "18.5 Cel" 991 14 | | 992 15 | | ____________ 993 16 ____________ |<-----+ Header: 2.05 0x51457b50 994 17 | 2.05 | 19.2 Cel Token: 0x4a 995 18 19.2 Cel | | Observe: 16 996 29 | | Max-Age: 15 997 20 | | Payload: "19.2 Cel" 998 21 | | 1000 Figure 3: A client registers and receives one notification of the 1001 current state and one of a new state upon a state change 1002 Observed CLIENT SERVER Actual 1003 t State | | State 1004 ____________ | | ____________ 1005 22 | | 1006 23 19.2 Cel | | 19.2 Cel 1007 24 | | ____________ 1008 25 | X----+ Header: 2.05 0x51457b51 1009 26 | 2.05 | 19.7 Cel Token: 0x4a 1010 27 | | Observe: 25 1011 28 | | Max-Age: 15 1012 29 | | Payload: "19.7 Cel" 1013 30 | | 1014 31 ____________ | | 1015 32 | | 1016 33 19.2 Cel | | 1017 34 (stale) | | 1018 35 | | 1019 36 | | 1020 37 | | 1021 38 +----->| Header: GET 0x41011634 1022 39 | GET | Token: 0xb2 1023 40 | | Uri-Path: temperature 1024 41 | | Observe: 0 (register) 1025 42 | | 1026 43 | | 1027 44 ____________ |<-----+ Header: 2.05 0x61451634 1028 45 | 2.05 | Token: 0xb2 1029 46 19.7 Cel | | Observe: 44 1030 47 | | Max-Age: 15 1031 48 | | ETag: 0x78797a7a79 1032 49 | | Payload: "19.7 Cel" 1033 50 | | 1035 Figure 4: The client re-registers after Max-Age ends 1037 Observed CLIENT SERVER Actual 1038 t State | | State 1039 ____________ | | ____________ 1040 51 | | 1041 52 19.7 Cel | | 19.7 Cel 1042 53 | | 1043 54 | | ____________ 1044 55 | crash 1045 56 | 1046 57 | 1047 58 | 1048 59 ____________ | 1049 60 | 1050 61 19.7 Cel | 1051 62 (stale) | 1052 63 | reboot____________ 1053 64 | | 1054 65 | | 20.0 Cel 1055 66 | | 1056 67 +----->| Header: GET 0x41011635 1057 68 | GET | Token: 0xf9 1058 69 | | Uri-Path: temperature 1059 70 | | Observe: 0 (register) 1060 71 | | ETag: 0x78797a7a79 1061 72 | | 1062 73 | | 1063 74 ____________ |<-----+ Header: 2.05 0x61451635 1064 75 | 2.05 | Token: 0xf9 1065 76 20.0 Cel | | Observe: 74 1066 77 | | Max-Age: 15 1067 78 | | Payload: "20.0 Cel" 1068 79 | | 1069 80 | | ____________ 1070 81 ____________ |<-----+ Header: 2.03 0x5143aa0c 1071 82 | 2.03 | 19.7 Cel Token: 0xf9 1072 83 19.7 Cel | | Observe: 81 1073 84 | | ETag: 0x78797a7a79 1074 85 | | Max-Age: 15 1075 86 | | 1077 Figure 5: The client re-registers and gives the server the 1078 opportunity to select a stored response 1080 Observed CLIENT SERVER Actual 1081 t State | | State 1082 ____________ | | ____________ 1083 87 | | 1084 88 19.7 Cel | | 19.7 Cel 1085 89 | | 1086 90 | | ____________ 1087 91 ____________ |<-----+ Header: 2.05 0x4145aa0f 1088 92 | 2.05 | 19.3 Cel Token: 0xf9 1089 93 19.3 Cel | | Observe: 91 1090 94 | | Max-Age: 15 1091 95 | | Payload: "19.3 Cel" 1092 96 | | 1093 97 | | 1094 98 +- - ->| Header: 0x7000aa0f 1095 99 | | 1096 100 | | 1097 101 | | 1098 102 | | ____________ 1099 103 | | 1100 104 | | 19.0 Cel 1101 105 | | 1102 106 ____________ | | 1103 107 | | 1104 108 19.3 Cel | | 1105 109 (stale) | | 1106 110 | | 1108 Figure 6: The client rejects a notification and thereby cancels the 1109 observation 1111 A.2. Proxy Examples 1113 CLIENT PROXY SERVER 1114 | | | 1115 | +----->| Header: GET 0x41015fb8 1116 | | GET | Token: 0x1a 1117 | | | Uri-Host: sensor.example 1118 | | | Uri-Path: status 1119 | | | Observe: 0 (register) 1120 | | | 1121 | |<-----+ Header: 2.05 0x61455fb8 1122 | | 2.05 | Token: 0x1a 1123 | | | Observe: 42 1124 | | | Max-Age: 60 1125 | | | Payload: "ready" 1126 | | | 1127 +----->| | Header: GET 0x41011633 1128 | GET | | Token: 0x9a 1129 | | | Proxy-Uri: coap://sensor.example/status 1130 | | | 1131 |<-----+ | Header: 2.05 0x61451633 1132 | 2.05 | | Token: 0x9a 1133 | | | Max-Age: 53 1134 | | | Payload: "ready" 1135 | | | 1136 | |<-----+ Header: 2.05 0x514505fc0 1137 | | 2.05 | Token: 0x1a 1138 | | | Observe: 135 1139 | | | Max-Age: 60 1140 | | | Payload: "busy" 1141 | | | 1142 +----->| | Header: GET 0x41011634 1143 | GET | | Token: 0x9b 1144 | | | Proxy-Uri: coap://sensor.example/status 1145 | | | 1146 |<-----+ | Header: 2.05 0x61451634 1147 | 2.05 | | Token: 0x9b 1148 | | | Max-Age: 49 1149 | | | Payload: "busy" 1150 | | | 1152 Figure 7: A proxy observes a resource to keep its cache up to date 1154 CLIENT PROXY SERVER 1155 | | | 1156 +----->| | Header: GET 0x41011635 1157 | GET | | Token: 0x6a 1158 | | | Proxy-Uri: coap://sensor.example/status 1159 | | | Observe: 0 (register) 1160 | | | 1161 |<- - -+ | Header: 0x60001635 1162 | | | 1163 | +----->| Header: GET 0x4101af90 1164 | | GET | Token: 0xaa 1165 | | | Uri-Host: sensor.example 1166 | | | Uri-Path: status 1167 | | | Observe: 0 (register) 1168 | | | 1169 | |<-----+ Header: 2.05 0x6145af90 1170 | | 2.05 | Token: 0xaa 1171 | | | Observe: 67 1172 | | | Max-Age: 60 1173 | | | Payload: "ready" 1174 | | | 1175 |<-----+ | Header: 2.05 0x4145af94 1176 | 2.05 | | Token: 0x6a 1177 | | | Observe: 17346 1178 | | | Max-Age: 60 1179 | | | Payload: "ready" 1180 | | | 1181 +- - ->| | Header: 0x6000af94 1182 | | | 1183 | |<-----+ Header: 2.05 0x51455a20 1184 | | 2.05 | Token: 0xaa 1185 | | | Observe: 157 1186 | | | Max-Age: 60 1187 | | | Payload: "busy" 1188 | | | 1189 |<-----+ | Header: 2.05 0x5145af9b 1190 | 2.05 | | Token: 0x6a 1191 | | | Observe: 17436 1192 | | | Max-Age: 60 1193 | | | Payload: "busy" 1194 | | | 1196 Figure 8: A client observes a resource through a proxy 1198 Appendix B. Changelog 1200 [Note to RFC Editor: Please remove this section before publication.] 1202 Changes from ietf-13 to ietf-14: 1204 o Updated references. 1206 Changes from ietf-12 to ietf-13: 1208 o Extended the Observe Option in requests to not only add but also 1209 remove an entry in the list of observers, depending on the option 1210 value. 1212 Note: The value of the Observe Option in a registration request 1213 may now be any sequence of bytes that encodes the unsigned 1214 integer 0, i.e., 0x'', 0x'00', 0x'00 00' or 0x'00 00 00'. 1216 o Removed the 7.31 Code for cancellation. 1218 Changes from ietf-11 to ietf-12: 1220 o Introduced the 7.31 Code to request the cancellation of a pending 1221 request. 1223 o Made the algorithm for superseding an outstanding transmission 1224 OPTIONAL. 1226 o Clarified that the entry in the list of observers is removed if 1227 the client fails to acknowledge a confirmable notification before 1228 the last retransmission attempt times out (#350). 1230 o Simplified the text on cancellation (#352) and the handling of 1231 Reset messages (#353). 1233 Changes from ietf-10 to ietf-11: 1235 o Pointed out that client and server clocks may differ in their 1236 realization of the SI second, and added robustness to the existing 1237 reordering scheme by reducing the maximum notification rate to 1238 32768 notifications per second (#341). 1240 Changes from ietf-09 to ietf-10: 1242 o Required consistent sequence numbers across requests (#333). 1244 o Clarified that a server needs to update the entry in the list of 1245 observers instead of adding a new entry if the endpoint/token pair 1246 is already present. 1248 o Allowed that a client uses a token that is currently in use to 1249 ensure that it's still in the list of observers. This is possible 1250 because sequence numbers are now consistent across requests and 1251 servers won't add a new entry for the same token. 1253 o Improved text on the transmission of non-confirmable notifications 1254 to match Section 3.1.2 of RFC 5405 more closely. 1256 o Updated examples to use UCUM units. 1258 o Moved Appendix B into the introduction. 1260 Changes from ietf-08 to ietf-09: 1262 o Removed the side effects of requests on existing observations. 1263 This includes removing that 1265 * the client can use a GET request to cancel an observation; 1267 * the server updates the entry in the list of observers instead 1268 of adding a new entry if the client is already present (#258, 1269 #281). 1271 o Clarified that a resource (and hence an observation relationship) 1272 is identified by the request options that are part of the Cache- 1273 Key (#258). 1275 o Clarified that a non-2.xx notification MUST NOT include an Observe 1276 Option. 1278 o Moved block-wise transfer of notifications to [I-D.ietf-core- 1279 block]. 1281 Changes from ietf-07 to ietf-08: 1283 o Expanded text on transmitting a notification while a previous 1284 transmission is pending (#242). 1286 o Changed reordering detection to use a fixed time span of 128 1287 seconds instead of EXCHANGE_LIFETIME (#276). 1289 o Removed the use of the freshness model to determine if the client 1290 is still on the list of observers. This includes removing that 1292 * the client assumes that it has been removed from the list of 1293 observers when Max-Age ends; 1295 * the server sets the Max-Age Option of a notification to a value 1296 that indicates when the server will send the next notification; 1298 * the server uses a number of retransmit attempts such that 1299 removing a client from the list of observers before Max-Age 1300 ends is avoided (#235); 1302 * the server may remove the client from all lists of observers 1303 when the transmission of a confirmable notification ultimately 1304 times out. 1306 o Changed that an unrecognized critical option in a request must 1307 actually have no effect on the state of any observation 1308 relationship to any resource, as the option could lead to a 1309 different target resource. 1311 o Clarified that client implementations must be prepared to receive 1312 each notification equally as a confirmable or a non-confirmable 1313 message, regardless of the message type of the request and of any 1314 previous notification. 1316 o Added a requirement for sending a confirmable notification at 1317 least every 24 hours before continuing with non-confirmable 1318 notifications (#221). 1320 o Added congestion control considerations from [I-D.bormann-core- 1321 congestion-control-02]. 1323 o Recommended that the client waits for a randomized time after the 1324 freshness of the latest notification expired before re- 1325 registering. This prevents that multiple clients observing a 1326 resource perform a GET request at the same time when the need to 1327 re-register arises. 1329 o Changed reordering detection from 'MAY' to 'SHOULD', as the goal 1330 of the protocol (to keep the observed state as closely in sync 1331 with the actual state as possible) is not optional. 1333 o Fixed the length of the Observe Option (3 bytes) in the table in 1334 Section 2. 1336 o Replaced the 'x' in the No-Cache-Key column in the table in 1337 Section 2 with a '-', as the Observe Option doesn't have the No- 1338 Cache-Key flag set, even though it is not part of the cache key. 1340 o Updated examples. 1342 Changes from ietf-06 to ietf-07: 1344 o Moved to 24-bit sequence numbers to allow for up to 15000 1345 notifications per second per client and resource (#217). 1347 o Re-numbered option number to use Unsafe/Safe and Cache-Key 1348 compliant numbers (#241). 1350 o Clarified how to react to a Reset message that is sent in reply to 1351 a non-confirmable notification (#225). 1353 o Clarified the semantics of the "obs" link target attribute (#236). 1355 Changes from ietf-05 to ietf-06: 1357 o Improved abstract and introduction to say that the protocol is 1358 about best effort and eventual consistency (#219). 1360 o Clarified that the value of the Observe Option in a request must 1361 have zero length. 1363 o Added requirement that the sequence number must be updated each 1364 time a server retransmits a notification. 1366 o Clarified that a server must remove a client from the list of 1367 observers when it receives a GET request with an unrecognized 1368 critical option. 1370 o Updated the text to use the endpoint concept from [I-D.ietf-core- 1371 coap] (#224). 1373 o Improved the reordering text (#223). 1375 Changes from ietf-04 to ietf-05: 1377 o Recommended that a client does not re-register while a new 1378 notification from the server is still likely to arrive. This is 1379 to avoid that the request of the client and the last notification 1380 after max-age cross over each other (#174). 1382 o Relaxed requirements when sending a Reset message in reply to non- 1383 confirmable notifications. 1385 o Added an implementation note about careless GET requests (#184). 1387 o Updated examples. 1389 Changes from ietf-03 to ietf-04: 1391 o Removed the "Max-OFE" Option. 1393 o Allowed a Reset message in reply to non-confirmable notifications. 1395 o Added a section on cancellation. 1397 o Updated examples. 1399 Changes from ietf-02 to ietf-03: 1401 o Separated client-side and server-side requirements. 1403 o Fixed uncertainty if client is still on the list of observers by 1404 introducing a liveliness model based on Max-Age and a new option 1405 called "Max-OFE" (#174). 1407 o Simplified the text on message reordering (#129). 1409 o Clarified requirements for intermediaries. 1411 o Clarified the combination of blockwise transfers with 1412 notifications (#172). 1414 o Updated examples to show how the state observed by the client 1415 becomes eventually consistent with the actual state on the server. 1417 o Added examples for parameterization of observable resource. 1419 Changes from ietf-01 to ietf-02: 1421 o Removed the requirement of periodic refreshing (#126). 1423 o The new "Observe" Option replaces the "Lifetime" Option. 1425 o Introduced a new mechanism to detect message reordering. 1427 o Changed 2.00 (OK) notifications to 2.05 (Content) notifications. 1429 Changes from ietf-00 to ietf-01: 1431 o Changed terminology from "subscriptions" to "observation 1432 relationships" (#33). 1434 o Changed the name of the option to "Lifetime". 1436 o Clarified establishment of observation relationships. 1438 o Clarified that an observation is only identified by the URI of the 1439 observed resource and the identity of the client (#66). 1441 o Clarified rules for establishing observation relationships (#68). 1443 o Clarified conditions under which an observation relationship is 1444 terminated. 1446 o Added explanation on how clients can terminate an observation 1447 relationship before the lifetime ends (#34). 1449 o Clarified that the overriding objective for notifications is 1450 eventual consistency of the actual and the observed state (#67). 1452 o Specified how a server needs to deal with clients not 1453 acknowledging confirmable messages carrying notifications (#69). 1455 o Added a mechanism to detect message reordering (#35). 1457 o Added an explanation of how notifications can be cached, 1458 supporting both the freshness and the validation model (#39, #64). 1460 o Clarified that non-GET requests do not affect observation 1461 relationships, and that GET requests without "Lifetime" Option 1462 affecting relationships is by design (#65). 1464 o Described interaction with blockwise transfers (#36). 1466 o Added Resource Discovery section (#99). 1468 o Added IANA Considerations. 1470 o Added Security Considerations (#40). 1472 o Added examples (#38). 1474 Author's Address 1476 Klaus Hartke 1477 Universitaet Bremen TZI 1478 Postfach 330440 1479 Bremen D-28359 1480 Germany 1482 Phone: +49-421-218-63905 1483 EMail: hartke@tzi.org