CoRE Working Group
Internet Engineering Task Force (IETF)                         K. Hartke
Internet-Draft
Request for Comments: 7641                       Universitaet Bremen TZI
Intended status:
Category: Standards Track                       December 30, 2014
Expires: July 3,                                 September 2015
ISSN: 2070-1721

   Observing Resources in CoAP
                       draft-ietf-core-observe-16 the Constrained Application Protocol (CoAP)

Abstract

   The Constrained Application Protocol (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 enables CoAP clients to
   "observe" resources, i.e., to retrieve a representation of a resource
   and keep this representation updated by the server over a period of
   time.  The protocol follows a best-effort approach for sending new
   representations to clients and provides eventual consistency between
   the state observed by each client and the actual resource state at
   the server.

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 an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list  It represents the consensus of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid the IETF community.  It has
   received public review and has been approved for a maximum publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 5741.

   Information about the current status of six months this document, any errata,
   and how to provide feedback on it may be updated, replaced, or obsoleted by other documents obtained 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 July 3, 2015.
   http://www.rfc-editor.org/info/rfc7641.

Copyright Notice

   Copyright (c) 2014 2015 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.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .  3  4
     1.1.  Background  . . . . . . . . . . . . . . . . . . . . . . . .  3  4
     1.2.  Protocol Overview . . . . . . . . . . . . . . . . . . . .  3  4
     1.3.  Consistency Model . . . . . . . . . . . . . . . . . . . .  5  6
     1.4.  Observable Resources  . . . . . . . . . . . . . . . . . . .  6  7
     1.5.  Requirements Notation . . . . . . . . . . . . . . . . . .  7  8
   2.  The Observe Option  . . . . . . . . . . . . . . . . . . . . . .  7  8
   3.  Client-side  Client-Side Requirements  . . . . . . . . . . . . . . . . . . .  8  9
     3.1.  Request . . . . . . . . . . . . . . . . . . . . . . . . .  8  9
     3.2.  Notifications . . . . . . . . . . . . . . . . . . . . . .  8 10
     3.3.  Caching . . . . . . . . . . . . . . . . . . . . . . . . .  9 10
     3.4.  Reordering  . . . . . . . . . . . . . . . . . . . . . . . . 10 11
     3.5.  Transmission  . . . . . . . . . . . . . . . . . . . . . . . 11 12
     3.6.  Cancellation  . . . . . . . . . . . . . . . . . . . . . . . 11 13
   4.  Server-side  Server-Side Requirements  . . . . . . . . . . . . . . . . . . . 12 13
     4.1.  Request . . . . . . . . . . . . . . . . . . . . . . . . . 12 13
     4.2.  Notifications . . . . . . . . . . . . . . . . . . . . . . 13 14
     4.3.  Caching . . . . . . . . . . . . . . . . . . . . . . . . . 13 14
     4.4.  Reordering  . . . . . . . . . . . . . . . . . . . . . . . . 14 15
     4.5.  Transmission  . . . . . . . . . . . . . . . . . . . . . . . 15 16
   5.  Intermediaries  . . . . . . . . . . . . . . . . . . . . . . . . 18 19
   6.  Web Linking . . . . . . . . . . . . . . . . . . . . . . . . . 19 20
   7.  Security Considerations . . . . . . . . . . . . . . . . . . . 19 20
   8.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 21
   9.  Acknowledgements . .  References  . . . . . . . . . . . . . . . . . . . . . 20
   10. References . . . . 22
     9.1.  Normative References  . . . . . . . . . . . . . . . . . . 22
     9.2.  Informative References  . . . . 21
     10.1. Normative References . . . . . . . . . . . . . 22
   Appendix A.  Examples . . . . . . 21
     10.2. Informative References . . . . . . . . . . . . . . . . 24
     A.1.  Client/Server Examples  . . 21
   Appendix A.  Examples . . . . . . . . . . . . . . . 24
     A.2.  Proxy Examples  . . . . . . . 22
     A.1.  Client/Server Examples . . . . . . . . . . . . . . 28
   Acknowledgements  . . . . 22
     A.2.  Proxy Examples . . . . . . . . . . . . . . . . . . . . 30
   Author's Address  . . 26
   Appendix B.  Changelog . . . . . . . . . . . . . . . . . . . . . . 28 30

1.  Introduction

1.1.  Background

   The Constrained Application Protocol (CoAP) [RFC7252] is intended to
   provide RESTful services [REST] not unlike HTTP [RFC7230] 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 [RFC7228].

   The model of REST is that of a client exchanging representations of
   resources with a server, where a representation captures the current
   or intended state of a resource.  The server is the authority for
   representations of the resources in its namespace.  A client
   interested in the state of a resource initiates a request to the
   server,
   server; the server then returns a response with a representation of
   the resource that is current at the time of the request.

   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 from HTTP, such as repeated polling or HTTP long polling
   [RFC6202], generate significant complexity and/or overhead and thus
   are less applicable in a constrained environment.

   The protocol specified in this document extends the CoAP core
   protocol with a mechanism for a CoAP client to "observe" a resource
   on a CoAP server: the client retrieves a representation of the
   resource and requests this representation be updated by the server
   as long as the client is interested in the resource.

   The protocol keeps the architectural properties of REST.  It enables
   high scalability and efficiency through the support of caches and
   proxies.  There is no intention, though, to solve the full set of
   problems that the existing HTTP solutions solve, solve or to replace
   publish/subscribe networks that solve a much more general problem
   [RFC5989].

1.2.  Protocol Overview

   The protocol is based on the well-known observer design pattern
   [GOF].  In this design pattern, components called "observers"
   register at a specific, known provider called the "subject" 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
   to an observer, the observer must register separately for all of
   them.

                       Observer             Subject
                          |                    |
                          |    Registration    |
                          +------------------->|
                          |                    |
                          |    Notification    |
                          |<-------------------+
                          |                    |
                          |    Notification    |
                          |<-------------------+
                          |                    |
                          |    Notification    |
                          |<-------------------+
                          |                    |

                   Figure 1: The Observer Design Pattern

   The observer design pattern is realized in CoAP as follows:

   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.

   Observer:  An observer is a CoAP client that is interested in having
      a current representation of the resource at any given time.

   Registration:  A client registers its interest in a resource by
      initiating 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.

   Notification:  Whenever the state of a resource changes, the server
      notifies each client in the list of observers of the resource.
      Each notification is an additional CoAP response sent by the
      server in reply to the single extended GET request, request and includes a
      complete, updated representation of the new resource state.

   Figure 2 below shows an example of a CoAP client registering its
   interest in a resource and receiving three notifications: the first
   with the current state upon registration, and then two upon changes
   to the resource state.  Both the registration request and the
   notifications are identified as such by the presence of the Observe
   Option defined in this document.  In notifications, the Observe
   Option additionally provides a sequence number for reordering
   detection.  All notifications carry the token specified by the
   client, so the client can easily correlate them to the request.

                       Client                Server
                          |                    |
                          |  GET /temperature  |
                          |    Token: 0x4a     |   Registration
                          |  Observe: 0        |
                          +------------------->|
                          |                    |
                          |    2.05 Content    |
                          |    Token: 0x4a     |   Notification of
                          |  Observe: 12       |   the current state
                          |  Payload: 22.9 Cel |
                          |<-------------------+
                          |                    |
                          |    2.05 Content    |
                          |    Token: 0x4a     |   Notification upon
                          |  Observe: 44       |   a state change
                          |  Payload: 22.8 Cel |
                          |<-------------------+
                          |                    |
                          |    2.05 Content    |
                          |    Token: 0x4a     |   Notification upon
                          |  Observe: 60       |   a state change
                          |  Payload: 23.1 Cel |
                          |<-------------------+
                          |                    |

                  Figure 2: Observing a Resource in CoAP

   Note: In this document, "Cel" stands for "degrees Celsius".

   A client remains on the list of observers as long as the server can
   determine the client's continued interest in the resource.  The
   server may send a notification in a confirmable CoAP message to
   request an acknowledgement from the client.  When the client
   deregisters, rejects a notification, or the transmission of a
   notification times out after several transmission attempts, the
   client is considered no longer interested in the resource and is
   removed by the server from the list of observers.

1.3.  Consistency Model

   While a client is in the list of observers of a resource, the goal of
   the protocol is to keep the resource state observed by the client as
   closely in sync with the actual state at the server as possible.

   It cannot be avoided that the client and the server become out of
   sync at times: First, there is always some latency between the change
   of the resource state and the receipt of the notification.  Second,
   CoAP messages with notifications can get lost, which will cause the
   client to assume an old state until it receives a new notification.
   And third, the server may erroneously come to the conclusion that the
   client is no longer interested in the resource, which will cause the
   server to stop sending notifications and the client to assume an old
   state until it eventually registers its interest again.

   The protocol addresses this issue as follows:

   o  It follows a best-effort approach for sending the current
      representation to the client after a state change: Clients clients should
      see the new state after a state change as soon as possible, and
      they should see as many states as possible.  This is limited by
      congestion control, however, so a client cannot rely on observing
      every single state that a resource might go through.

   o  It labels notifications with a maximum duration up to which it is
      acceptable for the observed state and the actual state to be out
      of sync.  When the age of the notification received reaches this
      limit, the client cannot use the enclosed representation until it
      receives a new notification.

   o  It is designed on the principle of eventual consistency: The the
      protocol guarantees that, that if the resource does not undergo a new
      change in state, eventually all registered observers will have a
      current representation of the latest resource state.

1.4.  Observable Resources

   A CoAP server is the authority for determining under what conditions
   resources change their state and thus when observers are notified of
   new resource states.  The protocol does not offer explicit means for
   setting up triggers or thresholds; it is up to the server to expose
   observable resources that change their state in a way that is useful
   in the application context.

   For example, a CoAP server with an attached temperature sensor could
   expose one or more of the following resources:

   o  <coap://server/temperature>, which changes its state every few
      seconds to a current reading of the temperature sensor;

   o  <coap://server/temperature/felt>, which changes its state to
      "COLD" whenever the temperature reading drops below a certain pre-
      configured threshold, threshold and to "WARM" whenever the reading exceeds a
      second, slightly higher threshold;
   o  <coap://server/temperature/critical?above=42>, which changes its
      state based on the client-specified parameter value: value either every
      few seconds to the current temperature reading if the temperature
      exceeds the threshold, threshold or to "OK" when the reading drops below;

   o  <coap://server/?query=select+avg(temperature)+from+Sensor.window:
      time(30sec)>, which accepts expressions of arbitrary complexity
      and changes its state accordingly.

   Thus, by designing CoAP resources that change their state on certain
   conditions, it is possible to update the client only when these
   conditions occur instead of supplying it continuously with raw sensor
   data.  By parameterizing resources, this is not limited to conditions
   defined by the server, but can be extended to arbitrarily complex
   queries specified by the client.  The application designer therefore
   can choose exactly the right level of complexity for the application
   envisioned and devices involved, involved and is not constrained to a "one size
   fits all" mechanism built into the protocol.

1.5.  Requirements Notation

   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 RFC 2119 [RFC2119].

2.  The Observe Option

   The Observe Option has the following properties.  Its meaning depends
   on whether it is included in a GET request or in a response.

       +-----+---+---+---+---+---------+--------+--------+---------+
       | No. | C | U | N | R | Name    | Format | Length | Default |
       +-----+---+---+---+---+---------+--------+--------+---------+
       |   6 |   | x | - |   | Observe | uint   | 0-3 B  | (none)  |
       +-----+---+---+---+---+---------+--------+--------+---------+

            C=Critical, U=Unsafe, N=No-Cache-Key, R=Repeatable

                        Table 1: The Observe Option

   When included in a GET request, the Observe Option extends the GET
   method so it does not only retrieve a current representation of the
   target resource, but also requests the server to add or remove an
   entry in the list of observers of the resource, resource depending on the
   option value.  The list entry consists of the client endpoint and the
   token specified by the client in the request.  Possible values are:

      0 (register) adds the entry to the list, if not present;

      1 (deregister) removes the entry from the list, if present.

   The Observe Option is not critical for processing the request.  If
   the server is unwilling or unable to add a new entry to the list of
   observers, then the request falls back to a normal GET request, request and
   the response does not include the Observe Option.

   The Observe Option is not part of the cache-key: Cache-Key: a cacheable response
   obtained with an Observe Option in the request can be used to satisfy
   a request without an Observe Option, and vice versa.  When a stored
   response with an Observe Option is used to satisfy a normal GET
   request, the option MUST be removed before the response is returned.

   When included in a response, the Observe Option identifies the
   message as a notification.  This implies that a matching entry exists
   in the list of observers and that the server will notify the client
   of changes to the resource state.  The option value is a sequence
   number for reordering detection (see Section Sections 3.4 and Section 4.4).

   The value of the Observe Option is encoded as an unsigned integer in
   network byte order using a variable number of bytes ('uint' option
   format); see Section 3.2 of RFC 7252 [RFC7252].

3.  Client-side  Client-Side Requirements

3.1.  Request

   A client registers its interest in a resource by issuing a GET
   request with an Observe Option set to 0 (register).  If the server
   returns a 2.xx response that includes an Observe Option as well, the
   server has successfully added an entry with the client endpoint and
   request token to the list of observers of the target resource resource, and
   the client will be notified of changes to the resource state.

   Like a fresh response can be used to satisfy a request without
   contacting the server, the stream of updates resulting from one
   observation request can be used to satisfy another (observation or
   normal GET) request if the target resource is the same.  A client
   MUST aggregate such requests and MUST NOT register more than once for
   the same target resource.  The target resource is identified by all
   options in the request that are part of the cache-key. Cache-Key. This includes,
   for example, the full request URI and the Accept Option.

3.2.  Notifications

   Notifications are additional responses sent by the server in reply to
   the single extended GET request that created the registration.  Each
   notification includes the token specified by the client in the
   request.  The only difference between a notification and a normal
   response is the presence of the Observe Option.

   Notifications typically have a 2.05 (Content) response code.  They
   include an Observe Option with a sequence number for reordering
   detection (see Section 3.4), 3.4) and a payload in the same Content-Format
   as the initial response.  If the client included one or more ETag
   Options in the GET request (see Section 3.3), notifications can have
   a 2.03 (Valid) response code rather than a 2.05 (Content) response
   code.  Such notifications include an Observe Option with a sequence
   number but no payload.

   In the event that the resource changes in a way that would cause a
   normal GET request at that time to return a non-2.xx response (for
   example, when the resource is deleted), the server sends a
   notification with an appropriate response code (such as 4.04 Not
   Found) and removes the client's entry from the list of observers of
   the resource.  Non-2.xx responses do not include an Observe Option.

