diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..52f32f5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +lib +venv +.refcache diff --git a/archive.json b/archive.json new file mode 100644 index 0000000..cd05b88 --- /dev/null +++ b/archive.json @@ -0,0 +1,1537 @@ +{ + "magic": "E!vIA5L86J2I", + "timestamp": "2023-03-14T00:47:02.834612+00:00", + "repo": "core-wg/coap-pubsub", + "labels": [ + { + "name": "bug", + "description": null, + "color": "ee0701" + }, + { + "name": "duplicate", + "description": null, + "color": "cccccc" + }, + { + "name": "enhancement", + "description": null, + "color": "84b6eb" + }, + { + "name": "help wanted", + "description": null, + "color": "128A0C" + }, + { + "name": "invalid", + "description": null, + "color": "e6e6e6" + }, + { + "name": "question", + "description": null, + "color": "cc317c" + }, + { + "name": "wontfix", + "description": null, + "color": "ffffff" + }, + { + "name": "for-future-docs", + "description": "Feature/enhancement not for this draft but potentially for a future focument", + "color": "1e2bdb" + } + ], + "issues": [ + { + "number": 1, + "id": "MDU6SXNzdWUyMTgwMzU3MTg=", + "title": "URI Template", + "url": "https://github.com/core-wg/coap-pubsub/issues/1", + "state": "CLOSED", + "author": "jaimejim", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "The URI template should be confirmed:\r\n\r\n`: /{+ps}{/topic*}?{q*}`\r\n\r\n", + "createdAt": "2017-03-29T23:08:24Z", + "updatedAt": "2017-07-04T16:58:48Z", + "closedAt": "2017-07-04T16:58:48Z", + "comments": [ + { + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "body": "PR #6 resolved this", + "createdAt": "2017-07-04T16:58:48Z", + "updatedAt": "2017-07-04T16:58:48Z" + } + ] + }, + { + "number": 2, + "id": "MDU6SXNzdWUyMTgwNTgxMTY=", + "title": "Are all operations mandatory?", + "url": "https://github.com/core-wg/coap-pubsub/issues/2", + "state": "CLOSED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "Should we make create topic, remove topic, and discovery optional? ", + "createdAt": "2017-03-30T01:49:01Z", + "updatedAt": "2018-07-18T22:28:37Z", + "closedAt": "2018-07-18T22:27:55Z", + "comments": [ + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "We currently don't require any particular set of operations:\r\n\r\nA CoAP pub/sub Broker implementing this\r\n specification SHOULD support the DISCOVERY, CREATE, PUBLISH,\r\n SUBSCRIBE, UNSUBSCRIBE, READ, and REMOVE operations defined in this\r\n section.", + "createdAt": "2018-07-18T22:12:01Z", + "updatedAt": "2018-07-18T22:12:01Z" + }, + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "We have alternate methods for all operations, such as pre-created topics, read vs. subscribe, pre-published topics.", + "createdAt": "2018-07-18T22:28:37Z", + "updatedAt": "2018-07-18T22:28:37Z" + } + ] + }, + { + "number": 3, + "id": "MDU6SXNzdWUyMTgwNTgzMTA=", + "title": "Is there a better name than \"API\" to describe the REST interface to pubsub?", + "url": "https://github.com/core-wg/coap-pubsub/issues/3", + "state": "CLOSED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "API may imply that it is a higher level API than REST operations. Is there a better name to replace the \"function set\" concept?\r\n", + "createdAt": "2017-03-30T01:50:35Z", + "updatedAt": "2018-07-18T21:58:58Z", + "closedAt": "2018-07-18T21:58:58Z", + "comments": [ + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "Using \"REST API\" type terminology", + "createdAt": "2018-07-18T21:58:58Z", + "updatedAt": "2018-07-18T21:58:58Z" + } + ] + }, + { + "number": 4, + "id": "MDU6SXNzdWUyMTgwNTg3MjI=", + "title": "Response code for stale published value or empty response, \"no content\"", + "url": "https://github.com/core-wg/coap-pubsub/issues/4", + "state": "OPEN", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "Currently we define a \"no content\" response, such as when a GET is done on a value which has expired its lifetime, with 2.04. We should probably define a new response code like 2.06 for this instead of trying to overload the 2.04 when used as a \"changed\" response to POST or PUT.", + "createdAt": "2017-03-30T01:53:44Z", + "updatedAt": "2018-07-18T21:52:06Z", + "closedAt": null, + "comments": [ + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "The semantic of this code is not the same as the HTTP 204 \"No Response\". 204 indicates that the data have not changes and the client may continue to use the last transmitted value. We need a response code that indicates data are not transmitted because of staleness and the client should not use the last transmitted value.", + "createdAt": "2018-07-18T21:25:21Z", + "updatedAt": "2018-07-18T21:25:21Z" + }, + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "Suggest we create an equivalent response code to HTTP 202 Accepted\r\n\r\n202 Accepted\r\nThe request has been accepted for processing, but the processing has not been completed. The request might or might not be eventually acted upon, and may be disallowed when processing occurs.\r\n\r\nSuggest using 2.07\r\n\r\n", + "createdAt": "2018-07-18T21:52:06Z", + "updatedAt": "2018-07-18T21:52:06Z" + } + ] + }, + { + "number": 5, + "id": "MDU6SXNzdWUyMTgwNjEzMjc=", + "title": "POST for queueing doesn't solve the QoS issue with missed publications ", + "url": "https://github.com/core-wg/coap-pubsub/issues/5", + "state": "OPEN", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [ + "for-future-docs" + ], + "body": "If a client subscribes using Observe, there is no handshake on the observe response to indicate that the notification was received by the subscriber. Creating a list of published representations in the broker using POST only covers the case where the broker can't keep up with sending notifications. The notifications are still \"best effort\".\r\n\r\nTo solve the QoS issue, we should have the subscriber create a queueing resource on the broker, which is specific to that subscriber, for each subscribed topic for which more than \"best effort\" QoS is desired. This resource will store published representations until the subscriber can retrieve or accept them. \r\n\r\nThe subscriber may use GET to return the representation of the queueing resource, receiving a list of links to published representations which may then be fetched using GET. The subscriber would be responsible for removing the representations it has fetched.\r\n\r\nThis enables sleepy subscribers and subscribers behind NAT firewalls to receive notifications without data loss. \r\n\r\nWe may also provide a resource that may be observed which returns and removes representations from the queue, in published order, using GET or Observe. Using GET, the broker would return \"no data\" upon fetches to an empty queue.\r\n\r\nA sleepy subscriber could wake up, subscribe, receive notifications, unsubscribe, and sleep again.\r\n\r\nWe may also provide a means for the subscriber to request a push or \"web callback\" using PUT or POST to update a resource on the subscriber upon notifications.\r\n\r\nWe could keep \"simple pubsub\" as it is, and allow queueing pubsub as an optional feature for enhanced QoS, sleepy subscribers, etc.\r\n", + "createdAt": "2017-03-30T02:14:21Z", + "updatedAt": "2018-07-18T21:15:02Z", + "closedAt": null, + "comments": [] + }, + { + "number": 8, + "id": "MDU6SXNzdWUyNDM3NDI2MzQ=", + "title": "We don't specify enough about options included in notifications", + "url": "https://github.com/core-wg/coap-pubsub/issues/8", + "state": "CLOSED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "Does the broker pass uri-host? content-format? etc...", + "createdAt": "2017-07-18T14:46:53Z", + "updatedAt": "2018-07-18T21:18:33Z", + "closedAt": "2018-07-18T21:18:33Z", + "comments": [ + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "There is no pass-through of header options. Will not specify in this document.", + "createdAt": "2018-07-18T21:18:33Z", + "updatedAt": "2018-07-18T21:18:33Z" + } + ] + }, + { + "number": 9, + "id": "MDU6SXNzdWUyNDM3NDU4Nzc=", + "title": "Create on publish needs more definition", + "url": "https://github.com/core-wg/coap-pubsub/issues/9", + "state": "CLOSED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "Should we allow create on publish?\r\n\r\nCreate on publish might use a query option to set the content format.", + "createdAt": "2017-07-18T14:56:04Z", + "updatedAt": "2018-07-18T21:15:57Z", + "closedAt": "2018-07-18T21:15:57Z", + "comments": [ + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "Create-on-publish uses the content-format from the header of the PUT/POST used to publish", + "createdAt": "2018-07-18T21:15:57Z", + "updatedAt": "2018-07-18T21:15:57Z" + } + ] + }, + { + "number": 10, + "id": "MDU6SXNzdWUyNDM3NDY4NDg=", + "title": "testing opening issues from cli", + "url": "https://github.com/core-wg/coap-pubsub/issues/10", + "state": "CLOSED", + "author": "jaimejim", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "jjjjj jjjj jjjj", + "createdAt": "2017-07-18T14:58:55Z", + "updatedAt": "2017-07-18T14:59:49Z", + "closedAt": "2017-07-18T14:59:49Z", + "comments": [] + }, + { + "number": 11, + "id": "MDU6SXNzdWUyNDM3NTAwMzI=", + "title": "Subscribing to a hierarchy of topics", + "url": "https://github.com/core-wg/coap-pubsub/issues/11", + "state": "CLOSED", + "author": "jaimejim", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "Given the following hierarchy:\n\n\"topic/subtopic1/subtopic2\"\n\nShould a subscriber be allowed to subscribe to topic or subtopic1? What would the broker return if so?", + "createdAt": "2017-07-18T15:08:17Z", + "updatedAt": "2018-07-18T21:15:35Z", + "closedAt": "2018-07-18T21:15:35Z", + "comments": [ + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "It depends on the content format requested by the subscriber. If there is only a link-format resource stored (sub topic but no data items) then the client can only get link-format. ", + "createdAt": "2017-07-18T21:01:31Z", + "updatedAt": "2017-07-18T21:01:31Z" + }, + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "The broker would return unsupported content format", + "createdAt": "2017-07-18T21:02:07Z", + "updatedAt": "2017-07-18T21:02:07Z" + }, + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "4.15", + "createdAt": "2017-07-18T21:02:52Z", + "updatedAt": "2017-07-18T21:02:52Z" + }, + { + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "body": "When subscribing to a parent topic, the broker will return a set of links that the client can subscribe to. The broker will send notifications when the link set changes so that a client stays up to date with the tree. This should work with the current draft already.", + "createdAt": "2018-07-18T21:15:35Z", + "updatedAt": "2018-07-18T21:15:35Z" + } + ] + }, + { + "number": 12, + "id": "MDU6SXNzdWUyNzkzNDg0NzA=", + "title": "Notification information to publisher", + "url": "https://github.com/core-wg/coap-pubsub/issues/12", + "state": "OPEN", + "author": "lauri-piikivi", + "authorAssociation": "NONE", + "assignees": [], + "labels": [ + "for-future-docs" + ], + "body": "Hi,\r\n\r\nMore of a feature wish. If a client subscribes for notifications, I would like to have an option that allows the broker to forward the notification attributes -- the greater than, less than, minimum period etc -- to the publishing client. The publishing client can use those to adjust it's own publishing. ", + "createdAt": "2017-12-05T11:56:32Z", + "updatedAt": "2018-07-18T21:12:12Z", + "closedAt": null, + "comments": [ + { + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "body": "A topic may have multiple subscribers so a broker would have to forward and update combinations of these parameters to the publisher. Also would need to define a mechanism to relay these attributes. This starts to get quite complex so maybe it's better left for the future unless there's a strong need for this.", + "createdAt": "2018-07-18T21:12:01Z", + "updatedAt": "2018-07-18T21:12:01Z" + } + ] + }, + { + "number": 18, + "id": "MDU6SXNzdWUzMDY1NTYwNzI=", + "title": "CREATE topic on the core.ps resource should start with slash", + "url": "https://github.com/core-wg/coap-pubsub/issues/18", + "state": "CLOSED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "When creating topics under the core.ps resource (\"/ps\" in the document examples) we should require or allow (?) a starts-with-slash path. When creating topics under a parent topic, we should require a relative path (not starts-with-slash). Should we allow PUT to create using an absolute URI?", + "createdAt": "2018-03-19T17:20:07Z", + "updatedAt": "2018-07-18T21:10:28Z", + "closedAt": "2018-07-18T21:10:27Z", + "comments": [ + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "dup 21", + "createdAt": "2018-07-18T21:10:27Z", + "updatedAt": "2018-07-18T21:10:27Z" + } + ] + }, + { + "number": 19, + "id": "MDU6SXNzdWUzMDY1NTg2OTg=", + "title": "DISCOVER should be enabled on parent topics", + "url": "https://github.com/core-wg/coap-pubsub/issues/19", + "state": "CLOSED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "Parent topics should have a rt=core.ps.discover target attribute and be described in the draft text as permitting DISCOVER operations.", + "createdAt": "2018-03-19T17:27:22Z", + "updatedAt": "2018-07-18T21:08:33Z", + "closedAt": "2018-07-18T21:08:33Z", + "comments": [ + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "After discussion, we think that rt=core.ps.discover should only appear at the root discovery resource and not in each parent topic link", + "createdAt": "2018-03-20T11:43:18Z", + "updatedAt": "2018-03-20T11:43:18Z" + }, + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "Done", + "createdAt": "2018-07-18T21:08:31Z", + "updatedAt": "2018-07-18T21:08:31Z" + } + ] + }, + { + "number": 21, + "id": "MDU6SXNzdWUzMDY1OTA2MDc=", + "title": "Should we allow topics to be created at locations other than under the pub/sub resource ?", + "url": "https://github.com/core-wg/coap-pubsub/issues/21", + "state": "CLOSED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "Currently we show topics only being created under the pub/sub resource (core.ps and \"/ps\" in the examples). Should we also allow creation of topics at starts-with-slash URIs, or should Creation, Discovery, and all topics be located under the pub/sub resource?", + "createdAt": "2018-03-19T18:57:46Z", + "updatedAt": "2018-03-19T19:11:58Z", + "closedAt": "2018-03-19T19:11:43Z", + "comments": [ + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "duplicate of #18", + "createdAt": "2018-03-19T19:11:58Z", + "updatedAt": "2018-03-19T19:11:58Z" + } + ] + }, + { + "number": 22, + "id": "MDU6SXNzdWUzMDY1OTI4MDc=", + "title": "How does a client use Conditional Notification parameters (CoRE Dynlink)?", + "url": "https://github.com/core-wg/coap-pubsub/issues/22", + "state": "OPEN", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [ + "for-future-docs" + ], + "body": "Should we support conditional notification on subscriptions? If so, how should we enable it? Can it only support pmin and pmax since we only forward representations?", + "createdAt": "2018-03-19T19:03:44Z", + "updatedAt": "2018-07-18T21:04:08Z", + "closedAt": null, + "comments": [] + }, + { + "number": 24, + "id": "MDU6SXNzdWUzMDY2Mzg4NzQ=", + "title": "What happens when a client tries to create a topic that already exists?", + "url": "https://github.com/core-wg/coap-pubsub/issues/24", + "state": "OPEN", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "Should we return 4.09 Conflict for the case when the client tries to create a topic that already exists? \r\n\r\n**Indicates that the request could not be processed because of conflict in the request, such as an edit conflict between multiple simultaneous updates.**\r\n\r\nThe draft currently specifies 4.03\r\n\r\n**The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.**\r\n", + "createdAt": "2018-03-19T21:16:20Z", + "updatedAt": "2018-07-18T22:46:09Z", + "closedAt": null, + "comments": [ + { + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "body": "LGTM", + "createdAt": "2018-07-18T21:05:32Z", + "updatedAt": "2018-07-18T21:05:32Z" + }, + { + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "body": "Will change to 4.09", + "createdAt": "2018-07-18T21:05:40Z", + "updatedAt": "2018-07-18T21:05:40Z" + }, + { + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "body": "4.03 is same as HTTP 403 per 7252: \r\n> The HTTP 403 Forbidden client error status response code indicates that the server understood the request but refuses to authorize it.\r\n\r\n4.09 is registered by 8132: https://tools.ietf.org/html/rfc8132#section-6\r\nhttps://tools.ietf.org/html/rfc8132#section-3.4\r\n\r\n> Conflicting state: If the modification specified by a PATCH or\r\n iPATCH request causes the resource to enter an inconsistent state\r\n that the server cannot resolve, the server can return the 4.09\r\n (Conflict) CoAP response.", + "createdAt": "2018-07-18T22:46:08Z", + "updatedAt": "2018-07-18T22:46:08Z" + } + ] + }, + { + "number": 29, + "id": "MDU6SXNzdWUzNDI1MTUxMDM=", + "title": "Add note to intro/abstract about pub/sub paradigm", + "url": "https://github.com/core-wg/coap-pubsub/issues/29", + "state": "CLOSED", + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "This mechanism is also useful for cases where the pub/sub paradigm instead of classic req/resp is desired (one-to-many, many-to-one, many-to-many communications, etc.).", + "createdAt": "2018-07-18T22:33:06Z", + "updatedAt": "2019-01-02T20:06:31Z", + "closedAt": "2019-01-02T20:06:31Z", + "comments": [] + }, + { + "number": 31, + "id": "MDU6SXNzdWUzOTUzODk2OTI=", + "title": "Add implementation status section", + "url": "https://github.com/core-wg/coap-pubsub/issues/31", + "state": "OPEN", + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "https://tools.ietf.org/html/rfc7942\r\n\r\nAt least:\r\n\r\n* https://github.com/Com-AugustCellars/PubSub\r\n* https://github.com/aldwinhermanudin/coap-broker\r\n* https://github.com/gotthardp/rabbitmq-coap-pubsub\r\n* https://github.com/PethrusG/CoAP-PubSub-Broker\r\n* https://github.com/herjulf/coap\r\n* https://github.com/kkdai/coapmq", + "createdAt": "2019-01-02T21:40:57Z", + "updatedAt": "2019-01-02T21:40:57Z", + "closedAt": null, + "comments": [] + }, + { + "number": 34, + "id": "MDU6SXNzdWU0MjE5OTAxODg=", + "title": "Handle topic timeout w/URI-query option and 4.04 and data staleness with max-age", + "url": "https://github.com/core-wg/coap-pubsub/issues/34", + "state": "OPEN", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "As per the CoRE interim discussion, we would like to support topic lifetime setting using a URI-query option (e.g. \"tlt\") on topic creation. If the topic isn't published to before the lifetime expires, the topic is removed, resulting in a 4.04 response to new SUBSCRIBE or READ requests, and the broker closes outstanding observes with a 4.04. Publishing to the topic resets the lifetime counter.\r\n\r\nMax-age will be used for data staleness. We suggest to provide the same feature to subscribing clients that a cache would use. One issue with Max-age is that it only applies to responses, and we need to convey the data lifetime on publish. We could use a uri-query option (e.g. \"dlt\") or a new header option for publish-max-age. Without this, the default Max-Age of 60 seconds would be required. For READ and SUBSCRIBE responses it will be (60 seconds - seconds since publish). ", + "createdAt": "2019-03-17T23:57:29Z", + "updatedAt": "2019-03-17T23:57:29Z", + "closedAt": null, + "comments": [] + }, + { + "number": 40, + "id": "MDU6SXNzdWU1MTQ5Mjc5MTI=", + "title": "Why do topics need to be created?", + "url": "https://github.com/core-wg/coap-pubsub/issues/40", + "state": "OPEN", + "author": "bdamm", + "authorAssociation": "NONE", + "assignees": [], + "labels": [], + "body": "The protocol requires that publishers and subscribers create topics before publishing or subscribing to topics. There is an option for a single-shot topic creation with publish, but no option for subscribing to a topic that hasn't been created yet.\r\n\r\nThe result is that if you have a very large tree of potential but not realized topics, subscribers need to actually create a topic before subscribing, regardless of whether the topic will actually be used or not. This converts potential topics into actual topics, which is a major resource burden in the case where there is a large number of potential topics but a small number of actual topics within that potential topic tree.\r\n", + "createdAt": "2019-10-30T19:30:25Z", + "updatedAt": "2019-10-30T19:30:25Z", + "closedAt": null, + "comments": [] + }, + { + "number": 41, + "id": "MDU6SXNzdWU1MTQ5MzA4MTI=", + "title": "Messages are always retained", + "url": "https://github.com/core-wg/coap-pubsub/issues/41", + "state": "OPEN", + "author": "bdamm", + "authorAssociation": "NONE", + "assignees": [], + "labels": [], + "body": "The pubsub protocol -09 requires the broker to always provide the most recent message to a subscriber. Why? The message might be very out-dated. Also, this requires the broker to retain the most recent message for every topic. If the topic tree is large and the broker is acting as an exchange point for millions of devices then the requirement that all topics have a cached message puts a big burden on the broker.", + "createdAt": "2019-10-30T19:35:39Z", + "updatedAt": "2019-10-30T19:35:39Z", + "closedAt": null, + "comments": [] + }, + { + "number": 42, + "id": "MDU6SXNzdWU1MTQ5ODAxMTQ=", + "title": "No way to wildcard subscriptions or subscribe to subtrees", + "url": "https://github.com/core-wg/coap-pubsub/issues/42", + "state": "OPEN", + "author": "bdamm", + "authorAssociation": "NONE", + "assignees": [], + "labels": [], + "body": "Suppose there is a topic structure such as /${tenant-id}/${device-mac}/${event-id}\r\n\r\nSuppose a subscriber wants to receive all events with a specific ID. There is no way to do that in this protocol.\r\n\r\nSuppose a subscriber wants to receive all events from a specific device-mac. \r\nSuppose a subscriber wants to receive all events from a specific tenant-id.\r\n\r\nHow could this be efficiently realized at all, even with complete freedom to structure the topic tree in any way? With the current protocol I don't see how to do it. Subscribers would need to subscribe to millions of potential topics, even though there may not be millions of actual topics. Even worse, subscribers would need intimate knowledge of all possible topics (all possible IDs and MACs) which may not even be possible.", + "createdAt": "2019-10-30T21:01:44Z", + "updatedAt": "2022-09-28T15:30:21Z", + "closedAt": null, + "comments": [ + { + "author": "mattaylor", + "authorAssociation": "NONE", + "body": "This proposal could be extended to support topic wildcard subscriptions following MQTT conventions (`+` for single path segments and `#` for multiple path segments). \r\nWhen a wildcard is included in the subscription, the broker is responsible for notifying all subscribers when any resources change on any matching topics. \r\nWhen a notify response is then delivered to the subscriber on a wildcard topic, the broker MUST include the `URI-PATH` option in the message which indicates the full topic path of the resource being sent. \r\n\r\nE.G: \r\n```\r\n Client1 Client2 Broker\r\n | | Subscribe |\r\n | | --- GET /ps/+ Obs:0 Token:XX ----------------> | \r\n | | <--- ACK ------------------------------------- | \r\n | | |\r\n | | Publish |\r\n | ---------|---- PUT /ps/topic1 \"1033.3\" ----------------> |\r\n |<---------|---- 2.01 Location:/ps/topic1 ----------------- |\r\n | | Notify |\r\n | | <-- 2.05 \"1033.3\" Obs:11 Uri-Path:/ps/topic1 - |\r\n```", + "createdAt": "2022-09-23T18:14:25Z", + "updatedAt": "2022-09-28T15:30:21Z" + } + ] + }, + { + "number": 44, + "id": "I_kwDOBEc_t85ca7ql", + "title": "Brokerless case", + "url": "https://github.com/core-wg/coap-pubsub/issues/44", + "state": "OPEN", + "author": "jaimejim", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "This issue is to discuss the need for the brokerless case, originally proposed for the L+G field bus. \r\n\r\nIn the past we have discussed expanding it and moving it to a new draft or an appendix. There has also been discussion around additional input on configuration and topics, combining the PubSub and Resource Directory patterns, and the interface for topic discovery.\r\n\r\nAs we have not enough material for now and we have chosen to keep this draft simple, I propose to remove it for now in https://github.com/core-wg/coap-pubsub/commit/88e17ec5d60c18d5bcf476a462be18e84cdbf4d5.", + "createdAt": "2023-01-20T09:42:22Z", + "updatedAt": "2023-01-20T09:43:33Z", + "closedAt": null, + "comments": [] + }, + { + "number": 45, + "id": "I_kwDOBEc_t85cbSvV", + "title": "CoAP pub/sub client", + "url": "https://github.com/core-wg/coap-pubsub/issues/45", + "state": "OPEN", + "author": "jaimejim", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "After multiple reads of the document I think it would make more sense to simply keep \"CoAP Clients\" as a general term for the endpoints and just have the classic publisher and subscriber roles indicated when needed. There is no need for a new term \"CoAP pub/sub Client\" as it may introduce confusion to the reader. \r\n\r\nFor now I have removed the term on https://github.com/core-wg/coap-pubsub/commit/a27f6a5d03fab445f0a47b8d7cc55aa59ba69e26", + "createdAt": "2023-01-20T10:53:44Z", + "updatedAt": "2023-01-20T10:53:44Z", + "closedAt": null, + "comments": [] + } + ], + "pulls": [ + { + "number": 6, + "id": "MDExOlB1bGxSZXF1ZXN0MTI4NzAzOTUw", + "title": "updates to address issues", + "url": "https://github.com/core-wg/coap-pubsub/pull/6", + "state": "MERGED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "address issues # 1,2,3,4,5\nremoved the list of representations on POST but kept POST to publish,\nmay do subscriber queueing in a separate document", + "createdAt": "2017-07-03T23:07:43Z", + "updatedAt": "2017-07-03T23:52:39Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "6aa618ca30e6926e2a8c7dbea9933e08c19d7000", + "headRepository": null, + "headRefName": "master", + "headRefOid": "48886f2bfbc52f441d22c3feac47571f59870cbf", + "closedAt": "2017-07-03T23:52:39Z", + "mergedAt": "2017-07-03T23:52:39Z", + "mergedBy": "akeranen", + "mergeCommit": { + "oid": "5efbc8d476de1fcf5e202f10a10f2f0ac0077b72" + }, + "comments": [], + "reviews": [] + }, + { + "number": 7, + "id": "MDExOlB1bGxSZXF1ZXN0MTI4ODQzNjk1", + "title": "Clarify the case for optional CREATE", + "url": "https://github.com/core-wg/coap-pubsub/pull/7", + "state": "MERGED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "change MAY to SHOULD and add clarifying text", + "createdAt": "2017-07-04T18:04:13Z", + "updatedAt": "2018-01-07T00:18:28Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "36081f432df7bbf5af14718709f61d26ab7599fe", + "headRepository": null, + "headRefName": "master", + "headRefOid": "97b732d7a9ed77b53142d87d44a42615d7902787", + "closedAt": "2018-01-07T00:18:28Z", + "mergedAt": "2018-01-07T00:18:28Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "0a29954fc436f592551e1484695ceace3bc3395b" + }, + "comments": [], + "reviews": [ + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3NjA2MzQ3MzQ=", + "commit": { + "abbreviatedOid": "97b732d" + }, + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "state": "APPROVED", + "body": "", + "createdAt": "2017-09-05T15:14:49Z", + "updatedAt": "2017-09-05T15:15:01Z", + "comments": [ + { + "originalPosition": 7, + "body": "How about: \"Fixed brokerless devices and pre-configured brokers in dedicated installations may disallow using CREATE\".", + "createdAt": "2017-09-05T15:14:49Z", + "updatedAt": "2017-09-05T15:15:02Z" + } + ] + } + ] + }, + { + "number": 13, + "id": "MDExOlB1bGxSZXF1ZXN0MTYwMDYyMTE0", + "title": "s|pubsub|pub/sub|g", + "url": "https://github.com/core-wg/coap-pubsub/pull/13", + "state": "MERGED", + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "Changed all instances of \"pubsub\" in the text to \"pub/sub\" that seems\nto be the most common way to abbreviate \"publish-subscribe\"", + "createdAt": "2017-12-25T16:25:33Z", + "updatedAt": "2018-01-07T00:24:09Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "0a29954fc436f592551e1484695ceace3bc3395b", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "pubsub-term-update", + "headRefOid": "7d7d825f63b14d238836de161e0d759d7e326920", + "closedAt": "2018-01-07T00:24:09Z", + "mergedAt": "2018-01-07T00:24:09Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "71bf553b58c4bdbae9dcf69597cfcdede19d57e7" + }, + "comments": [], + "reviews": [] + }, + { + "number": 14, + "id": "MDExOlB1bGxSZXF1ZXN0MTY4Njg1ODE1", + "title": "Master", + "url": "https://github.com/core-wg/coap-pubsub/pull/14", + "state": "MERGED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2018-02-12T20:56:33Z", + "updatedAt": "2018-02-12T20:57:04Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "71bf553b58c4bdbae9dcf69597cfcdede19d57e7", + "headRepository": null, + "headRefName": "master", + "headRefOid": "fdc855ef338e9fa2545c71afb7025594513b2065", + "closedAt": "2018-02-12T20:57:04Z", + "mergedAt": "2018-02-12T20:57:04Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "0718031131ba46f90ea53a0af76eb7916b882a3a" + }, + "comments": [], + "reviews": [] + }, + { + "number": 15, + "id": "MDExOlB1bGxSZXF1ZXN0MTY4Njg4MjQ4", + "title": "Master", + "url": "https://github.com/core-wg/coap-pubsub/pull/15", + "state": "MERGED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "pubsub-03", + "createdAt": "2018-02-12T21:07:53Z", + "updatedAt": "2018-02-12T21:08:11Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "0718031131ba46f90ea53a0af76eb7916b882a3a", + "headRepository": null, + "headRefName": "master", + "headRefOid": "8225dc4aee68a82dbf64f94d23eb68a975b60135", + "closedAt": "2018-02-12T21:08:11Z", + "mergedAt": "2018-02-12T21:08:11Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "21cde189cd77e601455353f56b7d9b19d17f2e93" + }, + "comments": [], + "reviews": [] + }, + { + "number": 16, + "id": "MDExOlB1bGxSZXF1ZXN0MTcyODk3Nzcz", + "title": "Too Many Reqs response code split", + "url": "https://github.com/core-wg/coap-pubsub/pull/16", + "state": "MERGED", + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2018-03-05T15:24:06Z", + "updatedAt": "2018-03-05T22:13:42Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "21cde189cd77e601455353f56b7d9b19d17f2e93", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "429-resp-code-split", + "headRefOid": "382abf2702f3017759ed764ccd923e9a0ac79a5c", + "closedAt": "2018-03-05T22:13:42Z", + "mergedAt": "2018-03-05T22:13:42Z", + "mergedBy": "akeranen", + "mergeCommit": { + "oid": "f5a1c9126f4b1dc0cf7bc0130ebded0825b881d7" + }, + "comments": [], + "reviews": [] + }, + { + "number": 17, + "id": "MDExOlB1bGxSZXF1ZXN0MTcyOTA0NzQx", + "title": "Fixed short description of 2.07 response code", + "url": "https://github.com/core-wg/coap-pubsub/pull/17", + "state": "MERGED", + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "The description should be just a few words (https://www.iana.org/assignments/core-parameters/core-parameters.xhtml)", + "createdAt": "2018-03-05T15:47:13Z", + "updatedAt": "2018-03-05T22:14:10Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "21cde189cd77e601455353f56b7d9b19d17f2e93", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "207-resp-code-fix", + "headRefOid": "b95c762cd4812f72cd463a0ce4db889955e14d3e", + "closedAt": "2018-03-05T22:14:10Z", + "mergedAt": "2018-03-05T22:14:10Z", + "mergedBy": "akeranen", + "mergeCommit": { + "oid": "7df4ed22c560bb0a687263d01ba6c95896827587" + }, + "comments": [], + "reviews": [] + }, + { + "number": 20, + "id": "MDExOlB1bGxSZXF1ZXN0MTc1OTk0NDE1", + "title": "Topic hierarchy editorial fixes", + "url": "https://github.com/core-wg/coap-pubsub/pull/20", + "state": "MERGED", + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2018-03-19T18:56:54Z", + "updatedAt": "2018-07-02T22:49:58Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "dfe5aa661bb37c6760ad4a5d3be81e88c0942bb8", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "topic-hierarchy-fixes", + "headRefOid": "b4668582f33837b55f46769b05fac4c3dc7ac7bc", + "closedAt": "2018-07-02T22:49:58Z", + "mergedAt": "2018-07-02T22:49:58Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "408c9ad04bf960f8725245c9b9c627277876b34d" + }, + "comments": [], + "reviews": [] + }, + { + "number": 23, + "id": "MDExOlB1bGxSZXF1ZXN0MTc2MDAyNDk3", + "title": "Added discussion on sub-topic discovery", + "url": "https://github.com/core-wg/coap-pubsub/pull/23", + "state": "MERGED", + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2018-03-19T19:31:00Z", + "updatedAt": "2019-01-02T17:42:25Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "408c9ad04bf960f8725245c9b9c627277876b34d", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "sub-topic-discovery-discussion", + "headRefOid": "9ea2fcef3495ea6b85cb3cbe8aee5da1eb39b5bd", + "closedAt": "2018-07-02T22:59:41Z", + "mergedAt": "2018-07-02T22:59:41Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "47e7939ae6f542f156f0ce2b94e7ad8b5b430c68" + }, + "comments": [], + "reviews": [] + }, + { + "number": 25, + "id": "MDExOlB1bGxSZXF1ZXN0MTk4ODA1MDM4", + "title": "Master", + "url": "https://github.com/core-wg/coap-pubsub/pull/25", + "state": "MERGED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "address email comments and more cleanup of terminology", + "createdAt": "2018-07-02T22:26:58Z", + "updatedAt": "2018-07-02T22:27:52Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "59afb67932ec8cb982be29d757e59afc69cc0f58", + "headRepository": null, + "headRefName": "master", + "headRefOid": "da5c3d0495118c89134288fc69c1e28cab61cb7f", + "closedAt": "2018-07-02T22:27:52Z", + "mergedAt": "2018-07-02T22:27:52Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "dfe5aa661bb37c6760ad4a5d3be81e88c0942bb8" + }, + "comments": [], + "reviews": [] + }, + { + "number": 26, + "id": "MDExOlB1bGxSZXF1ZXN0MTk4ODA4NDY2", + "title": "xml file", + "url": "https://github.com/core-wg/coap-pubsub/pull/26", + "state": "MERGED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2018-07-02T22:49:35Z", + "updatedAt": "2018-07-02T23:00:07Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "dfe5aa661bb37c6760ad4a5d3be81e88c0942bb8", + "headRepository": null, + "headRefName": "master", + "headRefOid": "cd8100ff607c00f2622062bd0b245ceb198a6f23", + "closedAt": "2018-07-02T23:00:07Z", + "mergedAt": "2018-07-02T23:00:07Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "11cdbe599b6d51821cd534c11e154f780a0eea95" + }, + "comments": [], + "reviews": [] + }, + { + "number": 27, + "id": "MDExOlB1bGxSZXF1ZXN0MTk4ODE0NDU2", + "title": "ready for upload", + "url": "https://github.com/core-wg/coap-pubsub/pull/27", + "state": "MERGED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "draft version to upload for IETF 102", + "createdAt": "2018-07-02T23:33:46Z", + "updatedAt": "2018-07-02T23:36:29Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "11cdbe599b6d51821cd534c11e154f780a0eea95", + "headRepository": "mjkoster/pubsub", + "headRefName": "master", + "headRefOid": "0453d84c4a584cc44db4f201588694acc3abadc2", + "closedAt": "2018-07-02T23:36:29Z", + "mergedAt": "2018-07-02T23:36:29Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "aa30422e652705aa797878328bee10868342cd69" + }, + "comments": [], + "reviews": [] + }, + { + "number": 28, + "id": "MDExOlB1bGxSZXF1ZXN0MjAxNDU2NTAz", + "title": "add relevant reference", + "url": "https://github.com/core-wg/coap-pubsub/pull/28", + "state": "MERGED", + "author": "ms-s", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2018-07-14T15:32:22Z", + "updatedAt": "2019-01-02T20:07:01Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "aa30422e652705aa797878328bee10868342cd69", + "headRepository": "ms-s/pubsub", + "headRefName": "master", + "headRefOid": "22a2cc1dd1c64d7251e4be86c1b363e1f8556d81", + "closedAt": "2019-01-02T20:07:01Z", + "mergedAt": "2019-01-02T20:07:01Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "3ac6365d1cae55c8893c2f66e2ba5b80911e35a0" + }, + "comments": [], + "reviews": [ + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MTM3MjQ0MTY2", + "commit": { + "abbreviatedOid": "22a2cc1" + }, + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "state": "APPROVED", + "body": "LGTM", + "createdAt": "2018-07-14T17:34:36Z", + "updatedAt": "2018-07-14T17:34:36Z", + "comments": [] + } + ] + }, + { + "number": 30, + "id": "MDExOlB1bGxSZXF1ZXN0MjQxODE5NTQz", + "title": "Added note on pub/sub being good fit for some apps; resolves #29", + "url": "https://github.com/core-wg/coap-pubsub/pull/30", + "state": "MERGED", + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2019-01-02T18:52:31Z", + "updatedAt": "2019-01-02T20:06:30Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "aa30422e652705aa797878328bee10868342cd69", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "pubsubintro", + "headRefOid": "185ca86575e0bb4d479bb8e092fe8a5211175070", + "closedAt": "2019-01-02T20:06:30Z", + "mergedAt": "2019-01-02T20:06:30Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "448dd4f3795943a85da037ae4636cc268db4d21b" + }, + "comments": [], + "reviews": [] + }, + { + "number": 32, + "id": "MDExOlB1bGxSZXF1ZXN0MjQxOTExNjAz", + "title": "cleanup of CREATE section", + "url": "https://github.com/core-wg/coap-pubsub/pull/32", + "state": "MERGED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "removed duplicate description of hierarchy, added a constraint to allow\nonly one topic to be created at a time, added text to allow additional\ntarget attributes in links for created topics", + "createdAt": "2019-01-03T06:05:29Z", + "updatedAt": "2019-01-04T22:27:46Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "3ac6365d1cae55c8893c2f66e2ba5b80911e35a0", + "headRepository": "mjkoster/pubsub", + "headRefName": "master", + "headRefOid": "3015934712655aab69743e1ed1bacdfbe5d4cf49", + "closedAt": "2019-01-04T22:27:46Z", + "mergedAt": "2019-01-04T22:27:46Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "fe126ebcf8db0a377a86a2a2dde11ea172e21d71" + }, + "comments": [], + "reviews": [ + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MTg5MDI2MjYy", + "commit": { + "abbreviatedOid": "f18d700" + }, + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "state": "CHANGES_REQUESTED", + "body": "", + "createdAt": "2019-01-03T14:16:19Z", + "updatedAt": "2019-01-03T14:20:35Z", + "comments": [ + { + "originalPosition": 29, + "body": "Is this sentence (\"link attribute value in payload\") correct?", + "createdAt": "2019-01-03T14:16:19Z", + "updatedAt": "2019-01-03T14:22:13Z" + }, + { + "originalPosition": 35, + "body": "s/may/MUST/ ?", + "createdAt": "2019-01-03T14:20:03Z", + "updatedAt": "2019-01-03T14:22:13Z" + } + ] + } + ] + }, + { + "number": 33, + "id": "MDExOlB1bGxSZXF1ZXN0MjYwMDkwMDUy", + "title": "Update per Feb. 7th meeting", + "url": "https://github.com/core-wg/coap-pubsub/pull/33", + "state": "MERGED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "Removed the 2.07 code for no data and expect publisher to publish\nsomething. Clean up Max-Age so it applies to the topic. address email\ncomments.", + "createdAt": "2019-03-11T18:42:45Z", + "updatedAt": "2019-03-11T23:41:18Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "fe126ebcf8db0a377a86a2a2dde11ea172e21d71", + "headRepository": "mjkoster/pubsub", + "headRefName": "master", + "headRefOid": "fd11bbb3f3fa7eafdd0fe7ff8160e0b2d0efcfe6", + "closedAt": "2019-03-11T23:41:18Z", + "mergedAt": "2019-03-11T23:41:18Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "2aeb1f7a98cb7dcba722f2832bc0476eef2b61b9" + }, + "comments": [], + "reviews": [ + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MjEzMDI2NDM1", + "commit": { + "abbreviatedOid": "29b92e8" + }, + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "state": "COMMENTED", + "body": "", + "createdAt": "2019-03-11T18:59:53Z", + "updatedAt": "2019-03-11T19:43:26Z", + "comments": [ + { + "originalPosition": 69, + "body": "s/returns errors on subscription/the broker returns \"4.04\" error response to subscription requests on the topic/", + "createdAt": "2019-03-11T18:59:53Z", + "updatedAt": "2019-03-11T23:15:53Z" + }, + { + "originalPosition": 70, + "body": "s/outstanding subscriptions are cancelled/outstanding subscriptions for the topic are cancelled by sending a \"4.04\" response code to subscribers of the topic/", + "createdAt": "2019-03-11T19:02:41Z", + "updatedAt": "2019-03-11T23:15:53Z" + }, + { + "originalPosition": 90, + "body": "Supporting just single ct is better.", + "createdAt": "2019-03-11T19:39:36Z", + "updatedAt": "2019-03-11T23:15:53Z" + } + ] + }, + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MjEzMTMwMjEy", + "commit": { + "abbreviatedOid": "c6a74f0" + }, + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "state": "COMMENTED", + "body": "", + "createdAt": "2019-03-11T23:14:06Z", + "updatedAt": "2019-03-11T23:14:07Z", + "comments": [ + { + "originalPosition": 70, + "body": "This part needs WG discussion", + "createdAt": "2019-03-11T23:14:07Z", + "updatedAt": "2019-03-11T23:15:53Z" + } + ] + }, + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MjEzMTMwMjk3", + "commit": { + "abbreviatedOid": "c6a74f0" + }, + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "state": "COMMENTED", + "body": "", + "createdAt": "2019-03-11T23:14:24Z", + "updatedAt": "2019-03-11T23:14:24Z", + "comments": [ + { + "originalPosition": 90, + "body": "This whole feature needs WG discussion", + "createdAt": "2019-03-11T23:14:24Z", + "updatedAt": "2019-03-11T23:15:53Z" + } + ] + }, + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MjEzMTMyNjc0", + "commit": { + "abbreviatedOid": "fd11bbb" + }, + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "state": "COMMENTED", + "body": "", + "createdAt": "2019-03-11T23:23:38Z", + "updatedAt": "2019-03-11T23:23:38Z", + "comments": [ + { + "originalPosition": 90, + "body": "Updated to require one ct\r\n", + "createdAt": "2019-03-11T23:23:38Z", + "updatedAt": "2019-03-11T23:23:39Z" + } + ] + } + ] + }, + { + "number": 35, + "id": "MDExOlB1bGxSZXF1ZXN0Mjk1NDI5OTY1", + "title": "Proposal for PubSub Broker Improvements", + "url": "https://github.com/core-wg/coap-pubsub/pull/35", + "state": "MERGED", + "author": "ektrah", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "@mjkoster @akeranen PTAL", + "createdAt": "2019-07-08T17:30:41Z", + "updatedAt": "2019-07-09T08:55:23Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "2aeb1f7a98cb7dcba722f2832bc0476eef2b61b9", + "headRepository": null, + "headRefName": "redesign", + "headRefOid": "69d8a006a9f6eeeb9f01421d1ff5b4448633dc8e", + "closedAt": "2019-07-08T20:11:22Z", + "mergedAt": "2019-07-08T20:11:22Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "8a10947836c4ac66429a2982f530a88012a2e31b" + }, + "comments": [], + "reviews": [] + }, + { + "number": 36, + "id": "MDExOlB1bGxSZXF1ZXN0Mjk3MjM3MTc2", + "title": "Small proposal improvements", + "url": "https://github.com/core-wg/coap-pubsub/pull/36", + "state": "MERGED", + "author": "ektrah", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "cc @mjkoster @akeranen ", + "createdAt": "2019-07-12T22:01:05Z", + "updatedAt": "2019-07-21T15:18:45Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "8a10947836c4ac66429a2982f530a88012a2e31b", + "headRepository": null, + "headRefName": "redesign-fixes", + "headRefOid": "79a83a4c9da5c5c24ac231cd246a60ff2a149138", + "closedAt": "2019-07-17T22:43:19Z", + "mergedAt": "2019-07-17T22:43:19Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "61e5dff454244ace1ee040246b303e07d40c8ecb" + }, + "comments": [ + { + "author": "cabo", + "authorAssociation": "MEMBER", + "body": "For some reason, I can't login to GitHub today. So I'll use this issue for discussing the proposal, sorry. \n\nA subscriber that is waiting for the first Data should observe the info object? An example might help. \n\nSo the data link had to be there from the outset (with a 404) so the publisher can PUT to it? But then it's not a 404, but a 405. \n\n\n\nSent from mobile, sorry for terse\n\n> On 18. Jul 2019, at 00:43, Michael Koster wrote:\n> \n> Merged #36 into master.\n> \n> \u2014\n> You are receiving this because you are subscribed to this thread.\n> Reply to this email directly, view it on GitHub, or mute the thread.\n", + "createdAt": "2019-07-18T07:46:07Z", + "updatedAt": "2019-07-18T07:46:07Z" + }, + { + "author": "ektrah", + "authorAssociation": "CONTRIBUTOR", + "body": "Let\u2019s discuss on the CoRE mailing list.", + "createdAt": "2019-07-18T11:04:29Z", + "updatedAt": "2019-07-18T11:04:29Z" + } + ], + "reviews": [ + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MjYzMTcwNDM0", + "commit": { + "abbreviatedOid": "79a83a4" + }, + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "state": "APPROVED", + "body": "LGTM. We may want to add some more text on client hinting what should the topic be while server keeping the authority to generate them.", + "createdAt": "2019-07-17T16:23:40Z", + "updatedAt": "2019-07-17T16:23:40Z", + "comments": [] + } + ] + }, + { + "number": 37, + "id": "MDExOlB1bGxSZXF1ZXN0Mjk5NjQ0Nzc4", + "title": "Some proposal additions", + "url": "https://github.com/core-wg/coap-pubsub/pull/37", + "state": "MERGED", + "author": "ektrah", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "cc @akeranen @mjkoster", + "createdAt": "2019-07-21T15:29:59Z", + "updatedAt": "2019-07-22T17:58:11Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "61e5dff454244ace1ee040246b303e07d40c8ecb", + "headRepository": null, + "headRefName": "redesign-additions", + "headRefOid": "5dd3c4d3b5e429f1511bfa520424de7331f35861", + "closedAt": "2019-07-22T17:56:24Z", + "mergedAt": "2019-07-22T17:56:24Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "fc4f81520b4d9a94fb30e186803ab28bf645befe" + }, + "comments": [], + "reviews": [ + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MjY0OTM5MjMz", + "commit": { + "abbreviatedOid": "5dd3c4d" + }, + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "state": "APPROVED", + "body": "", + "createdAt": "2019-07-22T17:22:44Z", + "updatedAt": "2019-07-22T17:22:44Z", + "comments": [] + } + ] + }, + { + "number": 38, + "id": "MDExOlB1bGxSZXF1ZXN0MzAzMzI0Mjcx", + "title": "More proposal improvements", + "url": "https://github.com/core-wg/coap-pubsub/pull/38", + "state": "MERGED", + "author": "ektrah", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "cc @mjkoster @akeranen @jimsch @chrysn", + "createdAt": "2019-08-01T10:39:00Z", + "updatedAt": "2020-01-02T23:18:09Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "fc4f81520b4d9a94fb30e186803ab28bf645befe", + "headRepository": null, + "headRefName": "redesign-updates", + "headRefOid": "b8b751f0c4fe7137316292c84f1874c9543da66a", + "closedAt": "2019-08-01T16:14:40Z", + "mergedAt": "2019-08-01T16:14:39Z", + "mergedBy": "mjkoster", + "mergeCommit": { + "oid": "35cf03a6bf30cbb76641a47e3254e27642798ec8" + }, + "comments": [], + "reviews": [ + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MjY5NzE5ODcz", + "commit": { + "abbreviatedOid": "b8b751f" + }, + "author": "akeranen", + "authorAssociation": "CONTRIBUTOR", + "state": "APPROVED", + "body": "", + "createdAt": "2019-08-01T15:57:17Z", + "updatedAt": "2019-08-01T15:57:17Z", + "comments": [] + } + ] + }, + { + "number": 39, + "id": "MDExOlB1bGxSZXF1ZXN0MzIyOTA4NjAy", + "title": "MJK update", + "url": "https://github.com/core-wg/coap-pubsub/pull/39", + "state": "CLOSED", + "author": "mjkoster", + "authorAssociation": "CONTRIBUTOR", + "assignees": [], + "labels": [], + "body": "I bumped the version number and put a paragraph into the abstract pointing to the proposal", + "createdAt": "2019-09-30T18:13:59Z", + "updatedAt": "2023-03-01T17:59:52Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "35cf03a6bf30cbb76641a47e3254e27642798ec8", + "headRepository": "mjkoster/pubsub", + "headRefName": "mjk-update", + "headRefOid": "bd1e236a0549827e1307f3e11acd43f1af91a6f0", + "closedAt": "2023-03-01T17:59:51Z", + "mergedAt": null, + "mergedBy": null, + "mergeCommit": null, + "comments": [], + "reviews": [ + { + "id": "MDE3OlB1bGxSZXF1ZXN0UmV2aWV3MzY4Njk3NjA4", + "commit": { + "abbreviatedOid": "bd1e236" + }, + "author": "jaimejim", + "authorAssociation": "MEMBER", + "state": "APPROVED", + "body": "", + "createdAt": "2020-03-04T11:21:49Z", + "updatedAt": "2020-03-04T11:21:49Z", + "comments": [] + } + ] + }, + { + "number": 43, + "id": "PR_kwDOBEc_t843R7_P", + "title": "v10 update", + "url": "https://github.com/core-wg/coap-pubsub/pull/43", + "state": "CLOSED", + "author": "jaimejim", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "Simple edition for the v10 submission of this document. \r\nReferences have been updated, indentation and few initd corrections made.\r\nI'd also like to rename the file `draft-ietf-core-coap-pubsub.md` instead of `draft-ietf-core-pubsub.md`", + "createdAt": "2022-05-04T10:08:23Z", + "updatedAt": "2022-05-04T11:19:09Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "master", + "baseRefOid": "13c522b7bfd140b6a2f9c2b51ada1caebd5f39fa", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "jaime-update", + "headRefOid": "0a2d3085f2b730a4406cb94ab3f1fc8a38fdae9d", + "closedAt": "2022-05-04T11:19:08Z", + "mergedAt": null, + "mergedBy": null, + "mergeCommit": null, + "comments": [], + "reviews": [] + }, + { + "number": 46, + "id": "PR_kwDOBEc_t85KIbFP", + "title": "added link to ongoing revision on README", + "url": "https://github.com/core-wg/coap-pubsub/pull/46", + "state": "CLOSED", + "author": "jaimejim", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2023-02-16T13:46:30Z", + "updatedAt": "2023-03-01T17:59:53Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "main", + "baseRefOid": "c4647aef3b9266903a998797f3981293c5bbab93", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "master", + "headRefOid": "79dbaf2647c1f4e6b92bdab59cc562b0f0a967fa", + "closedAt": "2023-03-01T17:59:52Z", + "mergedAt": null, + "mergedBy": null, + "mergeCommit": null, + "comments": [], + "reviews": [] + }, + { + "number": 47, + "id": "PR_kwDOBEc_t85KfcH-", + "title": "Typos", + "url": "https://github.com/core-wg/coap-pubsub/pull/47", + "state": "CLOSED", + "author": "cabo", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2023-02-22T08:24:14Z", + "updatedAt": "2023-02-22T13:24:12Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "main", + "baseRefOid": "c4647aef3b9266903a998797f3981293c5bbab93", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "typos", + "headRefOid": "7ef9727818b1ce5ecb964d709b352f19a124029f", + "closedAt": "2023-02-22T08:38:42Z", + "mergedAt": null, + "mergedBy": null, + "mergeCommit": null, + "comments": [ + { + "author": "cabo", + "authorAssociation": "MEMBER", + "body": "That didn't work very well. Resubmitting a new PR", + "createdAt": "2023-02-22T08:38:42Z", + "updatedAt": "2023-02-22T08:38:42Z" + } + ], + "reviews": [] + }, + { + "number": 48, + "id": "PR_kwDOBEc_t85Kfoo-", + "title": "Misc typos", + "url": "https://github.com/core-wg/coap-pubsub/pull/48", + "state": "MERGED", + "author": "cabo", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "", + "createdAt": "2023-02-22T09:06:59Z", + "updatedAt": "2023-03-01T17:56:17Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "ps-rev", + "baseRefOid": "82784969857abf53ff8ac337d2ecefdd502b7622", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "typos1", + "headRefOid": "08ef83b79b0ea5426c13dac84d2934c3c4da312f", + "closedAt": "2023-03-01T17:56:08Z", + "mergedAt": "2023-03-01T17:56:08Z", + "mergedBy": "jaimejim", + "mergeCommit": { + "oid": "98770b7d757981760486007ebbe500939e534bb1" + }, + "comments": [], + "reviews": [] + }, + { + "number": 49, + "id": "PR_kwDOBEc_t85L70r5", + "title": "Merging v12 on main", + "url": "https://github.com/core-wg/coap-pubsub/pull/49", + "state": "OPEN", + "author": "jaimejim", + "authorAssociation": "MEMBER", + "assignees": [], + "labels": [], + "body": "New pubsub draft merge", + "createdAt": "2023-03-13T21:12:12Z", + "updatedAt": "2023-03-13T21:17:10Z", + "baseRepository": "core-wg/coap-pubsub", + "baseRefName": "main", + "baseRefOid": "e1b2724949b44830f244acfee0b1d61537ff2a32", + "headRepository": "core-wg/coap-pubsub", + "headRefName": "ps-rev", + "headRefOid": "0b50aa2b88663bdb547d44979202e6c073067d1e", + "closedAt": null, + "mergedAt": null, + "mergedBy": null, + "mergeCommit": null, + "comments": [], + "reviews": [] + } + ] +} \ No newline at end of file diff --git a/circle.yml b/circle.yml new file mode 100644 index 0000000..56ad41b --- /dev/null +++ b/circle.yml @@ -0,0 +1,4 @@ +general: + branches: + ignore: + - gh-pages diff --git a/draft-ietf-core-coap-pubsub.html b/draft-ietf-core-coap-pubsub.html new file mode 100644 index 0000000..2c4e499 --- /dev/null +++ b/draft-ietf-core-coap-pubsub.html @@ -0,0 +1,2804 @@ + + + + + + +A publish-subscribe architecture for the Constrained Application Protocol (CoAP) + + + + + + + + + + + + + + + + + + + + + + + + +
Internet-DraftA publish-subscribe architecture for theNovember 2023
Jimenez, et al.Expires 8 May 2024[Page]
+
+
+
+
Workgroup:
+
CoRE Working Group
+
Internet-Draft:
+
draft-ietf-core-coap-pubsub-latest
+
Published:
+
+ +
+
Intended Status:
+
Standards Track
+
Expires:
+
+
Authors:
+
+
+
J. Jimenez
+
Ericsson
+
+
+
M. Koster
+
Dogtiger Labs
+
+
+
A. Keranen
+
Ericsson
+
+
+
+
+

A publish-subscribe architecture for the Constrained Application Protocol (CoAP)

+
+

Abstract

+

This document describes a publish-subscribe architecture for the Constrained Application Protocol (CoAP), extending the capabilities of CoAP communications for supporting endpoints with long breaks in connectivity and/or up-time. CoAP clients publish on and subscribe to a topic via a corresponding topic resource at a CoAP server acting as broker.

+
+
+

+About This Document +

+

This note is to be removed before publishing as an RFC.

+

+ Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-core-coap-pubsub/.

+

+ Discussion of this document takes place on the + core Working Group mailing list (mailto:core@ietf.org), + which is archived at https://mailarchive.ietf.org/arch/browse/core/. + Subscribe at https://www.ietf.org/mailman/listinfo/core/.

+

Source for this draft and an issue tracker can be found at + https://github.com/core-wg/coap-pubsub.

+
+
+
+

+Status of This Memo +

+

+ This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79.

+

+ Internet-Drafts are working documents of the Internet Engineering Task + Force (IETF). Note that other groups may also distribute working + documents as Internet-Drafts. The list of current Internet-Drafts is + at https://datatracker.ietf.org/drafts/current/.

+

+ Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress."

+

+ This Internet-Draft will expire on 8 May 2024.

+
+
+ +
+
+ ▲

+Table of Contents +

+ +
+
+
+
+

+1. Introduction +

+

The Constrained Application Protocol (CoAP) [RFC7252] supports +machine-to-machine communication across networks of constrained +devices and constrained networks. CoAP uses a request/response model where clients make requests to servers in order to request actions on resources. Depending on the situation the same device may act either as a server, a client, or both.

+

One important class of constrained devices includes devices that are intended to run for years from a small battery, or by scavenging energy from their environment. These devices have limited up-time because they spend most of their time in a sleeping state with no network connectivity. Another important class of nodes are devices with limited reachability due to middle-boxes like Network Address Translators (NATs) and firewalls.

+

For these nodes, the client/server-oriented architecture of REST can be challenging when interactions are not initiated by the devices themselves. A publish/subscribe-oriented architecture where nodes exchange data via topics through a broker entity might fit these nodes better.

+

This document applies the idea of broker-based publish-subscribe to Constrained RESTful Environments using CoAP. It defines a broker that allows to create, discover subscribe and publish on topics.

+
+
+

+1.1. Terminology +

+

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", +"MAY", and "OPTIONAL" in this document are to be interpreted as +described in BCP 14 [RFC2119] [RFC8174] when, and only when, they +appear in all capitals, as shown here.

+

This specification requires readers to be familiar with all the terms and +concepts that are discussed in [RFC8288] and [RFC6690]. Readers +should also be familiar with the terms and concepts discussed in +[RFC7252], [RFC9176] and [RFC7641]. The URI template +format [RFC6570] is used to describe the REST API defined in +this specification.

+

This specification makes use of the following terminology:

+
+
publish-subscribe (pub/sub):
+
+

A message communication model where messages associated with specific topics are sent to a broker. Interested parties, i.e. subscribers, receive these topic-based messages from the broker without the original sender knowing the recipients. The broker handles matching and delivering these messages to the appropriate subscribers.

+
+
+
publishers and subscribers:
+
+

CoAP clients can act as publishers or as subscribers. Publishers send CoAP messages (publications) to the broker on specific topics. Subscribers have an ongoing observation relation (subscription) to a topic. Both roles operate without any mutual knowledge, guided by their respective topic interests.

+
+
+
topic collection:
+
+

A set of topic configurations. A topic collection is hosted as one collection resource at the broker, and its representation is the list of links to the topic resources corresponding to each topic configuration.

+
+
+
topic-configuration:
+
+

A set of information concerning a topic, including its configuration and other metadata. A topic configuration is hosted as one topic resource at the broker, and its representation is the set of configuration information concerning the topic. All the topic resources associated with the same topic collection share a common base URI, i.e., the URI of the collection resource. Throughout this document the word "topic" and "topic-configuration" can be used interchangeably.

+
+
+
topic-data resource:
+
+

A resource where clients can publish data and/or subscribe to data for a specific topic. The representation of the topic resource corresponding to such a topic also specifies the URI to the present topic-data resource.

+
+
+
broker:
+
+

A CoAP server that hosts one or more topic collections with their topic-configurations, and also topic-data resources. The broker is responsible for the store-and-forward of state update representations, for the topics for which it hosts the corresponding topic-data resources. 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.

+
+
+
+
+
+
+
+

+1.2. CoAP Publish-Subscribe Architecture +

+

Figure 1 shows a simple Publish/Subscribe architecture over CoAP.

+

Topics are created by the broker, but the initial configuration can be proposed by a client (e.g., a publisher or a dedicated administrator) over the RESTful interface of a corresponding topic resource hosted by the broker.

+

Publishers submit their data over the RESTful interface of a topic-data resource corresponding to the topic, which may be hosted by the broker. Subscribers to a topic are notified of new publications by using Observe [RFC7641] on the corresponding topic-data resource.

+

The broker is responsible for the store-and-forward of state update representations between CoAP clients. Subscribers observing a resource will receive notifications, the delivery of which is done on a best-effort basis.

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CoAP + CoAP + CoAP + clients + server + clients + observe + publish + publisher + subscribe + ... + broker + ... + ... + ... + observe + publish + publisher + subscribe + + +
+
+
Figure 1: +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 3.2).

+

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

+

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

+
+
+
+
+

+1.3. Managing Topics +

+

Figure 2 shows the resources related to a Topic Collection that can be managed at the Broker.

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + topic + collection + resource + ... + topic + resources + + +
+
+
Figure 2: +Resources of a Broker +
+
+

The Broker exports one or more topic-collection resources, 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.

+

A topic-collection resource can have topic resources as its child resources, with resource type "core.ps.conf".

+
+
+
+
+
+
+

+2. Pub-Sub Topics +

+

The configuration side of a "publish/subscribe broker" consists of a collection of topics. These topics as well as the collection itself are exposed by a CoAP server as resources (see Figure 3). Each topic is associated with a topic configuration resource and a topic-data resource. The topic configuration resource is used by a client creating or administering a topic. The topic-data resource is used by the publishers and the subscribers to a topic.

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + topic + collection + resource + ...... + ...... + ...... + topic + : + : + : + : + : + : + configuration + : + : + : + : + : + : + resource + : + _ + _ + : + : + _ + _ + : + : + _ + _ + : + .... + .... + .... + .... + .... + .... + .... + .... + .... + .... + .... + .... + : + _ + _ + : + : + _ + _ + : + ... + : + _ + _ + : + topic-data + : + : + : + : + : + : + resource + : + : + : + : + : + : + :.......: + :.......: + :.......: + \ + / + ... + \ + / + topic + 1 + topic + 2 + topic + n + + +
+
+
Figure 3: +Topic and topic-data resources of a topic +
+
+
+
+

+2.1. Collection Representation +

+

Each topic configuration is represented as a link, where the link target is the URI of the corresponding topic resource.

+

Publication and subscription to a topic occur at a link, where the link target is the URI of the corresponding topic-data resource. Such a link is specified by the topic-data entry within the topic resource (see Section 2.2.1).

+

A topic resource with a topic-data link can also be simply called "topic".

+

The list of links to the topic resources can be retrieved from the associated topic collection resource, and represented as a Link Format document [RFC6690]where each such link specifies the link target attribute 'rt' (Resource Type), with value "core.ps.conf" defined in this document.

+
+
+
+
+

+2.2. Topic-Configuration Representation +

+

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 4.

+
+
+

+2.2.1. Topic Properties +

+

The CBOR map includes the following configuration parameters, whose 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 topic names include human-readable strings (e.g., "room2"), UUIDs, or other values.

    +
    • +
  • +

    'topic-data': A required field (optional during creation) containing the URI of the topic-data resource for publishing/subscribing to this topic. It encodes the URI as a CBOR text string.

    +
    • +
  • +

    'resource-type': A required field used to indicate the resource type of the topic-data resource for the topic. It encodes the resource type as a CBOR text string. The value should be "core.ps.conf".

    +
    • +
+
    +
  • +

    'media-type': An optional field used to indicate the media type of the topic-data resource for the topic. It encodes the media type as a this information as the integer identifier of the CoAP content-format (e.g., value is "50" for "application/json").

    +
    • +
  • +

    'topic-type': An optional field used to indicate the attribute or property of the topic-data resource for the topic. It encodes the attribute as a CBOR text string. Example attributes include "temperature".

    +
    • +
  • +

    'expiration-date': An optional field used to indicate the expiration date of the topic. It encodes the expiration date as a CBOR text string. The value should be a date string in ISO 8601 format (e.g., "2023-03-31T23:59:59Z"). The broker can use this field to automatically remove topics that are no longer valid. If this field is not present, the topic will not expire automatically.

    +
    • +
  • +

    'max-subscribers': An optional field used to indicate the maximum number of simultaneous subscribers allowed for the topic. It encodes the maximum number as an unsigned CBOR integer. If this field is not present, there is no limit to the number of simultaneous subscribers allowed. The broker can use this field to limit the number of subscribers for the topic. The default value for this field has been set to 100 subscribers.

    +
    • +
  • +

    'observer-check': An optional field that controls the maximum number of seconds between two consecutive Observe notifications sent as Confirmable messages to each topic subscriber. Encoded as a CBOR unsigned integer greater than 0, it ensures subscribers who have lost interest and silently forgotten the observation do not remain indefinitely on the server's observer list. If another CoAP server hosts the topic-data resource, that server is responsible for applying the observer-check value. The default value for this field is 86400, as defined in [RFC7641], which corresponds to 24 hours.

    +
    • +
+
+
+
+
+
+
+

+2.3. Discovery +

+

A client can perform a discovery of: the broker; the topic collection resources and topic resources hosted by the broker; and the topic-data resources associated with those topic resources.

+
+
+

+2.3.1. Broker Discovery +

+

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

+

The following example shows an endpoint discovering a broker using the "core.ps" resource type over a multicast network. Brokers within the multicast scope will answer the query.

+
+
+=> 0.01 GET
+   Uri-Path: coap://[ff0x::fe]/.well-known/core
+   Resource-Type: core.ps
+
+<= 2.05 Content
+   Payload:
+   Content-Format: 40 (application/link-format)
+   <coap://mythinguri.com/broker/v1>; rt=core.ps
+
+
+
+
+
+
+

+2.3.2. Topic Collection Discovery +

+

A Broker SHOULD offer a topic discovery entry point to enable clients to find topics of interest. The resource entry point is the topic collection resource collecting the topic configurations for those topics (see Section 1.2.2 of [RFC6690]) and is identified by the resource type "core.ps.coll".

+

The specific resource path is left for implementations, examples in this document use the "/ps" path. The interactions with a topic collection are further defined in Section 2.4.

+

Since the representation of the topic collection resource includes the links to the associated topic resources, it is not required to locate those links under "/.well-known/core", also in order to limit the size of the Link Format document returned as result of the discovery.

+

Example:

+
+
+=> 0.01 GET
+   Uri-Path: .well-known/core
+   Resource-Type: core.ps.coll
+
+   <= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps1>;rt="core.ps.coll";ct=40,
+   </other/path>;rt="core.ps.coll";ct=40
+
+
+
+
+
+
+

+2.3.3. Topic-Configuration Discovery +

+

Each topic collection is associated with a group of topic resources, each detailing the configuration of its respective topic (refer to Section 2.2.1). Each topic resource is identified by the resource type "core.ps.conf".

+

Below is an example of discovery via /.well-known/core with rt=core.ps.conf that returns a list of topics, as the list of links to the corresponding topic resources.

+
+
+=> 0.01 GET
+   Uri-Path: .well-known/core
+   Resource-Type: core.ps.conf
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps1/h9392>;rt="core.ps.conf";ct=TBD,
+   </other/path/2e3570>;rt=core.ps.conf;ct=TBD
+
+
+
+
+
+
+

+2.3.4. Topic-Data Discovery +

+

Within a topic, there is the topic-data property containing the URI of the topic-data resource that a CoAP client can subscribe and publish to. Resources exposing resources of the topic-data type are expected to use the resource type 'core.ps.data'.

+

The topic-data contains the URI of the topic-data resource for publishing and subscribing. So retrieving the topic configuration will also provide the URL of the topic-data (see Section 2.5.1).

+

It is also possible to discover a list of topic-data resources by sending a request to the collection with with rt=core.ps.data resources as shown below.

+
+
+=> 0.01 GET
+   Uri-Path: /ps
+   Resource-Type: core.ps.data
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps/data/62e4f8d>; rt=core.ps.data; obs
+
+
+
+
+
+
+
+
+

+2.4. Topic Collection Interactions +

+

These are the interactions that can happen directly with a specific topic collection.

+
+
+

+2.4.1. Retrieving all topic-configurations +

+

A client can request a collection of the topics present in the broker by making a GET request to the collection URI.

+

On success, the server returns a 2.05 (Content) response, specifying the list of links to topic resources associated with this topic collection (see Section 2.2).

+

Depending on its granted permissions, a client MAY retrieve a different list of links, corresponding to the topics that the client is authorized to access.

+

Example:

+
+
+=> 0.01 GET
+   Uri-Path: ps
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps/h9392>;rt="core.ps.conf",
+   </ps/2e3570>; rt="core.ps.conf"
+
+
+
+
+
+
+

+2.4.2. Getting topic-configurations by Properties +

+

A client can filter a collection of topics by submitting the +representation of a topic filter (see Section 2.5.2) in a FETCH request to the topic collection URI.

+

On success, the server returns a 2.05 (Content) response with a +representation of a list of topics in the collection (see + Section 2.3.3) that match the filter in CoRE link format [RFC6690].

+

Upon success, the server responds with a 2.05 (Content), providing a list of links to topic resources associated with this topic collection that match the request's filter criteria (refer to Section 2.3.3). A positive match happens only when each request parameter is present with the indicated value in the topic resource representation.

+

Example:

+
+
+=> 0.05 FETCH
+   Uri-Path: ps
+   Content-Format: TBD (application/pubsub+cbor)
+
+   {
+     "resource-type": "core.ps.conf",
+     "topic-type": "temperature"
+   }
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps/2e3570>;rt="core.ps.conf"
+
+
+
+
+
+
+

+2.4.3. Creating a Topic +

+

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

+

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 Location-Path of the new topic and the current representation of the topic resource. The response payload includes a CBOR map with key-value pairs. The response must include the required topic properties (see Section 2.2.1), namely: "topic-name", "resource-type" and "topic-data". It may also include a number of optional properties too.

+

If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST respond with a 4.03 (Forbidden) error. The response MUST have Content-Format set to "application/core-pubsub+cbor".

+

The broker MUST issue a 4.00 (Bad Request) error if a received parameter is invalid, unrecognized, or if the topic-name is already in use or otherwise invalid.

+
+
+=> 0.02 POST
+   Uri-Path: ps
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   TBD (this should be a CBOR map with the mandatory parameters)
+   {
+     "topic-name": "living-room-sensor",
+     "resource-type": "core.ps.conf"
+   }
+
+<= 2.01 Created
+   Location-Path: ps/h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   TBD (this should be a CBOR map)
+   {
+     "topic-name": "living-room-sensor",
+     "topic-data": "ps/data/1bd0d6d",
+     "resource-type": "core.ps.conf"
+   }
+
+
+
+
+
+
+
+
+

+2.5. Topic-Configuration Interactions +

+

These are the interactions that can happen at the topic resource level.

+
+
+

+2.5.1. Getting a topic-configuration +

+

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 partial representation of the topic resource, as specified in Section 2.2. The partial representation includes only the configuration parameters such that they are present and have the same value in both the current topic configuration as well as in the FETCH request.

+

If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker 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 4.

+

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

+
+
+=> 0.01 GET
+   Uri-Path: ps
+   Uri-Path: h9392
+
+<= 2.05 Content
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   {
+      "topic-name" : "living-room-sensor",
+      "topic-data" : "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "temperature",
+      "expiration-date": "2023-04-00T23:59:59Z",
+      "max-subscribers": 100
+   }
+
+
+
+
+
+
+
+

+2.5.2. Getting part of a topic-configuration +

+

A client can read the configuration of a topic by making a FETCH request to the topic resource URI with a filter for specific parameters. This is done in order to retrieve part of the current topic resource.

+

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 requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker 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 4.

+

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

+

Example:

+
+
+=> 0.05 FETCH
+   Uri-Path: ps
+   Uri-Path: h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   {
+     "conf-filter": ["topic-data", "media-type"]
+   }
+
+<= 2.05 Content
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   {
+     "topic-data": "ps/data/1bd0d6d",
+     "media-type": "application/senml-cbor"
+   }
+
+
+
+
+
+
+
+

+2.5.3. Updating the topic-configuration +

+

A client can update a topic's configuration by submitting the updated topic representation in a PUT request to the topic URI. However, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker.

+

On success, the topic configuration is overwritten and server returns a 2.04 (Changed) response and the current full resource representation. The broker may chose not to overwrite parameters that are not explicitly modified in the request.

+

Note that updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Updating the "topic-data" may happen also after it being deleted, as described on {delete-topic-data}, this will in turn create a new "topic-data" path for that topic configuration.

+

Similarly, decreasing max-subscribers will also cause that some subscribers get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per [RFC7641] Section 3.2.

+

Please note that when using PUT the topic configuration is being overwritten, thus some of the optional parameters (e.g., "max-subscribers", "observer-check") not included in the PUT message will be reset to their default values.

+

Example:

+
+
+=> 0.03 PUT
+   Uri-Path: ps
+   Uri-Path: h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   {
+      "topic-name": "living-room-sensor",
+      "topic-data": "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "temperature",
+      "expiration-date": "2023-04-28T23:59:59Z",
+   }
+
+<= 2.04 Changed
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   TBD (this should be a CBOR map)
+   {
+      "topic-name": "living-room-sensor",
+      "topic-data": "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "temperature",
+      "expiration-date": "2023-04-28T23:59:59Z",
+      "max-subscribers": 100,
+      "observer-check": 86400
+   }
+
+
+

Note that 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.

    +
    • +
  • +

    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.

    +
    • +
+
+
+
+
+

+2.5.4. Updating the topic-configuration with iPATCH +

+

A client can partially update a topic's configuration by submitting a partial topic representation in an iPATCH request to the topic URI. The iPATCH request allows for updating only specific fields of the topic configuration while leaving the others unchanged. As with the PUT method, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker.

+

On success, the server returns a 2.04 (Changed) response and the current full resource representation. The broker only updates parameters that are explicitly mentioned in the request.

+

As with the PUT method, updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Decreasing max-subscribers will also cause some subscribers to get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per [RFC7641] Section 3.2.

+

Contrary to PUT iPATCH operations will explicitly update some parameters, leaving others unmodified.

+
+
+=> 0.07 iPATCH
+   Uri-Path: ps
+   Uri-Path: h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   {
+      "topic-type": "humidity",
+      "max-subscribers": 5
+   }
+
+<= 2.04 Changed
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   TBD (this should be a CBOR map)
+   {
+      "topic-name" : "living-room-sensor",
+      "topic-data" : "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "humidity",
+      "expiration-date": "2023-05-28T23:59:59Z",
+      "max-subscribers": 5
+   }
+
+
+

Note that when a topic configuration changes through an iPATCH request, 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.

+
+
+
+
+

+2.5.5. Deleting a topic-configuration +

+

A client can delete a topic by making a CoAP DELETE request on the topic resource URI.

+

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

+

When a topic-configuration resource is deleted, the broker MUST also delete the topic-data resource, unsubscribe all subscribers by removing them from the list of observers and returning a final 4.04 (Not Found) response as per section 3.2 of [RFC7641].

+

Example:

+
+
+=> 0.04 DELETE
+   Uri-Path: ps
+   Uri-Path: h9392
+
+<= 2.02 Deleted
+
+
+
+
+
+
+
+
+
+
+

+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 Observe option set to 0 (register) to a topic-data resource. When resource state changes, subscribers observing the resource [RFC7641] at that time will receive a notification.

+

A topic-data resource does not exist until some initial data has been published to it. Before initial data publication, a GET request to the topic-data resource URI results in 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). There is no necessary URI pattern dependence between the URI where the topic-data exists and the URI of the topic-configuration resource.

+
+
+

+3.1. Topic Lifecycle +

+

When a topic is newly created, it is first placed by the broker 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 subscribe to 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 + + +
+
+
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 data by means of a GET request without observe. 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.

+
+
+
+
+

+3.2. Topic-Data Interactions +

+

Interactions with the topic-data resource are covered in this section.

+
+
+

+3.2.1. Publish +

+

A topic-configuration with a topic-data resource must have been created in order to publish data to it (See Section 2.4.3) and be in the half-created or fully-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
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+   Content-Format: 110
+
+   {
+      "n": "coap://dev1.example.com/temperature",
+      "u": "Cel",
+      "t": 1621452122,
+      "v": 23.5
+   }
+
+<= 2.01 Created
+
+
+

Example of subsequent publication:

+
+
+=> 0.03 PUT
+   Uri-Path: ps
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+   Content-Format: 110
+
+   {
+      "n": "coap://dev1.example.com/temperature",
+      "u": "Cel",
+      "t": 1621452149,
+      "v": 22.5
+   }
+
+<= 2.04 Updated
+
+
+
+
+
+
+

+3.2.2. Subscribe +

+

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

+

On success, the server hosting the topic-data resource MUST return 2.05 (Content) notifications with the data and the Observe Option. Otherwise, if no Observe Option is present the client should assume that the subscription was not successful.

+

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". The topic-data does not exist.

+
+
+
+

If the 'max-subscribers' 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
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+   Observe: 0
+
+<= 2.05 Content
+   Content-Format: 110
+   Observe: 10001
+   Max-Age: 15
+
+  {
+    "n": "urn:dev:os:32473-123456",
+    "u": "Cel",
+    "t": 1696341182,
+    "v": 19.87
+  }
+
+<= 2.05 Content
+   Content-Format: 110
+   Observe: 10002
+   Max-Age: 15
+
+  {
+
+    "n": "urn:dev:os:32473-123456",
+    "u": "Cel",
+    "t": 1696340184,
+    "v": 21.87
+  }
+
+
+
+
+
+
+

+3.2.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. Also on Section 3.6 of [RFC7641] the client can simply "forget" the observation and the server will remove it from the list of observers after the next notification.

+

As per [RFC7641] a server that transmits notifications mostly in non-confirmable messages, but it 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.

+
+
+
+
+

+3.2.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 3.1.

+

Example:

+
+
+=> 0.04 DELETE
+   Uri-Path: ps
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+
+<= 2.02 Deleted
+
+
+
+
+
+
+
+
+

+3.3. 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 3.1), the broker MUST return a response code 4.04 (Not Found).

