CoAP Option Extension : Size

This specification adds a new option Size to the Constrained Application Protocol (CoAP). The main purpose is to indicate the resource size in a Put/Post request, or in a Get response.

If the requester wants to retrieve large resource data using a Get request, it is better to know in advance the size of the resource data. Currently in the Link Format specification, the maximum size estimate attribute "sz" is defined to give an indication of the estimated maximum size of the resource data. By using this, the requester is able to know whether it is capable to accept the resource data. However it is not possible for the requester to know exactly how many blocks will be transmitted, therefore, concurrent Get can't be supported. Also in the Post/Put request (for example, a firmware update), it is not possible for the recipient to know in advance what is the size of the data to be transmitted. According to the current CoAP specification, when transmitting large data, the recipient will return an error code 4.13 (Request Entity Too Large) to the requester when the data size is too big to be accepted by the recipient. In this case the whole transmission has failed, and the previous received data will be useless. This is a waste of transmission resources. This document adds the new Size Option to provide the capability to indicate the accurate size in a Get response or in a Post/Put request. By using the Size Option in a Get response, the CoAP Server can let the requester know the actual size of the resource in advance. This is especially useful for large resources, and can facilitate the requester to allocate enough buffer space before transmission. Also, using the block size, the requester can calculate the total number of blocks and can use concurrent Get requests to retrieve resource data using the Block Option. Finally, the receipent can check the resource size after the data transmission has been completed. By using the Size Option in a Put/Post request, the requester can indicate the resource size in the first Block Option message, to let the recipient know the resource data size in advance. If the recipient is not able to receive the data with the indicated size, the recipient can tell the requester in a response code, avoiding the cost of the actual data transmission.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in .

+------+-----+-------+-----------+--------+---------------+ | Type | C/E | Name | Data type | Length | Default | +------+-----+-------+-----------+--------+---------------+ | 12 | E | Size | uint | 1-4 B | | +------+-----+-------+-----------+--------+---------------+

The Size Option is used to indicate the size of the resource data measured in bytes. It can be used in a Get response to give indication about the resource data size. The Get request including Size=0 is treated as a request to get the size of the resource representation (but not the resource payload). Also it can be used in a Post/Put request in the first Block Option message. The Size option is not expected to be included for small resources that can easily be carried in a single MTU, but SHOULD be included for resources larger than that, if the Size information is available. In the absence of the option, the size of the resource data is calculated after the data transmitted to the recipient, either from the CoAP payload length or based on number of blocks and block size. If the Size option is specified it SHOULD be accurate at that time, and SHOULD NOT be an estimate. But due to the dynamic change of the resource data, the Size may not be accurate. If the value of Size option is not the same as the actual transmitted data, the recipient MUST take the size of the actual transmitted data as accurate, and ignore the Size option. In case that the recipient gets all the data but it is still smaller than the Size, the recipient SHOULD stop the transmission. If the recipient finds out the transmitted data reaches the Size limit, and there's more data left, the recipient SHOULD continue to transmit the remaining data. This option is "Elective". It MUST NOT occur more than once.

In the Put/Post request for the large resource data, the requester can indicate the size of the resource using the Size option. If the recipient is not capable to receive the data with the indicated size, the recipient MUST return a 4.13 (Request Entity Too Large) response code to the requester, and the data transmission is avoided, so that the cost of the actual data transmission is saved.

In the Get response for the large resource data, the CoAP Server can use Size option to indicate the resource size and return the first block data. The requester can calculate the number of blocks to be transferred based on the block size and the resource size, and use concurrent Get requests to retrieve resource data.

This section gives a number of short examples with message flows to illustrate the use of Size option in GET response, or in a PUT/POST request. The first example (Figure 1) shows that the requester does not know the resource data size, and sends the Get request, the recipient can send back the resource size using the Size option and the first block. In the subsequent Get request, the requester can calculate the number of blocks and use concurrent Get requests to retrieve resource data.

| | | | <------ ACK [MID=1234], 2.00 OK, 0/1/128, Size: 5000 | | | | CON [MID=1235], GET, /status, 1/0/128 ------> | | | | <------ ACK [MID=1235], 2.00 OK, 1/1/128 | | | | ... ... | | | | CON [MID=1280], GET, /status, 40/0/128 ------> | | | | <------ ACK [MID=1280], 2.00 OK, 40/0/128 | | | Figure 1: Size Option in a GET response ]]> The second example (Figure 2) shows that the requester sends a Put request with the Size option to indicate the resource data size, the recipient determines that the resource data is too large to be accepted according to the size information, and sends back a 4.13 (Request Entity Too Large) response code.

| | | | <------ ACK [MID=1234], 4.13 Request Entity Too Large | | | Figure 2: Size Option in a Put request ]]>

This presents no security considerations beyond those in section 10 of the base CoAP specification and in section 5 of the block specification .

The IANA is requested to add the following Option Number entry.

+--------+---------------+----------------+ | Number | Name | Reference | +--------+---------------+----------------+ | 12 | Size | Section 2 | +--------+---------------+----------------+

The authors of this draft would like to thank the participants of the email discussion on this issue. Thanks to Bert Greevenbosch, Charles Palmer and Carsten Bormann for the detailed reviews and suggestions.