idnits 2.17.1 draft-hartke-t2trg-coral-pubsub-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (May 9, 2020) is 1447 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-06) exists of draft-ietf-core-coral-03 == Outdated reference: A later version (-14) exists of draft-ietf-core-coap-pubsub-09 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Thing-to-Thing Research Group K. Hartke 3 Internet-Draft Ericsson 4 Intended status: Experimental May 9, 2020 5 Expires: November 10, 2020 7 Publish/Subscribe over the Constrained Application Protocol (CoAP) 8 using the Constrained RESTful Application Language (CoRAL) 9 draft-hartke-t2trg-coral-pubsub-01 11 Abstract 13 This document explores how the Constrained RESTful Application 14 Language (CoRAL) might be used for enabling publish/subscribe-style 15 communication over the Constrained Application Protocol (CoAP), which 16 allows CoAP nodes with long breaks in connectivity and/or up-time to 17 exchange data via a publish/subscribe broker. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on November 10, 2020. 36 Copyright Notice 38 Copyright (c) 2020 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (https://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . 2 54 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2.1. Brokers and Topics . . . . . . . . . . . . . . . . . . . 3 56 2.2. Publish and Subscribe . . . . . . . . . . . . . . . . . . 4 57 2.3. Notational Conventions . . . . . . . . . . . . . . . . . 5 58 3. Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3.1. Topic Creation and Configuration . . . . . . . . . . . . 5 60 3.1.1. Configuration Properties . . . . . . . . . . . . . . 6 61 3.1.2. Status Properties . . . . . . . . . . . . . . . . . . 6 62 3.1.3. Topic Configuration Representation . . . . . . . . . 6 63 3.2. Topic Discovery . . . . . . . . . . . . . . . . . . . . . 6 64 3.2.1. Topic List Representation . . . . . . . . . . . . . . 6 65 3.2.2. Filter Query Representation . . . . . . . . . . . . . 7 66 3.3. Interactions . . . . . . . . . . . . . . . . . . . . . . 7 67 3.3.1. Getting All Topics . . . . . . . . . . . . . . . . . 7 68 3.3.2. Getting Topics by Properties . . . . . . . . . . . . 7 69 3.3.3. Creating a Topic . . . . . . . . . . . . . . . . . . 8 70 3.3.4. Reading the Configuration of a Topic . . . . . . . . 8 71 3.3.5. Updating the Configuration of a Topic . . . . . . . . 9 72 3.3.6. Deleting a Topic . . . . . . . . . . . . . . . . . . 9 73 4. Publish/Subscribe . . . . . . . . . . . . . . . . . . . . . . 10 74 4.1. Topic Lifecycle . . . . . . . . . . . . . . . . . . . . . 10 75 4.2. Rate Limiting . . . . . . . . . . . . . . . . . . . . . . 11 76 4.3. Interactions . . . . . . . . . . . . . . . . . . . . . . 11 77 4.3.1. Publishing to a Topic . . . . . . . . . . . . . . . . 11 78 4.3.2. Subscribing to a Topic . . . . . . . . . . . . . . . 12 79 4.3.3. Unsubscribing from a Topic . . . . . . . . . . . . . 13 80 4.3.4. Getting the Latest Published Data . . . . . . . . . . 13 81 5. Security Considerations . . . . . . . . . . . . . . . . . . . 14 82 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 83 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 14 84 7.1. Normative References . . . . . . . . . . . . . . . . . . 14 85 7.2. Informative References . . . . . . . . . . . . . . . . . 15 86 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15 87 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 89 1. Preamble 91 This document explores how CoAP Publish/Subscribe Broker 92 [I-D.ietf-core-coap-pubsub] might look like if based on CoRAL 93 [I-D.ietf-core-coral]. The exploration is done in the style of a 94 self-contained specification rather than a description of changes. 96 2. Introduction 98 Constrained RESTful Environments (CoRE) realize the Representational 99 State Transfer (REST) architectural style [REST] in a suitable form 100 for constrained nodes (e.g., 8-bit microcontrollers with limited RAM 101 and ROM) and constrained networks [RFC7228]. CoRE technologies like 102 the Constrained Application Protocol (CoAP) [RFC7252] are aimed at 103 machine-to-machine (M2M) applications like smart energy and building 104 automation. 106 An important class of constrained nodes are devices that are intended 107 to run for years on a small battery or by scavenging energy from 108 their environment. These nodes have limited reachability, since they 109 spend most of their time in a sleeping state with no network 110 connectivity. Another important class of nodes are devices with 111 limited reachability due to middle-boxes like Network Address 112 Translators (NATs) and firewalls. 114 For these nodes, the client/server-oriented architecture of REST can 115 be challenging when interactions are not initiated by the devices 116 themselves. A publish/subscribe-oriented architecture where nodes 117 are separated by a broker and data is exchanged via topics might fit 118 these nodes better. 120 This document applies the idea of a "Publish/Subscribe Broker" to 121 Constrained RESTful Environments. The broker enables store-and- 122 forward data exchange between nodes, thereby facilitating the 123 communication of nodes with limited reachability, providing simple 124 many-to-many communication, and easing integration with other 125 publish/subscribe systems. 127 2.1. Brokers and Topics 129 In this specification, publishing and subscribing is facilitated by a 130 CoAP server, called the "publish/subscribe broker" (see Figure 1). 131 Publishers and subscribers are CoAP clients that interact with this 132 broker using a RESTful API. 134 CoAP CoAP CoAP 135 Clients Server Clients 136 ___________ __________ observe ____________ 137 | | publish | | .--------- | | 138 | Publisher | ---------> | | |--------> | Subscriber | 139 |___________| | | '--------> |____________| 140 . | | . 141 . | Broker | . 142 ___________ | | observe ____________ 143 | | publish | | .--------- | | 144 | Publisher | ---------> | | |--------> | Subscriber | 145 |___________| |__________| '--------> |____________| 147 Figure 1: Publish/Subscribe over CoAP 149 Data is forwarded from publishers to subscribers via "topics" at the 150 broker. This way, both publishers and subscribers do not need to 151 have any knowledge each other; they just have to share the topic 152 they're publishing and subscribing to. 154 Topics have to be created and configured before any data can be 155 published. These are managed by the broker. Clients may propose new 156 topics to be created; however, it is up to the broker to choose if 157 and how a topic is created. The broker also decides the URI of each 158 topic. 160 The creation, configuration, and discovery of topics at a broker is 161 specified in Section 3. 163 2.2. Publish and Subscribe 165 A simple publish/subscribe mechanism can be implemented over CoAP by 166 having publishers submit their data in PUT requests to a broker- 167 managed resource and letting subscribers observe this resource 168 [RFC7641]. 170 However, the requirements may not always be simple: When observing a 171 resource, notifications are sent on a best-effort basis. Subscribers 172 are notified of as many state changes as possible; however, when a 173 publisher is publishing faster than subscribers can be notified, 174 subscribers might not see every publication. If this is not desired, 175 an alternative mechanism needs to be be used. Such alternatives are 176 supported, but their specification is out of this document's scope. 178 The simple publish/subscribe mechanism is specified in Section 4. 180 2.3. Notational Conventions 182 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 183 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 184 "OPTIONAL" in this document are to be interpreted as described in BCP 185 14 [RFC2119] [RFC8174] when, and only when, they appear in all 186 capitals, as shown here. 188 3. Topics 190 The configuration side of a "publish/subscribe broker" consists of a 191 collection of topics. These topics as well as the collection itself 192 are exposed by a CoAP server as resources (see Figure 2). 194 ___ 195 Topic / \ 196 Collection \___/ 197 \ 198 \____________________ 199 \___ \___ \___ 200 Topics / \ / \ ... / \ 201 \___/ \___/ \___/ 203 Figure 2: Resources of a Publish-Subscribe Broker 205 3.1. Topic Creation and Configuration 207 Each topic has a topic configuration. A CoAP client can create a new 208 topic by submitting an initial configuration for the topic. It can 209 also read and update the configuration of existing topics and delete 210 them when they are no longer needed. 212 The configuration of a topic itself consists of a set of properties. 213 These fall into one of two categories: configuration properties and 214 status properties. Configuration properties can be set by a client 215 and describe the desired configuration of a topic. Status properties 216 are read-only, managed by the server, and provide information about 217 the actual status of a topic. 219 When a client submits a configuration to create a new topic or update 220 an existing topic, it can only submit configuration properties. When 221 a server returns the configuration of a topic, it returns both the 222 configuration properties and the status properties of the topic. 224 Every property has a type and a value. The type takes the form of an 225 IRI [RFC3987]. This IRI serves only as an identifier; it must not be 226 dereferenced by clients. The value can be either a Boolean value, an 227 integer, a floating-point number, a date/time value, a byte string, a 228 text string, or a resource reference in the form of a URI [RFC3986]. 230 3.1.1. Configuration Properties 232 The following configuration properties are defined: 234 TODO. 236 3.1.2. Status Properties 238 The following status properties are defined: 240 TODO. 242 3.1.3. Topic Configuration Representation 244 A topic configuration is represented as a CoRAL document 245 [I-D.ietf-core-coral] containing the configuration properties and 246 status properties of the topic as top-level elements. 248 Each property is represented as a link where the link relation type 249 is the property type and the link target is the property value. 251 3.2. Topic Discovery 253 Topics can be discovered by a client on the basis of configuration 254 properties and status properties. For example, a client could fetch 255 a list of all topics that have a property of type "foo" or that have 256 a property of type "bar" with the value 42. Alternatively, topics 257 can also be discovered simply by getting the full list of all topics. 259 3.2.1. Topic List Representation 261 A list of topics is represented as a CoRAL document 262 [I-D.ietf-core-coral] containing the topics in the list as top-level 263 elements. 265 Each topic is represented as a link where the link relation type is 266 and the link target is the topic 267 URI. This link can optionally contain (a subset of) the 268 configuration properties and status properties of the topic as nested 269 elements. 271 Each property is represented in the same way as in Section 3.1.3. 273 3.2.2. Filter Query Representation 275 TODO. 277 3.3. Interactions 279 3.3.1. Getting All Topics 281 A client can list a collection of topics by making a GET request to 282 the collection URI. 284 On success, the server returns a 2.05 (Content) response with a 285 representation of the list of all topics (see Section 3.2.1) in the 286 collection. 288 Example: 290 => 0.01 GET 291 Uri-Path: pubsub 292 Uri-Path: topics 294 <= 2.05 Content 295 Content-Format: 65536 297 item 298 item 299 item 301 3.3.2. Getting Topics by Properties 303 A client can filter a collection of topics by submitting the 304 representation of a topic filter (see Section 3.2.2) in a FETCH 305 request to the topic collection URI. 307 On success, the server returns a 2.05 (Content) response with a 308 representation of a list of topics in the collection (see 309 Section 3.2.1) that match the filter. 311 Example: 313 => 0.05 FETCH 314 Uri-Path: pubsub 315 Uri-Path: topics 316 Content-Format: TODO 318 TODO 320 <= 2.05 Content 321 Content-Format: 65536 323 item 324 item 325 item 327 3.3.3. Creating a Topic 329 A client can add a new topic to a collection of topics by submitting 330 a representation of the initial topic configuration (see 331 Section 3.1.3) in a POST request to the topic collection URI. 333 If client just wants all the default configuration properties, it can 334 simply submit an empty CoRAL document. 336 On success, the server returns a 2.01 (Created) response indicating 337 the topic URI of the new topic. 339 Example: 341 => 0.02 POST 342 Uri-Path: pubsub 343 Uri-Path: topics 344 Content-Format: 65536 346 foo "xyz" 347 bar 42 349 <= 2.01 Created 350 Location-Path: pubsub 351 Location-Path: topics 352 Location-Path: 1234 354 3.3.4. Reading the Configuration of a Topic 356 A client can read the configuration of a topic by making a GET 357 request to the topic URI. 359 On success, the server returns a 2.05 (Content) response with a 360 representation of the topic configuration (see Section 3.1.3). 362 Example: 364 => 0.01 GET 365 Uri-Path: pubsub 366 Uri-Path: topics 367 Uri-Path: 1234 369 <= 2.05 Content 370 Content-Format: 65536 371 Max-Age: 300 373 foo "xyz" 374 bar 42 376 3.3.5. Updating the Configuration of a Topic 378 A client can update the configuration of a topic by submitting the 379 representation of the updated topic configuration (see Section 3.1.3) 380 in a PUT request to the topic URI. Any existing properties in the 381 configuration are replaced by this update. 383 On success, the server returns a 2.04 (Updated) response. 385 Example: 387 => 0.03 PUT 388 Uri-Path: pubsub 389 Uri-Path: topics 390 Uri-Path: 1234 391 Content-Format: 65536 393 foo "abc" 395 <= 2.04 Updated 397 3.3.6. Deleting a Topic 399 A client can delete a topic by making a DELETE request on the topic 400 URI. 402 On success, the server returns a 2.02 (Deleted) response. 404 Any subscribers to the topic are automatically unsubscribed. 406 Example: 408 => 0.04 DELETE 409 Uri-Path: pubsub 410 Uri-Path: topics 411 Uri-Path: 1234 413 <= 2.02 Deleted 415 4. Publish/Subscribe 417 Unless a topic is configured to use a different mechanism, publish/ 418 subscribe is performed as follows: A publisher publishes to a topic 419 by submitting the data in a PUT request to a broker-managed "topic 420 data resource". This causes a change to the state of that resources. 421 Any subscriber observing the resource [RFC7641] at that time receives 422 a notification about the change to the resource state. 424 ___ 425 Topic / \ 426 Collection \___/ 427 \ 428 \___________________________ 429 \ \ \ 430 \ ...... \ ...... \ ...... 431 : \___ : : \___ : : \___ : 432 Topic : / \ : : / \ : : / \ : 433 Configuration : \___/ : : \___/ : : \___/ : 434 : _|_ : : _|_ : ... : _|_ : 435 Topic : / \ : : / \ : : / \ : 436 Data : \___/ : : \___/ : : \___/ : 437 :.......: :.......: :.......: 439 Figure 3: Resources of a Publish-Subscribe Broker 441 The topic data resource (which is different from the resource holding 442 the topic configuration) does not exist until some initial data has 443 been published to it. Before initial data has been published, the 444 topic data resource yields a 4.04 (Not Found) response. If such a 445 "half created" topic is undesired, the creator of the topic can 446 simply immediately publish some initial placeholder data to make the 447 topic "fully created". 449 All URIs for configuration and data resources are broker-generated. 450 There does not need to be any URI pattern dependence between the URI 451 where the data exists and the URI of the topic configuration. Topic 452 configuration and data resources might even be hosted on different 453 servers. 455 4.1. Topic Lifecycle 457 When a topic is newly created, it is first placed by the server into 458 the HALF CREATED state (see Figure 4). In this state, a client can 459 read and update the configuration of the topic and delete the topic. 460 A publisher can publish to the topic data resource. However, a 461 subscriber cannot yet observe the topic data resource. 463 HALF FULLY 464 CREATED CREATED 465 ___ ___ Publish/ 466 -----------> | | ------------------> | | ------------. 467 Create |___| Publish |___| <-----------' 468 \ / Subscribe 469 | ^ \ ___ / | ^ 470 Read/ | | '--> | | <--' | | Read/ 471 Update | | Delete |___| Delete | | Update 472 '-' '-' 473 DELETED 475 Figure 4: Lifecycle of a Topic 477 After a publisher publishes to the topic for the first time, the 478 topic is placed into the FULLY CREATED state. In this state, a 479 client can read and update the configuration of the topic and delete 480 the topic; a publisher can publish to the topic data resource; and a 481 subscriber can observe the topic data resource. 483 When a client deletes a topic, the topic is placed into the DELETED 484 state and shortly after removed from the server. In this state, all 485 subscribers are removed from the list of observers of the topic data 486 resource and no further interactions with the topic are possible. 488 4.2. Rate Limiting 490 The server hosting a data resource may have to handle a potentially 491 very large number of publishers and subscribers at the same time. 492 This means the server can easily become overwhelmed if it receives 493 too many publications in a short period of time. 495 In this situation, if a client is sending publications too fast, the 496 server can return a 4.29 (Too Many Requests) response [RFC8516]. As 497 described in RFC 8516, the Max-Age option [RFC7252] in this response 498 indicates the number of seconds after which the client may retry. 499 When a client receives a 4.29 (Too Many Requests) response, it should 500 not send any new publication requests to the same topic data resource 501 before the time indicated by the Max-Age option has passed. 503 4.3. Interactions 505 4.3.1. Publishing to a Topic 507 A client can publish data to a topic by submitting it in a PUT 508 request to the topic data URI. The topic data URI is indicated by 509 the status property of type in the 510 topic configuration. (Note: The topic data URI is not identical to 511 the topic URI!) 513 The data MUST be in the content format specified by the configuration 514 property of type in the topic 515 configuration. 517 On success, the server returns a 2.04 (Updated) response. However, 518 when data is published to the topic for the first time, the server 519 may instead return a 2.01 (Created) response. 521 If the request does not have an acceptable content format, the server 522 returns a 4.15 (Unsupported Content Format) response. 524 If the client is sending publications too fast, the server returns a 525 4.29 (Too Many Requests) response [RFC8516]. 527 Example: 529 => 0.03 PUT 530 Uri-Path: pubsub 531 Uri-Path: data 532 Uri-Path: 6578616d706c65 533 Content-Format: 112 535 [...SenML data...] 537 <= 2.04 Updated 539 4.3.2. Subscribing to a Topic 541 A client can get the latest published data and subscribe to newly 542 published data by observing the topic data URI with a GET request 543 that includes the Observe option [RFC7641]. 545 On success, the server returns 2.05 (Content) notifications with the 546 data. 548 Example: 550 => 0.01 GET 551 Uri-Path: pubsub 552 Uri-Path: data 553 Uri-Path: 6578616d706c65 554 Observe: 0 556 <= 2.05 Content 557 Content-Format: 112 558 Observe: 10001 559 Max-Age: 15 561 [...SenML data...] 563 <= 2.05 Content 564 Content-Format: 112 565 Observe: 10002 566 Max-Age: 15 568 [...SenML data...] 570 <= 2.05 Content 571 Content-Format: 112 572 Observe: 10003 573 Max-Age: 15 575 [...SenML data...] 577 4.3.3. Unsubscribing from a Topic 579 A client can unsubscribe simply by cancelling the observation as 580 described in Section 3.6 of RFC 7641. 582 4.3.4. Getting the Latest Published Data 584 A client can just get the latest published data by making a GET 585 request to the topic data URI. 587 On success, the server returns 2.05 (Content) response with the data. 589 Example: 591 => 0.01 GET 592 Uri-Path: pubsub 593 Uri-Path: data 594 Uri-Path: 6578616d706c65 596 <= 2.05 Content 597 Content-Format: 112 598 Max-Age: 15 600 [...SenML data...] 602 5. Security Considerations 604 TODO. 606 6. IANA Considerations 608 TODO. 610 7. References 612 7.1. Normative References 614 [I-D.ietf-core-coral] 615 Hartke, K., "The Constrained RESTful Application Language 616 (CoRAL)", draft-ietf-core-coral-03 (work in progress), 617 March 2020. 619 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 620 Requirement Levels", BCP 14, RFC 2119, 621 DOI 10.17487/RFC2119, March 1997, 622 . 624 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 625 Resource Identifier (URI): Generic Syntax", STD 66, 626 RFC 3986, DOI 10.17487/RFC3986, January 2005, 627 . 629 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 630 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 631 January 2005, . 633 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 634 Application Protocol (CoAP)", RFC 7252, 635 DOI 10.17487/RFC7252, June 2014, 636 . 638 [RFC7641] Hartke, K., "Observing Resources in the Constrained 639 Application Protocol (CoAP)", RFC 7641, 640 DOI 10.17487/RFC7641, September 2015, 641 . 643 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 644 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 645 May 2017, . 647 [RFC8516] Keranen, A., ""Too Many Requests" Response Code for the 648 Constrained Application Protocol", RFC 8516, 649 DOI 10.17487/RFC8516, January 2019, 650 . 652 7.2. Informative References 654 [I-D.ietf-core-coap-pubsub] 655 Koster, M., Keranen, A., and J. Jimenez, "Publish- 656 Subscribe Broker for the Constrained Application Protocol 657 (CoAP)", draft-ietf-core-coap-pubsub-09 (work in 658 progress), September 2019. 660 [REST] Fielding, R., "Architectural Styles and the Design of 661 Network-based Software Architectures", Ph.D. Dissertation, 662 University of California, Irvine, 2000, 663 . 666 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 667 Constrained-Node Networks", RFC 7228, 668 DOI 10.17487/RFC7228, May 2014, 669 . 671 Acknowledgements 673 This document is based on a proposal for pub/sub broker improvements 674 presented at IETF 105 in Montreal by Michael Koster, Ari Keranen, and 675 Klaus Hartke. It borrows text from [I-D.ietf-core-coap-pubsub] by 676 Michael Koster, Ari Keranen, and Jaime Jimenez. 678 Thanks to Christian Amsuess, Carsten Bormann, Rikard Hoeglund, 679 Michael McCool, Francesca Palombini, Ivaylo Petrov, Jim Schaad, Peter 680 van der Stok, and Marco Tiloca for helpful comments and discussions 681 that have shaped the document. 683 Author's Address 685 Klaus Hartke 686 Ericsson 687 Torshamnsgatan 23 688 Stockholm SE-16483 689 Sweden 691 Email: klaus.hartke@ericsson.com