CoAP Option Extension : Timeout
draft-li-core-coap-request-timeout-option-00

Abstract

CoAP is a RESTful application protocol for constrained nodes and networks. This specification provides a simple extension for CoAP, to inform a CoAP server of the maximum time that a CoAP client will wait a response to its request. A CoAP server can use this header to ensure that a timely response is generated.

Note

Discussion and suggestions for improvement are requested, and should be sent to core@ietf.org.

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 http://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 November 20, 2011.

Copyright Notice

Copyright (c) 2011 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 (http://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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

• 1. Introduction
• 1.1. Justification
• 1.2. Terminology
• 2. Respuest-Timeout Option Extension
• 2.1. Request-Timeout Option Definition
• 2.2. Using the Request-Timeout Option
• 3. Example
• 4. Security Considerations
• 5. IANA Considerations
• 6. Acknowledgements
• 7. References
• Authors' Addresses

1. Introduction

This specification adds a new option Request-Timeout to CoAP. The main purpose is for the client to indicate the maximum time that a CoAP client will wait for a response to its request.

1.1. Justification

It is useful for the client to indicate that the response is required to be returned within a certain amount of time. For example, the client could require a response within 2 seconds. This applies to both a Piggy-backed Response and a Separate Response. With this indication of the response timeout, the client knows how long it should wait for the response, and it needs to keep the state of the request only for the indicated time. After this period, the request will be given up. In this way, the transmission resource can be saved to avoid the retransmission of requests. Also it can avoid that the server wastes resources by sending a response which already exceeds the set timeout of the client.

1.2. Terminology

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 [RFC2119].

2. Respuest-Timeout Option Extension

2.1. Request-Timeout Option Definition

        +------+-----+----------------+-----------+--------+----------+
        | Type | C/E |      Name      | Data type | Length | Default  |
        +------+-----+----------------+-----------+--------+----------+
        |  20  | E   | Request-Timeout|   uint    | 0-1 B  |          |
        +------+-----+----------------+-----------+--------+----------+
         

   
           0
           0 1 2 3 4 5 6 7
          +-+-+-+-+-+-+-+-+
          |       T       |
          +-+-+-+-+-+-+-+-+
          

Request-Timeout = 2^T milliseconds

The value of the Request-Timeout option is 2^T milliseconds. [TBD: keep the spec open on whether the base is milliseconds or 1024s of a second -- the clocks are not going to be that precise anyway, and this might help some implementations that count in 1024s ("mibiseconds") or in whole seconds.]

2.2. Using the Request-Timeout Option

This option is used to indicate the maximum time that a client is prepared to wait for a response.

The client adds the Request-Timeout option to any request for which it is prepared to wait for a response. The client sets the option to the maximum time that it is prepared to wait.

The server interprets this option as the time between receipt of the complete request and the time that it generates and begins sending the response. The client will observe a longer time interval between request and response, as network transit and processing by proxies add delays. If timing is critical, the client SHOULD consider the possible delays and choose the value for the option accordingly.

The server MAY apply a lower value to the timeout based on local policy. A server MAY choose to take longer to produce a response, at the risk that the client is no longer able to use the response.

In case that the CoAP message is transmitted through a proxy, the Proxy MAY reduce the value of a Request-Timeout option based on a local policy. A Proxy MAY add a Request-Timeout option if none is present. The value in the Request-Timeout option MUST NOT be increased or removed.

If the client does not receive a response within the indicated response time, the client MAY consider the request as failed.

If the server can't provide response within the required time, a 5.XX (Can't provide the data in time) [TBD] MUST be returned. Note that the client cannot rely on getting the response code, because the server might have failed in the meantime.

This option is not used in a response.

This option is "elective". It MUST NOT occur more than once.

3. Example

This section gives a short example with a message flow that illustrates the use of the Request-Timeout option in a GET request.

The first example (Figure 3) shows that the client wants to get a response within 2048 milliseconds.

 

   Client  Server
      |      |
      |      |
      +----->|          Header: GET (T=CON, Code=1, MID=0x7d38)
      | GET  |           Token: 0x53      
      |      | Request-Timeout: 00001011   
      |      |        Uri-Path: "temperature"
      |      |
      |<-----+     Header: 2.05 Content (T=ACK, Code=69, MID=0x7d38)
      | 2.05 |      Token: 0x53
      |      |    Payload: "22.3 C"
      |      |
 
       Figure 1: Request-Timeout Option in a request
      
        

4. Security Considerations

This presents no security considerations beyond those in section 10 of the base CoAP specification [I-D.ietf-core-coap].

5. IANA Considerations

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

                +--------+------------------+----------------+
                | Number | Name             | Reference      |
                +--------+------------------+----------------+
                |  20    | Request-Timeout  | Section 2      |
                +--------+------------------+----------------+
         

6. Acknowledgements

The authors of this draft would like to thank the participants of the email discussion on this issue. Thanks to Carsten Bormann, Peter Bigot, Barry Leiba, Linyi Tian for the reviews and discussions.

7. References

Authors' Addresses