3.3.  Caching

   As notifications are just additional responses to a GET request,
   notifications partake in caching as defined in Section 5.6 of RFC
   7252 [RFC7252].  Both the freshness model and the validation model
   are supported.

3.3.1.  Freshness

   A client MAY store a notification like a response in its cache and
   use a stored notification that is fresh without contacting the
   server.  Like a response, a notification is considered fresh while
   its age is not greater than the value indicated by the Max-Age Option
   (and no newer notification/response has been received).

   The server will do its best to keep the resource state observed by
   the client as closely in sync with the actual state as possible.
   However, a client cannot rely on observing every single state that a
   resource might go through.  For example, if the network is congested
   or the state changes more frequently than the network can handle, the
   server can skip notifications for any number of intermediate states.

   The server uses the Max-Age Option to indicate an age up to which it
   is acceptable that the observed state and the actual state are
   inconsistent.  If the age of the latest notification becomes greater
   than its indicated Max-Age, then the client MUST NOT assume that the
   enclosed representation reflects the actual resource state.

   To make sure it has a current representation and/or to re-register
   its interest in a resource, a client MAY issue a new GET request with
   the same token as the original at any time.  All options MUST be
   identical to those in the original request, request except for the set of ETag
   Options.  It is RECOMMENDED that the client does not issue the
   request while it still has a fresh notification/response for the
   resource in its cache.  Additionally, the client SHOULD at least wait
   for a random amount of time between 5 and 15 seconds after Max-Age
   expired to reduce collisions with other clients.