+

Example:

+
+
+=> 0.01 GET
+   Uri-Path: ps
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+
+<= 2.05 Content
+   Content-Format: 110
+   Max-Age: 15
+
+   {
+      "n": "coap://dev1.example.com/temperature",
+      "u": "Cel",
+      "t": 1621452122,
+      "v": 23.5
+   }
+
+
+
+
+
+
+

+3.4. Rate Limiting +

+

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

+

In this situation, if a publisher 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 also stop publishing messages from that publisher for the indicated time.

+

When a publisher 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.

+
+
+
+
+
+
+

+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.

+
+
+
+
++-----------------+-----------+-----------+------------+
+| Name            | CBOR Key  | CBOR Type | Reference  |
+|-----------------|-----------|-----------|------------|
+| topic-name      | TBD1      | tstr      | [RFC-XXXX] |
+| topic-data      | TBD2      | tstr      | [RFC-XXXX] |
+| resource-type   | TBD3      | tstr      | [RFC-XXXX] |
+| media-type      | TBD4      | uint      | [RFC-XXXX] |
+| topic-type      | TBD5      | tstr      | [RFC-XXXX] |
+| expiration-date | TBD6      | tstr      | [RFC-XXXX] |
+| max-subscribers | TBD7      | uint      | [RFC-XXXX] |
+| observer-check  | TBD8      | uint      | [RFC-XXXX] |
++-----------------+-----------+-----------+------------+
+
+
+
Figure 5: +CoAP Pubsub Parameters +
+
+
+
+
+
+

