CoAP Extensions for Asynchronous Task Resources

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 https://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 20 December 2026.¶

Copyright Notice

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

Table of Contents

1. Introduction

The Constrained Application Protocol (CoAP) [RFC7252] provides a RESTful interaction model for constrained nodes and constrained networks. Many CoAP resources can be read or modified with a single request and response. Other operations, however, are inherently asynchronous: firmware installation, actuator motion, multi-resource configuration, diagnostics, commissioning, and closed-loop automation may continue after the initial request has been accepted.¶

In current deployments, such long-running operations are often represented in an application-specific manner. One server may return a proprietary job URI in the payload, another may require repeated polling of the original resource, and another may use Observe [RFC7641] with implementation-specific state fields. These patterns work within a single application profile, but they do not provide common behavior for generic CoAP clients, gateways, cross-proxies, management systems, or resource-constrained servers that need to expose multiple kinds of long-running operations.¶

The lack of a common model creates several interoperability problems:¶

• A client has no standard way to discover the resource that represents an accepted operation.¶

• A client has no common state vocabulary for deciding whether an accepted operation is still pending, active, completed, failed, aborted, or rejected.¶

• Gateways and intermediaries cannot recognize task-related traffic without parsing application payloads.¶

• Observe notifications for progress or state changes can produce excessive traffic when clients only need coarse progress updates or minimum notification intervals. Existing Conditional Query Parameters for CoAP Observe can be reused for this purpose when task state is exposed as suitable observable resources.¶

• Multi-resource operations have no common request-level indication of whether sub-operations are intended to be atomic, ordered, or independently applied.¶

These are protocol interoperability issues rather than only application design issues. They affect common CoAP behavior across payload formats and deployment profiles. This document therefore specifies a small CoAP extension for asynchronous task resources. It preserves the CoAP REST model: task creation is performed with a request to an application resource, the server returns an addressable task resource, and the task is then monitored, modified, or canceled with existing CoAP methods.¶

Autonomous AI agents provide a useful stress case for this work because they can produce multi-step, non-instantaneous plans for constrained devices. However, the wire image defined here is not specific to AI. A conventional management client, scheduler, digital twin, or automation controller can use the same task resource model.¶

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

Task:

An asynchronous operation accepted by a CoAP server whose execution continues after the initial request/response exchange.¶

Task Resource:

A CoAP resource that represents one task instance. It exposes the task state and may allow task update or cancellation.¶

Task Initiator:

A CoAP client that requests creation of a task. The initiator can be a management client, automation controller, scheduler, or autonomous agent.¶

Executor:

A CoAP server that creates and executes a task resource.¶

Progress Link:

A link from the response to the task resource that was created for an accepted asynchronous operation.¶

Expected Effect:

An optional assertion supplied by the task initiator describing the intended effect of the operation. This document defines only the CoAP option carriage; the semantics of the assertion are application-profile specific.¶

3. Scope

This document specifies:¶

• the lifecycle of a CoAP task resource;¶

• CoAP Options that identify task-control behavior and provide a link to a task resource;¶

• use of existing CoAP methods for monitoring, update, and cancellation;¶

• use of Conditional Query Parameters for CoAP Observe with task-state and task-progress resources; and¶

• a CBOR status representation for task resources.¶

This document does not define a general intent language, a semantic safety model, or an authorization framework for autonomous agents. Those topics are expected to be handled by application profiles or by other IETF work. This document also does not change the base CoAP message layer, token processing, or retransmission behavior.¶

4. Task Lifecycle

A task resource represents an operation that has been accepted for asynchronous processing. The task state is represented by the state machine below.¶

    +---------+       Rejection
    | Pending | -------------------------> [ REJECTED ]
    +---------+
        |
        | Accepted for execution
        v
    +---------+       Cancellation
    | Active  | -------------------------> [ ABORTED ]
    +---------+
        |
        | Execution finishes
        v
  +--------------+
  |  Completed?  | -- Yes ---------------> [ COMPLETED ]
  +--------------+
        |
        | No
        v
    [ FAILED ]

                 Figure 1: Task Lifecycle

The state values are:¶

PENDING:

The task has been received and a task resource exists, but execution has not yet started.¶

ACTIVE:

The task is executing.¶

COMPLETED:

The task completed successfully.¶

FAILED:

The task terminated without successful completion.¶

ABORTED:

The task was canceled before completion.¶

REJECTED:

The task was not accepted for execution, for example because of invalid parameters, conflicting state, missing authorization, or a profile-specific safety policy.¶

An Executor SHOULD keep a terminal task resource available long enough for the Task Initiator to retrieve the final state. The retention time is deployment specific. After the retention time expires, the server MAY remove the task resource and respond to later requests with 4.04 (Not Found).¶

5. CoAP Options

This document defines the following CoAP Options. The option numbers are temporary until IANA assignment.¶

The options are elective. A server that does not understand one of these options processes the request according to normal CoAP option processing. An application profile MAY define stricter behavior when support for a specific option is required.¶

The options are marked unsafe-to-forward because they can affect operation execution or interpretation of the response. A proxy that does not understand these options MUST follow the unsafe option processing rules in [RFC7252].¶

GET /tasks/89/progress?c.st=20&c.pmin=5
Observe: 0

GET /tasks/89/progress?c.st=20&c.pmin=5&c.pmax=60
Observe: 0

6. Task-Resource Mapping

To create a task, a Task Initiator sends a request to an application resource. For example, a client can send a POST request to /actions/climate or a FETCH or PATCH request [RFC8132] to a configuration resource. If the Executor can complete the operation immediately, it MAY return the final response directly. If the Executor accepts the operation for asynchronous processing, it SHOULD return 2.02 (Accepted) and provide a link to the task resource.¶

