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
| "<temp... | as it is implied by the TID.)
|<----------------+
| |
... Time Passes ...
| |
| NON tid=153 | Here, the server decides
| 200 /foo | it will send updates often
| "<temp... | enough that a non-confirmable
|<----------------+ message is sufficient.
| |
... Time Passes ...
| |
| CON tid=783 | Here, the server decides
| 200 /foo | to send a confirmable message
| "<temp... | as the time to the next update
|<----------------+ is not certain yet.
| |
| ACK tid=783 |
+---------------->|
| | ... 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, <http://
www.ics.uci.edu/~fielding/pubs/dissertation/top.htm>.
(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]