3.3.2.  Validation

   When a client has one or more notifications stored in its cache for a
   resource, it can use the ETag Option in the GET request to give the
   server an opportunity to select a stored notification to be used.

   The client MAY include an ETag Option for each stored response that
   is applicable in the GET request.  Whenever the observed resource
   changes 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.

   A client implementation needs to keep all candidate responses in its
   cache until it is no longer interested in the target resource or it
   re-registers with a new set of entity-tags. entity tags.

3.4.  Reordering

   Messages with notifications can arrive in a different order than they
   were sent.  Since the goal is to keep the observed state as closely
   in sync with the actual state as possible, a client MUST consider the
   notification that was sent most recently as the freshest, regardless
   of the order of arrival.

   To provide an order among notifications for the client, the server
   sets the value of the Observe Option in each notification to the 24
   least-significant
   least significant bits of a strictly increasing sequence number.  An
   incoming notification was sent more recently than the freshest
   notification so far when one of the following conditions is met:

                      (V1 < V2 and V2 - V1 < 2^23) or
                      (V1 > V2 and V1 - V2 > 2^23) or
                      (T2 > T1 + 128 seconds)

   where V1 is the value of the Observe Option in the freshest
   notification so far, V2 is the value of the Observe Option in the
   incoming notification, T1 is a client-local timestamp for the
   freshest notification so far, and T2 is a client-local timestamp for
   the incoming notification.

   Design Note:  The first two conditions verify that V1 is less than V2
      in 24-bit serial number arithmetic [RFC1982].  The third condition
      ensures that, that if the server is generating serial numbers based on a
      local clock, the time elapsed between the two incoming messages is
      not so large that the difference between V1 and V2 has become
      larger than the largest integer that it is meaningful to add to a
      24-bit serial number; in other words, after 128 seconds have
      elapsed without any notification, a client does not need to check
      the sequence numbers to assume that an incoming notification was
      sent more recently than the freshest notification it has received
      so far.

      The duration of 128 seconds was chosen as a nice round number
      greater than MAX_LATENCY (Section 4.8.2 of RFC 7252 [RFC7252]).

3.5.  Transmission

   A notification can be confirmable or non-confirmable, i.e., it can be
   sent in a confirmable or a non-confirmable message.  The message type
   used for a notification is independent of the type used for the
   request and of any previous notification.

   If a client does not recognize the token in a confirmable
   notification, it MUST NOT acknowledge the message and SHOULD reject
   it with a Reset message; otherwise, the client MUST acknowledge the
   message as usual.  In the case of a non-confirmable notification,
   rejecting the message with a Reset message is OPTIONAL.

   An acknowledgement message 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 the associated entry from the list of
   observers.
   observers (Section 4.5).

3.6.  Cancellation

   A client that is no longer interested in receiving notifications for
   a resource can simply "forget" the observation.  When the server then
   sends the next notification, the client will not recognize the token
   in the message and thus will return a Reset message.  This causes the
   server to remove the associated entry from the list of observers.
   The entries in lists of observers are effectively "garbage collected"
   by the server.

   Implementation Note:  Due to potential message loss, the Reset
      message may not reach the server.  The client may therefore have
      to reject multiple notifications, each with one Reset message,
      until the server finally removes the associated entry from the
      list of observers and stops sending notifications.

   In some circumstances, it may be desirable to cancel an observation
   and release the resources allocated by the server to it more eagerly.
   In this case, a client MAY explicitly deregister by issuing a GET
   request which that has the Token field set to the token of the observation
   to be cancelled and includes an Observe Option with the value set to
   1 (deregister).  All other options MUST be identical to those in the
   registration request, request except for the set of ETag Options.  When the
   server receives such a request, it will remove any matching entry
   from the list of observers and process the GET request as usual.

4.  Server-side  Server-Side Requirements

4.1.  Request

   A GET request with an Observe Option set to 0 (register) requests the
   server not only to return a current representation of the target
   resource, but also to add the client to the list of observers of that
   resource.  Upon success, the server returns a current representation
   of the resource and MUST keep this representation updated (as
   described in Section 1.3) as long as the client is on the list of
   observers.

   The entry in the list of observers is keyed by the client endpoint
   and the token specified by the client in the request.  If an entry
   with a matching endpoint/token pair is already present in the list
   (which, for example, happens when the client wishes to reinforce its
   interest in a resource), the server MUST NOT add a new entry but MUST
   replace or update the existing one.

   A server that is unable or unwilling to add a new entry to the list
   of observers of a resource MAY silently ignore the registration
   request and process the GET request as usual.  The resulting response
   MUST NOT include an Observe Option, the absence of which signals to
   the client that it will not be notified of changes to the resource
   and, e.g., needs to poll the resource for its state instead.

   If the Observe Option in a GET request is set to 1 (deregister), then
   the server MUST remove any existing entry with a matching endpoint/
   token pair from the list of observers and process the GET request as
   usual.  The resulting response MUST NOT include an Observe Option.

