volumes::create

Tag 10: a client names a volume, its size in bytes and its mode; the server sends exactly one response stating that the volume exists, that the server has insufficient capacity for it, or an error, and the scope finishes; the volume persists until the client deletes it.

A client opens the scope with a request whose payload is the tag byte 10 followed by the name, the size and the mode of the volume. The server sends exactly one response, which states that the volume exists, that the server has insufficient capacity for it, that the server keeps no volume of the mode stated, 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 a name the client chooses, a size in bytes, and the mode the volume starts in. Request states its form.
The mode. The request states mode, one of persistent, ephemeral and read_only, and the volume has that mode from the moment it exists, until a volumes::edit request changes it. Every volumes::list listing of the client reports it as mode, and every listing the client holds open reports a change to it. When it is persistent, every change a container makes to the volume is in the volume when the container ends, every change a volumes::fuse_serve makes is in the volume, any number of running containers may mount the volume at once — every one of them mounts the one volume, a change any of them makes is in the volume for every other as the volume’s filesystem makes it visible, and the order of changes made at once is the filesystem’s and is not prescribed — and at most one FUSE serve holds the volume at a time, never beside a running container. When it is ephemeral, the volume is as it was before each run when the container ends, every container sees the content of the volume as of that container’s start, every FUSE serve changes a layer of its own that is discarded at its finish, and any number of containers and FUSE serves may hold the volume at once. When it is read_only, no container and no FUSE serve changes the volume, and any number of them may hold it at once. What a mode allows is the most any server allows; what this server allows for a mode, and whether it keeps volumes of the mode at all, is the mode object it holds out for the mode. Whatever the mode, a volumes::write request of the client puts a file in the volume. The mode is the volume’s and is the same for every container that mounts it and every FUSE serve of it; neither states anything about it.
A mode the server does not keep. A request whose mode is one the server holds out no mode object for is answered with ModeUnsupported, the byte 2, before anything is reserved; no volume, and no part of one, exists by that name as a result of the request, and the client’s listing is as it was.
The volume. When the server sends the byte 0, the volume exists. From that moment, every volumes::list scope the client opens lists the volume, and every list scope the client holds open is sent the volume as added, under the name the client gave and with bytes equal to the size the client gave, until a volumes::delete request by the client deletes it. The end of the scope, and the end of every connection of the client, leave the volume in existence. Response states the form of the response.
The content. The volume is created empty. Its content is changed only by a container in which the client mounts it. The server does not write to the volume, does not remove from it, and does not otherwise alter its content, and no party other than such a container does. Its dirhash, as volumes::stat reports it, is h1:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, the hash of a directory with no file, until a container changes its content.
The client. The client is the identity under which the connection was authorized, as Authorization provides. The volume is created for that identity, and that identity alone can name it.
The name. The name is the client’s choice. This revision prescribes no form for it. A server may refuse a name; the refusal is an error. A request whose name is the name of a volume already in the client’s listing is answered with an error, and the listing is unchanged. A name is unique among the volumes of one client only: two clients may each hold a volume of one name, and neither can name the other’s.
Insufficient capacity. When the server cannot reserve the size stated, it does not create the volume and sends the byte 1. No volume, and no part of one, exists by that name as a result of the request, and the client’s listing is as it was before the request. The server does not send the byte 0 for a size it cannot reserve. The largest size the server can reserve at a given time is reported by volumes::create_capacity.
The error. An error states that the volume was not created, for a reason other than capacity or the mode: no volume, and no part of one, exists by that name as a result of the request, and the client’s listing is as it was before the request.
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 3 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 10 followed by the name as a varint length and UTF-8 bytes, the size in bytes as a varint, and the mode as one byte, in the postcard wire format.
Response — The server sends exactly one response, whose payload is exactly the byte 0 when the volume exists, exactly the byte 1 when the server has insufficient capacity for it, exactly the byte 2 when the server keeps no volume of the mode stated, exactly the byte 3 when the server keeps no volume, or the byte 4 followed by an error as one JSON value, and the response finish follows it.