]> Zhongguancun Laboratory

Beijing 100094 China lilz@zgclab.edu.cn

Tsinghua University

Beijing 100084 China cuiyong@tsinghua.edu.cn http://www.cuiyong.net/

WIT CoRE CoAP task resource asynchronous operation lifecycle Many operations on constrained devices cannot complete within a single CoAP request and response exchange. Examples include firmware installation, diagnostic procedures, commissioning, calibration, and physical actuation. This document defines a common lifecycle model for representing such operations as addressable CoAP Task Resources. It specifies task creation, state monitoring, discovery, cancellation, terminal-state retention, and eventual removal. It also defines a four-part request payload model, identified by the existing CoAP Content-Format Option, for carrying resource operations together with task execution controls. No new CoAP Option is defined.

Introduction A CoAP request normally produces a response describing the immediate result of applying a method to a resource. Some operations, however, continue after the request has been accepted. A firmware installation may download an image, verify it, install it, and reboot the device. A diagnostic operation may run multiple tests and retain a report. Commissioning and physical actuation may wait for external events or take a substantial amount of time. Applications commonly represent these operations using implementation-specific job identifiers, state fields, polling endpoints, or Observe notifications. Although these mechanisms can work within one application, they do not provide a reusable contract for generic CoAP clients. In particular:

• a client has no common state vocabulary for determining whether an operation is pending, active, completed, failed, aborted, or rejected;
• a lost creation response or a client restart can leave an outstanding task undiscoverable;
• progress alone cannot reliably identify terminal failure or cancellation;
• cancellation is often confused with removal of the resource representing the operation;
• resource-operation semantics and task-execution controls are often carried in application-specific CoAP Options or payloads.

The primary contribution of this document is a common lifecycle for asynchronous Task Resources. A Task Initiator submits an operation using POST. When the Executor accepts the operation for asynchronous processing, it creates a Task Resource and returns the location of that resource. The Task Initiator subsequently retrieves or observes the Task Resource, updates permitted task parameters, or requests cancellation through a cancellation resource using existing CoAP methods.

Conventions and 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 when, and only when, they appear in all capitals, as shown here.

Task Initiator:

A CoAP client that requests an operation that may be processed asynchronously.

Executor:

A CoAP server that accepts, executes, and reports the operation.

Task Resource:

A CoAP resource representing one accepted operation. It exposes task state and MAY expose progress, estimated completion time, diagnostics, and per-resource results.

Task Request:

The four-part payload defined in . It contains resource-operation content and task-execution content.

Resource Operation:

One application operation on a target resource, carried in the Resource content part of a Task Request.

Terminal State:

COMPLETED, FAILED, ABORTED, or REJECTED.

Scope This document specifies:

• a common Task Resource lifecycle and state vocabulary;
• task creation, retrieval, observation, update, and cancellation behavior;
• discovery using CoRE Link Format interface descriptions;
• a four-part Task Request payload identified by Content-Format;

This document does not change the base CoAP message layer, token processing, retransmission behavior, or proxy behavior. It defines no new CoAP Option.

Task Lifecycle A Task Resource represents an operation accepted for asynchronous processing. Its state follows the state machine below.

Task Lifecycle [ REJECTED ] +---------+ | | Waiting for activate v +---------+ cancellation | PENDING | -------------------------> [ ABORTED ] +---------+ | | Accepted for execution v +---------+ Cancellation | ACTIVE | -------------------------> [ ABORTED ] +---------+ | | Execution finishes v +--------------+ | Successful? | -- Yes ---------------> [ COMPLETED ] +--------------+ | | No v [ FAILED ] ]]>

The states are:

PENDING:

A Task Resource exists, but execution has not started.

ACTIVE:

The operation is executing.

COMPLETED:

The operation completed successfully.

FAILED:

Execution terminated without successful completion.

ABORTED:

Execution was canceled before completion.

REJECTED:

The Task Resource was created and remained PENDING, but a dynamic admission decision made before execution determined that the operation could not be started under the current runtime conditions. Examples include insufficient currently available processing capacity, memory, storage, energy, execution slots, or excessive device load. REJECTED MUST NOT be used for an unsupported task type, malformed payload, unsupported execution control, authorization failure, or failure of a profile-specific security or safety requirement. Such failures are detected before Task Resource creation, reported using an appropriate 4.xx response, and do not produce REJECTED. A resource or load failure that occurs after the task becomes ACTIVE produces FAILED rather than REJECTED.

