One document matched: draft-ietf-core-observe-05.xml
<?xml version="1.0" encoding="us-ascii"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC1122 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1122.xml">
<!ENTITY RFC1982 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1982.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2616 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2616.xml">
<!ENTITY RFC5988 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5988.xml">
<!ENTITY RFC5989 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5989.xml">
<!ENTITY RFC6202 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6202.xml">
<!ENTITY I-D.ietf-core-coap SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-coap.xml">
<!ENTITY I-D.ietf-core-link-format SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-link-format.xml">
<!ENTITY I-D.ietf-core-block SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-core-block.xml">
<!ENTITY SELF "[RFCXXXX]">
<!ENTITY OPTION1 "Observe"><!ENTITY anOPTION1 "an &OPTION1;">
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<?rfc strict="yes"?>
<?rfc toc="yes"?>
<?rfc tocdepth="3"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes"?>
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<rfc category="std" docName="draft-ietf-core-observe-05" ipr="trust200902">
<front>
<title>Observing Resources in CoAP</title>
<author initials="K." surname="Hartke" fullname="Klaus Hartke">
<organization>Universitaet Bremen TZI</organization>
<address>
<postal>
<street>Postfach 330440</street>
<city>Bremen</city>
<code>D-28359</code>
<country>Germany</country>
</postal>
<phone>+49-421-218-63905</phone>
<facsimile>+49-421-218-7000</facsimile>
<email>hartke@tzi.org</email>
</address>
</author>
<!--
<author initials="Z." surname="Shelby" fullname="Zach Shelby" role="editor">
<organization>Sensinode</organization>
<address>
<postal>
<street>Kidekuja 2</street>
<city>Vuokatti</city>
<code>88600</code>
<country>Finland</country>
</postal>
<phone>+358407796297</phone>
<email>zach@sensinode.com</email>
</address>
</author>
<author initials="C." surname="Bormann" fullname="Carsten Bormann">
<organization>Universitaet Bremen TZI</organization>
<address>
<postal>
<street>Postfach 330440</street>
<city>Bremen</city>
<code>D-28359</code>
<country>Germany</country>
</postal>
<phone>+49-421-218-63921</phone>
<facsimile>+49-421-218-7000</facsimile>
<email>cabo@tzi.org</email>
</address>
</author>
-->
<date year="2012"/>
<area>Applications</area>
<workgroup>CoRE Working Group</workgroup>
<abstract>
<t>CoAP is a RESTful application protocol for constrained nodes and
networks. The state of a resource on a CoAP server can change over
time. This document specifies a simple protocol extension for CoAP that
gives clients the ability to observe such changes.</t>
</abstract>
</front>
<middle>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Introduction" anchor="introduction">
<section title="Background" anchor="background">
<t><xref target="I-D.ietf-core-coap">CoAP</xref> is an Application
Protocol for Constrained Nodes/Networks. It is intended to provide
<xref target="REST">RESTful services</xref> not unlike <xref
target="RFC2616">HTTP</xref> while reducing the complexity of
implementation as well as the size of packets exchanged in order to
make these services useful in a highly constrained network of
themselves highly constrained nodes.</t>
<t>The communication model of REST is that of a client exchanging
resource representations with an origin server. The origin server is
the definitive source for representations of the resources in its
namespace. A client interested in a resource sends a request to the
origin server that returns a response with a representation that is
current at the time of the request.</t>
<t>This model does not work well when a client is interested in having
a current representation of a resource over a period of time.
Existing approaches when using HTTP, such as repeated polling or
<xref target="RFC6202">long-polls</xref>, generate significant
complexity and/or overhead and thus are less applicable in a
constrained environment.</t>
<t>The protocol specified in this document extends the CoAP core
protocol with a mechanism to push resource representations from
servers to interested clients, while still keeping the properties of
REST.</t>
<t>Note that there is no intention for this mechanism to solve the full
set of problems that the existing HTTP solutions solve, or to replace
publish/subscribe networks that solve a much more general problem
<xref target="RFC5989"/>.</t>
</section>
<section title="Protocol Overview" anchor="overview">
<t>The protocol is based on the well-known <xref target="GOF">observer
design pattern</xref>.</t>
<t>In this design pattern, components, called
<spanx style="emph">observers</spanx>, register at a specific, known
provider, called the <spanx style="emph">subject</spanx>, that they
are interested in being notified whenever the subject undergoes a
change in state. The subject is responsible for administering its
list of registered observers. If multiple subjects are of interest,
an observer must register separately for all of them. The pattern is
typically used when a clean separation between related components is
required, such as data storage and user interface.</t>
<figure anchor="design-pattern" title="Observer Design Pattern">
<artwork type="drawing" align="left"><![CDATA[
Observer Subject
| |
| Register |
+----------------->|
| |
| Notification |
|<-----------------+
| |
| Notification |
|<-----------------+
| |
| Notification |
|<-----------------+
| |
]]></artwork>
</figure>
<t>The observer design pattern is realized in CoAP as follows: <list
style="hanging">
<t hangText="Subject:">In the context of CoAP, the subject is a
resource in the namespace of a CoAP server. The state of the
resource can change over time, ranging from infrequent updates to
continuous state transformations.</t>
<t hangText="Observer:">An observer is a CoAP client that is
interested in the current state of the resource at any given
time.</t>
<t hangText="Registration:">A client registers its interest by
sending an extended GET request to the server. In addition to
returning a representation of the target resource, this request
causes the server to add the client to the list of observers of
the resource.</t>
<t hangText="Notification:">Whenever the state of a resource
changes, the server notifies each client registered as observer
for the resource. Each notification is an additional CoAP
response sent by the server in reply to the GET request and
includes a complete representation of the new resource state.</t>
</list>
</t>
<t><xref target="example"/> shows an example of a CoAP client
registering and receiving three notifications: the first upon
registration and then two when the state of the resource changes.
Registration request and notifications are identified by the presence
of the &OPTION1; Option defined in this document. Notifications also
echo the token specified by the client in the request, so the client
can easily correlate them to the request.</t>
<figure anchor="example" title="Observing a Resource in CoAP">
<artwork type="drawing" align="left"><![CDATA[
Client Server
| |
| GET /temperature |
| Observe: 0 | (registration)
| Token: 0x4a |
+----------------->|
| |
| 2.05 Content |
| Observe: 12 | (notification of the current state)
| Token: 0x4a |
| Payload: 22.9 C |
|<-----------------+
| |
| 2.05 Content |
| Observe: 44 | (notification upon a state change)
| Token: 0x4a |
| Payload: 22.8 C |
|<-----------------+
| |
| 2.05 Content |
| Observe: 60 | (notification upon a state change)
| Token: 0x4a |
| Payload: 23.1 C |
|<-----------------+
| |
]]></artwork>
</figure>
<t>The client is removed from the list of observers when it is no
longer interested in the observed resource. The server can determine
the client's continued interest from the client's acknowledgement of
confirmable notifications. If a client wants to receive notifications
after it has been removed from the list of observers, it needs to
register again. The client can determine that it's still on the list
of observers from the fact that it receives notifications. The
protocol includes clear rules for what to do when a client does not
receive a notification for some time, or a server does not receive
acknowledgements.</t>
</section>
<section title="Design Philosophy" anchor="design-philosophy">
<t>The protocol builds on the architectural elements of REST, which
include: a server
that is responsible for the state and representation of the resources
in its namespace, a client that is responsible for keeping the
application state, and the stateless exchange of resource
representations. (A server needs to keep track of the observers
though, similar to how HTTP servers need to keep track of the TCP
connections from their clients.) The protocol enables high
scalability and efficiency through the support of caches and
intermediaries that multiplex the interest of multiple clients in the
same resource into a single association.</t>
<t>The server is the authority for determining under what conditions
resources change their state and how often observers are notified.
The protocol does not offer explicit means for setting up triggers,
thresholds or other conditions; it is up to the server to expose
observable resources that change their state in a way that is
meaningful for the application. Resources can be parameterized to
achieve similar effects though; see <xref
target="modeling-resources"/> for examples.</t>
<t>Since bandwidth is in short supply in constrained environments,
servers must adapt the rate of notifications to each client. This
implies that a client cannot rely on observing every single state a
resource goes through. Instead, the protocol is designed on the
principle of <spanx style="emph">eventual consistency</spanx>: it
guarantees that if the resource does not undergo a new change in
state, eventually all observers will have a current representation of
the last resource state.</t>
</section>
<section title="Conformance Requirements" anchor="conformance">
<t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in <xref target="RFC2119"
>RFC 2119</xref>.</t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="The Observe Option" anchor="option">
<texttable>
<ttcol align="right">No.</ttcol>
<ttcol align="left">C/E</ttcol>
<ttcol align="left">Name</ttcol>
<ttcol align="left">Format</ttcol>
<ttcol align="left">Length</ttcol>
<ttcol align="left">Default</ttcol>
<c>10</c>
<c>Elective</c>
<c>&OPTION1;</c>
<c>uint</c>
<c>0-2 B</c>
<c>(none)</c>
</texttable>
<t>The &OPTION1; 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, but also requests the server
to add the client to the list of observers of the resource. The exact
semantics are defined in the sections below. The value of the option
in a request MUST be zero on transmission and MUST be ignored on
reception.</t>
<t>In a response, the &OPTION1; Option identifies the message as a
notification, which implies that the client has been added to the
list of observers and that the server will notify the client of
further changes to the resource state. The option's value is a
sequence number that can be used for reordering detection (see <xref
target="client-reordering"/> and <xref target="server-reordering"
/>). The value is encoded as a variable-length unsigned integer as defined
in <xref target="I-D.ietf-core-coap">Appendix A of RFC
XXXX</xref>.</t>
<t>Since the &OPTION1; Option is elective, a GET request that includes
the &OPTION1; Option will automatically fall back to a normal GET
request if the server is unwilling or unable to add the client to the
list of observers.</t>
<t>The &OPTION1; Option MUST NOT occur more than once in a request or
response.</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Client-side Requirements" anchor="client">
<section title="Request" anchor="client-request">
<t>A client can register its interest in a resource by issuing a GET
request that includes an empty &OPTION1; Option. If the server
returns a 2.xx response that includes &anOPTION1; Option as well, the
server has added the client successfully to the list of observers of
the target resource and the client will be notified of changes to the
resource state for as long as the server can assume the client's
interest.</t>
</section>
<section title="Notifications" anchor="client-notifications">
<t>Notifications are additional responses sent by the server in reply
to the GET request. Each notification includes &anOPTION1; Option
with a sequence number (see <xref target="client-reordering"/>), a
Token Option that matches the token specified by the client in the
GET request, and a payload of the same media type as the initial
response.</t>
<t>A notification can be confirmable or non-confirmable (i.e. sent in a
confirmable or non-confirmable message). If a client does not
recognize the token in a confirmable notification, it MUST NOT
acknowledge the message and SHOULD reject it with a RST message.
Otherwise, the client MUST acknowledge the message with an ACK
message as usual. If a client does not recognize the token in a
non-confirmable notification, it MAY reject it with a RST
message.</t>
<t>An acknowledgement signals to the server that the client is alive
and interested in receiving further notifications; if the server does
not receive an acknowledgement in reply to a confirmable
notification, it will assume that the client is no longer interested
and will eventually remove it from the list of observers.</t>
<t>Notifications will have a 2.05 (Content) response code in most
cases. They may also have a 2.03 (Valid) response code if the client
includes an ETag Option in its request (see <xref
target="client-caching"/>). In the event that the state of an
observed resource is changed in a way that would cause a normal GET
request to return an error (for example, when the resource is
deleted), the server will send a notification with an error response
code (4.xx/5.xx) and empty the list of observers of the resource.</t>
</section>
<section title="Caching" anchor="client-caching">
<t>As notifications are just additional responses, notifications
partake in caching as defined by <xref target="I-D.ietf-core-coap"
>Section 5.6 of RFC XXXX</xref>. Both the freshness model and the
validation model are supported. The freshness model also serves as
the model for the client to determine if it's still on the list of
observers or if it needs to re-register its interest in the
resource.</t>
<t>A client MAY store a notification like a response in its cache and
use a stored notification/response that is fresh without contacting
the origin server. A notification/response is considered fresh while
its age is not greater than its Max-Age and no newer notification has
been received.</t>
<t>The server will do its best to keep the client up to date with a
fresh representation of the current resource state. It will send a
notification whenever the resource changes, or at latest when the age
of the last notification becomes greater than its Max-Age. (Note that
this notification may not arrive in time due to network latency.)</t>
<t>The client SHOULD assume that it's on the list of observers while the
age of the last notification is not greater than Max-Age. If the
client does not receive a notification before the age becomes greater
than Max-Age, it can assume that it has been removed from the list of
observers (e.g., due to a loss of server state). In this case, it
may need to re-register its interest.</t>
<t>To make sure it has a fresh representation and/or to re-register its
interest, a client MAY issue a new GET request with &anOPTION1;
Option at any time. The GET request SHOULD specify a new token to
avoid ambiguity, because the token serves as epoch identifier for the
sequence numbers in the &OPTION1; Option (see <xref
target="client-reordering"/>).</t>
<t>It is RECOMMENDED that the client does not issue the request while
it still has a fresh notification and, beyond that, while a new
notification from the server is still likely to arrive. I.e. the
client should wait until the age of the last notification becomes
greater than its Max-Age plus the potential retransmission window
(see <xref target="I-D.ietf-core-coap">Section 4.1 of RFC
XXXX</xref>) plus the expected maximum round trip time.</t>
<t>When a client has one or more notifications stored, it can use the
ETag Option in the GET request to give the server an opportunity to
select a stored response to be used. The client MAY include an ETag
Option for each stored response that is applicable. It needs to keep
those responses in the cache until it is no longer interested in
receiving notifications for the target resource or it issues a new
GET request with a new set of entity-tags. Whenever the observed
resource changes its state to a representation identified by one of
the ETag Options, the server can select a stored response by sending
a 2.03 (Valid) notification with an appropriate ETag Option instead
of a 2.05 (Content) notification.</t>
</section>
<section title="Reordering" anchor="client-reordering">
<t>Messages that carry notifications can arrive in a different order
than they were sent. Since the goal is eventual consistency (see
<xref target="design-philosophy"/>), a client can safely skip a
notification that arrives later than a newer notification. For this
purpose, the server sets the value of the &OPTION1; Option in each
notification to a sequence number.</t>
<t>A client MAY treat a notification as outdated (not fresh) under the
following condition:</t>
<figure>
<artwork type="inline" align="center"><![CDATA[
(V1 - V2) % (2**16) < (2**15) and T2 < (T1 + (2**14))
]]></artwork>
</figure>
<t>where V1 is the value of the &OPTION1; Option of the latest valid
notification received, V2 the value of the &OPTION1; Option of the
present notification, T1 a client-local timestamp of the latest valid
notification received (in seconds), and T2 a client-local timestamp
of the present notification.</t>
<t><list style="hanging">
<t hangText="Design Note:">The first condition essentially verifies
that V2 > V1 holds in 16-bit <xref target="RFC1982">sequence
number arithmetic</xref>. The second condition checks that the
time expired between the two incoming messages is not so large
that the sequence number might have wrapped around and the first
check is therefore invalid. (In other words, after about 2**14
seconds elapse without any notification, the client does not need
to check the sequence numbers in order to assume an incoming
notification is new.) The constants of 2**14 and 2**15 are
non-critical, as is the even speed or precision of the clock
involved.</t>
</list></t>
</section>
<section title="Cancellation" anchor="client-cancellation">
<t>When a client rejects a confirmable notification
with a RST message or when it performs a GET request
without &anOPTION1; Option for a currently observed resource, the server will remove the
client from the list of observers for this resource. The client MAY
use either method at any time to indicate that it is no longer
interested in receiving notifications about a resource.</t>
<t>When a client rejects non-confirmable notification with a RST, there
is also a chance that the server will remove the client from the list
of observers for this resource. So the client MAY try this method as
well. A client MAY rate-limit the RST messages it sends if the server
appears to persistently ignore them.</t>
<t><list style="hanging">
<t hangText="Implementation Note:"> A client that does not mediate
all its requests through its cache might inadvertantly cancel an
observation relationship by sending an unrelated GET to the same
resource. To avoid this, without incurring a need for
synchronization, such clients can use a different source
transport address for these unrelated GET requests.</t>
</list></t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Server-side Requirements" anchor="server">
<section title="Request" anchor="server-request">
<t>A GET request that includes &anOPTION1; Option requests the server
not only to return a representation of the resource identified by the
request URI, but also to add the client to the list of observers of
the target resource. If no error occurs, the server MUST return a
response with the representation of the current resource state and
MUST notify the client of subsequent changes to the state as long as
the client is on the list of observers.</t>
<t>A server that is unable or unwilling to add the client to the list
of observers of the target resource MAY silently ignore the &OPTION1;
Option and process the GET request as usual. The resulting response
MUST NOT include &anOPTION1; Option, the absence of which signals to
the client that it will not be notified of changes to the resource
state and, e.g., needs to poll the resource instead.</t>
<t>If the client is already on the list of observers, the server MUST
NOT add it a second time but MUST replace or update the existing
entry. If the server receives a GET request that does not include
&anOPTION1; Option, it MUST remove the client from the list of
observers.</t>
<t>Two requests relate to the same list entry if both the request URI
and the source of the requests match. The source of a request is
determined by the security mode used (see <xref
target="I-D.ietf-core-coap">Section 10 of RFC XXXX</xref>): With
NoSec, it is determined by the source IP address and UDP port number.
With other security modes, the source is also determined by the
security context. Note that Message IDs and Token Options MUST NOT be
taken into account.</t>
<t>Any request with a method other than GET MUST NOT have a direct
effect on a list of observers of a resource. However, such a request
can have the indirect consequence of causing the server to send an
error notification which does affect the list of observers (e.g.,
when a DELETE request is successful and an observed resource no
longer exists).</t>
</section>
<section title="Notifications" anchor="server-notifications">
<t>A client is notified of a resource state change by an additional
response sent by the server in reply to the GET request. Each such
notification response MUST include &anOPTION1; Option and MUST echo
the token specified by the client in the GET request. If there are
multiple clients on the list of observers, the order in which they
are notified is not defined; the server is free to use any method to
determine the order.</t>
<t>A notification SHOULD have a 2.05 (Content) or 2.03 (Valid) response
code. However, in the event that the state of a resource changes in a
way that would cause a normal GET request to return an error (for
example, if the resource is deleted), the server SHOULD notify the
client by sending a notification with an appropriate error response
code (4.xx/5.xx) and MUST empty the list of observers of the
resource.</t>
<t>The media type used in a notification MUST be the same as the one
used in the initial response to the GET request. If the server is
unable to continue sending notifications using this media type, it
SHOULD send a 5.00 (Internal Server Error) notification and MUST
empty the list of observers of the resource.</t>
<t>A notification can be sent as a confirmable or a non-confirmable
message. The message type used is typically application-dependent and
MAY be determined by the server for each notification individually.
For example, for resources that change in a somewhat predictable or
regular fashion, notifications can be sent in non-confirmable
messages; for resources that change infrequently, notifications can
be sent in confirmable messages. The server can combine these two
approaches depending on the frequency of state changes and the
importance of individual notifications.</t>
<t>The acknowledgement of a confirmable notification implies the
client's continued interest in being notified. If the client rejects
a confirmable notification with a RST message, the server MUST remove
the client from the list of observers. If the client rejects a
non-confirmable notification with a RST message, the server MAY
remove the client from the list of observers.</t>
</section>
<section title="Caching" anchor="server-caching">
<t>The Max-Age Option of a notification SHOULD be set to a value that
indicates when the server will send the next notification. For
example, if the server sends a notification every 30 seconds, a
Max-Age Option with value 30 should be included. The server MAY send
a new notification before Max-Age ends and MUST send a new
notification at latest when Max-Age ends. If the client does not
receive a new notification before Max-Age ends, it will assume that
it was removed from the list of observers (e.g., due to a loss of
server state) and may issue a new GET request to re-register its
interest.</t>
<t>It may not always be possible to predict when the server will send
the next notification, for example, when a resource does not change
its state in regular intervals. In this case, the server SHOULD set
Max-Age to a good approximation. The value is a trade-off between
increased usage of bandwidth and the risk of stale information.
Smaller values lead to more notifications and more GET requests,
while greater values result in network or device failures being
detected later and data becoming stale.</t>
<t>The client can include a set of entity-tags in its request using
the ETag Option.
When the observed resource changes its state and the origin server
is about to send a 2.05 (Content) notification, then, whenever that
notification has an entity-tag in the set of entity-tags specified by
the client, the server MAY send a 2.03 (Valid) response with an appropriate
ETag Option instead. The server MUST NOT assume that the recipient
has any response stored other than those identified by the
entity-tags in the most recent GET request for the resource.</t>
</section>
<section title="Reordering" anchor="server-reordering">
<t>Because messages can get reordered, the client needs a way to
determine if a notification arrived later than a newer notification.
For this purpose, the server MUST set the value of the &OPTION1;
Option in each notification to the 16 least-significant bits of a
strictly increasing sequence number. The sequence number MAY start at
any value. The server MUST NOT reuse the same option value with the
same client, token and resource within approximately 2**16 seconds
(roughly 18.2 hours).</t>
<t><list style="hanging">
<t hangText="Implementation Note:">A simple implementation that
satisfies the requirements is to use a timestamp (in seconds)
provided by the device's clock, or a 16-bit unsigned integer
variable that is incremented every second and wraps around every
2**16 seconds. It is not necessary that the clock reflects the
correct local time or that it ticks exactly every second. Note
that, on average, a server cannot send more than one notification
per second per client, token and resource.</t>
</list></t>
</section>
<section title="Retransmission" anchor="server-retransmission">
<t>In CoAP, confirmable messages are retransmitted in exponentially
increasing intervals for a certain number of attempts until they are
acknowledged by the client. In the context of observing a resource,
it is undesirable to continue transmitting the representation of a
resource state when the state has changed in the meantime.</t>
<t>When a server is in the process of delivering a confirmable
notification and is waiting for an acknowledgement, and it wants to
notify the client of a state change using a new confirmable message,
it MUST stop retransmitting the old notification and SHOULD attempt
to deliver the new notification with the number of attempts remaining
from the old notification. When the last attempt to retransmit a
confirmable message with a notification for a resource times out, the
server SHOULD remove the client from the list of observers and MAY
additionally remove the client from the lists of observers of all
resources in its namespace.</t>
<t>The server SHOULD use a number of retransmit attempts
(MAX_RETRANSMIT) such that removing a client from the list of
observers before Max-Age ends is avoided.</t>
<t>A server MAY choose to skip a notification if it knows that it will
send another notification soon (e.g., when the state is changing
frequently). Similarly, it MAY choose to send a notification more
than once. For example, when state changes occur in bursts, the
server can skip some notifications, send the notifications in
non-confirmable messages, and make sure that the client observes the
latest state change after the burst by repeating the last
notification in a confirmable message.</t>
</section>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Intermediaries" anchor="intermediary">
<t>A client may be interested in a resource in the namespace of an origin
server that is reached through one or more CoAP-to-CoAP intermediaries.
In this case, the client registers its interest with the first
intermediary towards the origin server, acting as if it was
communicating with the origin server itself as specified in <xref
target="client"/>. It is the task of this intermediary to provide the
client with a current representation of the target resource and send
notifications upon changes to the target resource state, much like an
origin server as specified in <xref target="server"/>.</t>
<t>To perform this task, the intermediary SHOULD make use of the protocol
specified in this document, taking the role of the client and
registering its own interest in the target resource with the next hop.
If the next hop does not return a response with &anOPTION1; Option, the
intermediary MAY resort to polling the next hop, or MAY itself return a
response without &anOPTION1; Option. Note that the communication
between each pair of hops is independent, i.e. each hop in the server
role MUST determine individually how many notifications to send, of
which type, and so on. Each hop MUST generate its own values for the &OPTION1;
Option, and MUST set the value of the Max-Age Option according to the
age of the local current representation.</t>
<t>Because a client (or an intermediary in the client role) can only be
once in the list of observers of a resource at a server (or an
intermediary in the server role) — it is useless to
observe the same resource multiple times — an intermediary MUST
observe a resource only once, even if there are multiple clients for
which it observes the resource.</t>
<t>Note that an intermediary is not required to have a client to observe
a resource; an intermediary MAY observe a resource, for instance, just
to keep its own cache up to date.</t>
<t>See <xref target="examples-proxying"/> for examples.</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Block-wise Transfers" anchor="block">
<t>Resources observed by clients may be larger than can be comfortably
processed or transferred in one CoAP message. CoAP provides a
block-wise transfer mechanism to address this problem <xref
target="I-D.ietf-core-block"/>. The following rules apply to the
combination of block-wise transfers with notifications.</t>
<t>As with basic GET transfers, the client can indicate its desired block
size in a Block2 Option in the GET request. If the server supports
block-wise transfers, it SHOULD take note of the block size for all
notifications/responses resulting from the GET request (until the
client is removed from the list of observers or the server receives a
new GET request from the client).</t>
<t>When sending a 2.05 (Content) notification, the server always sends
all blocks of the representation, suitably sequenced by its congestion
control mechanism, even if only some of the blocks have changed with
respect to a previous value. The server performs the block-wise
transfer by making use of the Block2 Option in each block. When
reassembling representations that are transmitted in multiple blocks,
the client MUST NOT combine blocks carrying different &OPTION1; Option
values, or blocks that have been received more than approximately 2**14
seconds apart.</t>
<t>See <xref target="examples-block"/> for an example.</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Discovery" anchor="discovery">
<t>A <xref target="RFC5988">web link</xref> to a resource accessible by
the CoAP protocol MAY indicate that the server encourages the
observation of this resource by including the target attribute "obs".
This is particularly useful in <xref target="I-D.ietf-core-link-format"
>link-format documents</xref>.</t>
<t>This target attribute is used as a flag, and thus it has no value
component — a value given for the attribute MUST NOT be given for
this version of the specification and MUST be ignored if present. The
target attribute "obs" MUST NOT be given more than once for this
version of the specification. </t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Security Considerations" anchor="security">
<t>The security considerations of <xref target="I-D.ietf-core-coap"
>RFC XXXX</xref> apply.</t>
<t>Note that the considerations about amplification attacks are somewhat
amplified when observing resources. In NoSec mode, a server MUST
therefore strictly limit the number of notifications that it sends
between receiving acknowledgements that confirm the actual interest of
the client in the data; i.e., any notifications sent in non-confirmable
messages MUST be interspersed with confirmable messages. (An attacker
may still spoof the acknowledgements if the confirmable messages are
sufficiently predictable.)</t>
<t>As with any protocol that creates state, attackers may attempt to
exhaust the resources that the server has available for maintaining the
list of observers for each resource. Servers MAY want to access-control
this creation of state. As degraded behavior, the server can always
fall back to processing the request as a normal GET request (without
&anOPTION1; Option) if it is unwilling or unable to add a client to the
list of observers of a resource, including if system resources are
exhausted or nearing exhaustion.</t>
<t>Intermediaries MUST be careful to ensure that notifications cannot be
employed to create a loop. A simple way to break any loops is to employ
caches for forwarding notifications in intermediaries.</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="IANA Considerations" anchor="iana-considerations">
<t>The following entries are added to the CoAP Option Numbers
registry:</t>
<texttable>
<ttcol align="right">Number</ttcol>
<ttcol align="left">Name</ttcol>
<ttcol align="left">Reference</ttcol>
<c>10</c>
<c>&OPTION1;</c>
<c>&SELF;</c>
</texttable>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Acknowledgements" anchor="acknowledgements">
<t>Carsten Bormann was an original author of this draft and is
acknowledged for significant contribution to this document.</t>
<t>Thanks to Daniele Alessandrelli, Jari Arkko, Peter Bigot, Angelo
Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank,
Cullen Jennings, Matthias Kovatsch, Salvatore Loreto, Charles Palmer
and Zach Shelby for helpful comments and discussions that have shaped
the document.</t>
<t>Klaus Hartke was funded by the Klaus Tschira Foundation.</t>
</section>
</middle>
<back>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<references title="Normative References">
&RFC2119;
&RFC5988;
&I-D.ietf-core-coap;
&I-D.ietf-core-block;
</references>
<references title="Informative References">
&RFC1982;
&RFC2616;
&RFC5989;
&RFC6202;
&I-D.ietf-core-link-format;
<reference anchor="REST" target="http://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm">
<front>
<title>Architectural Styles and the Design of Network-based Software Architectures</title>
<author initials="R." surname="Fielding" fullname="Roy Fielding">
<organization>University of California, Irvine</organization>
</author>
<date year="2000" />
</front>
</reference>
<reference anchor="GOF">
<front>
<title>Design Patterns: Elements of Reusable Object-Oriented Software</title>
<author initials="E." surname="Gamma" fullname="Erich Gamma">
<organization/>
</author>
<author initials="R." surname="Helm" fullname="Richard Helm">
<organization/>
</author>
<author initials="R." surname="Johnson" fullname="Ralph Johnson">
<organization/>
</author>
<author initials="J." surname="Vlissides" fullname="John M. Vlissides">
<organization/>
</author>
<date year="1994" month="November"/>
</front>
<seriesInfo name="Addison-Wesley," value="Reading, MA, USA"/>
</reference>
</references>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Examples" anchor="examples">
<figure anchor="example-1" title="A client registers and receives a notification of the current state and upon a state change">
<artwork type="example"><![CDATA[
Observed CLIENT SERVER Actual
t State | | State
____________ | | ____________
1 | |
2 unknown | | 18.5 C
3 +----->| Header: GET 0x43011633
4 | GET | Token: 0x4a
5 | | Uri-Path: temperature
6 | | Observe: 0
7 | |
8 | |
9 ____________ |<-----+ Header: 2.05 0x63451633
10 | 2.05 | Token: 0x4a
11 18.5 C | | Observe: 9
12 | | Max-Age: 15
13 | | Payload: "18.5 C"
14 | |
15 | | ____________
16 ____________ |<-----+ Header: 2.05 0x53457b50
17 | 2.05 | 19.2 C Token: 0x4a
18 19.2 C | | Observe: 16
29 | | Max-Age: 15
20 | | Payload: "19.2 C"
21 | |
]]></artwork>
</figure>
<figure anchor="example-2" title="The client re-registers after Max-Age ends">
<artwork type="example"><![CDATA[
Observed CLIENT SERVER Actual
t State | | State
____________ | | ____________
22 | |
23 19.2 C | | 19.2 C
24 | | ____________
25 | X----+ Header: 2.05 0x53457b51
26 | 2.05 | 19.7 C Token: 0x4a
27 | | Observe: 25
28 | | Max-Age: 15
29 | | Payload: "19.7 C"
30 | |
31 ____________ | |
32 +----->| Header: GET 0x43011633
33 19.2 C | GET | Token: 0xb2
34 (stale) | | Uri-Path: temperature
35 | | Observe: 0
36 | |
37 | |
38 ____________ |<-----+ Header: 2.05 0x54457b52
39 | 2.05 | Token: 0xb2
40 19.7 C | | Observe: 38
41 | | Max-Age: 15
42 | | ETag: 0x78797a7a79
43 | | Payload: "19.7 C"
44 | |
]]></artwork>
</figure>
<figure anchor="example-3" title="The client re-registers and gives the server the opportunity to select a stored response">
<artwork type="example"><![CDATA[
Observed CLIENT SERVER Actual
t State | | State
____________ | | ____________
45 | |
46 19.7 C | | 19.7 C
47 | |
48 | | ____________
49 | CRASH
50 |
51 |
52 | |
53 ____________ | | ____________
54 +----->| Header: GET 0x44011634
55 19.7 C | GET | 20.0 C Token: 0xf9
56 (stale) | | Uri-Path: temperature
57 | | Observe: 0
58 | | ETag: 0x78797a7a79
59 | |
60 | |
61 ____________ |<-----+ Header: 2.05 0x63451634
62 | 2.05 | Token: 0xf9
63 20.0 C | | Observe: 61
64 | | Max-Age: 15
65 | | Payload: "20.0 C"
66 | |
67 | | ____________
68 ____________ |<-----+ Header: 2.03 0x5443aa0c
69 | 2.03 | 19.7 C Token: 0xf9
70 19.7 C | | Observe: 68
71 | | ETag: 0x78797a7a79
72 | | Max-Age: 15
73 | |
]]></artwork>
</figure>
<section title="Proxying" anchor="examples-proxying">
<figure anchor="example-5" title="A proxy observes a resource to keep its cache up to date">
<artwork type="example"><![CDATA[
CLIENT PROXY SERVER
| | |
| +----->| Header: GET 0x44015fb8
| | GET | Token: 0x1a
| | | Uri-Host: sensor.example
| | | Uri-Path: status
| | | Observe: 0
| | |
| |<-----+ Header: 2.05 0x63455fb8
| | 2.05 | Token: 0x1a
| | | Observe: 42
| | | Max-Age: 60
| | | Payload: "ready"
| | |
+----->| | Header: GET 0x42011633
| GET | | Token: 0x9a
| | | Proxy-Uri: coap://sensor.example/status
| | |
|<-----+ | Header: 2.05 0x62451633
| 2.05 | | Token: 0x9a
| | | Max-Age: 53
| | | Payload: "ready"
| | |
| |<-----+ Header: 2.05 0x534505fc0
| | 2.05 | Token: 0x1a
| | | Observe: 135
| | | Max-Age: 60
| | | Payload: "busy"
| | |
+----->| | Header: GET 0x42011634
| GET | | Token: 0x9b
| | | Proxy-Uri: coap://sensor.example/status
| | |
|<-----+ | Header: 2.05 0x62451634
| 2.05 | | Token: 0x9b
| | | Max-Age: 49
| | | Payload: "busy"
| | |
]]></artwork>
</figure>
<figure anchor="example-6" title="A client observes a resource through a proxy">
<artwork type="example"><![CDATA[
CLIENT PROXY SERVER
| | |
+----->| | Header: GET 0x43011635
| GET | | Token: 0x6a
| | | Proxy-Uri: coap://sensor.example/status
| | | Observe: 0
| | |
|<- - -+ | Header: 0x60001635
| | |
| +----->| Header: GET 0x4401af90
| | GET | Token: 0xaa
| | | Uri-Host: sensor.example
| | | Uri-Path: status
| | | Observe: 0
| | |
| |<-----+ Header: 2.05 0x6345af90
| | 2.05 | Token: 0xaa
| | | Observe: 67
| | | Max-Age: 60
| | | Payload: "ready"
| | |
|<-----+ | Header: 2.05 0x4345af94
| 2.05 | | Token: 0x6a
| | | Observe: 17346
| | | Max-Age: 60
| | | Payload: "ready"
| | |
+- - ->| | Header: 0x6000af94
| | |
| |<-----+ Header: 2.05 0x53455a20
| | 2.05 | Token: 0xaa
| | | Observe: 157
| | | Max-Age: 60
| | | Payload: "busy"
| | |
|<-----+ | Header: 2.05 0x5345af9b
| 2.05 | | Token: 0x6a
| | | Observe: 17436
| | | Max-Age: 60
| | | Payload: "busy"
| | |
]]></artwork>
</figure>
</section>
<section title="Block-wise Transfer" anchor="examples-block">
<figure anchor="example-7" title="A server sends two notifications of two blocks each">
<artwork type="example"><![CDATA[
CLIENT SERVER
| |
+----->| Header: GET 0x43011636
| GET | Token: 0xfb
| | Uri-Path: status-icon
| | Observe: 0
| |
|<-----+ Header: 2.05 0x64451636
| 2.05 | Token: 0xfb
| | Block2: 0/1/128
| | Observe: 62354
| | Max-Age: 60
| | Payload: [128 bytes]
| |
|<-----+ Header: 2.05 0x5445af9c
| 2.05 | Token: 0xfb
| | Block2: 1/0/128
| | Observe: 62354
| | Max-Age: 60
| | Payload: [27 bytes]
| |
|<-----+ Header: 2.05 0x5445af9d
| 2.05 | Token: 0xfb
| | Block2: 0/1/128
| | Observe: 62444
| | Max-Age: 60
| | Payload: [128 bytes]
| |
|<-----+ Header: 2.05 0x5445af9e
| 2.05 | Token: 0xfb
| | Block2: 1/0/128
| | Observe: 62444
| | Max-Age: 60
| | Payload: [27 bytes]
| |
]]></artwork>
</figure>
</section>
</section>
<section title="Modeling Resources to Tailor Notifications" anchor="modeling-resources">
<t>A server may want to provide notifications that respond to very
specific conditions on some state. This is best done by modeling the
resources that the server exposes according to these needs.</t>
<t>For example, for a CoAP server with an attached temperature
sensor,<list style="symbols">
<t>the server could, in the simplest form, expose a resource
<coap://server/temperature> that changes its state every
second to the current temperature measured by the sensor;</t>
<t>the server could, however, also expose a resource
<coap://server/temperature/felt> that changes its state to
"cold" when the temperature drops below a preconfigured threshold,
and to "warm" when the temperature exceeds a second, higher
threshold;</t>
<t>the server could expose a parameterized resource
<coap://server/temperature/critical?above=45> that changes
its state to the current temperature if the temperature exceeds the
specified value, and changes its state to "OK" when the temperature
drops below; or</t>
<t>the server could expose a parameterized resource
<coap://server/temperature?query=select+avg(temperature)+from+Sensor.window:time(30sec)>
that accepts expressions of arbitrary complexity and changes its
state accordingly.</t>
</list></t>
<t>In any case, the client is notified about the current state of the
resource whenever the state of the appropriately modeled resource
changes. By designing resources that change their state on certain
conditions, it is possible to notify the client only when these
conditions occur instead of continuously supplying it with information
it doesn't need. With parametrized resources, this is not limited to
conditions defined by the server, but can be extended to arbitrarily
complex conditions defined by the client. Thus, the server designer can
choose exactly the right level of complexity for the application
envisioned and devices used, and is not constrained to a "one size fits
all" mechanism built into the protocol.</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<section title="Changelog" anchor="changelog">
<t>Changes from ietf-04 to ietf-05:
<list style="symbols">
<t>Recommended that a client does not re-register while a new
notification from the server is still likely to arrive. This is to
avoid that the request of the client and the last notification
after max-age cross over each other (#174).</t>
<t>Relaxed requirements when sending RST in reply to non-confirmable
notifications.</t>
<t>Added an implementation note about careless GETs (#184).</t>
<t>Updated examples.</t>
</list>
</t>
<t>Changes from ietf-03 to ietf-04:
<list style="symbols">
<t>Removed the "Max-OFE" Option.</t>
<t>Allowed RST in reply to non-confirmable notifications.</t>
<t>Added a section on cancellation.</t>
<t>Updated examples.</t>
</list>
</t>
<t>Changes from ietf-02 to ietf-03:
<list style="symbols">
<t>Separated client-side and server-side requirements.</t>
<t>Fixed uncertainty if client is still on the list of observers by
introducing a liveliness model based on Max-Age and a new option
called "Max-OFE" (#174).</t>
<t>Simplified the text on message reordering (#129).</t>
<t>Clarified requirements for intermediaries.</t>
<t>Clarified the combination of block-wise transfers with
notifications (#172).</t>
<t>Updated examples to show how the state observed by the client
becomes eventually consistent with the actual state on the
server.</t>
<t>Added examples for parameterization of observable resource.</t>
</list>
</t>
<t>Changes from ietf-01 to ietf-02:
<list style="symbols">
<t>Removed the requirement of periodic refreshing (#126).</t>
<t>The new "Observe" Option replaces the "Lifetime" Option.</t>
<t>Introduced a new mechanism to detect message reordering.</t>
<t>Changed 2.00 (OK) notifications to 2.05 (Content)
notifications.</t>
</list>
</t>
<t>Changes from ietf-00 to ietf-01:
<list style="symbols">
<t>Changed terminology from "subscriptions" to "observation
relationships" (#33).</t>
<t>Changed the name of the option to "Lifetime".</t>
<t>Clarified establishment of observation relationships.</t>
<t>Clarified that an observation is only identified by the URI of the
observed resource and the identity of the client (#66).</t>
<t>Clarified rules for establishing observation relationships
(#68).</t>
<t>Clarified conditions under which an observation relationship is
terminated.</t>
<t>Added explanation on how clients can terminate an observation
relationship before the lifetime ends (#34).</t>
<t>Clarified that the overriding objective for notifications is
eventual consistency of the actual and the observed state
(#67).</t>
<t>Specified how a server needs to deal with clients not
acknowledging confirmable messages carrying notifications
(#69).</t>
<t>Added a mechanism to detect message reordering (#35).</t>
<t>Added an explanation of how notifications can be cached,
supporting both the freshness and the validation model (#39,
#64).</t>
<t>Clarified that non-GET requests do not affect observation
relationships, and that GET requests without "Lifetime" Option
affecting relationships is by design (#65).</t>
<t>Described interaction with block-wise transfers (#36).</t>
<t>Added Resource Discovery section (#99).</t>
<t>Added IANA Considerations.</t>
<t>Added Security Considerations (#40).</t>
<t>Added examples (#38).</t>
</list>
</t>
</section>
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
<!-- **************************************************************** -->
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 03:04:39 |