diff --git a/ps-rev/draft-ietf-core-coap-pubsub.html b/ps-rev/draft-ietf-core-coap-pubsub.html index 7d2b905..02e4f14 100644 --- a/ps-rev/draft-ietf-core-coap-pubsub.html +++ b/ps-rev/draft-ietf-core-coap-pubsub.html @@ -1164,9 +1164,11 @@

topic-configuration:
-

An entry within a topic collection in a broker. A topic-configuration resource is used for configuration purposes before any data can be published. CoAP clients can propose new topics to be created, but it is up to the broker to decide whether and how a topic is created. The broker also decides the URI of each topic-configuration and the topic-data resource when hosted at the broker. The creation, configuration, and discovery of topics at a broker are specified in Section 2. The lifecycle of a topic is specified in Section 2.6.1. Interactions about the topic-data are defined in Section 2.7. The topic-configuration URI is NOT used to to publish and subscribe to data. Throughout this document the word "topic" and "topic-configuration" can appear interchangeably.

+

An entry within a topic collection in a broker. A topic-configuration resource is used for configuration purposes before any data can be published. CoAP clients can propose new topics to be created, but it is up to the broker to decide whether and how a topic is created. The broker also decides the URI of each topic-configuration and the topic-data resource when hosted at the broker. The creation, configuration, and discovery of topics at a broker are specified in Section 2. The lifecycle of a topic is specified in Section 3.1. Interactions about the topic-data are defined in Section 3.3. The topic-configuration URI is NOT used to to publish and subscribe to data. Throughout this document the word "topic" and "topic-configuration" can appear interchangeably.

topic-data resource:
@@ -1355,7 +1357,7 @@

broker:
-

A CoAP server that hosts one or more topic collections containing topic-configurations and sometimes also topic-data resources. The broker is responsible for the store-and-forward of state update representations when the topic-data URI points to a resource hosted on the broker. The broker is also responsible of handling the topic lifecycle as defined in Section 2.6.1. The creation, configuration, and discovery of topics at a broker is specified in Section 2.

+

A CoAP server that hosts one or more topic collections containing topic-configurations and sometimes also topic-data resources. The broker is responsible for the store-and-forward of state update representations when the topic-data URI points to a resource hosted on the broker. The broker is also responsible of handling the topic lifecycle as defined in Section 3.1. The creation, configuration, and discovery of topics at a broker is specified in Section 2.

@@ -1437,7 +1439,7 @@

Publish-subscribe architecture over CoAP -

This document describes two sets of interactions, interactions to configure topics and their lifecycle (see Section 2.5) and interactions about the topic-data (see Section 2.7).

+

This document describes two sets of interactions, interactions to configure topics and their lifecycle (see Section 2.5) and interactions about the topic-data (see Section 3.3).

Topic-configuration interactions are discovery, create, read configuration, update configuration, delete configuration and handle the management of the topics.

Topic-data interactions are publish, subscribe, unsubscribe, read and are oriented on how data is transferred from a publisher to a subscriber.

@@ -1496,7 +1498,7 @@

Resources of a Broker -

The Broker exports a topic-collection resource, with resource type "core.ps.coll" defined in Section 5 of this document. The interfaces for the topic-collection resource is defined in Section 2.4.

+

The Broker exports a topic-collection resource, with resource type "core.ps.coll" defined in Section 6 of this document. The interfaces for the topic-collection resource is defined in Section 2.4.

@@ -1676,13 +1678,13 @@

A CoAP client can create a new topic by submitting an initial configuration for the topic (see Section 2.4.3). It can also read and update the configuration of existing topics and delete them when they are no longer needed (see Section 2.5).

The configuration of a topic itself consists of a set of properties that can be set by a client or by the broker. The topic-configuration is represented as a CBOR map containing the configuration properties of the topic as top-level elements.

-

Unless specified otherwise, these are defined in this document and their CBOR abbreviations are defined in Section 3.

+

Unless specified otherwise, these are defined in this document and their CBOR abbreviations are defined in Section 4.

2.2.1. Topic Properties

-

The CBOR map includes the following configuration parameters, whose CBOR abbreviations are defined in Section 3 of this document.

+

The CBOR map includes the following configuration parameters, whose CBOR abbreviations are defined in Section 4 of this document.

-
-
-
-

-2.2.2. Default Values -

-

Below are the defined default values for the topic parameters:

+
+
+2.2.1.1. Default Values +
+

Below are the defined default values for the topic parameters:

    -
  • -

    'topic-name': There is no default value. This field is required and must be specified by the client or broker.

    +
  • +

    'topic-name': There is no default value. This field is required and must be specified by the client or broker.

    • -
  • -

    'topic-data': There is no default value. This field is required and must be specified by the client or broker.

    +
  • +

    'topic-data': There is no default value. This field is required and must be specified by the client or broker.

    • -
  • -

    'resource-type': The default value for a topic resource is "core.ps.conf".

    +
  • +

    'resource-type': The default value for a topic resource is "core.ps.conf".

    • -
  • -

    'media-type': The default value is an empty string, indicating that no media type is specified.

    +
  • +

    'media-type': The default value is an empty string, indicating that no media type is specified.

    • -
  • -

    'target-attribute': The default value is an empty string, indicating that no attribute is specified.

    +
  • +

    'target-attribute': The default value is an empty string, indicating that no attribute is specified.

    • -
  • -

    'expiration-date': The default value is an empty string, indicating that no expiration date is specified. If this field is not present, the topic will not expire automatically.

    +
  • +

    'expiration-date': The default value is an empty string, indicating that no expiration date is specified. If this field is not present, the topic will not expire automatically.

    • -
  • -

    'max-subscribers': The default value is -1, indicating that there is no limit to the number of subscribers allowed. If this field is not present, the pubsub system will not limit the number of subscribers for the topic.

    +
  • +

    'max-subscribers': The default value is -1, indicating that there is no limit to the number of subscribers allowed. If this field is not present, the pubsub system will not limit the number of subscribers for the topic.

    • -
  • -

    'observer-check': The default value is '86400', as defined in [RFC7641], which corresponds to 24 hours.

    +
  • +

    'observer-check': The default value is '86400', as defined in [RFC7641], which corresponds to 24 hours.

    • -