+5. Security Considerations +

+

The architecture presented in this document inherits the security considerations from CoAP [RFC7252] and Observe [RFC7641], as well as from Web Linking [RFC8288], Link-Format [RFC6690], and the CoRE Resource Directory [RFC9176].

+

Communications between each client and the broker MUST be secured, e.g., by using OSCORE [RFC8613] or DTLS [RFC9147]. Security considerations for the used secure communication protocols apply too.

+

The content published on a topic by a publisher client SHOULD be protected end-to-end between the publisher and all the subscribers to that topic. In such a case, it MUST be possible to assert source authentication of the published data. This can be achieved at the application layer, e.g., by using COSE [RFC9052], [RFC9053], [RFC9338].

+

Access control of clients at the broker MAY be enforced for performing discovery operation, and SHOULD be enforced in a fine-grained fashion for operations related to the the creation, update, and deletion of topic resources, as well as for operations on topic-data resources such as publication on and subscription to topics. This prevents rogue clients to, among other things, repeatedly create topics at the broker or publish (large) contents, which may result in Denial of Service against the broker and the active subscribers.

+

Building on [I-D.ietf-ace-key-groupcomm], its application profile for publish-subscribe communication with CoAP [I-D.ietf-ace-pubsub-profile] provides a security model that can be used in the architecture presented in this document, in order to enable secure communication between the different parties as well as secure, authorized operations of publishers and subscribers that fulfill the requirements above.

+

In particular, the application profile above relies on the ACE framework for Authentication and Authorization in Constrained Environments (ACE) [RFC9200] and defines a method to: authorize publishers and subscribers to perform operations at the broker, with fine-grained access control; authorize publishers and subscribers to obtain the keying material required to take part to a topic managed by the broker; protect published data end-to-end between its publisher and all the subscribers to the targeted topic, ensuring confidentiality, integrity, and source authentication of the published content end-to-end. That approach can be extended to enforce authorization and fine-grained access control for administrator clients that are intended to create, update, and delete topic configurations at the broker.

+
+
+
+
+

+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.

+
+
+

+6.1. Media Type +

+

IANA is requested to add the following Media-Type to the "Media Types" +registry [IANA.media-types].

+
+ + + + + + + + + + + + + + + + +
+Table 1: +New Media Type application/pubsub+cbor +
NameTemplateReference
pubsub+cborapplication/pubsub+cborRFC XXXX, Section 6.1 +
+
+
+
Type name:
+
+

application

+
+
+
Subtype name:
+
+

pubsub+cbor

+
+
+
Required parameters:
+
+

N/A

+
+
+
Optional parameters:
+
+

N/A

+
+
+
Encoding considerations:
+
+

binary (CBOR data item)

+
+
+
Security considerations:
+
+

Section 5 of RFC XXXX

+
+
+
Interoperability considerations:
+
+

none

+
+
+
Published specification:
+
+

Section 6.1 of RFC XXXX

+
+
+
Applications that use this media type:
+
+

This type is used by clients that create, retrieve, and update topic configurations at servers acting as a pub-sub broker.

+
+
+
Fragment identifier considerations:
+
+

N/A

+
+
+
Person & email address to contact for further information:
+
+

CoRE WG mailing list (core@ietf.org), +or IETF Applications and Real-Time Area (art@ietf.org)

+
+
+
Intended usage:
+
+

COMMON

+
+
+
Restrictions on usage:
+
+

none

+
+
+
Author/Change controller:
+
+

IETF

+
+
+
Provisional registration:
+
+

no

+
+
+
+
+
+
+
+

+6.2. Content-Format +

+

IANA has added the following Content-Formats to the +"CoAP Content-Formats" +sub-registry, within the "Constrained RESTful Environments (CoRE) +Parameters" Registry [IANA.core-parameters], as follows:

+ + + + + + + + + + + + + + + + + + +
+Table 2: +New Content-Format +
Content TypeContent CodingIDReference
application/pubsub+cbor-TBD9RFC XXXX
+

TBD9 is to be assigned from the space 256..999.

+
+
+
+
+

+6.3. CoAP Pubsub Parameters +

+

IANA is asked to register the following entries in the subregistry of the "Constrained RESTful Environments (CoRE) Parameters" registry group.

+

This specification establishes the "Pubsub Topic Configuration Parameters" IANA registry within the "Constrained RESTful Environments (CoRE) +Parameters" registry group.

+

The columns of this registry are:

+
    +
  • +

    Name: This is a descriptive name that enables easier reference to the item. The name MUST be unique. It is not used in the encoding.

    +
    • +
  • +

    CBOR Key: This is the value used as CBOR key of the item. These values MUST be unique. The value can be a positive integer, a negative integer, or a text string. Different ranges of values use different registration policies [RFC8126]. Integer values from -256 to 255 as well as text strings of length 1 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257 and from 256 to 65535, as well as text strings of length 2 are designated as "Specification Required". Integer values greater than 65535 as well as text strings of length greater than 2 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use".

    +
    • +
  • +

    CBOR Type: This contains the CBOR type of the item, or a pointer to the registry that defines its type, when that depends on another item.

    +
    • +
  • +

    Reference: This contains a pointer to the public specification for the item.

    +
    • +
+

The registry is initially populated with the entries in Figure 5 of Section 4.

+
+
+
+
+

+6.4. 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.

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

+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, Olaf Bergmann and Oscar Novo for their valuable contributions and reviews.

+
+
+
+

+References +

+
+
+

+Normative References +

+
+
[IANA.core-parameters]
+
+IANA, "Constrained RESTful Environments (CoRE) Parameters", <http://www.iana.org/assignments/core-parameters>.
+
+
[IANA.media-types]
+
+IANA, "Media Types", <http://www.iana.org/assignments/media-types>.
+
+
[RFC2119]
+
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
+
+
[RFC6570]
+
+Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, , <https://www.rfc-editor.org/rfc/rfc6570>.
+
+
[RFC6690]
+
+Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, , <https://www.rfc-editor.org/rfc/rfc6690>.
+
+
[RFC7252]
+
+Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, , <https://www.rfc-editor.org/rfc/rfc7252>.
+
+
[RFC7641]
+
+Hartke, K., "Observing Resources in the Constrained Application Protocol (CoAP)", RFC 7641, DOI 10.17487/RFC7641, , <https://www.rfc-editor.org/rfc/rfc7641>.
+
+
[RFC8174]
+
+Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
+
+
[RFC8516]
+
+Keranen, A., ""Too Many Requests" Response Code for the Constrained Application Protocol", RFC 8516, DOI 10.17487/RFC8516, , <https://www.rfc-editor.org/rfc/rfc8516>.
+
+
[RFC8613]
+
+Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, , <https://www.rfc-editor.org/rfc/rfc8613>.
+
+
[RFC9176]
+
+Amsüss, C., Ed., Shelby, Z., Koster, M., Bormann, C., and P. van der Stok, "Constrained RESTful Environments (CoRE) Resource Directory", RFC 9176, DOI 10.17487/RFC9176, , <https://www.rfc-editor.org/rfc/rfc9176>.
+
+
+
+
+
+
+

+Informative References +

+
+
[I-D.hartke-t2trg-coral-pubsub]
+
+Hartke, K., "Publish/Subscribe over the Constrained Application Protocol (CoAP) using the Constrained RESTful Application Language (CoRAL)", Work in Progress, Internet-Draft, draft-hartke-t2trg-coral-pubsub-01, , <https://datatracker.ietf.org/doc/html/draft-hartke-t2trg-coral-pubsub-01>.
+
+
[I-D.ietf-ace-key-groupcomm]
+
+Palombini, F. and M. Tiloca, "Key Provisioning for Group Communication using ACE", Work in Progress, Internet-Draft, draft-ietf-ace-key-groupcomm-17, , <https://datatracker.ietf.org/doc/html/draft-ietf-ace-key-groupcomm-17>.
+
+
[I-D.ietf-ace-oscore-gm-admin]
+
+Tiloca, M., Höglund, R., Van der Stok, P., and F. Palombini, "Admin Interface for the OSCORE Group Manager", Work in Progress, Internet-Draft, draft-ietf-ace-oscore-gm-admin-10, , <https://datatracker.ietf.org/doc/html/draft-ietf-ace-oscore-gm-admin-10>.
+
+
[I-D.ietf-ace-pubsub-profile]
+
+Palombini, F., Sengul, C., and M. Tiloca, "Publish-Subscribe Profile for Authentication and Authorization for Constrained Environments (ACE)", Work in Progress, Internet-Draft, draft-ietf-ace-pubsub-profile-08, , <https://datatracker.ietf.org/doc/html/draft-ietf-ace-pubsub-profile-08>.
+
+
[RFC8126]
+
+Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, , <https://www.rfc-editor.org/rfc/rfc8126>.
+
+
[RFC8288]
+
+Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, , <https://www.rfc-editor.org/rfc/rfc8288>.
+
+
[RFC9052]
+
+Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, , <https://www.rfc-editor.org/rfc/rfc9052>.
+
+
[RFC9053]
+
+Schaad, J., "CBOR Object Signing and Encryption (COSE): Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, , <https://www.rfc-editor.org/rfc/rfc9053>.
+
+
[RFC9147]
+
+Rescorla, E., Tschofenig, H., and N. Modadugu, "The Datagram Transport Layer Security (DTLS) Protocol Version 1.3", RFC 9147, DOI 10.17487/RFC9147, , <https://www.rfc-editor.org/rfc/rfc9147>.
+
+
[RFC9200]
+
+Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "Authentication and Authorization for Constrained Environments Using the OAuth 2.0 Framework (ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, , <https://www.rfc-editor.org/rfc/rfc9200>.
+
+
[RFC9338]
+
+Schaad, J., "CBOR Object Signing and Encryption (COSE): Countersignatures", STD 96, RFC 9338, DOI 10.17487/RFC9338, , <https://www.rfc-editor.org/rfc/rfc9338>.
+
+
+
+
+
+
+
+

+Contributors +

+
+
Marco Tiloca
+
RISE AB
+ +
+

Marco offered comprehensive reviews and insightful guidance on the recent iterations of this document. His contributions were particularly notable in the Security Considerations section, among others.

+
+
+
+
+

+Authors' Addresses +

+
+
Jaime Jimenez
+
Ericsson
+ +
+
+
Michael Koster
+
Dogtiger Labs
+ +
+
+
Ari Keranen
+
Ericsson
+ +
+
+
+ + + diff --git a/draft-ietf-core-coap-pubsub.txt b/draft-ietf-core-coap-pubsub.txt new file mode 100644 index 0000000..e50dbb4 --- /dev/null +++ b/draft-ietf-core-coap-pubsub.txt @@ -0,0 +1,1485 @@ + + + + +CoRE Working Group J. Jimenez +Internet-Draft Ericsson +Intended status: Standards Track M. Koster +Expires: 8 May 2024 Dogtiger Labs + A. Keranen + Ericsson + 5 November 2023 + + + A publish-subscribe architecture for the Constrained Application + Protocol (CoAP) + draft-ietf-core-coap-pubsub-latest + +Abstract + + This document describes a publish-subscribe architecture for the + Constrained Application Protocol (CoAP), extending the capabilities + of CoAP communications for supporting endpoints with long breaks in + connectivity and/or up-time. CoAP clients publish on and subscribe + to a topic via a corresponding topic resource at a CoAP server acting + as broker. + +About This Document + + This note is to be removed before publishing as an RFC. + + Status information for this document may be found at + https://datatracker.ietf.org/doc/draft-ietf-core-coap-pubsub/. + + Discussion of this document takes place on the core Working Group + mailing list (mailto:core@ietf.org), which is archived at + https://mailarchive.ietf.org/arch/browse/core/. Subscribe at + https://www.ietf.org/mailman/listinfo/core/. + + Source for this draft and an issue tracker can be found at + https://github.com/core-wg/coap-pubsub. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at https://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on 8 May 2024. + +Copyright Notice + + Copyright (c) 2023 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents (https://trustee.ietf.org/ + license-info) in effect on the date of publication of this document. + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. Code Components + extracted from this document must include Revised BSD License text as + described in Section 4.e of the Trust Legal Provisions and are + provided without warranty as described in the Revised BSD License. + +Table of Contents + + 1. Introduction + 1.1. Terminology + 1.2. CoAP Publish-Subscribe Architecture + 1.3. Managing Topics + 2. Pub-Sub Topics + 2.1. Collection Representation + 2.2. Topic-Configuration Representation + 2.2.1. Topic Properties + 2.3. Discovery + 2.3.1. Broker Discovery + 2.3.2. Topic Collection Discovery + 2.3.3. Topic-Configuration Discovery + 2.3.4. Topic-Data Discovery + 2.4. Topic Collection Interactions + 2.4.1. Retrieving all topic-configurations + 2.4.2. Getting topic-configurations by Properties + 2.4.3. Creating a Topic + 2.5. Topic-Configuration Interactions + 2.5.1. Getting a topic-configuration + 2.5.2. Getting part of a topic-configuration + 2.5.3. Updating the topic-configuration + 2.5.4. Updating the topic-configuration with iPATCH + 2.5.5. Deleting a topic-configuration + 3. Publish and Subscribe + 3.1. Topic Lifecycle + 3.2. Topic-Data Interactions + 3.2.1. Publish + 3.2.2. Subscribe + 3.2.3. Unsubscribe + 3.2.4. Delete topic-data + 3.3. Read latest data + 3.4. Rate Limiting + 4. CoAP Pubsub Parameters + 5. Security Considerations + 6. IANA Considerations + 6.1. Media Type + 6.2. Content-Format + 6.3. CoAP Pubsub Parameters + 6.4. Resource Types + Acknowledgements + References + Normative References + Informative References + Contributors + Authors' Addresses + +1. Introduction + + The Constrained Application Protocol (CoAP) [RFC7252] supports + machine-to-machine communication across networks of constrained + devices and constrained networks. CoAP uses a request/response model + where clients make requests to servers in order to request actions on + resources. Depending on the situation the same device may act either + as a server, a client, or both. + + One important class of constrained devices includes devices that are + intended to run for years from a small battery, or by scavenging + energy from their environment. These devices have limited up-time + because they spend most of their time in a sleeping state with no + network connectivity. Another important class of nodes are devices + with limited reachability due to middle-boxes like Network Address + Translators (NATs) and firewalls. + + For these nodes, the client/server-oriented architecture of REST can + be challenging when interactions are not initiated by the devices + themselves. A publish/subscribe-oriented architecture where nodes + exchange data via topics through a broker entity might fit these + nodes better. + + This document applies the idea of broker-based publish-subscribe to + Constrained RESTful Environments using CoAP. It defines a broker + that allows to create, discover subscribe and publish on topics. + +1.1. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + This specification requires readers to be familiar with all the terms + and concepts that are discussed in [RFC8288] and [RFC6690]. Readers + should also be familiar with the terms and concepts discussed in + [RFC7252], [RFC9176] and [RFC7641]. The URI template format + [RFC6570] is used to describe the REST API defined in this + specification. + + This specification makes use of the following terminology: + + publish-subscribe (pub/sub): + A message communication model where messages associated with + specific topics are sent to a broker. Interested parties, i.e. + subscribers, receive these topic-based messages from the broker + without the original sender knowing the recipients. The broker + handles matching and delivering these messages to the appropriate + subscribers. + + publishers and subscribers: + CoAP clients can act as publishers or as subscribers. Publishers + send CoAP messages (publications) to the broker on specific + topics. Subscribers have an ongoing observation relation + (subscription) to a topic. Both roles operate without any mutual + knowledge, guided by their respective topic interests. + + topic collection: + A set of topic configurations. A topic collection is hosted as + one collection resource at the broker, and its representation is + the list of links to the topic resources corresponding to each + topic configuration. + + topic-configuration: + A set of information concerning a topic, including its + configuration and other metadata. A topic configuration is hosted + as one topic resource at the broker, and its representation is the + set of configuration information concerning the topic. All the + topic resources associated with the same topic collection share a + common base URI, i.e., the URI of the collection resource. + Throughout this document the word "topic" and "topic- + configuration" can be used interchangeably. + + topic-data resource: + A resource where clients can publish data and/or subscribe to data + for a specific topic. The representation of the topic resource + corresponding to such a topic also specifies the URI to the + present topic-data resource. + + broker: + A CoAP server that hosts one or more topic collections with their + topic-configurations, and also topic-data resources. The broker + is responsible for the store-and-forward of state update + representations, for the topics for which it hosts the + corresponding topic-data resources. 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. + +1.2. CoAP Publish-Subscribe Architecture + + Figure 1 shows a simple Publish/Subscribe architecture over CoAP. + + Topics are created by the broker, but the initial configuration can + be proposed by a client (e.g., a publisher or a dedicated + administrator) over the RESTful interface of a corresponding topic + resource hosted by the broker. + + Publishers submit their data over the RESTful interface of a topic- + data resource corresponding to the topic, which may be hosted by the + broker. Subscribers to a topic are notified of new publications by + using Observe [RFC7641] on the corresponding topic-data resource. + + The broker is responsible for the store-and-forward of state update + representations between CoAP clients. Subscribers observing a + resource will receive notifications, the delivery of which is done on + a best-effort basis. + + CoAP CoAP CoAP + clients server clients + .-----------. .----------. observe .-----------. + | | publish | |<----------+ | + | publisher +--------->+ +---------->| subscribe | + | | | +---------->| | + '-----------' | | '-----------' + ... | broker | ... + ... | | ... + .-----------. | | observe .-----------. + | | publish | |<----------+ | + | publisher +--------->| +---------->| subscribe | + | | | +---------->| | + '-----------' '----------' '-----------' + + Figure 1: 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 3.2). + + Topic-configuration interactions are discovery, create, read + configuration, update configuration, and delete configuration. These + operations handle the management of the topics. + + Topic-data interactions are publish, subscribe, unsubscribe, read, + and delete. These operations are oriented on how data is transferred + from a publisher to a subscriber. + +1.3. Managing Topics + + Figure 2 shows the resources related to a Topic Collection that can + be managed at the Broker. + + ___ + topic / \ + collection \___/ + resource \ + \____________________ + \___ \___ \___ + / \ / \ ... / \ topic resources + \___/ \___/ \___/ + + Figure 2: Resources of a Broker + + The Broker exports one or more topic-collection resources, 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. + + A topic-collection resource can have topic resources as its child + resources, with resource type "core.ps.conf". + +2. Pub-Sub Topics + + The configuration side of a "publish/subscribe broker" consists of a + collection of topics. These topics as well as the collection itself + are exposed by a CoAP server as resources (see Figure 3). Each topic + is associated with a topic configuration resource and a topic-data + resource. The topic configuration resource is used by a client + creating or administering a topic. The topic-data resource is used + by the publishers and the subscribers to a topic. + + ___ + topic / \ + collection \___/ + resource \ + \___________________________ + \ \ \ + \ ...... \ ...... \ ...... + topic : \___ : : \___ : : \___ : + configuration : / * \ : : / * \ : : / * \ : + resource : \_|_/ : : \_|_/ : : \_|_/ : + ....|.... ....|.... ....|.... + ....|.... ....|.... ....|.... + : _|_ : : _|_ : ... : _|_ : + topic-data : / \ : : / \ : : / \ : + resource : \___/ : : \___/ : : \___/ : + :.......: :.......: :.......: + \_________/\_________/ ... \_________/ + topic 1 topic 2 topic n + + Figure 3: Topic and topic-data resources of a topic + +2.1. Collection Representation + + Each topic configuration is represented as a link, where the link + target is the URI of the corresponding topic resource. + + Publication and subscription to a topic occur at a link, where the + link target is the URI of the corresponding topic-data resource. + Such a link is specified by the topic-data entry within the topic + resource (see Section 2.2.1). + + A topic resource with a topic-data link can also be simply called + "topic". + + The list of links to the topic resources can be retrieved from the + associated topic collection resource, and represented as a Link + Format document [RFC6690]where each such link specifies the link + target attribute 'rt' (Resource Type), with value "core.ps.conf" + defined in this document. + +2.2. Topic-Configuration Representation + + 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 4. + +2.2.1. Topic Properties + + The CBOR map includes the following configuration parameters, whose + 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 + topic names include human-readable strings (e.g., "room2"), UUIDs, + or other values. + + * 'topic-data': A required field (optional during creation) + containing the URI of the topic-data resource for publishing/ + subscribing to this topic. It encodes the URI as a CBOR text + string. + + * 'resource-type': A required field used to indicate the resource + type of the topic-data resource for the topic. It encodes the + resource type as a CBOR text string. The value should be + "core.ps.conf". + + * 'media-type': An optional field used to indicate the media type of + the topic-data resource for the topic. It encodes the media type + as a this information as the integer identifier of the CoAP + content-format (e.g., value is "50" for "application/json"). + + * 'topic-type': An optional field used to indicate the attribute or + property of the topic-data resource for the topic. It encodes the + attribute as a CBOR text string. Example attributes include + "temperature". + + * 'expiration-date': An optional field used to indicate the + expiration date of the topic. It encodes the expiration date as a + CBOR text string. The value should be a date string in ISO 8601 + format (e.g., "2023-03-31T23:59:59Z"). The broker can use this + field to automatically remove topics that are no longer valid. If + this field is not present, the topic will not expire + automatically. + + * 'max-subscribers': An optional field used to indicate the maximum + number of simultaneous subscribers allowed for the topic. It + encodes the maximum number as an unsigned CBOR integer. If this + field is not present, there is no limit to the number of + simultaneous subscribers allowed. The broker can use this field + to limit the number of subscribers for the topic. The default + value for this field has been set to 100 subscribers. + + * 'observer-check': An optional field that controls the maximum + number of seconds between two consecutive Observe notifications + sent as Confirmable messages to each topic subscriber. Encoded as + a CBOR unsigned integer greater than 0, it ensures subscribers who + have lost interest and silently forgotten the observation do not + remain indefinitely on the server's observer list. If another + CoAP server hosts the topic-data resource, that server is + responsible for applying the observer-check value. The default + value for this field is 86400, as defined in [RFC7641], which + corresponds to 24 hours. + +2.3. Discovery + + A client can perform a discovery of: the broker; the topic collection + resources and topic resources hosted by the broker; and the topic- + data resources associated with those topic resources. + +2.3.1. Broker Discovery + + CoAP clients MAY discover brokers by using CoAP Simple Discovery, via + multicast, through a Resource Directory (RD) [RFC9176] or by other + means specified in extensions to [RFC7252]. Brokers MAY register + with a RD by following the steps on Section 5 of [RFC9176] with the + resource type set to "core.ps" as defined in Section 6 of this + document. + + The following example shows an endpoint discovering a broker using + the "core.ps" resource type over a multicast network. Brokers within + the multicast scope will answer the query. + + => 0.01 GET + Uri-Path: coap://[ff0x::fe]/.well-known/core + Resource-Type: core.ps + + <= 2.05 Content + Payload: + Content-Format: 40 (application/link-format) + ; rt=core.ps + +2.3.2. Topic Collection Discovery + + A Broker SHOULD offer a topic discovery entry point to enable clients + to find topics of interest. The resource entry point is the topic + collection resource collecting the topic configurations for those + topics (see Section 1.2.2 of [RFC6690]) and is identified by the + resource type "core.ps.coll". + + The specific resource path is left for implementations, examples in + this document use the "/ps" path. The interactions with a topic + collection are further defined in Section 2.4. + + Since the representation of the topic collection resource includes + the links to the associated topic resources, it is not required to + locate those links under "/.well-known/core", also in order to limit + the size of the Link Format document returned as result of the + discovery. + + Example: + + => 0.01 GET + Uri-Path: .well-known/core + Resource-Type: core.ps.coll + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.coll";ct=40, + ;rt="core.ps.coll";ct=40 + +2.3.3. Topic-Configuration Discovery + + Each topic collection is associated with a group of topic resources, + each detailing the configuration of its respective topic (refer to + Section 2.2.1). Each topic resource is identified by the resource + type "core.ps.conf". + + Below is an example of discovery via /.well-known/core with + rt=core.ps.conf that returns a list of topics, as the list of links + to the corresponding topic resources. + + => 0.01 GET + Uri-Path: .well-known/core + Resource-Type: core.ps.conf + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf";ct=TBD, + ;rt=core.ps.conf;ct=TBD + +2.3.4. Topic-Data Discovery + + Within a topic, there is the topic-data property containing the URI + of the topic-data resource that a CoAP client can subscribe and + publish to. Resources exposing resources of the topic-data type are + expected to use the resource type 'core.ps.data'. + + The topic-data contains the URI of the topic-data resource for + publishing and subscribing. So retrieving the topic configuration + will also provide the URL of the topic-data (see Section 2.5.1). + + It is also possible to discover a list of topic-data resources by + sending a request to the collection with with rt=core.ps.data + resources as shown below. + + => 0.01 GET + Uri-Path: /ps + Resource-Type: core.ps.data + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ; rt=core.ps.data; obs + +2.4. Topic Collection Interactions + + These are the interactions that can happen directly with a specific + topic collection. + +2.4.1. Retrieving all topic-configurations + + A client can request a collection of the topics present in the broker + by making a GET request to the collection URI. + + On success, the server returns a 2.05 (Content) response, specifying + the list of links to topic resources associated with this topic + collection (see Section 2.2). + + Depending on its granted permissions, a client MAY retrieve a + different list of links, corresponding to the topics that the client + is authorized to access. + + Example: + + => 0.01 GET + Uri-Path: ps + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf", + ; rt="core.ps.conf" + +2.4.2. Getting topic-configurations by Properties + + A client can filter a collection of topics by submitting the + representation of a topic filter (see Section 2.5.2) in a FETCH + request to the topic collection URI. + + On success, the server returns a 2.05 (Content) response with a + representation of a list of topics in the collection (see + Section 2.3.3) that match the filter in CoRE link format [RFC6690]. + + Upon success, the server responds with a 2.05 (Content), providing a + list of links to topic resources associated with this topic + collection that match the request's filter criteria (refer to + Section 2.3.3). A positive match happens only when each request + parameter is present with the indicated value in the topic resource + representation. + + Example: + + => 0.05 FETCH + Uri-Path: ps + Content-Format: TBD (application/pubsub+cbor) + + { + "resource-type": "core.ps.conf", + "topic-type": "temperature" + } + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf" + +2.4.3. Creating a Topic + + A client can add a new topic-configurations to a collection of topics + by submitting an initial representation of the initial topic resource + (see Section 2.2) in a POST request to the topic collection URI. The + request MUST specify at least a subset of the properties in + Section 2.2.1, namely: topic-name and resource-type. + + 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 Location-Path of the new topic and the current representation of + the topic resource. The response payload includes a CBOR map with + key-value pairs. The response must include the required topic + properties (see Section 2.2.1), namely: "topic-name", "resource-type" + and "topic-data". It may also include a number of optional + properties too. + + If requirements are defined for the client to create the topic as + requested and the broker does not successfully assess that those + requirements are met, then the broker MUST respond with a 4.03 + (Forbidden) error. The response MUST have Content-Format set to + "application/core-pubsub+cbor". + + The broker MUST issue a 4.00 (Bad Request) error if a received + parameter is invalid, unrecognized, or if the topic-name is already + in use or otherwise invalid. + + => 0.02 POST + Uri-Path: ps + Content-Format: TBD2 (application/core-pubsub+cbor) + TBD (this should be a CBOR map with the mandatory parameters) + { + "topic-name": "living-room-sensor", + "resource-type": "core.ps.conf" + } + + <= 2.01 Created + Location-Path: ps/h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf" + } + +2.5. Topic-Configuration Interactions + + These are the interactions that can happen at the topic resource + level. + +2.5.1. Getting a topic-configuration + + 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 + partial representation of the topic resource, as specified in + Section 2.2. The partial representation includes only the + configuration parameters such that they are present and have the same + value in both the current topic configuration as well as in the FETCH + request. + + If requirements are defined for the client to create the topic as + requested and the broker does not successfully assess that those + requirements are met, then the broker 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 4. + + For example, below is a request on the topic "ps/h9392": + + => 0.01 GET + Uri-Path: ps + Uri-Path: h9392 + + <= 2.05 Content + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "topic-name" : "living-room-sensor", + "topic-data" : "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-00T23:59:59Z", + "max-subscribers": 100 + } + +2.5.2. Getting part of a topic-configuration + + A client can read the configuration of a topic by making a FETCH + request to the topic resource URI with a filter for specific + parameters. This is done in order to retrieve part of the current + topic resource. + + 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 requirements are defined for the client to create the topic as + requested and the broker does not successfully assess that those + requirements are met, then the broker 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 4. + + Both request and response MUST have Content-Format set to + "application/core-pubsub+cbor". + + Example: + + => 0.05 FETCH + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "conf-filter": ["topic-data", "media-type"] + } + + <= 2.05 Content + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "topic-data": "ps/data/1bd0d6d", + "media-type": "application/senml-cbor" + } + +2.5.3. Updating the topic-configuration + + A client can update a topic's configuration by submitting the updated + topic representation in a PUT request to the topic URI. However, the + parameters "topic-name", "topic-data", and "resource-type" are + immutable post-creation, and any request attempting to change them + will be deemed invalid by the broker. + + On success, the topic configuration is overwritten and server returns + a 2.04 (Changed) response and the current full resource + representation. The broker may chose not to overwrite parameters + that are not explicitly modified in the request. + + Note that updating the "topic-data" path will automatically cancel + all existing observations on it and thus will unsubscribe all + subscribers. Updating the "topic-data" may happen also after it + being deleted, as described on {delete-topic-data}, this will in turn + create a new "topic-data" path for that topic configuration. + + Similarly, decreasing max-subscribers will also cause that some + subscribers get unsubscribed. Unsubscribed endpoints SHOULD receive + a final 4.04 (Not Found) response as per [RFC7641] Section 3.2. + + Please note that when using PUT the topic configuration is being + overwritten, thus some of the optional parameters (e.g., "max- + subscribers", "observer-check") not included in the PUT message will + be reset to their default values. + + Example: + + => 0.03 PUT + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-28T23:59:59Z", + } + + <= 2.04 Changed + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-28T23:59:59Z", + "max-subscribers": 100, + "observer-check": 86400 + } + + Note that 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. + + * 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. + +2.5.4. Updating the topic-configuration with iPATCH + + A client can partially update a topic's configuration by submitting a + partial topic representation in an iPATCH request to the topic URI. + The iPATCH request allows for updating only specific fields of the + topic configuration while leaving the others unchanged. As with the + PUT method, the parameters "topic-name", "topic-data", and "resource- + type" are immutable post-creation, and any request attempting to + change them will be deemed invalid by the broker. + + On success, the server returns a 2.04 (Changed) response and the + current full resource representation. The broker only updates + parameters that are explicitly mentioned in the request. + + As with the PUT method, updating the "topic-data" path will + automatically cancel all existing observations on it and thus will + unsubscribe all subscribers. Decreasing max-subscribers will also + cause some subscribers to get unsubscribed. Unsubscribed endpoints + SHOULD receive a final 4.04 (Not Found) response as per [RFC7641] + Section 3.2. + + Contrary to PUT iPATCH operations will explicitly update some + parameters, leaving others unmodified. + + => 0.07 iPATCH + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + { + "topic-type": "humidity", + "max-subscribers": 5 + } + + <= 2.04 Changed + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name" : "living-room-sensor", + "topic-data" : "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "humidity", + "expiration-date": "2023-05-28T23:59:59Z", + "max-subscribers": 5 + } + + Note that when a topic configuration changes through an iPATCH + request, 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. + +2.5.5. Deleting a topic-configuration + + A client can delete a topic by making a CoAP DELETE request on the + topic resource URI. + + On success, the server returns a 2.02 (Deleted) response. + + When a topic-configuration resource is deleted, the broker MUST also + delete the topic-data resource, unsubscribe all subscribers by + removing them from the list of observers and returning a final 4.04 + (Not Found) response as per section 3.2 of [RFC7641]. + + Example: + + => 0.04 DELETE + Uri-Path: ps + Uri-Path: h9392 + + <= 2.02 Deleted + +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 Observe option set to 0 + (register) to a topic-data resource. When resource state changes, + subscribers observing the resource [RFC7641] at that time will + receive a notification. + + A topic-data resource does not exist until some initial data has been + published to it. Before initial data publication, a GET request to + the topic-data resource URI results in 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). + There is no necessary URI pattern dependence between the URI where + the topic-data exists and the URI of the topic-configuration + resource. + +3.1. Topic Lifecycle + + When a topic is newly created, it is first placed by the broker 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 subscribe to 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 + + 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 data by means of a GET request without observe. 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. + +3.2. Topic-Data Interactions + + Interactions with the topic-data resource are covered in this + section. + +3.2.1. Publish + + A topic-configuration with a topic-data resource must have been + created in order to publish data to it (See Section 2.4.3) and be in + the half-created or fully-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 + Uri-Path: data + Uri-Path: 1bd0d6d + Content-Format: 110 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452122, + "v": 23.5 + } + + <= 2.01 Created + + Example of subsequent publication: + + => 0.03 PUT + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + Content-Format: 110 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452149, + "v": 22.5 + } + + <= 2.04 Updated + +3.2.2. Subscribe + + A client can subscribe to a topic-data by sending a CoAP GET request + with the Observe set to 0 to subscribe to resource updates. + [RFC7641]. + + On success, the server hosting the topic-data resource MUST return + 2.05 (Content) notifications with the data and the Observe Option. + Otherwise, if no Observe Option is present the client should assume + that the subscription was not successful. + + 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". The topic-data does not exist. + + If the 'max-subscribers' 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 + Uri-Path: data + Uri-Path: 1bd0d6d + Observe: 0 + + <= 2.05 Content + Content-Format: 110 + Observe: 10001 + Max-Age: 15 + + { + "n": "urn:dev:os:32473-123456", + "u": "Cel", + "t": 1696341182, + "v": 19.87 + } + + <= 2.05 Content + Content-Format: 110 + Observe: 10002 + Max-Age: 15 + + { + + "n": "urn:dev:os:32473-123456", + "u": "Cel", + "t": 1696340184, + "v": 21.87 + } + +3.2.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. Also on Section 3.6 of + [RFC7641] the client can simply "forget" the observation and the + server will remove it from the list of observers after the next + notification. + + As per [RFC7641] a server that transmits notifications mostly in non- + confirmable messages, but it 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. + +3.2.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 3.1. + + Example: + + => 0.04 DELETE + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + + <= 2.02 Deleted + +3.3. 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 3.1), the broker MUST + return a response code 4.04 (Not Found). + + Example: + + => 0.01 GET + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + + <= 2.05 Content + Content-Format: 110 + Max-Age: 15 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452122, + "v": 23.5 + } + +3.4. Rate Limiting + + The server hosting the topic-data may have to handle a potentially + large number of publishers and subscribers at the same time. This + means it could become overwhelmed if it receives too many + publications in a short period of time. + + In this situation, if a publisher 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 also stop publishing messages from + that publisher for the indicated time. + + When a publisher 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. + +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. + + +-----------------+-----------+-----------+------------+ + | Name | CBOR Key | CBOR Type | Reference | + |-----------------|-----------|-----------|------------| + | topic-name | TBD1 | tstr | [RFC-XXXX] | + | topic-data | TBD2 | tstr | [RFC-XXXX] | + | resource-type | TBD3 | tstr | [RFC-XXXX] | + | media-type | TBD4 | uint | [RFC-XXXX] | + | topic-type | TBD5 | tstr | [RFC-XXXX] | + | expiration-date | TBD6 | tstr | [RFC-XXXX] | + | max-subscribers | TBD7 | uint | [RFC-XXXX] | + | observer-check | TBD8 | uint | [RFC-XXXX] | + +-----------------+-----------+-----------+------------+ + + Figure 5: CoAP Pubsub Parameters + +5. Security Considerations + + The architecture presented in this document inherits the security + considerations from CoAP [RFC7252] and Observe [RFC7641], as well as + from Web Linking [RFC8288], Link-Format [RFC6690], and the CoRE + Resource Directory [RFC9176]. + + Communications between each client and the broker MUST be secured, + e.g., by using OSCORE [RFC8613] or DTLS [RFC9147]. Security + considerations for the used secure communication protocols apply too. + + The content published on a topic by a publisher client SHOULD be + protected end-to-end between the publisher and all the subscribers to + that topic. In such a case, it MUST be possible to assert source + authentication of the published data. This can be achieved at the + application layer, e.g., by using COSE [RFC9052], [RFC9053], + [RFC9338]. + + Access control of clients at the broker MAY be enforced for + performing discovery operation, and SHOULD be enforced in a fine- + grained fashion for operations related to the the creation, update, + and deletion of topic resources, as well as for operations on topic- + data resources such as publication on and subscription to topics. + This prevents rogue clients to, among other things, repeatedly create + topics at the broker or publish (large) contents, which may result in + Denial of Service against the broker and the active subscribers. + + Building on [I-D.ietf-ace-key-groupcomm], its application profile for + publish-subscribe communication with CoAP + [I-D.ietf-ace-pubsub-profile] provides a security model that can be + used in the architecture presented in this document, in order to + enable secure communication between the different parties as well as + secure, authorized operations of publishers and subscribers that + fulfill the requirements above. + + In particular, the application profile above relies on the ACE + framework for Authentication and Authorization in Constrained + Environments (ACE) [RFC9200] and defines a method to: authorize + publishers and subscribers to perform operations at the broker, with + fine-grained access control; authorize publishers and subscribers to + obtain the keying material required to take part to a topic managed + by the broker; protect published data end-to-end between its + publisher and all the subscribers to the targeted topic, ensuring + confidentiality, integrity, and source authentication of the + published content end-to-end. That approach can be extended to + enforce authorization and fine-grained access control for + administrator clients that are intended to create, update, and delete + topic configurations at the broker. + +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. + +6.1. Media Type + + IANA is requested to add the following Media-Type to the "Media + Types" registry [IANA.media-types]. + + +=============+=========================+=======================+ + | Name | Template | Reference | + +=============+=========================+=======================+ + | pubsub+cbor | application/pubsub+cbor | RFC XXXX, Section 6.1 | + +-------------+-------------------------+-----------------------+ + + Table 1: New Media Type application/pubsub+cbor + + Type name: application + Subtype name: pubsub+cbor + Required parameters: N/A + Optional parameters: N/A + Encoding considerations: binary (CBOR data item) + Security considerations: Section 5 of RFC XXXX + Interoperability considerations: none + Published specification: Section 6.1 of RFC XXXX + Applications that use this media type: This type is used by clients + that create, retrieve, and update topic configurations at servers + acting as a pub-sub broker. + Fragment identifier considerations: N/A + Person & email address to contact for further information: CoRE WG + mailing list (core@ietf.org), or IETF Applications and Real-Time + Area (art@ietf.org) + Intended usage: COMMON + Restrictions on usage: none + Author/Change controller: IETF + Provisional registration: no + +6.2. Content-Format + + IANA has added the following Content-Formats to the "CoAP + Content-Formats" sub-registry, within the "Constrained RESTful + Environments (CoRE) Parameters" Registry [IANA.core-parameters], as + follows: + + +=========================+================+======+===========+ + | Content Type | Content Coding | ID | Reference | + +=========================+================+======+===========+ + | application/pubsub+cbor | - | TBD9 | RFC XXXX | + +-------------------------+----------------+------+-----------+ + + Table 2: New Content-Format + + TBD9 is to be assigned from the space 256..999. + +6.3. CoAP Pubsub Parameters + + IANA is asked to register the following entries in the subregistry of + the "Constrained RESTful Environments (CoRE) Parameters" registry + group. + + This specification establishes the "Pubsub Topic Configuration + Parameters" IANA registry within the "Constrained RESTful + Environments (CoRE) Parameters" registry group. + + The columns of this registry are: + + * Name: This is a descriptive name that enables easier reference to + the item. The name MUST be unique. It is not used in the + encoding. + + * CBOR Key: This is the value used as CBOR key of the item. These + values MUST be unique. The value can be a positive integer, a + negative integer, or a text string. Different ranges of values + use different registration policies [RFC8126]. Integer values + from -256 to 255 as well as text strings of length 1 are + designated as "Standards Action With Expert Review". Integer + values from -65536 to -257 and from 256 to 65535, as well as text + strings of length 2 are designated as "Specification Required". + Integer values greater than 65535 as well as text strings of + length greater than 2 are designated as "Expert Review". Integer + values less than -65536 are marked as "Private Use". + + * CBOR Type: This contains the CBOR type of the item, or a pointer + to the registry that defines its type, when that depends on + another item. + + * Reference: This contains a pointer to the public specification for + the item. + + The registry is initially populated with the entries in Figure 5 of + Section 4. + +6.4. 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. + + Value: core.ps + Description: Publish-Subscribe Broker + Reference: [RFC-XXXX] + + Value: core.ps.coll + Description: Topic-collection resource of a Publish-Subscribe Broker + Reference: [RFC-XXXX] + + Value: core.ps.conf + Description: Topic-configuration resource of a Publish-Subscribe Broker + Reference: [RFC-XXXX] + + Value: core.ps.data + Description: Topic-data resource of a broker + Reference: [RFC-XXXX] + +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, Olaf + Bergmann and Oscar Novo for their valuable contributions and reviews. + +References + +Normative References + + [IANA.core-parameters] + IANA, "Constrained RESTful Environments (CoRE) + Parameters", + . + + [IANA.media-types] + IANA, "Media Types", + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., + and D. Orchard, "URI Template", RFC 6570, + DOI 10.17487/RFC6570, March 2012, + . + + [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link + Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, + . + + [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained + Application Protocol (CoAP)", RFC 7252, + DOI 10.17487/RFC7252, June 2014, + . + + [RFC7641] Hartke, K., "Observing Resources in the Constrained + Application Protocol (CoAP)", RFC 7641, + DOI 10.17487/RFC7641, September 2015, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8516] Keranen, A., ""Too Many Requests" Response Code for the + Constrained Application Protocol", RFC 8516, + DOI 10.17487/RFC8516, January 2019, + . + + [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, + "Object Security for Constrained RESTful Environments + (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, + . + + [RFC9176] Amsüss, C., Ed., Shelby, Z., Koster, M., Bormann, C., and + P. van der Stok, "Constrained RESTful Environments (CoRE) + Resource Directory", RFC 9176, DOI 10.17487/RFC9176, April + 2022, . + +Informative References + + [I-D.hartke-t2trg-coral-pubsub] + Hartke, K., "Publish/Subscribe over the Constrained + Application Protocol (CoAP) using the Constrained RESTful + Application Language (CoRAL)", Work in Progress, Internet- + Draft, draft-hartke-t2trg-coral-pubsub-01, 9 May 2020, + . + + [I-D.ietf-ace-key-groupcomm] + Palombini, F. and M. Tiloca, "Key Provisioning for Group + Communication using ACE", Work in Progress, Internet- + Draft, draft-ietf-ace-key-groupcomm-17, 6 October 2023, + . + + [I-D.ietf-ace-oscore-gm-admin] + Tiloca, M., Höglund, R., Van der Stok, P., and F. + Palombini, "Admin Interface for the OSCORE Group Manager", + Work in Progress, Internet-Draft, draft-ietf-ace-oscore- + gm-admin-10, 23 October 2023, + . + + [I-D.ietf-ace-pubsub-profile] + Palombini, F., Sengul, C., and M. Tiloca, "Publish- + Subscribe Profile for Authentication and Authorization for + Constrained Environments (ACE)", Work in Progress, + Internet-Draft, draft-ietf-ace-pubsub-profile-08, 23 + October 2023, . + + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + + [RFC8288] Nottingham, M., "Web Linking", RFC 8288, + DOI 10.17487/RFC8288, October 2017, + . + + [RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Structures and Process", STD 96, RFC 9052, + DOI 10.17487/RFC9052, August 2022, + . + + [RFC9053] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, + August 2022, . + + [RFC9147] Rescorla, E., Tschofenig, H., and N. Modadugu, "The + Datagram Transport Layer Security (DTLS) Protocol Version + 1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022, + . + + [RFC9200] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and + H. Tschofenig, "Authentication and Authorization for + Constrained Environments Using the OAuth 2.0 Framework + (ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, August 2022, + . + + [RFC9338] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Countersignatures", STD 96, RFC 9338, + DOI 10.17487/RFC9338, December 2022, + . + +Contributors + + Marco Tiloca + RISE AB + Email: marco.tiloca@ri.se + + + Marco offered comprehensive reviews and insightful guidance on the + recent iterations of this document. His contributions were + particularly notable in the Security Considerations section, among + others. + +Authors' Addresses + + Jaime Jimenez + Ericsson + Email: jaime@iki.fi + + + Michael Koster + Dogtiger Labs + Email: michaeljohnkoster@gmail.com + + + Ari Keranen + Ericsson + Email: ari.keranen@ericsson.com diff --git a/edit-fixes/draft-ietf-core-coap-pubsub.html b/edit-fixes/draft-ietf-core-coap-pubsub.html new file mode 100644 index 0000000..2c4e499 --- /dev/null +++ b/edit-fixes/draft-ietf-core-coap-pubsub.html @@ -0,0 +1,2804 @@ + + + + + + +A publish-subscribe architecture for the Constrained Application Protocol (CoAP) + + + + + + + + + + + + + + + + + + + + + + + + +
Internet-DraftA publish-subscribe architecture for theNovember 2023
Jimenez, et al.Expires 8 May 2024[Page]
+
+
+
+
Workgroup:
+
CoRE Working Group
+
Internet-Draft:
+
draft-ietf-core-coap-pubsub-latest
+
Published:
+
+ +
+
Intended Status:
+
Standards Track
+
Expires:
+
+
Authors:
+
+
+
J. Jimenez
+
Ericsson
+
+
+
M. Koster
+
Dogtiger Labs
+
+
+
A. Keranen
+
Ericsson
+
+
+
+
+

