idnits 2.17.1 draft-hartke-coap-observe-01.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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (July 08, 2010) is 5031 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Outdated reference: A later version (-27) exists of draft-bormann-coap-misc-05 == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-01 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group K. Hartke 3 Internet-Draft C. Bormann 4 Intended status: Informational Universitaet Bremen TZI 5 Expires: January 9, 2011 July 08, 2010 7 Observing Resources in CoAP 8 draft-hartke-coap-observe-01 10 Abstract 12 The state of a resource can change over time. We want to give 13 clients of the CoRE WG CoAP protocol the ability to observe this 14 change. This short I-D provides an example design for such an 15 addition to CoAP, in order to be able to discuss the design 16 alternatives in specific terms. 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 January 9, 2011. 35 Copyright Notice 37 Copyright (c) 2010 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 2. Subscription-lifetime Option . . . . . . . . . . . . . . . . . 4 54 2.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 5 55 3. Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 56 4. HTTP Mapping . . . . . . . . . . . . . . . . . . . . . . . . . 7 57 4.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 58 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 59 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 60 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 61 7.1. Normative References . . . . . . . . . . . . . . . . . . . 12 62 7.2. Informative References . . . . . . . . . . . . . . . . . . 12 63 Appendix A. Rationale . . . . . . . . . . . . . . . . . . . . . . 13 64 A.1. Design Pattern . . . . . . . . . . . . . . . . . . . . . . 13 65 A.2. Architecture . . . . . . . . . . . . . . . . . . . . . . . 13 66 A.3. Requirements . . . . . . . . . . . . . . . . . . . . . . . 14 67 A.4. The Design . . . . . . . . . . . . . . . . . . . . . . . . 18 68 A.4.1. State . . . . . . . . . . . . . . . . . . . . . . . . 18 69 A.4.2. Subscription Lifetime . . . . . . . . . . . . . . . . 18 70 A.4.3. Messages . . . . . . . . . . . . . . . . . . . . . . . 19 71 A.5. Message Exchanges . . . . . . . . . . . . . . . . . . . . 20 72 A.5.1. Subscribing to a resource . . . . . . . . . . . . . . 21 73 A.5.2. Notifying of state changes . . . . . . . . . . . . . . 22 74 A.5.3. Unsubscribing from a resource . . . . . . . . . . . . 23 75 A.5.4. Retrieving resource state . . . . . . . . . . . . . . 24 76 A.5.5. Changing resource state . . . . . . . . . . . . . . . 25 77 A.5.6. Deleting a resource . . . . . . . . . . . . . . . . . 25 78 A.6. Caching . . . . . . . . . . . . . . . . . . . . . . . . . 26 79 A.7. Identifying notifications and subscriptions . . . . . . . 26 80 A.8. Open issues . . . . . . . . . . . . . . . . . . . . . . . 28 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 29 83 1. Introduction 85 The state of a resource can change over time. We want to give CoAP 86 [I-D.ietf-core-coap] clients the ability to observe this change. 88 This short I-D provides an example design for such an addition to 89 CoAP, in order to be able to discuss the design alternatives in 90 specific terms. 92 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 93 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 94 and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119] 95 and indicate requirement levels for compliant CoAP implementations. 97 2. Subscription-lifetime Option 99 The Subscription-lifetime Option, when present, modifies the GET 100 method to not only retrieve a representation of the current state of 101 the resource identified by the request URI once, but also to notify 102 the client of changes to the resource state for the duration 103 specified in the option. 105 The client is notified of state changes by additional responses sent 106 from the server to the client (confirmable or non-confirmable). The 107 server MUST include the request URI, token and remaining subscription 108 lifetime in each such notification response. 110 The subscription ends when the server sends a response with a 4xx or 111 5xx code, the client sends a RST in reply to a confirmable response, 112 or the subscription lifetime expires. 114 It is not necessary that a subscribed client receives every single 115 notification response sent by a server, or that the server sends a 116 notification response for every single state change. However, the 117 state observed by an observer SHOULD eventually become consistent 118 with the actual state of the observed resource. 120 The representation format (i.e. the media type) used during the 121 lifetime of a subscription MUST NOT change. If the server is unable 122 to continue sending notification responses to a client in the 123 requested representation format, it MUST send a confirmable 406 124 response and end the subscription. 126 2.1. Example 128 Client Server 129 | | 130 | CON tid=47 | 131 | GET /foo | 132 | lifetime=60s | 133 +---------------->| 134 | | 135 | ACK tid=47 | 136 | 200 /foo | (The URI is actually elided 137 | "| 156 | | ... and so on... 158 Figure 1 160 3. Caching 162 A client may cache part or all of a resource's state changes. This 163 allows clients to make conditional requests: If a subscribing client 164 has cached a particular resource state, the server offering the 165 resource does not need to send a full notification response. 167 o A client informs the server of its cached resource states by 168 including Etags of cached resource states in the subscription 169 request. This can be multiple Etags, as this enables the server 170 to just send a "304 not modified" for a different Etag instead of 171 a different representation if the resource switches around between 172 multiple states. (Note that this list might be updated by a 173 subscription refresh.) 175 o A server notifies a client of a change to a cached state by 176 omitting the representation of the resource state in the 177 notification and sets the code to "304 not modified" to indicate 178 that the state changed to a cached state. 180 Another approach to caching multiple values for a resource is to 181 express each possible value of the resource's representation by a 182 reference to another (unchanging) resource. This lets a resource 183 change states between a set of such references that then provide the 184 actual state information. A subscribed client fetches the individual 185 resources on demand and caches the results for future use. 187 4. HTTP Mapping 189 Making a CoAP GET request with Subscription-lifetime Option available 190 through an HTTP proxy requires techniques that allow an HTTP server 191 (here: the proxy) to push data to an HTTP client, such as long 192 polling or HTML5 WebSockets. 194 With long polling, the client requests information from the proxy in 195 the same way as a normal HTTP GET request, but also indicates the 196 last cached state of the requested resource. As long as the resource 197 state hasn't changed, the proxy holds the request and waits for the 198 resource to change, instead of sending an empty (304) response. Once 199 the state of the resource changes (or possibly after a suitable 200 timeout), a complete response is sent to the client. The client will 201 normally then immediately re-request information from the server, so 202 that the client will generally be quickly notified of any change to 203 the state of the resource. 205 4.1. Example 207 HTTP CoAP 209 Client Proxy Server 210 | | | 211 | | CON tid=47 | 212 | GET coap://.. | GET /foo | 213 +---------------->+---------------->| Setting up 214 | | | the initial 215 | | ACK tid=47 | state 216 | 200 "+---------------->| Obtaining 225 | | | asynchronous 226 | | ACK tid=153 | updates 227 | | 304 "Not... | via HTTP 228 | | etag=0xab5f78 | long-poll 229 | |<----------------+ 230 | | | 231 ... Time Passes ... 232 | | | 233 | | CON tid=783 | 234 | 200 "| re-request here 240 | | | 242 Figure 2 244 In Figure 2, the HTTP client indicates the Etag that reflects its 245 current state in a query parameter ("wmf" = When-Modified-From) and 246 specifies a time in which it would like to receive an answer in any 247 case ("for"). In this specific example, a change actually arrives 248 within the time specified, so the HTTP client receives a 200 response 249 to the long-poll. (If the time specified were to elapse without a 250 change, a 304 response would be returned.) Figure 2 is not showing 251 that the HTTP client most likely immediate re-requests the long-poll 252 GET with the "wmf" parameter set to the new Etag. 254 Instead of specifying the parameters "wmf" and "for" in query 255 parameters, the lifetime could also be implied by the proxy (e.g., 256 the proxy could always set it to 60 seconds), and the Etag specifying 257 the current state could also be transported in a new HTTP header such 258 as "When-Modified-From:". 260 This example shows just one possible HTTP mapping, using a style of 261 long-polls as they are often used for asynchronous HTTP applications 262 [S6]. Alternative mappings are conceivable using HTML5 WebSockets or 263 even other forms of asynchronous notifications via HTTP. 265 5. IANA Considerations 267 This draft adds the following option numbers to Table 2 of 268 [I-D.ietf-core-coap]: 270 +------+-----+-----------------------+-----------+--------+---------+ 271 | Type | C/E | Name | Data type | Length | Default | 272 +------+-----+-----------------------+-----------+--------+---------+ 273 | 10 | E | Subscription-lifetime | Duration | 1 B | 0 | 274 +------+-----+-----------------------+-----------+--------+---------+ 276 (The representation of the duration is assumed to be based on the 277 Duration data type defined in [I-D.bormann-coap-misc]; alternatively 278 it could be a variable-length integer specifying the duration in 279 seconds.) 281 6. Acknowledgments 283 This work was partially funded by the Klaus Tschira Foundation. 285 7. References 287 7.1. Normative References 289 [I-D.bormann-coap-misc] 290 Bormann, C. and K. Hartke, "Miscellaneous additions to 291 CoAP", draft-bormann-coap-misc-05 (work in progress), 292 July 2010. 294 [I-D.ietf-core-coap] 295 Shelby, Z., Frank, B., and D. Sturek, "Constrained 296 Application Protocol (CoAP)", draft-ietf-core-coap-01 297 (work in progress), July 2010. 299 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 300 Requirement Levels", BCP 14, RFC 2119, March 1997. 302 7.2. Informative References 304 [DUAL] Meijer, E., "Subject/Observer is Dual to Iterator", 305 June 2010, . 308 [REST] Fielding, R., "Architectural Styles and the Design of 309 Network-based Software Architectures", 2000, . 312 (Seminal dissertation introducing the REST architectural 313 style.) 315 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 316 Resource Identifier (URI): Generic Syntax", STD 66, 317 RFC 3986, January 2005. 319 [S6] Bormann, C., "S6: Synchronized S5", September 2005, 320 . 322 (S6 synchronized slide show system based on HTTP long- 323 polls.) 325 Appendix A. Rationale 327 This appendix documents the considerations that led to the design 328 specified in the main body of this document. 330 A.1. Design Pattern 332 Many designs are possible for the observe capability of CoAP. So 333 that we don't end up with a random, arbitrary design, we base our 334 considerations on the well-known subject/observer design pattern. In 335 this pattern, an object, called the subject, maintains a list of 336 interested parties, called observers, and notifies them automatically 337 of any state changes. 339 There are a number of variants of that design pattern. We like one 340 that explicitly considers the way the evolution of the resource state 341 might end [DUAL]. In detail, this variant of the design pattern 342 consists of the following elements: 344 o A _subject_, which sends notifications to observers. It has a 345 single method, SUBSCRIBE, which is called by observers that wish 346 to receive notifications from the subject. 348 o An _observer_, which receives notifications from a subject. It 349 has three methods: YIELD, which supplies the observer with new or 350 current information; THROW, which informs the observer that the 351 subject experienced an error condition; and BREAK, which indicates 352 that the subject has finished sending notifications. The grammar 353 of notifications to be expected over time therefore is: 355 YIELD* ( BREAK | THROW )? 357 o A _subscription_, which represents the interest of an observer in 358 a subject. It has a single method, UNSUBSCRIBE, which enables the 359 subject to unsubscribe observers when notification has finished. 360 Observers receive a reference to the subscription from the 361 SUBSCRIBE method, so they can also call the UNSUBSCRIBE method to 362 unsubscribe before the subject has finished sending notifications. 364 In this document, we describe an architecture and a protocol design 365 that realizes a meaningful rendition of this design pattern within 366 the REST-based [REST] environment of CoAP. 368 A.2. Architecture 370 We interpret resources as the _subjects_ of the subject/observer 371 pattern. The _subscription_ causes the subject to continuously 372 supply an _observer_ with the state of the resource: once upon 373 subscription and then whenever the state of the resource changes. We 374 call a CoAP node offering a resource _server_, and a CoAP node 375 subscribing an observer to a resource _client_. As with the existing 376 REST methods, this architecture is about exchanging representations 377 of resources, not about the messages (or method calls). 379 The design is REST-based, as it maintains REST's uniform interface 380 and its four interface constraints ([REST], section 5.1.5): 382 o Identification of resources by the uniform mechanism of URIs 383 [RFC3986]; 385 o Resource manipulation through the exchange of resource state 386 representations; 388 o Self-describing messages (potentially with multiple representation 389 formats); 391 o Hypermedia as the engine of application state: A server 392 premediates application state transitions by providing links in 393 resources.; 395 While this is not a necessary implication of the design described 396 here, the assumption is that the subscription itself is modeled on 397 the level of conversation state, not as a resource by itself. (This, 398 of course, does not imply that there can't be resources that help 399 nodes decide whether to create subscriptions, but these are 400 application-specific and outside the scope of CoAP.) 402 A.3. Requirements 404 The requirements for implementing the subject/observer design pattern 405 over UDP stem largely from the fact that UDP is an unreliable, 406 connectionless transport. This means that method calls must be 407 expressed as messages, that preparation must be taken for the case 408 that messages arrive out of order, appear duplicated, or go missing 409 without notice, and that the transport keeps no state between 410 messages that can be utilized. 412 The detailed requirements that follow from this are: 414 o An invocation of the SUBSCRIBE method on an observable resource is 415 implemented by sending a message (a subscription request) from the 416 subscribing client to the server that offers the resource. 418 The client must be able to determine if a subscription request was 419 received by the server, and, if not, must be able to retransmit 420 the request. 422 The server must acknowledge the subscription request, and must be 423 prepared to receive duplicated subscription requests. 425 Since subscribing can be made idempotent (Appendix A.7), the 426 server need not be able to detect a duplicated subscription 427 request as such. 429 The client must be able to relate the acknowledgment to the 430 subscription request. 432 o The usual considerations for retrieving the representation of a 433 resource in a REST-based protocol apply, e.g.: 435 A subscribing client must be able to influence the representation 436 format in which the server supplies the resource state to the 437 client. 439 o Upon subscription, an observer must be supplied with the current 440 state of the resource in the requested format. 442 If the observer cannot be supplied with the current state (for 443 example, because the resource does not exist, the state cannot be 444 represented in the requested format, the client lacks 445 authorization, or a general error condition occurred), the server 446 must inform the client of the error condition. 448 For efficiency, this initial notification may be sent within the 449 same datagram that acknowledges the subscription request. 451 The initial notification might not include the actual 452 representation (e.g., take the form of a "304 not modified") if 453 the client already has a valid representation of the resource. 454 The client should be able to supply information (e.g., Etags or a 455 modification date) to enable the server to make this 456 determination. 458 o To take advantage of the multicast capabilities of the transport, 459 it should be possible to subscribe a UDP multicast group to a 460 resource. In contrast to subscribing multiple clients 461 individually to the resource, the server in this case must treat 462 the multicast group as a single observer. 464 o For robustness, a subscription has to be maintained through 465 periodic refreshing. If a subscription is not refreshed, its 466 lifetime must end after a certain duration that is negotiated as 467 part of the message exchange that implements the SUBSCRIBE method 468 call. 470 So a subscribing client must be able to specify a subscription 471 lifetime duration in a subscription request. A server must be 472 able to return the negotiated subscription lifetime duration back 473 to the client. 475 Since the client is responsible for taking care of the 476 subscription, refreshing a subscription must be implemented by 477 sending a message (a subscription refresh request) from the 478 subscribed client to the server. 480 The client must be able to determine if a subscription refresh 481 request was received by the server, and, if not, must be able to 482 retransmit the request. 484 The server must acknowledge the request. It must be prepared to 485 receive duplicated requests. It must be able to relate a refresh 486 request to a subscription. 488 The client must be able to relate the acknowledgment to the 489 subscription refresh request. 491 The server must be prepared for a refresh request to arrive after 492 the subscription expired. In this case, the subscription refresh 493 request is treated the same as a subscription request, since the 494 client expressed the desire to continue being subscribed to the 495 resource. 497 o For notifications, the equivalent of an invocation of the YIELD, 498 BREAK or THROW method on an observer must be implemented by 499 sending a notification message from the server offering the 500 resource to the subscribed client. 502 The subscribed client must be able to relate a notification 503 message to a subscription and/or to a resource (see also 504 Appendix A.7). 506 It is not a requirement that a subscribed client receives every 507 single notification messages sent by a server, or that the server 508 sends a notification message for every single state change. 509 However, the state observed by an observer must eventually become 510 consistent with the actual state of the observed resource. 512 o The representation format used during the lifetime of a 513 subscription must not change. If the server is unable to continue 514 notifying a client in the requested representation format, it must 515 invoke the THROW method on the observer. 517 o A server must not send any further notification messages after 518 sending a notification message that denotes a BREAK or THROW. 520 However, a client must be prepared to receive notification 521 messages after receiving such a notification message. (In this 522 case, it discards the excessive notification messages.) 524 o For robustness, a server can request the acknowledgment of a 525 notification message from a client. (For example, in order to 526 check if the client is still there, or to make sure that an 527 observer observes a particular resource state.) Such a 528 notification is called a _confirmable_ notification message. 530 A server must be able to determine if a confirmable notification 531 message was received by the client, and, if not, must retransmit 532 the message. 534 If the client cannot relate the confirmable notification message 535 to a subscription, it must reject the message. Otherwise, it must 536 acknowledge the message. 538 The server must be able to relate the acknowledgment or rejection 539 to the confirmable notification message. 541 There is no support for multicasting confirmable notification 542 messages. 544 o To end a subscription before the lifetime of the subscription 545 expires (UNSUSBCRIBE method), a message (an 'unsubscribe' request) 546 can be sent from the subscribed client to the server that 547 maintains the subscription. 549 The client must be able to determine if an 'unsubscribe' request 550 was indeed received by the server, and, if not, must be able to 551 retransmit the request. 553 The server must acknowledge the 'unsubscribe' request, and must be 554 prepared to receive duplicated requests (which also need to be 555 acknowledged). 557 The client must be able to relate the acknowledgment to the 558 request. 560 Note that, in a REST-based environment, all these message exchanges 561 should also work correctly through proxies. 563 A.4. The Design 565 A.4.1. State 567 The state required on nodes as indicated by the requirements, can be 568 summarized as follows: 570 o Nodes that send requests must keep track of pending requests. 571 (For non-idempotent requests, the node that receives the request 572 also must retain state to deduplicate requests.) 574 o A server offering a resource must keep track of the observers of 575 the resource. Similarly, a proxy must keep track of the observers 576 that observe a resource through that proxy. 578 o Due to the initial notification of an observer upon subscription, 579 the server must also keep track the resource state itself. (It 580 cannot just notify all observers when the state changes and then 581 immediately forget the state.) 583 o A client subscribed to a resource may have to keep track of the 584 subscriptions to the resource in order to be able to relate 585 notifications to the subscription and in order to be able to 586 refresh the subscription before the subscription lifetime ends 587 (Appendix A.7). 589 o A client (or a proxy) may optionally keep a cache of resource 590 states. 592 A.4.2. Subscription Lifetime 594 To summarize, the lifetime of a subscription begins with a 595 subscription request, and it ends when 597 o the subscription lifetime expires (as defined by the subscription 598 duration option in the subscription request), 600 o the client unsubscribes from the resource, 602 o the client rejects a request related to a subscription, 604 o an error condition related to a subscription occurred, or 606 o the observed resource has finished sending notifications. 608 A client can extend the lifetime of a subscription before its end by 609 sending a subscription refresh request. 611 A.4.3. Messages 613 The following message types and elements can be gathered from the 614 requirements. 616 A.4.3.1. Requests 618 Requests are messages that need to be acknowledged by the recipient. 619 As with other request in CoAP, they are retransmitted by the sender 620 using an exponential back-off delay until the acknowledgment is 621 received. 623 The request message types as indicated by the requirements can be 624 summarized as follows: 626 o A SUBSCRIBE request creates a new subscription or refreshes an 627 existing subscription. 629 o An UNSUBSCRIBE request ends an existing subscription. 631 To put this into perspective, the existing GET, PUT, POST and DELETE 632 messages have request semantics as well. 634 o A GET request retrieves a representation of the current resource 635 state. 637 o A PUT request provides a new resource state in some representation 638 format. 640 o A POST request creates or extends a resource. 642 o A DELETE request deletes a resource. 644 A request message includes a _transaction identifier_ which allows 645 the recipient to detect duplicated requests and, by inclusion of the 646 transaction identifier in the acknowledgment to the request, enables 647 the sender to relate the acknowledgment to the request. 649 A.4.3.2. Replies 651 Replies are messages that are sent in reply to a request. They carry 652 the aforementioned transaction identifier. 654 The reply messages types as indicated by the requirements can be 655 summarized as follows: 657 o An ACK reply indicates an acknowledgment of a request. 659 o A RST reply indicates the rejection of a request. 661 (Responses in CoAP are replies that may carry a resource 662 representation.) 664 A.4.3.3. Notifications 666 Matching the methods of an observer, the notification message types 667 can be summarized as follows: 669 o A YIELD notification supplies the subscribed client with the state 670 of a resource in some representation. 672 o A BREAK notification indicates that the observed resource has 673 finished sending notifications. 675 o A THROW notification informs the subscribed client of an error 676 condition. 678 Each of these notification messages can be sent as a message that 679 does not require acknowledgment, as a confirmable message that does 680 require acknowledgment (which makes it a request), or (in case of an 681 initial notification) piggy-backed with the ACK message that is sent 682 in reply to the subscription request. 684 A.5. Message Exchanges 686 The following message exchanges can be derived from the requirements. 688 A.5.1. Subscribing to a resource 690 Client Server Client Server 691 | | | | 692 | SUBSCRIBE | | SUBSCRIBE | 693 +---------------->| +---------------->| 694 | | | | 695 | ACK+YIELD | | ACK | 696 |<----------------+ or |<----------------+ 697 | | | | 698 ... Time Passes ... 699 | | 700 | YIELD [c?] | 701 |<----------------+ 702 | | 703 | ACK (if c) | 704 +---------------->| 705 | | 707 Figure 3 709 The workflow for subscribing an observer to an observable resource or 710 refreshing a subscription is as follows: 712 1. The subscribing client sends a SUBSCRIBE request to the server 713 that is offering the observable resource. The subscription 714 request includes the identifier of a representation format in 715 which the notifications have to be sent, specifies a subscription 716 lifetime duration and optionally indicates states cached by the 717 client (by Etag or Date) and other information that might be 718 relayed in a GET request. 720 2. The server creates a new subscription if no subscription exists 721 (Appendix A.7), and changes the lifetime duration of the 722 subscription to the duration specified in the subscription 723 request, or any shorter duration if it so desires. The server 724 then acknowledges the request and indicates the actual lifetime 725 with a ACK reply (or with a ACK+THROW, ACK+BREAK or ACK+YIELD 726 reply as described in the next step). 728 3. The server performs one of the following actions: 730 * If an error occurred, the server sends a THROW notification 731 (either as THROW request or as ACK+THROW reply to the 732 SUBSCRIBE request). 734 * If the resource has finished sending notifications, the server 735 sends a BREAK notification (either as BREAK request or as ACK+ 736 BREAK reply to the SUBSCRIBE request). 738 * Otherwise, the server supplies the observer with the current 739 resource state in the requested representation format, or 740 indicates that the cached state is the current state (either 741 as YIELD request or as ACK+YIELD reply to the SUBSCRIBE 742 request). 744 If the server sends a THROW, BREAK or YIELD request, the request 745 is treated like any other notification (i.e. the client must 746 acknowledge it if the message is marked as confirmable, etc.). 748 4. If the client does not receive the ACK, ACK+THROW, ACK+BREAK or 749 ACK+YIELD reply within a certain time frame (because the request 750 or the reply went missing), the client retransmits the SUBSCRIBE 751 request using the same request identifier. 753 A.5.2. Notifying of state changes 755 Client Server Client Server 756 | | | | 757 | YIELD | | YIELD [c] | 758 |<----------------+ or |<----------------+ 759 | | | | 760 | ACK | 761 +---------------->| 762 | | 764 Figure 4 766 The workflow for notifying an observer of a state change is as 767 follows: 769 1. The server performs one of the following actions: 771 * If the resource experienced an error condition, the server 772 sends a THROW request to the client. 774 * If the resource has finished sending notifications, the server 775 sends a BREAK request to the client. 777 * If the state of the resource changed, the server sends a YIELD 778 request with the current resource state in the requested 779 representation format. 781 The server may or may not mark the request sent as confirmable 782 ("[c]"). The server marks a request as confirmable because it 783 wants to check if the observer is still alive, or because there 784 might not be another notification in the near future and the 785 confirmation process is therefore needed to ensure eventual 786 consistency. 788 2. If the request is marked as confirmable, the subscribed client 789 performs one of the following actions: 791 * If the notification cannot be related to a subscription, the 792 client sends a RST reply. 794 * Otherwise, the client sends an ACK reply. 796 3. If the request is marked as confirmable and the server does not 797 receive the ACK reply or the RST reply within a given time frame, 798 the server retransmits the request using the same transaction 799 identifier. 801 (Note that it is entirely the decision of the server whether to 802 request an acknowledgment by marking the request as confirmable - it 803 might want to employ different strategies to determine this, e.g. 804 based on frequency of change, management of state etc.) 806 A.5.3. Unsubscribing from a resource 808 Client Server 809 | | 810 | UNSUBSCRIBE | 811 +---------------->| 812 | | 813 | ACK | 814 |<----------------+ 815 | | 817 Figure 5 819 The workflow for unsubscribing an observer from an observed resource 820 is as follows: 822 1. The subscribed client sends an UNSUBSCRIBE request to the server 823 offering the observed resource. 825 2. The server changes the lifetime duration of the subscription to 826 zero, which immediately expires the subscription. The server 827 then acknowledges the request with a ACK reply. 829 3. If the client does not receive the ACK reply within a certain 830 time frame, the client retransmits the UNSUBSCRIBE request using 831 the same request identifier. 833 Note that an subscribed client can also unsubscribe by "forgetting" 834 the subscription and subsequently replying with a RST to the next 835 notification. (In order to allow sending that RST even for messages 836 that are not marked as confirmable, an otherwise redundant 837 transaction identifier is sent in all messages.) 839 (An UNSUBSCRIBE message might be implemented as a SUBSCRIBE message 840 with a lifetime duration of 0, but this has some unintended 841 consequences. See Appendix A.7.) 843 A.5.4. Retrieving resource state 845 Note that a GET request matches closely the first steps of 846 subscribing, except that the GET request does not create or update an 847 subscription. (A GET request is likely to mark the yield as 848 confirmable.) 850 The second form in Figure 6 solves the long-poll case. 852 Client Server Client Server 853 | | | | 854 | GET | | GET | 855 +---------------->| +---------------->| 856 | | | | 857 | ACK+YIELD | | ACK | 858 |<----------------+ or |<----------------+ 859 | | | | 860 ... Time Passes ... 861 | | 862 | YIELD [c] | 863 |<----------------+ 864 | | 865 | ACK | 866 +---------------->| 867 | | 869 Figure 6 871 A.5.5. Changing resource state 873 Client Server Client Server 874 | | | | 875 | PUT | | PUT | 876 +---------------->| +---------------->| 877 | | | | 878 | ACK+BREAK | | ACK | 879 |<----------------+ or |<----------------+ 880 | | | | 881 ... Time Passes ... 882 | | 883 | BREAK [c] | 884 |<----------------+ 885 | | 886 | ACK | 887 +---------------->| 888 | | 890 Figure 7 892 (The motivation for the BREAK component of the response is: PUT, like 893 GET, can experience some error condition, so we need a place in the 894 state machine to put the THROW response; therefore we also need a 895 BREAK response. The second case in Figure 7 is motivated by: PUT, 896 like GET, can take some time to be processed, so we must be able to 897 send an ACK immediately and the THROW or BREAK response later.) 899 Obviously, changing the state of this resource leads to notification 900 of any observers of new state. PUT is idempotent, but if we add 901 notifications it may be a bit surprising that a duplicated or 902 retransmitted PUT might send notifications twice. To prevent that, 903 the resource might check whether it is being changed to the same 904 state it had before and not send notifications in that case. 906 A.5.6. Deleting a resource 908 A DELETE request is the same as a PUT request, except that the 909 resource is not created or its state changed, but deleted. 911 Client Server 912 | | 913 | DELETE | 914 +---------------->| 915 | | 916 | ACK+BREAK | 917 |<----------------+ 918 | | 920 Figure 8 922 If a resource is observed, deleting the resource leads to an error 923 condition of which the observers are notified with a THROW 924 notification or THROW request. 926 A.6. Caching 928 An observer may cache part or all of a resource's state changes. 929 This allows clients to make conditional requests: If a subscribing 930 client has cached a particular resource state, the server offering 931 the resource does not need to send a full notification. 933 o A client informs the server of its cached resource states by 934 including Etags of cached resource states in the subscription 935 request. This can be multiple Etags, as this enables the server 936 to just send a "304 not modified" for a different Etag instead of 937 a different representation if the resource switches around between 938 multiple states. (Note that this list might be updated by a 939 subscription refresh.) 941 o A server notifies a client of a change to a cached state by 942 omitting the representation of the resource state in the 943 notification and including a flag ("304 not modified") that 944 indicates that the state changed to a cached state. 946 Another approach to caching multiple values for a resource is to 947 express each possible value of the resource's representation by a 948 reference to another (unchanging) resource. This lets a resource 949 change states between a set of such references that then provide the 950 actual state information. A subscribed client fetches the individual 951 resources on demand and caches the results for future use. 953 A.7. Identifying notifications and subscriptions 955 There are two ways that a notification could be related to the 956 resource that it is about: 958 1. The notification could name the resource (its URI). 960 2. The notification could name a target that relates to a 961 subscription, which in turn relates back to the resource. 963 One or both ways could be implemented in CoAP, there are not 965 For way 1, each notification would contain the URI of the resource. 966 This is particularly useful for multicast messages, but could be 967 relatively wasteful. Also, it is not entirely clear that all servers 968 will be aware of their own authority. Apart from cached states 969 (Appendix A.6) and other information that could be part of a GET, a 970 subscription would simply be the triple 972 [URI, observer transport address, lifetime] 974 Resubscribing (or a duplicate subscription request) for the same 975 [URI, observer transport address] pair simply updates the lifetime; 976 thus, the subscription operation is idempotent. Similarly, 977 resubscribing with a lifetime of 0 will serve to delete the 978 subscription (however, a SUBSCRIBE message will be replied to with 979 the current state of the resource; a SUBSCRIBE with lifetime 0 is 980 thus equivalent to a GET with the side effect of deleting the 981 subscription). 983 The notification then needs to contain the URI (and might 984 occasionally contain a remaining lifetime): 986 [resource representation, resource metadata, URI, lifetime?] 988 For way 2, the subscription request would also contain a target 989 identifier that is to be used in every notification, identifying the 990 specific observer object that is to receive the notification. Again 991 apart from cached states (Appendix A.6) and other information that 992 could be part of a GET, the subscription would be the quadruple: 994 [URI, observer transport address, target, lifetime] 996 (Note that the combination of the observer transport address and the 997 target could be expressed as another URI, with the transport address 998 as the authority and the target as the path. Alternatively, the 999 target could be a short byte string. By varying the transport 1000 address, i.e. the port number, the target could also made to be 1001 always empty.) 1003 Resubscribing (or a duplicate subscription request) for the same 1004 [URI, observer transport address, target] triple simply updates the 1005 lifetime, thus, the subscription operation again is idempotent. (The 1006 same comment as with way 1 applies to SUBSCRIBE with lifetime 0.) 1008 As the notification already implicitly contains the transport 1009 address, it would just list the target (and might occasionally 1010 contain a remaining lifetime): 1012 [resource representation, resource metadata, target, lifetime?] 1014 In both cases, it would be beneficial if rebooting nodes could obtain 1015 the same transport address they had before, because a resubscription 1016 after the reboot does not create additional state. 1018 Multicast works nicely in way 1 (except that the URI may be large). 1019 In way 2, we can give each observer in a multicast group the same 1020 target name, so multicast works. 1022 For normal subscriptions, the observer transport address can be 1023 implied from the source address of the subscription request. For 1024 multicast, there needs to be a way to explicitly indicate that 1025 transport address. (This may be beneficial for unicast, too.) 1027 A.8. Open issues 1029 Add discussion of messages that get reordered. 1031 Add detailed message and option formats, once the semantics are 1032 agreed. 1034 Describe how to map this to HTTP long-polls, WebSockets, and other 1035 asynchronous forms of HTTP. 1037 Authors' Addresses 1039 Klaus Hartke 1040 Universitaet Bremen TZI 1041 Postfach 330440 1042 Bremen D-28359 1043 Germany 1045 Phone: +49-421-218-63905 1046 Fax: +49-421-218-7000 1047 Email: hartke@tzi.org 1049 Carsten Bormann 1050 Universitaet Bremen TZI 1051 Postfach 330440 1052 Bremen D-28359 1053 Germany 1055 Phone: +49-421-218-63921 1056 Fax: +49-421-218-7000 1057 Email: cabo@tzi.org