+ +
+
@@ -1760,7 +1762,7 @@

2.3.1. Broker Discovery

-

CoAP clients MAY discover brokers by using CoAP Simple Discovery, via multicast, through a Resource Directory (RD) [RFC9167] or by other means specified in extensions to [RFC7252]. Brokers MAY register with a RD by following the steps on Section 5 of [RFC9167] with the resource type set to "core.ps" as defined in Section 5 of this document.

+

CoAP clients MAY discover brokers by using CoAP Simple Discovery, via multicast, through a Resource Directory (RD) [RFC9167] or by other means specified in extensions to [RFC7252]. Brokers MAY register with a RD by following the steps on Section 5 of [RFC9167] with the resource type set to "core.ps" as defined in Section 6 of this document.

@@ -1896,7 +1898,7 @@

A client can add a new topic-configurations to a collection of topics by submitting a representation of the initial topic resource (see Section Section 2.2) in a POST request to the topic collection URI. The topic MUST contain at least a subset of the Section 2.2.1 , namely: topic-name and resource-type.

A CoAP endpoint creating a topic MAY specify a topic-data URI different than that used by the broker. The broker may then simply forward the observation requests to the topic-data URI as shown in Figure 5.

-

If the topic-data is empty the broker will assign a resource for a publisher to publish to. Please note that the topic will NOT be fully created until a publisher has published some data to it (See Section 2.6.1).

+

If the topic-data is empty the broker will assign a resource for a publisher to publish to. Please note that the topic will NOT be fully created until a publisher has published some data to it (See Section 3.1).

On success, the server returns a 2.01 (Created) response indicating the topic URI of the new topic and the current representation of the topic resource.

If a topic manager is present in the broker, the topic creation may require manager approval subject to certain conditions. If the conditions are not fulfilled, the manager MUST respond with a 4.03 (Forbidden) error. The response MUST have Content-Format set to "application/core-pubsub+cbor".

The broker MUST respond with a 4.00 (Bad Request) error if any received parameter is specified multiple times, invalid or not recognized.

@@ -1941,7 +1943,7 @@

A client can read the configuration of a topic by making a GET request to the topic resource URI.

On success, the server returns a 2.05 (Content) response with a representation of the topic resource. The response has as payload the representation of the topic resource as specified in Section 2.2.

If a topic manager (TBD) is present in the broker, retrieving topic information may require manager approval subject to certain conditions (TBD). If the conditions are not fulfilled, the manager MUST respond with a 4.03 (Forbidden) error. The response MUST have Content-Format set to "application/core-pubsub+cbor".

-

The response payload is a CBOR map, whose possible entries are specified in Section 2.2 and use the same abbreviations defined in Section 3.

+

The response payload is a CBOR map, whose possible entries are specified in Section 2.2 and use the same abbreviations defined in Section 4.

For example, below is a request on the topic "ps/h9392":

@@ -1974,7 +1976,7 @@ 

 
The request contains a CBOR map with a configuration filter or 'conf-filter', a CBOR array with CBOR abbreviation. Each element of the array specifies one requested configuration parameter of the current topic resource (see Section 2.2).

 
On success, the server returns a 2.05 (Content) response with a representation of the topic resource. The response has as payload the partial representation of the topic resource as specified in Section 2.2.

 
If a topic manager (TBD) is present in the broker, retrieving topic information may require manager approval subject to certain conditions (TBD). If the conditions are not fulfilled, the manager MUST respond with a 4.03 (Forbidden) error.

-
The response payload is a CBOR map, whose possible entries are specified in Section 2.2 and use the same abbreviations defined in Section 3.

+
The response payload is a CBOR map, whose possible entries are specified in Section 2.2 and use the same abbreviations defined in Section 4.

 
Both request and response MUST have Content-Format set to "application/core-pubsub+cbor".

 
Example:

 

@@ -2061,121 +2063,121 @@
+ +

-
-

-2.6. Publish and Subscribe -

-

The overview of the publish/subscribe mechanism over CoAP is as follows: a publisher publishes to a topic by submitting the data in a PUT request to a topic-data resource and subscribers subscribe to a topic by submitting a GET request with the Observe option active to a topic-data resource. When resource state changes, subscribers observing the resource [RFC7641] at that time will receive a notification.

-

As shown in Section 2, each topic contains two resources: topic-configuration resource and topic-data. In that section we explained the creation and configuration of the topic-configuration resources. This section will explain the management of topic-data resources.

-

A topic-data resource does not exist until some initial data has been published to it. Before initial data has been published, the topic-data resource yields a 4.04 (Not Found) response. If such a "half created" topic is undesired, the creator of the topic can simply immediately publish some initial placeholder data to make the topic "fully created" (see Section 2.6.1).

-

URIs for topic resources are broker-generated (see Section 2.4.3). URIs for topic-data MAY be broker-generated or client-generated. There is no necessary URI pattern dependence between the URI where the data exists and the URI of the topic resource. Topic resource and data resources might even be hosted on different servers.

+
+

+3. Publish and Subscribe +

+

The overview of the publish/subscribe mechanism over CoAP is as follows: a publisher publishes to a topic by submitting the data in a PUT request to a topic-data resource and subscribers subscribe to a topic by submitting a GET request with the Observe option active to a topic-data resource. When resource state changes, subscribers observing the resource [RFC7641] at that time will receive a notification.

+