A publish-subscribe architecture for the Constrained Application Protocol (CoAP)

+
+

Abstract

+

This document describes a publish-subscribe architecture for the Constrained Application Protocol (CoAP), extending the capabilities of CoAP communications for supporting endpoints with long breaks in connectivity and/or up-time. CoAP clients publish on and subscribe to a topic via a corresponding topic resource at a CoAP server acting as broker.

+
+
+

+About This Document +

+

This note is to be removed before publishing as an RFC.

+

+ Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-core-coap-pubsub/.

+

+ Discussion of this document takes place on the + core Working Group mailing list (mailto:core@ietf.org), + which is archived at https://mailarchive.ietf.org/arch/browse/core/. + Subscribe at https://www.ietf.org/mailman/listinfo/core/.

+

Source for this draft and an issue tracker can be found at + https://github.com/core-wg/coap-pubsub.

+
+
+
+

+Status of This Memo +

+

+ This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79.

+

+ Internet-Drafts are working documents of the Internet Engineering Task + Force (IETF). Note that other groups may also distribute working + documents as Internet-Drafts. The list of current Internet-Drafts is + at https://datatracker.ietf.org/drafts/current/.

+

+ Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress."

+

+ This Internet-Draft will expire on 8 May 2024.

+
+
+ +
+
+ ▲

+Table of Contents +

+ +
+
+
+
+

+1. Introduction +

+

The Constrained Application Protocol (CoAP) [RFC7252] supports +machine-to-machine communication across networks of constrained +devices and constrained networks. CoAP uses a request/response model where clients make requests to servers in order to request actions on resources. Depending on the situation the same device may act either as a server, a client, or both.

+

One important class of constrained devices includes devices that are intended to run for years from a small battery, or by scavenging energy from their environment. These devices have limited up-time because they spend most of their time in a sleeping state with no network connectivity. Another important class of nodes are devices with limited reachability due to middle-boxes like Network Address Translators (NATs) and firewalls.

+

For these nodes, the client/server-oriented architecture of REST can be challenging when interactions are not initiated by the devices themselves. A publish/subscribe-oriented architecture where nodes exchange data via topics through a broker entity might fit these nodes better.

+

This document applies the idea of broker-based publish-subscribe to Constrained RESTful Environments using CoAP. It defines a broker that allows to create, discover subscribe and publish on topics.

+
+
+

+1.1. Terminology +

+

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", +"MAY", and "OPTIONAL" in this document are to be interpreted as +described in BCP 14 [RFC2119] [RFC8174] when, and only when, they +appear in all capitals, as shown here.

+

This specification requires readers to be familiar with all the terms and +concepts that are discussed in [RFC8288] and [RFC6690]. Readers +should also be familiar with the terms and concepts discussed in +[RFC7252], [RFC9176] and [RFC7641]. The URI template +format [RFC6570] is used to describe the REST API defined in +this specification.

+

This specification makes use of the following terminology:

+
+
publish-subscribe (pub/sub):
+
+

A message communication model where messages associated with specific topics are sent to a broker. Interested parties, i.e. subscribers, receive these topic-based messages from the broker without the original sender knowing the recipients. The broker handles matching and delivering these messages to the appropriate subscribers.

+
+
+
publishers and subscribers:
+
+

CoAP clients can act as publishers or as subscribers. Publishers send CoAP messages (publications) to the broker on specific topics. Subscribers have an ongoing observation relation (subscription) to a topic. Both roles operate without any mutual knowledge, guided by their respective topic interests.

+
+
+
topic collection:
+
+

A set of topic configurations. A topic collection is hosted as one collection resource at the broker, and its representation is the list of links to the topic resources corresponding to each topic configuration.

+
+
+
topic-configuration:
+
+

A set of information concerning a topic, including its configuration and other metadata. A topic configuration is hosted as one topic resource at the broker, and its representation is the set of configuration information concerning the topic. All the topic resources associated with the same topic collection share a common base URI, i.e., the URI of the collection resource. Throughout this document the word "topic" and "topic-configuration" can be used interchangeably.

+
+
+
topic-data resource:
+
+

A resource where clients can publish data and/or subscribe to data for a specific topic. The representation of the topic resource corresponding to such a topic also specifies the URI to the present topic-data resource.

+
+
+
broker:
+
+

A CoAP server that hosts one or more topic collections with their topic-configurations, and also topic-data resources. The broker is responsible for the store-and-forward of state update representations, for the topics for which it hosts the corresponding topic-data resources. 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.

+
+
+
+
+
+
+
+

+1.2. CoAP Publish-Subscribe Architecture +

+

Figure 1 shows a simple Publish/Subscribe architecture over CoAP.

+

Topics are created by the broker, but the initial configuration can be proposed by a client (e.g., a publisher or a dedicated administrator) over the RESTful interface of a corresponding topic resource hosted by the broker.

+

Publishers submit their data over the RESTful interface of a topic-data resource corresponding to the topic, which may be hosted by the broker. Subscribers to a topic are notified of new publications by using Observe [RFC7641] on the corresponding topic-data resource.

+

The broker is responsible for the store-and-forward of state update representations between CoAP clients. Subscribers observing a resource will receive notifications, the delivery of which is done on a best-effort basis.

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CoAP + CoAP + CoAP + clients + server + clients + observe + publish + publisher + subscribe + ... + broker + ... + ... + ... + observe + publish + publisher + subscribe + + +
+
+
Figure 1: +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 3.2).

+

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

+

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

+
+
+
+
+

+1.3. Managing Topics +

+

Figure 2 shows the resources related to a Topic Collection that can be managed at the Broker.

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + topic + collection + resource + ... + topic + resources + + +
+
+
Figure 2: +Resources of a Broker +
+
+

The Broker exports one or more topic-collection resources, 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.

+

A topic-collection resource can have topic resources as its child resources, with resource type "core.ps.conf".

+
+
+
+
+
+
+

+2. Pub-Sub Topics +

+

The configuration side of a "publish/subscribe broker" consists of a collection of topics. These topics as well as the collection itself are exposed by a CoAP server as resources (see Figure 3). Each topic is associated with a topic configuration resource and a topic-data resource. The topic configuration resource is used by a client creating or administering a topic. The topic-data resource is used by the publishers and the subscribers to a topic.

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + topic + collection + resource + ...... + ...... + ...... + topic + : + : + : + : + : + : + configuration + : + : + : + : + : + : + resource + : + _ + _ + : + : + _ + _ + : + : + _ + _ + : + .... + .... + .... + .... + .... + .... + .... + .... + .... + .... + .... + .... + : + _ + _ + : + : + _ + _ + : + ... + : + _ + _ + : + topic-data + : + : + : + : + : + : + resource + : + : + : + : + : + : + :.......: + :.......: + :.......: + \ + / + ... + \ + / + topic + 1 + topic + 2 + topic + n + + +
+
+
Figure 3: +Topic and topic-data resources of a topic +
+
+
+
+

+2.1. Collection Representation +

+

Each topic configuration is represented as a link, where the link target is the URI of the corresponding topic resource.

+

Publication and subscription to a topic occur at a link, where the link target is the URI of the corresponding topic-data resource. Such a link is specified by the topic-data entry within the topic resource (see Section 2.2.1).

+

A topic resource with a topic-data link can also be simply called "topic".

+

The list of links to the topic resources can be retrieved from the associated topic collection resource, and represented as a Link Format document [RFC6690]where each such link specifies the link target attribute 'rt' (Resource Type), with value "core.ps.conf" defined in this document.

+
+
+
+
+

+2.2. Topic-Configuration Representation +

+

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 4.

+
+
+

+2.2.1. Topic Properties +

+

The CBOR map includes the following configuration parameters, whose 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 topic names include human-readable strings (e.g., "room2"), UUIDs, or other values.

    +
    • +
  • +

    'topic-data': A required field (optional during creation) containing the URI of the topic-data resource for publishing/subscribing to this topic. It encodes the URI as a CBOR text string.

    +
    • +
  • +

    'resource-type': A required field used to indicate the resource type of the topic-data resource for the topic. It encodes the resource type as a CBOR text string. The value should be "core.ps.conf".

    +
    • +
+
    +
  • +

    'media-type': An optional field used to indicate the media type of the topic-data resource for the topic. It encodes the media type as a this information as the integer identifier of the CoAP content-format (e.g., value is "50" for "application/json").

    +
    • +
  • +

    'topic-type': An optional field used to indicate the attribute or property of the topic-data resource for the topic. It encodes the attribute as a CBOR text string. Example attributes include "temperature".

    +
    • +
  • +

    'expiration-date': An optional field used to indicate the expiration date of the topic. It encodes the expiration date as a CBOR text string. The value should be a date string in ISO 8601 format (e.g., "2023-03-31T23:59:59Z"). The broker can use this field to automatically remove topics that are no longer valid. If this field is not present, the topic will not expire automatically.

    +
    • +
  • +

    'max-subscribers': An optional field used to indicate the maximum number of simultaneous subscribers allowed for the topic. It encodes the maximum number as an unsigned CBOR integer. If this field is not present, there is no limit to the number of simultaneous subscribers allowed. The broker can use this field to limit the number of subscribers for the topic. The default value for this field has been set to 100 subscribers.

    +
    • +
  • +

    'observer-check': An optional field that controls the maximum number of seconds between two consecutive Observe notifications sent as Confirmable messages to each topic subscriber. Encoded as a CBOR unsigned integer greater than 0, it ensures subscribers who have lost interest and silently forgotten the observation do not remain indefinitely on the server's observer list. If another CoAP server hosts the topic-data resource, that server is responsible for applying the observer-check value. The default value for this field is 86400, as defined in [RFC7641], which corresponds to 24 hours.

    +
    • +
+
+
+
+
+
+
+

+2.3. Discovery +

+

A client can perform a discovery of: the broker; the topic collection resources and topic resources hosted by the broker; and the topic-data resources associated with those topic resources.

+
+
+

+2.3.1. Broker Discovery +

+

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

+

The following example shows an endpoint discovering a broker using the "core.ps" resource type over a multicast network. Brokers within the multicast scope will answer the query.

+
+
+=> 0.01 GET
+   Uri-Path: coap://[ff0x::fe]/.well-known/core
+   Resource-Type: core.ps
+
+<= 2.05 Content
+   Payload:
+   Content-Format: 40 (application/link-format)
+   <coap://mythinguri.com/broker/v1>; rt=core.ps
+
+
+
+
+
+
+

+2.3.2. Topic Collection Discovery +

+

A Broker SHOULD offer a topic discovery entry point to enable clients to find topics of interest. The resource entry point is the topic collection resource collecting the topic configurations for those topics (see Section 1.2.2 of [RFC6690]) and is identified by the resource type "core.ps.coll".

+

The specific resource path is left for implementations, examples in this document use the "/ps" path. The interactions with a topic collection are further defined in Section 2.4.

+

Since the representation of the topic collection resource includes the links to the associated topic resources, it is not required to locate those links under "/.well-known/core", also in order to limit the size of the Link Format document returned as result of the discovery.

+

Example:

+
+
+=> 0.01 GET
+   Uri-Path: .well-known/core
+   Resource-Type: core.ps.coll
+
+   <= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps1>;rt="core.ps.coll";ct=40,
+   </other/path>;rt="core.ps.coll";ct=40
+
+
+
+
+
+
+

+2.3.3. Topic-Configuration Discovery +

+

Each topic collection is associated with a group of topic resources, each detailing the configuration of its respective topic (refer to Section 2.2.1). Each topic resource is identified by the resource type "core.ps.conf".

+

Below is an example of discovery via /.well-known/core with rt=core.ps.conf that returns a list of topics, as the list of links to the corresponding topic resources.

+
+
+=> 0.01 GET
+   Uri-Path: .well-known/core
+   Resource-Type: core.ps.conf
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps1/h9392>;rt="core.ps.conf";ct=TBD,
+   </other/path/2e3570>;rt=core.ps.conf;ct=TBD
+
+
+
+
+
+
+

+2.3.4. Topic-Data Discovery +

+

Within a topic, there is the topic-data property containing the URI of the topic-data resource that a CoAP client can subscribe and publish to. Resources exposing resources of the topic-data type are expected to use the resource type 'core.ps.data'.

+

The topic-data contains the URI of the topic-data resource for publishing and subscribing. So retrieving the topic configuration will also provide the URL of the topic-data (see Section 2.5.1).

+

It is also possible to discover a list of topic-data resources by sending a request to the collection with with rt=core.ps.data resources as shown below.

+
+
+=> 0.01 GET
+   Uri-Path: /ps
+   Resource-Type: core.ps.data
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps/data/62e4f8d>; rt=core.ps.data; obs
+
+
+
+
+
+
+
+
+

+2.4. Topic Collection Interactions +

+

These are the interactions that can happen directly with a specific topic collection.

+
+
+

+2.4.1. Retrieving all topic-configurations +

+

A client can request a collection of the topics present in the broker by making a GET request to the collection URI.

+

On success, the server returns a 2.05 (Content) response, specifying the list of links to topic resources associated with this topic collection (see Section 2.2).

+

Depending on its granted permissions, a client MAY retrieve a different list of links, corresponding to the topics that the client is authorized to access.

+

Example:

+
+
+=> 0.01 GET
+   Uri-Path: ps
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps/h9392>;rt="core.ps.conf",
+   </ps/2e3570>; rt="core.ps.conf"
+
+
+
+
+
+
+

+2.4.2. Getting topic-configurations by Properties +

+

A client can filter a collection of topics by submitting the +representation of a topic filter (see Section 2.5.2) in a FETCH request to the topic collection URI.

+

On success, the server returns a 2.05 (Content) response with a +representation of a list of topics in the collection (see + Section 2.3.3) that match the filter in CoRE link format [RFC6690].

+

Upon success, the server responds with a 2.05 (Content), providing a list of links to topic resources associated with this topic collection that match the request's filter criteria (refer to Section 2.3.3). A positive match happens only when each request parameter is present with the indicated value in the topic resource representation.

+

Example:

+
+
+=> 0.05 FETCH
+   Uri-Path: ps
+   Content-Format: TBD (application/pubsub+cbor)
+
+   {
+     "resource-type": "core.ps.conf",
+     "topic-type": "temperature"
+   }
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps/2e3570>;rt="core.ps.conf"
+
+
+
+
+
+
+

+2.4.3. Creating a Topic +

+

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

+

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 Location-Path of the new topic and the current representation of the topic resource. The response payload includes a CBOR map with key-value pairs. The response must include the required topic properties (see Section 2.2.1), namely: "topic-name", "resource-type" and "topic-data". It may also include a number of optional properties too.

+

If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST respond with a 4.03 (Forbidden) error. The response MUST have Content-Format set to "application/core-pubsub+cbor".

+

The broker MUST issue a 4.00 (Bad Request) error if a received parameter is invalid, unrecognized, or if the topic-name is already in use or otherwise invalid.

+
+
+=> 0.02 POST
+   Uri-Path: ps
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   TBD (this should be a CBOR map with the mandatory parameters)
+   {
+     "topic-name": "living-room-sensor",
+     "resource-type": "core.ps.conf"
+   }
+
+<= 2.01 Created
+   Location-Path: ps/h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   TBD (this should be a CBOR map)
+   {
+     "topic-name": "living-room-sensor",
+     "topic-data": "ps/data/1bd0d6d",
+     "resource-type": "core.ps.conf"
+   }
+
+
+
+
+
+
+
+
+

+2.5. Topic-Configuration Interactions +

+

These are the interactions that can happen at the topic resource level.

+
+
+

+2.5.1. Getting a topic-configuration +

+

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 partial representation of the topic resource, as specified in Section 2.2. The partial representation includes only the configuration parameters such that they are present and have the same value in both the current topic configuration as well as in the FETCH request.

+

If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker 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 4.

+

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

+
+
+=> 0.01 GET
+   Uri-Path: ps
+   Uri-Path: h9392
+
+<= 2.05 Content
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   {
+      "topic-name" : "living-room-sensor",
+      "topic-data" : "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "temperature",
+      "expiration-date": "2023-04-00T23:59:59Z",
+      "max-subscribers": 100
+   }
+
+
+
+
+
+
+
+

+2.5.2. Getting part of a topic-configuration +

+

A client can read the configuration of a topic by making a FETCH request to the topic resource URI with a filter for specific parameters. This is done in order to retrieve part of the current topic resource.

+

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 requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker 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 4.

+

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

+

Example:

+
+
+=> 0.05 FETCH
+   Uri-Path: ps
+   Uri-Path: h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   {
+     "conf-filter": ["topic-data", "media-type"]
+   }
+
+<= 2.05 Content
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   {
+     "topic-data": "ps/data/1bd0d6d",
+     "media-type": "application/senml-cbor"
+   }
+
+
+
+
+
+
+
+

+2.5.3. Updating the topic-configuration +

+

A client can update a topic's configuration by submitting the updated topic representation in a PUT request to the topic URI. However, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker.

+

On success, the topic configuration is overwritten and server returns a 2.04 (Changed) response and the current full resource representation. The broker may chose not to overwrite parameters that are not explicitly modified in the request.

+

Note that updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Updating the "topic-data" may happen also after it being deleted, as described on {delete-topic-data}, this will in turn create a new "topic-data" path for that topic configuration.

+

Similarly, decreasing max-subscribers will also cause that some subscribers get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per [RFC7641] Section 3.2.

+

Please note that when using PUT the topic configuration is being overwritten, thus some of the optional parameters (e.g., "max-subscribers", "observer-check") not included in the PUT message will be reset to their default values.

+

Example:

+
+
+=> 0.03 PUT
+   Uri-Path: ps
+   Uri-Path: h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   {
+      "topic-name": "living-room-sensor",
+      "topic-data": "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "temperature",
+      "expiration-date": "2023-04-28T23:59:59Z",
+   }
+
+<= 2.04 Changed
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   TBD (this should be a CBOR map)
+   {
+      "topic-name": "living-room-sensor",
+      "topic-data": "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "temperature",
+      "expiration-date": "2023-04-28T23:59:59Z",
+      "max-subscribers": 100,
+      "observer-check": 86400
+   }
+
+
+

Note that 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.

    +
    • +
  • +

    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.

    +
    • +
+
+
+
+
+

+2.5.4. Updating the topic-configuration with iPATCH +

+

A client can partially update a topic's configuration by submitting a partial topic representation in an iPATCH request to the topic URI. The iPATCH request allows for updating only specific fields of the topic configuration while leaving the others unchanged. As with the PUT method, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker.

+

On success, the server returns a 2.04 (Changed) response and the current full resource representation. The broker only updates parameters that are explicitly mentioned in the request.

+

As with the PUT method, updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Decreasing max-subscribers will also cause some subscribers to get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per [RFC7641] Section 3.2.

+

Contrary to PUT iPATCH operations will explicitly update some parameters, leaving others unmodified.

+
+
+=> 0.07 iPATCH
+   Uri-Path: ps
+   Uri-Path: h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   {
+      "topic-type": "humidity",
+      "max-subscribers": 5
+   }
+
+<= 2.04 Changed
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   TBD (this should be a CBOR map)
+   {
+      "topic-name" : "living-room-sensor",
+      "topic-data" : "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "humidity",
+      "expiration-date": "2023-05-28T23:59:59Z",
+      "max-subscribers": 5
+   }
+
+
+

Note that when a topic configuration changes through an iPATCH request, 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.

+
+
+
+
+

+2.5.5. Deleting a topic-configuration +

+

A client can delete a topic by making a CoAP DELETE request on the topic resource URI.

+

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

+

When a topic-configuration resource is deleted, the broker MUST also delete the topic-data resource, unsubscribe all subscribers by removing them from the list of observers and returning a final 4.04 (Not Found) response as per section 3.2 of [RFC7641].

+

Example:

+
+
+=> 0.04 DELETE
+   Uri-Path: ps
+   Uri-Path: h9392
+
+<= 2.02 Deleted
+
+
+
+
+
+
+
+
+
+
+

+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 Observe option set to 0 (register) to a topic-data resource. When resource state changes, subscribers observing the resource [RFC7641] at that time will receive a notification.

+

A topic-data resource does not exist until some initial data has been published to it. Before initial data publication, a GET request to the topic-data resource URI results in 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). There is no necessary URI pattern dependence between the URI where the topic-data exists and the URI of the topic-configuration resource.

+
+
+

+3.1. Topic Lifecycle +

+

When a topic is newly created, it is first placed by the broker 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 subscribe to 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 + + +
+
+
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 data by means of a GET request without observe. 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.

+
+
+
+
+

+3.2. Topic-Data Interactions +

+

Interactions with the topic-data resource are covered in this section.

+
+
+

+3.2.1. Publish +

+

A topic-configuration with a topic-data resource must have been created in order to publish data to it (See Section 2.4.3) and be in the half-created or fully-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
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+   Content-Format: 110
+
+   {
+      "n": "coap://dev1.example.com/temperature",
+      "u": "Cel",
+      "t": 1621452122,
+      "v": 23.5
+   }
+
+<= 2.01 Created
+
+
+

Example of subsequent publication:

+
+
+=> 0.03 PUT
+   Uri-Path: ps
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+   Content-Format: 110
+
+   {
+      "n": "coap://dev1.example.com/temperature",
+      "u": "Cel",
+      "t": 1621452149,
+      "v": 22.5
+   }
+
+<= 2.04 Updated
+
+
+
+
+
+
+

+3.2.2. Subscribe +

+

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

+

On success, the server hosting the topic-data resource MUST return 2.05 (Content) notifications with the data and the Observe Option. Otherwise, if no Observe Option is present the client should assume that the subscription was not successful.

+

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". The topic-data does not exist.

+
+
+
+

If the 'max-subscribers' 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
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+   Observe: 0
+
+<= 2.05 Content
+   Content-Format: 110
+   Observe: 10001
+   Max-Age: 15
+
+  {
+    "n": "urn:dev:os:32473-123456",
+    "u": "Cel",
+    "t": 1696341182,
+    "v": 19.87
+  }
+
+<= 2.05 Content
+   Content-Format: 110
+   Observe: 10002
+   Max-Age: 15
+
+  {
+
+    "n": "urn:dev:os:32473-123456",
+    "u": "Cel",
+    "t": 1696340184,
+    "v": 21.87
+  }
+
+
+
+
+
+
+