The task resource is then controlled with existing CoAP methods:¶

GET:

Retrieves the current task status. GET MAY be used with Observe to receive task-state notifications.¶

FETCH:

Retrieves selected task-state information when supported by the task resource.¶

PATCH or iPATCH:

Requests an update to mutable task parameters when the task profile allows in-flight modification.¶

DELETE:

Requests cancellation of the task. A successful cancellation causes the task to transition to ABORTED. If the task has already reached a terminal state, the server SHOULD return the current terminal state or a response code appropriate to the application profile.¶

The task resource URI is an implementation detail of the Executor. Clients MUST NOT infer task semantics from the URI path alone.¶

An Executor MAY expose task status as a compound CBOR representation at the task resource URI. For use with Conditional Query Parameters, the Executor SHOULD also expose scalar projections of task status, such as:¶

/tasks/{id}/state
/tasks/{id}/progress
/tasks/{id}/eta

The /progress resource is a numeric value from 0 to 100. The /state resource is a numeric task-state value defined by this document. The /eta resource, when present, is the estimated number of seconds to completion.¶

7. Protocol Flow

The following example shows an asynchronous operation using a task resource.¶

Task Initiator                              Executor
      |                                        |
      | POST /actions/climate                 |
      | Content-Format: application/cbor      |
      | Expected-Effect: h'a1...'             |
      | Batch-Control: 0x03                   |
      |--------------------------------------->|
      |                                        | Validate request
      |                                        | Create /tasks/89
      |                                        |
      | 2.02 Accepted                         |
      | Location-Path: "tasks"                |
      | Location-Path: "89"                   |
      | Progress-Link: "/tasks/89"            |
      |<---------------------------------------|
      |                                        |
      | GET /tasks/89/progress?c.st=20       |
      |   &c.pmin=5                          |
      | Observe: 0                            |
      |--------------------------------------->|
      |                                        |
      | 2.05 Content                          |
      | Observe: n                            |
      | Payload: 0                            |
      |<---------------------------------------|
      |                                        |
      | 2.05 Content                          |
      | Observe: n+1                          |
      | Payload: 20                           |
      |<---------------------------------------|
      |                                        |
      | PATCH /tasks/89                       |
      | Payload: update parameters            |
      |--------------------------------------->|
      |                                        |
      | 2.04 Changed                          |
      |<---------------------------------------|
      |                                        |
      | 2.05 Content                          |
      | Observe: n+2                          |
      | Payload: 100                          |
      |<---------------------------------------|

8. Payload Formats

Task resources SHOULD use CBOR [RFC8949] for compact status representation. This document defines the following CDDL [RFC8610] structures.¶

Task-Request = {
  ? 1 => uint,              ; client transaction identifier
    2 => [ + Sub-Operation ]
}

Sub-Operation = {
  1 => tstr,                ; target sub-resource path
  2 => uint / tstr / bstr   ; target value or profile-defined value
}

Task-Status = {
  1 => uint,                ; task state
  ? 2 => uint,              ; progress percentage, 0..100
  ? 3 => uint,              ; estimated seconds to completion
  ? 4 => tstr,              ; diagnostic text
  ? 5 => [ + Sub-Result ]   ; per-sub-operation result
}

Sub-Result = {
  1 => tstr,                ; sub-resource path
  2 => uint                 ; CoAP response code encoded as in RFC 7252
}

9. Intermediary Considerations

Intermediaries that understand this specification can recognize the creation of task resources and the subsequent control traffic without parsing application-specific payloads. This can be useful for request routing, traffic prioritization, diagnostics, and policy enforcement in constrained deployments.¶

Intermediaries MUST NOT change task-control options unless explicitly configured to do so by the relevant application profile and security policy. When OSCORE [RFC8613] protects an option end-to-end, intermediaries cannot inspect or modify that option.¶

10. Security Considerations

Task resources can cause physical, operational, or management actions to continue after the initial request has completed. Authorization therefore needs to cover both task creation and subsequent operations on the task resource. Deployments SHOULD use suitable CoAP security mechanisms, such as DTLS, OSCORE [RFC8613], and ACE [RFC9200], according to their threat model.¶

A Task Initiator that is authorized to create a task is not necessarily authorized to observe, modify, or cancel all task resources. Servers SHOULD apply authorization checks independently to task creation, GET/Observe, PATCH, FETCH, and DELETE.¶

Conditional Query Parameters can reduce notification traffic, but they can also hide intermediate progress information from a client. A client that needs every state transition SHOULD observe the task-state resource without conditional notification parameters, or use profile-defined parameters that preserve every state transition. Servers SHOULD ensure that terminal-state information remains available from the task resource after completion, failure, cancellation, or rejection.¶

Expected-Effect can help a server or profile bind a request to an asserted outcome. Because this document does not define the assertion language, servers MUST treat the option according to the application profile that defines that language. A server MUST NOT assume that the mere presence of Expected-Effect is sufficient for safety.¶

Task resources can reveal operational information, such as device activity, failure causes, or expected completion time. Access to task status therefore needs the same care as access to the underlying application resource.¶

11. IANA Considerations

IANA is requested to allocate the following entries in the "CoAP Option Numbers" registry:¶

The option properties are defined in Section 5.¶

This document does not request allocation of a CoAP Option for Observe filtering. Task resources reuse the Conditional Query Parameters defined in [I-D.ietf-core-conditional-attributes].¶

12. References

Acknowledgements

Thanks to Linbo Hui, Yannan Hu, Wenyong Wang, Shuisong Hu, Haoran Luo, and Linzhe Li for their contribution to this draft.¶

Authors' Addresses