As shown in Section 2, each topic contains two resources: topic-configuration resource and topic-data. In that section we explained the creation and configuration of the topic-configuration resources. This section will explain the management of topic-data resources.

+

A topic-data resource does not exist until some initial data has been published to it. Before initial data has been published, the topic-data resource yields a 4.04 (Not Found) response. If such a "half created" topic is undesired, the creator of the topic can simply immediately publish some initial placeholder data to make the topic "fully created" (see Section 3.1).

+

URIs for topic resources are broker-generated (see Section 2.4.3). URIs for topic-data MAY be broker-generated or client-generated. There is no necessary URI pattern dependence between the URI where the data exists and the URI of the topic resource. Topic resource and data resources might even be hosted on different servers.

-
-

-2.6.1. Topic Lifecycle -

-

When a topic is newly created, it is first placed by the server into the HALF CREATED state (see Figure 4). In this state, a client can read and update the configuration of the topic and delete the topic. A publisher can publish to the topic-data resource. However, a subscriber cannot yet observe the topic-data resource nor read the latest data.

+
+

+3.1. Topic Lifecycle +

+

When a topic is newly created, it is first placed by the server into the HALF CREATED state (see Figure 4). In this state, a client can read and update the configuration of the topic and delete the topic. A publisher can publish to the topic-data resource. However, a subscriber cannot yet observe the topic-data resource nor read the latest data.

-
-
+
+
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - HALF - FULLY - CREATED - Delete - CREATED - topic-data - Publish - Create - Publish - Subscribe - Read/ - Read/ - Update - Delete - Delete - Update - Topic - Topic - DELETED - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + HALF + FULLY + CREATED + Delete + CREATED + topic-data + Publish + Create + Publish + Subscribe + Read/ + Read/ + Update + Delete + Delete + Update + Topic + Topic + DELETED + +
Figure 4: Lifecycle of a Topic -
+
-

After a publisher publishes to the topic-data for the first time, the topic is placed into the FULLY CREATED state. In this state, a client can read, update and delete the topic; a publisher can publish to the topic-data resource; and a subscriber can observe the topic-data resource.

-

When a client deletes a topic-configuration resource, the topic is placed into the DELETED state and shortly after removed from the server. In this state, all subscribers are removed from the list of observers of the topic-data resource and no further interactions with the topic are possible.

-

When a client deletes a topic-data, the topic is placed into the HALF CREATED state, where clients can read, update and delete the topic-configuration and await for a publisher to begin publication.

+

After a publisher publishes to the topic-data for the first time, the topic is placed into the FULLY CREATED state. In this state, a client can read, update and delete the topic; a publisher can publish to the topic-data resource; and a subscriber can observe the topic-data resource.

+

When a client deletes a topic-configuration resource, the topic is placed into the DELETED state and shortly after removed from the server. In this state, all subscribers are removed from the list of observers of the topic-data resource and no further interactions with the topic are possible.

+

When a client deletes a topic-data, the topic is placed into the HALF CREATED state, where clients can read, update and delete the topic-configuration and await for a publisher to begin publication.

-
-

-2.6.2. Rate Limiting -

-

The server hosting a data resource may have to handle a potentially very large number of publishers and subscribers at the same time. This means the server can easily become overwhelmed if it receives too many publications in a short period of time.

-

In this situation, if a client is sending publications too fast, the server SHOULD return a 4.29 (Too Many Requests) response [RFC8516]. As described in [RFC8516], the Max-Age option [RFC7252] in this response indicates the number of seconds after which the client may retry. The Broker MAY stop publishing messages from the client for the indicated time.

-

When a client receives a 4.29 (Too Many Requests) response, it MUST NOT send any new publication requests to the same topic-data resource before the time indicated by the Max-Age option has passed.

-
-
+
+

+3.2. Rate Limiting +

+

The server hosting a data resource may have to handle a potentially very large number of publishers and subscribers at the same time. This means the server can easily become overwhelmed if it receives too many publications in a short period of time.

+

In this situation, if a client is sending publications too fast, the server SHOULD return a 4.29 (Too Many Requests) response [RFC8516]. As described in [RFC8516], the Max-Age option [RFC7252] in this response indicates the number of seconds after which the client may retry. The Broker MAY stop publishing messages from the client for the indicated time.

+

When a client receives a 4.29 (Too Many Requests) response, it MUST NOT send any new publication requests to the same topic-data resource before the time indicated by the Max-Age option has passed.

-
+

-2.7. Topic-Data Interactions +3.3. Topic-Data Interactions

-

Interactions with the topic-data resource are covered in this section. The interactions with topic-data are same as that of any other CoAP resource.

-

One variant shown in Figure 5 is where the resource is hosted. While the broker can create a topic-data resource when the topic is created, the client can select to host the data in a different CoAP server than that of the topic resource.

+

Interactions with the topic-data resource are covered in this section. The interactions with topic-data are same as that of any other CoAP resource.

+

One variant shown in Figure 5 is where the resource is hosted. While the broker can create a topic-data resource when the topic is created, the client can select to host the data in a different CoAP server than that of the topic resource.

-
-
+
+
@@ -2281,7 +2283,7 @@

: :.......: - +

Figure 5: @@ -2289,18 +2291,18 @@

-
+

-2.7.1. Publish +3.3.1. Publish

-

A topic-configuration with a topic-data resource must have been created in order to publish data to it (See Section Section 2.4.3) and be in the half-created state in order to the publish operation to work (see Section 2.6.1).

-

A client can publish data to a topic by submitting the data in a PUT request to the topic-data URI as indicated in its topic resource property. Please note that the topic-data URI is not the same as the topic-configuration URI used for configuring the topic (see Section 2.2).

-

On success, the server returns a 2.04 (Updated) response. However, when data is published to the topic for the first time, the server instead MUST return a 2.01 (Created) response and set the topic in the fully-created state (see Section 2.6.1).

