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