idnits 2.17.1 draft-ietf-core-observe-08.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 (February 25, 2013) is 4077 days in the past. Is this intentional? 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 800, but not defined == Outdated reference: A later version (-21) exists of draft-ietf-core-block-10 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-13 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) -- Obsolete informational reference (is this intentional?): RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 2 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 February 25, 2013 5 Expires: August 29, 2013 7 Observing Resources in CoAP 8 draft-ietf-core-observe-08 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 Editor's Note 24 This is an interim revision which will receive further modifications 25 during the resolution of open tickets, in particular #204 and #281. 27 Status of this Memo 29 This Internet-Draft is submitted in full conformance with the 30 provisions of BCP 78 and BCP 79. 32 Internet-Drafts are working documents of the Internet Engineering 33 Task Force (IETF). Note that other groups may also distribute 34 working documents as Internet-Drafts. The list of current Internet- 35 Drafts is at http://datatracker.ietf.org/drafts/current/. 37 Internet-Drafts are draft documents valid for a maximum of six months 38 and may be updated, replaced, or obsoleted by other documents at any 39 time. It is inappropriate to use Internet-Drafts as reference 40 material or to cite them other than as "work in progress." 42 This Internet-Draft will expire on August 29, 2013. 44 Copyright Notice 46 Copyright (c) 2013 IETF Trust and the persons identified as the 47 document authors. All rights reserved. 49 This document is subject to BCP 78 and the IETF Trust's Legal 50 Provisions Relating to IETF Documents 51 (http://trustee.ietf.org/license-info) in effect on the date of 52 publication of this document. Please review these documents 53 carefully, as they describe your rights and restrictions with respect 54 to this document. Code Components extracted from this document must 55 include Simplified BSD License text as described in Section 4.e of 56 the Trust Legal Provisions and are provided without warranty as 57 described in the Simplified BSD License. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.1. Background . . . . . . . . . . . . . . . . . . . . . . . . 3 63 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 3 64 1.3. Requirements Notation . . . . . . . . . . . . . . . . . . 6 65 2. The Observe Option . . . . . . . . . . . . . . . . . . . . . . 6 66 3. Client-side Requirements . . . . . . . . . . . . . . . . . . . 7 67 3.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 3.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 7 69 3.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 3.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 9 71 3.5. Transmission . . . . . . . . . . . . . . . . . . . . . . . 10 72 3.6. Cancellation . . . . . . . . . . . . . . . . . . . . . . . 10 73 4. Server-side Requirements . . . . . . . . . . . . . . . . . . . 10 74 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 10 75 4.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 11 76 4.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 4.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 13 78 4.5. Transmission . . . . . . . . . . . . . . . . . . . . . . . 13 79 5. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 15 80 6. Blockwise Transfers . . . . . . . . . . . . . . . . . . . . . 16 81 7. Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 16 82 8. Security Considerations . . . . . . . . . . . . . . . . . . . 17 83 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17 84 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 85 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 86 11.1. Normative References . . . . . . . . . . . . . . . . . . . 18 87 11.2. Informative References . . . . . . . . . . . . . . . . . . 18 88 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 19 89 A.1. Proxying . . . . . . . . . . . . . . . . . . . . . . . . . 23 90 A.2. Blockwise Transfer . . . . . . . . . . . . . . . . . . . . 25 91 Appendix B. Modeling Resources to Tailor Notifications . . . . . 26 92 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . . 26 93 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 31 95 1. Introduction 97 1.1. Background 99 CoAP [I-D.ietf-core-coap] is an application protocol for constrained 100 nodes and networks. It is intended to provide RESTful services 101 [REST] not unlike HTTP [RFC2616] while reducing the complexity of 102 implementation as well as the size of packets exchanged in order to 103 make these services useful in a highly constrained network of 104 themselves highly constrained nodes. 106 The model of REST is that of a client exchanging representations of 107 resources with a server. A representation captures the current or 108 intended state of a resource. The server is the definitive source 109 for representations of the resources in its namespace. A client 110 interested in the state of a resource initiates a request to the 111 server; the server then returns a response with a representation of 112 the resource that is current at the time of the request. 114 This model does not work well when a client is interested in having a 115 current representation of a resource over a period of time. Existing 116 approaches from HTTP, such as repeated polling or HTTP long polling 117 [RFC6202], generate significant complexity and/or overhead and thus 118 are less applicable in a constrained environment. 120 The protocol specified in this document extends the CoAP core 121 protocol with a mechanism for a CoAP client to "observe" a resource 122 on a CoAP server: the client can retrieve a representation of the 123 resource and keep this representation updated by the server over a 124 period of time. 126 The protocol keeps the architectural properties of REST. It enables 127 high scalability and efficiency through the support of caches and 128 proxies. There is no intention, though, to solve the full set of 129 problems that the existing HTTP solutions solve, or to replace 130 publish/subscribe networks that solve a much more general problem 131 [RFC5989]. 133 1.2. Protocol Overview 135 The protocol is based on the well-known observer design pattern 136 [GOF]. In this design pattern, components called "observers" 137 register at a specific, known provider called the "subject" that they 138 are interested in being notified whenever the subject undergoes a 139 change in state. The subject is responsible for administering its 140 list of registered observers. If multiple subjects are of interest 141 to an observer, it must register separately for all of them. 143 Observer Subject 144 | | 145 | Registration | 146 +----------------->| 147 | | 148 | Notification | 149 |<-----------------+ 150 | | 151 | Notification | 152 |<-----------------+ 153 | | 154 | Notification | 155 |<-----------------+ 156 | | 158 Figure 1: The Observer Design Pattern 160 The observer design pattern is realized in CoAP as follows: 162 Subject: In the context of CoAP, the subject is a resource in the 163 namespace of a CoAP server. The state of the resource can change 164 over time, ranging from infrequent updates to continuous state 165 transformations. 167 Observer: An observer is a CoAP client that is interested in having 168 a current representation of the resource at any given time. 170 Registration: A client registers its interest in a resource by 171 initiating an extended GET request to the server. In addition to 172 returning a representation of the target resource, this request 173 causes the server to add the client to the list of observers of 174 the resource. 176 Notification: Whenever the state of a resource changes, the server 177 notifies each client in the list of observers of the resource. 178 Each notification is an additional CoAP response sent by the 179 server in reply to the GET request and includes a complete, 180 updated representation of the new resource state. 182 Figure 2 below shows an example of a CoAP client registering its 183 interest in a resource and receiving three notifications: the first 184 upon registration with the current state, and then two upon two 185 changes to the resource state. Both the registration request and the 186 notifications are identified as such by the presence of the Observe 187 Option defined in this document. In notifications, the Observe 188 Option provides a sequence number for reordering detection. All 189 notifications carry the token specified by the client in the request, 190 so the client can easily correlate them to the request. 192 Client Server 193 | | 194 | GET /temperature | 195 | Token: 0x4a | Registration 196 | Observe: (empty) | 197 +----------------->| 198 | | 199 | 2.05 Content | 200 | Token: 0x4a | Notification of 201 | Observe: 12 | the current state 202 | Payload: 22.9 C | 203 |<-----------------+ 204 | | 205 | 2.05 Content | 206 | Token: 0x4a | Notification upon 207 | Observe: 44 | a state change 208 | Payload: 22.8 C | 209 |<-----------------+ 210 | | 211 | 2.05 Content | 212 | Token: 0x4a | Notification upon 213 | Observe: 60 | a state change 214 | Payload: 23.1 C | 215 |<-----------------+ 216 | | 218 Figure 2: Observing a Resource in CoAP 220 The server is the authority for determining under what conditions 221 resources change their state and how often observers are notified. 222 The protocol does not offer explicit means for setting up triggers, 223 thresholds or other conditions; it is up to the server to expose 224 observable resources that change their state in a way that is useful 225 in the application context. Resources can be parameterized to 226 achieve similar effects, though; see Appendix B for examples. 228 A client remains on the list of observers as long as the server can 229 determine the client's continued interest in the resource. The 230 interest is determined from the client's acknowledgement of 231 notifications sent in confirmable messages by the server. If the 232 client actively rejects a notification or if the transmission of a 233 notification ultimately fails, then the client is assumed to be no 234 longer interested and is removed from the list of observers. 236 While a client is in the list of observers of a resource, it is the 237 goal of the protocol to keep the resource state observed by the 238 client as closely in sync with the actual state at the server as 239 possible. 241 Becoming out of sync at times cannot be avoided: First, there is 242 always some latency between the change of the resource state and the 243 receipt of the notification. Second, messages with notifications can 244 get lost, which will cause the client assume an old state until it 245 receives the next notification. And third, the server may 246 erroneously come to the conclusion that the client is no longer 247 interested in the resource, which will cause it to stop sending 248 notifications and the client to assume an old state until it 249 registers its interest again. 251 The protocol addresses this issue as follows: 253 o It follows a best-effort approach for sending the current 254 representation to the client after a state change: Clients should 255 see the new state after a state change as soon as possible, and 256 they should see as many states as possible. However, a client 257 cannot rely on observing every single state that a resource goes 258 through. 260 o It labels notifications with a maximum duration up to which it is 261 acceptable for the observed state and the actual state to be out 262 of sync. When the age of the notification received reaches this 263 maximum, the client cannot use the enclosed representation until 264 it has received a new notification. 266 o It is designed on the principle of eventual consistency: The 267 protocol guarantees that, if the resource does not undergo a new 268 change in state, eventually all registered observers will have a 269 current representation of the latest resource state. 271 1.3. Requirements Notation 273 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 274 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 275 document are to be interpreted as described in RFC 2119 [RFC2119]. 277 2. The Observe Option 279 +-----+---+---+---+---+---------+------------+-----------+---------+ 280 | No. | C | U | N | R | Name | Format | Length | Default | 281 +-----+---+---+---+---+---------+------------+-----------+---------+ 282 | 6 | | x | - | | Observe | empty/uint | 0 B/0-3 B | (none) | 283 +-----+---+---+---+---+---------+------------+-----------+---------+ 285 C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable 287 Table 1: The Observe Option 289 The Observe Option, when present in a request, extends the GET method 290 so it does not only retrieve a current representation of the target 291 resource, but also requests the server to add the client to the list 292 of observers of the resource. The exact semantics are defined in the 293 following sections. The value of the option in a request MUST be 294 empty on transmission and MUST be ignored on reception. 296 The Observe Option is not critical for processing the request. If 297 the server is unwilling or unable to add the client to the list of 298 observers of the resource identified by the request URI, then the 299 request falls back to a normal GET request. 301 In a response, the Observe Option identifies the message as a 302 notification. This implies that the server has added the client to 303 the list of observers and that it will notify the client of changes 304 to the resource state. The value of the option is a 24-bit sequence 305 number for reordering detection; see Section 3.4 and Section 4.4 for 306 the client- and server-side respectively. The sequence number is 307 encoded in network byte order using a variable number of bytes, as 308 specified in Section 3.2 of RFC XXXX [I-D.ietf-core-coap]. 310 The Observe Option is not part of the cache-key: a cacheable response 311 obtained with an Observe Option in the request can be used to satisfy 312 a request without an Observe Option, and vice versa. When a stored 313 response with an Observe Option is used to satisfy a normal GET 314 request, the option MUST be removed before the response is returned 315 to the client. 317 3. Client-side Requirements 319 3.1. Request 321 A client can register its interest in a resource by issuing a GET 322 request that includes an empty Observe Option. If the server returns 323 a 2.xx response that includes an Observe Option as well, the server 324 has added the client successfully to the list of observers of the 325 target resource and the client will be notified of changes to the 326 resource state. 328 3.2. Notifications 330 Notifications are additional responses sent by the server in reply to 331 the GET request. Each notification includes the token specified by 332 the client in the GET request, an Observe Option with a sequence 333 number for reordering detection (see Section 3.4) and a payload in 334 the same Content-Format as the initial response. 336 Notifications have a 2.05 (Content) response code, or a 2.03 (Valid) 337 response code if the client has included one or more ETag Options in 338 the request (see Section 3.3). In the event that the resource 339 changes in a way that would cause a normal GET request at that time 340 to return a non-2.xx response (for example, when the resource is 341 deleted), the server sends a notification with a matching response 342 code and removes the client from the list of observers. 344 3.3. Caching 346 As notifications are just additional responses to a GET request, 347 notifications partake in caching as defined in Section 5.6 of RFC 348 XXXX [I-D.ietf-core-coap]. Both the freshness model and the 349 validation model are supported. 351 3.3.1. Freshness 353 A client MAY store a notification like a response in its cache and 354 use a stored notification that is fresh without contacting the origin 355 server. Like a response, a notification is considered fresh while 356 its age is not greater than the value indicated by the Max-Age Option 357 and if no newer notification/response has been received. 359 The server will do its best to keep the resource state observed by 360 the client as closely in sync with the actual state as possible. 361 However, a client cannot rely on observing every single state that a 362 resource might go through. For example, if the network is congested 363 or the state changes more frequently than the network can handle, the 364 server can skip notifications for intermediate states. 366 The server uses the Max-Age Option to indicate an age up to which it 367 is acceptable that the observed state and the actual state are 368 inconsistent. If the age of the latest notification becomes greater 369 than its indicated Max-Age, then the client MUST NOT use the enclosed 370 representation until it is validated or a new notification is 371 received. 373 To make sure it has a current representation and/or to re-register 374 its interest in a resource, a client MAY issue a new GET request with 375 an Observe Option at any time. The client SHOULD specify a new token 376 in the GET request, as the token serves as an epoch identifier for 377 the sequence numbers in the Observe Option (see Section 3.4). 379 It is RECOMMENDED that the client does not issue the request while it 380 still has a fresh notification/response for a resource in its cache. 381 Additionally, the client SHOULD wait for a random amount of time 382 between 5 and 15 seconds before issuing the new request to avoid 383 synchronicity with other clients. 385 3.3.2. Validation 387 When a client has one or more notifications stored in its cache for a 388 resource, it can use the ETag Option in the GET request to give the 389 server an opportunity to select a stored notification to be used. 391 The client MAY include an ETag Option for each stored response that 392 is applicable in the GET request. Whenever the observed resource 393 changes to a representation identified by one of the ETag Options, 394 the server can select a stored response by sending a 2.03 (Valid) 395 notification with an appropriate ETag Option instead of a 2.05 396 (Content) notification. The client needs to keep all candidate 397 responses in its cache until it is no longer interested in the target 398 resource or it issues a new GET request with a new set of entity- 399 tags. 401 3.4. Reordering 403 Messages with notifications can arrive in a different order than they 404 were sent. Since the goal is to keep the observed state as closely 405 in sync with the actual state as possible, a client SHOULD NOT update 406 the observed state with a notification that arrives later than a 407 newer notification. 409 For reordering detection, the server sets the value of the Observe 410 Option in each notification to a 24-bit sequence number. An incoming 411 notification is newer than the newest notification received so far 412 when one of the following conditions is met: 414 (V1 < V2 and V2 - V1 < 2^23) or 415 (V1 > V2 and V1 - V2 > 2^23) or 416 (T2 > T1 + 128 seconds) 418 where V1 is the value of the Observe Option of the newest 419 notification received so far, V2 the value of the Observe Option of 420 the incoming notification, T1 a client-local timestamp of the newest 421 notification received so far, and T2 a client-local timestamp of the 422 incoming notification. 424 Design Note: The first two conditions verify that V1 is less than V2 425 in 24-bit sequence number arithmetic [RFC1982]. The third 426 condition ensures that the time elapsed between the two incoming 427 messages is not so large that the difference between V1 and V2 has 428 become larger than the largest integer that it is meaningful to 429 add to a 24-bit sequence number; in other words, after 128 seconds 430 have elapsed without any notification, a client does not need to 431 check the sequence numbers in order to assume an incoming 432 notification is new. 434 3.5. Transmission 436 A notification can be confirmable or non-confirmable, i.e., be sent 437 in a confirmable or a non-confirmable message. The message type used 438 is independent from the type used for the request or any previous 439 notification. 441 If a client does not recognize the token in a confirmable 442 notification, it MUST NOT acknowledge the message and SHOULD reject 443 it with a Reset message; otherwise, the client MUST acknowledge the 444 message as usual. In the case of a non-confirmable notification, 445 rejecting the message with a Reset message is OPTIONAL. 447 An acknowledgement message signals to the server that the client is 448 alive and interested in receiving further notifications; if the 449 server does not receive an acknowledgement in reply to a confirmable 450 notification, it will assume that the client is no longer interested 451 and will eventually remove the client from the list of observers. 453 3.6. Cancellation 455 When a client rejects a confirmable notification with a Reset message 456 or when it issues a GET request without an Observe Option for a 457 currently observed resource, the server will remove the client from 458 the list of observers of this resource. The client MAY use either 459 method to indicate that it is no longer interested in receiving 460 further notifications for the resource until it eventually registers 461 again. 463 When a client rejects non-confirmable notification, the server may 464 also (but is not required to) remove the client from the list of 465 observers of this resource. The client MAY try this method as well, 466 and MAY rate-limit the Reset messages it sends if the server appears 467 to persistently ignore them. 469 Implementation Note: A client that does not mediate all its requests 470 through its cache might inadvertently cancel an observation by 471 making an unrelated GET to the same resource. To avoid this, 472 without incurring a need for synchronization, such clients can use 473 a different source endpoint for these unrelated GET requests. 475 4. Server-side Requirements 477 4.1. Request 479 A GET request that includes an Observe Option requests the server not 480 only to return a current representation of the resource identified by 481 the request URI, but also to add the client to the list of observers 482 of the target resource. If no error occurs, the server MUST return a 483 2.05 (Content) response with the representation of the current 484 resource state and MUST notify the client of subsequent changes to 485 the state as long as the client is on the list of observers. 487 A server that is unable or unwilling to add the client to the list of 488 observers of the target resource MAY silently ignore the Observe 489 Option and process the GET request as usual. The resulting response 490 MUST NOT include an Observe Option, the absence of which signals to 491 the client that it will not be notified of changes to the resource 492 and, e.g., needs to poll the resource for its state instead. 494 If the client is already on the list of observers, the server MUST 495 NOT add it a second time but MUST replace or update the existing 496 entry. If the server receives a GET request for the a resource that 497 does not include an Observe Option, the server MUST remove any 498 existing entry from the list of observers. 500 Two requests relate to the same list entry if and only if both the 501 request URI and the source endpoint of the requests are the same. 502 Message IDs, tokens and other options are not taken into account. 504 Any request with an unrecognized critical option or a method other 505 than GET MUST NOT have a direct effect on a list of observers of a 506 resource. However, a non-GET request can have the indirect 507 consequence of causing the server to send a non-2.xx notification 508 which does affect the list of observers (for example, when a DELETE 509 request is successful and the observed resource no longer exists). 511 4.2. Notifications 513 A client is notified of changes to the resource state by additional 514 responses sent by the server in reply to the GET request. Each such 515 notification response (including the initial response) MUST include 516 an Observe Option and MUST echo the token specified by the client in 517 the GET request. If there are multiple clients on the list of 518 observers, the order in which they are notified is not defined; the 519 server is free to use any method to determine the order. 521 A notification SHOULD have a 2.05 (Content) or 2.03 (Valid) response 522 code. However, in the event that the state of a resource changes in 523 a way that would cause a normal GET request at that time to return a 524 non-2.xx response (for example, when the resource is deleted), the 525 server SHOULD notify the client by sending a notification with a 526 matching response code and MUST remove the client from the list of 527 observers of the resource. 529 The Content-Format used in a notification MUST be the same as the one 530 used in the initial response to the GET request. If the server is 531 unable to continue sending notifications using this Content-Format, 532 it SHOULD send a notification with a 5.00 (Internal Server Error) 533 response code and MUST remove the client from the list of observers 534 of the resource. 536 4.3. Caching 538 As notifications are just additional responses sent by the server, 539 they are subject to caching as defined in Section 5.6 of RFC XXXX 540 [I-D.ietf-core-coap]. 542 4.3.1. Freshness 544 After returning the initial response, the server MUST try to keep the 545 returned representation current, i.e., keep the resource state 546 observed by the client as closely in sync with the actual resource 547 state as possible. 549 Since becoming out of sync at times cannot be avoided, the server 550 MUST indicate for each representation an age up to which it is 551 acceptable that the observed state and the actual state are 552 inconsistent. This age is application-dependent and MUST be 553 specified in notifications using the Max-Age Option. 555 When the resource does not change and the client has a current 556 representation, the server does not need to send a notification. 557 However, if the client does not receive a notification, it cannot 558 tell if the observed state and the actual state are still in sync. 559 So, when the the age of the latest notification becomes greater than 560 its indicated Max-Age, then the client will assume that the states 561 are inconsistent until the representation is validated or a new 562 notification is received. The server MAY wish to prevent that by 563 sending a notification with the unchanged representation before Max- 564 Age expires. 566 4.3.2. Validation 568 A client can include a set of entity-tags in its request using the 569 ETag Option. When a observed resource changes its state and the 570 origin server is about to send a 2.05 (Content) notification, then, 571 whenever that notification has an entity-tag in the set of entity- 572 tags specified by the client, the server MAY send a 2.03 (Valid) 573 response with an appropriate ETag Option instead. The server MUST 574 NOT assume that the client has any response stored other than those 575 identified by the entity-tags in the most recent GET request received 576 for the resource. 578 4.4. Reordering 580 Because messages can get reordered, the client needs a way to 581 determine if a notification arrived later than a newer notification. 582 For this purpose, the server MUST set the value of the Observe Option 583 of each notification it sends to the 24 least-significant bits of a 584 strictly increasing sequence number. The sequence number MAY start 585 at any value and MUST NOT increase so fast that it increases by more 586 than 2^24 within less than 256 seconds. 588 The sequence number selected for a notification MUST be greater than 589 that of any preceding notification sent to the same client for the 590 same resource with the same token. The value of the Observe Option 591 MUST be current at the time of transmission; if a notification is 592 retransmitted, the server MUST update value of the Observe Option 593 before sending the message. 595 Implementation Note: A simple implementation that satisfies the 596 requirements is to obtain a timestamp from a local clock. The 597 sequence number then is the timestamp in ticks, where 1 tick = 598 (256 seconds)/(2^24) = 15.26 microseconds. It is not necessary 599 that the clock reflects the current time/date or that it ticks in 600 a precisely periodical way. 602 Another valid implementation is to store a 24-bit unsigned integer 603 variable per resource and increment this variable each time the 604 resource undergoes a change of state (provided that the resource 605 changes its state less than 2^24 times in the next 256 seconds 606 after any state change). This alleviates the need to update the 607 value of the Observe Option in a message when the resource state 608 did not change. 610 Design Note: The choice of a 24-bit option value and a time span of 611 256 seconds allows for a notification rate of up to 65536 612 notifications per second. 64K ought to be enough for anybody. 614 4.5. Transmission 616 A notification can be sent in a confirmable or a non-confirmable 617 message. The message type used is typically application-dependent 618 and MAY be determined by the server for each notification 619 individually. For example, for resources that change in a somewhat 620 predictable or regular fashion, notifications can be sent in non- 621 confirmable messages; for resources that change infrequently, 622 notifications can be sent in confirmable messages. The server can 623 combine these two approaches depending on the frequency of state 624 changes and the importance of individual notifications. 626 The acknowledgement of a confirmable notification signals to the 627 server that the client is interested in receiving further 628 notifications. If a client rejects a confirmable notification with a 629 Reset message, the client is no longer interested and the server MUST 630 remove the client from the list of observers. If the client rejects 631 a non-confirmable notification, the server MAY remove the client from 632 the list of observers as well. (It is expected that the server does 633 remove the client if it has the information available that is needed 634 to match the Reset message to the non-confirmable notification, but 635 the server is not required to keep this information.) 637 At a minimum, the server MUST send a notification in a confirmable 638 message instead of a non-confirmable message at least every 24 hours. 640 A server MAY choose to skip a notification if it knows that it will 641 send another notification soon (e.g., when the state is changing 642 frequently). Similarly, it MAY choose to send a notification more 643 than once. For example, when state changes occur in bursts, the 644 server can skip some notifications, send the notifications in non- 645 confirmable messages, and make sure that the client observes the 646 latest state change after the burst by repeating the last 647 notification in a confirmable message. 649 The server MUST limit the number of confirmable notifications for 650 which an acknowledgement has not been received yet to NSTART (see 651 Section 4.7 of RFC XXXX [I-D.ietf-core-coap]), and it SHOULD NOT send 652 more than one non-confirmable notification every 3 seconds on 653 average. 655 When the state of an observed resource changes while the server is 656 still waiting for a confirmable notification to be acknowledged or 657 the 3 seconds for a non-confirmable notification to elapse, then the 658 server MUST proceed as follows: 660 1. Wait for the current transmission attempt to complete. 662 2. If the result is a Reset message or the transmission was the last 663 attempt to deliver a notification, remove the client from the 664 list of observers of the observed resource. 666 3. If the client is still in the list of observers, transmit a 667 notification with a representation of the current resource state. 668 Should the resource have changed its state more than once in the 669 meantime, skip the notifications for the intermediate states. 671 4. If the previously completed transmission timed out, increment the 672 retransmission counter and double the timeout; otherwise, 673 reinitialize the retransmission counter and the timeout. 675 If CoAP is used over a connection-oriented or session-based transport 676 such as DTLS, the server MUST remove the client from the list of 677 observers when the connection or session is closed. 679 5. Intermediaries 681 A client may be interested in a resource in the namespace of an 682 origin server that is reached through a chain of one or more CoAP-to- 683 CoAP intermediaries. In this case, the client registers its interest 684 with the first intermediary towards the origin server, acting as if 685 it was communicating with the origin server itself as specified in 686 Section 3. It is the task of this intermediary to provide the client 687 with a current representation of the target resource and send 688 notifications upon changes to the target resource state, much like an 689 origin server as specified in Section 4. 691 To perform this task, the intermediary SHOULD make use of the 692 protocol specified in this document, taking the role of the client 693 and registering its own interest in the target resource with the next 694 hop towards the origin server. If the next hop does not return a 695 response with an Observe Option, the intermediary MAY resort to 696 polling the next hop or MAY itself return a response without an 697 Observe Option. 699 The communication between each pair of hops is independent; each hop 700 in the server role MUST determine individually how many notifications 701 to send, of which message type, and so on. Each hop MUST generate 702 its own values for the Observe Option, and MUST set the value of the 703 Max-Age Option according to the age of the local current 704 representation. 706 Because a client (or an intermediary in the client role) can only be 707 once on the list of observers of a resource on a server (or an 708 intermediary in the server role) -- it is useless to observe the same 709 resource multiple times -- an intermediary MUST observe a resource 710 only once, even if there are multiple clients for which it observes 711 the resource. 713 An intermediary is not required to act on behalf of a client to 714 observe a resource; an intermediary MAY observe a resource, for 715 example, just to keep its own cache up to date. 717 See Appendix A.1 for examples. 719 6. Blockwise Transfers 721 Resources observed by clients may be larger than can be comfortably 722 processed or transferred in one CoAP message. CoAP provides a 723 blockwise transfer mechanism to address this problem 724 [I-D.ietf-core-block]. The following rules apply to the combination 725 of blockwise transfers with notifications. 727 As with basic GET transfers, the client can indicate its desired 728 block size in a Block2 Option in the GET request. If the server 729 supports blockwise transfers, it SHOULD take note of the block size 730 for all notifications/responses resulting from the GET request (until 731 the client is removed from the list of observers or the server 732 receives a new GET request for the resource from the client). 734 When sending a 2.05 (Content) notification, the server always sends 735 all blocks of the representation, suitably sequenced by its 736 congestion control mechanism, even if only some of the blocks have 737 changed with respect to a previous notification. The server performs 738 the blockwise transfer by making use of the Block2 Option in each 739 block. When reassembling representations that are transmitted in 740 multiple blocks, the client MUST NOT combine blocks carrying 741 different Observe Option values. 743 Blockwise transfers of notifications MUST use confirmable messages 744 and MUST NOT use non-confirmable messages. 746 See Appendix A.2 for an example. 748 7. Web Linking 750 A web link [RFC5988] to a resource accessible over CoAP (for example, 751 in a link-format document [RFC6690]) MAY include the target attribute 752 "obs". 754 The "obs" attribute, when present, is a hint indicating that the 755 destination of a link is useful for observation and thus, for 756 example, should have a suitable graphical representation in a user 757 interface. Note that this is only a hint; it is not a promise that 758 the Observe Option can actually be used to perform the observation. 759 A client may need to resort to polling the resource if the Observe 760 Option is not returned in the response to the GET request. 762 A value MUST NOT be given for the "obs" attribute; any present value 763 MUST be ignored by parsers. The "obs" attribute MUST NOT appear more 764 than once in a given link-value; occurrences after the first MUST be 765 ignored by parsers. 767 8. Security Considerations 769 The security considerations of RFC XXXX [I-D.ietf-core-coap] apply. 771 The considerations about amplification attacks are somewhat amplified 772 when observing resources. Without client authentication, a server 773 MUST therefore strictly limit the number of notifications that it 774 sends between receiving acknowledgements that confirm the actual 775 interest of the client in the data; i.e., any notifications sent in 776 non-confirmable messages MUST be interspersed with confirmable 777 messages. (An attacker may still spoof the acknowledgements if the 778 confirmable messages are sufficiently predictable.) 780 As with any protocol that creates state, attackers may attempt to 781 exhaust the resources that the server has available for maintaining 782 the list of observers for each resource. Servers may want to access- 783 control this creation of state. As degraded behavior, the server can 784 always fall back to processing the request as a normal GET request 785 (without an Observe Option) if it is unwilling or unable to add a 786 client to the list of observers of a resource, including if system 787 resources are exhausted or nearing exhaustion. 789 Intermediaries must be careful to ensure that notifications cannot be 790 employed to create a loop. A simple way to break any loops is to 791 employ caches for forwarding notifications in intermediaries. 793 9. IANA Considerations 795 The following entry is added to the CoAP Option Numbers registry: 797 +--------+---------+-----------+ 798 | Number | Name | Reference | 799 +--------+---------+-----------+ 800 | 6 | Observe | [RFCXXXX] | 801 +--------+---------+-----------+ 803 10. Acknowledgements 805 Carsten Bormann was an original author of this draft and is 806 acknowledged for significant contribution to this document. 808 Thanks to Daniele Alessandrelli, Jari Arkko, Peter Bigot, Angelo P. 809 Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank, 810 Jeroen Hoebeke, Cullen Jennings, Matthias Kovatsch, Salvatore Loreto, 811 Charles Palmer, Zach Shelby and Floris Van den Abeele for helpful 812 comments and discussions that have shaped the document. 814 11. References 816 11.1. Normative References 818 [I-D.ietf-core-block] 819 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 820 draft-ietf-core-block-10 (work in progress), October 2012. 822 [I-D.ietf-core-coap] 823 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 824 "Constrained Application Protocol (CoAP)", 825 draft-ietf-core-coap-13 (work in progress), December 2012. 827 [RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982, 828 August 1996. 830 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 831 Requirement Levels", BCP 14, RFC 2119, March 1997. 833 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 835 11.2. Informative References 837 [GOF] Gamma, E., Helm, R., Johnson, R., and J. Vlissides, 838 "Design Patterns: Elements of Reusable Object-Oriented 839 Software", Addison-Wesley, Reading, MA, USA, 840 November 1994. 842 [REST] Fielding, R., "Architectural Styles and the Design of 843 Network-based Software Architectures", Ph.D. Dissertation, 844 University of California, Irvine, 2000, . 848 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 849 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 850 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 852 [RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes 853 to an HTTP Resource", RFC 5989, October 2010. 855 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 856 "Known Issues and Best Practices for the Use of Long 857 Polling and Streaming in Bidirectional HTTP", RFC 6202, 858 April 2011. 860 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 861 Format", RFC 6690, August 2012. 863 Appendix A. Examples 865 Observed CLIENT SERVER Actual 866 t State | | State 867 ____________ | | ____________ 868 1 | | 869 2 unknown | | 18.5 C 870 3 +----->| Header: GET 0x41011633 871 4 | GET | Token: 0x4a 872 5 | | Uri-Path: temperature 873 6 | | Observe: (empty) 874 7 | | 875 8 | | 876 9 ____________ |<-----+ Header: 2.05 0x61451633 877 10 | 2.05 | Token: 0x4a 878 11 18.5 C | | Observe: 9 879 12 | | Max-Age: 15 880 13 | | Payload: "18.5 C" 881 14 | | 882 15 | | ____________ 883 16 ____________ |<-----+ Header: 2.05 0x51457b50 884 17 | 2.05 | 19.2 C Token: 0x4a 885 18 19.2 C | | Observe: 16 886 29 | | Max-Age: 15 887 20 | | Payload: "19.2 C" 888 21 | | 890 Figure 3: A client registers and receives one notification of the 891 current state and one of a new state upon a state change 892 Observed CLIENT SERVER Actual 893 t State | | State 894 ____________ | | ____________ 895 22 | | 896 23 19.2 C | | 19.2 C 897 24 | | ____________ 898 25 | X----+ Header: 2.05 0x51457b51 899 26 | 2.05 | 19.7 C Token: 0x4a 900 27 | | Observe: 25 901 28 | | Max-Age: 15 902 29 | | Payload: "19.7 C" 903 30 | | 904 31 ____________ | | 905 32 | | 906 33 19.2 C | | 907 34 (stale) | | 908 35 | | 909 36 | | 910 37 | | 911 38 +----->| Header: GET 0x41011634 912 39 | GET | Token: 0xb2 913 40 | | Uri-Path: temperature 914 41 | | Observe: (empty) 915 42 | | 916 43 | | 917 44 ____________ |<-----+ Header: 2.05 0x61451634 918 45 | 2.05 | Token: 0xb2 919 46 19.7 C | | Observe: 44 920 47 | | Max-Age: 15 921 48 | | ETag: 0x78797a7a79 922 49 | | Payload: "19.7 C" 923 50 | | 925 Figure 4: The client re-registers after Max-Age ends 927 Observed CLIENT SERVER Actual 928 t State | | State 929 ____________ | | ____________ 930 51 | | 931 52 19.7 C | | 19.7 C 932 53 | | 933 54 | | ____________ 934 55 | crash 935 56 | 936 57 | 937 58 | 938 59 ____________ | 939 60 | 940 61 19.7 C | 941 62 (stale) | 942 63 | reboot____________ 943 64 | | 944 65 | | 20.0 C 945 66 | | 946 67 +----->| Header: GET 0x41011635 947 68 | GET | Token: 0xf9 948 69 | | Uri-Path: temperature 949 70 | | Observe: (empty) 950 71 | | ETag: 0x78797a7a79 951 72 | | 952 73 | | 953 74 ____________ |<-----+ Header: 2.05 0x61451635 954 75 | 2.05 | Token: 0xf9 955 76 20.0 C | | Observe: 74 956 77 | | Max-Age: 15 957 78 | | Payload: "20.0 C" 958 79 | | 959 80 | | ____________ 960 81 ____________ |<-----+ Header: 2.03 0x5143aa0c 961 82 | 2.03 | 19.7 C Token: 0xf9 962 83 19.7 C | | Observe: 81 963 84 | | ETag: 0x78797a7a79 964 85 | | Max-Age: 15 965 86 | | 967 Figure 5: The client re-registers and gives the server the 968 opportunity to select a stored response 970 Observed CLIENT SERVER Actual 971 t State | | State 972 ____________ | | ____________ 973 87 | | 974 88 19.7 C | | 19.7 C 975 89 | | 976 90 | | ____________ 977 91 ____________ |<-----+ Header: 2.05 0x5145aa0f 978 92 | 2.05 | 19.3 C Token: 0xf9 979 93 19.3 C | | Observe: 91 980 94 | | Max-Age: 15 981 95 | | Payload: "19.3 C" 982 96 | | 983 97 | | 984 98 +----->| Header: GET 0x41011636 985 99 | GET | Token: 0x68 986 100 | | Uri-Path: temperature 987 101 | | ETag: 0x78797a7a79 988 102 | | 989 103 | | 990 104 |<-----+ Header: 2.05 0x61451636 991 105 | 2.05 | Token: 0x68 992 106 | | ETag: 0x78797a7a79 993 107 | | Max-Age: 15 994 108 | | Payload: "19.3 C" 995 109 | | 997 Figure 6: The client makes a normal GET request and thereby cancels 998 the observation 1000 A.1. Proxying 1002 CLIENT PROXY SERVER 1003 | | | 1004 | +----->| Header: GET 0x41015fb8 1005 | | GET | Token: 0x1a 1006 | | | Uri-Host: sensor.example 1007 | | | Uri-Path: status 1008 | | | Observe: (empty) 1009 | | | 1010 | |<-----+ Header: 2.05 0x61455fb8 1011 | | 2.05 | Token: 0x1a 1012 | | | Observe: 42 1013 | | | Max-Age: 60 1014 | | | Payload: "ready" 1015 | | | 1016 +----->| | Header: GET 0x41011633 1017 | GET | | Token: 0x9a 1018 | | | Proxy-Uri: coap://sensor.example/status 1019 | | | 1020 |<-----+ | Header: 2.05 0x61451633 1021 | 2.05 | | Token: 0x9a 1022 | | | Max-Age: 53 1023 | | | Payload: "ready" 1024 | | | 1025 | |<-----+ Header: 2.05 0x514505fc0 1026 | | 2.05 | Token: 0x1a 1027 | | | Observe: 135 1028 | | | Max-Age: 60 1029 | | | Payload: "busy" 1030 | | | 1031 +----->| | Header: GET 0x41011634 1032 | GET | | Token: 0x9b 1033 | | | Proxy-Uri: coap://sensor.example/status 1034 | | | 1035 |<-----+ | Header: 2.05 0x61451634 1036 | 2.05 | | Token: 0x9b 1037 | | | Max-Age: 49 1038 | | | Payload: "busy" 1039 | | | 1041 Figure 7: A proxy observes a resource to keep its cache up to date 1043 CLIENT PROXY SERVER 1044 | | | 1045 +----->| | Header: GET 0x41011635 1046 | GET | | Token: 0x6a 1047 | | | Proxy-Uri: coap://sensor.example/status 1048 | | | Observe: (empty) 1049 | | | 1050 |<- - -+ | Header: 0x60001635 1051 | | | 1052 | +----->| Header: GET 0x4101af90 1053 | | GET | Token: 0xaa 1054 | | | Uri-Host: sensor.example 1055 | | | Uri-Path: status 1056 | | | Observe: (empty) 1057 | | | 1058 | |<-----+ Header: 2.05 0x6145af90 1059 | | 2.05 | Token: 0xaa 1060 | | | Observe: 67 1061 | | | Max-Age: 60 1062 | | | Payload: "ready" 1063 | | | 1064 |<-----+ | Header: 2.05 0x4145af94 1065 | 2.05 | | Token: 0x6a 1066 | | | Observe: 17346 1067 | | | Max-Age: 60 1068 | | | Payload: "ready" 1069 | | | 1070 +- - ->| | Header: 0x6000af94 1071 | | | 1072 | |<-----+ Header: 2.05 0x51455a20 1073 | | 2.05 | Token: 0xaa 1074 | | | Observe: 157 1075 | | | Max-Age: 60 1076 | | | Payload: "busy" 1077 | | | 1078 |<-----+ | Header: 2.05 0x5145af9b 1079 | 2.05 | | Token: 0x6a 1080 | | | Observe: 17436 1081 | | | Max-Age: 60 1082 | | | Payload: "busy" 1083 | | | 1085 Figure 8: A client observes a resource through a proxy 1087 A.2. Blockwise Transfer 1089 CLIENT SERVER 1090 | | 1091 +----->| Header: GET 0x41011636 1092 | GET | Token: 0xfb 1093 | | Uri-Path: status-icon 1094 | | Observe: (empty) 1095 | | 1096 |<-----+ Header: 2.05 0x61451636 1097 | 2.05 | Token: 0xfb 1098 | | Block2: 0/1/128 1099 | | Observe: 62354 1100 | | Max-Age: 60 1101 | | Payload: [128 bytes] 1102 | | 1103 |<-----+ Header: 2.05 0x4145af9c 1104 | 2.05 | Token: 0xfb 1105 | | Block2: 1/0/128 1106 | | Observe: 62354 1107 | | Max-Age: 60 1108 | | Payload: [27 bytes] 1109 | | 1110 +- - ->| Header: 0x6000af9c 1111 | | 1112 |<-----+ Header: 2.05 0x4145af9d 1113 | 2.05 | Token: 0xfb 1114 | | Block2: 0/1/128 1115 | | Observe: 62444 1116 | | Max-Age: 60 1117 | | Payload: [128 bytes] 1118 | | 1119 +- - ->| Header: 60005af9d 1120 | | 1121 |<-----+ Header: 2.05 0x4145af9e 1122 | 2.05 | Token: 0xfb 1123 | | Block2: 1/0/128 1124 | | Observe: 62444 1125 | | Max-Age: 60 1126 | | Payload: [27 bytes] 1127 | | 1128 +- - ->| Header: 0x6000af9e 1129 | | 1131 Figure 9: A server sends two notifications of two blocks each 1133 Appendix B. Modeling Resources to Tailor Notifications 1135 A server may want to provide notifications that respond to very 1136 specific conditions on some state. This is best done by modeling the 1137 resources that the server exposes according to these needs. 1139 For example, for a CoAP server with an attached temperature sensor, 1141 o the server could, in the simplest form, expose a resource 1142 that changes its state every second to 1143 the current temperature measured by the sensor; 1145 o the server could, however, also expose a resource 1146 that changes its state to "cold" 1147 when it's warm and the temperature drops below a preconfigured 1148 threshold, and to "warm" when it's cold and the temperature 1149 exceeds a second, higher threshold; 1151 o the server could expose a parameterized resource 1152 that changes its 1153 state every second to the current temperature if the sensor 1154 reading exceeds the specified parameter value, and that changes 1155 its state to "OK" when the temperature drops below; or 1157 o the server could expose a parameterized resource 1158 that accepts expressions of arbitrary 1160 complexity and changes its state accordingly. 1162 In any case, the client is notified about the current state of the 1163 resource whenever the state of the appropriately modeled resource 1164 changes. By designing resources that change their state on certain 1165 conditions, it is possible to notify the client only when these 1166 conditions occur instead of continuously supplying it with 1167 information it doesn't need. 1169 By parametrizing resources, this is not limited to conditions defined 1170 by the server, but can be extended to arbitrarily complex conditions 1171 defined by the client. Thus, the server designer can choose exactly 1172 the right level of complexity for the application envisioned and 1173 devices used, and is not constrained to a "one size fits all" 1174 mechanism built into the protocol. 1176 Appendix C. Changelog 1178 Changes from ietf-07 to ietf-08: 1180 o Expanded text on transmitting notification while a previous 1181 transmission is pending (#242). 1183 o Changed reordering detection to use a fixed time span of 128 1184 seconds instead of EXCHANGE_LIFETIME (#276). 1186 o Removed the use of the freshness model to determine if the client 1187 is still on the list of observers. This includes removing that 1189 * the client assumes that it has been removed from the list of 1190 observers when Max-Age ends; 1192 * the server sets the Max-Age Option of a notification to a value 1193 that indicates when the server will send the next notification; 1195 * the server uses a number of retransmit attempts such that 1196 removing a client from the list of observers before Max-Age 1197 ends is avoided (#235); 1199 * the server may remove the client from all lists of observers 1200 when the transmission of a confirmable notification ultimately 1201 times out. 1203 o Changed that an unrecognized critical option in a request must 1204 actually have no effect on the state of any observation 1205 relationship to any resource, as the option could lead to a 1206 different target resource. 1208 o Clarified that client implementations must be prepared to receive 1209 each notification equally as a confirmable or a non-confirmable 1210 message, regardless of the message type of the request and of any 1211 previous notification. 1213 o Added a requirement for sending a confirmable notification at 1214 least every 24 hours before continuing with non-confirmable 1215 notifications (#221). 1217 o Added congestion control considerations from [I-D.bormann-core- 1218 congestion-control-02]. 1220 o Recommended that the client waits for a randomized time after the 1221 freshness of the latest notification expired before re- 1222 registering. This prevents that multiple clients observing a 1223 resource perform a GET request at the same time when the need to 1224 re-register arises. 1226 o Changed reordering detection from 'MAY' to 'SHOULD', as the goal 1227 of the protocol (to keep the observed state as closely in sync 1228 with the actual state as possible) is not optional. 1230 o Fixed the length of the Observe (3 bytes) in the table in 1231 Section 2. 1233 o Replaced the 'x' in the No-Cache-Key column in the table in 1234 Section 2 with a '-', as the Observe Option doesn't have the No- 1235 Cache-Key flag set, even though it is not part of the cache key. 1237 o Updated examples. 1239 Changes from ietf-06 to ietf-07: 1241 o Moved to 24-bit sequence numbers to allow for up to 15000 1242 notifications per second per client and resource (#217). 1244 o Re-numbered option number to use Unsafe/Safe and Cache-Key 1245 compliant numbers (#241). 1247 o Clarified how to react to a Reset message that is sent in reply to 1248 a non-confirmable notification (#225). 1250 o Clarified the semantics of the "obs" link target attribute (#236). 1252 Changes from ietf-05 to ietf-06: 1254 o Improved abstract and introduction to say that the protocol is 1255 about best effort and eventual consistency (#219). 1257 o Clarified that the value of the Observe Option in a request must 1258 have zero length. 1260 o Added requirement that the sequence number must be updated each 1261 time a server retransmits a notification. 1263 o Clarified that a server must remove a client from the list of 1264 observers when it receives a GET request with an unrecognized 1265 critical option. 1267 o Updated the text to use the endpoint concept from 1268 [I-D.ietf-core-coap] (#224). 1270 o Improved the reordering text (#223). 1272 Changes from ietf-04 to ietf-05: 1274 o Recommended that a client does not re-register while a new 1275 notification from the server is still likely to arrive. This is 1276 to avoid that the request of the client and the last notification 1277 after max-age cross over each other (#174). 1279 o Relaxed requirements when sending a Reset message in reply to non- 1280 confirmable notifications. 1282 o Added an implementation note about careless GET requests (#184). 1284 o Updated examples. 1286 Changes from ietf-03 to ietf-04: 1288 o Removed the "Max-OFE" Option. 1290 o Allowed a Reset message in reply to non-confirmable notifications. 1292 o Added a section on cancellation. 1294 o Updated examples. 1296 Changes from ietf-02 to ietf-03: 1298 o Separated client-side and server-side requirements. 1300 o Fixed uncertainty if client is still on the list of observers by 1301 introducing a liveliness model based on Max-Age and a new option 1302 called "Max-OFE" (#174). 1304 o Simplified the text on message reordering (#129). 1306 o Clarified requirements for intermediaries. 1308 o Clarified the combination of blockwise transfers with 1309 notifications (#172). 1311 o Updated examples to show how the state observed by the client 1312 becomes eventually consistent with the actual state on the server. 1314 o Added examples for parameterization of observable resource. 1316 Changes from ietf-01 to ietf-02: 1318 o Removed the requirement of periodic refreshing (#126). 1320 o The new "Observe" Option replaces the "Lifetime" Option. 1322 o Introduced a new mechanism to detect message reordering. 1324 o Changed 2.00 (OK) notifications to 2.05 (Content) notifications. 1326 Changes from ietf-00 to ietf-01: 1328 o Changed terminology from "subscriptions" to "observation 1329 relationships" (#33). 1331 o Changed the name of the option to "Lifetime". 1333 o Clarified establishment of observation relationships. 1335 o Clarified that an observation is only identified by the URI of the 1336 observed resource and the identity of the client (#66). 1338 o Clarified rules for establishing observation relationships (#68). 1340 o Clarified conditions under which an observation relationship is 1341 terminated. 1343 o Added explanation on how clients can terminate an observation 1344 relationship before the lifetime ends (#34). 1346 o Clarified that the overriding objective for notifications is 1347 eventual consistency of the actual and the observed state (#67). 1349 o Specified how a server needs to deal with clients not 1350 acknowledging confirmable messages carrying notifications (#69). 1352 o Added a mechanism to detect message reordering (#35). 1354 o Added an explanation of how notifications can be cached, 1355 supporting both the freshness and the validation model (#39, #64). 1357 o Clarified that non-GET requests do not affect observation 1358 relationships, and that GET requests without "Lifetime" Option 1359 affecting relationships is by design (#65). 1361 o Described interaction with blockwise transfers (#36). 1363 o Added Resource Discovery section (#99). 1365 o Added IANA Considerations. 1367 o Added Security Considerations (#40). 1369 o Added examples (#38). 1371 Author's Address 1373 Klaus Hartke 1374 Universitaet Bremen TZI 1375 Postfach 330440 1376 Bremen D-28359 1377 Germany 1379 Phone: +49-421-218-63905 1380 Email: hartke@tzi.org