idnits 2.17.1 draft-ietf-core-observe-03.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 31, 2011) is 4560 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 708, but not defined == Outdated reference: A later version (-21) exists of draft-ietf-core-block-04 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-07 ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-14) exists of draft-ietf-core-link-format-07 -- 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 (~~), 5 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 Z. Shelby, Ed. 5 Expires: May 3, 2012 Sensinode 6 October 31, 2011 8 Observing Resources in CoAP 9 draft-ietf-core-observe-03 11 Abstract 13 CoAP is a RESTful application protocol for constrained nodes and 14 networks. The state of a resource on a CoAP server can change over 15 time. This document specifies a simple protocol extension for CoAP 16 that gives clients the ability to observe such changes. 18 Status of this Memo 20 This Internet-Draft is submitted in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF). Note that other groups may also distribute 25 working documents as Internet-Drafts. The list of current Internet- 26 Drafts is at http://datatracker.ietf.org/drafts/current/. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 This Internet-Draft will expire on May 3, 2012. 35 Copyright Notice 37 Copyright (c) 2011 IETF Trust and the persons identified as the 38 document authors. All rights reserved. 40 This document is subject to BCP 78 and the IETF Trust's Legal 41 Provisions Relating to IETF Documents 42 (http://trustee.ietf.org/license-info) in effect on the date of 43 publication of this document. Please review these documents 44 carefully, as they describe your rights and restrictions with respect 45 to this document. Code Components extracted from this document must 46 include Simplified BSD License text as described in Section 4.e of 47 the Trust Legal Provisions and are provided without warranty as 48 described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 1.1. Background . . . . . . . . . . . . . . . . . . . . . . . . 3 54 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 3 55 1.3. Design Philosophy . . . . . . . . . . . . . . . . . . . . 5 56 1.4. Conformance Requirements . . . . . . . . . . . . . . . . . 6 57 2. Options . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 58 2.1. Observe . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 2.2. Max-OFE . . . . . . . . . . . . . . . . . . . . . . . . . 7 60 3. Client-side Requirements . . . . . . . . . . . . . . . . . . . 7 61 3.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 7 62 3.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 8 63 3.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 8 64 3.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 9 65 4. Server-side Requirements . . . . . . . . . . . . . . . . . . . 10 66 4.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 10 67 4.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 11 68 4.3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 4.4. Reordering . . . . . . . . . . . . . . . . . . . . . . . . 12 70 4.5. Retransmission . . . . . . . . . . . . . . . . . . . . . . 13 71 5. Intermediaries . . . . . . . . . . . . . . . . . . . . . . . . 13 72 6. Block-wise Transfers . . . . . . . . . . . . . . . . . . . . . 14 73 7. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 15 74 8. Security Considerations . . . . . . . . . . . . . . . . . . . 15 75 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 76 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 16 77 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 16 78 11.1. Normative References . . . . . . . . . . . . . . . . . . . 16 79 11.2. Informative References . . . . . . . . . . . . . . . . . . 16 80 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 18 81 A.1. Proxying . . . . . . . . . . . . . . . . . . . . . . . . . 22 82 A.2. Block-wise Transfer . . . . . . . . . . . . . . . . . . . 24 83 Appendix B. Modeling Resources to Tailor Notifications . . . . . 25 84 Appendix C. Changelog . . . . . . . . . . . . . . . . . . . . . . 25 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 27 87 1. Introduction 89 1.1. Background 91 CoAP [I-D.ietf-core-coap] is an Application Protocol for Constrained 92 Nodes/Networks. It is intended to provide RESTful services [REST] 93 not unlike HTTP [RFC2616] while reducing the complexity of 94 implementation as well as the size of packets exchanged in order to 95 make these services useful in a highly constrained network of 96 themselves highly constrained nodes. 98 The communication model of REST is that of a client exchanging 99 resource representations with an origin server. The origin server is 100 the definitive source for representations of the resources in its 101 namespace. A client interested in a resource sends a request to the 102 origin server that returns a response with a representation that is 103 current at the time of the request. 105 This model does not work well when a client is interested in having a 106 current representation of a resource over a period of time. Existing 107 approaches from the HTTP world, such as repeated polling or long- 108 polls [RFC6202], generate significant complexity and/or overhead and 109 thus are less applicable in the constrained CoAP world. 111 The protocol specified in this document extends the CoAP core 112 protocol with a mechanism to push resource representations from 113 servers to interested clients, while still keeping the properties of 114 REST. 116 Note that there is no intention for this mechanism to solve the full 117 set of problems that the existing HTTP solutions solve, to replace 118 publish/subscribe networks that solve a much more general problem 119 [RFC5989], or to enable general two-way communication between clients 120 and servers [I-D.ietf-hybi-thewebsocketprotocol]. 122 1.2. Protocol Overview 124 The protocol is based on the well-known observer design pattern 125 [GOF]. 127 In this design pattern, components, called _observers_, register at a 128 specific, known provider, called the _subject_, that they are 129 interested in being notified whenever the subject undergoes a change 130 in state. The subject is responsible for administering its list of 131 registered observers. If multiple subjects are of interest, an 132 observer must register separately for all of them. The pattern is 133 typically used when a clean separation between related components is 134 required, such as data storage and user interface. 136 Observer Subject 137 | | 138 | Register | 139 +----------------->| 140 | | 141 | Notification | 142 |<-----------------+ 143 | | 144 | Notification | 145 |<-----------------+ 146 | | 147 | Notification | 148 |<-----------------+ 149 | | 151 Figure 1: Observer Design Pattern 153 The observer design pattern is realized in CoAP as follows: 155 Subject: In the context of CoAP, the subject is a resource in the 156 namespace of a CoAP server. The state of the resource can change 157 over time, ranging from infrequent updates to continuous state 158 transformations. 160 Observer: An observer is a CoAP client that is interested in the 161 current state of the resource at any given time. 163 Registration: A client registers its interest by sending an extended 164 GET request to the server. In addition to returning a 165 representation of the target resource, this request causes the 166 server to add the client to the list of observers of the resource. 168 Notification: Whenever the state of a resource changes, the server 169 notifies each client registered as observer for the resource. 170 Each notification is an additional CoAP response sent by the 171 server in reply to the GET request and includes a complete 172 representation of the new resource state. 174 Figure 2 shows an example of a CoAP client registering and receiving 175 three notifications: the first upon registration and then two when 176 the state of the resource changes. Registration request and 177 notifications are identified by the presence of the Observe Option 178 defined in this document. Notifications also echo the token 179 specified by the client in the request, so the client can easily 180 correlate them to the request. 182 Client Server 183 | | 184 | GET /temperature | 185 | Observe: 0 | (registration) 186 | Token: 0x4a | 187 +----------------->| 188 | | 189 | 2.05 Content | 190 | Observe: 12 | (notification of the current state) 191 | Token: 0x4a | 192 | Payload: 22.9 C | 193 |<-----------------+ 194 | | 195 | 2.05 Content | 196 | Observe: 44 | (notification upon a state change) 197 | Token: 0x4a | 198 | Payload: 22.8 C | 199 |<-----------------+ 200 | | 201 | 2.05 Content | 202 | Observe: 60 | (notification upon a state change) 203 | Token: 0x4a | 204 | Payload: 23.1 C | 205 |<-----------------+ 206 | | 208 Figure 2: Observing a Resource in CoAP 210 The client is removed from the list of observers when it is no longer 211 interested in the observed resource. The server can determine the 212 client's continued interest from the client's acknowledgement of 213 confirmable notifications. If a client wants to receive 214 notifications after it has been removed from the list of observers, 215 it needs to register again. The client can determine that it's still 216 on the list of observers from the fact that it receives 217 notifications. The protocol includes clear rules for what to do when 218 a client does not receive a notification for some time, or a server 219 does not receive acknowledgements. 221 1.3. Design Philosophy 223 The protocol builds on the architectural elements of REST: a server 224 that is responsible for the state and representation of the resources 225 in its namespace, a client that is responsible for keeping the 226 application state, and the stateless exchange of resource 227 representations. (A server needs to keep track of the observers 228 though, similar to how HTTP servers need to keep track of the TCP 229 connections from their clients.) The protocol enables high 230 scalability and efficiency through the support of caches and 231 intermediaries that multiplex the interest of multiple clients in the 232 same resource into a single association. 234 The server is the authority for determining under what conditions 235 resources change their state and how often observers are notified. 236 The protocol does not offer explicit means for setting up triggers, 237 thresholds or other conditions; it is up to the server to expose 238 observable resources that change their state in a way that is 239 meaningful for the application. Resources can be parameterized to 240 achieve similar effects though; see Appendix B for examples. 242 Since bandwidth is in short supply in constrained environments, 243 servers must adapt the rate of notifications to each client. This 244 implies that a client cannot rely on observing every single state a 245 resource goes through. Instead, the protocol is designed on the 246 principle of _eventual consistency_: it guarantees that if the 247 resource does not undergo a new change in state, eventually all 248 observers will have a current representation of the last resource 249 state. 251 1.4. Conformance Requirements 253 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 254 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 255 document are to be interpreted as described in RFC 2119 [RFC2119]. 257 2. Options 259 +-----+----------+---------+--------+--------+---------+ 260 | No. | C/E | Name | Format | Length | Default | 261 +-----+----------+---------+--------+--------+---------+ 262 | 10 | Elective | Observe | uint | 0-2 B | (none) | 263 | 14 | Elective | Max-OFE | uint | 0-4 B | 0 | 264 +-----+----------+---------+--------+--------+---------+ 266 2.1. Observe 268 The Observe Option, when present, modifies the GET method so it does 269 not only retrieve a representation of the current state of the 270 resource identified by the request URI, but also requests the server 271 to add the client to the list of observers of the resource. The 272 exact semantics are defined in the sections below. The value of the 273 option in a request MUST be zero on transmission and MUST be ignored 274 on reception. 276 In a response, the Observe Option identifies the message as a 277 notification, which implies that the client has been added to the 278 list of observers and that the server will notify the client of 279 further changes to the resource state. The option's value is a 280 sequence number that can be used for reordering detection (see 281 Section 3.4 and Section 4.4). It is encoded as a variable-length 282 unsigned integer as defined in Appendix A of RFC XXXX 283 [I-D.ietf-core-coap]. 285 Since the Observe Option is elective, a GET request that includes the 286 Observe Option will automatically fall back to a normal GET request 287 if the server does not support the protocol specified in this 288 document. 290 The Observe Option MUST NOT occur more than once in a request or 291 response. 293 2.2. Max-OFE 295 The freshness of a notification for caching purposes is determined by 296 the Max-Age Option. However, a server may want to enable a cache to 297 continue to optimistically use a cached representation even when the 298 freshness indicated by the Max-Age Option has expired (see 299 Section 3.3 and Section 4.3). 301 The time span for which this optimism is justified is under control 302 of the server: it can use the Max-OFE Option to indicate a desired 303 "optimistic freshness extension". This is also a promise by the 304 server that it intends to send another notification within this time 305 period. The exact semantics are defined in the sections below. The 306 value of this option is a time span in seconds, measured from the 307 time of expiry of Max-Age. The option is elective and defaults to 308 zero (which means that no optimistic freshness extension is granted). 310 The Max-OFE Option MUST NOT occur more than once in a response. 312 3. Client-side Requirements 314 3.1. Request 316 A client can register its interest in a resource by issuing a GET 317 request that includes an empty Observe Option. If the server returns 318 a 2.xx response that includes an Observe Option as well, the server 319 has added the client successfully to the list of observers of the 320 target resource and the client will be notified of changes to the 321 resource state for as long as the server can assume the client's 322 interest. 324 3.2. Notifications 326 Notifications are additional responses sent by the server in reply to 327 the GET request. Each notification includes an Observe Option with a 328 sequence number (see Section 3.4), a Token Option that matches the 329 token specified by the client in the GET request, and a payload in 330 the same representation format as the initial response. 332 A notification can be confirmable or non-confirmable (i.e. sent in a 333 confirmable or non-confirmable message). If a client does not 334 recognize the token in a confirmable notification, it MUST NOT 335 acknowledge the message and SHOULD reject it with a RST message. 336 Otherwise, the client MUST acknowledge the message with an ACK 337 message as usual. 339 An acknowledgement signals to the server that the client is alive and 340 interested in receiving further notifications; if the server does not 341 receive an acknowledgement in reply to a confirmable notification, it 342 will assume that the client is no longer interested and will 343 eventually remove it from the list of observers. 345 Notifications will have a 2.05 (Content) response code in most cases. 346 They may also have a 2.03 (Valid) response code, if the client 347 includes an ETag Option in its request (see Section 3.3). In the 348 event that the state of an observed resource is changed in a way that 349 would cause a normal GET request to return an error (for example, 350 when the resource is deleted), the server will send a notification 351 with an error response code (4.xx/5.xx) and empty the list of 352 observers of the resource. 354 3.3. Caching 356 As notifications are just additional responses, notifications partake 357 in caching as defined by Section 5.6 of RFC XXXX 358 [I-D.ietf-core-coap]. Both the freshness model and the validation 359 model are supported. The freshness model also serves as the model 360 for the client to determine if it's still on the list of observers or 361 if it needs to re-register its interest in the resource. 363 A client MAY store a notification like a response in its cache and 364 use a stored response/notification that is fresh without contacting 365 the origin server. A notification is considered fresh while its age 366 is not greater than its Max-Age and if it has not been invalidated by 367 a newer notification or as the result of a request. 369 Ideally, the server will provide a new notification exactly when the 370 freshness of the latest notification expires. This may not always be 371 possible though, due to network latency and/or resources that change 372 their state in unpredictable intervals. In this case, the client MAY 373 optimistically use a stale (non-fresh) notification while the 374 notification's age is not greater than Max-Age plus Max-OFE and the 375 notification has not been invalidated. 377 If the client does not receive a notification before Max-Age plus 378 Max-OFE expires, the client can assume it has been removed from the 379 list of observers (e.g., due to a loss of server state). In this 380 case, it needs to re-register by issuing a new GET request with an 381 Observe Option. 383 To make sure it has a fresh representation and/or it is on the list 384 of observers, a client MAY issue another GET request with an Observe 385 Option at any time. The new GET request SHOULD specify a new token 386 to avoid ambiguity. It is RECOMMENDED that the client does not issue 387 the request before the Max-Age of the latest notification expires 388 (i.e. while it still has a fresh notification). 390 When a client has one or more notifications stored, it can use the 391 ETag Option in its request to give the server an opportunity to 392 select a stored response to be used. The client MAY include an ETag 393 Option for each stored response that is applicable. It needs to keep 394 those responses in the cache until it is no longer interested in 395 receiving notifications for the target resource or it issues a new 396 GET request with a new set of entity-tags. When the observed 397 resource changes its state to a representation identified by one of 398 the ETag Options, the server can send a 2.03 (Valid) notification 399 instead of a 2.05 (Content) notification. 401 3.4. Reordering 403 Messages that carry notifications can arrive in a different order 404 than they were sent. Since the goal is eventual consistency (see 405 Section 1.3), a client can safely skip a notification that arrives 406 later than a newer notification. For this purpose, the server sets 407 the value of the Observe Option in each notification to a sequence 408 number. 410 A client MAY treat a notification as outdated (not fresh) under the 411 following condition: 413 (V1 - V2) % (2**16) < (2**15) and T2 < (T1 + (2**14)) 415 where V1 is the value of the Observe Option of the latest valid 416 notification received, V2 the value of the Observe Option of the 417 present notification, T1 a client-local timestamp of the latest valid 418 notification received (in seconds), and T2 a client-local timestamp 419 of the present notification. 421 Design Note: The first condition essentially verifies that V2 > V1 422 holds in 16-bit sequence number arithmetic [RFC1982]. The second 423 condition checks that the time expired between the two incoming 424 messages is not so large that the sequence number might have 425 wrapped around and the first check is therefore invalid. (In 426 other words, after about 2**14 seconds elapse without any 427 notification, the client does not need to check the sequence 428 numbers in order to assume an incoming notification is new.) The 429 constants of 2**14 and 2**15 are non-critical, as is the even 430 speed or precision of the clock involved. 432 4. Server-side Requirements 434 4.1. Request 436 A GET request that includes an Observe Option requests the server not 437 only to return a representation of the resource identified by the 438 request URI, but also to add the client to the list of observers of 439 the target resource. If no error occurs, the server MUST return a 440 response with the representation of the current resource state and 441 MUST notify the client of subsequent changes to the state as long as 442 the client is on the list of observers. 444 A server that is unable or unwilling to add the client to the list of 445 observers of the target resource MAY silently ignore the Observe 446 Option and process the GET request as usual. The resulting response 447 MUST NOT include an Observe Option, the absence of which signals to 448 the client that it will not be notified of changes to the resource 449 state and, e.g., needs to poll the resource instead. 451 If the client is already on the list of observers, the server MUST 452 NOT add it a second time but MUST replace or update the existing 453 entry. If the server receives a GET request that does not include an 454 Observe Option, it MUST remove the client from the list of observers. 456 Two requests relate to the same list entry if both the request URI 457 and the source of the requests match. The source of a request is 458 determined by the security mode used (see Section 10 of RFC XXXX 459 [I-D.ietf-core-coap]): With NoSec, it is determined by the source IP 460 address and UDP port number. With other security modes, the source 461 is also determined by the security context. Message IDs and Token 462 Options MUST NOT be taken into account. 464 Any request with a method other than GET MUST NOT have a direct 465 effect on a list of observers of a resource. However, such a request 466 can have the indirect consequence of causing the server to send an 467 error notification which affects the list of observers (e.g., when a 468 DELETE request is successful and an observed resource no longer 469 exists). 471 4.2. Notifications 473 A client is notified of a resource state change by an additional 474 response sent by the server in reply to the GET request. Each such 475 notification response MUST include an Observe Option and MUST echo 476 the token specified by the client in the GET request. If there are 477 multiple clients, the order in which they are notified is not 478 defined; the server is free to use any method to determine the order. 480 A notification SHOULD have a 2.05 (Content) or 2.03 (Valid) response 481 code. However, in the event that the state of a resource changes in 482 a way that would cause a normal GET request to return an error (for 483 example, if the resource is deleted), the server SHOULD notify the 484 client by sending a notification with an appropriate error response 485 code (4.xx/5.xx) and MUST empty the list of observers of the 486 resource. 488 The representation format/media type used in a notification MUST be 489 the same format used in the initial response to the GET request. If 490 the server is unable to continue sending notifications in this 491 format, it SHOULD send a 5.00 (Internal Server Error) notification 492 and MUST empty the list of observers of the resource. 494 A notification can be sent as a confirmable or a non-confirmable 495 message. The message type used is typically application-dependent 496 and MAY be determined by the server for each notification 497 individually. For example, for resources that change in a somewhat 498 predictable or regular fashion, notifications can be sent in non- 499 confirmable messages; for resources that change infrequently, 500 notifications can be sent in confirmable messages. The server can 501 combine these two approaches depending on the frequency of state 502 changes and the importance of individual notifications. 504 The acknowledgement of a confirmable notification implies the 505 client's continued interest in being notified. If the client rejects 506 a confirmable notification with a RST message, the server MUST remove 507 the client from the list of observers. 509 4.3. Caching 511 The Max-Age Option of a notification SHOULD be set to a value that 512 indicates when the server will send the next notification. For 513 example, if the server sends a notification every 30 seconds, a Max- 514 Age Option with value 30 should be included. The server MAY send a 515 new notification before Max-Age ends. The server SHOULD also include 516 a Max-OFE Option so the client can continue to use a notification in 517 case the next notification arrives a bit later due to network 518 latency. If the client does not receive a new notification before 519 Max-Age plus Max-OFE ends, it will assume that it was removed from 520 the list of observers (e.g., due to a loss of server state) and may 521 issue a new GET request to re-register its interest. 523 It may not always be possible to predict when the server will send 524 the next notification, for example, when a resource does not change 525 its state in regular intervals. In this case, the server SHOULD set 526 Max-Age to a good approximation and Max-OFE to a time span for which 527 the server is willing to keep the client in the list of observers. 529 Setting the values for Max-Age and Max-OFE is a trade-off between 530 increased usage of bandwidth and the risk of stale information. 531 Smaller values lead to more notifications and more GET requests, 532 while greater values result in network or device failures being 533 detect later and data becoming stale. 535 When the observed resource changes its state and the origin server is 536 about to send a 2.05 (Content) notification, then, whenever that 537 notification has an entity-tag in the set of entity-tags specified by 538 the client, it MAY send a 2.03 (Valid) response with an appropriate 539 ETag Option instead. The server MUST NOT assume that the recipient 540 has any response stored other than those identified by the entity- 541 tags in the most recent GET request. 543 4.4. Reordering 545 Because messages can get reordered, the client needs a way to 546 determine if a notification arrived later than a newer notification. 547 For this purpose, the server MUST set the value of the Observe Option 548 in each notification to the 16 least-significant bits of a strictly 549 increasing sequence number. The sequence number MAY start at any 550 value. The server MUST NOT reuse the same option value with the same 551 client, token and resource within approximately 2**16 seconds 552 (roughly 18.2 hours). 554 Implementation Note: A simple implementation that satisfies the 555 requirements is to use a timestamp (in seconds) provided by the 556 device's clock, or a 16-bit unsigned integer variable that is 557 incremented every second and wraps around every 2**16 seconds. It 558 is not necessary that the clock reflects the correct local time or 559 that it ticks exactly every second. Note that, on average, a 560 server cannot send more than one notification per second per 561 client, token and resource. 563 4.5. Retransmission 565 In CoAP, confirmable messages are retransmitted in exponentially 566 increasing intervals for a certain number of attempts until they are 567 acknowledged by the client. In the context of observing a resource, 568 it is undesirable to continue transmitting the representation of a 569 resource state when the state has changed in the meantime. 571 When a server is in the process of delivering a confirmable 572 notification and is waiting for an acknowledgement, and it wants to 573 notify the client of a state change using a new confirmable message, 574 it MUST stop retransmitting the old notification and SHOULD attempt 575 to deliver the new notification with the number of attempts remaining 576 from the old notification. When the last attempt to retransmit a 577 confirmable message with a notification for a resource times out, the 578 server SHOULD remove the client from the list of observers and MAY 579 additionally remove the client from the lists of observers of all 580 resources in its namespace. 582 The server SHOULD use a number of retransmit attempts 583 (MAX_RETRANSMIT) such that removing a client from the list of 584 observers before Max-Age plus Max-OFE ends is avoided. 586 A server MAY choose to skip a notification if it knows that it will 587 send another notification soon (e.g., when the state is changing 588 frequently). Similarly, it MAY choose to send a notification more 589 than once. For example, when state changes occur in bursts, the 590 server can skip some notifications, send notifications in non- 591 confirmable messages, and make sure that the client observes the 592 latest state change after the burst by repeating the last 593 notification in a confirmable message. 595 5. Intermediaries 597 A client may be interested in a resource in the namespace of an 598 origin server that is reached through one or more CoAP-to-CoAP 599 intermediaries. In this case, the client registers its interest with 600 the first intermediary towards the origin server, acting as if it was 601 communicating with the origin server itself as specified in 602 Section 3. It is the task of this intermediary to provide the client 603 with a current representation of the target resource and send 604 notifications upon changes to the target resource state, much like an 605 origin server as specified in Section 4. 607 To perform this task, the intermediary SHOULD make use of the 608 protocol specified in this document, taking the role of the client 609 and registering its own interest in the target resource with the next 610 hop. If the next hop does not return a response with an Observe 611 Option, the intermediary MAY resort to polling the next hop, or MAY 612 itself return a response without an Observe Option. Note that the 613 communication between each pair of hops is independent, i.e. each hop 614 in the server role MUST determine individually how many notifications 615 to send, of which type, and so on, MUST generate its own values for 616 the Observe Option, and MUST set the values of the Max-Age Option and 617 Max-OFE Option according to the age of the local current 618 representation. 620 Because a client (or an intermediary in the client role) can only be 621 once in the list of observers of a resource at a server (or an 622 intermediary in the server role) -- as it makes no sense to observe 623 the same resource multiple times -- an intermediary MUST observe a 624 resource only once, even if there are multiple clients for which it 625 observes the resource. 627 Note that an intermediary is not required to have a client to observe 628 a resource; an intermediary MAY observe a resource, for instance, 629 just to keep its own cache up to date. 631 See Appendix A.1 for examples. 633 6. Block-wise Transfers 635 Resources observed by clients may be larger than can be comfortably 636 processed or transferred in one CoAP message. CoAP provides a block- 637 wise transfer mechanism to address this problem 638 [I-D.ietf-core-block]. The following rules apply to the combination 639 of block-wise transfers with notifications. 641 As with basic GET transfers, the client can indicate its desired 642 block size in a Block2 Option in the GET request. If the server 643 supports block-wise transfers, it SHOULD take note of the block size 644 for all notifications/responses resulting from the GET request (until 645 the client is removed from the list of observers or the server 646 receives a new GET request from the client). 648 When sending a 2.05 (Content) notification, the server always sends 649 all blocks of the representation, suitably sequenced by its 650 congestion control mechanism, even if only some of the blocks have 651 changed with respect to a previous value. The server performs the 652 block-wise transfer by making use of the Block2 Option in each block. 653 When reassembling representations that are transmitted in multiple 654 blocks, the client MUST NOT combine blocks carrying different Observe 655 Option values, or blocks that have been received more than 656 approximately 2**14 seconds apart. 658 See Appendix A.2 for an example. 660 7. Discovery 662 A web link [RFC5988] to a resource accessible by the CoAP protocol 663 MAY indicate that the server encourages the observation of this 664 resource by including the target attribute "obs". This is 665 particularly useful in link-format documents 666 [I-D.ietf-core-link-format]. 668 This target attribute is used as a flag, and thus it has no value 669 component -- a value given for the attribute MUST NOT be given for 670 this version of the specification and MUST be ignored if present. 671 The target attribute "obs" MUST NOT be given more than once for this 672 version of the specification. 674 8. Security Considerations 676 The security considerations of RFC XXXX [I-D.ietf-core-coap] apply. 678 Note that the considerations about amplification attacks are somewhat 679 amplified when observing resources. In NoSec mode, a server MUST 680 therefore strictly limit the number of notifications that it sends 681 between receiving acknowledgements that confirm the actual interest 682 of the client in the data; i.e., any notifications sent in non- 683 confirmable messages MUST be interspersed with confirmable messages. 684 (An attacker may still spoof the acknowledgements if the confirmable 685 messages are sufficiently predictable.) 687 As with any protocol that creates state, attackers may attempt to 688 exhaust the resources that the server has available for maintaining 689 the list of observers for each resource. Servers MAY want to access- 690 control this creation of state. As degraded behavior, the server can 691 always fall back to processing the request as a normal GET request 692 (without an Observe Option) if it is unwilling or unable to add a 693 client to the list of observers of a resource, including if system 694 resources are exhausted or nearing exhaustion. 696 Intermediaries MUST be careful to ensure that notifications cannot be 697 employed to create a loop. A simple way to break any loops is to 698 employ caches for forwarding notifications in intermediaries. 700 9. IANA Considerations 702 The following entries are added to the CoAP Option Numbers registry: 704 +--------+---------+-----------+ 705 | Number | Name | Reference | 706 +--------+---------+-----------+ 707 | 10 | Observe | [RFCXXXX] | 708 | 14 | Max-OFE | [RFCXXXX] | 709 +--------+---------+-----------+ 711 10. Acknowledgements 713 Carsten Bormann was an original author of this draft and is 714 acknowledged for significant contribution to this document. 716 Thanks to Daniele Alessandrelli, Jari Arkko, Peter Bigot, Angelo 717 Castellani, Gilbert Clark, Esko Dijk, Brian Frank, Salvatore Loreto 718 and Charles Palmer for helpful comments and discussions that have 719 shaped the document. 721 Klaus Hartke was funded by the Klaus Tschira Foundation. 723 11. References 725 11.1. Normative References 727 [I-D.ietf-core-block] 728 Bormann, C. and Z. Shelby, "Blockwise transfers in CoAP", 729 draft-ietf-core-block-04 (work in progress), July 2011. 731 [I-D.ietf-core-coap] 732 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 733 "Constrained Application Protocol (CoAP)", 734 draft-ietf-core-coap-07 (work in progress), July 2011. 736 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 737 Requirement Levels", BCP 14, RFC 2119, March 1997. 739 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 741 11.2. Informative References 743 [GOF] Gamma, E., Helm, R., Johnson, R., and J. Vlissides, 744 "Design Patterns: Elements of Reusable Object-Oriented 745 Software", Addison-Wesley, Reading, MA, USA, 746 November 1994. 748 [I-D.ietf-core-link-format] 749 Shelby, Z., "CoRE Link Format", 750 draft-ietf-core-link-format-07 (work in progress), 751 July 2011. 753 [I-D.ietf-hybi-thewebsocketprotocol] 754 Fette, I. and A. Melnikov, "The WebSocket protocol", 755 draft-ietf-hybi-thewebsocketprotocol-17 (work in 756 progress), September 2011. 758 [REST] Fielding, R., "Architectural Styles and the Design of 759 Network-based Software Architectures", 2000, . 762 [RFC1982] Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982, 763 August 1996. 765 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 766 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 767 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 769 [RFC5989] Roach, A., "A SIP Event Package for Subscribing to Changes 770 to an HTTP Resource", RFC 5989, October 2010. 772 [RFC6202] Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins, 773 "Known Issues and Best Practices for the Use of Long 774 Polling and Streaming in Bidirectional HTTP", RFC 6202, 775 April 2011. 777 Appendix A. Examples 779 Observed CLIENT SERVER Actual 780 t State | | State 781 ____________ | | ____________ 782 1 | | 783 2 unknown | | 18.5 C 784 3 +----->| Header: GET 0x43011633 785 4 | GET | Token: 0x4a 786 5 | | Uri-Path: temperature 787 6 | | Observe: 0 788 7 | | 789 8 | | 790 9 ____________ |<-----+ Header: 2.05 0x64451633 791 10 | 2.05 | Token: 0x4a 792 11 18.5 C | | Observe: 9 793 12 | | Max-Age: 15 794 13 | | Max-OFE: 60 795 14 | | Payload: "18.5 C" 796 15 | | 797 16 | | ____________ 798 17 ____________ |<-----+ Header: 2.05 0x54457b50 799 18 | 2.05 | 19.2 C Token: 0x4a 800 19 19.2 C | | Observe: 17 801 20 | | Max-Age: 15 802 21 | | Max-OFE: 60 803 22 | | Payload: "19.2 C" 804 23 | | 806 Figure 3: A client registers and receives a notification of the 807 current state and upon a state change 809 Observed CLIENT SERVER Actual 810 t State | | State 811 ____________ | | ____________ 812 24 | | 813 25 19.2 C | | 19.2 C 814 26 | | 815 27 | | 816 28 | | ____________ 817 29 | X----+ Header: 2.05 0x54457b51 818 30 | 2.05 | 19.7 C Token: 0x4a 819 31 | | Observe: 29 820 32 ____________ | | Max-Age: 15 821 33 | | Max-OFE: 60 822 34 19.2 C | | Payload: "19.7 C" 823 35 (optimistic) | | 824 36 | | ____________ 825 37 ____________ |<-----+ Header: 2.05 0x55457b52 826 38 | 2.05 | 18.9 C Token: 0x4a 827 39 18.9 C | | Observe: 37 828 40 | | ETag: 0x78797a7a79 829 41 | | Max-Age: 15 830 42 | | Max-OFE: 60 831 43 | | Payload: "18.9 C" 832 44 | | 834 Figure 4: The client optimistically assumes that the state did not 835 change after Max-Age ended 837 Observed CLIENT SERVER Actual 838 t State | | State 839 ____________ | | ____________ 840 45 | | 841 46 18.9 C | | 18.9 C 842 47 | | 843 48 | | ____________ 844 49 | CRASH 845 50 | 846 51 | 847 52 ____________ | 848 53 | 849 54 18.9 C | 850 55 (optimistic) | 851 56 | 852 : : 853 111 | 854 112 ____________ | 855 113 | 856 114 18.9 C | 857 115 (invalid) | 858 116 | 860 Figure 5: The server crashes and leaves the client with stale 861 information 863 Observed CLIENT SERVER Actual 864 t State | | State 865 ____________ | | ____________ 866 117 | | 867 118 18.9 C | | 18.0 C 868 119 (invalid) +----->| Header: GET 0x44011634 869 120 | GET | Token: 0xf9 870 121 | | Uri-Path: temperature 871 122 | | Observe: 0 872 123 | | ETag: 0x78797a7a79 873 124 | | 874 125 | | 875 126 ____________ |<-----+ Header: 2.05 0x64451634 876 127 | 2.05 | Token: 0xf9 877 128 18.0 C | | Observe: 126 878 129 | | Max-Age: 15 879 130 | | Max-OFE: 60 880 131 | | Payload: "18.0 C" 881 132 | | 882 133 | | ____________ 883 134 ____________ |<-----+ Header: 2.03 0x5543aa0c 884 135 | 2.03 | 18.9 C Token: 0xf9 885 136 18.9 C | | Observe: 134 886 137 | | ETag: 0x78797a7a79 887 138 | | Max-Age: 15 888 139 | | Max-OFE: 60 889 140 | | 891 Figure 6: The client re-registers and gives the server the 892 opportunity to select a stored response 894 A.1. Proxying 896 CLIENT PROXY SERVER 897 | | | 898 | +----->| Header: GET 0x44015fb8 899 | | GET | Token: 0x1a 900 | | | Uri-Host: sensor.example 901 | | | Uri-Path: status 902 | | | Observe: 0 903 | | | 904 | |<-----+ Header: 2.05 0x64455fb8 905 | | 2.05 | Token: 0x1a 906 | | | Observe: 42 907 | | | Max-Age: 60 908 | | | Max-OFE: 60 909 | | | Payload: "ready" 910 | | | 911 +----->| | Header: GET 0x42011633 912 | GET | | Token: 0x9a 913 | | | Proxy-Uri: coap://sensor.example/status 914 | | | 915 |<-----+ | Header: 2.05 0x62451633 916 | 2.05 | | Token: 0x9a 917 | | | Max-Age: 53 918 | | | Payload: "ready" 919 | | | 920 | |<-----+ Header: 2.05 0x544505fc0 921 | | 2.05 | Token: 0x1a 922 | | | Observe: 135 923 | | | Max-Age: 60 924 | | | Max-OFE: 60 925 | | | Payload: "busy" 926 | | | 927 +----->| | Header: GET 0x42011634 928 | GET | | Token: 0x9b 929 | | | Proxy-Uri: coap://sensor.example/status 930 | | | 931 |<-----+ | Header: 2.05 0x62451634 932 | 2.05 | | Token: 0x9b 933 | | | Max-Age: 49 934 | | | Payload: "busy" 935 | | | 937 Figure 7: A proxy observes a resource to keep its cache up to date 939 CLIENT PROXY SERVER 940 | | | 941 +----->| | Header: GET 0x43011635 942 | GET | | Token: 0x6a 943 | | | Proxy-Uri: coap://sensor.example/status 944 | | | Observe: 0 945 | | | 946 |<- - -+ | Header: 0x60001635 947 | | | 948 | +----->| Header: GET 0x4401af90 949 | | GET | Token: 0xaa 950 | | | Uri-Host: sensor.example 951 | | | Uri-Path: status 952 | | | Observe: 0 953 | | | 954 | |<-----+ Header: 2.05 0x6445af90 955 | | 2.05 | Token: 0xaa 956 | | | Observe: 67 957 | | | Max-Age: 60 958 | | | Max-OFE: 60 959 | | | Payload: "ready" 960 | | | 961 |<-----+ | Header: 2.05 0x4445af94 962 | 2.05 | | Token: 0x6a 963 | | | Observe: 17346 964 | | | Max-Age: 60 965 | | | Max-OFE: 60 966 | | | Payload: "ready" 967 | | | 968 +- - ->| | Header: 0x6000af94 969 | | | 970 | |<-----+ Header: 2.05 0x54455a20 971 | | 2.05 | Token: 0xaa 972 | | | Observe: 157 973 | | | Max-Age: 60 974 | | | Max-OFE: 60 975 | | | Payload: "busy" 976 | | | 977 |<-----+ | Header: 2.05 0x5445af9b 978 | 2.05 | | Token: 0x6a 979 | | | Observe: 17436 980 | | | Max-Age: 60 981 | | | Max-OFE: 60 982 | | | Payload: "busy" 983 | | | 985 Figure 8: A client observes a resource through a proxy 987 A.2. Block-wise Transfer 989 CLIENT SERVER 990 | | 991 +----->| Header: GET 0x43011636 992 | GET | Token: 0xfb 993 | | Uri-Path: status-icon 994 | | Observe: 0 995 | | 996 |<-----+ Header: 2.05 0x65451636 997 | 2.05 | Token: 0xfb 998 | | Block2: 0/1/128 999 | | Observe: 62354 1000 | | Max-Age: 60 1001 | | Max-OFE: 60 1002 | | Payload: [128 bytes] 1003 | | 1004 |<-----+ Header: 2.05 0x5545af9c 1005 | 2.05 | Token: 0xfb 1006 | | Block2: 1/0/128 1007 | | Observe: 62354 1008 | | Max-Age: 60 1009 | | Max-OFE: 60 1010 | | Payload: [27 bytes] 1011 | | 1012 |<-----+ Header: 2.05 0x5545af9d 1013 | 2.05 | Token: 0xfb 1014 | | Block2: 0/1/128 1015 | | Observe: 62444 1016 | | Max-Age: 60 1017 | | Max-OFE: 60 1018 | | Payload: [128 bytes] 1019 | | 1020 |<-----+ Header: 2.05 0x5545af9e 1021 | 2.05 | Token: 0xfb 1022 | | Block2: 1/0/128 1023 | | Observe: 62444 1024 | | Max-Age: 60 1025 | | Max-OFE: 60 1026 | | Payload: [27 bytes] 1027 | | 1029 Figure 9: A server sends two notifications of two blocks each 1031 Appendix B. Modeling Resources to Tailor Notifications 1033 A server may want to provide notifications that respond to very 1034 specific conditions on some state. This is best done by modeling the 1035 resources that the server exposes according to these needs. 1037 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-02 to ietf-03: 1075 o Separated client-side and server-side requirements. 1077 o Fixed uncertainty if client is still in the list of observers by 1078 introducing a liveliness model based on Max-Age and a new option 1079 called Max-OFE (#174). 1081 o Simplified the text on message reordering (#129). 1083 o Clarified requirements for intermediaries. 1085 o Clarified the combination of block-wise transfers with 1086 notifications (#172). 1088 o Updated examples to show how the state observed by the client 1089 becomes eventually consistent with the actual state on the server. 1091 o Added examples for parameterization of observable resource. 1093 Changes from ietf-01 to ietf-02: 1095 o Removed the requirement of periodic refreshing (#126). 1097 o The new "Observe" Option replaces the "Lifetime" Option. 1099 o Introduced a new mechanism to detect message reordering. 1101 o Changed 2.00 (OK) notifications to 2.05 (Content) notifications. 1103 Changes from ietf-00 to ietf-01: 1105 o Changed terminology from "subscriptions" to "observation 1106 relationships" (#33). 1108 o Changed the name of the option to "Lifetime". 1110 o Clarified establishment of observation relationships. 1112 o Clarified that an observation is only identified by the URI of the 1113 observed resource and the identity of the client (#66). 1115 o Clarified rules for establishing observation relationships (#68). 1117 o Clarified conditions under which an observation relationship is 1118 terminated. 1120 o Added explanation on how clients can terminate an observation 1121 relationship before the lifetime ends (#34). 1123 o Clarified that the overriding objective for notifications is 1124 eventual consistency of the actual and the observed state (#67). 1126 o Specified how a server needs to deal with clients not 1127 acknowledging confirmable messages carrying notifications (#69). 1129 o Added a mechanism to detect message reordering (#35). 1131 o Added an explanation of how notifications can be cached, 1132 supporting both the freshness and the validation model (#39, #64). 1134 o Clarified that non-GET requests do not affect observation 1135 relationships, and that GET requests without "Lifetime" Option 1136 affecting relationships is by design (#65). 1138 o Described interaction with block-wise transfers (#36). 1140 o Added Resource Discovery section (#99). 1142 o Added IANA Considerations. 1144 o Added Security Considerations (#40). 1146 o Added examples (#38). 1148 Authors' Addresses 1150 Klaus Hartke 1151 Universitaet Bremen TZI 1152 Postfach 330440 1153 Bremen D-28359 1154 Germany 1156 Phone: +49-421-218-63905 1157 Fax: +49-421-218-7000 1158 Email: hartke@tzi.org 1160 Zach Shelby (editor) 1161 Sensinode 1162 Kidekuja 2 1163 Vuokatti 88600 1164 Finland 1166 Phone: +358407796297 1167 Email: zach@sensinode.com