idnits 2.17.1 draft-hartke-core-pending-02.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 (February 26, 2018) is 2249 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group P. van der Stok 3 Internet-Draft consultant 4 Intended status: Informational K. Hartke 5 Expires: August 30, 2018 Universitaet Bremen TZI 6 February 26, 2018 8 "Pending" Responses for the Constrained Application Protocol (CoAP) 9 draft-hartke-core-pending-02 11 Abstract 13 This document proposes a new type of response for the Constrained 14 Application Protocol (CoAP) called a "Pending" response. A CoAP 15 server can use a Pending response to indicate that it has accepted a 16 request but has not yet started processing it or that processing the 17 request will take longer than a client is typically willing to wait 18 for a response. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on August 30, 2018. 37 Copyright Notice 39 Copyright (c) 2018 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 56 2. Pending Responses . . . . . . . . . . . . . . . . . . . . . . 3 57 2.1. Observing Resources . . . . . . . . . . . . . . . . . . . 4 58 3. Security Considerations . . . . . . . . . . . . . . . . . . . 4 59 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 60 5. References . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 5.1. Normative References . . . . . . . . . . . . . . . . . . 5 62 5.2. Informative References . . . . . . . . . . . . . . . . . 5 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 6 65 1. Introduction 67 The Constrained Application Protocol (CoAP) [RFC7252] is a request/ 68 response protocol not unlike HTTP. CoAP defines no upper bound for 69 the time between a request and the resulting response. For example, 70 a CoAP-over-UDP server is expected to return an empty Acknowledgement 71 to the client if it cannot provide a response right away, but there 72 is no limit on the time when the server should return the Separate 73 Response. 75 In particular in the case of requests with long processing times, a 76 CoAP client faces the problem that it cannot easily determine how 77 long it should wait for the response and whether the CoAP server is 78 actually still processing the request. Long processing times occur, 79 for example, when requests need manual intervention to authorize 80 their processing, or when they perform a long sequence of remote 81 actions. An example for this is the "possibly long" authorization 82 request specified in EST-coaps [I-D.vanderstok-ace-coap-est]. 84 This document proposes a new kind of response in CoAP, called a 85 "Pending" response. The semantics of this response are modelled 86 after the HTTP 202 (Accepted) status code [RFC7231]: 88 The 202 (Accepted) status code indicates that the request has been 89 accepted for processing, but the processing has not been 90 completed. The request might or might not eventually be acted 91 upon, as it might be disallowed when processing actually takes 92 place. [...] The representation sent with this response ought to 93 describe the request's current status and point to (or embed) a 94 status monitor that can provide the user with an estimate of when 95 the request will be fulfilled. 97 Pending responses are not intended for overload cases, which are 98 better handled by the 5.03 (Service Unavailable) response code. 100 1.1. Terminology 102 Readers are expected to be familiar with the terms and concepts 103 described in [RFC7252] and [RFC7641]. 105 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 106 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 107 "OPTIONAL" in this document are to be interpreted as described in 108 [RFC2119]. 110 2. Pending Responses 112 A Pending response is denoted by a response code in the 2.xx range 113 and a Content-Format Option that is set to content-format ID TBD1. 115 A 2.01 (Creation Pending) response in reply to a POST request 116 indicates that the result of processing the request is not available 117 yet, for example, because the server needs more time to process the 118 request than a client is typically willing to wait for a response. 119 The server MAY specify a location using the Location-* options where 120 the result will become available. If the server does not specify a 121 location, the result will become available at the target resource of 122 the POST request. To retrieve the result, the client MAY poll or 123 observe the resource at this location using the GET request method. 125 A 2.02 (Deletion Pending) response in reply to a DELETE request 126 indicates that the server has accepted the request but the target has 127 not been fully deleted yet. 129 A 2.04 (Change Pending) response in reply to a POST or PUT request 130 indicates that the server has accepted the request but the result of 131 processing the request is not available yet. 133 A 2.05 (Content Pending) response in reply to GET request indicates 134 that the target resource exists but a representation of the resource 135 is not available yet. The Max-Age Option indicates after what time a 136 client should retry its GET request to retrieve the representation. 137 The client MAY observe the resource [RFC7641] to get notified when 138 the representation becomes available (see Section 2.1 for details). 140 The payload of a Pending response MAY be a brief human-readable 141 diagnostic message, explaining the situation, or MUST be absent. 143 The cacheability of Pending responses is as specified for the 144 respective response code. 146 2.1. Observing Resources 148 When a client registers to observe a resource [RFC7641] for which no 149 representation is available yet, the server MAY send one or more 2.05 150 (Content Pending) notifications before sending the first actual 2.05 151 (Content) or 2.03 (Valid) notification. The possible resulting 152 sequence of notifications is shown in Figure 1. 154 __________ __________ __________ 155 | | | | | | 156 ---->| 2.05 |---->| 2.05 / |---->| 4.xx / | 157 | Pending | | 2.03 | | 5.xx | 158 |__________| |__________| |__________| 159 ^ \ \ ^ \ ^ 160 \__/ \ \___/ / 161 \_______________________/ 163 Figure 1: Sequence of Notifications 165 Unless the server is unwilling to add the client to the list of 166 observers, each 2.05 (Content Pending) notification MUST include an 167 Observe Option with a sequence number as specified in [RFC7641]. 168 Otherwise, the registration request falls back to a normal GET 169 request. 171 3. Security Considerations 173 This section analyses the possible threats related to Pending 174 responses. It is meant to inform protocol and application developers 175 about the security limitations of the response code as described in 176 this document. 178 A Pending response is subject to the same general security 179 considerations as all CoAP responses as described in Section 11 of 180 [RFC7252]. Specifically, the security considerations for the 181 response code are closest to those of the Observe Option as stated in 182 Section 7 of [RFC7641], because the server stores additional state 183 over an extended period. 185 Pending responses are secured following the recommendations for the 186 existing CoAP response codes as specified in Section 9 of [RFC7252]. 187 When additional security techniques are standardized for CoAP (e.g., 188 based on object security), these are then also available for securing 189 the responses. 191 4. IANA Considerations 193 This document adds the content-format used to signal Pending 194 responses to the "CoAP Content-Formats" registry. 196 +------------+----------------+------+-----------------+ 197 | Media Type | Content Coding | ID | Reference | 198 +------------+----------------+------+-----------------+ 199 | - | - | TBD1 | [This Document] | 200 +------------+----------------+------+-----------------+ 202 New CoAP Content-Formats 204 TBD1 is taken from the "First Come First Served" range of the "CoAP 205 Content-Formats" registry. 207 5. References 209 5.1. Normative References 211 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 212 Requirement Levels", BCP 14, RFC 2119, 213 DOI 10.17487/RFC2119, March 1997, 214 . 216 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 217 Application Protocol (CoAP)", RFC 7252, 218 DOI 10.17487/RFC7252, June 2014, 219 . 221 [RFC7641] Hartke, K., "Observing Resources in the Constrained 222 Application Protocol (CoAP)", RFC 7641, 223 DOI 10.17487/RFC7641, September 2015, 224 . 226 5.2. Informative References 228 [I-D.vanderstok-ace-coap-est] 229 Stok, P., Kampanakis, P., Kumar, S., Richardson, M., 230 Furuhed, M., and S. Raza, "EST over secure CoAP (EST- 231 coaps)", draft-vanderstok-ace-coap-est-04 (work in 232 progress), January 2018. 234 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 235 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 236 DOI 10.17487/RFC7231, June 2014, 237 . 239 Authors' Addresses 241 Peter van der Stok 242 consultant 244 Phone: +31-492474673 (Netherlands), +33-966015248 (France) 245 Email: consultancy@vanderstok.org 246 URI: www.vanderstok.org 248 Klaus Hartke 249 Universitaet Bremen TZI 250 Postfach 330440 251 Bremen D-28359 252 Germany 254 Phone: +49-421-218-63905 255 Email: hartke@tzi.org