-

If the request does not have an acceptable content format, the server returns a 4.15 (Unsupported Content Format) response.

-

If the client is sending publications too fast, the server returns a -4.29 (Too Many Requests) response [RFC8516].

-

Example of first publication:

-
+

A topic-configuration with a topic-data resource must have been created in order to publish data to it (See Section Section 2.4.3) and be in the half-created state in order to the publish operation to work (see Section 3.1).

+

A client can publish data to a topic by submitting the data in a PUT request to the topic-data URI as indicated in its topic resource property. Please note that the topic-data URI is not the same as the topic-configuration URI used for configuring the topic (see Section 2.2).

+

On success, the server returns a 2.04 (Updated) response. However, when data is published to the topic for the first time, the server instead MUST return a 2.01 (Created) response and set the topic in the fully-created state (see Section 3.1).

+

If the request does not have an acceptable content format, the server returns a 4.15 (Unsupported Content Format) response.

+

If the client is sending publications too fast, the server returns a +4.29 (Too Many Requests) response [RFC8516].

+

Example of first publication:

+
 => 0.03 PUT
    Uri-Path: ps
@@ -2316,10 +2318,10 @@ 

    }
 
 <= 2.01 Created
-
+
-

Example of subsequent publication:

-
+

Example of subsequent publication:

+
 => 0.03 PUT
    Uri-Path: ps
@@ -2335,34 +2337,34 @@ 

    }
 
 <= 2.04 Updated
-
+
-
+

-2.7.2. Subscribe +3.3.2. Subscribe

-

A client can subscribe to a topic by sending a CoAP GET request with the Observe set to '0' to subscribe to resource updates. [RFC7641].

-

On success, the broker MUST return 2.05 (Content) notifications with the data.

-

If the topic is not yet in the fully created state (see Section 2.6.1) the broker SHOULD return a response code 4.04 (Not Found).

-

The following response codes are defined for the Subscribe operation:

-
-
Success:
-
-

2.05 "Content". Successful subscribe with observe response, current value included in the response.

+

A client can subscribe to a topic by sending a CoAP GET request with the Observe set to '0' to subscribe to resource updates. [RFC7641].

+

On success, the broker MUST return 2.05 (Content) notifications with the data.

+

If the topic is not yet in the fully created state (see Section 3.1) the broker SHOULD return a response code 4.04 (Not Found).

+

The following response codes are defined for the Subscribe operation:

+
+
Success:
+
+

2.05 "Content". Successful subscribe with observe response, current value included in the response.

-
Failure:
-
-

4.04 "Not Found". Topic does not exist.

+
Failure:
+
+

4.04 "Not Found". Topic does not exist.

-

If the 'max-clients' parameter has been reached, the server must treat that as specified in section 4.1 of [RFC7641]. The response MUST NOT include an Observe Option, the absence of which signals to the subscriber that the subscription failed.

-

Example:

-
+

If the 'max-clients' parameter has been reached, the server must treat that as specified in section 4.1 of [RFC7641]. The response MUST NOT include an Observe Option, the absence of which signals to the subscriber that the subscription failed.

+

Example:

+
 => 0.01 GET
    Uri-Path: ps
@@ -2395,31 +2397,31 @@ 

     "t": 1696340182,
     "v": 21.87
   }
-
+
-
+

-2.7.3. Unsubscribe +3.3.3. Unsubscribe

-

A CoAP client can unsubscribe simply by cancelling the observation as described in Section 3.6 of [RFC7641]. The client MUST either use CoAP GET with the Observe Option set to 1 or send a CoAP Reset message in response to a notification.

-

In some circumstances, it may be desirable to cancel an observation and release the resources allocated by the broker. In this case, a client MAY explicitly deregister by issuing a GET request 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).

-

As per [RFC7641] 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 value can be modified at the broker by the administrator of a topic by modifying the parameter "observer-check" on Section 2.2. This would allow to change the rate at which different implementations verify that a subscriber is still interested in observing a topic-data resource.

+

A CoAP client can unsubscribe simply by cancelling the observation as described in Section 3.6 of [RFC7641]. The client MUST either use CoAP GET with the Observe Option set to 1 or send a CoAP Reset message in response to a notification.

+

In some circumstances, it may be desirable to cancel an observation and release the resources allocated by the broker. In this case, a client MAY explicitly deregister by issuing a GET request 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).

+

As per [RFC7641] 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 value can be modified at the broker by the administrator of a topic by modifying the parameter "observer-check" on Section 2.2. This would allow to change the rate at which different implementations verify that a subscriber is still interested in observing a topic-data resource.

-
+

-2.7.4. Delete topic-data +3.3.4. Delete topic-data

-

A publisher MAY delete a topic by making a CoAP DELETE request on the topic-data URI.

-

On success, the server returns a 2.02 (Deleted) response.

-

When a topic-data resource is deleted, the broker SHOULD also delete the topic-data parameter in the topic resource, unsubscribe all subscribers by removing them from the list of observers and return a final 4.04 (Not Found) response as per [RFC7641] Section 3.2. The topic is then set back to the half created state as per Section 2.6.1.

-

Example:

-
+

A publisher MAY delete a topic by making a CoAP DELETE request on the topic-data URI.

+

On success, the server returns a 2.02 (Deleted) response.

+

When a topic-data resource is deleted, the broker SHOULD also delete the topic-data parameter in the topic resource, unsubscribe all subscribers by removing them from the list of observers and return a final 4.04 (Not Found) response as per [RFC7641] Section 3.2. The topic is then set back to the half created state as per Section 3.1.

+

Example:

+
 => 0.04 DELETE
    Uri-Path: ps
@@ -2427,21 +2429,21 @@ 

    Uri-Path: 1bd0d6d
 
 <= 2.02 Deleted