+3.2.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. Also on Section 3.6 of [RFC7641] the client can simply "forget" the observation and the server will remove it from the list of observers after the next notification.

+

As per [RFC7641] a server that transmits notifications mostly in non-confirmable messages, but it 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.

+
+
+
+
+

+3.2.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 3.1.

+

Example:

+
+
+=> 0.04 DELETE
+   Uri-Path: ps
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+
+<= 2.02 Deleted
+
+
+
+
+
+
+
+
+

+3.3. 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 3.1), the broker MUST return a response code 4.04 (Not Found).

+

Example:

+
+
+=> 0.01 GET
+   Uri-Path: ps
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+
+<= 2.05 Content
+   Content-Format: 110
+   Max-Age: 15
+
+   {
+      "n": "coap://dev1.example.com/temperature",
+      "u": "Cel",
+      "t": 1621452122,
+      "v": 23.5
+   }
+
+
+
+
+
+
+

+3.4. Rate Limiting +

+

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

+

In this situation, if a publisher 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 also stop publishing messages from that publisher for the indicated time.

+

When a publisher 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.

+
+
+
+
+
+
+

+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.

+
+
+
+
++-----------------+-----------+-----------+------------+
+| Name            | CBOR Key  | CBOR Type | Reference  |
+|-----------------|-----------|-----------|------------|
+| topic-name      | TBD1      | tstr      | [RFC-XXXX] |
+| topic-data      | TBD2      | tstr      | [RFC-XXXX] |
+| resource-type   | TBD3      | tstr      | [RFC-XXXX] |
+| media-type      | TBD4      | uint      | [RFC-XXXX] |
+| topic-type      | TBD5      | tstr      | [RFC-XXXX] |
+| expiration-date | TBD6      | tstr      | [RFC-XXXX] |
+| max-subscribers | TBD7      | uint      | [RFC-XXXX] |
+| observer-check  | TBD8      | uint      | [RFC-XXXX] |
++-----------------+-----------+-----------+------------+
+
+
+
Figure 5: +CoAP Pubsub Parameters +
+
+
+
+
+
+

+5. Security Considerations +

+

The architecture presented in this document inherits the security considerations from CoAP [RFC7252] and Observe [RFC7641], as well as from Web Linking [RFC8288], Link-Format [RFC6690], and the CoRE Resource Directory [RFC9176].

+

Communications between each client and the broker MUST be secured, e.g., by using OSCORE [RFC8613] or DTLS [RFC9147]. Security considerations for the used secure communication protocols apply too.

+

The content published on a topic by a publisher client SHOULD be protected end-to-end between the publisher and all the subscribers to that topic. In such a case, it MUST be possible to assert source authentication of the published data. This can be achieved at the application layer, e.g., by using COSE [RFC9052], [RFC9053], [RFC9338].

+

Access control of clients at the broker MAY be enforced for performing discovery operation, and SHOULD be enforced in a fine-grained fashion for operations related to the the creation, update, and deletion of topic resources, as well as for operations on topic-data resources such as publication on and subscription to topics. This prevents rogue clients to, among other things, repeatedly create topics at the broker or publish (large) contents, which may result in Denial of Service against the broker and the active subscribers.

+

Building on [I-D.ietf-ace-key-groupcomm], its application profile for publish-subscribe communication with CoAP [I-D.ietf-ace-pubsub-profile] provides a security model that can be used in the architecture presented in this document, in order to enable secure communication between the different parties as well as secure, authorized operations of publishers and subscribers that fulfill the requirements above.

+

In particular, the application profile above relies on the ACE framework for Authentication and Authorization in Constrained Environments (ACE) [RFC9200] and defines a method to: authorize publishers and subscribers to perform operations at the broker, with fine-grained access control; authorize publishers and subscribers to obtain the keying material required to take part to a topic managed by the broker; protect published data end-to-end between its publisher and all the subscribers to the targeted topic, ensuring confidentiality, integrity, and source authentication of the published content end-to-end. That approach can be extended to enforce authorization and fine-grained access control for administrator clients that are intended to create, update, and delete topic configurations at the broker.

+
+
+
+
+

+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.

+
+
+

+6.1. Media Type +

+

IANA is requested to add the following Media-Type to the "Media Types" +registry [IANA.media-types].

+
+ + + + + + + + + + + + + + + + +
+Table 1: +New Media Type application/pubsub+cbor +
NameTemplateReference
pubsub+cborapplication/pubsub+cborRFC XXXX, Section 6.1 +
+
+
+
Type name:
+
+

application

+
+
+
Subtype name:
+
+

pubsub+cbor

+
+
+
Required parameters:
+
+

N/A

+
+
+
Optional parameters:
+
+

N/A

+
+
+
Encoding considerations:
+
+

binary (CBOR data item)

+
+
+
Security considerations:
+
+

Section 5 of RFC XXXX

+
+
+
Interoperability considerations:
+
+

none

+
+
+
Published specification:
+
+

Section 6.1 of RFC XXXX

+
+
+
Applications that use this media type:
+
+

This type is used by clients that create, retrieve, and update topic configurations at servers acting as a pub-sub broker.

+
+
+
Fragment identifier considerations:
+
+

N/A

+
+
+
Person & email address to contact for further information:
+
+

CoRE WG mailing list (core@ietf.org), +or IETF Applications and Real-Time Area (art@ietf.org)

+
+
+
Intended usage:
+
+

COMMON

+
+
+
Restrictions on usage:
+
+

none

+
+
+
Author/Change controller:
+
+

IETF

+
+
+
Provisional registration:
+
+

no

+
+
+
+
+
+
+
+

+6.2. Content-Format +

+

IANA has added the following Content-Formats to the +"CoAP Content-Formats" +sub-registry, within the "Constrained RESTful Environments (CoRE) +Parameters" Registry [IANA.core-parameters], as follows:

+ + + + + + + + + + + + + + + + + + +
+Table 2: +New Content-Format +
Content TypeContent CodingIDReference
application/pubsub+cbor-TBD9RFC XXXX
+

TBD9 is to be assigned from the space 256..999.

+
+
+
+
+

+6.3. CoAP Pubsub Parameters +

+

IANA is asked to register the following entries in the subregistry of the "Constrained RESTful Environments (CoRE) Parameters" registry group.

+

This specification establishes the "Pubsub Topic Configuration Parameters" IANA registry within the "Constrained RESTful Environments (CoRE) +Parameters" registry group.

+

The columns of this registry are:

+
    +
  • +

    Name: This is a descriptive name that enables easier reference to the item. The name MUST be unique. It is not used in the encoding.

    +
    • +
  • +

    CBOR Key: This is the value used as CBOR key of the item. These values MUST be unique. The value can be a positive integer, a negative integer, or a text string. Different ranges of values use different registration policies [RFC8126]. Integer values from -256 to 255 as well as text strings of length 1 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257 and from 256 to 65535, as well as text strings of length 2 are designated as "Specification Required". Integer values greater than 65535 as well as text strings of length greater than 2 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use".

    +
    • +
  • +

    CBOR Type: This contains the CBOR type of the item, or a pointer to the registry that defines its type, when that depends on another item.

    +
    • +
  • +

    Reference: This contains a pointer to the public specification for the item.

    +
    • +
+

The registry is initially populated with the entries in Figure 5 of Section 4.

+
+
+
+
+

+6.4. 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.

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

+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, Olaf Bergmann and Oscar Novo for their valuable contributions and reviews.

+
+
+
+

+References +

+
+
+

+Normative References +

+
+
[IANA.core-parameters]
+
+IANA, "Constrained RESTful Environments (CoRE) Parameters", <http://www.iana.org/assignments/core-parameters>.
+
+
[IANA.media-types]
+
+IANA, "Media Types", <http://www.iana.org/assignments/media-types>.
+
+
[RFC2119]
+
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
+
+
[RFC6570]
+
+Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, , <https://www.rfc-editor.org/rfc/rfc6570>.
+
+
[RFC6690]
+
+Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, , <https://www.rfc-editor.org/rfc/rfc6690>.
+
+
[RFC7252]
+
+Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, , <https://www.rfc-editor.org/rfc/rfc7252>.
+
+
[RFC7641]
+
+Hartke, K., "Observing Resources in the Constrained Application Protocol (CoAP)", RFC 7641, DOI 10.17487/RFC7641, , <https://www.rfc-editor.org/rfc/rfc7641>.
+
+
[RFC8174]
+
+Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
+
+
[RFC8516]
+
+Keranen, A., ""Too Many Requests" Response Code for the Constrained Application Protocol", RFC 8516, DOI 10.17487/RFC8516, , <https://www.rfc-editor.org/rfc/rfc8516>.
+
+
[RFC8613]
+
+Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, , <https://www.rfc-editor.org/rfc/rfc8613>.
+
+
[RFC9176]
+
+Amsüss, C., Ed., Shelby, Z., Koster, M., Bormann, C., and P. van der Stok, "Constrained RESTful Environments (CoRE) Resource Directory", RFC 9176, DOI 10.17487/RFC9176, , <https://www.rfc-editor.org/rfc/rfc9176>.
+
+
+
+
+
+
+

+Informative References +

+
+
[I-D.hartke-t2trg-coral-pubsub]
+
+Hartke, K., "Publish/Subscribe over the Constrained Application Protocol (CoAP) using the Constrained RESTful Application Language (CoRAL)", Work in Progress, Internet-Draft, draft-hartke-t2trg-coral-pubsub-01, , <https://datatracker.ietf.org/doc/html/draft-hartke-t2trg-coral-pubsub-01>.
+
+
[I-D.ietf-ace-key-groupcomm]
+
+Palombini, F. and M. Tiloca, "Key Provisioning for Group Communication using ACE", Work in Progress, Internet-Draft, draft-ietf-ace-key-groupcomm-17, , <https://datatracker.ietf.org/doc/html/draft-ietf-ace-key-groupcomm-17>.
+
+
[I-D.ietf-ace-oscore-gm-admin]
+
+Tiloca, M., Höglund, R., Van der Stok, P., and F. Palombini, "Admin Interface for the OSCORE Group Manager", Work in Progress, Internet-Draft, draft-ietf-ace-oscore-gm-admin-10, , <https://datatracker.ietf.org/doc/html/draft-ietf-ace-oscore-gm-admin-10>.
+
+
[I-D.ietf-ace-pubsub-profile]
+
+Palombini, F., Sengul, C., and M. Tiloca, "Publish-Subscribe Profile for Authentication and Authorization for Constrained Environments (ACE)", Work in Progress, Internet-Draft, draft-ietf-ace-pubsub-profile-08, , <https://datatracker.ietf.org/doc/html/draft-ietf-ace-pubsub-profile-08>.
+
+
[RFC8126]
+
+Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, , <https://www.rfc-editor.org/rfc/rfc8126>.
+
+
[RFC8288]
+
+Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, , <https://www.rfc-editor.org/rfc/rfc8288>.
+
+
[RFC9052]
+
+Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, , <https://www.rfc-editor.org/rfc/rfc9052>.
+
+
[RFC9053]
+
+Schaad, J., "CBOR Object Signing and Encryption (COSE): Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, , <https://www.rfc-editor.org/rfc/rfc9053>.
+
+
[RFC9147]
+
+Rescorla, E., Tschofenig, H., and N. Modadugu, "The Datagram Transport Layer Security (DTLS) Protocol Version 1.3", RFC 9147, DOI 10.17487/RFC9147, , <https://www.rfc-editor.org/rfc/rfc9147>.
+
+
[RFC9200]
+
+Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "Authentication and Authorization for Constrained Environments Using the OAuth 2.0 Framework (ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, , <https://www.rfc-editor.org/rfc/rfc9200>.
+
+
[RFC9338]
+
+Schaad, J., "CBOR Object Signing and Encryption (COSE): Countersignatures", STD 96, RFC 9338, DOI 10.17487/RFC9338, , <https://www.rfc-editor.org/rfc/rfc9338>.
+
+
+
+
+
+
+
+

+Contributors +

+
+
Marco Tiloca
+
RISE AB
+ +
+

Marco offered comprehensive reviews and insightful guidance on the recent iterations of this document. His contributions were particularly notable in the Security Considerations section, among others.

+
+
+
+
+

+Authors' Addresses +

+
+
Jaime Jimenez
+
Ericsson
+ +
+
+
Michael Koster
+
Dogtiger Labs
+ +
+
+
Ari Keranen
+
Ericsson
+ +
+
+
+ + + diff --git a/edit-fixes/draft-ietf-core-coap-pubsub.txt b/edit-fixes/draft-ietf-core-coap-pubsub.txt new file mode 100644 index 0000000..e50dbb4 --- /dev/null +++ b/edit-fixes/draft-ietf-core-coap-pubsub.txt @@ -0,0 +1,1485 @@ + + + + +CoRE Working Group J. Jimenez +Internet-Draft Ericsson +Intended status: Standards Track M. Koster +Expires: 8 May 2024 Dogtiger Labs + A. Keranen + Ericsson + 5 November 2023 + + + A publish-subscribe architecture for the Constrained Application + Protocol (CoAP) + draft-ietf-core-coap-pubsub-latest + +Abstract + + This document describes a publish-subscribe architecture for the + Constrained Application Protocol (CoAP), extending the capabilities + of CoAP communications for supporting endpoints with long breaks in + connectivity and/or up-time. CoAP clients publish on and subscribe + to a topic via a corresponding topic resource at a CoAP server acting + as broker. + +About This Document + + This note is to be removed before publishing as an RFC. + + Status information for this document may be found at + https://datatracker.ietf.org/doc/draft-ietf-core-coap-pubsub/. + + Discussion of this document takes place on the core Working Group + mailing list (mailto:core@ietf.org), which is archived at + https://mailarchive.ietf.org/arch/browse/core/. Subscribe at + https://www.ietf.org/mailman/listinfo/core/. + + Source for this draft and an issue tracker can be found at + https://github.com/core-wg/coap-pubsub. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at https://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on 8 May 2024. + +Copyright Notice + + Copyright (c) 2023 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents (https://trustee.ietf.org/ + license-info) in effect on the date of publication of this document. + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. Code Components + extracted from this document must include Revised BSD License text as + described in Section 4.e of the Trust Legal Provisions and are + provided without warranty as described in the Revised BSD License. + +Table of Contents + + 1. Introduction + 1.1. Terminology + 1.2. CoAP Publish-Subscribe Architecture + 1.3. Managing Topics + 2. Pub-Sub Topics + 2.1. Collection Representation + 2.2. Topic-Configuration Representation + 2.2.1. Topic Properties + 2.3. Discovery + 2.3.1. Broker Discovery + 2.3.2. Topic Collection Discovery + 2.3.3. Topic-Configuration Discovery + 2.3.4. Topic-Data Discovery + 2.4. Topic Collection Interactions + 2.4.1. Retrieving all topic-configurations + 2.4.2. Getting topic-configurations by Properties + 2.4.3. Creating a Topic + 2.5. Topic-Configuration Interactions + 2.5.1. Getting a topic-configuration + 2.5.2. Getting part of a topic-configuration + 2.5.3. Updating the topic-configuration + 2.5.4. Updating the topic-configuration with iPATCH + 2.5.5. Deleting a topic-configuration + 3. Publish and Subscribe + 3.1. Topic Lifecycle + 3.2. Topic-Data Interactions + 3.2.1. Publish + 3.2.2. Subscribe + 3.2.3. Unsubscribe + 3.2.4. Delete topic-data + 3.3. Read latest data + 3.4. Rate Limiting + 4. CoAP Pubsub Parameters + 5. Security Considerations + 6. IANA Considerations + 6.1. Media Type + 6.2. Content-Format + 6.3. CoAP Pubsub Parameters + 6.4. Resource Types + Acknowledgements + References + Normative References + Informative References + Contributors + Authors' Addresses + +1. Introduction + + The Constrained Application Protocol (CoAP) [RFC7252] supports + machine-to-machine communication across networks of constrained + devices and constrained networks. CoAP uses a request/response model + where clients make requests to servers in order to request actions on + resources. Depending on the situation the same device may act either + as a server, a client, or both. + + One important class of constrained devices includes devices that are + intended to run for years from a small battery, or by scavenging + energy from their environment. These devices have limited up-time + because they spend most of their time in a sleeping state with no + network connectivity. Another important class of nodes are devices + with limited reachability due to middle-boxes like Network Address + Translators (NATs) and firewalls. + + For these nodes, the client/server-oriented architecture of REST can + be challenging when interactions are not initiated by the devices + themselves. A publish/subscribe-oriented architecture where nodes + exchange data via topics through a broker entity might fit these + nodes better. + + This document applies the idea of broker-based publish-subscribe to + Constrained RESTful Environments using CoAP. It defines a broker + that allows to create, discover subscribe and publish on topics. + +1.1. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + This specification requires readers to be familiar with all the terms + and concepts that are discussed in [RFC8288] and [RFC6690]. Readers + should also be familiar with the terms and concepts discussed in + [RFC7252], [RFC9176] and [RFC7641]. The URI template format + [RFC6570] is used to describe the REST API defined in this + specification. + + This specification makes use of the following terminology: + + publish-subscribe (pub/sub): + A message communication model where messages associated with + specific topics are sent to a broker. Interested parties, i.e. + subscribers, receive these topic-based messages from the broker + without the original sender knowing the recipients. The broker + handles matching and delivering these messages to the appropriate + subscribers. + + publishers and subscribers: + CoAP clients can act as publishers or as subscribers. Publishers + send CoAP messages (publications) to the broker on specific + topics. Subscribers have an ongoing observation relation + (subscription) to a topic. Both roles operate without any mutual + knowledge, guided by their respective topic interests. + + topic collection: + A set of topic configurations. A topic collection is hosted as + one collection resource at the broker, and its representation is + the list of links to the topic resources corresponding to each + topic configuration. + + topic-configuration: + A set of information concerning a topic, including its + configuration and other metadata. A topic configuration is hosted + as one topic resource at the broker, and its representation is the + set of configuration information concerning the topic. All the + topic resources associated with the same topic collection share a + common base URI, i.e., the URI of the collection resource. + Throughout this document the word "topic" and "topic- + configuration" can be used interchangeably. + + topic-data resource: + A resource where clients can publish data and/or subscribe to data + for a specific topic. The representation of the topic resource + corresponding to such a topic also specifies the URI to the + present topic-data resource. + + broker: + A CoAP server that hosts one or more topic collections with their + topic-configurations, and also topic-data resources. The broker + is responsible for the store-and-forward of state update + representations, for the topics for which it hosts the + corresponding topic-data resources. 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. + +1.2. CoAP Publish-Subscribe Architecture + + Figure 1 shows a simple Publish/Subscribe architecture over CoAP. + + Topics are created by the broker, but the initial configuration can + be proposed by a client (e.g., a publisher or a dedicated + administrator) over the RESTful interface of a corresponding topic + resource hosted by the broker. + + Publishers submit their data over the RESTful interface of a topic- + data resource corresponding to the topic, which may be hosted by the + broker. Subscribers to a topic are notified of new publications by + using Observe [RFC7641] on the corresponding topic-data resource. + + The broker is responsible for the store-and-forward of state update + representations between CoAP clients. Subscribers observing a + resource will receive notifications, the delivery of which is done on + a best-effort basis. + + CoAP CoAP CoAP + clients server clients + .-----------. .----------. observe .-----------. + | | publish | |<----------+ | + | publisher +--------->+ +---------->| subscribe | + | | | +---------->| | + '-----------' | | '-----------' + ... | broker | ... + ... | | ... + .-----------. | | observe .-----------. + | | publish | |<----------+ | + | publisher +--------->| +---------->| subscribe | + | | | +---------->| | + '-----------' '----------' '-----------' + + Figure 1: 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 3.2). + + Topic-configuration interactions are discovery, create, read + configuration, update configuration, and delete configuration. These + operations handle the management of the topics. + + Topic-data interactions are publish, subscribe, unsubscribe, read, + and delete. These operations are oriented on how data is transferred + from a publisher to a subscriber. + +1.3. Managing Topics + + Figure 2 shows the resources related to a Topic Collection that can + be managed at the Broker. + + ___ + topic / \ + collection \___/ + resource \ + \____________________ + \___ \___ \___ + / \ / \ ... / \ topic resources + \___/ \___/ \___/ + + Figure 2: Resources of a Broker + + The Broker exports one or more topic-collection resources, 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. + + A topic-collection resource can have topic resources as its child + resources, with resource type "core.ps.conf". + +2. Pub-Sub Topics + + The configuration side of a "publish/subscribe broker" consists of a + collection of topics. These topics as well as the collection itself + are exposed by a CoAP server as resources (see Figure 3). Each topic + is associated with a topic configuration resource and a topic-data + resource. The topic configuration resource is used by a client + creating or administering a topic. The topic-data resource is used + by the publishers and the subscribers to a topic. + + ___ + topic / \ + collection \___/ + resource \ + \___________________________ + \ \ \ + \ ...... \ ...... \ ...... + topic : \___ : : \___ : : \___ : + configuration : / * \ : : / * \ : : / * \ : + resource : \_|_/ : : \_|_/ : : \_|_/ : + ....|.... ....|.... ....|.... + ....|.... ....|.... ....|.... + : _|_ : : _|_ : ... : _|_ : + topic-data : / \ : : / \ : : / \ : + resource : \___/ : : \___/ : : \___/ : + :.......: :.......: :.......: + \_________/\_________/ ... \_________/ + topic 1 topic 2 topic n + + Figure 3: Topic and topic-data resources of a topic + +2.1. Collection Representation + + Each topic configuration is represented as a link, where the link + target is the URI of the corresponding topic resource. + + Publication and subscription to a topic occur at a link, where the + link target is the URI of the corresponding topic-data resource. + Such a link is specified by the topic-data entry within the topic + resource (see Section 2.2.1). + + A topic resource with a topic-data link can also be simply called + "topic". + + The list of links to the topic resources can be retrieved from the + associated topic collection resource, and represented as a Link + Format document [RFC6690]where each such link specifies the link + target attribute 'rt' (Resource Type), with value "core.ps.conf" + defined in this document. + +2.2. Topic-Configuration Representation + + 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 4. + +2.2.1. Topic Properties + + The CBOR map includes the following configuration parameters, whose + 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 + topic names include human-readable strings (e.g., "room2"), UUIDs, + or other values. + + * 'topic-data': A required field (optional during creation) + containing the URI of the topic-data resource for publishing/ + subscribing to this topic. It encodes the URI as a CBOR text + string. + + * 'resource-type': A required field used to indicate the resource + type of the topic-data resource for the topic. It encodes the + resource type as a CBOR text string. The value should be + "core.ps.conf". + + * 'media-type': An optional field used to indicate the media type of + the topic-data resource for the topic. It encodes the media type + as a this information as the integer identifier of the CoAP + content-format (e.g., value is "50" for "application/json"). + + * 'topic-type': An optional field used to indicate the attribute or + property of the topic-data resource for the topic. It encodes the + attribute as a CBOR text string. Example attributes include + "temperature". + + * 'expiration-date': An optional field used to indicate the + expiration date of the topic. It encodes the expiration date as a + CBOR text string. The value should be a date string in ISO 8601 + format (e.g., "2023-03-31T23:59:59Z"). The broker can use this + field to automatically remove topics that are no longer valid. If + this field is not present, the topic will not expire + automatically. + + * 'max-subscribers': An optional field used to indicate the maximum + number of simultaneous subscribers allowed for the topic. It + encodes the maximum number as an unsigned CBOR integer. If this + field is not present, there is no limit to the number of + simultaneous subscribers allowed. The broker can use this field + to limit the number of subscribers for the topic. The default + value for this field has been set to 100 subscribers. + + * 'observer-check': An optional field that controls the maximum + number of seconds between two consecutive Observe notifications + sent as Confirmable messages to each topic subscriber. Encoded as + a CBOR unsigned integer greater than 0, it ensures subscribers who + have lost interest and silently forgotten the observation do not + remain indefinitely on the server's observer list. If another + CoAP server hosts the topic-data resource, that server is + responsible for applying the observer-check value. The default + value for this field is 86400, as defined in [RFC7641], which + corresponds to 24 hours. + +2.3. Discovery + + A client can perform a discovery of: the broker; the topic collection + resources and topic resources hosted by the broker; and the topic- + data resources associated with those topic resources. + +2.3.1. Broker Discovery + + CoAP clients MAY discover brokers by using CoAP Simple Discovery, via + multicast, through a Resource Directory (RD) [RFC9176] or by other + means specified in extensions to [RFC7252]. Brokers MAY register + with a RD by following the steps on Section 5 of [RFC9176] with the + resource type set to "core.ps" as defined in Section 6 of this + document. + + The following example shows an endpoint discovering a broker using + the "core.ps" resource type over a multicast network. Brokers within + the multicast scope will answer the query. + + => 0.01 GET + Uri-Path: coap://[ff0x::fe]/.well-known/core + Resource-Type: core.ps + + <= 2.05 Content + Payload: + Content-Format: 40 (application/link-format) + ; rt=core.ps + +2.3.2. Topic Collection Discovery + + A Broker SHOULD offer a topic discovery entry point to enable clients + to find topics of interest. The resource entry point is the topic + collection resource collecting the topic configurations for those + topics (see Section 1.2.2 of [RFC6690]) and is identified by the + resource type "core.ps.coll". + + The specific resource path is left for implementations, examples in + this document use the "/ps" path. The interactions with a topic + collection are further defined in Section 2.4. + + Since the representation of the topic collection resource includes + the links to the associated topic resources, it is not required to + locate those links under "/.well-known/core", also in order to limit + the size of the Link Format document returned as result of the + discovery. + + Example: + + => 0.01 GET + Uri-Path: .well-known/core + Resource-Type: core.ps.coll + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.coll";ct=40, + ;rt="core.ps.coll";ct=40 + +2.3.3. Topic-Configuration Discovery + + Each topic collection is associated with a group of topic resources, + each detailing the configuration of its respective topic (refer to + Section 2.2.1). Each topic resource is identified by the resource + type "core.ps.conf". + + Below is an example of discovery via /.well-known/core with + rt=core.ps.conf that returns a list of topics, as the list of links + to the corresponding topic resources. + + => 0.01 GET + Uri-Path: .well-known/core + Resource-Type: core.ps.conf + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf";ct=TBD, + ;rt=core.ps.conf;ct=TBD + +2.3.4. Topic-Data Discovery + + Within a topic, there is the topic-data property containing the URI + of the topic-data resource that a CoAP client can subscribe and + publish to. Resources exposing resources of the topic-data type are + expected to use the resource type 'core.ps.data'. + + The topic-data contains the URI of the topic-data resource for + publishing and subscribing. So retrieving the topic configuration + will also provide the URL of the topic-data (see Section 2.5.1). + + It is also possible to discover a list of topic-data resources by + sending a request to the collection with with rt=core.ps.data + resources as shown below. + + => 0.01 GET + Uri-Path: /ps + Resource-Type: core.ps.data + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ; rt=core.ps.data; obs + +2.4. Topic Collection Interactions + + These are the interactions that can happen directly with a specific + topic collection. + +2.4.1. Retrieving all topic-configurations + + A client can request a collection of the topics present in the broker + by making a GET request to the collection URI. + + On success, the server returns a 2.05 (Content) response, specifying + the list of links to topic resources associated with this topic + collection (see Section 2.2). + + Depending on its granted permissions, a client MAY retrieve a + different list of links, corresponding to the topics that the client + is authorized to access. + + Example: + + => 0.01 GET + Uri-Path: ps + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf", + ; rt="core.ps.conf" + +2.4.2. Getting topic-configurations by Properties + + A client can filter a collection of topics by submitting the + representation of a topic filter (see Section 2.5.2) in a FETCH + request to the topic collection URI. + + On success, the server returns a 2.05 (Content) response with a + representation of a list of topics in the collection (see + Section 2.3.3) that match the filter in CoRE link format [RFC6690]. + + Upon success, the server responds with a 2.05 (Content), providing a + list of links to topic resources associated with this topic + collection that match the request's filter criteria (refer to + Section 2.3.3). A positive match happens only when each request + parameter is present with the indicated value in the topic resource + representation. + + Example: + + => 0.05 FETCH + Uri-Path: ps + Content-Format: TBD (application/pubsub+cbor) + + { + "resource-type": "core.ps.conf", + "topic-type": "temperature" + } + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf" + +2.4.3. Creating a Topic + + A client can add a new topic-configurations to a collection of topics + by submitting an initial representation of the initial topic resource + (see Section 2.2) in a POST request to the topic collection URI. The + request MUST specify at least a subset of the properties in + Section 2.2.1, namely: topic-name and resource-type. + + 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 Location-Path of the new topic and the current representation of + the topic resource. The response payload includes a CBOR map with + key-value pairs. The response must include the required topic + properties (see Section 2.2.1), namely: "topic-name", "resource-type" + and "topic-data". It may also include a number of optional + properties too. + + If requirements are defined for the client to create the topic as + requested and the broker does not successfully assess that those + requirements are met, then the broker MUST respond with a 4.03 + (Forbidden) error. The response MUST have Content-Format set to + "application/core-pubsub+cbor". + + The broker MUST issue a 4.00 (Bad Request) error if a received + parameter is invalid, unrecognized, or if the topic-name is already + in use or otherwise invalid. + + => 0.02 POST + Uri-Path: ps + Content-Format: TBD2 (application/core-pubsub+cbor) + TBD (this should be a CBOR map with the mandatory parameters) + { + "topic-name": "living-room-sensor", + "resource-type": "core.ps.conf" + } + + <= 2.01 Created + Location-Path: ps/h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf" + } + +2.5. Topic-Configuration Interactions + + These are the interactions that can happen at the topic resource + level. + +2.5.1. Getting a topic-configuration + + 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 + partial representation of the topic resource, as specified in + Section 2.2. The partial representation includes only the + configuration parameters such that they are present and have the same + value in both the current topic configuration as well as in the FETCH + request. + + If requirements are defined for the client to create the topic as + requested and the broker does not successfully assess that those + requirements are met, then the broker 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 4. + + For example, below is a request on the topic "ps/h9392": + + => 0.01 GET + Uri-Path: ps + Uri-Path: h9392 + + <= 2.05 Content + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "topic-name" : "living-room-sensor", + "topic-data" : "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-00T23:59:59Z", + "max-subscribers": 100 + } + +2.5.2. Getting part of a topic-configuration + + A client can read the configuration of a topic by making a FETCH + request to the topic resource URI with a filter for specific + parameters. This is done in order to retrieve part of the current + topic resource. + + 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 requirements are defined for the client to create the topic as + requested and the broker does not successfully assess that those + requirements are met, then the broker 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 4. + + Both request and response MUST have Content-Format set to + "application/core-pubsub+cbor". + + Example: + + => 0.05 FETCH + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "conf-filter": ["topic-data", "media-type"] + } + + <= 2.05 Content + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "topic-data": "ps/data/1bd0d6d", + "media-type": "application/senml-cbor" + } + +2.5.3. Updating the topic-configuration + + A client can update a topic's configuration by submitting the updated + topic representation in a PUT request to the topic URI. However, the + parameters "topic-name", "topic-data", and "resource-type" are + immutable post-creation, and any request attempting to change them + will be deemed invalid by the broker. + + On success, the topic configuration is overwritten and server returns + a 2.04 (Changed) response and the current full resource + representation. The broker may chose not to overwrite parameters + that are not explicitly modified in the request. + + Note that updating the "topic-data" path will automatically cancel + all existing observations on it and thus will unsubscribe all + subscribers. Updating the "topic-data" may happen also after it + being deleted, as described on {delete-topic-data}, this will in turn + create a new "topic-data" path for that topic configuration. + + Similarly, decreasing max-subscribers will also cause that some + subscribers get unsubscribed. Unsubscribed endpoints SHOULD receive + a final 4.04 (Not Found) response as per [RFC7641] Section 3.2. + + Please note that when using PUT the topic configuration is being + overwritten, thus some of the optional parameters (e.g., "max- + subscribers", "observer-check") not included in the PUT message will + be reset to their default values. + + Example: + + => 0.03 PUT + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-28T23:59:59Z", + } + + <= 2.04 Changed + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-28T23:59:59Z", + "max-subscribers": 100, + "observer-check": 86400 + } + + Note that 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. + + * 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. + +2.5.4. Updating the topic-configuration with iPATCH + + A client can partially update a topic's configuration by submitting a + partial topic representation in an iPATCH request to the topic URI. + The iPATCH request allows for updating only specific fields of the + topic configuration while leaving the others unchanged. As with the + PUT method, the parameters "topic-name", "topic-data", and "resource- + type" are immutable post-creation, and any request attempting to + change them will be deemed invalid by the broker. + + On success, the server returns a 2.04 (Changed) response and the + current full resource representation. The broker only updates + parameters that are explicitly mentioned in the request. + + As with the PUT method, updating the "topic-data" path will + automatically cancel all existing observations on it and thus will + unsubscribe all subscribers. Decreasing max-subscribers will also + cause some subscribers to get unsubscribed. Unsubscribed endpoints + SHOULD receive a final 4.04 (Not Found) response as per [RFC7641] + Section 3.2. + + Contrary to PUT iPATCH operations will explicitly update some + parameters, leaving others unmodified. + + => 0.07 iPATCH + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + { + "topic-type": "humidity", + "max-subscribers": 5 + } + + <= 2.04 Changed + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name" : "living-room-sensor", + "topic-data" : "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "humidity", + "expiration-date": "2023-05-28T23:59:59Z", + "max-subscribers": 5 + } + + Note that when a topic configuration changes through an iPATCH + request, 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. + +2.5.5. Deleting a topic-configuration + + A client can delete a topic by making a CoAP DELETE request on the + topic resource URI. + + On success, the server returns a 2.02 (Deleted) response. + + When a topic-configuration resource is deleted, the broker MUST also + delete the topic-data resource, unsubscribe all subscribers by + removing them from the list of observers and returning a final 4.04 + (Not Found) response as per section 3.2 of [RFC7641]. + + Example: + + => 0.04 DELETE + Uri-Path: ps + Uri-Path: h9392 + + <= 2.02 Deleted + +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 Observe option set to 0 + (register) to a topic-data resource. When resource state changes, + subscribers observing the resource [RFC7641] at that time will + receive a notification. + + A topic-data resource does not exist until some initial data has been + published to it. Before initial data publication, a GET request to + the topic-data resource URI results in 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). + There is no necessary URI pattern dependence between the URI where + the topic-data exists and the URI of the topic-configuration + resource. + +3.1. Topic Lifecycle + + When a topic is newly created, it is first placed by the broker 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 subscribe to 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 + + 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 data by means of a GET request without observe. 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. + +3.2. Topic-Data Interactions + + Interactions with the topic-data resource are covered in this + section. + +3.2.1. Publish + + A topic-configuration with a topic-data resource must have been + created in order to publish data to it (See Section 2.4.3) and be in + the half-created or fully-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 + Uri-Path: data + Uri-Path: 1bd0d6d + Content-Format: 110 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452122, + "v": 23.5 + } + + <= 2.01 Created + + Example of subsequent publication: + + => 0.03 PUT + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + Content-Format: 110 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452149, + "v": 22.5 + } + + <= 2.04 Updated + +3.2.2. Subscribe + + A client can subscribe to a topic-data by sending a CoAP GET request + with the Observe set to 0 to subscribe to resource updates. + [RFC7641]. + + On success, the server hosting the topic-data resource MUST return + 2.05 (Content) notifications with the data and the Observe Option. + Otherwise, if no Observe Option is present the client should assume + that the subscription was not successful. + + 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". The topic-data does not exist. + + If the 'max-subscribers' 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 + Uri-Path: data + Uri-Path: 1bd0d6d + Observe: 0 + + <= 2.05 Content + Content-Format: 110 + Observe: 10001 + Max-Age: 15 + + { + "n": "urn:dev:os:32473-123456", + "u": "Cel", + "t": 1696341182, + "v": 19.87 + } + + <= 2.05 Content + Content-Format: 110 + Observe: 10002 + Max-Age: 15 + + { + + "n": "urn:dev:os:32473-123456", + "u": "Cel", + "t": 1696340184, + "v": 21.87 + } + +3.2.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. Also on Section 3.6 of + [RFC7641] the client can simply "forget" the observation and the + server will remove it from the list of observers after the next + notification. + + As per [RFC7641] a server that transmits notifications mostly in non- + confirmable messages, but it 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. + +3.2.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 3.1. + + Example: + + => 0.04 DELETE + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + + <= 2.02 Deleted + +3.3. 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 3.1), the broker MUST + return a response code 4.04 (Not Found). + + Example: + + => 0.01 GET + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + + <= 2.05 Content + Content-Format: 110 + Max-Age: 15 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452122, + "v": 23.5 + } + +3.4. Rate Limiting + + The server hosting the topic-data may have to handle a potentially + large number of publishers and subscribers at the same time. This + means it could become overwhelmed if it receives too many + publications in a short period of time. + + In this situation, if a publisher 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 also stop publishing messages from + that publisher for the indicated time. + + When a publisher 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. + +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. + + +-----------------+-----------+-----------+------------+ + | Name | CBOR Key | CBOR Type | Reference | + |-----------------|-----------|-----------|------------| + | topic-name | TBD1 | tstr | [RFC-XXXX] | + | topic-data | TBD2 | tstr | [RFC-XXXX] | + | resource-type | TBD3 | tstr | [RFC-XXXX] | + | media-type | TBD4 | uint | [RFC-XXXX] | + | topic-type | TBD5 | tstr | [RFC-XXXX] | + | expiration-date | TBD6 | tstr | [RFC-XXXX] | + | max-subscribers | TBD7 | uint | [RFC-XXXX] | + | observer-check | TBD8 | uint | [RFC-XXXX] | + +-----------------+-----------+-----------+------------+ + + Figure 5: CoAP Pubsub Parameters + +5. Security Considerations + + The architecture presented in this document inherits the security + considerations from CoAP [RFC7252] and Observe [RFC7641], as well as + from Web Linking [RFC8288], Link-Format [RFC6690], and the CoRE + Resource Directory [RFC9176]. + + Communications between each client and the broker MUST be secured, + e.g., by using OSCORE [RFC8613] or DTLS [RFC9147]. Security + considerations for the used secure communication protocols apply too. + + The content published on a topic by a publisher client SHOULD be + protected end-to-end between the publisher and all the subscribers to + that topic. In such a case, it MUST be possible to assert source + authentication of the published data. This can be achieved at the + application layer, e.g., by using COSE [RFC9052], [RFC9053], + [RFC9338]. + + Access control of clients at the broker MAY be enforced for + performing discovery operation, and SHOULD be enforced in a fine- + grained fashion for operations related to the the creation, update, + and deletion of topic resources, as well as for operations on topic- + data resources such as publication on and subscription to topics. + This prevents rogue clients to, among other things, repeatedly create + topics at the broker or publish (large) contents, which may result in + Denial of Service against the broker and the active subscribers. + + Building on [I-D.ietf-ace-key-groupcomm], its application profile for + publish-subscribe communication with CoAP + [I-D.ietf-ace-pubsub-profile] provides a security model that can be + used in the architecture presented in this document, in order to + enable secure communication between the different parties as well as + secure, authorized operations of publishers and subscribers that + fulfill the requirements above. + + In particular, the application profile above relies on the ACE + framework for Authentication and Authorization in Constrained + Environments (ACE) [RFC9200] and defines a method to: authorize + publishers and subscribers to perform operations at the broker, with + fine-grained access control; authorize publishers and subscribers to + obtain the keying material required to take part to a topic managed + by the broker; protect published data end-to-end between its + publisher and all the subscribers to the targeted topic, ensuring + confidentiality, integrity, and source authentication of the + published content end-to-end. That approach can be extended to + enforce authorization and fine-grained access control for + administrator clients that are intended to create, update, and delete + topic configurations at the broker. + +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. + +6.1. Media Type + + IANA is requested to add the following Media-Type to the "Media + Types" registry [IANA.media-types]. + + +=============+=========================+=======================+ + | Name | Template | Reference | + +=============+=========================+=======================+ + | pubsub+cbor | application/pubsub+cbor | RFC XXXX, Section 6.1 | + +-------------+-------------------------+-----------------------+ + + Table 1: New Media Type application/pubsub+cbor + + Type name: application + Subtype name: pubsub+cbor + Required parameters: N/A + Optional parameters: N/A + Encoding considerations: binary (CBOR data item) + Security considerations: Section 5 of RFC XXXX + Interoperability considerations: none + Published specification: Section 6.1 of RFC XXXX + Applications that use this media type: This type is used by clients + that create, retrieve, and update topic configurations at servers + acting as a pub-sub broker. + Fragment identifier considerations: N/A + Person & email address to contact for further information: CoRE WG + mailing list (core@ietf.org), or IETF Applications and Real-Time + Area (art@ietf.org) + Intended usage: COMMON + Restrictions on usage: none + Author/Change controller: IETF + Provisional registration: no + +6.2. Content-Format + + IANA has added the following Content-Formats to the "CoAP + Content-Formats" sub-registry, within the "Constrained RESTful + Environments (CoRE) Parameters" Registry [IANA.core-parameters], as + follows: + + +=========================+================+======+===========+ + | Content Type | Content Coding | ID | Reference | + +=========================+================+======+===========+ + | application/pubsub+cbor | - | TBD9 | RFC XXXX | + +-------------------------+----------------+------+-----------+ + + Table 2: New Content-Format + + TBD9 is to be assigned from the space 256..999. + +6.3. CoAP Pubsub Parameters + + IANA is asked to register the following entries in the subregistry of + the "Constrained RESTful Environments (CoRE) Parameters" registry + group. + + This specification establishes the "Pubsub Topic Configuration + Parameters" IANA registry within the "Constrained RESTful + Environments (CoRE) Parameters" registry group. + + The columns of this registry are: + + * Name: This is a descriptive name that enables easier reference to + the item. The name MUST be unique. It is not used in the + encoding. + + * CBOR Key: This is the value used as CBOR key of the item. These + values MUST be unique. The value can be a positive integer, a + negative integer, or a text string. Different ranges of values + use different registration policies [RFC8126]. Integer values + from -256 to 255 as well as text strings of length 1 are + designated as "Standards Action With Expert Review". Integer + values from -65536 to -257 and from 256 to 65535, as well as text + strings of length 2 are designated as "Specification Required". + Integer values greater than 65535 as well as text strings of + length greater than 2 are designated as "Expert Review". Integer + values less than -65536 are marked as "Private Use". + + * CBOR Type: This contains the CBOR type of the item, or a pointer + to the registry that defines its type, when that depends on + another item. + + * Reference: This contains a pointer to the public specification for + the item. + + The registry is initially populated with the entries in Figure 5 of + Section 4. + +6.4. 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. + + Value: core.ps + Description: Publish-Subscribe Broker + Reference: [RFC-XXXX] + + Value: core.ps.coll + Description: Topic-collection resource of a Publish-Subscribe Broker + Reference: [RFC-XXXX] + + Value: core.ps.conf + Description: Topic-configuration resource of a Publish-Subscribe Broker + Reference: [RFC-XXXX] + + Value: core.ps.data + Description: Topic-data resource of a broker + Reference: [RFC-XXXX] + +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, Olaf + Bergmann and Oscar Novo for their valuable contributions and reviews. + +References + +Normative References + + [IANA.core-parameters] + IANA, "Constrained RESTful Environments (CoRE) + Parameters", + . + + [IANA.media-types] + IANA, "Media Types", + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., + and D. Orchard, "URI Template", RFC 6570, + DOI 10.17487/RFC6570, March 2012, + . + + [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link + Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, + . + + [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained + Application Protocol (CoAP)", RFC 7252, + DOI 10.17487/RFC7252, June 2014, + . + + [RFC7641] Hartke, K., "Observing Resources in the Constrained + Application Protocol (CoAP)", RFC 7641, + DOI 10.17487/RFC7641, September 2015, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8516] Keranen, A., ""Too Many Requests" Response Code for the + Constrained Application Protocol", RFC 8516, + DOI 10.17487/RFC8516, January 2019, + . + + [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, + "Object Security for Constrained RESTful Environments + (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, + . + + [RFC9176] Amsüss, C., Ed., Shelby, Z., Koster, M., Bormann, C., and + P. van der Stok, "Constrained RESTful Environments (CoRE) + Resource Directory", RFC 9176, DOI 10.17487/RFC9176, April + 2022, . + +Informative References + + [I-D.hartke-t2trg-coral-pubsub] + Hartke, K., "Publish/Subscribe over the Constrained + Application Protocol (CoAP) using the Constrained RESTful + Application Language (CoRAL)", Work in Progress, Internet- + Draft, draft-hartke-t2trg-coral-pubsub-01, 9 May 2020, + . + + [I-D.ietf-ace-key-groupcomm] + Palombini, F. and M. Tiloca, "Key Provisioning for Group + Communication using ACE", Work in Progress, Internet- + Draft, draft-ietf-ace-key-groupcomm-17, 6 October 2023, + . + + [I-D.ietf-ace-oscore-gm-admin] + Tiloca, M., Höglund, R., Van der Stok, P., and F. + Palombini, "Admin Interface for the OSCORE Group Manager", + Work in Progress, Internet-Draft, draft-ietf-ace-oscore- + gm-admin-10, 23 October 2023, + . + + [I-D.ietf-ace-pubsub-profile] + Palombini, F., Sengul, C., and M. Tiloca, "Publish- + Subscribe Profile for Authentication and Authorization for + Constrained Environments (ACE)", Work in Progress, + Internet-Draft, draft-ietf-ace-pubsub-profile-08, 23 + October 2023, . + + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + + [RFC8288] Nottingham, M., "Web Linking", RFC 8288, + DOI 10.17487/RFC8288, October 2017, + . + + [RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Structures and Process", STD 96, RFC 9052, + DOI 10.17487/RFC9052, August 2022, + . + + [RFC9053] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, + August 2022, . + + [RFC9147] Rescorla, E., Tschofenig, H., and N. Modadugu, "The + Datagram Transport Layer Security (DTLS) Protocol Version + 1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022, + . + + [RFC9200] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and + H. Tschofenig, "Authentication and Authorization for + Constrained Environments Using the OAuth 2.0 Framework + (ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, August 2022, + . + + [RFC9338] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Countersignatures", STD 96, RFC 9338, + DOI 10.17487/RFC9338, December 2022, + . + +Contributors + + Marco Tiloca + RISE AB + Email: marco.tiloca@ri.se + + + Marco offered comprehensive reviews and insightful guidance on the + recent iterations of this document. His contributions were + particularly notable in the Security Considerations section, among + others. + +Authors' Addresses + + Jaime Jimenez + Ericsson + Email: jaime@iki.fi + + + Michael Koster + Dogtiger Labs + Email: michaeljohnkoster@gmail.com + + + Ari Keranen + Ericsson + Email: ari.keranen@ericsson.com diff --git a/edit-fixes/index.html b/edit-fixes/index.html new file mode 100644 index 0000000..afb23c6 --- /dev/null +++ b/edit-fixes/index.html @@ -0,0 +1,45 @@ + + + + core-wg/coap-pubsub edit-fixes preview + + + + +

