CoRE Working Group K. Hartke Internet-Draft C. Bormann Intended status: Informational Universitaet Bremen TZI Expires: February 25, 2011 August 24, 2010 Observing Resources in CoAP draft-hartke-coap-observe-02 Abstract The state of a resource can change over time. We want to give clients of the CoRE WG CoAP protocol the ability to observe this change. This short I-D provides a design for such an addition to CoAP. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on February 25, 2011. Copyright Notice Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Hartke & Bormann Expires February 25, 2011 [Page 1] Internet-Draft CoAP-observe August 2010 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Architecture . . . . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Subscriptions . . . . . . . . . . . . . . . . . . . . . . 4 2.2. Notifications . . . . . . . . . . . . . . . . . . . . . . 4 3. Subscription-lifetime Option . . . . . . . . . . . . . . . . . 6 3.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 4. Open issues . . . . . . . . . . . . . . . . . . . . . . . . . 8 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 6.1. Normative References . . . . . . . . . . . . . . . . . . . 10 6.2. Informative References . . . . . . . . . . . . . . . . . . 10 Appendix A. Data types . . . . . . . . . . . . . . . . . . . . . 11 A.1. Variable-length unsigned integer . . . . . . . . . . . . . 11 A.2. Duration . . . . . . . . . . . . . . . . . . . . . . . . . 11 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 Hartke & Bormann Expires February 25, 2011 [Page 2] Internet-Draft CoAP-observe August 2010 1. Introduction The state of a resource can change over time. We want to give CoAP [I-D.ietf-core-coap] clients the ability to observe this change. This short I-D describes an architecture and a protocol design that realizes the well-known subject/observer design pattern within the REST-based [REST] environment of CoAP. In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in BCP 14 [RFC2119] and indicate requirement levels for compliant CoAP implementations. Hartke & Bormann Expires February 25, 2011 [Page 3] Internet-Draft CoAP-observe August 2010 2. Architecture The architecture is based on the well-known subject/observer design pattern. In this pattern, an object, called the subject, maintains a list of interested parties, called observers, and notifies them automatically when a predefined condition occurs. In the context of CoAP, the subjects are resources. A subscription to a resource causes the CoAP server to continuously supply an CoAP client with the state of the resource: once upon subscription and then whenever the state of the resource changes. As with the existing REST methods, this architecture is about exchanging representations of resources, not about the messages (or method calls). 2.1. Subscriptions A client subscribes to a resource by performing a GET request that includes the Subscription-lifetime Option (Section 3). For robustness, a subscription has to be maintained through periodic refreshing. If a subscription is not refreshed, it MUST end after the duration that is negotiated using the Subscription-lifetime Option. A client refreshes a subscription by repeating the original GET request before the subscription lifetime expired. 2.2. Notifications Upon subscription, an observer MUST be supplied with the current state of the resource. For efficiency, this initial notification MAY be sent within the same message that acknowledges the subscription request. The client is notified of resource state changes by additional responses sent from the server to the client. Each such notification response MUST include the request URI, token and remaining subscription lifetime. It is not necessary that a subscribed client receives every single notification response, or that the server sends a notification response for every single state change. However, the state observed by an observer SHOULD eventually become consistent with the actual state of the observed resource. The representation format (i.e. the media type) used during the lifetime of a subscription MUST NOT change. If the server is unable to continue sending notification responses to a client in the requested representation format, it MUST send a response with code Hartke & Bormann Expires February 25, 2011 [Page 4] Internet-Draft CoAP-observe August 2010 406 (Not Acceptable) and end the subscription. A server MUST NOT send any further notification responses after sending a response with code 4xx or 5xx, i.e. the subscription MUST end. (Note: a client must be prepared to receive additional notification responses after receiving such a response. In this case, it MUST handle them like a subscription notification that it cannot relate to a subscription.) For resources that change in a somewhat predictable or regular fashion. it is RECOMMENDED that a notification message is non- confirmable. For robustness, a server MAY instead request the acknowledgment of a notification response from a client by marking it as confirmable. (For example, in order to check if the client is still there, or to make sure that an observer observes a particular resource state.) If a confirmable notification requires a retransmission, it is RECOMMENDED to send the state that is current at the instant of the retransmission; it is NOT RECOMMENDED to have multiple such confirmable notification transactions active for one resource/client pair at any one instant. If a client cannot relate a confirmable notification response to a subscription, it MUST reject the message with a RST (in which case the server MUST end the subscription). Otherwise, it MUST acknowledge the message with an ACK. Hartke & Bormann Expires February 25, 2011 [Page 5] Internet-Draft CoAP-observe August 2010 3. Subscription-lifetime Option +-----+----+---------------------+---------------+--------+---------+ | Typ | C/ | Name | Data type | Length | Default | | e | E | | | | | +-----+----+---------------------+---------------+--------+---------+ | 10 | E | Subscription-lifeti | Duration | 0-4 B* | 0 | | | | me | (Appendix A.2 | | | | | | | ) | | | +-----+----+---------------------+---------------+--------+---------+ The Subscription-lifetime Option, when present, modifies the GET method so it does not only retrieve a representation of the current state of the resource identified by the request URI once, but also lets the server notify the client of changes to the resource state for the duration specified in the option. (Note: since the Subscription-lifetime Option is elective, the GET request that includes the Subscription-lifetime Option will automatically fall back to a simple GET request if the server does not support subscriptions.) In a response, the Subscription-lifetime Option indicates a lower bound (e.g., by rounding down) for the remaining subscription lifetime. (Note that the server can always choose to cut short the subscription lifetime before it echoes this lifetime back in an ACK or a confirmable response.) Hartke & Bormann Expires February 25, 2011 [Page 6] Internet-Draft CoAP-observe August 2010 3.1. Example Client Server | | | CON tid=47 | | GET /foo | | lifetime=60s | +---------------->| | | | ACK tid=47 | | 200 /foo | (The URI is actually elided | "| | | ... and so on... Figure 1 Hartke & Bormann Expires February 25, 2011 [Page 7] Internet-Draft CoAP-observe August 2010 4. Open issues Add discussion of messages that get reordered. Add discussion of how to handle the influence of datagram latency on subscription lifetimes. Describe how subscriptions interact with other CoAP features (e.g., the Block Option, caching, etc.). Describe how to map subscriptions to HTTP long-polls, WebSockets, and other asynchronous forms of HTTP. Hartke & Bormann Expires February 25, 2011 [Page 8] Internet-Draft CoAP-observe August 2010 5. Acknowledgements This work was partially funded by the Klaus Tschira Foundation. Hartke & Bormann Expires February 25, 2011 [Page 9] Internet-Draft CoAP-observe August 2010 6. References 6.1. Normative References [I-D.ietf-core-coap] Shelby, Z., Frank, B., and D. Sturek, "Constrained Application Protocol (CoAP)", draft-ietf-core-coap-01 (work in progress), July 2010. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 6.2. Informative References [I-D.bormann-coap-misc] Bormann, C. and K. Hartke, "Miscellaneous additions to CoAP", draft-bormann-coap-misc-05 (work in progress), July 2010. [REST] Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", 2000, . (Seminal dissertation introducing the REST architectural style.) Hartke & Bormann Expires February 25, 2011 [Page 10] Internet-Draft CoAP-observe August 2010 Appendix A. Data types A.1. Variable-length unsigned integer A "Variable-length unsigned integer" is a non-negative integer that is represented in network byte order and uses a variable number of bytes as shown in Figure 2. Len = 0 (implies value of 0) 0 0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+-+ Len = 1 | 0-255 | +-+-+-+-+-+-+-+-+ 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Len = 2 | 0-65535 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Len = 3 is 24 bits, Len = 4 is 32 bits etc. Figure 2: Variable length unsigned integer value format A.2. Duration This draft takes no position on how a Duration should be represented. Pick one of: 1. A "Duration" is a variable-length unsigned integer (Appendix A.1) that indicates a duration of time measured in seconds. 2. A "Duration" is defined as in [I-D.bormann-coap-misc]. Hartke & Bormann Expires February 25, 2011 [Page 11] Internet-Draft CoAP-observe August 2010 Authors' Addresses Klaus Hartke Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63905 Fax: +49-421-218-7000 Email: hartke@tzi.org Carsten Bormann Universitaet Bremen TZI Postfach 330440 Bremen D-28359 Germany Phone: +49-421-218-63921 Fax: +49-421-218-7000 Email: cabo@tzi.org Hartke & Bormann Expires February 25, 2011 [Page 12]