-
+
-
+

-2.7.5. Read latest data +3.3.5. Read latest data

-

A client can get the latest published topic-data by making a GET request to the topic-data URI in the broker. Please note that discovery of the topic-data parameter is a required previous step (see Section 2.5.1).

-

On success, the server MUST return 2.05 (Content) response with the data.

-

If the target URI does not match an existing resource or the topic is not in the fully created state (see Section 2.6.1), the broker SHOULD return a response code 4.04 (Not Found).

-

If the broker can not return the requested content format it MUST return a response code 4.15 (Unsupported Content Format).

-

Example:

-
+

A client can get the latest published topic-data by making a GET request to the topic-data URI in the broker. Please note that discovery of the topic-data parameter is a required previous step (see Section 2.5.1).

+

On success, the server MUST return 2.05 (Content) response with the data.

+

If the target URI does not match an existing resource or the topic is not in the fully created state (see Section 3.1), the broker SHOULD return a response code 4.04 (Not Found).

+

If the broker can not return the requested content format it MUST return a response code 4.15 (Unsupported Content Format).

+

Example:

+
 => 0.01 GET
    Uri-Path: ps
@@ -2458,7 +2460,7 @@ 

       "t": 1621452122,
       "v": 23.5
    }
-
+
@@ -2467,15 +2469,15 @@

-
+

-3. CoAP Pubsub Parameters +4. CoAP Pubsub Parameters

-

This document defines parameters used in the messages exchanged between a client and the broker during the topic creation and configuration process (see Section 2.2). The table below summarizes them and specifies the CBOR key to use instead of the full descriptive name.

-

Note that the media type application/core-pubsub+cbor MUST be used when these parameters are transported in the respective message fields.

+

This document defines parameters used in the messages exchanged between a client and the broker during the topic creation and configuration process (see Section 2.2). The table below summarizes them and specifies the CBOR key to use instead of the full descriptive name.

+

Note that the media type application/core-pubsub+cbor MUST be used when these parameters are transported in the respective message fields.

-
+ 
 +-----------------+-----------+--------------+------------+
 | Name            | CBOR Key  | CBOR Type    | Reference  |
@@ -2498,69 +2500,69 @@
-
+

-4. Security Considerations +5. Security Considerations

-

The security considerations discussed in this document cover various aspects related to the publish-subscribe architecture and the management of topics, administrators, and the change of topic-configuration.

+

The security considerations discussed in this document cover various aspects related to the publish-subscribe architecture and the management of topics, administrators, and the change of topic-configuration.

-
+

-4.1. Change of Topic-Configuration +5.1. Change of Topic-Configuration

-

When a topic configuration changes, it may result in disruptions for the subscribers. Some potential issues that may arise include:

+

When a topic configuration changes, it may result in disruptions for the subscribers. Some potential issues that may arise include:

    -
  • -

    Limiting the number of subscribers will cause to cancel ongoing subscriptions until max-subscribers has been reached.

    +
  • +

    Limiting the number of subscribers will cause to cancel ongoing subscriptions until max-subscribers has been reached.

    • -
  • -

    Changing the topic-data value will cancel all ongoing subscriptions.

    +
  • +

    Changing the topic-data value will cancel all ongoing subscriptions.

    • -
  • -

    Changing of the expiration-date may cause to cancel ongoing subscriptions if the topic expires at an earlier data.

    +
  • +

    Changing of the expiration-date may cause to cancel ongoing subscriptions if the topic expires at an earlier data.

-

To address these potential issues, it is vital to have an administration process in place for topic configurations, including monitoring, validation, and enforcement of security policies and procedures.

-

It is also recommended for subscribers to subscribe to the topic-configuration resource in order to receive notifications of topic parameter changes.

+

To address these potential issues, it is vital to have an administration process in place for topic configurations, including monitoring, validation, and enforcement of security policies and procedures.

+

It is also recommended for subscribers to subscribe to the topic-configuration resource in order to receive notifications of topic parameter changes.

-
+

-4.2. Topic Administrators +5.2. Topic Administrators

-

In a publish-subscribe architecture, it is essential to ensure that topic administrators are trustworthy and authorized to perform their duties. This includes the ability to create, modify, and delete topics, enforce proper access control policies, and handle potential security issues arising from topic management.

-

The draft [I-D.ietf-ace-pubsub-profile] defines an application profile of the Authentication and Authorization for Constrained Environments (ACE) framework. The profile is designed to enable secure group communication for the architecture defined in this document "[RFC-XXXX]" (See Figure 1).

-

The profile relies on protocol-specific transport profiles of ACE for communication security, server authentication, and proof-of-possession for a key that is owned by the Client and bound to an OAuth 2.0 Access Token.

-

The document outlines the provisioning and enforcement of authorization information for Clients to act as Publishers and/or Subscribers. Additionally, it specifies the provisioning of keying material and security parameters that Clients use to protect their communications end-to-end through the Broker.

+

In a publish-subscribe architecture, it is essential to ensure that topic administrators are trustworthy and authorized to perform their duties. This includes the ability to create, modify, and delete topics, enforce proper access control policies, and handle potential security issues arising from topic management.

+

The draft [I-D.ietf-ace-pubsub-profile] defines an application profile of the Authentication and Authorization for Constrained Environments (ACE) framework. The profile is designed to enable secure group communication for the architecture defined in this document "[RFC-XXXX]" (See Figure 1).

+

The profile relies on protocol-specific transport profiles of ACE for communication security, server authentication, and proof-of-possession for a key that is owned by the Client and bound to an OAuth 2.0 Access Token.

+

The document outlines the provisioning and enforcement of authorization information for Clients to act as Publishers and/or Subscribers. Additionally, it specifies the provisioning of keying material and security parameters that Clients use to protect their communications end-to-end through the Broker.

