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