Editor's drafts for edit-fixes branch of core-wg/coap-pubsub

+ + + + + + +
A publish-subscribe architecture for the Constrained Application Protocol (CoAP)plain textsame as main
+ + + diff --git a/index.html b/index.html new file mode 100644 index 0000000..f33ad41 --- /dev/null +++ b/index.html @@ -0,0 +1,64 @@ + + + + core-wg/coap-pubsub main preview + + + + +

Editor's drafts for main branch of core-wg/coap-pubsub

+

View saved issues, or the latest GitHub issues and pull requests in the repo.

+ + + + + + + + +
A publish-subscribe architecture for the Constrained Application Protocol (CoAP)plain textdatatrackerdiff with last submission
+

Preview for branch edit-fixes

+ + + + + + +
A publish-subscribe architecture for the Constrained Application Protocol (CoAP)plain textsame as main
+

Preview for branch ps-rev

+ + + + + + +
A publish-subscribe architecture for the Constrained Application Protocol (CoAP)plain textdiff with main
+ + + diff --git a/issues.html b/issues.html new file mode 100644 index 0000000..7afaf98 --- /dev/null +++ b/issues.html @@ -0,0 +1,103 @@ + + + + + Issue Viewer + + + + +
+ + + records +
+
+ + + + + + + + + + + + + +
IDTitleStateAuthorAssigneeLabels
+
+
+
+

This page shows GitHub issues in a simple form.

+

The filter box above accepts a set of filters, each separated by space.

+
    +
+

You can /sort on id, recent, or closed.

+

Pressing enter saves the current search. + Pressing esc leaves the text input area.

+

Outside the search box

+

Clicking an issue title displays details for the issue including comments. + Pressing n or j moves to the next issue, + and p or k move to the previous one.

+

Pressing esc closes the issue view, ' focuses search, and + c clears the search.

