Draft: draft-ietf-core-pubsub

Commentary: address email comments and more cleanup of terminology
This specification requires readers to be familiar with all the terms
and concepts that are discussed in RFC5988 and RFC6690.  Readers
should also be familiar with the terms and concepts discussed in
RFC7252 and I-D.ietf-core-resource-directory.  The URI template
format RFC6570 is used to describe the REST interfaces defined in
this specification.
This specification requires readers to be familiar with all the terms
and concepts that are discussed in RFC5988 and RFC6690.  Readers
should also be familiar with the terms and concepts discussed in
RFC7252 and I-D.ietf-core-resource-directory.  The URI template
format RFC6570 is used to describe the REST API defined in this
specification.
The clients and broker use topics to identify a particular resource
or object in a publish-subscribe system.  Topics are conventionally
formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or
"EP-33543/sen/3303/0/5700".  The topics are hosted at the broker and
all the clients using the broker share the same namespace for topics.
Every CoAP pub/sub topic has a link, consisting of a reference path
on the broker using URI path RFC3986 construction and link attributes
RFC6690.  Every topic is associated with zero or more stored
representations with a content-format specified in the link.  A CoAP
pub/sub topic value may alternatively be a collection of one or more
sub-topics, consisting of links to the sub-topic URIs and indicated
by a link-format content-format.
brokerless shows an arrangement for using CoAP pub/sub in a
"brokerless" configuration between peer nodes.  Nodes in a brokerless
system may act as both broker and client.  The Broker interface in a
brokerless node may be pre-configured with topics that expose
services and resources.  Brokerless peer nodes can be mixed with
client and broker nodes in a system with full interoperability.
The clients and Broker use topics to identify a particular resource
or object in a publish-subscribe system.  Topics are conventionally
formed as a hierarchy, e.g. "/sensors/weather/barometer/pressure" or
"/EP-33543/sen/3303/0/5700".  The topics are hosted by a Broker and
all the clients using the Broker share the same namespace for topics.
Every CoAP pub/sub topic has an associated link, consisting of a
reference path on the Broker using URI path RFC3986 construction and
link attributes RFC6690.  Every topic is associated with zero or more
stored representations and a content-format specified in the 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-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 structure of
unique paths that is implemented using URIs.  The full URI of a topic
includes a schems and authority for the Broker, for example
"coaps://10.0.0.13:5684/EP-33543/sen/3303/0/5700".
brokerless shows an arrangement for using CoAP pub/sub in a
"Brokerless" configuration between peer nodes.  Nodes in a Brokerless
system may act as both Broker and client.  A node that supports
Broker functionality may be pre-configured with topics that expose
services and resources.  Brokerless peer nodes can be mixed with
client and Broker nodes in a system with full interoperability.
A CoAP pub/sub Broker MAY expose the Discover interface 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. discover-topic-
wk-fig shows an example of topic discovery through .well-known/core.
A CoAP pub/sub Broker MAY provide topic discovery functionality
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.
discover-topic-wk-fig shows an example of topic discovery through
.well-known/core.
Ony one level in the topic hierarchy may be created as a result of a
CREATE operation, unless create on PUBLISH is supported (see sec-
publish).  The topic string used in the link target MUST NOT contain
the "/" character.
A topic creator MUST include exactly one content format link
attribute value (ct) in the create payload.  If the Broker does not
support the indicated format for both publish and subscribe, it MUST
reject the 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".
Create on PUBLISH: A Broker MAY accept PUBLISH operations to new
topics using the PUT method.  If a Broker accepts a PUBLISH using PUT
to a topic that does not exist, the Broker MUST create the topic
using the information in the PUT operation.  The Broker MUST create a
topic with the URI-Path of the request, including all of the sub-
topics necessary, and create a topic link with the ct attribute set
to the content-format of the payload of the PUT request.  If topic is
created, the Broker MUST return the response "2.01 Created" with the
URI of the created topic, including all of the created path segments,
returned via the Location-Path option.
A Broker MAY accept PUBLISH operations using the POST method.  If a
broker accepts PUBLISH using POST it shall respond with the 2.04
Changed status code.
Create on PUBLISH: A Broker MAY accept PUBLISH operations to new
topics using the PUT method.  If a Broker accepts a PUBLISH using PUT
to a topic that does not exist, the Broker MUST create the topic
using the information in the PUT operation.  The Broker MUST create a
topic with the URI-Path of the request, including all of the sub-
topics necessary, and create a topic link with the ct attribute set
to the content-format value from the header of the PUT request.  If
topic is created, the Broker MUST return the response "2.01 Created"
with the URI of the created topic, including all of the created path
segments, returned via the Location-Path option.
create-publish-fig shows an example of a topic being created on first
PUBLISH.
A Broker MAY accept PUBLISH operations using the POST method.  If a
Broker accepts PUBLISH using POST it shall respond with the 2.04
Changed status code.  If an attempt is made to PUBLISH using POST to
a topic that does not exist, the Broker SHALL return a response
status indicating resource not found, such as HTTP 404 or CoAP 4.04.
A Broker MUST make a best-effort attempt to notify all clients
subscribed on a particular topic each time it receives a publish on
that topic.  An example is shown in subscribe-fig.  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 notifications.
A broker MUST use CoAP Notification as described in RFC7641 to notify
subscribed 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
that topic.  An example is shown in subscribe-fig.
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
notifications.
A Broker MUST use CoAP Notification as described in RFC7641 to notify
subscribed clients.
A CoAP pub/sub broker MAY allow Clients to subscribe to topics on the
Broker using CoAP Observe as described in RFC7641.  A CoAP pub/sub
Client wishing to Subscribe to a topic on a broker MUST use a CoAP
GET with the Observe option set to 0 (zero).  The Broker MAY add the
client to a list of observers.  The Broker MUST return a response
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
requested content format.  The broker MUST reject Subscribe requests
on a topic if the content format of the request is not supported by
the content format the topic was created with.  The broker MAY accept
Subscribe requests which specify content formats that the broker can
supply as alternate content formats to the content format the topic
was registered with.  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 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 Content" if the Max-Age of the previously
stored value has expired.  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 response code "4.15 Unsupported Content
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
return the appropriate response code without the Observe option as
per as per RFC7641 Section 4.1.  There is no explicit maximum
lifetime of a Subscription, thus a Broker may remove subscribers at
any time.  The Broker, upon removing a Subscriber, will transmit the
appropriate response code without the Observe option, as per RFC7641
Section 4.2, to the removed Subscriber.
A CoAP pub/sub Broker MAY allow Clients to subscribe to topics on the
Broker using CoAP Observe as described in RFC7641.  A CoAP pub/sub
Client wishing to Subscribe to a topic on a Broker MUST use a CoAP
GET with the Observe option set to 0 (zero).  The Broker MAY add the
client to a list of observers.  The Broker MUST return a response
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
requested content format.  The Broker MUST reject Subscribe requests
on a topic if the content format of the request is not the content
format the topic was created with.
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
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
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
response code "4.04 Not Found" if the topic does not exist or has
been removed.
The Broker MUST return a response code "4.15 Unsupported Content
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
return the appropriate response code without the Observe option as
per RFC7641 Section 4.1.
There is no explicit maximum lifetime of a Subscription, thus a
Broker may remove subscribers at any time.  The Broker, upon removing
a Subscriber, will transmit the appropriate response code without the
Observe option, as per RFC7641 Section 4.2, to the removed
Subscriber.
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
content format the topic was created with.  The broker MAY accept
Read requests which specify content formats that the broker can
supply as alternate content formats to the content format the topic
was registered with.  The Broker MUST return a response 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 requested
content format.  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 remaining for the topic to be valid since the last
publish.  The Broker MUST return a response code of "2.07 No Content"
if the Max-Age of the previously stored value has expired.  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 response
code "4.15 Unsupported Content Format" if the broker can not return
the requested content format.
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
content format the topic was created with.  The Broker MAY accept
Read requests which specify content formats that the Broker can
supply as alternate content formats to the content format the topic
was registered with.  The Broker MUST return a response 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 requested
content format.
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
remaining for the topic to be valid since the last publish.  The
Broker MUST return a response code of "2.07 No Content" if the Max-
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
does not exist or has been removed.  The Broker MUST return a
response code "4.15 Unsupported Content Format" if the Broker can not
return the requested content format.
A CoAP pub/sub broker MAY allow clients to remove topics from the
broker using the CoAP Delete method on the URI of the topic.  The
CoAP pub/sub Broker MUST return "2.02 Deleted" if the removal is
successful.  The broker MUST return the appropriate 4.xx response
code indicating the reason for failure if the topic can not be
removed.  When a topic is removed for any reason, the Broker SHOULD
return the response code 4.04 Not Found and remove all of the
observers from the list of observers as per as per RFC7641
Section 3.2.  If a topic which has sub-topics is removed, then all of
its sub-topics MUST be recursively removed.
A CoAP pub/sub Broker MAY allow clients to remove topics from the
Broker using the CoAP Delete method on the URI of the topic.  The
CoAP pub/sub Broker MUST return "2.02 Deleted" if the removal is
successful.  The Broker MUST return the appropriate 4.xx response
code indicating the reason for failure if the topic can not be
removed.
When a topic is removed for any reason, the Broker SHOULD remove all
of the observers from the list of observers and return a final 4.04
"Not Found" response as per RFC7641 Section 3.2.  If a topic which
has sub-topics is removed, then all of its sub-topics MUST be
recursively removed.