idnits 2.17.1 draft-ietf-core-observe-06.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 (September 6, 2012) is 4250 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 745, but not defined == Outdated reference: A later version (-21) exists of draft-ietf-core-block-09 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-11 ** 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 September 6, 2012 5 Expires: March 10, 2013 7 Observing Resources in CoAP 8 draft-ietf-core-observe-06 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 a server to replicate a resource state to interested 16 clients. The protocol follows a best-effort approach when 17 transmitting new resource states to a client, and provides eventual 18 consistency between the state observed by the client and the actual 19 resource state. 21 Editor's Note 23 This is an interim revision which will receive further modifications 24 during the resolution of open tickets, in particular #204, #217, #235 25 and #242. 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 March 10, 2013. 44 Copyright Notice 46 Copyright (c) 2012 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. Design Philosophy . . . . . . . . . . . . . . . . . . . . 6 65 1.4. Requirements Notation . . . . . . . . . . . . . . . . . . 6 66 2. The Observe Option . . . . . . . . . . . . . . . . . . . . . . 7 67 3. Client-side Requirements . . . . . . . . . . . . . . . . . . . 7 68 3.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 3.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 8 70 3.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 3.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 9 72 3.5. Cancellation . . . . . . . . . . . . . . . . . . . . . . . 10 73 4. Server-side Requirements . . . . . . . . . . . . . . . . . . . 11 74 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 11 75 4.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 11 76 4.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 12 77 4.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 13 78 4.5. Retransmission . . . . . . . . . . . . . . . . . . . . . . 13 79 5. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 14 80 6. Block-wise Transfers . . . . . . . . . . . . . . . . . . . . . 15 81 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 15 82 8. Security Considerations . . . . . . . . . . . . . . . . . . . 16 83 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 84 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 85 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 86 11.1. Normative References . . . . . . . . . . . . . . . . . . . 17 87 11.2. Informative References . . . . . . . . . . . . . . . . . . 17 88 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 18 89 A.1. Proxying . . . . . . . . . . . . . . . . . . . . . . . . . 21 90 A.2. Block-wise Transfer . . . . . . . . . . . . . . . . . . . 23 91 Appendix B. Modeling Resources to Tailor Notifications . . . . . 23 92 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . . 24 93 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 27 95 1. Introduction 97 1.1. Background 99 CoAP [I-D.ietf-core-coap] is an Application Protocol for Constrained 100 Nodes/Networks. It is intended to provide RESTful services [REST] 101 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 communication model of REST is that of a client exchanging 107 resource representations with an origin server. The origin server is 108 the definitive source for representations of the resources in its 109 namespace. A client interested in a resource sends a request to the 110 origin server that returns a response with a representation that is 111 current at the time of the request. 113 This model does not work well when a client is interested in having a 114 current representation of a resource over a period of time. Existing 115 approaches when using HTTP, such as repeated polling or long-polls 116 [RFC6202], generate significant complexity and/or overhead and thus 117 are less applicable in a constrained environment. 119 The protocol specified in this document extends the CoAP core 120 protocol with a mechanism to replicate a resource state from a server 121 to interested clients, while still keeping the properties of REST. 123 Note that there is no intention for this mechanism to solve the full 124 set of problems that the existing HTTP solutions solve, or to replace 125 publish/subscribe networks that solve a much more general problem 126 [RFC5989]. 128 1.2. Protocol Overview 130 The protocol is based on the well-known observer design pattern 131 [GOF]. 133 In this design pattern, components - called observers - register at a 134 specific, known provider - called the subject - that they are 135 interested in being notified whenever the subject undergoes a change 136 in state. The subject is responsible for administering its list of 137 registered observers. If multiple subjects are of interest, an 138 observer must register separately for all of them. The pattern is 139 typically used when a clean separation between related components is 140 required, such as data storage and user interface. 142 Observer Subject 143 | | 144 | Registration | 145 +----------------->| 146 | | 147 | Notification | 148 |<-----------------+ 149 | | 150 | Notification | 151 |<-----------------+ 152 | | 153 | Notification | 154 |<-----------------+ 155 | | 157 Figure 1: Observer Design Pattern 159 The observer design pattern is realized in CoAP as follows: 161 Subject: In the context of CoAP, the subject is a resource in the 162 namespace of a CoAP server. The state of the resource can change 163 over time, ranging from infrequent updates to continuous state 164 transformations. 166 Observer: An observer is a CoAP client that is interested in the 167 current state of the resource at any given time. 169 Registration: A client registers its interest by sending an extended 170 GET request to the server. In addition to returning a 171 representation of the target resource, this request causes the 172 server to add the client to the list of observers for the 173 resource. 175 Notification: Whenever the state of a resource changes, the server 176 notifies each client registered as observer for the resource. 177 Each notification is an additional CoAP response sent by the 178 server in reply to the GET request and includes a complete 179 representation of the new resource state. 181 Figure 2 shows an example of a CoAP client registering its interest 182 in a resource and receiving three notifications: the first with the 183 current state upon registration and then two notifications when the 184 state of the resource changes. Registration request and 185 notifications are identified by the presence of the Observe Option 186 defined in this document. All notifications echo the token specified 187 by the client in the request, so the client can easily correlate them 188 to the request. 190 Client Server 191 | | 192 | GET /temperature | 193 | Observe: | (registration) 194 | Token: 0x4a | 195 +----------------->| 196 | | 197 | 2.05 Content | 198 | Observe: 12 | (notification of the current state) 199 | Token: 0x4a | 200 | Payload: 22.9 C | 201 |<-----------------+ 202 | | 203 | 2.05 Content | 204 | Observe: 44 | (notification upon a state change) 205 | Token: 0x4a | 206 | Payload: 22.8 C | 207 |<-----------------+ 208 | | 209 | 2.05 Content | 210 | Observe: 60 | (notification upon a state change) 211 | Token: 0x4a | 212 | Payload: 23.1 C | 213 |<-----------------+ 214 | | 216 Figure 2: Observing a Resource in CoAP 218 A client remains on the list of observers as long as the server can 219 determine the client's continued interest in the resource. The 220 interest is determined by the server from the client's 221 acknowledgement of notifications sent in confirmable messages. If 222 the client rejects a notification or if the transmission of a 223 notification ultimately fails, then the client is assumed to be no 224 longer interested and is removed by the server from the list of 225 observers. 227 A notification is cacheable like any other response and can be used 228 until the next notification arrives. Each notification includes an 229 indication of when the server will send the next notification at 230 latest (Max-Age). This helps a client that does not receive a 231 notification for a while, to decide if the resource simply did not 232 undergo a change of state yet or if the next notification is overdue 233 and the server is apparently no longer aware of the client's interest 234 in the resource. 236 When a client wants to be notified after it has determined that no 237 further notifications can be expected, it needs to register again. 239 1.3. Design Philosophy 241 The protocol builds on the architectural elements of REST, which 242 include: a server that is responsible for the state and 243 representation of the resources in its namespace, a client that is 244 responsible for keeping the application state, and the stateless 245 exchange of resource representations. (Beyond stateless REST, a 246 server needs to keep track of the observers though, somewhat similar 247 to how HTTP servers need to keep track of the TCP connections from 248 their clients.) The protocol enables high scalability and efficiency 249 through the support of caches and intermediaries that multiplex the 250 interest of multiple clients in the same resource into a single 251 association. 253 The server is the authority for determining under what conditions 254 resources change their state and how often observers are notified. 255 The protocol does not offer explicit means for setting up triggers, 256 thresholds or other conditions; it is up to the server to expose 257 observable resources that change their state in a way that is 258 meaningful in the application context. Resources can be 259 parameterized to achieve similar effects though; see Appendix B for 260 examples. 262 Since bandwidth is in short supply in constrained environments, a 263 server must adapt the rate of notifications to each client. This 264 implies that a client cannot rely on observing every single state a 265 resource goes through. Instead, the protocol follows a best-effort 266 approach when transmitting the new resource state after a state 267 change: clients should see the new state after a state change as soon 268 as possible, and they should see as many states as possible. 270 Furthermore, the protocol is designed on the principle of eventual 271 consistency: it guarantees that if the resource does not undergo a 272 new change in state, eventually all registered observers will have a 273 current representation of the last resource state. 275 1.4. Requirements Notation 277 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 278 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 279 document are to be interpreted as described in RFC 2119 [RFC2119]. 281 2. The Observe Option 283 +-----+----+----+---------+------------+-----------+---------+ 284 | No. | C. | R. | Name | Format | Length | Default | 285 +-----+----+----+---------+------------+-----------+---------+ 286 | 10 | no | no | Observe | empty/uint | 0 B/0-2 B | (none) | 287 +-----+----+----+---------+------------+-----------+---------+ 289 C=Critical, R=Repeatable 291 The Observe Option, when present, modifies the GET method so it does 292 not only retrieve a representation of the current state of the 293 resource identified by the request URI, but also requests the server 294 to add the client to the list of observers of the resource. The 295 exact semantics are defined in the sections below. The value of the 296 option in a request MUST be empty on transmission and MUST be ignored 297 on reception. 299 In a response, the Observe Option identifies the message as a 300 notification, which implies that the client has been added to the 301 list of observers and that the server will notify the client of 302 further changes to the resource state. The option's value is a 303 sequence number that can be used for reordering detection (see 304 Section 3.4 and Section 4.4). The value is encoded as a variable- 305 length unsigned integer as defined in Section 3.3.1 of RFC XXXX 306 [I-D.ietf-core-coap]. 308 Since the Observe Option is not critical, a GET request that includes 309 the Observe Option will automatically fall back to a normal GET 310 request if the server is unwilling or unable to add the client to the 311 list of observers. 313 3. Client-side Requirements 315 3.1. Request 317 A client can register its interest in a resource by issuing a GET 318 request that includes an empty Observe Option. If the server returns 319 a 2.xx response that includes an Observe Option as well, the server 320 has added the client successfully to the list of observers of the 321 target resource and the client will be notified of changes to the 322 resource state for as long as the server can assume the client's 323 interest. 325 3.2. Notifications 327 Notifications are additional responses sent by the server in reply to 328 the GET request. Each notification includes an Observe Option with a 329 sequence number (see Section 3.4), a Token Option that matches the 330 token specified by the client in the GET request, and a payload of 331 the same media type as the initial response. 333 A notification can be confirmable or non-confirmable (i.e. sent in a 334 confirmable or non-confirmable message). If a client does not 335 recognize the token in a confirmable notification, it MUST NOT 336 acknowledge the message and SHOULD reject it with a RST message. 337 Otherwise, the client MUST acknowledge the message with an ACK 338 message as usual. If a client does not recognize the token in a non- 339 confirmable notification, it MAY reject it with a RST message. 341 An acknowledgement signals to the server that the client is alive and 342 interested in receiving further notifications; if the server does not 343 receive an acknowledgement in reply to a confirmable notification, it 344 will assume that the client is no longer interested and will 345 eventually remove it from the list of observers. 347 Notifications will have a 2.05 (Content) response code in most cases. 348 They may also have a 2.03 (Valid) response code if the client 349 includes an ETag Option in its request (see Section 3.3). In the 350 event that the state of an observed resource is changed in a way that 351 would cause a normal GET request not to return success (for example, 352 when the resource is deleted), the server will send a notification 353 with a non-success response code (such as 4.xx/5.xx) and empty the 354 list of observers of the resource. 356 3.3. Caching 358 As notifications are just additional responses, notifications partake 359 in caching as defined by Section 5.6 of RFC XXXX 360 [I-D.ietf-core-coap]. Both the freshness model and the validation 361 model are supported. The freshness model also serves as the model 362 for the client to determine if it's still on the list of observers or 363 if it needs to re-register its interest in the resource. 365 A client MAY store a notification like a response in its cache and 366 use a stored notification/response that is fresh without contacting 367 the origin server. A notification/response is considered fresh while 368 its age is not greater than its Max-Age and no newer notification has 369 been received. 371 The server will do its best to keep the client up to date with a 372 fresh representation of the current resource state. It will send a 373 notification whenever the resource changes, or at latest when the age 374 of the last notification becomes greater than its Max-Age. (Note 375 that this notification may not arrive in time due to network 376 latency.) 378 The client SHOULD assume that it's on the list of observers while the 379 age of the last notification is not greater than Max-Age. If the 380 client does not receive a notification before the age becomes greater 381 than Max-Age, it can assume that it has been removed from the list of 382 observers (e.g., due to a loss of server state). In this case, it 383 may need to re-register its interest. 385 To make sure it has a fresh representation and/or to re-register its 386 interest, a client MAY issue a new GET request with an Observe Option 387 at any time. The GET request SHOULD specify a new token to avoid 388 ambiguity, because the token serves as epoch identifier for the 389 sequence numbers in the Observe Option (see Section 3.4). 391 It is RECOMMENDED that the client does not issue the request while it 392 still has a fresh notification and, beyond that, while a new 393 notification from the server is still likely to arrive. I.e. the 394 client should wait until the age of the last notification becomes 395 greater than its Max-Age plus MAX_LATENCY (the maximum time a 396 datagram is expected to take from the start of its transmission to 397 the completion of its reception; see Section 4.8 of RFC XXXX 398 [I-D.ietf-core-coap]). 400 When a client has one or more notifications stored, it can use the 401 ETag Option in the GET request to give the server an opportunity to 402 select a stored response to be used. The client MAY include an ETag 403 Option for each stored response that is applicable. It needs to keep 404 those responses in the cache until it is no longer interested in 405 receiving notifications for the target resource or it issues a new 406 GET request with a new set of entity-tags. Whenever the observed 407 resource changes its state to a representation identified by one of 408 the ETag Options, the server can select a stored response by sending 409 a 2.03 (Valid) notification with an appropriate ETag Option instead 410 of a 2.05 (Content) notification. 412 3.4. Reordering 414 Messages that carry notifications can arrive in a different order 415 than they were sent. Since the goal is eventual consistency (see 416 Section 1.3), a client MAY safely skip a notification that arrives 417 later than a newer notification. For this purpose, the server sets 418 the value of the Observe Option in each notification to a sequence 419 number. 421 A notification is older than the latest notification received and 422 thus can be skipped when the following condition is met: 424 (V1 - V2) % (2**16) < (2**15) and T2 < (T1 + (2**14)) 426 where V1 is the value of the Observe Option of the latest valid 427 notification received, V2 the value of the Observe Option of the 428 present notification, T1 a client-local timestamp of the latest valid 429 notification received (in seconds), and T2 a client-local timestamp 430 of the present notification. 432 Design Note: The first condition essentially verifies that V2 > V1 433 holds in 16-bit sequence number arithmetic [RFC1982]. The second 434 condition checks that the time expired between the two incoming 435 messages is not so large that the sequence number might have 436 wrapped around and the first check is therefore invalid. (In 437 other words, after about 2**14 seconds elapse without any 438 notification, the client does not need to check the sequence 439 numbers in order to assume an incoming notification is new.) The 440 constants of 2**14 and 2**15 are non-critical, as is the even 441 speed or precision of the clock involved. 443 3.5. Cancellation 445 When a client rejects a confirmable notification with a RST message 446 or when it performs a GET request without an Observe Option for a 447 currently observed resource, the server will remove the client from 448 the list of observers for this resource. The client MAY use either 449 method at any time to indicate that it is no longer interested in 450 receiving notifications about a resource. 452 When a client rejects non-confirmable notification with a RST, there 453 is also a chance that the server will remove the client from the list 454 of observers for this resource. So the client MAY try this method as 455 well. A client MAY rate-limit the RST messages it sends if the 456 server appears to persistently ignore them. 458 Implementation Note: A client that does not mediate all its requests 459 through its cache might inadvertantly cancel an observation 460 relationship by sending an unrelated GET to the same resource. To 461 avoid this, without incurring a need for synchronization, such 462 clients can use a different source transport address for these 463 unrelated GET requests. 465 4. Server-side Requirements 467 4.1. Request 469 A GET request that includes an Observe Option requests the server not 470 only to return a representation of the resource identified by the 471 request URI, but also to add the client to the list of observers of 472 the target resource. If no error occurs, the server MUST return a 473 response with the representation of the current resource state and 474 MUST notify the client of subsequent changes to the state as long as 475 the client is on the list of observers. 477 A server that is unable or unwilling to add the client to the list of 478 observers of the target resource MAY silently ignore the Observe 479 Option and process the GET request as usual. The resulting response 480 MUST NOT include an Observe Option, the absence of which signals to 481 the client that it will not be notified of changes to the resource 482 state and, e.g., needs to poll the resource instead. 484 If the client is already on the list of observers, the server MUST 485 NOT add it a second time but MUST replace or update the existing 486 entry. If the server receives a GET request for the same resource 487 that does not include an Observe Option or a GET request that 488 includes an unrecognized critical option, the server MUST remove the 489 client from the list of observers. 491 Two requests relate to the same list entry if and only if both the 492 request URI and the source endpoint of the requests match. Message 493 IDs and tokens are not taken into account. 495 Any request with a method other than GET MUST NOT have a direct 496 effect on a list of observers of a resource. However, such a request 497 can have the indirect consequence of causing the server to send a 498 non-success notification which does affect the list of observers 499 (e.g., when a DELETE request is successful and an observed resource 500 no longer exists). 502 4.2. Notifications 504 A client is notified of resource state changes by additional 505 responses sent by the server in reply to the GET request. Each such 506 notification response MUST include an Observe Option and MUST echo 507 the token specified by the client in the GET request. If there are 508 multiple clients on the list of observers, the order in which they 509 are notified is not defined; the server is free to use any method to 510 determine the order. 512 A notification SHOULD have a 2.05 (Content) or 2.03 (Valid) response 513 code. However, in the event that the state of a resource changes in 514 a way that would cause a normal GET request to return a non-success 515 response code (for example, if the resource is deleted), the server 516 SHOULD notify the client by sending a notification with an 517 appropriate non-success response code (such as 4.xx/5.xx) and MUST 518 empty the list of observers of the resource. 520 The media type used in a notification MUST be the same as the one 521 used in the initial response to the GET request. If the server is 522 unable to continue sending notifications using this media type, it 523 SHOULD send a notification with a 5.00 (Internal Server Error) 524 response code and MUST empty the list of observers of the resource. 526 A notification can be sent as a confirmable or a non-confirmable 527 message. The message type used is typically application-dependent 528 and MAY be determined by the server for each notification 529 individually. For example, for resources that change in a somewhat 530 predictable or regular fashion, notifications can be sent in non- 531 confirmable messages; for resources that change infrequently, 532 notifications can be sent in confirmable messages. The server can 533 combine these two approaches depending on the frequency of state 534 changes and the importance of individual notifications. 536 The acknowledgement of a confirmable notification implies the 537 client's continued interest in being notified. If the client rejects 538 a confirmable notification with a RST message, the server MUST remove 539 the client from the list of observers. If the client rejects a non- 540 confirmable notification with a RST message, the server MAY remove 541 the client from the list of observers. 543 If CoAP is used over a connection-oriented or session-based transport 544 such as DTLS, the server MUST remove the client from the list of 545 observers when the connection or session is closed. 547 4.3. Caching 549 The Max-Age Option of a notification SHOULD be set to a value that 550 indicates when the server will send the next notification. For 551 example, if the server sends a notification every 30 seconds, a Max- 552 Age Option with value 30 should be included. The server MAY send a 553 new notification before Max-Age ends and MUST send a new notification 554 at latest when Max-Age ends. If the client does not receive a new 555 notification before Max-Age ends, it will assume that it was removed 556 from the list of observers (e.g., due to a loss of server state) and 557 may issue a new GET request to re-register its interest. 559 It may not always be possible to predict when the server will send 560 the next notification, for example, when a resource does not change 561 its state in regular intervals. In this case, the server SHOULD set 562 Max-Age to a good approximation. The value is a trade-off between 563 increased usage of bandwidth and the risk of stale information. 564 Smaller values lead to more notifications and more GET requests, 565 while greater values result in network or device failures being 566 detected later and data becoming stale. 568 The client can include a set of entity-tags in its request using the 569 ETag Option. When the 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 recipient has any response stored other than 575 those identified by the entity-tags in the most recent GET request 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 in each notification to the 16 least-significant bits of a strictly 584 increasing sequence number. The sequence number MAY start at any 585 value. The server MUST NOT reuse the same option value with the same 586 client, token and resource within approximately 2**16 seconds 587 (roughly 18.2 hours). 589 Implementation Note: A simple implementation that satisfies the 590 requirements is to use a timestamp (in seconds) provided by the 591 device's clock, or a 16-bit unsigned integer variable that is 592 incremented every second and wraps around every 2**16 seconds. It 593 is not necessary that the clock reflects the correct local time or 594 that it ticks exactly every second. Note that, on average, a 595 server cannot send more than one notification per second per 596 client, token and resource. 598 4.5. Retransmission 600 In CoAP, confirmable messages are retransmitted in exponentially 601 increasing intervals for a certain number of attempts until they are 602 acknowledged by the client. In the context of observing a resource, 603 it is undesirable to continue transmitting the representation of a 604 resource state when the state has changed in the meantime. 606 When a server is in the process of delivering a confirmable 607 notification and is waiting for an acknowledgement, and it wants to 608 notify the client of a state change using a new confirmable message, 609 it MUST stop retransmitting the old notification and SHOULD attempt 610 to deliver the new notification with the number of attempts remaining 611 from the old notification. When the last attempt to retransmit a 612 confirmable message with a notification for a resource times out, the 613 server SHOULD remove the client from the list of observers and 614 additionally MAY remove the client from the lists of observers of all 615 resources in its namespace. 617 The server SHOULD use a number of retransmit attempts 618 (MAX_RETRANSMIT) such that removing a client from the list of 619 observers before Max-Age ends is avoided. 621 A server MAY choose to skip a notification if it knows that it will 622 send another notification soon (e.g., when the state is changing 623 frequently). Similarly, it MAY choose to send a notification more 624 than once. For example, when state changes occur in bursts, the 625 server can skip some notifications, send the notifications in non- 626 confirmable messages, and make sure that the client observes the 627 latest state change after the burst by repeating the last 628 notification in a confirmable message. 630 When a notification is transmitted multiple times (either as caused 631 by a retransmission attempt or repeating it), the server MUST update 632 value of the Observe Option. Otherwise, the client might discard the 633 notification as too old. 635 5. Intermediaries 637 A client may be interested in a resource in the namespace of an 638 origin server that is reached through one or more CoAP-to-CoAP 639 intermediaries. In this case, the client registers its interest with 640 the first intermediary towards the origin server, acting as if it was 641 communicating with the origin server itself as specified in 642 Section 3. It is the task of this intermediary to provide the client 643 with a current representation of the target resource and send 644 notifications upon changes to the target resource state, much like an 645 origin server as specified in Section 4. 647 To perform this task, the intermediary SHOULD make use of the 648 protocol specified in this document, taking the role of the client 649 and registering its own interest in the target resource with the next 650 hop. If the next hop does not return a response with an Observe 651 Option, the intermediary MAY resort to polling the next hop, or MAY 652 itself return a response without an Observe Option. Note that the 653 communication between each pair of hops is independent, i.e. each hop 654 in the server role MUST determine individually how many notifications 655 to send, of which type, and so on. Each hop MUST generate its own 656 values for the Observe Option, and MUST set the value of the Max-Age 657 Option according to the age of the local current representation. 659 Because a client (or an intermediary in the client role) can only be 660 once in the list of observers of a resource at a server (or an 661 intermediary in the server role) -- it is useless to observe the same 662 resource multiple times -- an intermediary MUST observe a resource 663 only once, even if there are multiple clients for which it observes 664 the resource. 666 Note that an intermediary is not required to have a client to observe 667 a resource; an intermediary MAY observe a resource, for instance, 668 just to keep its own cache up to date. 670 See Appendix A.1 for examples. 672 6. Block-wise Transfers 674 Resources observed by clients may be larger than can be comfortably 675 processed or transferred in one CoAP message. CoAP provides a block- 676 wise transfer mechanism to address this problem 677 [I-D.ietf-core-block]. The following rules apply to the combination 678 of block-wise transfers with notifications. 680 As with basic GET transfers, the client can indicate its desired 681 block size in a Block2 Option in the GET request. If the server 682 supports block-wise transfers, it SHOULD take note of the block size 683 for all notifications/responses resulting from the GET request (until 684 the client is removed from the list of observers or the server 685 receives a new GET request from the client). 687 When sending a 2.05 (Content) notification, the server always sends 688 all blocks of the representation, suitably sequenced by its 689 congestion control mechanism, even if only some of the blocks have 690 changed with respect to a previous value. The server performs the 691 block-wise transfer by making use of the Block2 Option in each block. 692 When reassembling representations that are transmitted in multiple 693 blocks, the client MUST NOT combine blocks carrying different Observe 694 Option values, or blocks that have been received more than 695 approximately 2**14 seconds apart. 697 See Appendix A.2 for an example. 699 7. Discovery 701 A web link [RFC5988] to a resource accessible by the CoAP protocol 702 MAY indicate that the server encourages the observation of this 703 resource by including the target attribute "obs". This is 704 particularly useful in link-format documents [RFC6690]. 706 This target attribute is used as a flag, and thus it has no value 707 component -- a value given for the attribute MUST NOT be given for 708 this version of the specification and MUST be ignored if present. 709 The target attribute "obs" MUST NOT be given more than once for this 710 version of the specification. 712 8. Security Considerations 714 The security considerations of RFC XXXX [I-D.ietf-core-coap] apply. 716 Note that the considerations about amplification attacks are somewhat 717 amplified when observing resources. Without client authentication, a 718 server MUST therefore strictly limit the number of notifications that 719 it sends between receiving acknowledgements that confirm the actual 720 interest of the client in the data; i.e., any notifications sent in 721 non-confirmable messages MUST be interspersed with confirmable 722 messages. (An attacker may still spoof the acknowledgements if the 723 confirmable messages are sufficiently predictable.) 725 As with any protocol that creates state, attackers may attempt to 726 exhaust the resources that the server has available for maintaining 727 the list of observers for each resource. Servers may want to access- 728 control this creation of state. As degraded behavior, the server can 729 always fall back to processing the request as a normal GET request 730 (without an Observe Option) if it is unwilling or unable to add a 731 client to the list of observers of a resource, including if system 732 resources are exhausted or nearing exhaustion. 734 Intermediaries must be careful to ensure that notifications cannot be 735 employed to create a loop. A simple way to break any loops is to 736 employ caches for forwarding notifications in intermediaries. 738 9. IANA Considerations 740 The following entries are added to the CoAP Option Numbers registry: 742 +--------+---------+-----------+ 743 | Number | Name | Reference | 744 +--------+---------+-----------+ 745 | 10 | Observe | [RFCXXXX] | 746 +--------+---------+-----------+ 748 10. Acknowledgements 750 Carsten Bormann was an original author of this draft and is 751 acknowledged for significant contribution to this document. 753 Thanks to Daniele Alessandrelli, Jari Arkko, Peter Bigot, Angelo 754 Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank, 755 Cullen Jennings, Matthias Kovatsch, Salvatore Loreto, Charles Palmer 756 and Zach Shelby for helpful comments and discussions that have shaped 757 the document. 759 Klaus Hartke was funded by the Klaus Tschira Foundation. 761 11. References 763 11.1. Normative References 765 [I-D.ietf-core-block] 766 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 767 draft-ietf-core-block-09 (work in progress), August 2012. 769 [I-D.ietf-core-coap] 770 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 771 "Constrained Application Protocol (CoAP)", 772 draft-ietf-core-coap-11 (work in progress), July 2012. 774 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 775 Requirement Levels", BCP 14, RFC 2119, March 1997. 777 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 779 11.2. Informative References 781 [GOF] Gamma, E., Helm, R., Johnson, R., and J. Vlissides, 782 "Design Patterns: Elements of Reusable Object-Oriented 783 Software", Addison-Wesley, Reading, MA, USA, 784 November 1994. 786 [REST] Fielding, R., "Architectural Styles and the Design of 787 Network-based Software Architectures", Ph.D. Dissertation, 788 University of California, Irvine, 2000, . 792 [RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982, 793 August 1996. 795 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 796 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 797 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 799 [RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes 800 to an HTTP Resource", RFC 5989, October 2010. 802 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 803 "Known Issues and Best Practices for the Use of Long 804 Polling and Streaming in Bidirectional HTTP", RFC 6202, 805 April 2011. 807 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 808 Format", RFC 6690, August 2012. 810 Appendix A. Examples 812 Observed CLIENT SERVER Actual 813 t State | | State 814 ____________ | | ____________ 815 1 | | 816 2 unknown | | 18.5 C 817 3 +----->| Header: GET 0x43011633 818 4 | GET | Token: 0x4a 819 5 | | Uri-Path: temperature 820 6 | | Observe: 821 7 | | 822 8 | | 823 9 ____________ |<-----+ Header: 2.05 0x63451633 824 10 | 2.05 | Token: 0x4a 825 11 18.5 C | | Observe: 9 826 12 | | Max-Age: 15 827 13 | | Payload: "18.5 C" 828 14 | | 829 15 | | ____________ 830 16 ____________ |<-----+ Header: 2.05 0x53457b50 831 17 | 2.05 | 19.2 C Token: 0x4a 832 18 19.2 C | | Observe: 16 833 29 | | Max-Age: 15 834 20 | | Payload: "19.2 C" 835 21 | | 837 Figure 3: A client registers and receives a notification of the 838 current state and upon a state change 840 Observed CLIENT SERVER Actual 841 t State | | State 842 ____________ | | ____________ 843 22 | | 844 23 19.2 C | | 19.2 C 845 24 | | ____________ 846 25 | X----+ Header: 2.05 0x53457b51 847 26 | 2.05 | 19.7 C Token: 0x4a 848 27 | | Observe: 25 849 28 | | Max-Age: 15 850 29 | | Payload: "19.7 C" 851 30 | | 852 31 ____________ | | 853 32 +----->| Header: GET 0x43011633 854 33 19.2 C | GET | Token: 0xb2 855 34 (stale) | | Uri-Path: temperature 856 35 | | Observe: 857 36 | | 858 37 | | 859 38 ____________ |<-----+ Header: 2.05 0x54457b52 860 39 | 2.05 | Token: 0xb2 861 40 19.7 C | | Observe: 38 862 41 | | Max-Age: 15 863 42 | | ETag: 0x78797a7a79 864 43 | | Payload: "19.7 C" 865 44 | | 867 Figure 4: The client re-registers after Max-Age ends 869 Observed CLIENT SERVER Actual 870 t State | | State 871 ____________ | | ____________ 872 45 | | 873 46 19.7 C | | 19.7 C 874 47 | | 875 48 | | ____________ 876 49 | CRASH 877 50 | 878 51 | 879 52 | | 880 53 ____________ | | ____________ 881 54 +----->| Header: GET 0x44011634 882 55 19.7 C | GET | 20.0 C Token: 0xf9 883 56 (stale) | | Uri-Path: temperature 884 57 | | Observe: 885 58 | | ETag: 0x78797a7a79 886 59 | | 887 60 | | 888 61 ____________ |<-----+ Header: 2.05 0x63451634 889 62 | 2.05 | Token: 0xf9 890 63 20.0 C | | Observe: 61 891 64 | | Max-Age: 15 892 65 | | Payload: "20.0 C" 893 66 | | 894 67 | | ____________ 895 68 ____________ |<-----+ Header: 2.03 0x5443aa0c 896 69 | 2.03 | 19.7 C Token: 0xf9 897 70 19.7 C | | Observe: 68 898 71 | | ETag: 0x78797a7a79 899 72 | | Max-Age: 15 900 73 | | 902 Figure 5: The client re-registers and gives the server the 903 opportunity to select a stored response 905 A.1. Proxying 907 CLIENT PROXY SERVER 908 | | | 909 | +----->| Header: GET 0x44015fb8 910 | | GET | Token: 0x1a 911 | | | Uri-Host: sensor.example 912 | | | Uri-Path: status 913 | | | Observe: 914 | | | 915 | |<-----+ Header: 2.05 0x63455fb8 916 | | 2.05 | Token: 0x1a 917 | | | Observe: 42 918 | | | Max-Age: 60 919 | | | Payload: "ready" 920 | | | 921 +----->| | Header: GET 0x42011633 922 | GET | | Token: 0x9a 923 | | | Proxy-Uri: coap://sensor.example/status 924 | | | 925 |<-----+ | Header: 2.05 0x62451633 926 | 2.05 | | Token: 0x9a 927 | | | Max-Age: 53 928 | | | Payload: "ready" 929 | | | 930 | |<-----+ Header: 2.05 0x534505fc0 931 | | 2.05 | Token: 0x1a 932 | | | Observe: 135 933 | | | Max-Age: 60 934 | | | Payload: "busy" 935 | | | 936 +----->| | Header: GET 0x42011634 937 | GET | | Token: 0x9b 938 | | | Proxy-Uri: coap://sensor.example/status 939 | | | 940 |<-----+ | Header: 2.05 0x62451634 941 | 2.05 | | Token: 0x9b 942 | | | Max-Age: 49 943 | | | Payload: "busy" 944 | | | 946 Figure 6: A proxy observes a resource to keep its cache up to date 948 CLIENT PROXY SERVER 949 | | | 950 +----->| | Header: GET 0x43011635 951 | GET | | Token: 0x6a 952 | | | Proxy-Uri: coap://sensor.example/status 953 | | | Observe: 954 | | | 955 |<- - -+ | Header: 0x60001635 956 | | | 957 | +----->| Header: GET 0x4401af90 958 | | GET | Token: 0xaa 959 | | | Uri-Host: sensor.example 960 | | | Uri-Path: status 961 | | | Observe: 962 | | | 963 | |<-----+ Header: 2.05 0x6345af90 964 | | 2.05 | Token: 0xaa 965 | | | Observe: 67 966 | | | Max-Age: 60 967 | | | Payload: "ready" 968 | | | 969 |<-----+ | Header: 2.05 0x4345af94 970 | 2.05 | | Token: 0x6a 971 | | | Observe: 17346 972 | | | Max-Age: 60 973 | | | Payload: "ready" 974 | | | 975 +- - ->| | Header: 0x6000af94 976 | | | 977 | |<-----+ Header: 2.05 0x53455a20 978 | | 2.05 | Token: 0xaa 979 | | | Observe: 157 980 | | | Max-Age: 60 981 | | | Payload: "busy" 982 | | | 983 |<-----+ | Header: 2.05 0x5345af9b 984 | 2.05 | | Token: 0x6a 985 | | | Observe: 17436 986 | | | Max-Age: 60 987 | | | Payload: "busy" 988 | | | 990 Figure 7: A client observes a resource through a proxy 992 A.2. Block-wise Transfer 994 CLIENT SERVER 995 | | 996 +----->| Header: GET 0x43011636 997 | GET | Token: 0xfb 998 | | Uri-Path: status-icon 999 | | Observe: 1000 | | 1001 |<-----+ Header: 2.05 0x64451636 1002 | 2.05 | Token: 0xfb 1003 | | Block2: 0/1/128 1004 | | Observe: 62354 1005 | | Max-Age: 60 1006 | | Payload: [128 bytes] 1007 | | 1008 |<-----+ Header: 2.05 0x5445af9c 1009 | 2.05 | Token: 0xfb 1010 | | Block2: 1/0/128 1011 | | Observe: 62354 1012 | | Max-Age: 60 1013 | | Payload: [27 bytes] 1014 | | 1015 |<-----+ Header: 2.05 0x5445af9d 1016 | 2.05 | Token: 0xfb 1017 | | Block2: 0/1/128 1018 | | Observe: 62444 1019 | | Max-Age: 60 1020 | | Payload: [128 bytes] 1021 | | 1022 |<-----+ Header: 2.05 0x5445af9e 1023 | 2.05 | Token: 0xfb 1024 | | Block2: 1/0/128 1025 | | Observe: 62444 1026 | | Max-Age: 60 1027 | | Payload: [27 bytes] 1028 | | 1030 Figure 8: A server sends two notifications of two blocks each 1032 Appendix B. Modeling Resources to Tailor Notifications 1034 A server may want to provide notifications that respond to very 1035 specific conditions on some state. This is best done by modeling the 1036 resources that the server exposes according to these needs. 1038 For example, for a CoAP server with an attached temperature sensor, 1039 o the server could, in the simplest form, expose a resource 1040 that changes its state every second to 1041 the current temperature measured by the sensor; 1043 o the server could, however, also expose a resource 1044 that changes its state to "cold" 1045 when the temperature drops below a preconfigured threshold, and to 1046 "warm" when the temperature exceeds a second, higher threshold; 1048 o the server could expose a parameterized resource 1049 that changes its 1050 state to the current temperature if the temperature exceeds the 1051 specified value, and changes its state to "OK" when the 1052 temperature drops below; or 1054 o the server could expose a parameterized resource that accepts expressions of arbitrary 1057 complexity and changes its state accordingly. 1059 In any case, the client is notified about the current state of the 1060 resource whenever the state of the appropriately modeled resource 1061 changes. By designing resources that change their state on certain 1062 conditions, it is possible to notify the client only when these 1063 conditions occur instead of continuously supplying it with 1064 information it doesn't need. With parametrized resources, this is 1065 not limited to conditions defined by the server, but can be extended 1066 to arbitrarily complex conditions defined by the client. Thus, the 1067 server designer can choose exactly the right level of complexity for 1068 the application envisioned and devices used, and is not constrained 1069 to a "one size fits all" mechanism built into the protocol. 1071 Appendix C. Changelog 1073 Changes from ietf-05 to ietf-06: 1075 o Improved abstract and introduction to say that the protocol is 1076 about best effort and eventual consistency (#219). 1078 o Clarified that the value of the Observe Option in a request must 1079 have zero length. 1081 o Added requirement that the sequence number must be updated each 1082 time a server retransmits a notification. 1084 o Clarified that a server must remove a client from the list of 1085 observers when it receives a GET request with an unrecognized 1086 critical option. 1088 o Updated the text to use the endpoint concept from 1089 [I-D.ietf-core-coap] (#224). 1091 o Improved the reordering text (#223). 1093 Changes from ietf-04 to ietf-05: 1095 o Recommended that a client does not re-register while a new 1096 notification from the server is still likely to arrive. This is 1097 to avoid that the request of the client and the last notification 1098 after max-age cross over each other (#174). 1100 o Relaxed requirements when sending RST in reply to non-confirmable 1101 notifications. 1103 o Added an implementation note about careless GETs (#184). 1105 o Updated examples. 1107 Changes from ietf-03 to ietf-04: 1109 o Removed the "Max-OFE" Option. 1111 o Allowed RST in reply to non-confirmable notifications. 1113 o Added a section on cancellation. 1115 o Updated examples. 1117 Changes from ietf-02 to ietf-03: 1119 o Separated client-side and server-side requirements. 1121 o Fixed uncertainty if client is still on the list of observers by 1122 introducing a liveliness model based on Max-Age and a new option 1123 called "Max-OFE" (#174). 1125 o Simplified the text on message reordering (#129). 1127 o Clarified requirements for intermediaries. 1129 o Clarified the combination of block-wise transfers with 1130 notifications (#172). 1132 o Updated examples to show how the state observed by the client 1133 becomes eventually consistent with the actual state on the server. 1135 o Added examples for parameterization of observable resource. 1137 Changes from ietf-01 to ietf-02: 1139 o Removed the requirement of periodic refreshing (#126). 1141 o The new "Observe" Option replaces the "Lifetime" Option. 1143 o Introduced a new mechanism to detect message reordering. 1145 o Changed 2.00 (OK) notifications to 2.05 (Content) notifications. 1147 Changes from ietf-00 to ietf-01: 1149 o Changed terminology from "subscriptions" to "observation 1150 relationships" (#33). 1152 o Changed the name of the option to "Lifetime". 1154 o Clarified establishment of observation relationships. 1156 o Clarified that an observation is only identified by the URI of the 1157 observed resource and the identity of the client (#66). 1159 o Clarified rules for establishing observation relationships (#68). 1161 o Clarified conditions under which an observation relationship is 1162 terminated. 1164 o Added explanation on how clients can terminate an observation 1165 relationship before the lifetime ends (#34). 1167 o Clarified that the overriding objective for notifications is 1168 eventual consistency of the actual and the observed state (#67). 1170 o Specified how a server needs to deal with clients not 1171 acknowledging confirmable messages carrying notifications (#69). 1173 o Added a mechanism to detect message reordering (#35). 1175 o Added an explanation of how notifications can be cached, 1176 supporting both the freshness and the validation model (#39, #64). 1178 o Clarified that non-GET requests do not affect observation 1179 relationships, and that GET requests without "Lifetime" Option 1180 affecting relationships is by design (#65). 1182 o Described interaction with block-wise transfers (#36). 1184 o Added Resource Discovery section (#99). 1186 o Added IANA Considerations. 1188 o Added Security Considerations (#40). 1190 o Added examples (#38). 1192 Author's Address 1194 Klaus Hartke 1195 Universitaet Bremen TZI 1196 Postfach 330440 1197 Bremen D-28359 1198 Germany 1200 Phone: +49-421-218-63905 1201 Email: hartke@tzi.org