4.2.  Notifications

   A client is notified of changes to the resource state by additional
   responses sent by the server in reply to the GET request.  Each such
   notification response (including the initial response) MUST echo the
   token specified by the client in the GET request.  If there are
   multiple entries in the list of observers, the order in which the
   clients are notified is not defined; the server is free to use any
   method to determine the order.

   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 at that time to return a
   non-2.xx response (for example, when the resource is deleted), the
   server SHOULD notify the client by sending a notification with an
   appropriate response code (such as 4.04 Not Found) and subsequently
   MUST remove the associated entry from the list of observers of the
   resource.

   The Content-Format specified in a 2.xx 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 in this format, it
   SHOULD send a notification with a 4.06 (Not Acceptable) response code
   and subsequently MUST remove the associated entry from the list of
   observers of the resource.

   A 2.xx notification MUST include an Observe Option with a sequence
   number as specified in Section 4.4 below; a non-2.xx notification
   MUST NOT include an Observe Option.

4.3.  Caching

   As notifications are just additional responses sent by the server in
   reply to a GET request, they are subject to caching as defined in
   Section 5.6 of RFC 7252 [RFC7252].

4.3.1.  Freshness

   After returning the initial response, the server MUST keep the
   resource state that is observed by the client as closely in sync with
   the actual resource state as possible.

   Since becoming out of sync at times cannot be avoided, the server
   MUST indicate for each representation an age up to which it is
   acceptable that the observed state and the actual state are
   inconsistent.  This age is application-dependent application dependent and MUST be
   specified in notifications using the Max-Age Option.

   When the resource does not change and the client has a current
   representation, the server does not need to send a notification.
   However, if the client does not receive a notification, the client
   cannot tell if the observed state and the actual state are still in
   sync.  Thus, when the age of the latest notification becomes greater
   than its indicated Max-Age, the client no longer has a usable
   representation of the resource state.  The server MAY wish to prevent
   that by sending a new notification with the unchanged representation
   and a new Max-Age just before the Max-Age indicated earlier expires.

4.3.2.  Validation

   A client can include a set of entity-tags entity tags in its request using the
   ETag Option.  When a an observed resource changes its state and the
   origin server is about to send a 2.05 (Content) notification, then, then
   whenever that notification has an entity-tag entity tag in the set of entity- entity
   tags specified by the client, the server MAY send a 2.03 (Valid)
   response with an appropriate ETag Option instead.

4.4.  Reordering

   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 Observe Option
   of each notification it sends to the 24 least-significant least significant bits of a
   strictly increasing sequence number.  The sequence number MAY start
   at any value and MUST NOT increase so fast that it increases by more
   than 2^23 within less than 256 seconds.

   The sequence number selected for a notification MUST be greater than
   that of any preceding notification sent to the same client with the
   same token for the same resource.  The value of the Observe Option
   MUST be current at the time of transmission; if a notification is
   retransmitted, the server MUST update the value of the option to the
   sequence number that is current at that time before retransmission.

   Implementation Note:  A simple implementation that satisfies the
      requirements is to obtain a timestamp from a local clock.  The
      sequence number then is the timestamp in ticks, where 1 tick =
      (256 seconds)/(2^23) = 30.52 microseconds.  It is not necessary
      that the clock reflects the current time/date.

      Another valid implementation is to store a 24-bit unsigned integer
      variable per resource and increment this variable each time the
      resource undergoes a change of state (provided that the resource
      changes its state less than 2^23 times in the first 256 seconds
      after every state change).  This removes the need to update the
      value of the Observe Option on retransmission when the resource
      state did not change.

   Design Note:  The choice of a 24-bit option value and a time span of
      256 seconds theoretically allows for a notification rate of up to
      65536 notifications per second.  Constrained nodes often have
      rather imprecise clocks, though, and inaccuracies of the client
      and server side may cancel out or add in effect.  Therefore, the
      maximum notification rate is reduced to 32768 notifications per
      second.  This is still well beyond the highest known design
      objective of around 1 kHz (most CoAP applications will be several
      orders of magnitude below that), that) but allows total clock
      inaccuracies of up to -50/+100 %. -50/+100%.

4.5.  Transmission

   A notification can be sent in a confirmable or a non-confirmable
   message.  The message type used is typically application-dependent 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.

   A server MAY choose to skip sending a notification if it knows that
   it will send another notification soon, for example, when the state
   of a resource is changing frequently.  It also MAY choose to send
   more than one notification for the same resource state.  However,
   above all, the server MUST ensure that a client in the list of
   observers of a resource eventually observes the latest state if the
   resource does not undergo a new change in state.

   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 by repeating the last notification in a confirmable message
   when the burst is over.

   The client's acknowledgement of a confirmable notification signals
   that the client is interested in receiving further notifications.  If
   a client rejects a confirmable or non-confirmable notification with a
   Reset message, or if the last attempt to retransmit a confirmable
   notification times out, then the client is considered no longer
   interested and the server MUST remove the associated entry from the
   list of observers.

   Implementation Note:  To properly process a Reset message that
      rejects a non-confirmable notification, a server needs to remember
      the message IDs of the non-confirmable notifications it sends.
      This may be challenging for a server with constrained resources.
      However, since Reset messages are transmitted unreliably, the
      client must be prepared that its in case the Reset messages aren't are not
      received by the server.  A  Thus, a server thus can always pretend that a
      Reset message rejecting a non-confirmable notification was lost.
      If a server does this, it could accelerate cancellation by sending
      the following notifications to that client in confirmable
      messages.

   A server that transmits notifications mostly in non-confirmable
   messages MUST send a notification in a confirmable message instead of
   a non-confirmable message at least every 24 hours.  This prevents a
   client that went away or is no longer interested from remaining in
   the list of observers indefinitely.

4.5.1.  Congestion Control

   Basic congestion control for CoAP is provided by the exponential
   back-off mechanism in Section 4.2 of RFC 7252 [RFC7252] and the
   limitations in Section 4.7 of RFC 7252 [RFC7252].  However, CoAP
   places the responsibility of congestion control for simple request/
   response interactions only on the clients: rate limiting rate-limiting request
   transmission implicitly controls the transmission of the responses.
   When a single request yields a potentially infinite number of
   notifications, additional responsibility needs to be placed on the
   server.

   In order not to cause congestion, servers MUST strictly limit the
   number of simultaneous outstanding notifications/responses that they
   transmit to a given client to NSTART (1 by default; see Section 4.7
   of RFC 7252 [RFC7252]).  An outstanding notification/response is
   either a confirmable message for which an acknowledgement has not yet
   been received and whose last retransmission attempt has not yet timed
   out,
   out or a non-confirmable message for which the waiting time that
   results from the following rate limiting rate-limiting rules has not yet elapsed.

   The server SHOULD NOT send more than one non-confirmable notification
   per round-trip time (RTT) to a client on average.  If the server
   cannot maintain an RTT estimate for a client, it SHOULD NOT send more
   than one non-confirmable notification every 3 seconds, seconds and SHOULD use
   an even less aggressive rate when possible (see also Section 3.1.2 of
   RFC 5405 [RFC5405]).

   Further congestion control optimizations and considerations are
   expected in the future with advanced CoAP congestion control
   mechanisms.