An Executor SHOULD keep a terminal Task Resource available long enough for the Task Initiator to retrieve its final state. Retention time is deployment specific. Where possible, the Executor SHOULD indicate how long the Task Resource is expected to remain available. The applicable application profile defines how this indication is conveyed; this document does not define a retention Option or a new retention field. After the retention period expires, the Executor MAY remove the Task Resource. Subsequent requests to the removed URI SHOULD receive 4.04 (Not Found).

Task Request Payload

Content-Format A Task Request MUST include the CoAP Content-Format Option with value 62, identifying application/multipart-core as defined by . This document does not define or register a new Content-Format. The payload contains exactly two multipart-core parts. The first part carries the Resource representation, and the second part carries the Task representation. Because each multipart-core part consists of a Content-Format identifier followed by a byte string or null, the complete Task Request is encoded as a four-element CBOR array. An Executor that does not support Content-Format 62 for Task Requests MUST respond with 4.15 (Unsupported Content-Format).

Four-Part Payload A Task Request contains four ordered logical parts:

Part	Name	Content
1	Resource Content-Format	The registered CoAP Content-Format identifier for Part 2
2	Resource representation	A byte string containing resources and values to be operated on
3	Task Content-Format	The registered CoAP Content-Format identifier for Part 4
4	Task representation	A byte string containing task controls, or null when no Task content is supplied

The parts have the following semantics:

1. The first element is the registered CoAP Content-Format identifier of the Resource representation carried in the second element. An application profile selects this value. For example, the value is 60 when the Resource representation uses application/cbor.
2. The second element is a non-empty CBOR byte string containing exactly one Resource representation encoded according to the first element.
3. The third element is the registered CoAP Content-Format identifier of the Task representation carried in the fourth element. This document uses 60 (application/cbor) for the Task-Content map defined below.
4. The fourth element is a CBOR byte string containing exactly one Task-Content map encoded using application/cbor. It MAY be null when the request carries no execution mode or profile-specific task parameters.

The values in the first and third elements identify the embedded representations; they are not format-version numbers. In particular, the outer value 62 MUST NOT be repeated in either position unless the corresponding embedded representation is itself another application/multipart-core representation.

Encoding The complete Task Request has the following CDDL structure, using the multipart-core rules from : execution-mode, ? 2 => profile-parameters } execution-mode = atomic / sequential atomic = 1 sequential = 2 profile-parameters = { * int => any } ]]> The byte string in resource-representation MUST be interpreted according to resource-content-format and the applicable application profile. The byte string in task-representation, when present, MUST contain exactly one well-formed CBOR data item matching Task-Content; no bytes may remain after that item is decoded. The outer multipart-core array, the Task-Content map, and CBOR Resource representations defined by an application profile SHOULD use the deterministic encoding requirements in Section 4.2.1 of . Indefinite-length items MUST NOT be used in the outer array or Task-Content map. A receiver MUST reject the complete Task Request with 4.00 (Bad Request) if:

• the outer array does not contain exactly four elements;
• the first or third element is not an unsigned integer;
• the Resource representation is absent, null, or empty;
• the fourth element is neither a byte string nor null;
• the third element is not 60 when the fourth element is a byte string; or
• an embedded representation is malformed according to its Content-Format.

The Executor MUST NOT apply any Resource Operation from a malformed Task Request. If Content-Format 62 is supported but an embedded Content-Format is not supported for the applicable profile, the Executor MUST respond with 4.15 (Unsupported Content-Format).

Resource Operations The Resource content part identifies target resources and the content to be applied to them. Every target MUST be within the authorization scope of the request. An application profile MUST define how resources are identified, how operation order is represented, and which value types and operations are permitted. The representation is profile-defined because firmware management, diagnostics, commissioning, and actuation differ. A profile SHOULD reuse an existing resource representation where possible and MUST specify how its contents are applied.

Task Execution Controls The Task content part can carry these execution modes:

atomic (1):

The Resource Operations form one atomic unit. The Executor MUST either apply all operations successfully or leave all targets unchanged. An Executor that does not support this guarantee for the requested task type or Resource Operations MUST reject the request with 4.22 (Unprocessable Entity) and MUST NOT create a Task Resource. An Executor that supports the guarantee but cannot admit the created task because of current runtime resource availability follows the dynamic admission procedure in and transitions the Task Resource to REJECTED.

sequential (2):

The Executor applies Resource Operations in the order expressed by the Resource content part. The application profile defines whether execution stops after the first failed operation. Task-Status SHOULD include per-operation results when more than one operation was attempted.

For more than one Resource Operation, Task content MUST state the requested execution mode unless equivalent semantics are defined by the application profile. For one operation, the mode MAY be omitted. Task controls are interpreted only by the Task Initiator and Executor. Intermediaries are not required to understand the representation. Profiles MAY instead define equivalent semantics through collection or interface behavior.