+
+
+ + diff --git a/issues.js b/issues.js new file mode 100644 index 0000000..632b674 --- /dev/null +++ b/issues.js @@ -0,0 +1,1050 @@ +function setStatus(msg) { + let status = document.getElementById('status'); + status.innerText = msg; +} + +function date(s) { + const d = Date.parse(s); + if (isNaN(d)) { + return 0; + } + return d; +} + +function stateString(issue) { + let str; + if (issue.pr) { + switch (issue.state) { + case 'MERGED': + str = 'merged'; + break; + case 'CLOSED': + str = 'discarded'; + break; + default: + str = 'pr'; + break; + } + } else { + str = issue.state.toLowerCase(); + } + return str; +} + +function stateOrder(issue) { + return ['open', 'pr', 'closed', 'merged', 'discarded'].indexOf(stateString(issue)); +} + +var sortKey = 'id'; +var sortInvert = false; +function invert(x) { + return x * (sortInvert ? -1 : 1); +} +function sort(k) { + sortInvert = (k === sortKey) ? !sortInvert : false; + k = k || sortKey; + let message = k; + switch (k) { + case 'id': + subset.sort((x, y) => invert(x.number - y.number)); + message = 'ID'; + break; + case 'recent': + subset.sort((x, y) => invert(date(y.updatedAt) - date(x.updatedAt))); + message = 'last modified'; + break; + case 'closed': + subset.sort((x, y) => invert(date(y.closedAt) - date(x.closedAt))); + message = 'time of closure'; + break; + case 'title': + subset.sort((x, y) => invert(x.title.localeCompare(y.title))); + break; + case 'state': + subset.sort((x, y) => invert(stateOrder(x) - stateOrder(y))); + break; + case 'author': + subset.sort((x, y) => invert(x.author.localeCompare(y.author))); + break; + default: + setStatus('no idea how to sort like that'); + return; + } + setStatus(`sorted by ${message}${(sortInvert) ? ' (reversed)' : ''}`); + sortKey = k; + list(subset); +} + +function sortSetup() { + ['id', 'title', 'state', 'author'].forEach(k => { + let el = document.getElementById(`sort-${k}`); + el.addEventListener('click', _ => sort(k)); + el.style.cursor = 'pointer'; + el.title = `Sort by ${el.innerText}`; + }); +} + +var db; +async function get() { + db = null; + const response = await fetch('archive.json'); + if (Math.floor(response.status / 100) !== 2) { + throw new Error(`Error loading <${url}>: ${response.status}`); + } + db = await response.json(); + db.pulls.forEach(pr => pr.pr = true); + subset = db.all = db.issues.concat(db.pulls); + db.labels = db.labels.reduce((all, l) => { + all[l.name] = l; + return all; + }, {}); + sort(); + document.title = `${db.repo} Issues`; + console.log(`Loaded ${db.all.length} issues for ${db.repo}.`); + console.log('Raw data for issues can be found in:'); + console.log(' db.all = all issues and pull requests'); + console.log(' subset = just the subset of issues that are shown'); + console.log('format(subset[, formatter]) to dump the current subset to the console'); +} + +var issueFilters = { + assigned: { + args: ['string'], + h: 'assigned to this user', + f: login => issue => { + if (login === '') { + return issue.assignees.length > 0; + } else { + return issue.assignees.some(assignee => assignee === login); + } + }, + }, + + author: { + args: ['string'], + h: 'created by this user', + f: login => issue => issue.author === login, + }, + + commenter: { + args: ['string'], + h: 'commented on by this user', + f: login => issue => { + return issue.author === login || + issue.comments.some(comment => comment.author === login) || + (issue.reviews || []).some(review => review.author === login); + }, + }, + + reviewer: { + args: ['string'], + h: 'reviewed by this user', + f: login => issue => { + return issue.reviews && + issue.reviews.some(review => review.author === login); + }, + }, + + user: { + args: ['string'], + h: 'mentions this user', + f: login => issue => { + return issue.author === login || + issue.assignees.some(assignee => assignee === login) || + issue.comments.some(comment => comment.author === login) || + (issue.reviews || []).some(review => review.author === login); + }, + }, + + closed: { + args: [], + h: 'is closed', + f: issue => issue.state === 'CLOSED', + }, + + open: { + args: [], + h: 'is open', + f: issue => issue.state === 'OPEN', + }, + + merged: { + args: [], + h: 'a merged pull request', + f: issue => issue.state == 'MERGED', + }, + + discarded: { + args: [], + h: 'a discarded pull request', + f: issue => issue.pr && issue.state === 'CLOSED' + }, + + n: { + args: ['integer'], + h: 'issue by number', + f: i => issue => issue.number === i, + }, + + label: { + args: ['string'], + h: 'has a specific label', + f: name => issue => issue.labels.some(label => label === name), + }, + + labelled: { + args: [], + h: 'has any label', + f: issue => issue.labels.length > 0, + }, + + title: { + args: ['string'], + h: 'search title with a regular expression', + f: function(re) { + re = new RegExp(re); + return issue => issue.title.match(re); + } + }, + + body: { + args: ['string'], + h: 'search body with a regular expression', + f: function(re) { + re = new RegExp(re); + return issue => issue.body.match(re); + } + }, + + text: { + args: ['string'], + h: 'search title and body with a regular expression', + f: function(re) { + re = new RegExp(re); + return issue => issue.title.match(re) || issue.body.match(re); + } + }, + + pr: { + args: [], + h: 'is a pull request', + f: issue => issue.pr, + }, + + issue: { + args: [], + h: 'is a plain issue, i.e., not(pr)', + f: function(issue) { + return !issue.pr; + } + }, + + or: { + args: ['filter', '...filter'], + h: 'union', + f: (...filters) => x => filters.some(filter => filter(x)), + }, + + and: { + args: ['filter', '...filter'], + h: 'intersection', + f: (...filters) => x => filters.every(filter => filter(x)), + }, + + + xor: { + args: ['filter', '...filter'], + h: 'for the insane', + f: (...filters) => + x => filters.slice(1).reduce((a, filter) => a ^ filter(x), filters[0](x)), + }, + + not: { + args: ['filter'], + h: 'exclusion', + f: a => issue => !a(issue), + }, + + closed_since: { + args: ['date'], + h: 'issues closed since the date and time', + f: since => issue => date(issue.closedAt) >= since, + }, + + updated_since: { + args: ['date'], + h: 'issues updated since the date and time', + f: since => issue => date(issue.updatedAt) >= since, + } +}; + +class Parser { + constructor(s) { + this.str = s; + this.skipws(); + } + + skipws() { + this.str = this.str.trimLeft(); + } + + jump(idx) { + this.str = this.str.slice(idx); + this.skipws(); + } + + get next() { + return this.str.charAt(0); + } + + parseName() { + let m = this.str.match(/^[a-zA-Z](?:[a-zA-Z0-9_-]*[a-zA-Z0-9])?/); + if (!m) { + return; + } + + this.jump(m[0].length); + return m[0]; + } + + parseSeparator(separator) { + if (this.next !== separator) { + throw new Error(`Expecting separator ${separator}`); + } + this.jump(1); + } + + parseString() { + let end = -1; + for (let i = 0; i < this.str.length; ++i) { + let v = this.str.charAt(i); + if (v === ')' || v === ',') { + end = i; + break; + } + } + if (end < 0) { + throw new Error(`Unterminated string`); + } + let s = this.str.slice(0, end).trim(); + this.jump(end); + return s; + } + + parseDate() { + let str = this.parseString(); + let time = Date.parse(str); + if (isNaN(time)) { + throw new Error(`not a valid date: ${str}`); + } + return time; + } + + parseNumber() { + let m = this.str.match(/^\d+/); + if (!m) { + return; + } + this.jump(m[0].length); + return parseInt(m[0], 10); + } + + parseFilter() { + if (this.next === '-') { + this.parseSeparator('-'); + return issueFilters.not.f.call(null, this.parseFilter()); + } + let name = this.parseName(); + if (!name) { + let n = this.parseNumber(); + if (!isNaN(n)) { + return issueFilters.n.f.call(null, n); + } + return; + } + let f = issueFilters[name]; + if (!f) { + throw new Error(`Unknown filter: ${name}`); + } + if (f.args.length === 0) { + return f.f; + } + let args = []; + for (let i = 0; i < f.args.length; ++i) { + let arg = f.args[i]; + let ellipsis = arg.slice(0, 3) === '...'; + if (ellipsis) { + arg = arg.slice(3); + } + + this.parseSeparator((i === 0) ? '(' : ','); + if (arg === 'string') { + args.push(this.parseString()); + } else if (arg === 'date') { + args.push(this.parseDate()); + } else if (arg === 'integer') { + args.push(this.parseNumber()); + } else if (arg === 'filter') { + args.push(this.parseFilter()); + } else { + throw new Error(`Error in filter ${name} definition`); + } + if (ellipsis && this.next === ',') { + --i; + } + } + this.parseSeparator(')'); + return f.f.apply(null, args); + } +} + +var subset = []; +function filterIssues(str) { + subset = db.all; + let parser = new Parser(str); + let f = parser.parseFilter(); + while (f) { + subset = subset.filter(f); + f = parser.parseFilter(); + } +} + +var formatter = { + brief: x => `* ${x.title} (#${x.number})`, + md: x => `* [#${x.number}](${x.url}): ${x.title}`, +}; + +function format(set, f) { + return (set || subset).map(f || formatter.brief).join('\n'); +} + +var debounces = {}; +var debounceSlowdown = 100; +function measureSlowdown() { + let start = Date.now(); + window.setTimeout(_ => { + let diff = Date.now() - start; + if (diff > debounceSlowdown) { + console.log(`slowed to ${diff} ms`); + debounceSlowdown = Math.min(1000, diff + debounceSlowdown / 2); + } + }, 0); +} +function debounce(f) { + let r = now => { + measureSlowdown(); + f(now); + }; + return e => { + if (debounces[f.name]) { + window.clearTimeout(debounces[f.name]); + delete debounces[f.name]; + } + if (e.key === 'Enter') { + r(true); + } else { + debounces[f.name] = window.setTimeout(_ => { + delete debounces[f.name]; + r(false) + }, 10 + debounceSlowdown); + } + } +} + +function cell(row, children, cellClass) { + let td = document.createElement('td'); + if (cellClass) { + td.className = cellClass; + } + if (Array.isArray(children)) { + children.forEach(c => { + td.appendChild(c); + td.appendChild(document.createTextNode(' ')); + }); + } else { + td.appendChild(children); + } + row.appendChild(td); +} + + +function loadAvatars(elements) { + elements.forEach(e => { + let avatar = new Image(16, 16); + avatar.addEventListener('load', _ => e.target.replaceWith(avatar)); + let user = e.target.dataset.user; + avatar.src = `https://github.com/${user}.png?size=16`; + }); +} +var intersection = new IntersectionObserver(loadAvatars, { rootMargin: '50px 0px 100px 0px' }); + +function author(x, click, userSearch) { + let user = x.author || x; + let sp = document.createElement('span'); + sp.classList.add('item', 'user'); + let ai = document.createElement('a'); + ai.href = `https://github.com/${user}`; + ai.className = 'avatar'; + let placeholder = document.createElement('span'); + placeholder.className = 'swatch'; + placeholder.innerText = '\uD83E\uDDD0'; + placeholder.dataset.user = user; + intersection.observe(placeholder); + ai.appendChild(placeholder); + sp.appendChild(ai); + + let au = document.createElement('a'); + au.href = `#${userSearch || 'user'}(${user})`; + au.innerText = user; + au.addEventListener('click', click); + sp.appendChild(au); + return sp; +} + +function issueState(issue, click) { + let st = document.createElement('span'); + st.classList.add('item', 'state'); + let a = document.createElement('a'); + a.innerText = stateString(issue); + a.href = `#${stateString(issue)}`; + if (click) { + a.addEventListener('click', click); + } + st.appendChild(a); + return st; +} + +function showBody(item) { + let div = document.createElement('div'); + div.className = 'body'; + let body = item.body.trim().replace(/\r\n?/g, '\n'); + + let list = null; + let el = null; + let pre = null; + function closeElement() { + if (el) { + if (list) { + list.appendChild(el); + } else { + div.appendChild(el); + } + } + el = null; + pre = null; + } + function closeBoth() { + closeElement(); + if (list) { + div.appendChild(list); + list = null; + } + } + function addText(t) { + if (pre) { + el.appendChild(document.createTextNode(t + '\n')); + return; + } + if (el.innerText !== '') { + el.appendChild(document.createElement('br')); + } + if (t !== '') { + el.appendChild(document.createTextNode(t)); + } + } + + body.split('\n').forEach(t => { + if (t.charAt(0) === ' ') { + t = t.substring(1); // This fixes lots of problems. + } + if (t.indexOf('```') === 0) { + let needNew = !el || !pre; + closeBoth(); + if (needNew) { + el = document.createElement('pre'); + pre = 'q'; + let language = t.substring(3).trim(); + if (language) { + el.dataset.language = language; + } + } + } else if (pre === 'q') { + addText(t); + } else if (!el && t.indexOf(' ') === 0) { + if (!pre) { + closeBoth(); + el = document.createElement('pre'); + pre = 's'; + } + addText(t.substring(3)); + } else if (t.trim() === '') { + closeElement(); + } else if (t.indexOf('# ') === 0) { + closeBoth(); + el = document.createElement('h2'); + addText(t.substring(2).trimLeft()); + closeElement(); + } else if (t.indexOf('## ') === 0) { + closeBoth(); + el = document.createElement('h3'); + addText(t.substring(3).trimLeft()); + closeElement(); + } else if (t.indexOf('### ') === 0) { + closeBoth(); + el = document.createElement('h4'); + addText(t.substring(4).trimLeft()); + closeElement(); + } else if (t.charAt(0) === '>') { + if (!el || el.tagName !== 'BLOCKQUOTE') { + closeElement(); + el = document.createElement('blockquote'); + } + addText(t.substring(1).trimLeft()); + } else if (t.indexOf('* ') === 0 || t.indexOf('- ') === 0) { + if (list && list.tagName !== 'UL') { + closeBoth(); + } else { + closeElement(); + } + if (!list) { + list = document.createElement('ul'); + } + el = document.createElement('li'); + addText(t.substring(2).trimLeft()); + } else if (t.match(/^(?:\(?\d+\)|\d+\.)/)) { + if (list && list.tagName !== 'OL') { + closeBoth(); + } else { + closeElement(); + } + if (!list) { + list = document.createElement('ol'); + } + el = document.createElement('li'); + let sep = t.match(/^(?:\(?\d+\)|\d+\.)/)[0].length; + addText(t.substring(sep).trimLeft()); + } else { + if (list && !el) { + div.appendChild(list); + list = null; + } + if (!el) { + el = document.createElement('p'); + } + addText(t); + } + }); + closeBoth(); + return div; +} + +function showDate(d, reference) { + let de = document.createElement('span'); + de.classList.add('item', 'date'); + const full = d.toISOString(); + const parts = full.split(/[TZ\.]/); + if (reference && parts[0] === reference.toISOString().split('T')[0]) { + de.innerText = parts[1]; + } else { + de.innerText = parts[0] + ' ' + parts[1]; + } + de.title = full; + return de; +} + +function narrow(e, extra) { + e.preventDefault(); + hideIssue(); + let cmd = document.getElementById('cmd'); + let v = `${cmd.value} ${extra}`; + cmd.value = v.trim(); + redraw(true); +} + +function narrowLabel(e) { + narrow(e, `label(${e.target.innerText})`); +} + +function narrowState(e) { + narrow(e, e.target.innerText); +} + +function narrowUser(userType) { + return function narrowUserInner(e) { + narrow(e, `${userType}(${e.target.innerText})`); + }; +} + +function showLabels(labels, click) { + return labels.map(label => { + let item = document.createElement('span'); + item.className = 'item'; + let sp = document.createElement('span'); + sp.className = 'swatch'; + item.appendChild(sp); + let a = document.createElement('a'); + a.innerText = label; + a.href = `#label(${label})`; + if (click) { + a.addEventListener('click', click); + } + if (db.labels.hasOwnProperty(label)) { + sp.style.backgroundColor = '#' + db.labels[label].color; + if (db.labels[label].description) { + item.title = db.labels[label].description; + } + } + item.appendChild(a); + return item; + }); +} + +// Make a fresh replacement element for the identified element. +function freshReplacement(id) { + let e = document.getElementById(id); + let r = document.createElement(e.tagName); + r.id = id; + e.replaceWith(r); + return r; +} + +var displayed = null; + +function show(index) { + if (index < 0 || index >= subset.length) { + hideIssue(); + return; + } + displayed = index; + const issue = subset[index]; + + document.getElementById('overlay').classList.add('active'); + let frame = freshReplacement('issue'); + frame.classList.add('active'); + + function showTitle() { + let title = document.createElement('h2'); + title.className = 'title'; + let number = document.createElement('a'); + number.className = 'number'; + number.href = issue.url; + number.innerText = `#${issue.number}`; + title.appendChild(number); + title.appendChild(document.createTextNode(': ')); + let name = document.createElement('a'); + name.href = issue.url; + name.innerText = issue.title; + title.appendChild(name); + return title; + } + + function showIssueLabels() { + let meta = document.createElement('div'); + meta.className = 'meta'; + showLabels(issue.labels, hideIssue).forEach(el => { + meta.appendChild(el); + meta.appendChild(document.createTextNode(' ')); + }); + return meta; + } + + function showIssueUsers() { + let meta = document.createElement('div'); + meta.className = 'meta'; + meta.appendChild(author(issue, hideIssue, 'author')); + if (issue.assignees && issue.assignees.length > 0) { + let arrow = document.createElement('span'); + arrow.innerText = ' \u279c'; + arrow.title = 'Assigned to'; + meta.appendChild(arrow); + issue.assignees.map(u => author(u, hideIssue, 'assigned')).forEach(el => { + meta.appendChild(document.createTextNode(' ')); + meta.appendChild(el); + }); + } + return meta; + } + + function showIssueDates() { + let meta = document.createElement('div'); + meta.className = 'meta'; + let created = new Date(issue.createdAt); + meta.appendChild(showDate(created)); + meta.appendChild(issueState(issue, hideIssue)); + if (issue.closedAt) { + meta.appendChild(showDate(new Date(issue.closedAt), created)); + } + return meta; + } + + let refdate = null; + function showComment(c) { + let row = document.createElement('tr'); + let cdate = new Date(c.createdAt); + cell(row, showDate(cdate, refdate), 'date'); + refdate = cdate; + cell(row, author(c, hideIssue, (c.commit) ? 'reviewer' : 'commenter'), 'user'); + + if (issue.pr) { + let icon = document.createElement('span'); + switch (c.state) { + case 'APPROVED': + icon.innerText = '\u2714'; + icon.title = 'Approved'; + break; + case 'CHANGES_REQUESTED': + icon.innerText = '\u2718'; + icon.title = 'Changes Requested'; + break; + default: + icon.innerText = '\uD83D\uDCAC'; + icon.title = 'Comment'; + break; + } + cell(row, icon); + } + + let body = showBody(c); + if (c.comments && c.comments.length > 0) { + let codeComments = document.createElement('div'); + codeComments.className = 'item'; + const s = (c.comments.length === 1) ? '' : 's'; + codeComments.innerText = `... ${c.comments.length} comment${s} on changes`; + body.appendChild(codeComments); + } + cell(row, body); + return row; + } + + frame.appendChild(showTitle()); + frame.appendChild(showIssueLabels()); + frame.appendChild(showIssueUsers()); + frame.appendChild(showIssueDates()); + frame.appendChild(showBody(issue)); + + let allcomments = (issue.comments || []).concat(issue.reviews || []); + allcomments.sort((a, b) => date(a.createdAt) - date(b.createdAt)); + let comments = document.createElement('table'); + comments.className = 'comments'; + allcomments.map(showComment).forEach(row => comments.appendChild(row)); + frame.appendChild(comments); + + frame.scroll(0, 0); + frame.focus(); +} + +function hideIssue() { + document.getElementById('help').classList.remove('active'); + document.getElementById('issue').classList.remove('active'); + document.getElementById('overlay').classList.remove('active'); + displayed = null; +} + +function step(n) { + if (displayed === null) { + if (n > 0) { + show(n - 1); + } else { + show(subset.length + n); + } + } else { + show(displayed + n); + } +} + +function makeRow(issue, index) { + function cellID() { + let a = document.createElement('a'); + a.innerText = issue.number; + a.href = issue.url; + a.onclick = e => { + e.preventDefault(); + show(index); + }; + return a; + } + + function cellTitle() { + let a = document.createElement('a'); + a.innerText = issue.title; + a.href = issue.url; + a.onclick = e => { + e.preventDefault(); + show(index); + }; + return a; + } + + let tr = document.createElement('tr'); + cell(tr, cellID(), 'id'); + cell(tr, cellTitle(), 'title'); + cell(tr, issueState(issue, narrowState), 'state'); + cell(tr, author(issue, narrowUser('author'), 'author'), 'user'); + cell(tr, (issue.assignees || []) + .map(u => author(u, narrowUser('assigned'), 'assigned')), 'assignees'); + cell(tr, showLabels(issue.labels, narrowLabel), 'labels'); + return tr; +} + +function list(issues) { + if (!issues) { + return; + } + + let body = freshReplacement('issuelist'); + body.innerHTML = ''; + issues.forEach((issue, index) => { + body.appendChild(makeRow(issue, index)); + }); +} + +var currentFilter = ''; +function filter(str, now) { + try { + filterIssues(str); + setStatus(`${subset.length} records selected`); + if (now) { + window.location.hash = str; + currentFilter = str; + } + } catch (e) { + if (now) { // Only show errors when someone hits enter. + setStatus(`Error: ${e.message}`); + console.log(e); + } + } +} + +function showHelp() { + setStatus('help shown'); + let h = document.getElementById('help'); + h.classList.add('active'); + h.scroll(0, 0); + h.focus(); + document.getElementById('overlay').classList.add('active'); +} + +function slashCmd(cmd) { + if (cmd[0] === 'help') { + document.getElementById('cmd').blur(); + showHelp(); + } else { + setStatus('unknown command: /' + cmd.join(' ')); + } +} + +function redraw(now) { + let cmd = document.getElementById('cmd'); + if (cmd.value.charAt(0) == '/') { + if (now) { + slashCmd(cmd.value.slice(1).split(' ').map(x => x.trim())); + cmd.value = currentFilter; + } + return; + } + + if (!db) { + if (now) { + showStatus('Still loading...'); + } + return; + } + + document.getElementById('help').classList.remove('active'); + filter(cmd.value, now); + list(subset); +} + +function generateHelp() { + let functionhelp = document.getElementById('functions'); + Object.keys(issueFilters).forEach(k => { + let li = document.createElement('li'); + let arglist = ''; + if (issueFilters[k].args.length > 0) { + arglist = '(' + issueFilters[k].args.map(x => '<' + x + '>').join(', ') + ')'; + } + let fn = document.createElement('tt'); + fn.innerText = k + arglist; + li.appendChild(fn); + let help = ''; + if (issueFilters[k].h) { + help = ' - ' + issueFilters[k].h; + } + li.appendChild(document.createTextNode(help)); + functionhelp.appendChild(li); + }); +} + +function addFileHelp() { + setStatus('error loading file'); + if (window.location.protocol !== 'file:') { + return; + } + let p = document.createElement('p'); + p.className = 'warning'; + p.innerHTML = 'Important: Browsers display files inconsistently.' + + ' You can work around this by running an HTTP server,' + + ' such as python3 -m http.server,' + + ' then view this file using that server.'; + document.getElementById('help').insertBefore(p, h.firstChild); +} + +function issueOverlaySetup() { + let overlay = document.getElementById('overlay'); + overlay.addEventListener('click', hideIssue); + window.addEventListener('keyup', e => { + if (e.target.id === 'cmd') { + if (e.key === 'Escape') { + e.preventDefault(); + e.target.blur(); + } + return; + } + if (e.key === 'Escape') { + e.preventDefault(); + hideIssue(); + } + }); + window.addEventListener('keypress', e => { + if (e.target.closest('input')) { + return; + } + if (e.key === 'p' || e.key === 'k') { + e.preventDefault(); + step(-1); + } else if (e.key === 'n' || e.key === 'j') { + e.preventDefault(); + step(1); + } else if (e.key === '?') { + e.preventDefault(); + showHelp(); + } else if (e.key === '\'') { + e.preventDefault(); + hideIssue(); + document.getElementById('cmd').focus(); + } else if (e.key === 'c') { + e.preventDefault(); + hideIssue(); + document.getElementById('cmd').value = ''; + redraw(true); + } + }) +} + +window.onload = () => { + let cmd = document.getElementById('cmd'); + let redrawHandler = debounce(redraw); + cmd.addEventListener('input', redrawHandler); + cmd.addEventListener('keypress', redrawHandler); + window.addEventListener('hashchange', e => { + cmd.value = decodeURIComponent(window.location.hash.substring(1)); + redrawHandler(e); + }); + if (window.location.hash) { + cmd.value = decodeURIComponent(window.location.hash.substring(1)); + } + sortSetup(); + generateHelp(); + issueOverlaySetup(); + get().then(redraw).catch(addFileHelp); +} diff --git a/ps-rev/draft-ietf-core-coap-pubsub.html b/ps-rev/draft-ietf-core-coap-pubsub.html new file mode 100644 index 0000000..7dbf8c9 --- /dev/null +++ b/ps-rev/draft-ietf-core-coap-pubsub.html @@ -0,0 +1,2804 @@ + + + + + + +A publish-subscribe architecture for the Constrained Application Protocol (CoAP) + + + + + + + + + + + + + + + + + + + + + + + + +
Internet-DraftA publish-subscribe architecture for theNovember 2023
Jimenez, et al.Expires 2 June 2024[Page]
+
+
+
+
Workgroup:
+
CoRE Working Group
+
Internet-Draft:
+
draft-ietf-core-coap-pubsub-latest
+
Published:
+
+ +
+
Intended Status:
+
Standards Track
+
Expires:
+
+
Authors:
+
+
+
J. Jimenez
+
Ericsson
+
+
+
M. Koster
+
Dogtiger Labs
+
+
+
A. Keranen
+
Ericsson
+
+
+
+
+

A publish-subscribe architecture for the Constrained Application Protocol (CoAP)

+
+

Abstract

+

This document describes a publish-subscribe architecture for the Constrained Application Protocol (CoAP), extending the capabilities of CoAP communications for supporting endpoints with long breaks in connectivity and/or up-time. CoAP clients publish on and subscribe to a topic via a corresponding topic resource at a CoAP server acting as broker.

+
+
+

+About This Document +

+

This note is to be removed before publishing as an RFC.

+

+ Status information for this document may be found at https://datatracker.ietf.org/doc/draft-ietf-core-coap-pubsub/.

+

+ Discussion of this document takes place on the + core Working Group mailing list (mailto:core@ietf.org), + which is archived at https://mailarchive.ietf.org/arch/browse/core/. + Subscribe at https://www.ietf.org/mailman/listinfo/core/.

+

Source for this draft and an issue tracker can be found at + https://github.com/core-wg/coap-pubsub.

+
+
+
+

+Status of This Memo +

+

+ This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79.

+

+ Internet-Drafts are working documents of the Internet Engineering Task + Force (IETF). Note that other groups may also distribute working + documents as Internet-Drafts. The list of current Internet-Drafts is + at https://datatracker.ietf.org/drafts/current/.

+

+ Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress."

+

+ This Internet-Draft will expire on 2 June 2024.

+
+
+ +
+
+ ▲

+Table of Contents +

+ +
+
+
+
+

+1. Introduction +

+

The Constrained Application Protocol (CoAP) [RFC7252] supports +machine-to-machine communication across networks of constrained +devices and constrained networks. CoAP uses a request/response model where clients make requests to servers in order to request actions on resources. Depending on the situation the same device may act either as a server, a client, or both.

+

One important class of constrained devices includes devices that are intended to run for years from a small battery, or by scavenging energy from their environment. These devices have limited up-time because they spend most of their time in a sleeping state with no network connectivity. Another important class of nodes are devices with limited reachability due to middle-boxes like Network Address Translators (NATs) and firewalls.

+

For these nodes, the client/server-oriented architecture of REST can be challenging when interactions are not initiated by the devices themselves. A publish/subscribe-oriented architecture where nodes exchange data via topics through a broker entity might fit these nodes better.

+

This document applies the idea of broker-based publish-subscribe to Constrained RESTful Environments using CoAP. It defines a broker that allows to create, discover subscribe and publish on topics.

+
+
+

+1.1. Terminology +

+

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL +NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", +"MAY", and "OPTIONAL" in this document are to be interpreted as +described in BCP 14 [RFC2119] [RFC8174] when, and only when, they +appear in all capitals, as shown here.

+

This specification requires readers to be familiar with all the terms and +concepts that are discussed in [RFC8288] and [RFC6690]. Readers +should also be familiar with the terms and concepts discussed in +[RFC7252], [RFC9176] and [RFC7641]. The URI template +format [RFC6570] is used to describe the REST API defined in +this specification.

+

This specification makes use of the following terminology:

+
+
publish-subscribe (pub/sub):
+
+

A message communication model where messages associated with specific topics are sent to a broker. Interested parties, i.e. subscribers, receive these topic-based messages from the broker without the original sender knowing the recipients. The broker handles matching and delivering these messages to the appropriate subscribers.

+
+
+
publishers and subscribers:
+
+

CoAP clients can act as publishers or as subscribers. Publishers send CoAP messages (publications) to the broker on specific topics. Subscribers have an ongoing observation relation (subscription) to a topic. Both roles operate without any mutual knowledge, guided by their respective topic interests.

+
+
+
topic collection:
+
+

A set of topic configurations. A topic collection is hosted as one collection resource at the broker, and its representation is the list of links to the topic resources corresponding to each topic configuration.

+
+
+
topic-configuration:
+
+

A set of information concerning a topic, including its configuration and other metadata. A topic configuration is hosted as one topic resource at the broker, and its representation is the set of configuration information concerning the topic. All the topic resources associated with the same topic collection share a common base URI, i.e., the URI of the collection resource. Throughout this document the word "topic" and "topic-configuration" can be used interchangeably.

+
+
+
topic-data resource:
+
+

A resource where clients can publish data and/or subscribe to data for a specific topic. The representation of the topic resource corresponding to such a topic also specifies the URI to the present topic-data resource.

+
+
+
broker:
+
+

A CoAP server that hosts one or more topic collections with their topic-configurations, and also topic-data resources. The broker is responsible for the store-and-forward of state update representations, for the topics for which it hosts the corresponding topic-data resources. 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.

+
+
+
+
+
+
+
+

+1.2. CoAP Publish-Subscribe Architecture +

+

Figure 1 shows a simple Publish/Subscribe architecture over CoAP.

+

Topics are created by the broker, but the initial configuration can be proposed by a client (e.g., a publisher or a dedicated administrator) over the RESTful interface of a corresponding topic resource hosted by the broker.

+

Publishers submit their data over the RESTful interface of a topic-data resource corresponding to the topic, which may be hosted by the broker. Subscribers to a topic are notified of new publications by using Observe [RFC7641] on the corresponding topic-data resource.

+

The broker is responsible for the store-and-forward of state update representations between CoAP clients. Subscribers observing a resource will receive notifications, the delivery of which is done on a best-effort basis.

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + CoAP + CoAP + CoAP + clients + server + clients + observe + publish + publisher + subscriber + ... + broker + ... + ... + ... + observe + publish + publisher + subscriber + + +
+
+
Figure 1: +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 3.2).

+

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

+

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

+
+
+
+
+

+1.3. Managing Topics +

+

Figure 2 shows the resources related to a Topic Collection that can be managed at the Broker.

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + topic + collection + resource + ... + topic + resources + + +
+
+
Figure 2: +Resources of a Broker +
+
+

The Broker exports one or more topic-collection resources, 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.

+

A topic-collection resource can have topic resources as its child resources, with resource type "core.ps.conf".

+
+
+
+
+
+
+

+2. Pub-Sub Topics +

+

The configuration side of a "publish/subscribe broker" consists of a collection of topics. These topics as well as the collection itself are exposed by a CoAP server as resources (see Figure 3). Each topic is associated with a topic configuration resource and a topic-data resource. The topic configuration resource is used by a client creating or administering a topic. The topic-data resource is used by the publishers and the subscribers to a topic.

+
+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + topic + collection + resource + ...... + ...... + ...... + topic + : + : + : + : + : + : + configuration + : + : + : + : + : + : + resource + : + _ + _ + : + : + _ + _ + : + : + _ + _ + : + .... + .... + .... + .... + .... + .... + .... + .... + .... + .... + .... + .... + : + _ + _ + : + : + _ + _ + : + ... + : + _ + _ + : + topic-data + : + : + : + : + : + : + resource + : + : + : + : + : + : + :.......: + :.......: + :.......: + \ + / + ... + \ + / + topic + 1 + topic + 2 + topic + n + + +
+
+
Figure 3: +Topic and topic-data resources of a topic +
+
+
+
+

+2.1. Collection Representation +

+

Each topic configuration is represented as a link, where the link target is the URI of the corresponding topic resource.

+

Publication and subscription to a topic occur at a link, where the link target is the URI of the corresponding topic-data resource. Such a link is specified by the topic-data entry within the topic resource (see Section 2.2.1).

+

A topic resource with a topic-data link can also be simply called "topic".

+

The list of links to the topic resources can be retrieved from the associated topic collection resource, and represented as a Link Format document [RFC6690]where each such link specifies the link target attribute 'rt' (Resource Type), with value "core.ps.conf" defined in this document.

+
+
+
+
+

+2.2. Topic-Configuration Representation +

+

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 4.

+
+
+

+2.2.1. Topic Properties +

+

The CBOR map includes the following configuration parameters, whose 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 topic names include human-readable strings (e.g., "room2"), UUIDs, or other values.

    +
    • +
  • +

    'topic-data': A required field (optional during creation) containing the URI of the topic-data resource for publishing/subscribing to this topic. It encodes the URI as a CBOR text string.

    +
    • +
  • +

    'resource-type': A required field used to indicate the resource type of the topic-data resource for the topic. It encodes the resource type as a CBOR text string. The value should be "core.ps.conf".

    +
    • +
+
    +
  • +

    'media-type': An optional field used to indicate the media type of the topic-data resource for the topic. It encodes the media type as a this information as the integer identifier of the CoAP content-format (e.g., value is "50" for "application/json").

    +
    • +
  • +

    'topic-type': An optional field used to indicate the attribute or property of the topic-data resource for the topic. It encodes the attribute as a CBOR text string. Example attributes include "temperature".

    +
    • +
  • +

    'expiration-date': An optional field used to indicate the expiration date of the topic. It encodes the expiration date as a CBOR text string. The value should be a date string in ISO 8601 format (e.g., "2023-03-31T23:59:59Z"). The broker can use this field to automatically remove topics that are no longer valid. If this field is not present, the topic will not expire automatically.

    +
    • +
  • +

    'max-subscribers': An optional field used to indicate the maximum number of simultaneous subscribers allowed for the topic. It encodes the maximum number as an unsigned CBOR integer. If this field is not present, there is no limit to the number of simultaneous subscribers allowed. The broker can use this field to limit the number of subscribers for the topic. The default value for this field has been set to 100 subscribers.

    +
    • +
  • +

    'observer-check': An optional field that controls the maximum number of seconds between two consecutive Observe notifications sent as Confirmable messages to each topic subscriber. Encoded as a CBOR unsigned integer greater than 0, it ensures subscribers who have lost interest and silently forgotten the observation do not remain indefinitely on the server's observer list. If another CoAP server hosts the topic-data resource, that server is responsible for applying the observer-check value. The default value for this field is 86400, as defined in [RFC7641], which corresponds to 24 hours.

    +
    • +
+
+
+
+
+
+
+

+2.3. Discovery +

+

A client can perform a discovery of: the broker; the topic collection resources and topic resources hosted by the broker; and the topic-data resources associated with those topic resources.

+
+
+

+2.3.1. Broker Discovery +

+

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

+

The following example shows an endpoint discovering a broker using the "core.ps" resource type over a multicast network. Brokers within the multicast scope will answer the query.

+
+
+=> 0.01 GET
+   Uri-Path: coap://[ff0x::fe]/.well-known/core
+   Resource-Type: core.ps
+
+<= 2.05 Content
+   Payload:
+   Content-Format: 40 (application/link-format)
+   <coap://mythinguri.com/broker/v1>; rt=core.ps
+
+
+
+
+
+
+

+2.3.2. Topic Collection Discovery +

+

A Broker SHOULD offer a topic discovery entry point to enable clients to find topics of interest. The resource entry point is the topic collection resource collecting the topic configurations for those topics (see Section 1.2.2 of [RFC6690]) and is identified by the resource type "core.ps.coll".

+

The specific resource path is left for implementations, examples in this document use the "/ps" path. The interactions with a topic collection are further defined in Section 2.4.

+

Since the representation of the topic collection resource includes the links to the associated topic resources, it is not required to locate those links under "/.well-known/core", also in order to limit the size of the Link Format document returned as result of the discovery.

+

Example:

+
+
+=> 0.01 GET
+   Uri-Path: .well-known/core
+   Resource-Type: core.ps.coll
+
+   <= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps1>;rt="core.ps.coll";ct=40,
+   </other/path>;rt="core.ps.coll";ct=40
+
+
+
+
+
+
+

+2.3.3. Topic-Configuration Discovery +

+

Each topic collection is associated with a group of topic resources, each detailing the configuration of its respective topic (refer to Section 2.2.1). Each topic resource is identified by the resource type "core.ps.conf".

+

Below is an example of discovery via /.well-known/core with rt=core.ps.conf that returns a list of topics, as the list of links to the corresponding topic resources.

+
+
+=> 0.01 GET
+   Uri-Path: .well-known/core
+   Resource-Type: core.ps.conf
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps1/h9392>;rt="core.ps.conf";ct=TBD,
+   </other/path/2e3570>;rt=core.ps.conf;ct=TBD
+
+
+
+
+
+
+

+2.3.4. Topic-Data Discovery +

+

Within a topic, there is the topic-data property containing the URI of the topic-data resource that a CoAP client can subscribe and publish to. Resources exposing resources of the topic-data type are expected to use the resource type 'core.ps.data'.

+

The topic-data contains the URI of the topic-data resource for publishing and subscribing. So retrieving the topic configuration will also provide the URL of the topic-data (see Section 2.5.1).

+

It is also possible to discover a list of topic-data resources by sending a request to the collection with with rt=core.ps.data resources as shown below.

+
+
+=> 0.01 GET
+   Uri-Path: /ps
+   Resource-Type: core.ps.data
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps/data/62e4f8d>; rt=core.ps.data; obs
+
+
+
+
+
+
+
+
+

+2.4. Topic Collection Interactions +

+

These are the interactions that can happen directly with a specific topic collection.

+
+
+

+2.4.1. Retrieving all topic-configurations +

+

A client can request a collection of the topics present in the broker by making a GET request to the collection URI.

+

On success, the server returns a 2.05 (Content) response, specifying the list of links to topic resources associated with this topic collection (see Section 2.2).

+

Depending on its granted permissions, a client MAY retrieve a different list of links, corresponding to the topics that the client is authorized to access.

+

Example:

+
+
+=> 0.01 GET
+   Uri-Path: ps
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps/h9392>;rt="core.ps.conf",
+   </ps/2e3570>; rt="core.ps.conf"
+
+
+
+
+
+
+

+2.4.2. Getting topic-configurations by Properties +

+

A client can filter a collection of topics by submitting the +representation of a topic filter (see Section 2.5.2) in a FETCH request to the topic collection URI.

+

On success, the server returns a 2.05 (Content) response with a +representation of a list of topics in the collection (see + Section 2.3.3) that match the filter in CoRE link format [RFC6690].

+

Upon success, the server responds with a 2.05 (Content), providing a list of links to topic resources associated with this topic collection that match the request's filter criteria (refer to Section 2.3.3). A positive match happens only when each request parameter is present with the indicated value in the topic resource representation.

+

Example:

+
+
+=> 0.05 FETCH
+   Uri-Path: ps
+   Content-Format: TBD (application/pubsub+cbor)
+
+   {
+     "resource-type": "core.ps.conf",
+     "topic-type": "temperature"
+   }
+
+<= 2.05 Content
+   Content-Format: 40 (application/link-format)
+   </ps/2e3570>;rt="core.ps.conf"
+
+
+
+
+
+
+

+2.4.3. Creating a Topic +

+

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

+

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 Location-Path of the new topic and the current representation of the topic resource. The response payload includes a CBOR map with key-value pairs. The response must include the required topic properties (see Section 2.2.1), namely: "topic-name", "resource-type" and "topic-data". It may also include a number of optional properties too.

+

If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker MUST respond with a 4.03 (Forbidden) error. The response MUST have Content-Format set to "application/core-pubsub+cbor".

+

The broker MUST issue a 4.00 (Bad Request) error if a received parameter is invalid, unrecognized, or if the topic-name is already in use or otherwise invalid.

+
+
+=> 0.02 POST
+   Uri-Path: ps
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   TBD (this should be a CBOR map with the mandatory parameters)
+   {
+     "topic-name": "living-room-sensor",
+     "resource-type": "core.ps.conf"
+   }
+
+<= 2.01 Created
+   Location-Path: ps/h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   TBD (this should be a CBOR map)
+   {
+     "topic-name": "living-room-sensor",
+     "topic-data": "ps/data/1bd0d6d",
+     "resource-type": "core.ps.conf"
+   }
+
+
+
+
+
+
+
+
+

+2.5. Topic-Configuration Interactions +

+

These are the interactions that can happen at the topic resource level.

+
+
+

+2.5.1. Getting a topic-configuration +

+

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 partial representation of the topic resource, as specified in Section 2.2. The partial representation includes only the configuration parameters such that they are present and have the same value in both the current topic configuration as well as in the FETCH request.

+

If requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker 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 4.

+

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

+
+
+=> 0.01 GET
+   Uri-Path: ps
+   Uri-Path: h9392
+
+<= 2.05 Content
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   {
+      "topic-name" : "living-room-sensor",
+      "topic-data" : "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "temperature",
+      "expiration-date": "2023-04-00T23:59:59Z",
+      "max-subscribers": 100
+   }
+
+
+
+
+
+
+
+

+2.5.2. Getting part of a topic-configuration +

+

A client can read the configuration of a topic by making a FETCH request to the topic resource URI with a filter for specific parameters. This is done in order to retrieve part of the current topic resource.

+

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 requirements are defined for the client to create the topic as requested and the broker does not successfully assess that those requirements are met, then the broker 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 4.

+

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

+

Example:

+
+
+=> 0.05 FETCH
+   Uri-Path: ps
+   Uri-Path: h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   {
+     "conf-filter": ["topic-data", "media-type"]
+   }
+
+<= 2.05 Content
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+   {
+     "topic-data": "ps/data/1bd0d6d",
+     "media-type": "application/senml-cbor"
+   }
+
+
+
+
+
+
+
+

+2.5.3. Updating the topic-configuration +

+

A client can update a topic's configuration by submitting the updated topic representation in a PUT request to the topic URI. However, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker.

+

On success, the topic configuration is overwritten and server returns a 2.04 (Changed) response and the current full resource representation. The broker may chose not to overwrite parameters that are not explicitly modified in the request.

+

Note that updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Updating the "topic-data" may happen also after it being deleted, as described on {delete-topic-data}, this will in turn create a new "topic-data" path for that topic configuration.

+

Similarly, decreasing max-subscribers will also cause that some subscribers get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per [RFC7641] Section 3.2.

+

Please note that when using PUT the topic configuration is being overwritten, thus some of the optional parameters (e.g., "max-subscribers", "observer-check") not included in the PUT message will be reset to their default values.

+

Example:

+
+
+=> 0.03 PUT
+   Uri-Path: ps
+   Uri-Path: h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   {
+      "topic-name": "living-room-sensor",
+      "topic-data": "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "temperature",
+      "expiration-date": "2023-04-28T23:59:59Z",
+   }
+
+<= 2.04 Changed
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   TBD (this should be a CBOR map)
+   {
+      "topic-name": "living-room-sensor",
+      "topic-data": "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "temperature",
+      "expiration-date": "2023-04-28T23:59:59Z",
+      "max-subscribers": 100,
+      "observer-check": 86400
+   }
+
+
+

Note that 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.

    +
    • +
  • +

    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.

    +
    • +
+
+
+
+
+

+2.5.4. Updating the topic-configuration with iPATCH +

+

A client can partially update a topic's configuration by submitting a partial topic representation in an iPATCH request to the topic URI. The iPATCH request allows for updating only specific fields of the topic configuration while leaving the others unchanged. As with the PUT method, the parameters "topic-name", "topic-data", and "resource-type" are immutable post-creation, and any request attempting to change them will be deemed invalid by the broker.

+

On success, the server returns a 2.04 (Changed) response and the current full resource representation. The broker only updates parameters that are explicitly mentioned in the request.

+

As with the PUT method, updating the "topic-data" path will automatically cancel all existing observations on it and thus will unsubscribe all subscribers. Decreasing max-subscribers will also cause some subscribers to get unsubscribed. Unsubscribed endpoints SHOULD receive a final 4.04 (Not Found) response as per [RFC7641] Section 3.2.

+

Contrary to PUT iPATCH operations will explicitly update some parameters, leaving others unmodified.

+
+
+=> 0.07 iPATCH
+   Uri-Path: ps
+   Uri-Path: h9392
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   {
+      "topic-type": "humidity",
+      "max-subscribers": 5
+   }
+
+<= 2.04 Changed
+   Content-Format: TBD2 (application/core-pubsub+cbor)
+
+   TBD (this should be a CBOR map)
+   {
+      "topic-name" : "living-room-sensor",
+      "topic-data" : "ps/data/1bd0d6d",
+      "resource-type": "core.ps.conf",
+      "media-type": "application/senml-cbor",
+      "topic-type": "humidity",
+      "expiration-date": "2023-05-28T23:59:59Z",
+      "max-subscribers": 5
+   }
+
+
+

Note that when a topic configuration changes through an iPATCH request, 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.

+
+
+
+
+

+2.5.5. Deleting a topic-configuration +

+

A client can delete a topic by making a CoAP DELETE request on the topic resource URI.

+

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

+

When a topic-configuration resource is deleted, the broker MUST also delete the topic-data resource, unsubscribe all subscribers by removing them from the list of observers and returning a final 4.04 (Not Found) response as per section 3.2 of [RFC7641].

+

Example:

+
+
+=> 0.04 DELETE
+   Uri-Path: ps
+   Uri-Path: h9392
+
+<= 2.02 Deleted
+
+
+
+
+
+
+
+
+
+
+

+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 Observe option set to 0 (register) to a topic-data resource. When resource state changes, subscribers observing the resource [RFC7641] at that time will receive a notification.

+

A topic-data resource does not exist until some initial data has been published to it. Before initial data publication, a GET request to the topic-data resource URI results in 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). There is no necessary URI pattern dependence between the URI where the topic-data exists and the URI of the topic-configuration resource.

+
+
+

+3.1. Topic Lifecycle +

+

When a topic is newly created, it is first placed by the broker 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 subscribe to 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 + + +
+
+
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 data by means of a GET request without observe. 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.

+
+
+
+
+

+3.2. Topic-Data Interactions +

+

Interactions with the topic-data resource are covered in this section.

+
+
+

+3.2.1. Publish +

+

A topic-configuration with a topic-data resource must have been created in order to publish data to it (See Section 2.4.3) and be in the half-created or fully-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
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+   Content-Format: 110
+
+   {
+      "n": "coap://dev1.example.com/temperature",
+      "u": "Cel",
+      "t": 1621452122,
+      "v": 23.5
+   }
+
+<= 2.01 Created
+
+
+

Example of subsequent publication:

+
+
+=> 0.03 PUT
+   Uri-Path: ps
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+   Content-Format: 110
+
+   {
+      "n": "coap://dev1.example.com/temperature",
+      "u": "Cel",
+      "t": 1621452149,
+      "v": 22.5
+   }
+
+<= 2.04 Updated
+
+
+
+
+
+
+

+3.2.2. Subscribe +

+

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

+

On success, the server hosting the topic-data resource MUST return 2.05 (Content) notifications with the data and the Observe Option. Otherwise, if no Observe Option is present the client should assume that the subscription was not successful.

+

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". The topic-data does not exist.

+
+
+
+

If the 'max-subscribers' 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
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+   Observe: 0
+
+<= 2.05 Content
+   Content-Format: 110
+   Observe: 10001
+   Max-Age: 15
+
+  {
+    "n": "urn:dev:os:32473-123456",
+    "u": "Cel",
+    "t": 1696341182,
+    "v": 19.87
+  }
+
+<= 2.05 Content
+   Content-Format: 110
+   Observe: 10002
+   Max-Age: 15
+
+  {
+
+    "n": "urn:dev:os:32473-123456",
+    "u": "Cel",
+    "t": 1696340184,
+    "v": 21.87
+  }
+
+
+
+
+
+
+

+3.2.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. Also on Section 3.6 of [RFC7641] the client can simply "forget" the observation and the server will remove it from the list of observers after the next notification.

+

As per [RFC7641] a server that transmits notifications mostly in non-confirmable messages, but it 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.

+
+
+
+
+

+3.2.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 3.1.

+

Example:

+
+
+=> 0.04 DELETE
+   Uri-Path: ps
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+
+<= 2.02 Deleted
+
+
+
+
+
+
+
+
+

+3.3. 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 3.1), the broker MUST return a response code 4.04 (Not Found).

+

Example:

+
+
+=> 0.01 GET
+   Uri-Path: ps
+   Uri-Path: data
+   Uri-Path: 1bd0d6d
+
+<= 2.05 Content
+   Content-Format: 110
+   Max-Age: 15
+
+   {
+      "n": "coap://dev1.example.com/temperature",
+      "u": "Cel",
+      "t": 1621452122,
+      "v": 23.5
+   }
+
+
+
+
+
+
+

+3.4. Rate Limiting +

+

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

+

In this situation, if a publisher 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 also stop publishing messages from that publisher for the indicated time.

+

When a publisher 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.

+
+
+
+
+
+
+

+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.

+
+
+
+
++-----------------+-----------+-----------+------------+
+| Name            | CBOR Key  | CBOR Type | Reference  |
+|-----------------|-----------|-----------|------------|
+| topic-name      | TBD1      | tstr      | [RFC-XXXX] |
+| topic-data      | TBD2      | tstr      | [RFC-XXXX] |
+| resource-type   | TBD3      | tstr      | [RFC-XXXX] |
+| media-type      | TBD4      | uint      | [RFC-XXXX] |
+| topic-type      | TBD5      | tstr      | [RFC-XXXX] |
+| expiration-date | TBD6      | tstr      | [RFC-XXXX] |
+| max-subscribers | TBD7      | uint      | [RFC-XXXX] |
+| observer-check  | TBD8      | uint      | [RFC-XXXX] |
++-----------------+-----------+-----------+------------+
+
+
+
Figure 5: +CoAP Pubsub Parameters +
+
+
+
+
+
+

+5. Security Considerations +

+

The architecture presented in this document inherits the security considerations from CoAP [RFC7252] and Observe [RFC7641], as well as from Web Linking [RFC8288], Link-Format [RFC6690], and the CoRE Resource Directory [RFC9176].

+

Communications between each client and the broker MUST be secured, e.g., by using OSCORE [RFC8613] or DTLS [RFC9147]. Security considerations for the used secure communication protocols apply too.

+

The content published on a topic by a publisher client SHOULD be protected end-to-end between the publisher and all the subscribers to that topic. In such a case, it MUST be possible to assert source authentication of the published data. This can be achieved at the application layer, e.g., by using COSE [RFC9052], [RFC9053], [RFC9338].

+

Access control of clients at the broker MAY be enforced for performing discovery operation, and SHOULD be enforced in a fine-grained fashion for operations related to the the creation, update, and deletion of topic resources, as well as for operations on topic-data resources such as publication on and subscription to topics. This prevents rogue clients to, among other things, repeatedly create topics at the broker or publish (large) contents, which may result in Denial of Service against the broker and the active subscribers.

+

Building on [I-D.ietf-ace-key-groupcomm], its application profile for publish-subscribe communication with CoAP [I-D.ietf-ace-pubsub-profile] provides a security model that can be used in the architecture presented in this document, in order to enable secure communication between the different parties as well as secure, authorized operations of publishers and subscribers that fulfill the requirements above.

+

In particular, the application profile above relies on the ACE framework for Authentication and Authorization in Constrained Environments (ACE) [RFC9200] and defines a method to: authorize publishers and subscribers to perform operations at the broker, with fine-grained access control; authorize publishers and subscribers to obtain the keying material required to take part to a topic managed by the broker; protect published data end-to-end between its publisher and all the subscribers to the targeted topic, ensuring confidentiality, integrity, and source authentication of the published content end-to-end. That approach can be extended to enforce authorization and fine-grained access control for administrator clients that are intended to create, update, and delete topic configurations at the broker.

+
+
+
+
+

+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.

+
+
+

+6.1. Media Type +

+

IANA is requested to add the following Media-Type to the "Media Types" +registry [IANA.media-types].

+
+ + + + + + + + + + + + + + + + +
+Table 1: +New Media Type application/pubsub+cbor +
NameTemplateReference
pubsub+cborapplication/pubsub+cborRFC XXXX, Section 6.1 +
+
+
+
Type name:
+
+

application

+
+
+
Subtype name:
+
+

pubsub+cbor

+
+
+
Required parameters:
+
+

N/A

+
+
+
Optional parameters:
+
+

N/A

+
+
+
Encoding considerations:
+
+

binary (CBOR data item)

+
+
+
Security considerations:
+
+

Section 5 of RFC XXXX

+
+
+
Interoperability considerations:
+
+

none

+
+
+
Published specification:
+
+

Section 6.1 of RFC XXXX

+
+
+
Applications that use this media type:
+
+

This type is used by clients that create, retrieve, and update topic configurations at servers acting as a pub-sub broker.

+
+
+
Fragment identifier considerations:
+
+

N/A

+
+
+
Person & email address to contact for further information:
+
+

CoRE WG mailing list (core@ietf.org), +or IETF Applications and Real-Time Area (art@ietf.org)

+
+
+
Intended usage:
+
+

COMMON

+
+
+
Restrictions on usage:
+
+

none

+
+
+
Author/Change controller:
+
+

IETF

+
+
+
Provisional registration:
+
+

no

+
+
+
+
+
+
+
+

+6.2. Content-Format +

+

IANA has added the following Content-Formats to the +"CoAP Content-Formats" +sub-registry, within the "Constrained RESTful Environments (CoRE) +Parameters" Registry [IANA.core-parameters], as follows:

+ + + + + + + + + + + + + + + + + + +
+Table 2: +New Content-Format +
Content TypeContent CodingIDReference
application/pubsub+cbor-TBD9RFC XXXX
+

TBD9 is to be assigned from the space 256..999.

+
+
+
+
+

+6.3. CoAP Pubsub Parameters +

+

IANA is asked to register the following entries in the subregistry of the "Constrained RESTful Environments (CoRE) Parameters" registry group.

+

This specification establishes the "Pubsub Topic Configuration Parameters" IANA registry within the "Constrained RESTful Environments (CoRE) +Parameters" registry group.

+

The columns of this registry are:

+
    +
  • +

    Name: This is a descriptive name that enables easier reference to the item. The name MUST be unique. It is not used in the encoding.

    +
    • +
  • +

    CBOR Key: This is the value used as CBOR key of the item. These values MUST be unique. The value can be a positive integer, a negative integer, or a text string. Different ranges of values use different registration policies [RFC8126]. Integer values from -256 to 255 as well as text strings of length 1 are designated as "Standards Action With Expert Review". Integer values from -65536 to -257 and from 256 to 65535, as well as text strings of length 2 are designated as "Specification Required". Integer values greater than 65535 as well as text strings of length greater than 2 are designated as "Expert Review". Integer values less than -65536 are marked as "Private Use".

    +
    • +
  • +

    CBOR Type: This contains the CBOR type of the item, or a pointer to the registry that defines its type, when that depends on another item.

    +
    • +
  • +

    Reference: This contains a pointer to the public specification for the item.

    +
    • +
+

The registry is initially populated with the entries in Figure 5 of Section 4.

+
+
+
+
+

+6.4. 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.

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

+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, Olaf Bergmann and Oscar Novo for their valuable contributions and reviews.

+
+
+
+

+References +

+
+
+

+Normative References +

+
+
[IANA.core-parameters]
+
+IANA, "Constrained RESTful Environments (CoRE) Parameters", <http://www.iana.org/assignments/core-parameters>.
+
+
[IANA.media-types]
+
+IANA, "Media Types", <http://www.iana.org/assignments/media-types>.
+
+
[RFC2119]
+
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
+
+
[RFC6570]
+
+Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, DOI 10.17487/RFC6570, , <https://www.rfc-editor.org/rfc/rfc6570>.
+
+
[RFC6690]
+
+Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, , <https://www.rfc-editor.org/rfc/rfc6690>.
+
+
[RFC7252]
+
+Shelby, Z., Hartke, K., and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, , <https://www.rfc-editor.org/rfc/rfc7252>.
+
+
[RFC7641]
+
+Hartke, K., "Observing Resources in the Constrained Application Protocol (CoAP)", RFC 7641, DOI 10.17487/RFC7641, , <https://www.rfc-editor.org/rfc/rfc7641>.
+
+
[RFC8174]
+
+Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
+
+
[RFC8516]
+
+Keranen, A., ""Too Many Requests" Response Code for the Constrained Application Protocol", RFC 8516, DOI 10.17487/RFC8516, , <https://www.rfc-editor.org/rfc/rfc8516>.
+
+
[RFC8613]
+
+Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security for Constrained RESTful Environments (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, , <https://www.rfc-editor.org/rfc/rfc8613>.
+
+
[RFC9176]
+
+Amsüss, C., Ed., Shelby, Z., Koster, M., Bormann, C., and P. van der Stok, "Constrained RESTful Environments (CoRE) Resource Directory", RFC 9176, DOI 10.17487/RFC9176, , <https://www.rfc-editor.org/rfc/rfc9176>.
+
+
+
+
+
+
+

+Informative References +

+
+
[I-D.hartke-t2trg-coral-pubsub]
+
+Hartke, K., "Publish/Subscribe over the Constrained Application Protocol (CoAP) using the Constrained RESTful Application Language (CoRAL)", Work in Progress, Internet-Draft, draft-hartke-t2trg-coral-pubsub-01, , <https://datatracker.ietf.org/doc/html/draft-hartke-t2trg-coral-pubsub-01>.
+
+
[I-D.ietf-ace-key-groupcomm]
+
+Palombini, F. and M. Tiloca, "Key Provisioning for Group Communication using ACE", Work in Progress, Internet-Draft, draft-ietf-ace-key-groupcomm-17, , <https://datatracker.ietf.org/doc/html/draft-ietf-ace-key-groupcomm-17>.
+
+
[I-D.ietf-ace-oscore-gm-admin]
+
+Tiloca, M., Höglund, R., Van der Stok, P., and F. Palombini, "Admin Interface for the OSCORE Group Manager", Work in Progress, Internet-Draft, draft-ietf-ace-oscore-gm-admin-10, , <https://datatracker.ietf.org/doc/html/draft-ietf-ace-oscore-gm-admin-10>.
+
+
[I-D.ietf-ace-pubsub-profile]
+
+Palombini, F., Sengul, C., and M. Tiloca, "Publish-Subscribe Profile for Authentication and Authorization for Constrained Environments (ACE)", Work in Progress, Internet-Draft, draft-ietf-ace-pubsub-profile-08, , <https://datatracker.ietf.org/doc/html/draft-ietf-ace-pubsub-profile-08>.
+
+
[RFC8126]
+
+Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, , <https://www.rfc-editor.org/rfc/rfc8126>.
+
+
[RFC8288]
+
+Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, , <https://www.rfc-editor.org/rfc/rfc8288>.
+
+
[RFC9052]
+
+Schaad, J., "CBOR Object Signing and Encryption (COSE): Structures and Process", STD 96, RFC 9052, DOI 10.17487/RFC9052, , <https://www.rfc-editor.org/rfc/rfc9052>.
+
+
[RFC9053]
+
+Schaad, J., "CBOR Object Signing and Encryption (COSE): Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, , <https://www.rfc-editor.org/rfc/rfc9053>.
+
+
[RFC9147]
+
+Rescorla, E., Tschofenig, H., and N. Modadugu, "The Datagram Transport Layer Security (DTLS) Protocol Version 1.3", RFC 9147, DOI 10.17487/RFC9147, , <https://www.rfc-editor.org/rfc/rfc9147>.
+
+
[RFC9200]
+
+Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and H. Tschofenig, "Authentication and Authorization for Constrained Environments Using the OAuth 2.0 Framework (ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, , <https://www.rfc-editor.org/rfc/rfc9200>.
+
+
[RFC9338]
+
+Schaad, J., "CBOR Object Signing and Encryption (COSE): Countersignatures", STD 96, RFC 9338, DOI 10.17487/RFC9338, , <https://www.rfc-editor.org/rfc/rfc9338>.
+
+
+
+
+
+
+
+

+Contributors +

+
+
Marco Tiloca
+
RISE AB
+ +
+

Marco offered comprehensive reviews and insightful guidance on the recent iterations of this document. His contributions were particularly notable in the Security Considerations section, among others.

+
+
+
+
+

+Authors' Addresses +

+
+
Jaime Jimenez
+
Ericsson
+ +
+
+
Michael Koster
+
Dogtiger Labs
+ +
+
+
Ari Keranen
+
Ericsson
+ +
+
+
+ + + diff --git a/ps-rev/draft-ietf-core-coap-pubsub.txt b/ps-rev/draft-ietf-core-coap-pubsub.txt new file mode 100644 index 0000000..6092a30 --- /dev/null +++ b/ps-rev/draft-ietf-core-coap-pubsub.txt @@ -0,0 +1,1485 @@ + + + + +CoRE Working Group J. Jimenez +Internet-Draft Ericsson +Intended status: Standards Track M. Koster +Expires: 2 June 2024 Dogtiger Labs + A. Keranen + Ericsson + 30 November 2023 + + + A publish-subscribe architecture for the Constrained Application + Protocol (CoAP) + draft-ietf-core-coap-pubsub-latest + +Abstract + + This document describes a publish-subscribe architecture for the + Constrained Application Protocol (CoAP), extending the capabilities + of CoAP communications for supporting endpoints with long breaks in + connectivity and/or up-time. CoAP clients publish on and subscribe + to a topic via a corresponding topic resource at a CoAP server acting + as broker. + +About This Document + + This note is to be removed before publishing as an RFC. + + Status information for this document may be found at + https://datatracker.ietf.org/doc/draft-ietf-core-coap-pubsub/. + + Discussion of this document takes place on the core Working Group + mailing list (mailto:core@ietf.org), which is archived at + https://mailarchive.ietf.org/arch/browse/core/. Subscribe at + https://www.ietf.org/mailman/listinfo/core/. + + Source for this draft and an issue tracker can be found at + https://github.com/core-wg/coap-pubsub. + +Status of This Memo + + This Internet-Draft is submitted in full conformance with the + provisions of BCP 78 and BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF). Note that other groups may also distribute + working documents as Internet-Drafts. The list of current Internet- + Drafts is at https://datatracker.ietf.org/drafts/current/. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + This Internet-Draft will expire on 2 June 2024. + +Copyright Notice + + Copyright (c) 2023 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents (https://trustee.ietf.org/ + license-info) in effect on the date of publication of this document. + Please review these documents carefully, as they describe your rights + and restrictions with respect to this document. Code Components + extracted from this document must include Revised BSD License text as + described in Section 4.e of the Trust Legal Provisions and are + provided without warranty as described in the Revised BSD License. + +Table of Contents + + 1. Introduction + 1.1. Terminology + 1.2. CoAP Publish-Subscribe Architecture + 1.3. Managing Topics + 2. Pub-Sub Topics + 2.1. Collection Representation + 2.2. Topic-Configuration Representation + 2.2.1. Topic Properties + 2.3. Discovery + 2.3.1. Broker Discovery + 2.3.2. Topic Collection Discovery + 2.3.3. Topic-Configuration Discovery + 2.3.4. Topic-Data Discovery + 2.4. Topic Collection Interactions + 2.4.1. Retrieving all topic-configurations + 2.4.2. Getting topic-configurations by Properties + 2.4.3. Creating a Topic + 2.5. Topic-Configuration Interactions + 2.5.1. Getting a topic-configuration + 2.5.2. Getting part of a topic-configuration + 2.5.3. Updating the topic-configuration + 2.5.4. Updating the topic-configuration with iPATCH + 2.5.5. Deleting a topic-configuration + 3. Publish and Subscribe + 3.1. Topic Lifecycle + 3.2. Topic-Data Interactions + 3.2.1. Publish + 3.2.2. Subscribe + 3.2.3. Unsubscribe + 3.2.4. Delete topic-data + 3.3. Read latest data + 3.4. Rate Limiting + 4. CoAP Pubsub Parameters + 5. Security Considerations + 6. IANA Considerations + 6.1. Media Type + 6.2. Content-Format + 6.3. CoAP Pubsub Parameters + 6.4. Resource Types + Acknowledgements + References + Normative References + Informative References + Contributors + Authors' Addresses + +1. Introduction + + The Constrained Application Protocol (CoAP) [RFC7252] supports + machine-to-machine communication across networks of constrained + devices and constrained networks. CoAP uses a request/response model + where clients make requests to servers in order to request actions on + resources. Depending on the situation the same device may act either + as a server, a client, or both. + + One important class of constrained devices includes devices that are + intended to run for years from a small battery, or by scavenging + energy from their environment. These devices have limited up-time + because they spend most of their time in a sleeping state with no + network connectivity. Another important class of nodes are devices + with limited reachability due to middle-boxes like Network Address + Translators (NATs) and firewalls. + + For these nodes, the client/server-oriented architecture of REST can + be challenging when interactions are not initiated by the devices + themselves. A publish/subscribe-oriented architecture where nodes + exchange data via topics through a broker entity might fit these + nodes better. + + This document applies the idea of broker-based publish-subscribe to + Constrained RESTful Environments using CoAP. It defines a broker + that allows to create, discover subscribe and publish on topics. + +1.1. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in + BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + + This specification requires readers to be familiar with all the terms + and concepts that are discussed in [RFC8288] and [RFC6690]. Readers + should also be familiar with the terms and concepts discussed in + [RFC7252], [RFC9176] and [RFC7641]. The URI template format + [RFC6570] is used to describe the REST API defined in this + specification. + + This specification makes use of the following terminology: + + publish-subscribe (pub/sub): + A message communication model where messages associated with + specific topics are sent to a broker. Interested parties, i.e. + subscribers, receive these topic-based messages from the broker + without the original sender knowing the recipients. The broker + handles matching and delivering these messages to the appropriate + subscribers. + + publishers and subscribers: + CoAP clients can act as publishers or as subscribers. Publishers + send CoAP messages (publications) to the broker on specific + topics. Subscribers have an ongoing observation relation + (subscription) to a topic. Both roles operate without any mutual + knowledge, guided by their respective topic interests. + + topic collection: + A set of topic configurations. A topic collection is hosted as + one collection resource at the broker, and its representation is + the list of links to the topic resources corresponding to each + topic configuration. + + topic-configuration: + A set of information concerning a topic, including its + configuration and other metadata. A topic configuration is hosted + as one topic resource at the broker, and its representation is the + set of configuration information concerning the topic. All the + topic resources associated with the same topic collection share a + common base URI, i.e., the URI of the collection resource. + Throughout this document the word "topic" and "topic- + configuration" can be used interchangeably. + + topic-data resource: + A resource where clients can publish data and/or subscribe to data + for a specific topic. The representation of the topic resource + corresponding to such a topic also specifies the URI to the + present topic-data resource. + + broker: + A CoAP server that hosts one or more topic collections with their + topic-configurations, and also topic-data resources. The broker + is responsible for the store-and-forward of state update + representations, for the topics for which it hosts the + corresponding topic-data resources. 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. + +1.2. CoAP Publish-Subscribe Architecture + + Figure 1 shows a simple Publish/Subscribe architecture over CoAP. + + Topics are created by the broker, but the initial configuration can + be proposed by a client (e.g., a publisher or a dedicated + administrator) over the RESTful interface of a corresponding topic + resource hosted by the broker. + + Publishers submit their data over the RESTful interface of a topic- + data resource corresponding to the topic, which may be hosted by the + broker. Subscribers to a topic are notified of new publications by + using Observe [RFC7641] on the corresponding topic-data resource. + + The broker is responsible for the store-and-forward of state update + representations between CoAP clients. Subscribers observing a + resource will receive notifications, the delivery of which is done on + a best-effort basis. + + CoAP CoAP CoAP + clients server clients + .-----------. .----------. observe .------------. + | | publish | |<----------+ | + | publisher +--------->+ +---------->| subscriber | + | | | +---------->| | + '-----------' | | '------------' + ... | broker | ... + ... | | ... + .-----------. | | observe .------------. + | | publish | |<----------+ | + | publisher +--------->| +---------->| subscriber | + | | | +---------->| | + '-----------' '----------' '------------' + + Figure 1: 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 3.2). + + Topic-configuration interactions are discovery, create, read + configuration, update configuration, and delete configuration. These + operations handle the management of the topics. + + Topic-data interactions are publish, subscribe, unsubscribe, read, + and delete. These operations are oriented on how data is transferred + from a publisher to a subscriber. + +1.3. Managing Topics + + Figure 2 shows the resources related to a Topic Collection that can + be managed at the Broker. + + ___ + topic / \ + collection \___/ + resource \ + \____________________ + \___ \___ \___ + / \ / \ ... / \ topic resources + \___/ \___/ \___/ + + Figure 2: Resources of a Broker + + The Broker exports one or more topic-collection resources, 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. + + A topic-collection resource can have topic resources as its child + resources, with resource type "core.ps.conf". + +2. Pub-Sub Topics + + The configuration side of a "publish/subscribe broker" consists of a + collection of topics. These topics as well as the collection itself + are exposed by a CoAP server as resources (see Figure 3). Each topic + is associated with a topic configuration resource and a topic-data + resource. The topic configuration resource is used by a client + creating or administering a topic. The topic-data resource is used + by the publishers and the subscribers to a topic. + + ___ + topic / \ + collection \___/ + resource \ + \___________________________ + \ \ \ + \ ...... \ ...... \ ...... + topic : \___ : : \___ : : \___ : + configuration : / * \ : : / * \ : : / * \ : + resource : \_|_/ : : \_|_/ : : \_|_/ : + ....|.... ....|.... ....|.... + ....|.... ....|.... ....|.... + : _|_ : : _|_ : ... : _|_ : + topic-data : / \ : : / \ : : / \ : + resource : \___/ : : \___/ : : \___/ : + :.......: :.......: :.......: + \_________/\_________/ ... \_________/ + topic 1 topic 2 topic n + + Figure 3: Topic and topic-data resources of a topic + +2.1. Collection Representation + + Each topic configuration is represented as a link, where the link + target is the URI of the corresponding topic resource. + + Publication and subscription to a topic occur at a link, where the + link target is the URI of the corresponding topic-data resource. + Such a link is specified by the topic-data entry within the topic + resource (see Section 2.2.1). + + A topic resource with a topic-data link can also be simply called + "topic". + + The list of links to the topic resources can be retrieved from the + associated topic collection resource, and represented as a Link + Format document [RFC6690]where each such link specifies the link + target attribute 'rt' (Resource Type), with value "core.ps.conf" + defined in this document. + +2.2. Topic-Configuration Representation + + 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 4. + +2.2.1. Topic Properties + + The CBOR map includes the following configuration parameters, whose + 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 + topic names include human-readable strings (e.g., "room2"), UUIDs, + or other values. + + * 'topic-data': A required field (optional during creation) + containing the URI of the topic-data resource for publishing/ + subscribing to this topic. It encodes the URI as a CBOR text + string. + + * 'resource-type': A required field used to indicate the resource + type of the topic-data resource for the topic. It encodes the + resource type as a CBOR text string. The value should be + "core.ps.conf". + + * 'media-type': An optional field used to indicate the media type of + the topic-data resource for the topic. It encodes the media type + as a this information as the integer identifier of the CoAP + content-format (e.g., value is "50" for "application/json"). + + * 'topic-type': An optional field used to indicate the attribute or + property of the topic-data resource for the topic. It encodes the + attribute as a CBOR text string. Example attributes include + "temperature". + + * 'expiration-date': An optional field used to indicate the + expiration date of the topic. It encodes the expiration date as a + CBOR text string. The value should be a date string in ISO 8601 + format (e.g., "2023-03-31T23:59:59Z"). The broker can use this + field to automatically remove topics that are no longer valid. If + this field is not present, the topic will not expire + automatically. + + * 'max-subscribers': An optional field used to indicate the maximum + number of simultaneous subscribers allowed for the topic. It + encodes the maximum number as an unsigned CBOR integer. If this + field is not present, there is no limit to the number of + simultaneous subscribers allowed. The broker can use this field + to limit the number of subscribers for the topic. The default + value for this field has been set to 100 subscribers. + + * 'observer-check': An optional field that controls the maximum + number of seconds between two consecutive Observe notifications + sent as Confirmable messages to each topic subscriber. Encoded as + a CBOR unsigned integer greater than 0, it ensures subscribers who + have lost interest and silently forgotten the observation do not + remain indefinitely on the server's observer list. If another + CoAP server hosts the topic-data resource, that server is + responsible for applying the observer-check value. The default + value for this field is 86400, as defined in [RFC7641], which + corresponds to 24 hours. + +2.3. Discovery + + A client can perform a discovery of: the broker; the topic collection + resources and topic resources hosted by the broker; and the topic- + data resources associated with those topic resources. + +2.3.1. Broker Discovery + + CoAP clients MAY discover brokers by using CoAP Simple Discovery, via + multicast, through a Resource Directory (RD) [RFC9176] or by other + means specified in extensions to [RFC7252]. Brokers MAY register + with a RD by following the steps on Section 5 of [RFC9176] with the + resource type set to "core.ps" as defined in Section 6 of this + document. + + The following example shows an endpoint discovering a broker using + the "core.ps" resource type over a multicast network. Brokers within + the multicast scope will answer the query. + + => 0.01 GET + Uri-Path: coap://[ff0x::fe]/.well-known/core + Resource-Type: core.ps + + <= 2.05 Content + Payload: + Content-Format: 40 (application/link-format) + ; rt=core.ps + +2.3.2. Topic Collection Discovery + + A Broker SHOULD offer a topic discovery entry point to enable clients + to find topics of interest. The resource entry point is the topic + collection resource collecting the topic configurations for those + topics (see Section 1.2.2 of [RFC6690]) and is identified by the + resource type "core.ps.coll". + + The specific resource path is left for implementations, examples in + this document use the "/ps" path. The interactions with a topic + collection are further defined in Section 2.4. + + Since the representation of the topic collection resource includes + the links to the associated topic resources, it is not required to + locate those links under "/.well-known/core", also in order to limit + the size of the Link Format document returned as result of the + discovery. + + Example: + + => 0.01 GET + Uri-Path: .well-known/core + Resource-Type: core.ps.coll + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.coll";ct=40, + ;rt="core.ps.coll";ct=40 + +2.3.3. Topic-Configuration Discovery + + Each topic collection is associated with a group of topic resources, + each detailing the configuration of its respective topic (refer to + Section 2.2.1). Each topic resource is identified by the resource + type "core.ps.conf". + + Below is an example of discovery via /.well-known/core with + rt=core.ps.conf that returns a list of topics, as the list of links + to the corresponding topic resources. + + => 0.01 GET + Uri-Path: .well-known/core + Resource-Type: core.ps.conf + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf";ct=TBD, + ;rt=core.ps.conf;ct=TBD + +2.3.4. Topic-Data Discovery + + Within a topic, there is the topic-data property containing the URI + of the topic-data resource that a CoAP client can subscribe and + publish to. Resources exposing resources of the topic-data type are + expected to use the resource type 'core.ps.data'. + + The topic-data contains the URI of the topic-data resource for + publishing and subscribing. So retrieving the topic configuration + will also provide the URL of the topic-data (see Section 2.5.1). + + It is also possible to discover a list of topic-data resources by + sending a request to the collection with with rt=core.ps.data + resources as shown below. + + => 0.01 GET + Uri-Path: /ps + Resource-Type: core.ps.data + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ; rt=core.ps.data; obs + +2.4. Topic Collection Interactions + + These are the interactions that can happen directly with a specific + topic collection. + +2.4.1. Retrieving all topic-configurations + + A client can request a collection of the topics present in the broker + by making a GET request to the collection URI. + + On success, the server returns a 2.05 (Content) response, specifying + the list of links to topic resources associated with this topic + collection (see Section 2.2). + + Depending on its granted permissions, a client MAY retrieve a + different list of links, corresponding to the topics that the client + is authorized to access. + + Example: + + => 0.01 GET + Uri-Path: ps + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf", + ; rt="core.ps.conf" + +2.4.2. Getting topic-configurations by Properties + + A client can filter a collection of topics by submitting the + representation of a topic filter (see Section 2.5.2) in a FETCH + request to the topic collection URI. + + On success, the server returns a 2.05 (Content) response with a + representation of a list of topics in the collection (see + Section 2.3.3) that match the filter in CoRE link format [RFC6690]. + + Upon success, the server responds with a 2.05 (Content), providing a + list of links to topic resources associated with this topic + collection that match the request's filter criteria (refer to + Section 2.3.3). A positive match happens only when each request + parameter is present with the indicated value in the topic resource + representation. + + Example: + + => 0.05 FETCH + Uri-Path: ps + Content-Format: TBD (application/pubsub+cbor) + + { + "resource-type": "core.ps.conf", + "topic-type": "temperature" + } + + <= 2.05 Content + Content-Format: 40 (application/link-format) + ;rt="core.ps.conf" + +2.4.3. Creating a Topic + + A client can add a new topic-configurations to a collection of topics + by submitting an initial representation of the initial topic resource + (see Section 2.2) in a POST request to the topic collection URI. The + request MUST specify at least a subset of the properties in + Section 2.2.1, namely: topic-name and resource-type. + + 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 Location-Path of the new topic and the current representation of + the topic resource. The response payload includes a CBOR map with + key-value pairs. The response must include the required topic + properties (see Section 2.2.1), namely: "topic-name", "resource-type" + and "topic-data". It may also include a number of optional + properties too. + + If requirements are defined for the client to create the topic as + requested and the broker does not successfully assess that those + requirements are met, then the broker MUST respond with a 4.03 + (Forbidden) error. The response MUST have Content-Format set to + "application/core-pubsub+cbor". + + The broker MUST issue a 4.00 (Bad Request) error if a received + parameter is invalid, unrecognized, or if the topic-name is already + in use or otherwise invalid. + + => 0.02 POST + Uri-Path: ps + Content-Format: TBD2 (application/core-pubsub+cbor) + TBD (this should be a CBOR map with the mandatory parameters) + { + "topic-name": "living-room-sensor", + "resource-type": "core.ps.conf" + } + + <= 2.01 Created + Location-Path: ps/h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf" + } + +2.5. Topic-Configuration Interactions + + These are the interactions that can happen at the topic resource + level. + +2.5.1. Getting a topic-configuration + + 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 + partial representation of the topic resource, as specified in + Section 2.2. The partial representation includes only the + configuration parameters such that they are present and have the same + value in both the current topic configuration as well as in the FETCH + request. + + If requirements are defined for the client to create the topic as + requested and the broker does not successfully assess that those + requirements are met, then the broker 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 4. + + For example, below is a request on the topic "ps/h9392": + + => 0.01 GET + Uri-Path: ps + Uri-Path: h9392 + + <= 2.05 Content + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "topic-name" : "living-room-sensor", + "topic-data" : "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-00T23:59:59Z", + "max-subscribers": 100 + } + +2.5.2. Getting part of a topic-configuration + + A client can read the configuration of a topic by making a FETCH + request to the topic resource URI with a filter for specific + parameters. This is done in order to retrieve part of the current + topic resource. + + 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 requirements are defined for the client to create the topic as + requested and the broker does not successfully assess that those + requirements are met, then the broker 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 4. + + Both request and response MUST have Content-Format set to + "application/core-pubsub+cbor". + + Example: + + => 0.05 FETCH + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "conf-filter": ["topic-data", "media-type"] + } + + <= 2.05 Content + Content-Format: TBD2 (application/core-pubsub+cbor) + { + "topic-data": "ps/data/1bd0d6d", + "media-type": "application/senml-cbor" + } + +2.5.3. Updating the topic-configuration + + A client can update a topic's configuration by submitting the updated + topic representation in a PUT request to the topic URI. However, the + parameters "topic-name", "topic-data", and "resource-type" are + immutable post-creation, and any request attempting to change them + will be deemed invalid by the broker. + + On success, the topic configuration is overwritten and server returns + a 2.04 (Changed) response and the current full resource + representation. The broker may chose not to overwrite parameters + that are not explicitly modified in the request. + + Note that updating the "topic-data" path will automatically cancel + all existing observations on it and thus will unsubscribe all + subscribers. Updating the "topic-data" may happen also after it + being deleted, as described on {delete-topic-data}, this will in turn + create a new "topic-data" path for that topic configuration. + + Similarly, decreasing max-subscribers will also cause that some + subscribers get unsubscribed. Unsubscribed endpoints SHOULD receive + a final 4.04 (Not Found) response as per [RFC7641] Section 3.2. + + Please note that when using PUT the topic configuration is being + overwritten, thus some of the optional parameters (e.g., "max- + subscribers", "observer-check") not included in the PUT message will + be reset to their default values. + + Example: + + => 0.03 PUT + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-28T23:59:59Z", + } + + <= 2.04 Changed + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name": "living-room-sensor", + "topic-data": "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "temperature", + "expiration-date": "2023-04-28T23:59:59Z", + "max-subscribers": 100, + "observer-check": 86400 + } + + Note that 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. + + * 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. + +2.5.4. Updating the topic-configuration with iPATCH + + A client can partially update a topic's configuration by submitting a + partial topic representation in an iPATCH request to the topic URI. + The iPATCH request allows for updating only specific fields of the + topic configuration while leaving the others unchanged. As with the + PUT method, the parameters "topic-name", "topic-data", and "resource- + type" are immutable post-creation, and any request attempting to + change them will be deemed invalid by the broker. + + On success, the server returns a 2.04 (Changed) response and the + current full resource representation. The broker only updates + parameters that are explicitly mentioned in the request. + + As with the PUT method, updating the "topic-data" path will + automatically cancel all existing observations on it and thus will + unsubscribe all subscribers. Decreasing max-subscribers will also + cause some subscribers to get unsubscribed. Unsubscribed endpoints + SHOULD receive a final 4.04 (Not Found) response as per [RFC7641] + Section 3.2. + + Contrary to PUT iPATCH operations will explicitly update some + parameters, leaving others unmodified. + + => 0.07 iPATCH + Uri-Path: ps + Uri-Path: h9392 + Content-Format: TBD2 (application/core-pubsub+cbor) + + { + "topic-type": "humidity", + "max-subscribers": 5 + } + + <= 2.04 Changed + Content-Format: TBD2 (application/core-pubsub+cbor) + + TBD (this should be a CBOR map) + { + "topic-name" : "living-room-sensor", + "topic-data" : "ps/data/1bd0d6d", + "resource-type": "core.ps.conf", + "media-type": "application/senml-cbor", + "topic-type": "humidity", + "expiration-date": "2023-05-28T23:59:59Z", + "max-subscribers": 5 + } + + Note that when a topic configuration changes through an iPATCH + request, 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. + +2.5.5. Deleting a topic-configuration + + A client can delete a topic by making a CoAP DELETE request on the + topic resource URI. + + On success, the server returns a 2.02 (Deleted) response. + + When a topic-configuration resource is deleted, the broker MUST also + delete the topic-data resource, unsubscribe all subscribers by + removing them from the list of observers and returning a final 4.04 + (Not Found) response as per section 3.2 of [RFC7641]. + + Example: + + => 0.04 DELETE + Uri-Path: ps + Uri-Path: h9392 + + <= 2.02 Deleted + +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 Observe option set to 0 + (register) to a topic-data resource. When resource state changes, + subscribers observing the resource [RFC7641] at that time will + receive a notification. + + A topic-data resource does not exist until some initial data has been + published to it. Before initial data publication, a GET request to + the topic-data resource URI results in 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). + There is no necessary URI pattern dependence between the URI where + the topic-data exists and the URI of the topic-configuration + resource. + +3.1. Topic Lifecycle + + When a topic is newly created, it is first placed by the broker 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 subscribe to 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 + + 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 data by means of a GET request without observe. 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. + +3.2. Topic-Data Interactions + + Interactions with the topic-data resource are covered in this + section. + +3.2.1. Publish + + A topic-configuration with a topic-data resource must have been + created in order to publish data to it (See Section 2.4.3) and be in + the half-created or fully-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 + Uri-Path: data + Uri-Path: 1bd0d6d + Content-Format: 110 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452122, + "v": 23.5 + } + + <= 2.01 Created + + Example of subsequent publication: + + => 0.03 PUT + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + Content-Format: 110 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452149, + "v": 22.5 + } + + <= 2.04 Updated + +3.2.2. Subscribe + + A client can subscribe to a topic-data by sending a CoAP GET request + with the Observe set to 0 to subscribe to resource updates. + [RFC7641]. + + On success, the server hosting the topic-data resource MUST return + 2.05 (Content) notifications with the data and the Observe Option. + Otherwise, if no Observe Option is present the client should assume + that the subscription was not successful. + + 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". The topic-data does not exist. + + If the 'max-subscribers' 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 + Uri-Path: data + Uri-Path: 1bd0d6d + Observe: 0 + + <= 2.05 Content + Content-Format: 110 + Observe: 10001 + Max-Age: 15 + + { + "n": "urn:dev:os:32473-123456", + "u": "Cel", + "t": 1696341182, + "v": 19.87 + } + + <= 2.05 Content + Content-Format: 110 + Observe: 10002 + Max-Age: 15 + + { + + "n": "urn:dev:os:32473-123456", + "u": "Cel", + "t": 1696340184, + "v": 21.87 + } + +3.2.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. Also on Section 3.6 of + [RFC7641] the client can simply "forget" the observation and the + server will remove it from the list of observers after the next + notification. + + As per [RFC7641] a server that transmits notifications mostly in non- + confirmable messages, but it 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. + +3.2.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 3.1. + + Example: + + => 0.04 DELETE + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + + <= 2.02 Deleted + +3.3. 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 3.1), the broker MUST + return a response code 4.04 (Not Found). + + Example: + + => 0.01 GET + Uri-Path: ps + Uri-Path: data + Uri-Path: 1bd0d6d + + <= 2.05 Content + Content-Format: 110 + Max-Age: 15 + + { + "n": "coap://dev1.example.com/temperature", + "u": "Cel", + "t": 1621452122, + "v": 23.5 + } + +3.4. Rate Limiting + + The server hosting the topic-data may have to handle a potentially + large number of publishers and subscribers at the same time. This + means it could become overwhelmed if it receives too many + publications in a short period of time. + + In this situation, if a publisher 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 also stop publishing messages from + that publisher for the indicated time. + + When a publisher 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. + +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. + + +-----------------+-----------+-----------+------------+ + | Name | CBOR Key | CBOR Type | Reference | + |-----------------|-----------|-----------|------------| + | topic-name | TBD1 | tstr | [RFC-XXXX] | + | topic-data | TBD2 | tstr | [RFC-XXXX] | + | resource-type | TBD3 | tstr | [RFC-XXXX] | + | media-type | TBD4 | uint | [RFC-XXXX] | + | topic-type | TBD5 | tstr | [RFC-XXXX] | + | expiration-date | TBD6 | tstr | [RFC-XXXX] | + | max-subscribers | TBD7 | uint | [RFC-XXXX] | + | observer-check | TBD8 | uint | [RFC-XXXX] | + +-----------------+-----------+-----------+------------+ + + Figure 5: CoAP Pubsub Parameters + +5. Security Considerations + + The architecture presented in this document inherits the security + considerations from CoAP [RFC7252] and Observe [RFC7641], as well as + from Web Linking [RFC8288], Link-Format [RFC6690], and the CoRE + Resource Directory [RFC9176]. + + Communications between each client and the broker MUST be secured, + e.g., by using OSCORE [RFC8613] or DTLS [RFC9147]. Security + considerations for the used secure communication protocols apply too. + + The content published on a topic by a publisher client SHOULD be + protected end-to-end between the publisher and all the subscribers to + that topic. In such a case, it MUST be possible to assert source + authentication of the published data. This can be achieved at the + application layer, e.g., by using COSE [RFC9052], [RFC9053], + [RFC9338]. + + Access control of clients at the broker MAY be enforced for + performing discovery operation, and SHOULD be enforced in a fine- + grained fashion for operations related to the the creation, update, + and deletion of topic resources, as well as for operations on topic- + data resources such as publication on and subscription to topics. + This prevents rogue clients to, among other things, repeatedly create + topics at the broker or publish (large) contents, which may result in + Denial of Service against the broker and the active subscribers. + + Building on [I-D.ietf-ace-key-groupcomm], its application profile for + publish-subscribe communication with CoAP + [I-D.ietf-ace-pubsub-profile] provides a security model that can be + used in the architecture presented in this document, in order to + enable secure communication between the different parties as well as + secure, authorized operations of publishers and subscribers that + fulfill the requirements above. + + In particular, the application profile above relies on the ACE + framework for Authentication and Authorization in Constrained + Environments (ACE) [RFC9200] and defines a method to: authorize + publishers and subscribers to perform operations at the broker, with + fine-grained access control; authorize publishers and subscribers to + obtain the keying material required to take part to a topic managed + by the broker; protect published data end-to-end between its + publisher and all the subscribers to the targeted topic, ensuring + confidentiality, integrity, and source authentication of the + published content end-to-end. That approach can be extended to + enforce authorization and fine-grained access control for + administrator clients that are intended to create, update, and delete + topic configurations at the broker. + +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. + +6.1. Media Type + + IANA is requested to add the following Media-Type to the "Media + Types" registry [IANA.media-types]. + + +=============+=========================+=======================+ + | Name | Template | Reference | + +=============+=========================+=======================+ + | pubsub+cbor | application/pubsub+cbor | RFC XXXX, Section 6.1 | + +-------------+-------------------------+-----------------------+ + + Table 1: New Media Type application/pubsub+cbor + + Type name: application + Subtype name: pubsub+cbor + Required parameters: N/A + Optional parameters: N/A + Encoding considerations: binary (CBOR data item) + Security considerations: Section 5 of RFC XXXX + Interoperability considerations: none + Published specification: Section 6.1 of RFC XXXX + Applications that use this media type: This type is used by clients + that create, retrieve, and update topic configurations at servers + acting as a pub-sub broker. + Fragment identifier considerations: N/A + Person & email address to contact for further information: CoRE WG + mailing list (core@ietf.org), or IETF Applications and Real-Time + Area (art@ietf.org) + Intended usage: COMMON + Restrictions on usage: none + Author/Change controller: IETF + Provisional registration: no + +6.2. Content-Format + + IANA has added the following Content-Formats to the "CoAP + Content-Formats" sub-registry, within the "Constrained RESTful + Environments (CoRE) Parameters" Registry [IANA.core-parameters], as + follows: + + +=========================+================+======+===========+ + | Content Type | Content Coding | ID | Reference | + +=========================+================+======+===========+ + | application/pubsub+cbor | - | TBD9 | RFC XXXX | + +-------------------------+----------------+------+-----------+ + + Table 2: New Content-Format + + TBD9 is to be assigned from the space 256..999. + +6.3. CoAP Pubsub Parameters + + IANA is asked to register the following entries in the subregistry of + the "Constrained RESTful Environments (CoRE) Parameters" registry + group. + + This specification establishes the "Pubsub Topic Configuration + Parameters" IANA registry within the "Constrained RESTful + Environments (CoRE) Parameters" registry group. + + The columns of this registry are: + + * Name: This is a descriptive name that enables easier reference to + the item. The name MUST be unique. It is not used in the + encoding. + + * CBOR Key: This is the value used as CBOR key of the item. These + values MUST be unique. The value can be a positive integer, a + negative integer, or a text string. Different ranges of values + use different registration policies [RFC8126]. Integer values + from -256 to 255 as well as text strings of length 1 are + designated as "Standards Action With Expert Review". Integer + values from -65536 to -257 and from 256 to 65535, as well as text + strings of length 2 are designated as "Specification Required". + Integer values greater than 65535 as well as text strings of + length greater than 2 are designated as "Expert Review". Integer + values less than -65536 are marked as "Private Use". + + * CBOR Type: This contains the CBOR type of the item, or a pointer + to the registry that defines its type, when that depends on + another item. + + * Reference: This contains a pointer to the public specification for + the item. + + The registry is initially populated with the entries in Figure 5 of + Section 4. + +6.4. 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. + + Value: core.ps + Description: Publish-Subscribe Broker + Reference: [RFC-XXXX] + + Value: core.ps.coll + Description: Topic-collection resource of a Publish-Subscribe Broker + Reference: [RFC-XXXX] + + Value: core.ps.conf + Description: Topic-configuration resource of a Publish-Subscribe Broker + Reference: [RFC-XXXX] + + Value: core.ps.data + Description: Topic-data resource of a broker + Reference: [RFC-XXXX] + +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, Olaf + Bergmann and Oscar Novo for their valuable contributions and reviews. + +References + +Normative References + + [IANA.core-parameters] + IANA, "Constrained RESTful Environments (CoRE) + Parameters", + . + + [IANA.media-types] + IANA, "Media Types", + . + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., + and D. Orchard, "URI Template", RFC 6570, + DOI 10.17487/RFC6570, March 2012, + . + + [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link + Format", RFC 6690, DOI 10.17487/RFC6690, August 2012, + . + + [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained + Application Protocol (CoAP)", RFC 7252, + DOI 10.17487/RFC7252, June 2014, + . + + [RFC7641] Hartke, K., "Observing Resources in the Constrained + Application Protocol (CoAP)", RFC 7641, + DOI 10.17487/RFC7641, September 2015, + . + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, . + + [RFC8516] Keranen, A., ""Too Many Requests" Response Code for the + Constrained Application Protocol", RFC 8516, + DOI 10.17487/RFC8516, January 2019, + . + + [RFC8613] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, + "Object Security for Constrained RESTful Environments + (OSCORE)", RFC 8613, DOI 10.17487/RFC8613, July 2019, + . + + [RFC9176] Amsüss, C., Ed., Shelby, Z., Koster, M., Bormann, C., and + P. van der Stok, "Constrained RESTful Environments (CoRE) + Resource Directory", RFC 9176, DOI 10.17487/RFC9176, April + 2022, . + +Informative References + + [I-D.hartke-t2trg-coral-pubsub] + Hartke, K., "Publish/Subscribe over the Constrained + Application Protocol (CoAP) using the Constrained RESTful + Application Language (CoRAL)", Work in Progress, Internet- + Draft, draft-hartke-t2trg-coral-pubsub-01, 9 May 2020, + . + + [I-D.ietf-ace-key-groupcomm] + Palombini, F. and M. Tiloca, "Key Provisioning for Group + Communication using ACE", Work in Progress, Internet- + Draft, draft-ietf-ace-key-groupcomm-17, 6 October 2023, + . + + [I-D.ietf-ace-oscore-gm-admin] + Tiloca, M., Höglund, R., Van der Stok, P., and F. + Palombini, "Admin Interface for the OSCORE Group Manager", + Work in Progress, Internet-Draft, draft-ietf-ace-oscore- + gm-admin-10, 23 October 2023, + . + + [I-D.ietf-ace-pubsub-profile] + Palombini, F., Sengul, C., and M. Tiloca, "Publish- + Subscribe Profile for Authentication and Authorization for + Constrained Environments (ACE)", Work in Progress, + Internet-Draft, draft-ietf-ace-pubsub-profile-08, 23 + October 2023, . + + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + . + + [RFC8288] Nottingham, M., "Web Linking", RFC 8288, + DOI 10.17487/RFC8288, October 2017, + . + + [RFC9052] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Structures and Process", STD 96, RFC 9052, + DOI 10.17487/RFC9052, August 2022, + . + + [RFC9053] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Initial Algorithms", RFC 9053, DOI 10.17487/RFC9053, + August 2022, . + + [RFC9147] Rescorla, E., Tschofenig, H., and N. Modadugu, "The + Datagram Transport Layer Security (DTLS) Protocol Version + 1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022, + . + + [RFC9200] Seitz, L., Selander, G., Wahlstroem, E., Erdtman, S., and + H. Tschofenig, "Authentication and Authorization for + Constrained Environments Using the OAuth 2.0 Framework + (ACE-OAuth)", RFC 9200, DOI 10.17487/RFC9200, August 2022, + . + + [RFC9338] Schaad, J., "CBOR Object Signing and Encryption (COSE): + Countersignatures", STD 96, RFC 9338, + DOI 10.17487/RFC9338, December 2022, + . + +Contributors + + Marco Tiloca + RISE AB + Email: marco.tiloca@ri.se + + + Marco offered comprehensive reviews and insightful guidance on the + recent iterations of this document. His contributions were + particularly notable in the Security Considerations section, among + others. + +Authors' Addresses + + Jaime Jimenez + Ericsson + Email: jaime@iki.fi + + + Michael Koster + Dogtiger Labs + Email: michaeljohnkoster@gmail.com + + + Ari Keranen + Ericsson + Email: ari.keranen@ericsson.com diff --git a/ps-rev/index.html b/ps-rev/index.html new file mode 100644 index 0000000..bfb88eb --- /dev/null +++ b/ps-rev/index.html @@ -0,0 +1,45 @@ + + + + core-wg/coap-pubsub ps-rev preview + + + + +

Editor's drafts for ps-rev branch of core-wg/coap-pubsub

+ + + + + + +
A publish-subscribe architecture for the Constrained Application Protocol (CoAP)plain textsame as main
+ + +