volumes::filetree

Tag 7: a client names a volume from its listing and a subtree of it; the server sends exactly one response carrying the tree of that subtree as a snapshot, or an error, and the scope finishes; nothing is watched and no change is sent.

A client opens the scope with a request whose payload is the tag byte 7 followed by the name of a volume and the path of a subtree of it. The server sends exactly one response, which is either the tree or an error. The response finish follows the response, and no frame follows the finish.

The request. The request carries the name of one volume and a path, which may be empty. Request states its form.
The volume named. The client names a volume by the name its volumes::list listing gave it. The server resolves the name against the identity under which the connection was authorized, as Authorization provides. A name that is not in the client’s listing is answered with an error. A client cannot name another client’s volume.
The path. The path is a sequence of components from the root of the volume: the same components a volume mount’s volume_relative_path names. An empty path names the root of the volume. No component is empty, . or .., or contains / or NUL; a request whose path is not of that form is answered with an error. A path at which nothing is, and a path at which what is there is not a directory, are answered with an error.
The tree. The answer carries the entries of the directory the path names, each with everything beneath it, as the nodes of a snapshot in the form the filetree channel defines. The tree is the subtree at rest, at the time of the response: no container changes the volume while the server walks it. Response states its form.
A snapshot, not a watch. The response is the whole of the exchange. The server sends no change after it, and every Directory in the tree has changes 0. A volume being served is watched, as the FUSE serve sees it, by the filetree channel of its serve; this request is answered with an error while a FUSE serve holds the volume. A client that needs the tree as it is later sends another request.
A held volume is not walked. The server does not walk a volume that a running container of the client holds, that a volumes::fuse_serve of the client holds, or that is under a volumes::stat, volumes::read, volumes::write, volumes::filetree, volumes::edit or volumes::delete, at the time of the request. A request naming such a volume is answered with the refusal the response states for who holds it — Mounted, FuseServed or Held — decided in the order Capabilities states for an operation, and nothing is changed. The server holds the volume to itself from the moment it accepts the request until the response finish, and a run, a FUSE serve or another operation naming the volume is refused for as long as it does.
The error. An error states that the tree was not sent, and that nothing was determined about the volume. A volume absent from the client’s listing, a path that is not of the stated form, and a path that names no directory are each answered with an error. A volume that something holds is answered with the refusal the response states, which is not an error.
No volume at all. A server that holds out none of the three mode objects of Capabilities keeps no volume and answers every request of this endpoint with exactly one response, the byte 4 alone, and the response finish, before anything is looked up. Every other requirement of this page holds for a server that keeps volumes.

In this section

Request — The payload is the tag byte 7 followed by the name of the volume as a varint length and UTF-8 bytes and the path of the subtree as a varint count of components each a varint length and UTF-8 bytes, in the postcard wire format.
Response — The server sends exactly one response, whose payload begins with the byte 0 followed by the tree in the postcard wire format, a varint count of nodes followed by that many nodes; is the byte 1, 2 or 3 alone when a running container, a FUSE serve or an operation holds the volume; is the byte 4 alone when the server keeps no volume; or begins with the byte 5 followed by an error as one JSON value; and the response finish follows it.