idnits 2.17.1 draft-ietf-core-observe-16.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 (December 30, 2014) is 3398 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 926, 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 December 30, 2014 5 Expires: July 3, 2015 7 Observing Resources in CoAP 8 draft-ietf-core-observe-16 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 July 3, 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. 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: 0 | 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 from 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 in the resource and is 222 removed by the 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 The Observe Option has the following properties. Its meaning depends 309 on whether it is included in a GET request or in a response. 311 +-----+---+---+---+---+---------+--------+--------+---------+ 312 | No. | C | U | N | R | Name | Format | Length | Default | 313 +-----+---+---+---+---+---------+--------+--------+---------+ 314 | 6 | | x | - | | Observe | uint | 0-3 B | (none) | 315 +-----+---+---+---+---+---------+--------+--------+---------+ 317 C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable 319 Table 1: The Observe Option 321 When included in a GET request, the Observe Option extends the GET 322 method so it does not only retrieve a current representation of the 323 target resource, but also requests the server to add or remove an 324 entry in the list of observers of the resource, depending on the 325 option value. The list entry consists of the client endpoint and the 326 token specified by the client in the request. Possible values are: 328 0 (register) adds the entry to the list, if not present; 330 1 (deregister) removes the entry from the list, if present. 332 The Observe Option is not critical for processing the request. If 333 the server is unwilling or unable to add a new entry to the list of 334 observers, then the request falls back to a normal GET request, and 335 the response does not include the Observe Option. 337 The Observe Option is not part of the cache-key: a cacheable response 338 obtained with an Observe Option in the request can be used to satisfy 339 a request without an Observe Option, and vice versa. When a stored 340 response with an Observe Option is used to satisfy a normal GET 341 request, the option MUST be removed before the response is returned. 343 When included in a response, the Observe Option identifies the 344 message as a notification. This implies that a matching entry exists 345 in the list of observers and that the server will notify the client 346 of changes to the resource state. The option value is a sequence 347 number for reordering detection (see Section 3.4 and Section 4.4). 349 The value of the Observe Option is encoded as an unsigned integer in 350 network byte order using a variable number of bytes ('uint' option 351 format); see Section 3.2 of RFC 7252 [RFC7252]. 353 3. Client-side Requirements 355 3.1. Request 357 A client registers its interest in a resource by issuing a GET 358 request with an Observe Option set to 0 (register). If the server 359 returns a 2.xx response that includes an Observe Option as well, the 360 server has successfully added an entry with the client endpoint and 361 request token to the list of observers of the target resource and the 362 client will be notified of changes to the resource state. 364 Like a fresh response can be used to satisfy a request without 365 contacting the server, the stream of updates resulting from one 366 observation request can be used to satisfy another (observation or 367 normal GET) request if the target resource is the same. A client 368 MUST aggregate such requests and MUST NOT register more than once for 369 the same target resource. The target resource is identified by all 370 options in the request that are part of the cache-key. This 371 includes, for example, the full request URI and the Accept Option. 373 3.2. Notifications 375 Notifications are additional responses sent by the server in reply to 376 the single extended GET request that created the registration. Each 377 notification includes the token specified by the client in the 378 request. The only difference between a notification and a normal 379 response is the presence of the Observe Option. 381 Notifications typically have a 2.05 (Content) response code. They 382 include an Observe Option with a sequence number for reordering 383 detection (see Section 3.4), and a payload in the same Content-Format 384 as the initial response. If the client included one or more ETag 385 Options in the GET request (see Section 3.3), notifications can have 386 a 2.03 (Valid) response code rather than a 2.05 (Content) response 387 code. Such notifications include an Observe Option with a sequence 388 number but no payload. 390 In the event that the resource changes in a way that would cause a 391 normal GET request at that time to return a non-2.xx response (for 392 example, when the resource is deleted), the server sends a 393 notification with an appropriate response code (such as 4.04 Not 394 Found) and removes the client's entry from the list of observers of 395 the resource. Non-2.xx responses do not include an Observe Option. 397 3.3. Caching 399 As notifications are just additional responses to a GET request, 400 notifications partake in caching as defined in Section 5.6 of RFC 401 7252 [RFC7252]. Both the freshness model and the validation model 402 are supported. 404 3.3.1. Freshness 406 A client MAY store a notification like a response in its cache and 407 use a stored notification that is fresh without contacting the 408 server. Like a response, a notification is considered fresh while 409 its age is not greater than the value indicated by the Max-Age Option 410 (and no newer notification/response has been received). 412 The server will do its best to keep the resource state observed by 413 the client as closely in sync with the actual state as possible. 414 However, a client cannot rely on observing every single state that a 415 resource might go through. For example, if the network is congested 416 or the state changes more frequently than the network can handle, the 417 server can skip notifications for any number of intermediate states. 419 The server uses the Max-Age Option to indicate an age up to which it 420 is acceptable that the observed state and the actual state are 421 inconsistent. If the age of the latest notification becomes greater 422 than its indicated Max-Age, then the client MUST NOT assume that the 423 enclosed representation reflects the actual resource state. 425 To make sure it has a current representation and/or to re-register 426 its interest in a resource, a client MAY issue a new GET request with 427 the same token as the original at any time. All options MUST be 428 identical to those in the original request, except for the set of 429 ETag Options. It is RECOMMENDED that the client does not issue the 430 request while it still has a fresh notification/response for the 431 resource in its cache. Additionally, the client SHOULD at least wait 432 for a random amount of time between 5 and 15 seconds after Max-Age 433 expired to reduce collisions with other clients. 435 3.3.2. Validation 437 When a client has one or more notifications stored in its cache for a 438 resource, it can use the ETag Option in the GET request to give the 439 server an opportunity to select a stored notification to be used. 441 The client MAY include an ETag Option for each stored response that 442 is applicable in the GET request. Whenever the observed resource 443 changes to a representation identified by one of the ETag Options, 444 the server can select a stored response by sending a 2.03 (Valid) 445 notification with an appropriate ETag Option instead of a 2.05 446 (Content) notification. 448 A client implementation needs to keep all candidate responses in its 449 cache until it is no longer interested in the target resource or it 450 re-registers with a new set of entity-tags. 452 3.4. Reordering 454 Messages with notifications can arrive in a different order than they 455 were sent. Since the goal is to keep the observed state as closely 456 in sync with the actual state as possible, a client MUST consider the 457 notification that was sent most recently as the freshest, regardless 458 of the order of arrival. 460 To provide an order among notifications for the client, the server 461 sets the value of the Observe Option in each notification to the 24 462 least-significant bits of a strictly increasing sequence number. An 463 incoming notification was sent more recently than the freshest 464 notification so far when one of the following conditions is met: 466 (V1 < V2 and V2 - V1 < 2^23) or 467 (V1 > V2 and V1 - V2 > 2^23) or 468 (T2 > T1 + 128 seconds) 470 where V1 is the value of the Observe Option in the freshest 471 notification so far, V2 the value of the Observe Option in the 472 incoming notification, T1 a client-local timestamp for the freshest 473 notification so far, and T2 a client-local timestamp for the incoming 474 notification. 476 Design Note: The first two conditions verify that V1 is less than V2 477 in 24-bit serial number arithmetic [RFC1982]. The third condition 478 ensures that, if the server is generating serial numbers based on 479 a local clock, the time elapsed between the two incoming messages 480 is not so large that the difference between V1 and V2 has become 481 larger than the largest integer that it is meaningful to add to a 482 24-bit serial number; in other words, after 128 seconds have 483 elapsed without any notification, a client does not need to check 484 the sequence numbers to assume that an incoming notification was 485 sent more recently than the freshest notification it has received 486 so far. 488 The duration of 128 seconds was chosen as a nice round number 489 greater than MAX_LATENCY (Section 4.8.2 of RFC 7252 [RFC7252]). 491 3.5. Transmission 493 A notification can be confirmable or non-confirmable, i.e., it can be 494 sent in a confirmable or a non-confirmable message. The message type 495 used for a notification is independent of the type used for the 496 request and of any previous notification. 498 If a client does not recognize the token in a confirmable 499 notification, it MUST NOT acknowledge the message and SHOULD reject 500 it with a Reset message; otherwise, the client MUST acknowledge the 501 message as usual. In the case of a non-confirmable notification, 502 rejecting the message with a Reset message is OPTIONAL. 504 An acknowledgement message signals to the server that the client is 505 alive and interested in receiving further notifications; if the 506 server does not receive an acknowledgement in reply to a confirmable 507 notification, it will assume that the client is no longer interested 508 and will eventually remove the associated entry from the list of 509 observers. 511 3.6. Cancellation 513 A client that is no longer interested in receiving notifications for 514 a resource can simply "forget" the observation. When the server then 515 sends the next notification, the client will not recognize the token 516 in the message and thus will return a Reset message. This causes the 517 server to remove the associated entry from the list of observers. 518 The entries in lists of observers are effectively "garbage collected" 519 by the server. 521 Implementation Note: Due to potential message loss, the Reset 522 message may not reach the server. The client may therefore have 523 to reject multiple notifications, each with one Reset message, 524 until the server finally removes the associated entry from the 525 list of observers and stops sending notifications. 527 In some circumstances, it may be desirable to cancel an observation 528 and release the resources allocated by the server to it more eagerly. 529 In this case, a client MAY explicitly deregister by issuing a GET 530 request which has the Token field set to the token of the observation 531 to be cancelled and includes an Observe Option with the value set to 532 1 (deregister). All other options MUST be identical to those in the 533 registration request, except for the set of ETag Options. When the 534 server receives such a request, it will remove any matching entry 535 from the list of observers and process the GET request as usual. 537 4. Server-side Requirements 539 4.1. Request 541 A GET request with an Observe Option set to 0 (register) requests the 542 server not only to return a current representation of the target 543 resource, but also to add the client to the list of observers of that 544 resource. Upon success, the server returns a current representation 545 of the resource and MUST keep this representation updated (as 546 described in Section 1.3) as long as the client is on the list of 547 observers. 549 The entry in the list of observers is keyed by the client endpoint 550 and the token specified by the client in the request. If an entry 551 with a matching endpoint/token pair is already present in the list 552 (which, for example, happens when the client wishes to reinforce its 553 interest in a resource), the server MUST NOT add a new entry but MUST 554 replace or update the existing one. 556 A server that is unable or unwilling to add a new entry to the list 557 of observers of a resource MAY silently ignore the registration 558 request and process the GET request as usual. The resulting response 559 MUST NOT include an Observe Option, the absence of which signals to 560 the client that it will not be notified of changes to the resource 561 and, e.g., needs to poll the resource for its state instead. 563 If the Observe Option in a GET request is set to 1 (deregister), then 564 the server MUST remove any existing entry with a matching endpoint/ 565 token pair from the list of observers and process the GET request as 566 usual. The resulting response MUST NOT include an Observe Option. 568 4.2. Notifications 570 A client is notified of changes to the resource state by additional 571 responses sent by the server in reply to the GET request. Each such 572 notification response (including the initial response) MUST echo the 573 token specified by the client in the GET request. If there are 574 multiple entries in the list of observers, the order in which the 575 clients are notified is not defined; the server is free to use any 576 method to determine the order. 578 A notification SHOULD have a 2.05 (Content) or 2.03 (Valid) response 579 code. However, in the event that the state of a resource changes in 580 a way that would cause a normal GET request at that time to return a 581 non-2.xx response (for example, when the resource is deleted), the 582 server SHOULD notify the client by sending a notification with an 583 appropriate response code (such as 4.04 Not Found) and subsequently 584 MUST remove the associated entry from the list of observers of the 585 resource. 587 The Content-Format specified in a 2.xx notification MUST be the same 588 as the one used in the initial response to the GET request. If the 589 server is unable to continue sending notifications in this format, it 590 SHOULD send a notification with a 4.06 (Not Acceptable) response code 591 and subsequently MUST remove the associated entry from the list of 592 observers of the resource. 594 A 2.xx notification MUST include an Observe Option with a sequence 595 number as specified in Section 4.4 below; a non-2.xx notification 596 MUST NOT include an Observe Option. 598 4.3. Caching 600 As notifications are just additional responses sent by the server in 601 reply to a GET request, they are subject to caching as defined in 602 Section 5.6 of RFC 7252 [RFC7252]. 604 4.3.1. Freshness 606 After returning the initial response, the server MUST keep the 607 resource state that is observed by the client as closely in sync with 608 the actual resource state as possible. 610 Since becoming out of sync at times cannot be avoided, the server 611 MUST indicate for each representation an age up to which it is 612 acceptable that the observed state and the actual state are 613 inconsistent. This age is application-dependent and MUST be 614 specified in notifications using the Max-Age Option. 616 When the resource does not change and the client has a current 617 representation, the server does not need to send a notification. 618 However, if the client does not receive a notification, the client 619 cannot tell if the observed state and the actual state are still in 620 sync. Thus, when the age of the latest notification becomes greater 621 than its indicated Max-Age, the client no longer has a usable 622 representation of the resource state. The server MAY wish to prevent 623 that by sending a new notification with the unchanged representation 624 and a new Max-Age just before the Max-Age indicated earlier expires. 626 4.3.2. Validation 628 A client can include a set of entity-tags in its request using the 629 ETag Option. When a observed resource changes its state and the 630 origin server is about to send a 2.05 (Content) notification, then, 631 whenever that notification has an entity-tag in the set of entity- 632 tags specified by the client, the server MAY send a 2.03 (Valid) 633 response with an appropriate ETag Option instead. 635 4.4. Reordering 637 Because messages can get reordered, the client needs a way to 638 determine if a notification arrived later than a newer notification. 639 For this purpose, the server MUST set the value of the Observe Option 640 of each notification it sends to the 24 least-significant bits of a 641 strictly increasing sequence number. The sequence number MAY start 642 at any value and MUST NOT increase so fast that it increases by more 643 than 2^23 within less than 256 seconds. 645 The sequence number selected for a notification MUST be greater than 646 that of any preceding notification sent to the same client with the 647 same token for the same resource. The value of the Observe Option 648 MUST be current at the time of transmission; if a notification is 649 retransmitted, the server MUST update the value of the option to the 650 sequence number that is current at that time before retransmission. 652 Implementation Note: A simple implementation that satisfies the 653 requirements is to obtain a timestamp from a local clock. The 654 sequence number then is the timestamp in ticks, where 1 tick = 655 (256 seconds)/(2^23) = 30.52 microseconds. It is not necessary 656 that the clock reflects the current time/date. 658 Another valid implementation is to store a 24-bit unsigned integer 659 variable per resource and increment this variable each time the 660 resource undergoes a change of state (provided that the resource 661 changes its state less than 2^23 times in the first 256 seconds 662 after every state change). This removes the need to update the 663 value of the Observe Option on retransmission when the resource 664 state did not change. 666 Design Note: The choice of a 24-bit option value and a time span of 667 256 seconds theoretically allows for a notification rate of up to 668 65536 notifications per second. Constrained nodes often have 669 rather imprecise clocks, though, and inaccuracies of the client 670 and server side may cancel out or add in effect. Therefore, the 671 maximum notification rate is reduced to 32768 notifications per 672 second. This is still well beyond the highest known design 673 objective of around 1 kHz (most CoAP applications will be several 674 orders of magnitude below that), but allows total clock 675 inaccuracies of up to -50/+100 %. 677 4.5. Transmission 679 A notification can be sent in a confirmable or a non-confirmable 680 message. The message type used is typically application-dependent 681 and may be determined by the server for each notification 682 individually. 684 For example, for resources that change in a somewhat predictable or 685 regular fashion, notifications can be sent in non-confirmable 686 messages; for resources that change infrequently, notifications can 687 be sent in confirmable messages. The server can combine these two 688 approaches depending on the frequency of state changes and the 689 importance of individual notifications. 691 A server MAY choose to skip sending a notification if it knows that 692 it will send another notification soon, for example, when the state 693 of a resource is changing frequently. It also MAY choose to send 694 more than one notification for the same resource state. However, 695 above all, the server MUST ensure that a client in the list of 696 observers of a resource eventually observes the latest state if the 697 resource does not undergo a new change in state. 699 For example, when state changes occur in bursts, the server can skip 700 some notifications, send the notifications in non-confirmable 701 messages, and make sure that the client observes the latest state 702 change by repeating the last notification in a confirmable message 703 when the burst is over. 705 The client's acknowledgement of a confirmable notification signals 706 that the client is interested in receiving further notifications. If 707 a client rejects a confirmable or non-confirmable notification with a 708 Reset message, or if the last attempt to retransmit a confirmable 709 notification times out, then the client is considered no longer 710 interested and the server MUST remove the associated entry from the 711 list of observers. 713 Implementation Note: To properly process a Reset message that 714 rejects a non-confirmable notification, a server needs to remember 715 the message IDs of the non-confirmable notifications it sends. 716 This may be challenging for a server with constrained resources. 717 However, since Reset messages are transmitted unreliably, the 718 client must be prepared that its Reset messages aren't received by 719 the server. A server thus can always pretend that a Reset message 720 rejecting a non-confirmable notification was lost. If a server 721 does this, it could accelerate cancellation by sending the 722 following notifications to that client in confirmable messages. 724 A server that transmits notifications mostly in non-confirmable 725 messages MUST send a notification in a confirmable message instead of 726 a non-confirmable message at least every 24 hours. This prevents a 727 client that went away or is no longer interested from remaining in 728 the list of observers indefinitely. 730 4.5.1. Congestion Control 732 Basic congestion control for CoAP is provided by the exponential 733 back-off mechanism in Section 4.2 of RFC 7252 [RFC7252] and the 734 limitations in Section 4.7 of RFC 7252 [RFC7252]. However, CoAP 735 places the responsibility of congestion control for simple request/ 736 response interactions only on the clients: rate limiting request 737 transmission implicitly controls the transmission of the responses. 738 When a single request yields a potentially infinite number of 739 notifications, additional responsibility needs to be placed on the 740 server. 742 In order not to cause congestion, servers MUST strictly limit the 743 number of simultaneous outstanding notifications/responses that they 744 transmit to a given client to NSTART (1 by default; see Section 4.7 745 of RFC 7252 [RFC7252]). An outstanding notification/response is 746 either a confirmable message for which an acknowledgement has not yet 747 been received and whose last retransmission attempt has not yet timed 748 out, or a non-confirmable message for which the waiting time that 749 results from the following rate limiting rules has not yet elapsed. 751 The server SHOULD NOT send more than one non-confirmable notification 752 per round-trip time (RTT) to a client on average. If the server 753 cannot maintain an RTT estimate for a client, it SHOULD NOT send more 754 than one non-confirmable notification every 3 seconds, and SHOULD use 755 an even less aggressive rate when possible (see also Section 3.1.2 of 756 RFC 5405 [RFC5405]). 758 Further congestion control optimizations and considerations are 759 expected in the future with advanced CoAP congestion control 760 mechanisms. 762 4.5.2. Advanced Transmission 764 The state of an observed resource may change while the number of the 765 number of simultaneous outstanding notifications/responses to a 766 client on the list of observers is greater than or equal to NSTART. 767 In this case, the server cannot notify the client of the new resource 768 state immediately but has to wait for an outstanding notification/ 769 response to complete first. 771 If there exists an outstanding notification/response that the server 772 transmits to the client and that pertains to the changed resource, 773 then it is desirable for the server to stop working towards getting 774 the representation of the old resource state to the client, and to 775 start transmitting the current representation to the client instead, 776 so the resource state observed by the client stays closer in sync 777 with the actual state at the server. 779 For this purpose, the server MAY optimize the transmission process by 780 aborting the transmission of the old notification (but not before the 781 current transmission attempt completed) and starting a new 782 transmission for the new notification (but with the retransmission 783 timer and counter of the aborted transmission retained). 785 In more detail, a server MAY supersede an outstanding transmission 786 that pertains to an observation as follows: 788 1. Wait for the current (re-)transmission attempt to be 789 acknowledged, rejected or to time out (confirmable transmission); 790 or wait for the waiting time to elapse or the transmission to be 791 rejected (non-confirmable transmission). 793 2. If the transmission is rejected or it was the last attempt to 794 retransmit a notification, remove the associated entry from the 795 list of observers of the observed resource. 797 3. If the entry is still in the list of observers, start to transmit 798 a new notification with a representation of the current resource 799 state. Should the resource have changed its state more than once 800 in the meantime, the notifications for the intermediate states 801 are silently skipped. 803 4. The new notification is transmitted with a new Message ID and the 804 following transmission parameters: If the previous 805 (re-)transmission attempt timed out, retain its transmission 806 parameters, increment the retransmission counter and double the 807 timeout; otherwise, initialize the transmission parameters as 808 usual (see Section 4.2 of RFC 7252 [RFC7252]). 810 It is possible that the server later receives an acknowledgement for 811 a confirmable notification that it superseded this way. Even though 812 this does not signal consistency, it is valuable in that it signals 813 the client's further interest in the resource. The server therefore 814 should avoid inadvertently removing the associated entry from the 815 list of observers. 817 5. Intermediaries 819 A client may be interested in a resource in the namespace of a server 820 that is reached through a chain of one or more CoAP intermediaries. 821 In this case, the client registers its interest with the first 822 intermediary towards the server, acting as if it was communicating 823 with the server itself, as specified in Section 3. It is the task of 824 this intermediary to provide the client with a current representation 825 of the target resource and to keep the representation updated upon 826 changes to the resource state, as specified in Section 4. 828 To perform this task, the intermediary SHOULD make use of the 829 protocol specified in this document, taking the role of the client 830 and registering its own interest in the target resource with the next 831 hop towards the server. If the response returned by the next hop 832 doesn't include an Observe Option, the intermediary MAY resort to 833 polling the next hop or MAY itself return a response without an 834 Observe Option. 836 The communication between each pair of hops is independent; each hop 837 in the server role MUST determine individually how many notifications 838 to send, of which message type, and so on. Each hop MUST generate 839 its own values for the Observe Option in notifications, and MUST set 840 the value of the Max-Age Option according to the age of the local 841 current representation. 843 If two or more clients have registered their interest in a resource 844 with an intermediary, the intermediary MUST register itself only once 845 with the next hop and fan out the notifications it receives to all 846 registered clients. This relieves the next hop from sending the same 847 notifications multiple times and thus enables scalability. 849 An intermediary is not required to act on behalf of a client to 850 observe a resource; an intermediary MAY observe a resource, for 851 example, just to keep its own cache up to date. 853 See Appendix A.2 for examples. 855 6. Web Linking 857 A web link [RFC5988] to a resource accessible over CoAP (for example, 858 in a link-format document [RFC6690]) MAY include the target attribute 859 "obs". 861 The "obs" attribute, when present, is a hint indicating that the 862 destination of a link is useful for observation and thus, for 863 example, should have a suitable graphical representation in a user 864 interface. Note that this is only a hint; it is not a promise that 865 the Observe Option can actually be used to perform the observation. 866 A client may need to resort to polling the resource if the Observe 867 Option is not returned in the response to the GET request. 869 A value MUST NOT be given for the "obs" attribute; any present value 870 MUST be ignored by parsers. The "obs" attribute MUST NOT appear more 871 than once in a given link-value; occurrences after the first MUST be 872 ignored by parsers. 874 7. Security Considerations 876 The security considerations in Section 11 of the CoAP specification 877 [RFC7252] apply. 879 Observing resources can dramatically increase the negative effects of 880 amplification attacks. That is, not only can notifications messages 881 be much larger than the request message, but the nature of the 882 protocol can cause a significant number of notifications to be 883 generated. Without client authentication, a server therefore MUST 884 strictly limit the number of notifications that it sends between 885 receiving acknowledgements that confirm the actual interest of the 886 client in the data; i.e., any notifications sent in non-confirmable 887 messages MUST be interspersed with confirmable messages. (An 888 attacker may still spoof the acknowledgements if the confirmable 889 messages are sufficiently predictable.) 891 The protocol follows a best-effort approach for keeping the state 892 observed by a client and the actual resource state at a server in 893 sync. This may have the client and the server become out of sync at 894 times. Depending on the sensitivity of the observed resource, 895 operating on an old state might be a security threat. The client 896 therefore must be careful not to use a representation after its Max- 897 Age expires, and the server must set the Max-Age Option to a sensible 898 value. 900 As with any protocol that creates state, attackers may attempt to 901 exhaust the resources that the server has available for maintaining 902 the list of observers for each resource. Servers may want to apply 903 access controls to this creation of state. As degraded behavior, the 904 server can always fall back to processing the request as a normal GET 905 request (without an Observe Option) if it is unwilling or unable to 906 add a client to the list of observers of a resource, including if 907 system resources are exhausted or nearing exhaustion. 909 Intermediaries must be careful to ensure that notifications cannot be 910 employed to create a loop. A simple way to break any loops is to 911 employ caches for forwarding notifications in intermediaries. 913 Resources can be observed over DTLS-secured CoAP using any of the 914 security modes described in Section 9 of RFC 7252. The use of DTLS 915 is indicated by the "coaps" URI scheme. All notifications resulting 916 from a GET request with an Observe Option MUST be returned within the 917 same epoch of the same connection as the request. 919 8. IANA Considerations 921 The following entry is added to the CoAP Option Numbers registry: 923 +--------+---------+-----------+ 924 | Number | Name | Reference | 925 +--------+---------+-----------+ 926 | 6 | Observe | [RFCXXXX] | 927 +--------+---------+-----------+ 929 [Note to RFC Editor: Please replace XXXX with the RFC number of this 930 specification.] 932 9. Acknowledgements 934 Carsten Bormann was an original author of this draft and is 935 acknowledged for significant contribution to this document. 937 Thanks to Daniele Alessandrelli, Jari Arkko, Peter A. Bigot, Angelo 938 P. Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank, 939 Bert Greevenbosch, Jeroen Hoebeke, Cullen Jennings, Matthias 940 Kovatsch, Barry Leiba, Salvatore Loreto, Charles Palmer, Akbar 941 Rahman, Zach Shelby, and Floris Van den Abeele for helpful comments 942 and discussions that have shaped the document. 944 This work was supported in part by Klaus Tschira Foundation, Intel, 945 Cisco, and Nokia. 947 10. References 948 10.1. Normative References 950 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 951 Requirement Levels", BCP 14, RFC 2119, March 1997. 953 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 955 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 956 Application Protocol (CoAP)", RFC 7252, June 2014. 958 10.2. Informative References 960 [GOF] Gamma, E., Helm, R., Johnson, R., and J. Vlissides, 961 "Design Patterns: Elements of Reusable Object-Oriented 962 Software", Addison-Wesley, Reading, MA, USA, 963 November 1994. 965 [REST] Fielding, R., "Architectural Styles and the Design of 966 Network-based Software Architectures", Ph.D. Dissertation, 967 University of California, Irvine, 2000, . 971 [RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982, 972 August 1996. 974 [RFC5405] Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines 975 for Application Designers", BCP 145, RFC 5405, 976 November 2008. 978 [RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes 979 to an HTTP Resource", RFC 5989, October 2010. 981 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 982 "Known Issues and Best Practices for the Use of Long 983 Polling and Streaming in Bidirectional HTTP", RFC 6202, 984 April 2011. 986 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 987 Format", RFC 6690, August 2012. 989 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 990 Constrained-Node Networks", RFC 7228, May 2014. 992 [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol 993 (HTTP/1.1): Message Syntax and Routing", RFC 7230, 994 June 2014. 996 Appendix A. Examples 998 A.1. Client/Server Examples 1000 Observed CLIENT SERVER Actual 1001 t State | | State 1002 ____________ | | ____________ 1003 1 | | 1004 2 unknown | | 18.5 Cel 1005 3 +----->| Header: GET 0x41011633 1006 4 | GET | Token: 0x4a 1007 5 | | Uri-Path: temperature 1008 6 | | Observe: 0 (register) 1009 7 | | 1010 8 | | 1011 9 ____________ |<-----+ Header: 2.05 0x61451633 1012 10 | 2.05 | Token: 0x4a 1013 11 18.5 Cel | | Observe: 9 1014 12 | | Max-Age: 15 1015 13 | | Payload: "18.5 Cel" 1016 14 | | 1017 15 | | ____________ 1018 16 ____________ |<-----+ Header: 2.05 0x51457b50 1019 17 | 2.05 | 19.2 Cel Token: 0x4a 1020 18 19.2 Cel | | Observe: 16 1021 29 | | Max-Age: 15 1022 20 | | Payload: "19.2 Cel" 1023 21 | | 1025 Figure 3: A client registers and receives one notification of the 1026 current state and one of a new state upon a state change 1027 Observed CLIENT SERVER Actual 1028 t State | | State 1029 ____________ | | ____________ 1030 22 | | 1031 23 19.2 Cel | | 19.2 Cel 1032 24 | | ____________ 1033 25 | X----+ Header: 2.05 0x51457b51 1034 26 | 2.05 | 19.7 Cel Token: 0x4a 1035 27 | | Observe: 25 1036 28 | | Max-Age: 15 1037 29 | | Payload: "19.7 Cel" 1038 30 | | 1039 31 ____________ | | 1040 32 | | 1041 33 19.2 Cel | | 1042 34 (stale) | | 1043 35 | | 1044 36 | | 1045 37 | | 1046 38 +----->| Header: GET 0x41011634 1047 39 | GET | Token: 0xb2 1048 40 | | Uri-Path: temperature 1049 41 | | Observe: 0 (register) 1050 42 | | 1051 43 | | 1052 44 ____________ |<-----+ Header: 2.05 0x61451634 1053 45 | 2.05 | Token: 0xb2 1054 46 19.7 Cel | | Observe: 44 1055 47 | | Max-Age: 15 1056 48 | | ETag: 0x78797a7a79 1057 49 | | Payload: "19.7 Cel" 1058 50 | | 1060 Figure 4: The client re-registers after Max-Age ends 1062 Observed CLIENT SERVER Actual 1063 t State | | State 1064 ____________ | | ____________ 1065 51 | | 1066 52 19.7 Cel | | 19.7 Cel 1067 53 | | 1068 54 | | ____________ 1069 55 | crash 1070 56 | 1071 57 | 1072 58 | 1073 59 ____________ | 1074 60 | 1075 61 19.7 Cel | 1076 62 (stale) | 1077 63 | reboot____________ 1078 64 | | 1079 65 | | 20.0 Cel 1080 66 | | 1081 67 +----->| Header: GET 0x41011635 1082 68 | GET | Token: 0xf9 1083 69 | | Uri-Path: temperature 1084 70 | | Observe: 0 (register) 1085 71 | | ETag: 0x78797a7a79 1086 72 | | 1087 73 | | 1088 74 ____________ |<-----+ Header: 2.05 0x61451635 1089 75 | 2.05 | Token: 0xf9 1090 76 20.0 Cel | | Observe: 74 1091 77 | | Max-Age: 15 1092 78 | | Payload: "20.0 Cel" 1093 79 | | 1094 80 | | ____________ 1095 81 ____________ |<-----+ Header: 2.03 0x5143aa0c 1096 82 | 2.03 | 19.7 Cel Token: 0xf9 1097 83 19.7 Cel | | Observe: 81 1098 84 | | ETag: 0x78797a7a79 1099 85 | | Max-Age: 15 1100 86 | | 1102 Figure 5: The client re-registers and gives the server the 1103 opportunity to select a stored response 1105 Observed CLIENT SERVER Actual 1106 t State | | State 1107 ____________ | | ____________ 1108 87 | | 1109 88 19.7 Cel | | 19.7 Cel 1110 89 | | 1111 90 | | ____________ 1112 91 ____________ |<-----+ Header: 2.05 0x4145aa0f 1113 92 | 2.05 | 19.3 Cel Token: 0xf9 1114 93 19.3 Cel | | Observe: 91 1115 94 | | Max-Age: 15 1116 95 | | Payload: "19.3 Cel" 1117 96 | | 1118 97 | | 1119 98 +- - ->| Header: 0x7000aa0f 1120 99 | | 1121 100 | | 1122 101 | | 1123 102 | | ____________ 1124 103 | | 1125 104 | | 19.0 Cel 1126 105 | | 1127 106 ____________ | | 1128 107 | | 1129 108 19.3 Cel | | 1130 109 (stale) | | 1131 110 | | 1133 Figure 6: The client rejects a notification and thereby cancels the 1134 observation 1136 A.2. Proxy Examples 1138 CLIENT PROXY SERVER 1139 | | | 1140 | +----->| Header: GET 0x41015fb8 1141 | | GET | Token: 0x1a 1142 | | | Uri-Host: sensor.example 1143 | | | Uri-Path: status 1144 | | | Observe: 0 (register) 1145 | | | 1146 | |<-----+ Header: 2.05 0x61455fb8 1147 | | 2.05 | Token: 0x1a 1148 | | | Observe: 42 1149 | | | Max-Age: 60 1150 | | | Payload: "ready" 1151 | | | 1152 +----->| | Header: GET 0x41011633 1153 | GET | | Token: 0x9a 1154 | | | Proxy-Uri: coap://sensor.example/status 1155 | | | 1156 |<-----+ | Header: 2.05 0x61451633 1157 | 2.05 | | Token: 0x9a 1158 | | | Max-Age: 53 1159 | | | Payload: "ready" 1160 | | | 1161 | |<-----+ Header: 2.05 0x514505fc0 1162 | | 2.05 | Token: 0x1a 1163 | | | Observe: 135 1164 | | | Max-Age: 60 1165 | | | Payload: "busy" 1166 | | | 1167 +----->| | Header: GET 0x41011634 1168 | GET | | Token: 0x9b 1169 | | | Proxy-Uri: coap://sensor.example/status 1170 | | | 1171 |<-----+ | Header: 2.05 0x61451634 1172 | 2.05 | | Token: 0x9b 1173 | | | Max-Age: 49 1174 | | | Payload: "busy" 1175 | | | 1177 Figure 7: A proxy observes a resource to keep its cache up to date 1179 CLIENT PROXY SERVER 1180 | | | 1181 +----->| | Header: GET 0x41011635 1182 | GET | | Token: 0x6a 1183 | | | Proxy-Uri: coap://sensor.example/status 1184 | | | Observe: 0 (register) 1185 | | | 1186 |<- - -+ | Header: 0x60001635 1187 | | | 1188 | +----->| Header: GET 0x4101af90 1189 | | GET | Token: 0xaa 1190 | | | Uri-Host: sensor.example 1191 | | | Uri-Path: status 1192 | | | Observe: 0 (register) 1193 | | | 1194 | |<-----+ Header: 2.05 0x6145af90 1195 | | 2.05 | Token: 0xaa 1196 | | | Observe: 67 1197 | | | Max-Age: 60 1198 | | | Payload: "ready" 1199 | | | 1200 |<-----+ | Header: 2.05 0x4145af94 1201 | 2.05 | | Token: 0x6a 1202 | | | Observe: 17346 1203 | | | Max-Age: 60 1204 | | | Payload: "ready" 1205 | | | 1206 +- - ->| | Header: 0x6000af94 1207 | | | 1208 | |<-----+ Header: 2.05 0x51455a20 1209 | | 2.05 | Token: 0xaa 1210 | | | Observe: 157 1211 | | | Max-Age: 60 1212 | | | Payload: "busy" 1213 | | | 1214 |<-----+ | Header: 2.05 0x5145af9b 1215 | 2.05 | | Token: 0x6a 1216 | | | Observe: 17436 1217 | | | Max-Age: 60 1218 | | | Payload: "busy" 1219 | | | 1221 Figure 8: A client observes a resource through a proxy 1223 Appendix B. Changelog 1225 [Note to RFC Editor: Please remove this section before publication.] 1227 Changes from ietf-15 to ietf-16: 1229 o Clarified several points based on AD, GenART, IESG, and Secdir 1230 reviews. 1232 Changes from ietf-14 to ietf-15: 1234 o Clarified several points based on AD, GenART, IESG, and Secdir 1235 reviews. 1237 Changes from ietf-13 to ietf-14: 1239 o Updated references. 1241 Changes from ietf-12 to ietf-13: 1243 o Extended the Observe Option in requests to not only add but also 1244 remove an entry in the list of observers, depending on the option 1245 value. 1247 Note: The value of the Observe Option in a registration request 1248 may now be any sequence of bytes that encodes the unsigned 1249 integer 0, i.e., 0x'', 0x'00', 0x'00 00' or 0x'00 00 00'. 1251 o Removed the 7.31 Code for cancellation. 1253 Changes from ietf-11 to ietf-12: 1255 o Introduced the 7.31 Code to request the cancellation of a pending 1256 request. 1258 o Made the algorithm for superseding an outstanding transmission 1259 OPTIONAL. 1261 o Clarified that the entry in the list of observers is removed if 1262 the client fails to acknowledge a confirmable notification before 1263 the last retransmission attempt times out (#350). 1265 o Simplified the text on cancellation (#352) and the handling of 1266 Reset messages (#353). 1268 Changes from ietf-10 to ietf-11: 1270 o Pointed out that client and server clocks may differ in their 1271 realization of the SI second, and added robustness to the existing 1272 reordering scheme by reducing the maximum notification rate to 1273 32768 notifications per second (#341). 1275 Changes from ietf-09 to ietf-10: 1277 o Required consistent sequence numbers across requests (#333). 1279 o Clarified that a server needs to update the entry in the list of 1280 observers instead of adding a new entry if the endpoint/token pair 1281 is already present. 1283 o Allowed that a client uses a token that is currently in use to 1284 ensure that it's still in the list of observers. This is possible 1285 because sequence numbers are now consistent across requests and 1286 servers won't add a new entry for the same token. 1288 o Improved text on the transmission of non-confirmable notifications 1289 to match Section 3.1.2 of RFC 5405 more closely. 1291 o Updated examples to use UCUM units. 1293 o Moved Appendix B into the introduction. 1295 Changes from ietf-08 to ietf-09: 1297 o Removed the side effects of requests on existing observations. 1298 This includes removing that 1300 * the client can use a GET request to cancel an observation; 1302 * the server updates the entry in the list of observers instead 1303 of adding a new entry if the client is already present (#258, 1304 #281). 1306 o Clarified that a resource (and hence an observation relationship) 1307 is identified by the request options that are part of the Cache- 1308 Key (#258). 1310 o Clarified that a non-2.xx notification MUST NOT include an Observe 1311 Option. 1313 o Moved block-wise transfer of notifications to [I-D.ietf-core- 1314 block]. 1316 Changes from ietf-07 to ietf-08: 1318 o Expanded text on transmitting a notification while a previous 1319 transmission is pending (#242). 1321 o Changed reordering detection to use a fixed time span of 128 1322 seconds instead of EXCHANGE_LIFETIME (#276). 1324 o Removed the use of the freshness model to determine if the client 1325 is still on the list of observers. This includes removing that 1327 * the client assumes that it has been removed from the list of 1328 observers when Max-Age ends; 1330 * the server sets the Max-Age Option of a notification to a value 1331 that indicates when the server will send the next notification; 1333 * the server uses a number of retransmit attempts such that 1334 removing a client from the list of observers before Max-Age 1335 ends is avoided (#235); 1337 * the server may remove the client from all lists of observers 1338 when the transmission of a confirmable notification ultimately 1339 times out. 1341 o Changed that an unrecognized critical option in a request must 1342 actually have no effect on the state of any observation 1343 relationship to any resource, as the option could lead to a 1344 different target resource. 1346 o Clarified that client implementations must be prepared to receive 1347 each notification equally as a confirmable or a non-confirmable 1348 message, regardless of the message type of the request and of any 1349 previous notification. 1351 o Added a requirement for sending a confirmable notification at 1352 least every 24 hours before continuing with non-confirmable 1353 notifications (#221). 1355 o Added congestion control considerations from [I-D.bormann-core- 1356 congestion-control-02]. 1358 o Recommended that the client waits for a randomized time after the 1359 freshness of the latest notification expired before re- 1360 registering. This prevents that multiple clients observing a 1361 resource perform a GET request at the same time when the need to 1362 re-register arises. 1364 o Changed reordering detection from 'MAY' to 'SHOULD', as the goal 1365 of the protocol (to keep the observed state as closely in sync 1366 with the actual state as possible) is not optional. 1368 o Fixed the length of the Observe Option (3 bytes) in the table in 1369 Section 2. 1371 o Replaced the 'x' in the No-Cache-Key column in the table in 1372 Section 2 with a '-', as the Observe Option doesn't have the No- 1373 Cache-Key flag set, even though it is not part of the cache key. 1375 o Updated examples. 1377 Changes from ietf-06 to ietf-07: 1379 o Moved to 24-bit sequence numbers to allow for up to 15000 1380 notifications per second per client and resource (#217). 1382 o Re-numbered option number to use Unsafe/Safe and Cache-Key 1383 compliant numbers (#241). 1385 o Clarified how to react to a Reset message that is sent in reply to 1386 a non-confirmable notification (#225). 1388 o Clarified the semantics of the "obs" link target attribute (#236). 1390 Changes from ietf-05 to ietf-06: 1392 o Improved abstract and introduction to say that the protocol is 1393 about best effort and eventual consistency (#219). 1395 o Clarified that the value of the Observe Option in a request must 1396 have zero length. 1398 o Added requirement that the sequence number must be updated each 1399 time a server retransmits a notification. 1401 o Clarified that a server must remove a client from the list of 1402 observers when it receives a GET request with an unrecognized 1403 critical option. 1405 o Updated the text to use the endpoint concept from [I-D.ietf-core- 1406 coap] (#224). 1408 o Improved the reordering text (#223). 1410 Changes from ietf-04 to ietf-05: 1412 o Recommended that a client does not re-register while a new 1413 notification from the server is still likely to arrive. This is 1414 to avoid that the request of the client and the last notification 1415 after max-age cross over each other (#174). 1417 o Relaxed requirements when sending a Reset message in reply to non- 1418 confirmable notifications. 1420 o Added an implementation note about careless GET requests (#184). 1422 o Updated examples. 1424 Changes from ietf-03 to ietf-04: 1426 o Removed the "Max-OFE" Option. 1428 o Allowed a Reset message in reply to non-confirmable notifications. 1430 o Added a section on cancellation. 1432 o Updated examples. 1434 Changes from ietf-02 to ietf-03: 1436 o Separated client-side and server-side requirements. 1438 o Fixed uncertainty if client is still on the list of observers by 1439 introducing a liveliness model based on Max-Age and a new option 1440 called "Max-OFE" (#174). 1442 o Simplified the text on message reordering (#129). 1444 o Clarified requirements for intermediaries. 1446 o Clarified the combination of blockwise transfers with 1447 notifications (#172). 1449 o Updated examples to show how the state observed by the client 1450 becomes eventually consistent with the actual state on the server. 1452 o Added examples for parameterization of observable resource. 1454 Changes from ietf-01 to ietf-02: 1456 o Removed the requirement of periodic refreshing (#126). 1458 o The new "Observe" Option replaces the "Lifetime" Option. 1460 o Introduced a new mechanism to detect message reordering. 1462 o Changed 2.00 (OK) notifications to 2.05 (Content) notifications. 1464 Changes from ietf-00 to ietf-01: 1466 o Changed terminology from "subscriptions" to "observation 1467 relationships" (#33). 1469 o Changed the name of the option to "Lifetime". 1471 o Clarified establishment of observation relationships. 1473 o Clarified that an observation is only identified by the URI of the 1474 observed resource and the identity of the client (#66). 1476 o Clarified rules for establishing observation relationships (#68). 1478 o Clarified conditions under which an observation relationship is 1479 terminated. 1481 o Added explanation on how clients can terminate an observation 1482 relationship before the lifetime ends (#34). 1484 o Clarified that the overriding objective for notifications is 1485 eventual consistency of the actual and the observed state (#67). 1487 o Specified how a server needs to deal with clients not 1488 acknowledging confirmable messages carrying notifications (#69). 1490 o Added a mechanism to detect message reordering (#35). 1492 o Added an explanation of how notifications can be cached, 1493 supporting both the freshness and the validation model (#39, #64). 1495 o Clarified that non-GET requests do not affect observation 1496 relationships, and that GET requests without "Lifetime" Option 1497 affecting relationships is by design (#65). 1499 o Described interaction with blockwise transfers (#36). 1501 o Added Resource Discovery section (#99). 1503 o Added IANA Considerations. 1505 o Added Security Considerations (#40). 1507 o Added examples (#38). 1509 Author's Address 1511 Klaus Hartke 1512 Universitaet Bremen TZI 1513 Postfach 330440 1514 Bremen D-28359 1515 Germany 1517 Phone: +49-421-218-63905 1518 EMail: hartke@tzi.org