Example The following example uses multipart-core diagnostic notation. The Resource representation and Task representation both use Content-Format 60 (application/cbor). The example Resource representation h'A101F5' is a profile-defined CBOR map, while h'A10102' encodes the Task-Content map {1: 2}, requesting sequential execution. The complete encoded payload for this example is: If the same request carries no Task content, the fourth element is null:

Task-Resource Mapping

Creation A Task Initiator submits a Task Request using POST to an operation-submission resource or task collection identified by the application profile. POST is used because processing the request creates a distinct Task Resource whose URI is returned by the Executor. This document does not use PATCH or iPATCH to submit a Task Request: those methods apply changes to the resource identified by the request URI, whereas Task Request submission creates a separate Task Resource. If the Executor accepts the operation for asynchronous processing, it MUST create a Task Resource and return 2.01 (Created). The response MUST include one or more Location-Path Options identifying the Task Resource. This specification does not use Location-Query to identify a Task Resource. Location is the sole protocol mechanism defined here for returning the Task Resource URI. A client MUST NOT depend on a separate task-link Option. Before returning 2.01 (Created), the Executor MUST complete pre-creation validation. This validation MUST include the Task Request structure and embedded representations, support for the requested task type and Resource Operations, support for the requested execution controls, authorization for every target, and all profile-specific security and safety requirements. If pre-creation validation fails, the Executor MUST return an appropriate 4.xx response and MUST NOT create a Task Resource. After creating the Task Resource and while it remains PENDING, the Executor MAY perform dynamic admission based on runtime conditions that can vary after creation. These conditions include currently available processing capacity, memory, storage, energy, execution slots, and device load. If dynamic admission determines that the operation cannot be started, the Executor MUST transition the Task Resource to REJECTED. The Executor MUST NOT use REJECTED for a condition that was required to be checked during pre-creation validation.

Methods on a Task Resource

GET:

Retrieves Task-Status or another selected representation. A Task Resource MAY be observable using CoAP Observe .

FETCH:

Retrieves selected task-state information when supported by the profile.

PATCH and iPATCH :

Update mutable task parameters when permitted by the profile. An update MUST NOT change the identity of the represented operation.

DELETE:

Requests removal of the Task Resource, consistently with . The Executor MUST NOT interpret DELETE as a cancellation request. If deletion is permitted and succeeds, the Executor SHOULD return 2.02 (Deleted), and the Task Resource URI is no longer available. An Executor SHOULD reject deletion of a PENDING or ACTIVE task with 4.09 (Conflict) unless an application profile explicitly permits removal while execution continues.

An Executor MAY remove a terminal Task Resource automatically after its retention period. Explicit DELETE and automatic retention expiry have the same resource-removal semantics.

Cancellation Resource An Executor that supports cancellation MUST expose a cancellation resource associated with each cancellable Task Resource. The cancellation resource is identified by appending the single path segment cancel to the Task Resource URI. For example, if the Task Resource URI is /tasks/89, the cancellation resource URI is /tasks/89/cancel. The Task Initiator requests cancellation by sending POST to this resource. If cancellation is not supported for the Task Resource, the Executor MUST return 4.04 (Not Found) or 4.05 (Method Not Allowed), as applicable. If the task is PENDING or ACTIVE and cancellation succeeds, the Executor SHOULD return 2.04 (Changed) and transition the Task Resource to ABORTED. The Task Resource remains available during its retention period so clients can retrieve the terminal state. If the task is already terminal, the Executor SHOULD return 4.09 (Conflict), unless the application profile defines cancellation as idempotent and permits a success response. Refusal to cancel because stopping the underlying operation would be unsafe SHOULD also use an appropriate error response and MUST NOT change the current task state.

Task Status Subresources An Executor MAY expose subordinate resources identified by appending the corresponding path segment to the Task Resource URI: For example, if the Task Resource URI is /tasks/89, the state subresource URI is /tasks/89/state. /state contains the numeric state value defined in . /progress contains an unsigned integer from 0 to 100. /eta contains estimated seconds to completion. Successful responses from /state, /progress, and /eta MUST include Content-Format 60 (application/cbor). Each response payload MUST contain exactly one CBOR unsigned integer. For /state, the integer is one of the state values defined in . For /progress, it is in the range 0 to 100. For /eta, it is the estimated number of seconds to completion. A client MUST determine terminal status using /state or the state field of a Task-Status representation. Progress is informational. FAILED, ABORTED, and REJECTED are not required to report progress 100.