-
+

-4.3. Caching and Freshness +5.3. Caching and Freshness

-

A broker could become overloaded if it always had to provide the most recent cached resource representation of a topic-data to a subscriber. On deployments with a large number of clients and with many topic resources this would represent a big burden on the broker.

-

For this reason is it recommended to consider changing the default Max-Age Option, which has a value of 60 in CoAP, in order to cater to different deployment scenarios.

-

For example, the broker could choose not to cache anything, therefore it SHOULD explicitly include a Max-Age Option with a value of zero seconds. For more information about caching and freshness in CoAP, please check [RFC7252] and [RFC7641]

+

A broker could become overloaded if it always had to provide the most recent cached resource representation of a topic-data to a subscriber. On deployments with a large number of clients and with many topic resources this would represent a big burden on the broker.

+

For this reason is it recommended to consider changing the default Max-Age Option, which has a value of 60 in CoAP, in order to cater to different deployment scenarios.

+

For example, the broker could choose not to cache anything, therefore it SHOULD explicitly include a Max-Age Option with a value of zero seconds. For more information about caching and freshness in CoAP, please check [RFC7252] and [RFC7641]

-
+

-5. IANA Considerations +6. IANA Considerations

-

This document has the following actions for IANA.

-

Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" with the RFC number of this specification and delete this paragraph.

+

This document has the following actions for IANA.

+

Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" with the RFC number of this specification and delete this paragraph.

-
+

-5.1. CoAP Pubsub Parameters +6.1. CoAP Pubsub Parameters

-

IANA is asked to register the following entries in the "CoAP Pubsub Parameters" registry.

-
+

IANA is asked to register the following entries in the "CoAP Pubsub Parameters" registry.

+
 Name: topic-name
 CBOR Key: TBD1
@@ -2621,17 +2623,17 @@ 

 CBOR Key: TBD12
 CBOR Type: tstr
 Reference: [RFC-XXXX]
-
+
-
+

-5.2. Resource Types +6.2. Resource Types

-

IANA is asked to enter the following values in the "Resource Type (rt=) Link Target Attribute Values" registry within the "Constrained Restful Environments (CoRE) Parameters" registry group.

-
+

IANA is asked to enter the following values in the "Resource Type (rt=) Link Target Attribute Values" registry within the "Constrained Restful Environments (CoRE) Parameters" registry group.

+
 Value: core.ps
 Description: Publish-Subscribe Broker
@@ -2648,29 +2650,29 @@ 

 Value: core.ps.data
 Description: Topic-data resource of a Publish-Subscribe Broker
 Reference: [RFC-XXXX]
-
+
-
+

-6. Acknowledgements +7. Acknowledgements

-

The current version of this document contains a substantial contribution by Klaus Hartke's proposal [I-D.hartke-t2trg-coral-pubsub], which defines the topic resource model and structure as well as the topic lifecycle and interactions. It also follows a similar architectural design as that provided by Marco Tiloca's [I-D.ietf-ace-oscore-gm-admin].

-

The authors would like to also thank Carsten Bormann, Hannes Tschofenig, Zach Shelby, Mohit Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran Selander, Mikko Majanen, and Olaf Bergmann for their valuable contributions and reviews.

+

The current version of this document contains a substantial contribution by Klaus Hartke's proposal [I-D.hartke-t2trg-coral-pubsub], which defines the topic resource model and structure as well as the topic lifecycle and interactions. It also follows a similar architectural design as that provided by Marco Tiloca's [I-D.ietf-ace-oscore-gm-admin].

+

The authors would like to also thank Carsten Bormann, Hannes Tschofenig, Zach Shelby, Mohit Sethi, Peter van der Stok, Tim Kellogg, Anders Eriksson, Goran Selander, Mikko Majanen, and Olaf Bergmann for their valuable contributions and reviews.

-
+

-7. References +8. References

-
+

-7.1. Normative References +8.1. Normative References

[RFC2119]
@@ -2709,9 +2711,9 @@

-
+

-7.2. Informative References +8.2. Informative References

