Everything over CoAP

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 5 September 2024.¶

Copyright Notice

Copyright (c) 2024 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

[ See abstract for now ]¶

2. Applications

Appendix A. CoAP File Service

This sketches [ TBD: describes ] a file transfer protocol / remote file system built on top of CoAP.¶

A file server works similar to a WebDAV server, and follows these rules (which are sometimes expressed from the point of view of the server, but apply when a client maps them back into a file system in such a way that operations can round-trip):¶

• Directories are unconditionally represented by URIs with a trailing slash; files by those without one.¶

  The GET operation is used to list them (for there is no PROPFIND operation in CoAP). Different media types migth be used depending on the capabilities of the parties, with application/link-format as a base line.¶

  (Note that application/link-format is not particularly efficient for this purpose, as the directory listing needs to repeat the requested resource's full path for each entry).¶

  Clients need to be prepared for links that do not follow the regular pattern of a directory advertising its children, but (as with all unknown links) may ignore them.¶

• Paths are constructed by placing directory names and either an empty string (for the trailing slash) or the unescaped file name in Uri-Path options.¶
• Clients may attempt to treat any URI composed of the file server entry URI and additional path segments as files on the file server. Consequently, any additional services the file server may provide (e.g., as resources specified in extensions) are necessarily assigned URIs with a query, for these can not be inadvertedly constructed in an attempt to access a file.¶

• For lack of a HEAD option, file metadata can only be obtained by performing a GET on the directory containing the file, or a FETCH for efficiency if suitable media types are defined.¶

  All metadata is provided on a best-effort basis, and the supported directory formats limit what can be expressed. Typical supported metadata are the media type (expressed as ct in link format) and the size (sz).¶

• If write support is available and permissions allow, a client can create files by performing a PUT operation on a previously nonexistent resource.¶

  Files can be overwritten by PUTting a new representation. Files sent with block-wise transfer should be processed atomically by the server unless explicitly negotiated otherwise. (On POSIX file systems, this can be implemented without additional state by storing the blocks in a temporary file whose name contains the original file name and the block key of the request, and renaming it to the target name when receiving the last block).¶

  Directories can be created with PUT as well (it is clear from their path that they are directories); these would typically be empty and not have a content format, but may use a content format that already describes directory metadata. (It is up to the client to fall back to plain directory creation, if that is a viable option for it -- it would be if it's just about unimportant metadata, but might not if the initial metadata indicates an ACL).¶

• Files and directories can be removed using the DELETE operation, subject ot the same conditions as writing to resources.¶

  Deleting directories is recursive; client that desire POSIX semantics need to check whether the directory is empty and use the If-Match option with the empty directory's ETag to avoid race conditions.¶

• Regular CoAP extensions apply if the parties support them, for example:¶

  • Observation can be used to watch files or directories for changes.¶

  • ETags (e.g. derived from the file's stats) can be used to ensure that large files are assembled correctly by the client, and to perform file updates with optimistic locking by using the If-Match option.¶

    Note that ETags are always "strong" in CoAP: They indicate that a precise representation of a resource has not changed. If a resource has different representations (eg. a directory listing may be available in different media types), they may have different ETags. They may also have identical ETags, but that means that if one format carries less information, its ETag needs to change when any representation changes, not just the selected one.¶

    Consequently, if a client learns of a resource's ETag and revalidates that that ETag is still valid, it can not know which properties of the resource have stayed constant. (In the extreme case, the representation might merely express that the resource exists). Only when knowing the representation, or at least relevant metadata of the tagged representation, can the client be sure that an ETag's validity has any meaning beyond that the resource still exists.¶

    For file services backed by content based naming systems (such as git), it is tempting to use content identifiers for ETags -- consequently, a directory will be flagged as changed when any file below it changes. To allow monitoring directories for additions and removal of files, it is RECOMMENDED that a representation is provided that does not contain the contained files' and directories' ETags, and has a stable ETag that is distinct from any representation that does include them. There is no recommendation as to whether the default representation should contain ETags or not.¶

• Additional features can be specified and advertised separately, either per resoource or by a named specification that provides templates for further operations.¶

  For example, a specification might say that when a file system is advertised with a given interface (if parameter of link format), for each file and directory there is an associated resource at ?acl that describes access control applicable to that file, and can be used with GET and PUT as per the ACL's policies.¶

  Additional operations can use their custom media types and methods, and possibly create more resources. For example, a server-to-server copy (again, advertised by a suitable interface parameter) could provide a ?copy resource under any directory, to which a CBOR list containing two CRIs (source and destination) would be posted. That specification might describe that if copies are not completed instantly, the response might indicate a new location using Uri-Path and Uri-Query options (the latter might be necessary to not conflict with existing files) which tracks the status of the operation.¶

• File service is compatible with "index.html" style directory indices provided statically in the file system. It is recommended to not serve index files of typical directory listing formats (such as application/link-format) as these might mislead the client about the file system's content, and prevent clients that access the server as a file server from even seeing the providing file's name.¶

  These files still need to be written to or deleted in their file version (e.g. as "index.html"); the file server may use yet to be specified link relations to point out which files are being served as the index files.¶

Some implementation guidance should be provided around the interaction between idempotent requests that have no actual effect and preconditions: If a DELETE with If-Match is transmitted again on a new token (by a proxy relying on its idempotence), should the server respond Deleted rather than Not Found? If a PUT with If-Match is transmitted again after it has been acted on, should the server respond Changed rather than Precondition Failed? (Probably "No" to both, as the former is easily recognizable by the client, and the latter would delay faulting by long, but still needs further thought.)¶

Appendix B. Change log

From -03 to -04:¶

• Add section about tunneling¶
• Extend notes on theuse of ETags on file servers¶

From -02 to -03:¶

• Added Runtime configuration section¶
• Terminal access now has an implementation¶

From -01 to -02:¶

• Added "Web browsing" section¶

From -00 to -01:¶

• Added details to file service¶

Author's Address