]> Zhongguancun Laboratory

Beijing 100094 China lilz@zgclab.edu.cn

Tsinghua University

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

WIT CORE Working Group CoAP Task Resource Observe CBOR Many CoAP deployments need to start operations that cannot be completed within one request/response exchange. Existing deployments commonly model these operations with application-specific resources, payload formats, and polling or notification conventions. This makes clients, gateways, and proxies unable to interoperate across implementations that expose otherwise similar long-running operations. This document defines a CoAP task-resource pattern for asynchronous operations. It specifies a small set of CoAP Options and a CBOR status representation that allow a server to create a temporary task resource, allow a client to monitor, update, or cancel that task using existing CoAP methods, and allow task-state and task-progress observations to reuse the Conditional Query Parameters defined for CoAP Observe . The mechanisms are intended to be generally usable for constrained applications that need interoperable task orchestration.

Introduction The Constrained Application Protocol (CoAP) 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 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. Management clients, schedulers, automation controllers, and other CoAP clients can use the same task resource model without requiring application-specific task-state conventions.

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:

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, or scheduler.

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.

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 model for device capabilities or operation effects, or an authorization framework. 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.

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. [ 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).

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

Name	No.	C/E	U/N	R	Format	Length
Batch-Control	TBD1	E	U	-	uint	0-2
Progress-Link	TBD2	E	U	-	string	1-255

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 .

Batch-Control Option The Batch-Control Option indicates how sub-operations contained in the request payload are intended to be executed. The option value is a bit mask:

• 0x01 (Atomic): the server is requested to apply the sub-operations as an atomic unit. If one sub-operation fails, the server rolls back all sub-operations for which rollback is supported.
• 0x02 (Sequential): the server is requested to execute the sub-operations in the order in which they appear in the payload.

If the server cannot provide the requested behavior, it MUST reject the request with 4.00 (Bad Request) or 4.09 (Conflict), unless an application profile defines different behavior. A server MUST NOT silently treat an Atomic request as non-atomic.

Use of Conditional Attributes with Task Resources This document does not define a new CoAP Option for filtering Observe notifications. Task resources reuse the Conditional Query Parameters defined for CoAP Observe in . Task resources that are Observable SHOULD support the Conditional Query Parameters when they expose task information as scalar resources. For example, a client that observes task progress and wants to receive a notification only when the progress changes by at least 20 percentage points, and no more frequently than once every 5 seconds, can use: A client that wants a maximum interval between progress notifications can also use c.pmax, for example: The task progress value is a scalar numeric value in the range 0..100 and is therefore suitable for use with Conditional Query Parameters such as c.st, c.gt, c.lt, c.pmin, and c.pmax. Task state is an enumerated value. Application profiles that expose task state as a conditionally observable value SHOULD define whether the state is observed as a numeric scalar value or as a separate state resource. A client that needs to observe every state transition SHOULD observe the task-state resource without conditional notification parameters, or use parameters that are guaranteed by the profile to report each state transition.

Progress-Link Option The Progress-Link Option is returned in a successful response when a server has created a task resource for an accepted asynchronous operation. The option value is a URI-reference encoded as a UTF-8 string. The value identifies the task resource. A server SHOULD use Location-Path and Location-Query when they are sufficient to identify the task resource. Progress-Link is useful when a compact single option or an absolute URI-reference is needed by a profile. If both Progress-Link and Location-Path/Location-Query are present, they MUST identify the same task resource.

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 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: 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.

Protocol Flow The following example shows an asynchronous operation using a task resource. | | | 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 | |<---------------------------------------| ]]>

Payload Formats Task resources SHOULD use CBOR for compact status representation. This document defines the following CDDL structures.

Task Creation Payload Application profiles define the payload used to create a task. When a profile uses a generic multi-operation payload, it MAY use the following structure: 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 Payload The task resource status payload is: 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 } ]]> The task state values are:

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

Scalar Projection Resources The compound Task-Status representation is useful when a client needs the complete task state in one response. It is not intended to define field-level filtering of a CBOR map. When a server supports conditional observation of task information, it SHOULD expose scalar projection resources for the values to which Conditional Query Parameters are applied. In particular, /tasks/{id}/progress SHOULD return the progress value alone, and /tasks/{id}/state SHOULD return the numeric task state value alone. Application profiles MAY define additional projection resources.

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 protects an option end-to-end, intermediaries cannot inspect or modify that option.

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 , and ACE , 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. 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.

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

Number	Name	Reference
TBD1	Batch-Control	RFC-to-be
TBD2	Progress-Link	RFC-to-be

The option properties are defined in . This document does not request allocation of a CoAP Option for Observe filtering. Task resources reuse the Conditional Query Parameters defined in .

References Normative References Tampere University Dogtiger Labs Qualcomm Technologies, Inc. This specification defines Conditional Notification and Control Query Parameters compatible with CoAP Observe (RFC7641). 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. 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. 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. Informative References This document defines Object Security for Constrained RESTful Environments (OSCORE), a method for application-layer protection of the Constrained Application Protocol (CoAP), using CBOR Object Signing and Encryption (COSE). OSCORE provides end-to-end protection between endpoints communicating using CoAP or CoAP-mappable HTTP. OSCORE is designed for constrained nodes and networks supporting a range of proxy operations, including translation between different transport protocols. Although an optional functionality of CoAP, OSCORE alters CoAP options processing and IANA registration. Therefore, this document updates RFC 7252. This specification defines a framework for authentication and authorization in Internet of Things (IoT) environments called ACE-OAuth. The framework is based on a set of building blocks including OAuth 2.0 and the Constrained Application Protocol (CoAP), thus transforming a well-known and widely used authorization solution into a form suitable for IoT devices. Existing specifications are used where possible, but extensions are added and profiles are defined to better serve the IoT use cases.

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