Conditional Observation Task-state and task-progress resources MAY support Conditional Query Parameters defined by . This reduces Observe traffic without defining task-specific query parameters. For example: A client needing every transition SHOULD observe /state without a step condition. Conditional reporting MUST NOT make terminal state permanently unavailable.

Task Discovery Task Resources SHOULD be discoverable using CoRE Link Format and its interface description mechanism. This document defines no new discovery protocol. ;if="core.task" ]]> A client can request Task Resources using: Subject to authorization and privacy policy, retained terminal Task Resources SHOULD remain discoverable during retention. This permits a restarted client to recover outstanding or recently completed tasks. Executors MUST NOT expose task existence, target paths, status, or diagnostics to unauthorized clients through discovery.

Task Status Payload Task-Status is encoded using CBOR and described using CDDL . A response carrying a Task-Status representation MUST include Content-Format 60 (application/cbor). task-state, ; task state ? 2 => progress, ; progress percentage ? 3 => uint, ; estimated seconds to completion ? 4 => tstr, ; diagnostic text ? 5 => [ + Sub-Result ] ; per-resource-operation result } task-state = 0..5 progress = 0..100 coap-response-code = 0..255 Sub-Result = { 1 => tstr, ; target resource path 2 => coap-response-code ; CoAP response code } ]]> The state values are:

Value	State
0	PENDING
1	ACTIVE
2	COMPLETED
3	FAILED
4	ABORTED
5	REJECTED

The compound representation is used when a client needs complete state in one response. Task Status Subresources SHOULD return only the corresponding individual task-status value. A client MUST determine terminal status from state, not progress. A Task-Status representation containing a state or progress value outside the ranges defined above is malformed. The response code in a Sub-Result is the 8-bit CoAP Code value. An Executor MUST NOT generate an unassigned or reserved CoAP response code in a Sub-Result.

Workflow The scalar state payloads in the following exchanges are shown in CBOR diagnostic notation. Responses carrying these payloads use Content-Format 60 (application/cbor). | | | | 2.01 Created | | Location-Path: "tasks" | | Location-Path: "89" | |<----------------------------------------| | | | GET /tasks/89/state | | Observe: 0 | |---------------------------------------->| | | | 2.05 Content | | Content-Format: 60 | | Payload: 1 (ACTIVE) | |<----------------------------------------| | | | 2.05 Content | | Content-Format: 60 | | Payload: 2 (COMPLETED) | |<----------------------------------------| ]]> Failure, cancellation, or rejection produces FAILED, ABORTED, or REJECTED rather than relying on progress reaching 100. Cancellation, when needed, uses a separate interaction: | | | | 2.04 Changed | |<----------------------------------------| | | | GET /tasks/89/state | |---------------------------------------->| | | | 2.05 Content | | Content-Format: 60 | | Payload: 4 (ABORTED) | |<----------------------------------------| ]]>

Error Handling The Executor MUST reject a request before creating a Task Resource when:

• the Task Request structure or an embedded representation is malformed;
• the requested task type, Resource Operation, or execution control is not supported;
• a target or operation is not allowed;
• authorization for any target fails;
• a profile-specific security or safety requirement is not satisfied.

4.15 (Unsupported Content-Format) is used when the media type is unsupported. 4.00 (Bad Request) is used when the multipart-core structure or an embedded representation is malformed. 4.22 (Unprocessable Entity) is used when a syntactically valid request asks for semantics that the Executor cannot provide, including an unsupported execution guarantee. Authorization errors use the code required by the security profile. Insufficient runtime resources or excessive device load discovered during dynamic admission after Task Resource creation are reported using REJECTED. Once a task becomes ACTIVE, inability to continue execution is reported using FAILED and optional diagnostics and Sub-Result fields.

Security Considerations Task Requests can change multiple resources and initiate long-running physical or administrative operations. The Executor MUST authorize the complete request, including every target and requested execution control, before creating a Task Resource. Atomic execution can require buffering, rollback state, or durable storage. The Executor MUST reject atomic mode unless it can preserve all-or-nothing behavior across relevant failures. Profiles SHOULD define whether this includes power loss and reboot. Attackers can create expensive tasks to exhaust processing, storage, bandwidth, or energy. Executors SHOULD apply admission control, authorization, quotas, request-size limits, task-count limits, and retention limits. Discovery and Task-Status can expose operational history, target paths, and diagnostics. Access MUST be protected according to application policy. Task Requests remain end-to-end application data. A proxy can recognize Content-Format 62 as application/multipart-core without understanding the application semantics of the two embedded representations. Such a proxy is not expected to inspect Task-Content or enforce execution controls. Deployments requiring confidentiality or integrity across intermediaries SHOULD use an appropriate end-to-end security mechanism. Cancellation can be safety-sensitive. The Executor MUST authorize POST to the cancellation resource and MAY reject it when stopping the underlying operation would be unsafe. DELETE authorization is separate and controls removal of the Task Resource, not cancellation of the underlying operation.