4.5.2.  Advanced Transmission

   The state of an observed resource may change while the number of the
   number of
   simultaneous outstanding notifications/responses to a client on the
   list of observers is greater than or equal to NSTART.  In this case,
   the server cannot notify the client of the new resource state
   immediately but has to wait for an outstanding notification/
   response notification/response
   to complete first.

   If there exists an outstanding notification/response that the server
   transmits to the client and that pertains to the changed resource,
   then it is desirable for the server to stop working towards getting
   the representation of the old resource state to the client, client and to
   start transmitting the current representation to the client instead,
   so the resource state observed by the client stays closer in sync
   with the actual state at the server.

   For this purpose, the server MAY optimize the transmission process by
   aborting the transmission of the old notification (but not before the
   current transmission attempt is completed) and starting a new
   transmission for the new notification (but with the retransmission
   timer and counter of the aborted transmission retained).

   In more detail, a server MAY supersede an outstanding transmission
   that pertains to an observation as follows:

   1.  Wait for the current (re-)transmission (re)transmission attempt to be acknowledged, rejected
       rejected, or to time out (confirmable transmission);
       or or, wait for
       the waiting time to elapse or the transmission to be rejected
       (non-confirmable transmission).

   2.  If the transmission is rejected or it was the last attempt to
       retransmit a notification, remove the associated entry from the
       list of observers of the observed resource.

   3.  If the entry is still in the list of observers, start to transmit
       a new notification with a representation of the current resource
       state.  Should the resource have changed its state more than once
       in the meantime, the notifications for the intermediate states
       are silently skipped.

   4.  The new notification is transmitted with a new Message ID and the
       following transmission parameters: If if the previous
       (re-)transmission
       (re)transmission attempt timed out, retain its transmission
       parameters, increment the retransmission counter counter, and double the
       timeout; otherwise, initialize the transmission parameters as
       usual (see Section 4.2 of RFC 7252 [RFC7252]).

   It is possible that the server later receives an acknowledgement for
   a confirmable notification that it superseded this way.  Even though
   this does not signal consistency, it is valuable in that it signals
   the client's further interest in the resource.  The server therefore
   should avoid inadvertently removing the associated entry from the
   list of observers.

5.  Intermediaries

   A client may be interested in a resource in the namespace of a server
   that is reached through a chain of one or more CoAP intermediaries.
   In this case, the client registers its interest with the first
   intermediary towards the server, acting as if it was communicating
   with the server itself, as specified in Section 3.  It is the task of
   this intermediary to provide the client with a current representation
   of the target resource and to keep the representation updated upon
   changes to the resource state, as specified in Section 4.

   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 towards the server.  If the response returned by the next hop
   doesn't include an Observe Option, the intermediary MAY resort to
   polling the next hop or MAY itself return a response without an
   Observe Option.

   The communication between each pair of hops is independent; each hop
   in the server role MUST determine individually how many notifications
   to send, of which message type, and so on.  Each hop MUST generate
   its own values for the Observe Option in notifications, notifications and MUST set
   the value of the Max-Age Option according to the age of the local
   current representation.

   If two or more clients have registered their interest in a resource
   with an intermediary, the intermediary MUST register itself only once
   with the next hop and fan out the notifications it receives to all
   registered clients.  This relieves the next hop from sending the same
   notifications multiple times and thus enables scalability.

   An intermediary is not required to act on behalf of a client to
   observe a resource; an intermediary MAY observe a resource, for
   example, just to keep its own cache up to date.

   See Appendix A.2 for examples.

6.  Web Linking

   A web link [RFC5988] to a resource accessible over CoAP (for example,
   in a link-format document [RFC6690]) MAY include the target attribute
   "obs".

   The "obs" attribute, when present, is a hint indicating that the
   destination of a link is useful for observation and thus, for
   example, should have a suitable graphical representation in a user
   interface.  Note that this is only a hint; it is not a promise that
   the Observe Option can actually be used to perform the observation.
   A client may need to resort to polling the resource if the Observe
   Option is not returned in the response to the GET request.

   A value MUST NOT be given for the "obs" attribute; any present value
   MUST be ignored by parsers.  The "obs" attribute MUST NOT appear more
   than once in a given link-value; occurrences after the first MUST be
   ignored by parsers.

