draft-ietf-core-coap-pubsub-06.txt   draft-ietf-core-coap-pubsub-07.txt 
Network Working Group M. Koster Network Working Group M. Koster
Internet-Draft SmartThings Internet-Draft SmartThings
Intended status: Standards Track A. Keranen Intended status: Standards Track A. Keranen
Expires: July 7, 2019 J. Jimenez Expires: September 12, 2019 J. Jimenez
Ericsson Ericsson
January 3, 2019 March 11, 2019
Publish-Subscribe Broker for the Constrained Application Protocol (CoAP) Publish-Subscribe Broker for the Constrained Application Protocol (CoAP)
draft-ietf-core-coap-pubsub-06 draft-ietf-core-coap-pubsub-07
Abstract Abstract
The Constrained Application Protocol (CoAP), and related extensions The Constrained Application Protocol (CoAP), and related extensions
are intended to support machine-to-machine communication in systems are intended to support machine-to-machine communication in systems
where one or more nodes are resource constrained, in particular for where one or more nodes are resource constrained, in particular for
low power wireless sensor networks. This document defines a publish- low power wireless sensor networks. This document defines a publish-
subscribe Broker for CoAP that extends the capabilities of CoAP for subscribe Broker for CoAP that extends the capabilities of CoAP for
supporting nodes with long breaks in connectivity and/or up-time. supporting nodes with long breaks in connectivity and/or up-time.
skipping to change at page 1, line 37 skipping to change at page 1, line 37
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on July 7, 2019. This Internet-Draft will expire on September 12, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 14 skipping to change at page 2, line 14
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Architecture . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. CoAP Pub/sub Architecture . . . . . . . . . . . . . . . . 4 3.1. CoAP Pub/sub Architecture . . . . . . . . . . . . . . . . 4
3.2. CoAP Pub/sub Broker . . . . . . . . . . . . . . . . . . . 5 3.2. CoAP Pub/sub Broker . . . . . . . . . . . . . . . . . . . 4
3.3. CoAP Pub/sub Client . . . . . . . . . . . . . . . . . . . 5 3.3. CoAP Pub/sub Client . . . . . . . . . . . . . . . . . . . 5
3.4. CoAP Pub/sub Topic . . . . . . . . . . . . . . . . . . . 5 3.4. CoAP Pub/sub Topic . . . . . . . . . . . . . . . . . . . 5
3.5. brokerless Pub/sub . . . . . . . . . . . . . . . . . . . 5 3.5. Brokerless Pub/sub . . . . . . . . . . . . . . . . . . . 5
4. CoAP Pub/sub REST API . . . . . . . . . . . . . . . . . . . . 6 4. CoAP Pub/sub REST API . . . . . . . . . . . . . . . . . . . . 6
4.1. DISCOVERY . . . . . . . . . . . . . . . . . . . . . . . . 6 4.1. DISCOVERY . . . . . . . . . . . . . . . . . . . . . . . . 6
4.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.2. CREATE . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 11 4.3. PUBLISH . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 13 4.4. SUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . . 14
4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 15 4.5. UNSUBSCRIBE . . . . . . . . . . . . . . . . . . . . . . . 15
4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.6. READ . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 18 4.7. REMOVE . . . . . . . . . . . . . . . . . . . . . . . . . 18
5. CoAP Pub/sub Operation with Resource Directory . . . . . . . 19 5. CoAP Pub/sub Operation with Resource Directory . . . . . . . 20
6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 20 6. Sleep-Wake Operation . . . . . . . . . . . . . . . . . . . . 20
7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 20 7. Simple Flow Control . . . . . . . . . . . . . . . . . . . . . 20
8. Security Considerations . . . . . . . . . . . . . . . . . . . 20 8. Security Considerations . . . . . . . . . . . . . . . . . . . 21
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 22 9.1. Resource Type value 'core.ps' . . . . . . . . . . . . . . 22
9.2. Resource Type value 'core.ps.discover' . . . . . . . . . 22 9.2. Resource Type value 'core.ps.discover' . . . . . . . . . 22
9.3. Response Code value '2.07' . . . . . . . . . . . . . . . 22
10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 22
11. References . . . . . . . . . . . . . . . . . . . . . . . . . 23 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 23
11.1. Normative References . . . . . . . . . . . . . . . . . . 23 11.1. Normative References . . . . . . . . . . . . . . . . . . 23
11.2. Informative References . . . . . . . . . . . . . . . . . 23 11.2. Informative References . . . . . . . . . . . . . . . . . 23
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 24
1. Introduction 1. Introduction
The Constrained Application Protocol (CoAP) [RFC7252] supports The Constrained Application Protocol (CoAP) [RFC7252] supports
machine-to-machine communication across networks of constrained machine-to-machine communication across networks of constrained
skipping to change at page 3, line 26 skipping to change at page 3, line 25
This document specifies simple extensions to CoAP for enabling This document specifies simple extensions to CoAP for enabling
publish-subscribe communication using a Broker node that enables publish-subscribe communication using a Broker node that enables
store-and-forward messaging between two or more nodes. This model store-and-forward messaging between two or more nodes. This model
facilitates communication of nodes with limited reachability, enables facilitates communication of nodes with limited reachability, enables
simple many-to-many communication, and eases integration with other simple many-to-many communication, and eases integration with other
publish-subscribe systems. publish-subscribe systems.
2. Terminology 2. Terminology
The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT', {::boilerplate bcp14}
'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
specification are to be interpreted as described in [RFC2119].
This specification requires readers to be familiar with all the terms This specification requires readers to be familiar with all the terms
and concepts that are discussed in [RFC5988] and [RFC6690]. Readers and concepts that are discussed in [RFC5988] and [RFC6690]. Readers
should also be familiar with the terms and concepts discussed in should also be familiar with the terms and concepts discussed in
[RFC7252] and [I-D.ietf-core-resource-directory]. The URI template [RFC7252] and [I-D.ietf-core-resource-directory]. The URI template
format [RFC6570] is used to describe the REST API defined in this format [RFC6570] is used to describe the REST API defined in this
specification. specification.
This specification makes use of the following additional terminology: This specification makes use of the following additional terminology:
skipping to change at page 4, line 14 skipping to change at page 4, line 12
to match subscriptions and publications in order to route messages to match subscriptions and publications in order to route messages
to the right destinations. The Broker can also temporarily store to the right destinations. The Broker can also temporarily store
publications to satisfy future subscriptions and pending publications to satisfy future subscriptions and pending
notifications. notifications.
CoAP pub/sub Client: A CoAP client which is capable of publish or CoAP pub/sub Client: A CoAP client which is capable of publish or
subscribe operations as defined in this specification. subscribe operations as defined in this specification.
Topic: A unique identifier for a particular item being published Topic: A unique identifier for a particular item being published
and/or subscribed to. A Broker uses the topics to match and/or subscribed to. A Broker uses the topics to match
subscriptions to publications. A topic is a valid CoAP URI as subscriptions to publications. A reference to a Topic on a Broker
defined in [RFC7252] is a valid CoAP URI as defined in [RFC7252]
3. Architecture 3. Architecture
3.1. CoAP Pub/sub Architecture 3.1. CoAP Pub/sub Architecture
Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/ Figure 1 shows the architecture of a CoAP pub/sub service. CoAP pub/
sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/ sub Clients interact with a CoAP pub/sub Broker through the CoAP pub/
sub REST API which is hosted by the Broker. State information is sub REST API which is hosted by the Broker. State information is
updated between the Clients and the Broker. The CoAP pub/sub Broker updated between the Clients and the Broker. The CoAP pub/sub Broker
performs a store-and-forward of state update representations between performs a store-and-forward of state update representations between
skipping to change at page 5, line 43 skipping to change at page 5, line 37
Every CoAP pub/sub topic has an associated link, consisting of a Every CoAP pub/sub topic has an associated link, consisting of a
reference path on the Broker using URI path [RFC3986] construction reference path on the Broker using URI path [RFC3986] construction
and link attributes [RFC6690]. Every topic is associated with zero and link attributes [RFC6690]. Every topic is associated with zero
or more stored representations and a content-format specified in the or more stored representations and a content-format specified in the
link. A CoAP pub/sub topic value may alternatively consist of a link. A CoAP pub/sub topic value may alternatively consist of a
collection of one or more sub-topics, consisting of links to the sub- collection of one or more sub-topics, consisting of links to the sub-
topic URIs and indicated by a link-format content-format. Sub-topics topic URIs and indicated by a link-format content-format. Sub-topics
are also topics and may have their own sub-topics, forming a tree are also topics and may have their own sub-topics, forming a tree
structure of unique paths that is implemented using URIs. The full structure of unique paths that is implemented using URIs. The full
URI of a topic includes a scheme and authority for the Broker, for URI of a topic includes a scheme and authority for the Broker, for
example "coaps://10.0.0.13:5684/EP-33543/sen/3303/0/5700". example "coaps://192.0.2.13:5684/EP-33543/sen/3303/0/5700".
3.5. brokerless Pub/sub A Topic may have a lifetime defined by using the CoAP Max-Age option
on topic creation, or on publish operations to the topic. The
lifetime is refreshed each time a representation is published to the
topic. If the lifetime expires, the topic is removed from discovery
responses, returns errors on subscription, and any outstanding
subscriptions are cancelled.
3.5. Brokerless Pub/sub
In some use cases, it is desireable to use pub/sub semantics for
peer-to-peer communication, but it is not feasible or desireable to
include a separate node on the network to serve as a Broker. In
other use cases, it is desireable to enable one-way-only
communication, such as sensors pushing updates to a service.
Figure 2 shows an arrangement for using CoAP pub/sub in a Figure 2 shows an arrangement for using CoAP pub/sub in a
"Brokerless" configuration between peer nodes. Nodes in a Brokerless "Brokerless" configuration between peer nodes. Nodes in a Brokerless
system may act as both Broker and client. A node that supports system may act as both Broker and client. A node that supports
Broker functionality may be pre-configured with topics that expose Broker functionality may be pre-configured with topics that expose
services and resources. Brokerless peer nodes can be mixed with services and resources. Brokerless peer nodes can be mixed with
client and Broker nodes in a system with full interoperability. client and Broker nodes in a system with full interoperability.
Peer pub/sub Peer Peer pub/sub Peer
+-------+ | +-------+ +-------+ | +-------+
skipping to change at page 7, line 11 skipping to change at page 7, line 20
receives the URI of the resource and its content-format. A pub/sub receives the URI of the resource and its content-format. A pub/sub
Broker wishing to advertise topic discovery MUST use the relation Broker wishing to advertise topic discovery MUST use the relation
rt=core.ps.discover in the link. rt=core.ps.discover in the link.
A CoAP pub/sub Broker MAY provide topic discovery functionality A CoAP pub/sub Broker MAY provide topic discovery functionality
through the .well-known/core resource. Links to topics may be through the .well-known/core resource. Links to topics may be
exposed at .well-known/core in addition to links to the pub/sub API. exposed at .well-known/core in addition to links to the pub/sub API.
Figure 5 shows an example of topic discovery through .well-known/ Figure 5 shows an example of topic discovery through .well-known/
core. core.
Topics in the broker may be created in hierarchies (see {create}) Topics in the broker may be created in hierarchies (see Section 4.2)
with parent topics having sub-topics. For a discovery the broker may with parent topics having sub-topics. For a discovery the broker may
choose to not expose the sub-topics in order to limit amount of topic choose to not expose the sub-topics in order to limit amount of topic
links sent in a discovery response. The client can then perform links sent in a discovery response. The client can then perform
discovery for the parent topics it wants to discover the sub-topics. discovery for the parent topics it wants to discover the sub-topics.
The DISCOVER interface is specified as follows: The DISCOVER interface is specified as follows:
Interaction: Client -> Broker Interaction: Client -> Broker
Method: GET Method: GET
skipping to change at page 9, line 4 skipping to change at page 9, line 17
A CoAP pub/sub broker SHOULD allow Clients to create new topics on A CoAP pub/sub broker SHOULD allow Clients to create new topics on
the broker using CREATE. Some exceptions are for fixed brokerless the broker using CREATE. Some exceptions are for fixed brokerless
devices and pre-configured brokers in dedicated installations. A devices and pre-configured brokers in dedicated installations. A
client wishing to create a topic MUST use a CoAP POST to the pub/sub client wishing to create a topic MUST use a CoAP POST to the pub/sub
API with a payload indicating the desired topic. The topic API with a payload indicating the desired topic. The topic
specification sent in the payload MUST use a supported serialization specification sent in the payload MUST use a supported serialization
of the CoRE link format [RFC6690]. The target of the link MUST be a of the CoRE link format [RFC6690]. The target of the link MUST be a
URI formatted string. The client MUST indicate the desired content URI formatted string. The client MUST indicate the desired content
format for publishes to the topic by using the ct (Content Format) format for publishes to the topic by using the ct (Content Format)
link attribute in the link-format payload. Additional link target link attribute in the link-format payload. Additional link target
attributes and relation values may be included in the topic attributes and relation values MAY be included in the topic
specification link whena topic is created. specification link when a topic is created.
The client MAY indicate the lifetime of the topic by including the The client MAY indicate the lifetime of the topic by including the
Max-Age option in the CREATE request. Max-Age option in the CREATE request.
Topic hierarchies can be created by creating parent topics. A parent Topic hierarchies can be created by creating parent topics. A parent
topic is created with a POST using ct (Content Format) link attribute topic is created with a POST using ct (Content Format) link attribute
value which describes a supported serialization of the CoRE link value which describes a supported serialization of the CoRE link
format [RFC6690], such as application/link-format (ct=40) or its JSON format [RFC6690], such as application/link-format (ct=40) or its JSON
or CBOR serializations. If a topic is created which describes a link or CBOR serializations. If a topic is created which describes a link
serialization, that topic may then have sub-topics created under it serialization, that topic may then have sub-topics created under it
as shown in Figure 7. as shown in Figure 7.
Ony one level in the topic hierarchy may be created as a result of a Ony one level in the topic hierarchy may be created as a result of a
CREATE operation, unless create on PUBLISH is supported (see CREATE operation, unless create on PUBLISH is supported (see
Section 4.3). The topic string used in the link target MUST NOT Section 4.3). The topic string used in the link target MUST NOT
contain the "/" character. contain the "/" character.
A topic creator MUST include exactly one content format link A topic creator MUST include exactly one content format link
attribute value (ct) in the create payload. If the Broker does not attribute value (ct) in the create payload. If the content format
support the indicated format for both publish and subscribe, or if option is not included or if the option is repeated, the Broker MUST
there is more than one "ct" value included in the request, the Broker reject the operation with an error code of "4.00 Bad Request".
MUST reject the operation with an error code of 4.00 "Bad Request".
Only one topic may be created per request. If there is more than one Only one topic may be created per request. If there is more than one
link included in a CREATE request, the Broker MUST reject the link included in a CREATE request, the Broker MUST reject the
operation with an erroro code of 4.00 "Bad Request". operation with an error code of "4.00 Bad Request".
There is no default content format. If no ct is specified, the
Broker MUST reject the operation with an error code of 4.00 "Bad
Request".
A Broker MUST return a response code of "2.01 Created" if the topic A Broker MUST return a response code of "2.01 Created" if the topic
is created and return the URI path of the created topic via Location- is created and MUST return the URI path of the created topic via
Path options. The Broker MUST return the appropriate 4.xx response Location-Path options. If a new topic can not be created, the Broker
code indicating the reason for failure if a new topic can not be MUST return the appropriate 4.xx response code indicating the reason
created. Broker SHOULD remove topics if the Max-Age of the topic is for failure.
exceeded without any publishes to the topic. Broker SHOULD retain a
topic indefinitely if the Max-Age option is elided or is set to zero A Broker SHOULD remove topics if the Max-Age of the topic is exceeded
upon topic creation. The lifetime of a topic MUST be refreshed upon without any publishes to the topic. A Broker SHOULD retain a topic
indefinitely if the Max-Age option is elided or is set to zero upon
topic creation. The lifetime of a topic MUST be refreshed upon
create operations with a target of an existing topic. create operations with a target of an existing topic.
A topic creator SHOULD PUBLISH an initial value to a newly-created
Topic in order to enable responses to READ and SUBSCRIBE requests
that may be submitted after the topic is discoverable.
The CREATE interface is specified as follows: The CREATE interface is specified as follows:
Interaction: Client -> Broker Interaction: Client -> Broker
Method: POST Method: POST
URI Template: {+ps}/{+topic} URI Template: {+ps}/{+topic}
URI Template Variables: ps := Pub/sub REST API entry point URI Template Variables: ps := Pub/sub REST API entry point
(optional). The entry point of the pub/sub REST API, as obtained (optional). The entry point of the pub/sub REST API, as obtained
from discovery, used to discover topics. from discovery, used to discover topics.
topic := The desired topic to return links for (optional). topic := The desired topic to return links for (optional).
Content-Format: application/link-format Content-Format: application/link-format
skipping to change at page 10, line 24 skipping to change at page 10, line 38
Payload: The desired topic to CREATE Payload: The desired topic to CREATE
The following response codes are defined for the CREATE operation: The following response codes are defined for the CREATE operation:
Success: 2.01 "Created". Successful Creation of the topic Success: 2.01 "Created". Successful Creation of the topic
Failure: 4.00 "Bad Request". Malformed request. Failure: 4.00 "Bad Request". Malformed request.
Failure: 4.01 "Unauthorized". Authorization failure. Failure: 4.01 "Unauthorized". Authorization failure.
Failure: 4.03 "Forbidden". Topic already exists.
Failure: 4.06 "Not Acceptable". Unsupported content format for
topic.
Figure 6 shows an example of a topic called "topic1" being Figure 6 shows an example of a topic called "topic1" being
successfully created. successfully created.
Client Broker Client Broker
| | | |
| ---------- POST /ps/ "<topic1>;ct=50" ------->| | ---------- POST /ps/ "<topic1>;ct=50" ------->|
| | | |
| <---------------- 2.01 Created ---------------| | <---------------- 2.01 Created ---------------|
| Location: /ps/topic1 | | Location: /ps/topic1 |
| | | |
skipping to change at page 12, line 24 skipping to change at page 12, line 24
A Broker MAY perform garbage collection of stored representations A Broker MAY perform garbage collection of stored representations
which have been delivered to all subscribers or which have timed out. which have been delivered to all subscribers or which have timed out.
A Broker MAY retain at least one most recently published A Broker MAY retain at least one most recently published
representation to return in response to SUBSCRIBE and READ requests. representation to return in response to SUBSCRIBE and READ requests.
A Broker MUST make a best-effort attempt to notify all clients A Broker MUST make a best-effort attempt to notify all clients
subscribed on a particular topic each time it receives a publish on subscribed on a particular topic each time it receives a publish on
that topic. An example is shown in Figure 10. that topic. An example is shown in Figure 10.
If a client publishes to a Broker without the Max-Age option, the
Broker MUST refresh the topic lifetime with the most recently set
Max-Age value, and the Broker MUST include the most recently set Max-
Age value in the Max-Age option of all notifications.
If a client publishes to a Broker with the Max-Age option, the Broker If a client publishes to a Broker with the Max-Age option, the Broker
MUST include the same value for the Max-Age option in all MUST include the same value for the Max-Age option in all
notifications. notifications.
A Broker MUST use CoAP Notification as described in [RFC7641] to A Broker MUST use CoAP Notification as described in [RFC7641] to
notify subscribed clients. notify subscribed clients.
The PUBLISH operation is specified as follows: The PUBLISH operation is specified as follows:
Interaction: Client -> Broker Interaction: Client -> Broker
skipping to change at page 14, line 12 skipping to change at page 14, line 21
client to a list of observers. The Broker MUST return a response client to a list of observers. The Broker MUST return a response
code of "2.05 Content" along with the most recently published value code of "2.05 Content" along with the most recently published value
if the topic contains a valid value and the Broker can supply the if the topic contains a valid value and the Broker can supply the
requested content format. The Broker MUST reject Subscribe requests requested content format. The Broker MUST reject Subscribe requests
on a topic if the content format of the request is not the content on a topic if the content format of the request is not the content
format the topic was created with. format the topic was created with.
If the topic was published with the Max-Age option, the Broker MUST If the topic was published with the Max-Age option, the Broker MUST
set the Max-Age option in the valid response to the amount of time set the Max-Age option in the valid response to the amount of time
remaining for the value to be valid since the last publish operation remaining for the value to be valid since the last publish operation
on that topic. The Broker MUST return a response code of "2.07 No on that topic.
Content" if the topic has not yet been published to, or if Max-Age of
the previously stored value has expired. The Broker MUST return a The Broker MUST return a response code "4.04 Not Found" if the topic
response code "4.04 Not Found" if the topic does not exist or has does not exist or has been removed, or if Max-Age of a previously
been removed. published representation has expired.
If a Topic has been created but not yet published to when a SUBSCRIBE
to the topic is received, the Broker MAY acknowledge and queue the
pending SUBSCRIBE and defer the response until an initial PUBLISH
occurs.
The Broker MUST return a response code "4.15 Unsupported Content The Broker MUST return a response code "4.15 Unsupported Content
Format" if it can not return the requested content format. If a Format" if it can not return the requested content format. If a
Broker is unable to accept a new Subscription on a topic, it SHOULD Broker is unable to accept a new Subscription on a topic, it SHOULD
return the appropriate response code without the Observe option as return the appropriate response code without the Observe option as
per [RFC7641] Section 4.1. per [RFC7641] Section 4.1.
There is no explicit maximum lifetime of a Subscription, thus a There is no explicit maximum lifetime of a Subscription, thus a
Broker may remove subscribers at any time. The Broker, upon removing Broker may remove subscribers at any time. The Broker, upon removing
a Subscriber, will transmit the appropriate response code without the a Subscriber, will transmit the appropriate response code without the
skipping to change at page 15, line 5 skipping to change at page 15, line 15
(optional). The entry point of the pub/sub REST API, as obtained (optional). The entry point of the pub/sub REST API, as obtained
from discovery, used to discover topics. from discovery, used to discover topics.
topic := The desired topic to return links for (optional). topic := The desired topic to return links for (optional).
The following response codes are defined for the SUBSCRIBE operation: The following response codes are defined for the SUBSCRIBE operation:
Success: 2.05 "Content". Successful subscribe, current value Success: 2.05 "Content". Successful subscribe, current value
included included
Success: 2.07 "No Content". Successful subscribe, value not
included
Failure: 4.00 "Bad Request". Malformed request. Failure: 4.00 "Bad Request". Malformed request.
Failure: 4.01 "Unauthorized". Authorization failure. Failure: 4.01 "Unauthorized". Authorization failure.
Failure: 4.04 "Not Found". Topic does not exist. Failure: 4.04 "Not Found". Topic does not exist.
Failure: 4.15 "Unsupported Content Format". Unsupported content Failure: 4.15 "Unsupported Content Format". Unsupported content
format. format.
Figure 10 shows an example of Client2 subscribing to "topic1" and Figure 10 shows an example of Client2 subscribing to "topic1" and
skipping to change at page 17, line 9 skipping to change at page 17, line 25
A CoAP pub/sub Broker MAY accept Read requests on a topic using the A CoAP pub/sub Broker MAY accept Read requests on a topic using the
the CoAP GET method if the content format of the request matches the the CoAP GET method if the content format of the request matches the
content format the topic was created with. The Broker MUST return a content format the topic was created with. The Broker MUST return a
response code of "2.05 Content" along with the most recently response code of "2.05 Content" along with the most recently
published value if the topic contains a valid value and the Broker published value if the topic contains a valid value and the Broker
can supply the requested content format. can supply the requested content format.
If the topic was published with the Max-Age option, the Broker MUST If the topic was published with the Max-Age option, the Broker MUST
set the Max-Age option in the valid response to the amount of time set the Max-Age option in the valid response to the amount of time
remaining for the topic to be valid since the last publish. The remaining for the value to be valid since the last publish operation
Broker MUST return a response code of "2.07 No Content" if the Max- on that topic.
Age of the previously stored value has expired, or if the topic has
not yet been published to.
The Broker MUST return a response code "4.04 Not Found" if the topic The Broker MUST return a response code "4.04 Not Found" if the topic
does not exist or has been removed. The Broker MUST return a does not exist or has been removed, or if Max-Age of a previously
response code "4.15 Unsupported Content Format" if the Broker can not published representation has expired.
return the requested content format.
If a Topic has been created but not yet published to when a READ to
the topic is received, the Broker MAY acknowledge and queue the
pending READ, and defer the response until an initial PUBLISH occurs.
The Broker MUST return a response code "4.15 Unsupported Content
Format" if the Broker can not return the requested content format.
The READ operation is specified as follows: The READ operation is specified as follows:
Interaction: Client -> Broker Interaction: Client -> Broker
Method: GET Method: GET
URI Template: {+ps}/{+topic} URI Template: {+ps}/{+topic}
URI Template Variables: ps := Pub/sub REST API entry point URI Template Variables: ps := Pub/sub REST API entry point
(optional). The entry point of the pub/sub REST API, as obtained (optional). The entry point of the pub/sub REST API, as obtained
from discovery, used to discover topics. from discovery, used to discover topics.
topic := The desired topic to return links for (optional). topic := The desired topic to return links for (optional).
The following response codes are defined for the READ operation: The following response codes are defined for the READ operation:
Success: 2.05 "Content". Successful READ, current value included Success: 2.05 "Content". Successful READ, current value included
Success: 2.07 "No Content". Topic exists, value not included
Failure: 4.00 "Bad Request". Malformed request. Failure: 4.00 "Bad Request". Malformed request.
Failure: 4.01 "Unauthorized". Authorization failure. Failure: 4.01 "Unauthorized". Authorization failure.
Failure: 4.04 "Not Found". Topic does not exist. Failure: 4.04 "Not Found". Topic does not exist.
Failure: 4.15 "Unsupported Content Format". Unsupported content- Failure: 4.15 "Unsupported Content Format". Unsupported content-
format. format.
Figure 12 shows an example of a successful READ from topic1, followed Figure 12 shows an example of a successful READ from topic1, followed
skipping to change at page 20, line 36 skipping to change at page 21, line 9
7. Simple Flow Control 7. Simple Flow Control
Since the Broker node has to potentially send a large amount of Since the Broker node has to potentially send a large amount of
notification messages for each publish message and it may be serving notification messages for each publish message and it may be serving
a large amount of subscribers and publishers simultaneously, the a large amount of subscribers and publishers simultaneously, the
Broker may become overwhelmed if it receives many publish messages to Broker may become overwhelmed if it receives many publish messages to
popular topics in a short period of time. popular topics in a short period of time.
If the Broker is unable to serve a certain client that is sending If the Broker is unable to serve a certain client that is sending
publish messages too fast, the Broker SHOULD respond with Response publish messages too fast, the Broker SHOULD respond with Response
Code 4.29, "Too Many Requests" [I-D.ietf-core-too-many-reqs] and set Code 4.29, "Too Many Requests" [RFC8516] and set the Max-Age Option
the Max-Age Option to indicate the number of seconds after which the to indicate the number of seconds after which the client can retry.
client can retry. The Broker MAY stop creating notifications from The Broker MAY stop creating notifications from the publish messages
the publish messages from this client and to this topic for the from this client and to this topic for the indicated time.
indicated time.
If a client receives the 4.29 Response Code from the Broker for a If a client receives the 4.29 Response Code from the Broker for a
publish message to a topic, it MUST NOT send new publish messages to publish message to a topic, it MUST NOT send new publish messages to
the Broker on the same topic before the time indicated in Max-Age has the Broker on the same topic before the time indicated in Max-Age has
passed. passed.
8. Security Considerations 8. Security Considerations
CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory CoAP pub/sub re-uses CoAP [RFC7252], CoRE Resource Directory
[I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and [I-D.ietf-core-resource-directory], and Web Linking [RFC5988] and
skipping to change at page 22, line 31 skipping to change at page 22, line 47
9.2. Resource Type value 'core.ps.discover' 9.2. Resource Type value 'core.ps.discover'
o Attribute Value: core.ps.discover o Attribute Value: core.ps.discover
o Description: Section 4 of [[This document]] o Description: Section 4 of [[This document]]
o Reference: [[This document]] o Reference: [[This document]]
o Notes: None o Notes: None
9.3. Response Code value '2.07'
o Response Code: 2.07
o Description: No Content
o Reference: [[This document]]
o Notes: The server sends this code to the client to indicate that
the request was valid and accepted, but the response may contain
an empty payload. It is comparable to and may be proxied with the
HTTP 204 No Content status code.
10. Acknowledgements 10. Acknowledgements
The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit The authors would like to thank Hannes Tschofenig, Zach Shelby, Mohit
Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran
Selander, Mikko Majanen, and Olaf Bergmann for their contributions Selander, Mikko Majanen, and Olaf Bergmann for their contributions
and reviews. and reviews.
11. References 11. References
11.1. Normative References 11.1. Normative References
[I-D.ietf-core-too-many-reqs]
Keranen, A., "Too Many Requests Response Code for the
Constrained Application Protocol", draft-ietf-core-too-
many-reqs-06 (work in progress), November 2018.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, <https://www.rfc- DOI 10.17487/RFC2119, March 1997, <https://www.rfc-
editor.org/info/rfc2119>. editor.org/info/rfc2119>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/info/rfc3986>. <https://www.rfc-editor.org/info/rfc3986>.
skipping to change at page 23, line 43 skipping to change at page 23, line 40
[RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
Application Protocol (CoAP)", RFC 7252, Application Protocol (CoAP)", RFC 7252,
DOI 10.17487/RFC7252, June 2014, <https://www.rfc- DOI 10.17487/RFC7252, June 2014, <https://www.rfc-
editor.org/info/rfc7252>. editor.org/info/rfc7252>.
[RFC7641] Hartke, K., "Observing Resources in the Constrained [RFC7641] Hartke, K., "Observing Resources in the Constrained
Application Protocol (CoAP)", RFC 7641, Application Protocol (CoAP)", RFC 7641,
DOI 10.17487/RFC7641, September 2015, <https://www.rfc- DOI 10.17487/RFC7641, September 2015, <https://www.rfc-
editor.org/info/rfc7641>. editor.org/info/rfc7641>.
[RFC8516] Keranen, A., ""Too Many Requests" Response Code for the
Constrained Application Protocol", RFC 8516,
DOI 10.17487/RFC8516, January 2019, <https://www.rfc-
editor.org/info/rfc8516>.
11.2. Informative References 11.2. Informative References
[I-D.ietf-core-object-security] [I-D.ietf-core-object-security]
Selander, G., Mattsson, J., Palombini, F., and L. Seitz, Selander, G., Mattsson, J., Palombini, F., and L. Seitz,
"Object Security for Constrained RESTful Environments "Object Security for Constrained RESTful Environments
(OSCORE)", draft-ietf-core-object-security-15 (work in (OSCORE)", draft-ietf-core-object-security-16 (work in
progress), August 2018. progress), March 2019.
[I-D.ietf-core-resource-directory] [I-D.ietf-core-resource-directory]
Shelby, Z., Koster, M., Bormann, C., Stok, P., and C. Shelby, Z., Koster, M., Bormann, C., Stok, P., and C.
Amsuess, "CoRE Resource Directory", draft-ietf-core- Amsuess, "CoRE Resource Directory", draft-ietf-core-
resource-directory-18 (work in progress), December 2018. resource-directory-20 (work in progress), March 2019.
[I-D.palombini-ace-coap-pubsub-profile] [I-D.palombini-ace-coap-pubsub-profile]
Palombini, F., "CoAP Pub-Sub Profile for Authentication Palombini, F., "CoAP Pub-Sub Profile for Authentication
and Authorization for Constrained Environments (ACE)", and Authorization for Constrained Environments (ACE)",
draft-palombini-ace-coap-pubsub-profile-03 (work in draft-palombini-ace-coap-pubsub-profile-03 (work in
progress), June 2018. progress), June 2018.
[RFC5988] Nottingham, M., "Web Linking", RFC 5988, [RFC5988] Nottingham, M., "Web Linking", RFC 5988,
DOI 10.17487/RFC5988, October 2010, <https://www.rfc- DOI 10.17487/RFC5988, October 2010, <https://www.rfc-
editor.org/info/rfc5988>. editor.org/info/rfc5988>.
 End of changes. 36 change blocks. 
86 lines changed or deleted 88 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/