idnits 2.17.1 draft-ietf-core-observe-00.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. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) 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 (October 18, 2010) is 4937 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) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-02 Summary: 2 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group K. Hartke, Ed. 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Standards Track Z. Shelby 5 Expires: April 21, 2011 Sensinode 6 October 18, 2010 8 Observing Resources in CoAP 9 draft-ietf-core-observe-00 11 Abstract 13 The state of a resource can change over time. We want to give 14 clients of the CoRE WG CoAP protocol the ability to observe this 15 change. This short I-D provides a design for such an addition to 16 CoAP. 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 April 21, 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. Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2.1. Subscriptions . . . . . . . . . . . . . . . . . . . . . . 4 55 2.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 4 56 3. Subscription-lifetime Option . . . . . . . . . . . . . . . . . 6 57 3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 4. Open issues . . . . . . . . . . . . . . . . . . . . . . . . . 8 59 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 60 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 61 6.1. Normative References . . . . . . . . . . . . . . . . . . . 10 62 6.2. Informative References . . . . . . . . . . . . . . . . . . 10 63 Appendix A. Data types . . . . . . . . . . . . . . . . . . . . . 11 64 A.1. Variable-length unsigned integer . . . . . . . . . . . . . 11 65 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 67 1. Introduction 69 The state of a resource can change over time. We want to give CoAP 70 [I-D.ietf-core-coap] clients the ability to observe this change. 72 This short I-D describes an architecture and a protocol design that 73 realizes the well-known subject/observer design pattern within the 74 REST-based [REST] environment of CoAP. 76 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 77 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 78 and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119] 79 and indicate requirement levels for compliant CoAP implementations. 81 2. Architecture 83 The architecture is based on the well-known subject/observer design 84 pattern. In this pattern, an object, called the subject, maintains a 85 list of interested parties, called observers, and notifies them 86 automatically when a predefined condition occurs. 88 In the context of CoAP, the subjects are resources. A subscription 89 to a resource causes the CoAP server to continuously supply an CoAP 90 client with the state of the resource: once upon subscription and 91 then whenever the state of the resource changes. 93 As with the existing REST methods, this architecture is about 94 exchanging representations of resources, not about the messages (or 95 method calls). 97 2.1. Subscriptions 99 A client subscribes to a resource by performing a GET request that 100 includes the Subscription-lifetime Option (Section 3). A 101 subscription request MAY include a Token Option, which will then be 102 included in all subsequent notifications. For robustness, a 103 subscription has to be maintained through periodic refreshing. If a 104 subscription is not refreshed, it MUST end after the duration that is 105 negotiated using the Subscription-lifetime Option. A client 106 refreshes a subscription by repeating the original GET request before 107 the subscription lifetime expired. 109 2.2. Notifications 111 Upon subscription, an observer MUST be supplied with the current 112 state of the resource. For efficiency, this initial notification MAY 113 be sent within the same message that acknowledges the subscription 114 request. 116 The client is notified of resource state changes by additional 117 responses sent from the server to the client. Each such notification 118 response MUST include either the request URI or Token Option, and the 119 remaining subscription lifetime. 121 It is not necessary that a subscribed client receives every single 122 notification response, or that the server sends a notification 123 response for every single state change. However, the state observed 124 by an observer SHOULD eventually become consistent with the actual 125 state of the observed resource. 127 The representation format (i.e. the media type) used during the 128 lifetime of a subscription MUST NOT change. If the server is unable 129 to continue sending notification responses to a client in the 130 requested representation format, it MUST send a response with code 131 406 (Not Acceptable) and end the subscription. 133 A server MUST NOT send any further notification responses after 134 sending a response with code 4xx or 5xx, i.e. the subscription MUST 135 end. (Note: a client must be prepared to receive additional 136 notification responses after receiving such a response. In this 137 case, it MUST handle them like a subscription notification that it 138 cannot relate to a subscription.) 140 For resources that change in a somewhat predictable or regular 141 fashion. it is RECOMMENDED that a notification message is non- 142 confirmable. For robustness, a server MAY instead request the 143 acknowledgment of a notification response from a client by marking it 144 as confirmable. (For example, in order to check if the client is 145 still there, or to make sure that an observer observes a particular 146 resource state.) If a confirmable notification requires a 147 retransmission, it is RECOMMENDED to send the state that is current 148 at the instant of the retransmission; it is NOT RECOMMENDED to have 149 multiple such confirmable notification transactions active for one 150 resource/client pair at any one instant. 152 If a client cannot relate a confirmable notification response to a 153 subscription, it MUST reject the message with a RST (in which case 154 the server MUST end the subscription). Otherwise, it MUST 155 acknowledge the message with an ACK. 157 3. Subscription-lifetime Option 159 +-----+----+--------------------+----------------+--------+---------+ 160 | Typ | C/ | Name | Data type | Length | Default | 161 | e | E | | | | | 162 +-----+----+--------------------+----------------+--------+---------+ 163 | 10 | E | Subscription-lifet | Variable-lengt | 0-4 B | 0 | 164 | | | ime | h unsigned | | | 165 | | | | integer | | | 166 | | | | (Appendix A.1) | | | 167 +-----+----+--------------------+----------------+--------+---------+ 169 The Subscription-lifetime Option, when present, modifies the GET 170 method so it does not only retrieve a representation of the current 171 state of the resource identified by the request URI once, but also 172 lets the server notify the client of changes to the resource state 173 for the duration specified in the option. 175 (Note: since the Subscription-lifetime Option is elective, the GET 176 request that includes the Subscription-lifetime Option will 177 automatically fall back to a simple GET request if the server does 178 not support subscriptions.) 180 In a response, the Subscription-lifetime Option indicates a lower 181 bound (e.g., by rounding down) for the remaining subscription 182 lifetime. (Note that the server can always choose to cut short the 183 subscription lifetime before it echoes this lifetime back in an ACK 184 or a confirmable response.) 186 3.1. Example 188 Client Server 189 | | 190 | CON tid=47 | 191 | GET /foo | 192 | lifetime=60s | 193 +---------------->| 194 | | 195 | ACK tid=47 | 196 | 200 /foo | (The URI is actually elided 197 | "| 216 | | ... and so on... 218 Figure 1 220 4. Open issues 222 Add discussion of messages that get reordered. 224 Add discussion of how to handle the influence of datagram latency on 225 subscription lifetimes. 227 Describe how subscriptions interact with other CoAP features (e.g., 228 the Block Option, caching, etc.). 230 Describe how to map subscriptions to HTTP long-polls, WebSockets, and 231 other asynchronous forms of HTTP. 233 5. Acknowledgements 235 Carsten Bormann was an original author of this draft and is 236 acknowledged for significant contribution to this document. This 237 work was partially funded by the Klaus Tschira Foundation. 239 6. References 241 6.1. Normative References 243 [I-D.ietf-core-coap] 244 Shelby, Z., Frank, B., and D. Sturek, "Constrained 245 Application Protocol (CoAP)", draft-ietf-core-coap-02 246 (work in progress), September 2010. 248 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 249 Requirement Levels", BCP 14, RFC 2119, March 1997. 251 6.2. Informative References 253 [REST] Fielding, R., "Architectural Styles and the Design of 254 Network-based Software Architectures", 2000, . 257 (Seminal dissertation introducing the REST architectural 258 style.) 260 Appendix A. Data types 262 A.1. Variable-length unsigned integer 264 A "Variable-length unsigned integer" is a non-negative integer that 265 is represented in network byte order and uses a variable number of 266 bytes as shown in Figure 2. 268 Len = 0 (implies value of 0) 270 0 271 0 1 2 3 4 5 6 7 272 +-+-+-+-+-+-+-+-+ 273 Len = 1 | 0-255 | 274 +-+-+-+-+-+-+-+-+ 276 0 1 277 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 278 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 279 Len = 2 | 0-65535 | 280 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 282 Len = 3 is 24 bits, Len = 4 is 32 bits etc. 284 Figure 2: Variable length unsigned integer value format 286 Authors' Addresses 288 Klaus Hartke (editor) 289 Universitaet Bremen TZI 290 Postfach 330440 291 Bremen D-28359 292 Germany 294 Phone: +49-421-218-63905 295 Fax: +49-421-218-7000 296 Email: hartke@tzi.org 298 Zach Shelby 299 Sensinode 300 Kidekuja 2 301 Vuokatti 88600 302 FINLAND 304 Phone: +358407796297 305 Email: zach@sensinode.com