7.  Security Considerations

   The security considerations in Section 11 of [RFC7252], the CoAP specification
   [RFC7252]
   specification, apply.

   Observing resources can dramatically increase the negative effects of
   amplification attacks.  That is, not only can notifications messages
   be much larger than the request message, but the nature of the
   protocol can cause a significant number of notifications to be
   generated.  Without client authentication, a server therefore MUST
   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  Note that
   an attacker may still spoof the acknowledgements if the confirmable
   messages are sufficiently predictable.) predictable.

   The protocol follows a best-effort approach for keeping the state
   observed by a client and the actual resource state at a server in
   sync.  This may have the client and the server become out of sync at
   times.  Depending on the sensitivity of the observed resource,
   operating on an old state might be a security threat.  The client
   therefore must be careful not to use a representation after its Max-
   Age expires, and the server must set the Max-Age Option to a sensible
   value.

   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 apply
   access controls to this creation of state.  As degraded behavior, the
   server can always fall back to processing the request as a normal GET
   request (without an Observe 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.

   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.

   Resources can be observed over DTLS-secured CoAP that is secured by Datagram
   Transport Layer Security (DTLS) using any of the security modes
   described in Section 9 of RFC 7252.  The use of DTLS is indicated by
   the "coaps" URI scheme.  All notifications resulting from a GET
   request with an Observe Option MUST be returned within the same epoch
   of the same connection as the request.

8.  IANA Considerations

   The following entry is has been added to the CoAP Option Numbers
   registry:

                     +--------+---------+-----------+
                     | Number | Name    | Reference |
                     +--------+---------+-----------+
                     |      6 | Observe | [RFCXXXX] RFC 7641  |
                     +--------+---------+-----------+

   [Note to RFC Editor: Please replace XXXX with the RFC number of this
   specification.]

9.  Acknowledgements

   Carsten Bormann was an original author of this draft and is
   acknowledged for significant contribution to this document.

   Thanks to Daniele Alessandrelli, Jari Arkko, Peter A. Bigot, Angelo
   P. Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank,
   Bert Greevenbosch, Jeroen Hoebeke, Cullen Jennings, Matthias
   Kovatsch, Barry Leiba, Salvatore Loreto, Charles Palmer, Akbar
   Rahman, Zach Shelby, and Floris Van den Abeele for helpful comments
   and discussions that have shaped the document.

   This work was supported in part by Klaus Tschira Foundation, Intel,
   Cisco, and Nokia.

10.  References

10.1.

9.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997. 1997,
              <http://www.rfc-editor.org/info/rfc2119>.

   [RFC5988]  Nottingham, M., "Web Linking", RFC 5988,
              DOI 10.17487/RFC5988, October 2010. 2010,
              <http://www.rfc-editor.org/info/rfc5988>.

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252,
              DOI 10.17487/RFC7252, June 2014.

10.2. 2014,
              <http://www.rfc-editor.org/info/rfc7252>.

9.2.  Informative References

   [GOF]      Gamma, E., Helm, R., Johnson, R., and J. Vlissides,
              "Design Patterns: Elements of Reusable Object-Oriented
              Software", Addison-Wesley, Reading, MA, USA,
              November Addison-Wesley Professional Computing Series,
              1994.

   [REST]     Fielding, R., "Architectural Styles and the Design of
              Network-based Software Architectures", Ph.D. Dissertation,
              University of California, Irvine, 2000, <http://
              www.ics.uci.edu/~fielding/pubs/dissertation/
              <http://www.ics.uci.edu/~fielding/pubs/dissertation/
              fielding_dissertation.pdf>.

   [RFC1982]  Elz, R. and R. Bush, "Serial Number Arithmetic", RFC 1982,
              DOI 10.17487/RFC1982, August 1996. 1996,
              <http://www.rfc-editor.org/info/rfc1982>.

   [RFC5405]  Eggert, L. and G. Fairhurst, "Unicast UDP Usage Guidelines
              for Application Designers", BCP 145, RFC 5405,
              DOI 10.17487/RFC5405, November 2008. 2008,
              <http://www.rfc-editor.org/info/rfc5405>.

   [RFC5989]  Roach, A., "A SIP Event Package for Subscribing to Changes
              to an HTTP Resource", RFC 5989, DOI 10.17487/RFC5989,
              October 2010. 2010, <http://www.rfc-editor.org/info/rfc5989>.

   [RFC6202]  Loreto, S., Saint-Andre, P., Salsano, S., and G. Wilkins,
              "Known Issues and Best Practices for the Use of Long
              Polling and Streaming in Bidirectional HTTP", RFC 6202,
              DOI 10.17487/RFC6202, April 2011. 2011,
              <http://www.rfc-editor.org/info/rfc6202>.

   [RFC6690]  Shelby, Z., "Constrained RESTful Environments (CoRE) Link
              Format", RFC 6690, DOI 10.17487/RFC6690, August 2012. 2012,
              <http://www.rfc-editor.org/info/rfc6690>.

   [RFC7228]  Bormann, C., Ersue, M., and A. Keranen, "Terminology for
              Constrained-Node Networks", RFC 7228,
              DOI 10.17487/RFC7228, May 2014. 2014,
              <http://www.rfc-editor.org/info/rfc7228>.

   [RFC7230]  Fielding, R. R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Message Syntax and Routing", RFC
              7230, DOI 10.17487/RFC7230, June 2014. 2014,
              <http://www.rfc-editor.org/info/rfc7230>.

Appendix A.  Examples

A.1.  Client/Server Examples

         Observed   CLIENT  SERVER     Actual
     t   State         |      |         State
         ____________  |      |  ____________
     1                 |      |
     2    unknown      |      |     18.5 Cel
     3                 +----->|                  Header: GET 0x41011633
     4                 | GET  |                   Token: 0x4a
     5                 |      |                Uri-Path: temperature
     6                 |      |                 Observe: 0 (register)
     7                 |      |
     8                 |      |
     9   ____________  |<-----+                  Header: 2.05 0x61451633
    10                 | 2.05 |                   Token: 0x4a
    11    18.5 Cel     |      |                 Observe: 9
    12                 |      |                 Max-Age: 15
    13                 |      |                 Payload: "18.5 Cel"
    14                 |      |
    15                 |      |  ____________
    16   ____________  |<-----+                  Header: 2.05 0x51457b50
    17                 | 2.05 |     19.2 Cel      Token: 0x4a
    18    19.2 Cel     |      |                 Observe: 16
    29                 |      |                 Max-Age: 15
    20                 |      |                 Payload: "19.2 Cel"
    21                 |      |

     Figure 3: A client registers Client Registers and receives one notification Receives One Notification of the
         current state
         Current State and one One of a new state New State upon a state change State Change
         Observed   CLIENT  SERVER     Actual
     t   State         |      |         State
         ____________  |      |  ____________
    22                 |      |
    23    19.2 Cel     |      |     19.2 Cel
    24                 |      |  ____________
    25                 | X----+                  Header: 2.05 0x51457b51
    26                 | 2.05 |     19.7 Cel      Token: 0x4a
    27                 |      |                 Observe: 25
    28                 |      |                 Max-Age: 15
    29                 |      |                 Payload: "19.7 Cel"
    30                 |      |
    31   ____________  |      |
    32                 |      |
    33    19.2 Cel     |      |
    34    (stale)      |      |
    35                 |      |
    36                 |      |
    37                 |      |
    38                 +----->|                  Header: GET 0x41011634
    39                 | GET  |                   Token: 0xb2
    40                 |      |                Uri-Path: temperature
    41                 |      |                 Observe: 0 (register)
    42                 |      |
    43                 |      |
    44   ____________  |<-----+                  Header: 2.05 0x61451634
    45                 | 2.05 |                   Token: 0xb2
    46    19.7 Cel     |      |                 Observe: 44
    47                 |      |                 Max-Age: 15
    48                 |      |                    ETag: 0x78797a7a79
    49                 |      |                 Payload: "19.7 Cel"
    50                 |      |

           Figure 4: The client re-registers Client Re-registers after Max-Age ends Ends
         Observed   CLIENT  SERVER     Actual
     t   State         |      |         State
         ____________  |      |  ____________
    51                 |      |
    52    19.7 Cel     |      |     19.7 Cel
    53                 |      |
    54                 |      |  ____________
    55                 |    crash
    56                 |
    57                 |
    58                 |
    59   ____________  |
    60                 |
    61    19.7 Cel     |
    62    (stale)      |
    63                 |   reboot____________
    64                 |      |
    65                 |      |     20.0 Cel
    66                 |      |
    67                 +----->|                  Header: GET 0x41011635
    68                 | GET  |                   Token: 0xf9
    69                 |      |                Uri-Path: temperature
    70                 |      |                 Observe: 0 (register)
    71                 |      |                    ETag: 0x78797a7a79
    72                 |      |
    73                 |      |
    74   ____________  |<-----+                  Header: 2.05 0x61451635
    75                 | 2.05 |                   Token: 0xf9
    76    20.0 Cel     |      |                 Observe: 74
    77                 |      |                 Max-Age: 15
    78                 |      |                 Payload: "20.0 Cel"
    79                 |      |
    80                 |      |  ____________
    81   ____________  |<-----+                  Header: 2.03 0x5143aa0c
    82                 | 2.03 |     19.7 Cel      Token: 0xf9
    83    19.7 Cel     |      |                 Observe: 81
    84                 |      |                    ETag: 0x78797a7a79
    85                 |      |                 Max-Age: 15
    86                 |      |

        Figure 5: The client re-registers Client Re-registers and gives Gives the server Server the
                  opportunity
                  Opportunity to select Select a stored response Stored Response
         Observed   CLIENT  SERVER     Actual
     t   State         |      |         State
         ____________  |      |  ____________
    87                 |      |
    88    19.7 Cel     |      |     19.7 Cel
    89                 |      |
    90                 |      |  ____________
    91   ____________  |<-----+                  Header: 2.05 0x4145aa0f
    92                 | 2.05 |     19.3 Cel      Token: 0xf9
    93    19.3 Cel     |      |                 Observe: 91
    94                 |      |                 Max-Age: 15
    95                 |      |                 Payload: "19.3 Cel"
    96                 |      |
    97                 |      |
    98                 +- - ->|                  Header: 0x7000aa0f
    99                 |      |
   100                 |      |
   101                 |      |
   102                 |      |  ____________
   103                 |      |
   104                 |      |     19.0 Cel
   105                 |      |
   106   ____________  |      |
   107                 |      |
   108    19.3 Cel     |      |
   109    (stale)      |      |
   110                 |      |

    Figure 6: The client rejects Client Rejects a notification Notification and thereby cancels Thereby Cancels the
                                observation
                                Observation

A.2.  Proxy Examples

   CLIENT  PROXY  SERVER
      |      |      |
      |      +----->|     Header: GET 0x41015fb8
      |      | GET  |      Token: 0x1a
      |      |      |   Uri-Host: sensor.example
      |      |      |   Uri-Path: status
      |      |      |    Observe: 0 (register)
      |      |      |
      |      |<-----+     Header: 2.05 0x61455fb8
      |      | 2.05 |      Token: 0x1a
      |      |      |    Observe: 42
      |      |      |    Max-Age: 60
      |      |      |    Payload: "ready"
      |      |      |
      +----->|      |     Header: GET 0x41011633
      | GET  |      |      Token: 0x9a
      |      |      |  Proxy-Uri: coap://sensor.example/status
      |      |      |
      |<-----+      |     Header: 2.05 0x61451633
      | 2.05 |      |      Token: 0x9a
      |      |      |    Max-Age: 53
      |      |      |    Payload: "ready"
      |      |      |
      |      |<-----+     Header: 2.05 0x514505fc0
      |      | 2.05 |      Token: 0x1a
      |      |      |    Observe: 135
      |      |      |    Max-Age: 60
      |      |      |    Payload: "busy"
      |      |      |
      +----->|      |     Header: GET 0x41011634
      | GET  |      |      Token: 0x9b
      |      |      |  Proxy-Uri: coap://sensor.example/status
      |      |      |
      |<-----+      |     Header: 2.05 0x61451634
      | 2.05 |      |      Token: 0x9b
      |      |      |    Max-Age: 49
      |      |      |    Payload: "busy"
      |      |      |

    Figure 7: A proxy observes Proxy Observes a resource Resource to keep Keep its cache up Cache Up to date Date
   CLIENT  PROXY  SERVER
      |      |      |
      +----->|      |     Header: GET 0x41011635
      | GET  |      |      Token: 0x6a
      |      |      |  Proxy-Uri: coap://sensor.example/status
      |      |      |    Observe: 0 (register)
      |      |      |
      |<- - -+      |     Header: 0x60001635
      |      |      |
      |      +----->|     Header: GET 0x4101af90
      |      | GET  |      Token: 0xaa
      |      |      |   Uri-Host: sensor.example
      |      |      |   Uri-Path: status
      |      |      |    Observe: 0 (register)
      |      |      |
      |      |<-----+     Header: 2.05 0x6145af90
      |      | 2.05 |      Token: 0xaa
      |      |      |    Observe: 67
      |      |      |    Max-Age: 60
      |      |      |    Payload: "ready"
      |      |      |
      |<-----+      |     Header: 2.05 0x4145af94
      | 2.05 |      |      Token: 0x6a
      |      |      |    Observe: 17346
      |      |      |    Max-Age: 60
      |      |      |    Payload: "ready"
      |      |      |
      +- - ->|      |     Header: 0x6000af94
      |      |      |
      |      |<-----+     Header: 2.05 0x51455a20
      |      | 2.05 |      Token: 0xaa
      |      |      |    Observe: 157
      |      |      |    Max-Age: 60
      |      |      |    Payload: "busy"
      |      |      |
      |<-----+      |     Header: 2.05 0x5145af9b
      | 2.05 |      |      Token: 0x6a
      |      |      |    Observe: 17436
      |      |      |    Max-Age: 60
      |      |      |    Payload: "busy"
      |      |      |

          Figure 8: A client observes Client Observes a resource Resource through a proxy

Appendix B.  Changelog

   [Note to RFC Editor: Please remove Proxy

Acknowledgements

   Carsten Bormann was an original author of this section before publication.]

   Changes from ietf-15 to ietf-16:

   o  Clarified several points based on AD, GenART, IESG, and Secdir
      reviews.

   Changes from ietf-14 to ietf-15:

   o  Clarified several points based on AD, GenART, IESG, document and Secdir
      reviews.

   Changes from ietf-13 to ietf-14:

   o  Updated references.

   Changes from ietf-12 is
   acknowledged for significant contribution to ietf-13:

   o  Extended the Observe Option in requests this document.

   Thanks to not only add but also
      remove an entry in the list of observers, depending on the option
      value.

      Note:  The value of the Observe Option in a registration request
         may now be any sequence of bytes that encodes the unsigned
         integer 0, i.e., 0x'', 0x'00', 0x'00 00' or 0x'00 00 00'.

   o  Removed the 7.31 Code for cancellation.

   Changes from ietf-11 to ietf-12:

   o  Introduced the 7.31 Code to request the cancellation of a pending
      request.

   o  Made the algorithm for superseding an outstanding transmission
      OPTIONAL.

   o  Clarified that the entry in the list of observers is removed if
      the client fails to acknowledge a confirmable notification before
      the last retransmission attempt times out (#350).

   o  Simplified the text on cancellation (#352) and the handling of
      Reset messages (#353).

   Changes from ietf-10 to ietf-11:

   o  Pointed out that client and server clocks may differ in their
      realization of the SI second, and added robustness to the existing
      reordering scheme by reducing the maximum notification rate to
      32768 notifications per second (#341).

   Changes from ietf-09 to ietf-10:

   o  Required consistent sequence numbers across requests (#333).

   o  Clarified that a server needs to update the entry in the list of
      observers instead of adding a new entry if the endpoint/token pair
      is already present.

   o  Allowed that a client uses a token that is currently in use to
      ensure that it's still in the list of observers.  This is possible
      because sequence numbers are now consistent across requests and
      servers won't add a new entry for the same token.

   o  Improved text on the transmission of non-confirmable notifications
      to match Section 3.1.2 of RFC 5405 more closely.

   o  Updated examples to use UCUM units.

   o  Moved Appendix B into the introduction.

   Changes from ietf-08 to ietf-09:

   o  Removed the side effects of requests on existing observations.
      This includes removing that

      *  the client can use a GET request to cancel an observation;

      *  the server updates the entry in the list of observers instead
         of adding a new entry if the client is already present (#258,
         #281).

   o  Clarified that a resource (and hence an observation relationship)
      is identified by the request options that are part of the Cache-
      Key (#258).

   o  Clarified that a non-2.xx notification MUST NOT include an Observe
      Option.

   o  Moved block-wise transfer of notifications to [I-D.ietf-core-
      block].

   Changes from ietf-07 to ietf-08:

   o  Expanded text on transmitting a notification while a previous
      transmission is pending (#242).

   o  Changed reordering detection to use a fixed time span of 128
      seconds instead of EXCHANGE_LIFETIME (#276).

   o  Removed the use of the freshness model to determine if the client
      is still on the list of observers.  This includes removing that

      *  the client assumes that it has been removed from the list of
         observers when Max-Age ends;

      *  the server sets the Max-Age Option of a notification to a value
         that indicates when the server will send the next notification;

      *  the server uses a number of retransmit attempts such that
         removing a client from the list of observers before Max-Age
         ends is avoided (#235);

      *  the server may remove the client from all lists of observers
         when the transmission of a confirmable notification ultimately
         times out.

   o  Changed that an unrecognized critical option in a request must
      actually have no effect on the state of any observation
      relationship to any resource, as the option could lead to a
      different target resource.

   o  Clarified that client implementations must be prepared to receive
      each notification equally as a confirmable or a non-confirmable
      message, regardless of the message type of the request and of any
      previous notification.

   o  Added a requirement for sending a confirmable notification at
      least every 24 hours before continuing with non-confirmable
      notifications (#221).

   o  Added congestion control considerations from [I-D.bormann-core-
      congestion-control-02].

   o  Recommended that the client waits for a randomized time after the
      freshness of the latest notification expired before re-
      registering.  This prevents that multiple clients observing a
      resource perform a GET request at the same time when the need to
      re-register arises.

   o  Changed reordering detection from 'MAY' to 'SHOULD', as the goal
      of the protocol (to keep the observed state as closely in sync
      with the actual state as possible) is not optional.

   o  Fixed the length of the Observe Option (3 bytes) in the table in
      Section 2.

   o  Replaced the 'x' in the No-Cache-Key column in the table in
      Section 2 with a '-', as the Observe Option doesn't have the No-
      Cache-Key flag set, even though it is not part of the cache key.

   o  Updated examples.

   Changes from ietf-06 to ietf-07:

   o  Moved to 24-bit sequence numbers to allow for up to 15000
      notifications per second per client and resource (#217).

   o  Re-numbered option number to use Unsafe/Safe and Cache-Key
      compliant numbers (#241).

   o  Clarified how to react to a Reset message that is sent in reply to
      a non-confirmable notification (#225).

   o  Clarified the semantics of the "obs" link target attribute (#236).

   Changes from ietf-05 to ietf-06:

   o  Improved abstract and introduction to say that the protocol is
      about best effort and eventual consistency (#219).

   o  Clarified that the value of the Observe Option in a request must
      have zero length.

   o  Added requirement that the sequence number must be updated each
      time a server retransmits a notification.

   o  Clarified that a server must remove a client from the list of
      observers when it receives a GET request with an unrecognized
      critical option.

   o  Updated the text to use the endpoint concept from [I-D.ietf-core-
      coap] (#224).

   o  Improved the reordering text (#223).

   Changes from ietf-04 to ietf-05:

   o  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).

   o  Relaxed requirements when sending a Reset message in reply to non-
      confirmable notifications.

   o  Added an implementation note about careless GET requests (#184).

   o  Updated examples.

   Changes from ietf-03 to ietf-04:

   o  Removed the "Max-OFE" Option.

   o  Allowed a Reset message in reply to non-confirmable notifications.

   o  Added a section on cancellation.

   o  Updated examples.

   Changes from ietf-02 to ietf-03:

   o  Separated client-side and server-side requirements.

   o  Fixed uncertainty if client is still on the list of observers by
      introducing a liveliness model based on Max-Age Daniele Alessandrelli, Jari Arkko, Peter A. Bigot, Angelo
   P. Castellani, Gilbert Clark, Esko Dijk, Thomas Fossati, Brian Frank,
   Bert Greevenbosch, Jeroen Hoebeke, Cullen Jennings, Matthias
   Kovatsch, Barry Leiba, Salvatore Loreto, Charles Palmer, Akbar
   Rahman, Zach Shelby, and a new option
      called "Max-OFE" (#174).

   o  Simplified the text on message reordering (#129).

   o  Clarified requirements for intermediaries.

   o  Clarified the combination of blockwise transfers with
      notifications (#172).

   o  Updated examples to show how the state observed by the client
      becomes eventually consistent with the actual state on the server.

   o  Added examples Floris Van den Abeele for parameterization of observable resource.

   Changes from ietf-01 to ietf-02:

   o  Removed the requirement of periodic refreshing (#126).

   o  The new "Observe" Option replaces the "Lifetime" Option.

   o  Introduced a new mechanism to detect message reordering.

   o  Changed 2.00 (OK) notifications to 2.05 (Content) notifications.

   Changes from ietf-00 to ietf-01:

   o  Changed terminology from "subscriptions" to "observation
      relationships" (#33).

   o  Changed the name of the option to "Lifetime".

   o  Clarified establishment of observation relationships.

   o  Clarified that an observation is only identified by the URI of the
      observed resource helpful comments
   and the identity of the client (#66).

   o  Clarified rules for establishing observation relationships (#68).

   o  Clarified conditions under which an observation relationship is
      terminated.

   o  Added explanation on how clients can terminate an observation
      relationship before the lifetime ends (#34).

   o  Clarified discussions that have shaped the overriding objective for notifications is
      eventual consistency of the actual and the observed state (#67).

   o  Specified how a server needs to deal with clients not
      acknowledging confirmable messages carrying notifications (#69).

   o  Added a mechanism to detect message reordering (#35).

   o  Added an explanation of how notifications can be cached,
      supporting both the freshness and the validation model (#39, #64).

   o  Clarified that non-GET requests do not affect observation
      relationships, and that GET requests without "Lifetime" Option
      affecting relationships is document.

   This work was supported in part by design (#65).

   o  Described interaction with blockwise transfers (#36).

   o  Added Resource Discovery section (#99).

   o  Added IANA Considerations.

   o  Added Security Considerations (#40).

   o  Added examples (#38). Klaus Tschira Foundation, Intel,
   Cisco, and Nokia.

Author's Address

   Klaus Hartke
   Universitaet Bremen TZI
   Postfach 330440
   Bremen  D-28359
   Germany

   Phone: +49-421-218-63905
   EMail:
   Email: hartke@tzi.org