IANA Considerations

Task Request Content-Format This document uses the existing application/multipart-core CoAP Content-Format (ID 62) registered by . It requests no new media type or CoAP Content-Format identifier.

Interface Description Registration IANA is requested to register:

Value:

core.task

Description:

CoAP Task Resource for an asynchronous or long-running operation.

Reference:

This document.

Implementation Considerations An Executor can persist Task Resource state independently from the execution engine. Persisting state, request identity, and final result allows recovery after reboot and reduces duplicate work after application retries. Profiles should define limits on Resource Operations, request size, execution modes, mutable task fields, and retention. They should also define how a client correlates a retry with an existing task when duplication is unsafe.

Changes from draft-li-coap-task-resources-00

• Removed the Batch-Control and Progress-Link CoAP Options.
• Made Location the sole mechanism for returning the Task Resource URI.
• Added a four-part Task Request payload identified using Content-Format.
• Encoded the four elements using the existing application/multipart-core Content-Format (ID 62), with one Resource representation and one Task representation.
• Moved atomic and sequential controls into Task content.
• Updated examples, error handling, proxy behavior, and security text.
• Separated cancellation from deletion: POST to the cancel subresource of a Task Resource requests cancellation, while DELETE removes the Task Resource.
• Distinguished pre-creation validation from post-creation dynamic admission and clarified the use of REJECTED.
• Constrained Task-Status state, progress, and CoAP response-code values in CDDL.

Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This specification defines Web Linking using a link format for use by constrained web servers to describe hosted resources, their attributes, and other relationships between links. Based on the HTTP Link Header field defined in RFC 5988, the Constrained RESTful Environments (CoRE) Link Format is carried as a payload and is assigned an Internet media type. "RESTful" refers to the Representational State Transfer (REST) architecture. A well-known URI is defined as a default entry point for requesting the links hosted by a server. [STANDARDS-TRACK] The Constrained Application Protocol (CoAP) is a specialized web transfer protocol for use with constrained nodes and constrained (e.g., low-power, lossy) networks. The nodes often have 8-bit microcontrollers with small amounts of ROM and RAM, while constrained networks such as IPv6 over Low-Power Wireless Personal Area Networks (6LoWPANs) often have high packet error rates and a typical throughput of 10s of kbit/s. The protocol is designed for machine- to-machine (M2M) applications such as smart energy and building automation. CoAP provides a request/response interaction model between application endpoints, supports built-in discovery of services and resources, and includes key concepts of the Web such as URIs and Internet media types. CoAP is designed to easily interface with HTTP for integration with the Web while meeting specialized requirements such as multicast support, very low overhead, and simplicity for constrained environments. The Constrained Application Protocol (CoAP) is a RESTful application protocol for constrained nodes and networks. The state of a resource on a CoAP server can change over time. This document specifies a simple protocol extension for CoAP that enables CoAP clients to "observe" resources, i.e., to retrieve a representation of a resource and keep this representation updated by the server over a period of time. The protocol follows a best-effort approach for sending new representations to clients and provides eventual consistency between the state observed by each client and the actual resource state at the server. The methods defined in RFC 7252 for the Constrained Application Protocol (CoAP) only allow access to a complete resource, not to parts of a resource. In case of resources with larger or complex data, or in situations where resource continuity is required, replacing or requesting the whole resource is undesirable. Several applications using CoAP need to access parts of the resources. This specification defines the new CoAP methods, FETCH, PATCH, and iPATCH, which are used to access and update parts of a resource. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. This memo defines application/multipart-core, an application-independent media type that can be used to combine representations of zero or more different media types (each with a Constrained Application Protocol (CoAP) Content-Format identifier) into a single representation, with minimal framing overhead. The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. These design goals make it different from earlier binary serializations such as ASN.1 and MessagePack. This document obsoletes RFC 7049, providing editorial improvements, new details, and errata fixes while keeping full compatibility with the interchange format of RFC 7049. It does not create a new version of the format. Tampere University Dogtiger Labs Qualcomm Technologies, Inc. This specification defines Conditional Notification and Control Query Parameters compatible with CoAP Observe (RFC7641).

Acknowledgments The authors thank CoRE Working Group participants who reviewed earlier versions and encouraged the document to focus on the reusable task lifecycle, reuse existing discovery and observation mechanisms, and avoid unnecessary CoAP Options.