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

Canonical: https://protocol.diverge.network/2.3.0/endpoints/volumes-filetree/
Specification revision: 2.3.0

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](/2.3.0/endpoints/volumes-filetree/request/) states its form.
- **The volume named.** The client names a volume by the `name` its
  [volumes::list](/2.3.0/endpoints/volumes-list/) listing gave it. The
  server resolves the name against the identity under which the
  connection was authorized, as [Authorization](/2.3.0/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](/2.3.0/endpoints/containers-agents-run/client/filetree/response/)
  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](/2.3.0/endpoints/volumes-filetree/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](/2.3.0/endpoints/volumes-fuse-serve/client/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](/2.3.0/endpoints/volumes-fuse-serve/) of the
  client holds, or that is under a
  [volumes::stat](/2.3.0/endpoints/volumes-stat/),
  [volumes::read](/2.3.0/endpoints/volumes-read/),
  [volumes::write](/2.3.0/endpoints/volumes-write/),
  [volumes::filetree](/2.3.0/endpoints/volumes-filetree/),
  [volumes::edit](/2.3.0/endpoints/volumes-edit/) or
  [volumes::delete](/2.3.0/endpoints/volumes-delete/), at the time of the
  request. A request naming such a volume is answered with the
  refusal the [response](/2.3.0/endpoints/volumes-filetree/response/) states for who holds it —
  `Mounted`, `FuseServed` or `Held` — decided in the order
  [Capabilities](/2.3.0/capabilities/#the-hold) 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](/2.3.0/capabilities/#the-volume-modes)
  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.