[I-D.hartke-t2trg-coral-pubsub]
diff --git a/ps-rev/draft-ietf-core-coap-pubsub.txt b/ps-rev/draft-ietf-core-coap-pubsub.txt index bc2e4ec..63a962a 100644 --- a/ps-rev/draft-ietf-core-coap-pubsub.txt +++ b/ps-rev/draft-ietf-core-coap-pubsub.txt @@ -79,7 +79,7 @@ Table of Contents 2.1. Collection Representation 2.2. Topic-Configuration Representation 2.2.1. Topic Properties - 2.2.2. Default Values + 2.2.1.1. Default Values 2.3. Discovery 2.3.1. Broker Discovery 2.3.2. Topic Collection Discovery @@ -94,27 +94,27 @@ Table of Contents 2.5.2. Getting part of a topic-configuration 2.5.3. Updating the topic-configuration 2.5.4. Deleting a topic-configuration - 2.6. Publish and Subscribe - 2.6.1. Topic Lifecycle - 2.6.2. Rate Limiting - 2.7. Topic-Data Interactions - 2.7.1. Publish - 2.7.2. Subscribe - 2.7.3. Unsubscribe - 2.7.4. Delete topic-data - 2.7.5. Read latest data - 3. CoAP Pubsub Parameters - 4. Security Considerations - 4.1. Change of Topic-Configuration - 4.2. Topic Administrators - 4.3. Caching and Freshness - 5. IANA Considerations - 5.1. CoAP Pubsub Parameters - 5.2. Resource Types - 6. Acknowledgements - 7. References - 7.1. Normative References - 7.2. Informative References + 3. Publish and Subscribe + 3.1. Topic Lifecycle + 3.2. Rate Limiting + 3.3. Topic-Data Interactions + 3.3.1. Publish + 3.3.2. Subscribe + 3.3.3. Unsubscribe + 3.3.4. Delete topic-data + 3.3.5. Read latest data + 4. CoAP Pubsub Parameters + 5. Security Considerations + 5.1. Change of Topic-Configuration + 5.2. Topic Administrators + 5.3. Caching and Freshness + 6. IANA Considerations + 6.1. CoAP Pubsub Parameters + 6.2. Resource Types + 7. Acknowledgements + 8. References + 8.1. Normative References + 8.2. Informative References Authors' Addresses 1. Introduction @@ -191,8 +191,8 @@ Table of Contents configuration and the topic-data resource when hosted at the broker. The creation, configuration, and discovery of topics at a broker are specified in Section 2. The lifecycle of a topic is - specified in Section 2.6.1. Interactions about the topic-data are - defined in Section 2.7. The topic-configuration URI is NOT used + specified in Section 3.1. Interactions about the topic-data are + defined in Section 3.3. The topic-configuration URI is NOT used to to publish and subscribe to data. Throughout this document the word "topic" and "topic-configuration" can appear interchangeably. @@ -208,7 +208,7 @@ Table of Contents broker is responsible for the store-and-forward of state update representations when the topic-data URI points to a resource hosted on the broker. The broker is also responsible of handling - the topic lifecycle as defined in Section 2.6.1. The creation, + the topic lifecycle as defined in Section 3.1. The creation, configuration, and discovery of topics at a broker is specified in Section 2. @@ -246,7 +246,7 @@ Table of Contents This document describes two sets of interactions, interactions to configure topics and their lifecycle (see Section 2.5) and - interactions about the topic-data (see Section 2.7). + interactions about the topic-data (see Section 3.3). Topic-configuration interactions are discovery, create, read configuration, update configuration, delete configuration and handle @@ -273,7 +273,7 @@ Table of Contents Figure 2: Resources of a Broker The Broker exports a topic-collection resource, with resource type - "core.ps.coll" defined in Section 5 of this document. The interfaces + "core.ps.coll" defined in Section 6 of this document. The interfaces for the topic-collection resource is defined in Section 2.4. 2. Pub-Sub Topics @@ -336,12 +336,12 @@ Table of Contents configuration properties of the topic as top-level elements. Unless specified otherwise, these are defined in this document and - their CBOR abbreviations are defined in Section 3. + their CBOR abbreviations are defined in Section 4. 2.2.1. Topic Properties The CBOR map includes the following configuration parameters, whose - CBOR abbreviations are defined in Section 3 of this document. + CBOR abbreviations are defined in Section 4 of this document. * 'topic-name': A required field used as an application identifier. It encodes the topic name as a CBOR text string. Examples of @@ -390,7 +390,7 @@ Table of Contents if the topic-data is not hosted by the broker but by another CoAP server it is up to that server to apply the observer-check value. -2.2.2. Default Values +2.2.1.1. Default Values Below are the defined default values for the topic parameters: @@ -432,7 +432,7 @@ Table of Contents multicast, through a Resource Directory (RD) [RFC9167] or by other means specified in extensions to [RFC7252]. Brokers MAY register with a RD by following the steps on Section 5 of [RFC9167] with the - resource type set to "core.ps" as defined in Section 5 of this + resource type set to "core.ps" as defined in Section 6 of this document. 2.3.2. Topic Collection Discovery @@ -571,7 +571,7 @@ Table of Contents If the topic-data is empty the broker will assign a resource for a publisher to publish to. Please note that the topic will NOT be fully created until a publisher has published some data to it (See - Section 2.6.1). + Section 3.1). On success, the server returns a 2.01 (Created) response indicating the topic URI of the new topic and the current representation of the @@ -629,7 +629,7 @@ Table of Contents The response payload is a CBOR map, whose possible entries are specified in Section 2.2 and use the same abbreviations defined in - Section 3. + Section 4. For example, below is a request on the topic "ps/h9392": @@ -673,7 +673,7 @@ Table of Contents The response payload is a CBOR map, whose possible entries are specified in Section 2.2 and use the same abbreviations defined in - Section 3. + Section 4. Both request and response MUST have Content-Format set to "application/core-pubsub+cbor". @@ -762,7 +762,7 @@ Table of Contents <= 2.02 Deleted -2.6. Publish and Subscribe +3. Publish and Subscribe The overview of the publish/subscribe mechanism over CoAP is as follows: a publisher publishes to a topic by submitting the data in a @@ -782,7 +782,7 @@ Table of Contents data resource yields a 4.04 (Not Found) response. If such a "half created" topic is undesired, the creator of the topic can simply immediately publish some initial placeholder data to make the topic - "fully created" (see Section 2.6.1). + "fully created" (see Section 3.1). URIs for topic resources are broker-generated (see Section 2.4.3). URIs for topic-data MAY be broker-generated or client-generated. @@ -790,7 +790,7 @@ Table of Contents the data exists and the URI of the topic resource. Topic resource and data resources might even be hosted on different servers. -2.6.1. Topic Lifecycle +3.1. Topic Lifecycle When a topic is newly created, it is first placed by the server into the HALF CREATED state (see Figure 4). In this state, a client can @@ -830,7 +830,7 @@ Table of Contents CREATED state, where clients can read, update and delete the topic- configuration and await for a publisher to begin publication. -2.6.2. Rate Limiting +3.2. Rate Limiting The server hosting a data resource may have to handle a potentially very large number of publishers and subscribers at the same time. @@ -848,7 +848,7 @@ Table of Contents NOT send any new publication requests to the same topic-data resource before the time indicated by the Max-Age option has passed. -2.7. Topic-Data Interactions +3.3. Topic-Data Interactions Interactions with the topic-data resource are covered in this section. The interactions with topic-data are same as that of any @@ -882,12 +882,12 @@ Table of Contents Figure 5: topic-data hosted externally -2.7.1. Publish +3.3.1. Publish A topic-configuration with a topic-data resource must have been created in order to publish data to it (See Section Section 2.4.3) and be in the half-created state in order to the publish operation to - work (see Section 2.6.1). + work (see Section 3.1). A client can publish data to a topic by submitting the data in a PUT request to the topic-data URI as indicated in its topic resource @@ -898,7 +898,7 @@ Table of Contents On success, the server returns a 2.04 (Updated) response. However, when data is published to the topic for the first time, the server instead MUST return a 2.01 (Created) response and set the topic in - the fully-created state (see Section 2.6.1). + the fully-created state (see Section 3.1). If the request does not have an acceptable content format, the server returns a 4.15 (Unsupported Content Format) response. @@ -940,7 +940,7 @@ Table of Contents <= 2.04 Updated -2.7.2. Subscribe +3.3.2. Subscribe A client can subscribe to a topic by sending a CoAP GET request with the Observe set to '0' to subscribe to resource updates. [RFC7641]. @@ -948,9 +948,8 @@ Table of Contents On success, the broker MUST return 2.05 (Content) notifications with the data. - If the topic is not yet in the fully created state (see - Section 2.6.1) the broker SHOULD return a response code 4.04 (Not - Found). + If the topic is not yet in the fully created state (see Section 3.1) + the broker SHOULD return a response code 4.04 (Not Found). The following response codes are defined for the Subscribe operation: @@ -998,7 +997,7 @@ Table of Contents "v": 21.87 } -2.7.3. Unsubscribe +3.3.3. Unsubscribe A CoAP client can unsubscribe simply by cancelling the observation as described in Section 3.6 of [RFC7641]. The client MUST either use @@ -1021,7 +1020,7 @@ Table of Contents implementations verify that a subscriber is still interested in observing a topic-data resource. -2.7.4. Delete topic-data +3.3.4. Delete topic-data A publisher MAY delete a topic by making a CoAP DELETE request on the topic-data URI. @@ -1032,8 +1031,7 @@ Table of Contents the topic-data parameter in the topic resource, unsubscribe all subscribers by removing them from the list of observers and return a final 4.04 (Not Found) response as per [RFC7641] Section 3.2. The - topic is then set back to the half created state as per - Section 2.6.1. + topic is then set back to the half created state as per Section 3.1. Example: @@ -1044,7 +1042,7 @@ Table of Contents <= 2.02 Deleted -2.7.5. Read latest data +3.3.5. Read latest data A client can get the latest published topic-data by making a GET request to the topic-data URI in the broker. Please note that @@ -1055,7 +1053,7 @@ Table of Contents data. If the target URI does not match an existing resource or the topic is - not in the fully created state (see Section 2.6.1), the broker SHOULD + not in the fully created state (see Section 3.1), the broker SHOULD return a response code 4.04 (Not Found). If the broker can not return the requested content format it MUST @@ -1079,7 +1077,7 @@ Table of Contents "v": 23.5 } -3. CoAP Pubsub Parameters +4. CoAP Pubsub Parameters This document defines parameters used in the messages exchanged between a client and the broker during the topic creation and @@ -1106,14 +1104,14 @@ Table of Contents Figure 6: CoAP Pubsub Parameters -4. Security Considerations +5. Security Considerations The security considerations discussed in this document cover various aspects related to the publish-subscribe architecture and the management of topics, administrators, and the change of topic- configuration. -4.1. Change of Topic-Configuration +5.1. Change of Topic-Configuration When a topic configuration changes, it may result in disruptions for the subscribers. Some potential issues that may arise include: @@ -1136,7 +1134,7 @@ Table of Contents configuration resource in order to receive notifications of topic parameter changes. -4.2. Topic Administrators +5.2. Topic Administrators In a publish-subscribe architecture, it is essential to ensure that topic administrators are trustworthy and authorized to perform their @@ -1161,7 +1159,7 @@ Table of Contents material and security parameters that Clients use to protect their communications end-to-end through the Broker. -4.3. Caching and Freshness +5.3. Caching and Freshness A broker could become overloaded if it always had to provide the most recent cached resource representation of a topic-data to a @@ -1177,14 +1175,14 @@ Table of Contents seconds. For more information about caching and freshness in CoAP, please check [RFC7252] and [RFC7641] -5. IANA Considerations +6. IANA Considerations This document has the following actions for IANA. Note to RFC Editor: Please replace all occurrences of "[RFC-XXXX]" with the RFC number of this specification and delete this paragraph. -5.1. CoAP Pubsub Parameters +6.1. CoAP Pubsub Parameters IANA is asked to register the following entries in the "CoAP Pubsub Parameters" registry. @@ -1249,7 +1247,7 @@ Table of Contents CBOR Type: tstr Reference: [RFC-XXXX] -5.2. Resource Types +6.2. Resource Types IANA is asked to enter the following values in the "Resource Type (rt=) Link Target Attribute Values" registry within the "Constrained @@ -1271,7 +1269,7 @@ Table of Contents Description: Topic-data resource of a Publish-Subscribe Broker Reference: [RFC-XXXX] -6. Acknowledgements +7. Acknowledgements The current version of this document contains a substantial contribution by Klaus Hartke's proposal @@ -1285,9 +1283,9 @@ Table of Contents Kellogg, Anders Eriksson, Goran Selander, Mikko Majanen, and Olaf Bergmann for their valuable contributions and reviews. -7. References +8. References -7.1. Normative References +8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, @@ -1327,7 +1325,7 @@ Table of Contents Protocol (EPP)", RFC 9167, DOI 10.17487/RFC9167, December 2021, . -7.2. Informative References +8.2. Informative References [I-D.hartke-t2trg-coral-pubsub] Hartke, K., "Publish/Subscribe over the Constrained