volumes::edit

Tag 12: a client names a volume from its listing and states a change to it, its size, its mode, or both; the server sends exactly one response stating that the volume has what was stated, that the server has insufficient capacity for the size, that the content of the volume exceeds the size, or an error, and the scope finishes; the size and the mode are the only properties an edit changes.

A client opens the scope with a request whose payload is the tag byte 12 followed by the name of a volume and a change: a size, a mode, or both. The server sends exactly one response, which states that the volume has what was stated, that the server has insufficient capacity for the size stated, that the content of the volume exceeds the size stated, that the server keeps no volume of the mode stated, that something holds the volume, that the server keeps no volume, 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 one change, which is one of three kinds: a size in bytes, a mode, or a size and a mode together. 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. A server may refuse to edit a volume that it offered on its own account and that the client did not create; the refusal is an error.
• The size. A change that states a size states the size the volume has after the edit, not a change to its size: the size is absolute. When the server sends the byte 0, the volume has the size stated. From that moment, every volumes::list listing and every volumes::stat response of the client reports that size as bytes, and every list scope the client holds open is sent the volume as changed, until a later edit changes it.
• The mode. A change that states a mode states the mode the volume has after the edit, persistent, ephemeral or read_only, as volumes::create defines the three. When the server sends the byte 0, the volume has the mode stated. From that moment, every listing and every stat of the client reports that mode as mode, and every list scope the client holds open is sent the volume as changed, until a later edit changes it, and every container the client mounts the volume in after that moment, and every FUSE serve of it after that moment, is bound under that mode. The content of the volume is as it was: a volume made ephemeral or read_only holds what it held, and a volume made persistent holds what it held, which is what it had before any run or serve under ephemeral.
• Both, or neither. A change that states a size and a mode is one edit. When the server sends the byte 0, the volume has both. When the server sends the byte 1 or the byte 2, the volume has neither: its mode is as it was before the request, as its size is. The server does not change the mode of a volume whose size it refuses.
• What an edit changes. The size and the mode are the only properties an edit changes: the name, the content, the bytes in use and the hash of the content are as they were before the request. Response states the form of the response.
• Insufficient capacity. When the server cannot reserve the size stated, it does not change the size and sends the byte 1. The volume has the size it had before the request. The server does not send the byte 0 for a size it cannot reserve. The number of bytes by which the volume can grow at a given time is reported by volumes::edit_capacity.
• Content too large. When the size stated is smaller than the number of bytes the volume holds, the server does not change the size and sends the byte 2. The volume has the size it had before the request, and its content is as it was. The server does not send the byte 0 for a size that the content of the volume exceeds. A client that wants the smaller size removes content from the volume, by a container in which the volume is mounted, and asks again.
• A held volume is not edited. The server does not change the size or the mode of 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 mode must be kept. A change that states a mode — as Mode, or as Both — for which the server holds out no mode object is answered with ModeUnsupported, the byte 3, after the server has found the volume in the client’s listing and before it holds the volume; the volume has the size and the mode it had before the request, and every container that mounts it and every FUSE serve of it is unaffected.
• The error. An error states that nothing was changed, for a reason other than capacity, content, the mode or a hold: the volume has the size and the mode it had before the request, and every listing and every stat reports them. A volume absent from the client’s listing is answered with an error. A volume that something holds, and a change naming a mode the server does not keep, are each 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 7 alone, and the response finish, before anything is looked up. Every other requirement of this page holds for a server that keeps volumes.