idnits 2.17.1 draft-hartke-t2trg-coral-pubsub-00.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 (November 4, 2019) is 1635 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-01 == 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 November 4, 2019 5 Expires: May 7, 2020 7 Publish/Subscribe over the Constrained Application Protocol (CoAP) 8 using the Constrained RESTful Application Language (CoRAL) 9 draft-hartke-t2trg-coral-pubsub-00 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 May 7, 2020. 36 Copyright Notice 38 Copyright (c) 2019 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 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 . . . . . . . . . . . . . . . . . . . . . 11 78 4.3.2. Subscribing . . . . . . . . . . . . . . . . . . . . . 12 79 4.3.3. Unsubscribing . . . . . . . . . . . . . . . . . . . . 13 80 5. Security Considerations . . . . . . . . . . . . . . . . . . . 13 81 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 82 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 83 7.1. Normative References . . . . . . . . . . . . . . . . . . 13 84 7.2. Informative References . . . . . . . . . . . . . . . . . 14 85 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 15 86 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 15 88 1. Preamble 90 This document explores how CoAP Publish/Subscribe Broker 91 [I-D.ietf-core-coap-pubsub] might look like if based on CoRAL 92 [I-D.ietf-core-coral]. The exploration is done in the style of a 93 self-contained specification rather than a description of changes. 95 2. Introduction 97 Constrained RESTful Environments (CoRE) realize the Representational 98 State Transfer (REST) architectural style [REST] in a suitable form 99 for constrained nodes (e.g., 8-bit microcontrollers with limited RAM 100 and ROM) and constrained networks [RFC7228]. CoRE technologies like 101 the Constrained Application Protocol (CoAP) [RFC7252] are aimed at 102 machine-to-machine (M2M) applications like smart energy and building 103 automation. 105 An important class of constrained nodes are devices that are intended 106 to run for years on a small battery or by scavenging energy from 107 their environment. These nodes have limited reachability, since they 108 spend most of their time in a sleeping state with no network 109 connectivity. Another important class of nodes are devices with 110 limited reachability due to middle-boxes like Network Address 111 Translators (NATs) and firewalls. 113 For these nodes, the client/server-oriented architecture of REST can 114 be challenging when interactions are not initiated by the devices 115 themselves. A publish/subscribe-oriented architecture where nodes 116 are separated by a broker and data is exchanged via topics might fit 117 these nodes better. 119 This document applies the idea of a "Publish/Subscribe Broker" to 120 Constrained RESTful Environments. The broker enables store-and- 121 forward data exchange between nodes, thereby facilitating the 122 communication of nodes with limited reachability, providing simple 123 many-to-many communication, and easing integration with other 124 publish/subscribe systems. 126 2.1. Brokers and Topics 128 In this specification, publishing and subscribing is facilitated by a 129 CoAP server, called the "publish/subscribe broker" (see Figure 1). 130 Publishers and subscribers are CoAP clients that interact with this 131 broker using a RESTful API. 133 CoAP CoAP CoAP 134 Clients Server Clients 135 ___________ __________ observe ____________ 136 | | publish | | .--------- | | 137 | Publisher | ---------> | | |--------> | Subscriber | 138 |___________| | | '--------> |____________| 139 . | | . 140 . | Broker | . 141 ___________ | | observe ____________ 142 | | publish | | .--------- | | 143 | Publisher | ---------> | | |--------> | Subscriber | 144 |___________| |__________| '--------> |____________| 146 Figure 1: Publish/Subscribe over CoAP 148 Data is forwarded from publishers to subscribers via "topics" at the 149 broker. This way, both publishers and subscribers do not need to 150 have any knowledge each other; they just have to share the topic 151 they're publishing and subscribing to. 153 Topics have to be created and configured before any data can be 154 published. These are managed by the broker. Clients may propose new 155 topics to be created; however, it is up to the broker to choose if 156 and how a topic is created. The broker also decides the URI of each 157 topic. 159 The creation, configuration, and discovery of topics at a broker is 160 specified in Section 3. 162 2.2. Publish and Subscribe 164 A simple publish/subscribe mechanism can be implemented over CoAP by 165 having publishers submit their data in PUT requests to a broker- 166 managed resource and letting subscribers observing this resource 167 [RFC7641]. 169 However, the case may not always be simple: As described in RFC 7641, 170 notifications are sent on a best-effort basis: Subscribers should be 171 notified of as many state changes as possible; however, when a 172 publisher publishes faster than subscribers can be notified, 173 subscribers might not see every publication. If this is not desired, 174 an alternative mechanism needs to be be used. Such alternatives are 175 supported, but their specification is out of this document's scope. 177 The simple publish/subscribe mechanism is specified in Section 4. 179 2.3. Notational Conventions 181 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 182 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 183 "OPTIONAL" in this document are to be interpreted as described in BCP 184 14 [RFC2119] [RFC8174] when, and only when, they appear in all 185 capitals, as shown here. 187 3. Topics 189 The configuration side of a "publish/subscribe broker" consists of a 190 collection of topics. These topics as well as the collection itself 191 are exposed by a CoAP server as resources (see Figure 2). 193 ___ 194 Topic / \ 195 Collection \___/ 196 \ 197 \____________________ 198 \___ \___ \___ 199 / \ / \ ... / \ Topics 200 \___/ \___/ \___/ 202 Figure 2: Resources of a Publish-Subscribe Broker 204 3.1. Topic Configuration 206 Each topic has a topic configuration. A CoAP client can create a new 207 topic by submitting an initial configuration for the topic. It can 208 also read and update the configuration of existing topics and delete 209 them when they are no longer needed. 211 The configuration of a topic itself consists of a set of properties. 212 These fall into one of two categories: configuration properties and 213 status properties. Configuration properties can be set by a client 214 and describe the desired configuration of a topic. Status properties 215 are read-only, managed by the server, and provide information about 216 the actual status of a topic. 218 When a client submits a configuration to create a new topic or update 219 an existing topic, it can only submit configuration properties. When 220 a server returns the configuration of a topic, it returns both the 221 configuration properties and the status properties of the topic. 223 Every property has a type and a value. The type takes the form of an 224 IRI [RFC3987]. This IRI serves only as an identifier; it must not be 225 dereferenced by clients. The value can be either a Boolean value, an 226 integer, a floating-point number, a date/time value, a byte string, a 227 text string, or a resource reference in the form of a URI [RFC3986]. 229 3.1.1. Configuration Properties 231 The following configuration properties are defined: 233 TODO. 235 3.1.2. Status Properties 237 The following status properties are defined: 239 TODO. 241 3.1.3. Topic Configuration Representation 243 A topic configuration is represented as a CoRAL document 244 [I-D.ietf-core-coral] containing the configuration properties and 245 status properties of the topic as top-level elements. 247 Each property is represented as a link where the link relation type 248 is the property type and the link target is the property value. 250 3.2. Topic Discovery 252 Topics can be discovered by a client on the basis of configuration 253 properties and status properties. For example, a client could fetch 254 a list of all topics that have a property of type "foo" or that have 255 a property of type "bar" with the value 42. Alternatively, topics 256 can also be discovered simply by getting the full list of all topics. 258 3.2.1. Topic List Representation 260 A list of topics is represented as a CoRAL document 261 [I-D.ietf-core-coral] containing the topics in the list as top-level 262 elements. 264 Each topic is represented as a link where the link relation type is 265 and the link target is the topic 266 URI. This link can optionally contain (a subset of) the 267 configuration properties and status properties of the topic as nested 268 elements. 270 Each property is represented in the same way as in Section 3.1.3. 272 3.2.2. Filter Query Representation 274 TODO. 276 3.3. Interactions 278 3.3.1. Getting All Topics 280 A client can list a collection of topics by making a GET request to 281 the collection URI. 283 On success, the server returns a 2.05 (Content) response with a 284 representation of the list of all topics (see Section 3.2.1) in the 285 collection. 287 Example: 289 => 0.01 GET 290 Uri-Path: pubsub 291 Uri-Path: topics 293 <= 2.05 Content 294 Content-Format: 65536 296 item 297 item 298 item 300 3.3.2. Getting Topics by Properties 302 A client can filter a collection of topics by submitting the 303 representation of a topic filter (see Section 3.2.2) in a FETCH 304 request to the topic collection URI. 306 On success, the server returns a 2.05 (Content) response with a 307 representation of a list of topics in the collection (see 308 Section 3.2.1) that match the filter. 310 Example: 312 => 0.05 FETCH 313 Uri-Path: pubsub 314 Uri-Path: topics 315 Content-Format: TODO 317 TODO 319 <= 2.05 Content 320 Content-Format: 65536 322 item 323 item 324 item 326 3.3.3. Creating a Topic 328 A client can add a new topic to a collection of topics by submitting 329 a representation of the initial topic configuration (see 330 Section 3.1.3) in a POST request to the topic collection URI. 332 If client just wants all the default configuration properties, it can 333 simply submit an empty CoRAL document. 335 On success, the server returns a 2.01 (Created) response indicating 336 the topic URI of the new topic. 338 Example: 340 => 0.02 POST 341 Uri-Path: pubsub 342 Uri-Path: topics 343 Content-Format: 65536 345 foo "xyz" 346 bar 42 348 <= 2.01 Created 349 Location-Path: pubsub 350 Location-Path: topics 351 Location-Path: 1234 353 3.3.4. Reading the Configuration of a Topic 355 A client can read the configuration of a topic by making a GET 356 request to the topic URI. 358 On success, the server returns a 2.05 (Content) response with a 359 representation of the topic configuration (see Section 3.1.3). 361 Example: 363 => 0.01 GET 364 Uri-Path: pubsub 365 Uri-Path: topics 366 Uri-Path: 1234 368 <= 2.05 Content 369 Content-Format: 65536 370 Max-Age: 300 372 foo "xyz" 373 bar 42 375 3.3.5. Updating the Configuration of a Topic 377 A client can update the configuration of a topic by submitting the 378 representation of the updated topic configuration (see Section 3.1.3) 379 in a PUT request to the topic URI. Any existing properties in the 380 configuration are replaced by this update. 382 On success, the server returns a 2.04 (Updated) response. 384 Example: 386 => 0.03 PUT 387 Uri-Path: pubsub 388 Uri-Path: topics 389 Uri-Path: 1234 390 Content-Format: 65536 392 foo "abc" 394 <= 2.04 Updated 396 3.3.6. Deleting a Topic 398 A client can delete a topic by making a DELETE request on the topic 399 URI. 401 On success, the server returns a 2.02 (Deleted) response. 403 Any subscribers to the topic are automatically unsubscribed. 405 Example: 407 => 0.04 DELETE 408 Uri-Path: pubsub 409 Uri-Path: topics 410 Uri-Path: 1234 412 <= 2.02 Deleted 414 4. Publish/Subscribe 416 Unless a topic is configured to use a different mechanism, publish/ 417 subscribe is performed as follows: A publisher publishes to a topic 418 by submitting the data in a PUT request to a broker-managed "topic 419 data resource". This causes a change to the state of that resources. 420 Any subscriber observing the resource [RFC7641] at that time receives 421 a notification about the change to the resource state. 423 ___ 424 Topic / \ 425 Collection \___/ 426 \ 427 \___________________________ 428 \ \ \ 429 \ ...... \ ...... \ ...... 430 : \___ : : \___ : : \___ : 431 Topic : / \ : : / \ : : / \ : 432 Configuration : \___/ : : \___/ : : \___/ : 433 : _|_ : : _|_ : ... : _|_ : 434 Topic : / \ : : / \ : : / \ : 435 Data : \___/ : : \___/ : : \___/ : 436 :.......: :.......: :.......: 438 Figure 3: Resources of a Publish-Subscribe Broker 440 The topic data resource (which is different from the resource holding 441 the topic configuration) does not exist until some initial data has 442 been published to it. Before initial data has been published, the 443 topic data resource yields a 4.04 (Not Found) response. If such a 444 "half created" topic is undesired, the creator of the topic can 445 simply immediately publish some initial placeholder data to make the 446 topic "fully created". 448 All URIs for configuration and data resources are broker-generated. 449 There does not need to be any URI pattern dependence between the URI 450 where the data exists and the URI of the topic configuration. Topic 451 configuration and data resources might even be hosted on different 452 servers. 454 4.1. Topic Lifecycle 456 When a topic is newly created, it is first placed by the server into 457 the HALF CREATED state (see Figure 4). In this state, a client can 458 read and update the configuration of the topic and delete the topic. 459 A publisher can publish to the topic data resource. However, a 460 subscriber cannot yet observe the topic data resource. 462 HALF FULLY 463 CREATED CREATED 464 ___ ___ Publish/ 465 -----------> | | ------------------> | | ------------. 466 Create |___| Publish |___| <-----------' 467 \ / Subscribe 468 | ^ \ ___ / | ^ 469 Read/ | | '--> | | <--' | | Read/ 470 Update | | Delete |___| Delete | | Update 471 '-' '-' 472 DELETED 474 Figure 4: Lifecycle of a Topic 476 After a publisher publishes to the topic for the first time, the 477 topic is placed into the FULLY CREATED state. In this state, a 478 client can read and update the configuration of the topic and delete 479 the topic; a publisher can publish to the topic data resource; and a 480 subscriber can observe the topic data resource. 482 When a client deletes a topic, the topic is placed into the DELETED 483 state and shortly after removed from the server. In this state, all 484 subscribers are removed from the list of observers of the topic data 485 resource and no further interactions with the topic are possible. 487 4.2. Rate Limiting 489 The server hosting a data resource may have to handle a potentially 490 very large number of publishers and subscribers at the same time. 491 This means the server can easily become overwhelmed if it receives 492 too many publications in a short period of time. 494 In this situation, if a client is sending publications too fast, the 495 server can return a 4.29 (Too Many Requests) response [RFC8516]. The 496 Max-Age option [RFC7252] in this response indicates the number of 497 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 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 instead returns 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 541 A client can subscribe to newly published data by observing the topic 542 data URI with a GET request that includes the Observe option 543 [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 579 A client can unsubscribe simply by cancelling the observation as 580 described in Section 3.6 of RFC 7641. 582 5. Security Considerations 584 TODO. 586 6. IANA Considerations 588 TODO. 590 7. References 592 7.1. Normative References 594 [I-D.ietf-core-coral] 595 Hartke, K., "The Constrained RESTful Application Language 596 (CoRAL)", draft-ietf-core-coral-01 (work in progress), 597 November 2019. 599 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 600 Requirement Levels", BCP 14, RFC 2119, 601 DOI 10.17487/RFC2119, March 1997, 602 . 604 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 605 Resource Identifier (URI): Generic Syntax", STD 66, 606 RFC 3986, DOI 10.17487/RFC3986, January 2005, 607 . 609 [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource 610 Identifiers (IRIs)", RFC 3987, DOI 10.17487/RFC3987, 611 January 2005, . 613 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 614 Application Protocol (CoAP)", RFC 7252, 615 DOI 10.17487/RFC7252, June 2014, 616 . 618 [RFC7641] Hartke, K., "Observing Resources in the Constrained 619 Application Protocol (CoAP)", RFC 7641, 620 DOI 10.17487/RFC7641, September 2015, 621 . 623 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 624 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 625 May 2017, . 627 [RFC8516] Keranen, A., ""Too Many Requests" Response Code for the 628 Constrained Application Protocol", RFC 8516, 629 DOI 10.17487/RFC8516, January 2019, 630 . 632 7.2. Informative References 634 [I-D.ietf-core-coap-pubsub] 635 Koster, M., Keranen, A., and J. Jimenez, "Publish- 636 Subscribe Broker for the Constrained Application Protocol 637 (CoAP)", draft-ietf-core-coap-pubsub-09 (work in 638 progress), September 2019. 640 [REST] Fielding, R., "Architectural Styles and the Design of 641 Network-based Software Architectures", Ph.D. Dissertation, 642 University of California, Irvine, 2000, 643 . 646 [RFC7228] Bormann, C., Ersue, M., and A. Keranen, "Terminology for 647 Constrained-Node Networks", RFC 7228, 648 DOI 10.17487/RFC7228, May 2014, 649 . 651 Acknowledgements 653 This document is based on a proposal for pub/sub broker improvements 654 presented at IETF 105 in Montreal by Michael Koster, Ari Keranen, and 655 Klaus Hartke. It borrows text from [I-D.ietf-core-coap-pubsub] by 656 Michael Koster, Ari Keranen, and Jaime Jimenez. 658 Thanks to Christian Amsuess, Carsten Bormann, Rikard Hoeglund, 659 Michael McCool, Francesca Palombini, Ivaylo Petrov, Jim Schaad, Peter 660 van der Stok, and Marco Tiloca for helpful comments and discussions 661 that have shaped the document. 663 Author's Address 665 Klaus Hartke 666 Ericsson 667 Torshamnsgatan 23 668 Stockholm SE-16483 669 Sweden 671 Email: klaus.hartke@ericsson.com