filesystem::write

Tag 5: the client names one file of the container; the server asks for the content on a channel of its own, puts the file in place whole, and answers Written or an error, and the finish.

The client opens the scope with a request whose payload is the tag byte 5 followed by the path of one file, as JSON. The server opens one channel on the scope, the content, and the client answers on it with the bytes of the file; the server puts the file in place and answers with exactly one response, Written or an error, and ends the scope by the response finish.

  • The request. Request states its form.
  • The response. Response states the one response.
  • The channels. The server opens the channel that Server Channels defines. The client opens no channel on a write scope.

The order#

  1. The server reads the request. A request whose payload does not decode is answered by a response finish that no response precedes, as Container Proxy Endpoints provides. A path that is the root, or that has a component that is empty, ., .., or contains / or NUL, is answered by exactly one error response and the finish.
  2. The server makes a temporary file. Beside the destination, new, named .<name>.diverge-write-<n> where <name> is the destination’s last component and <n> a number no other temporary of the server has. A parent that is missing or is not a directory is answered by exactly one error response and the finish.
  3. The server opens the content channel. Exactly one, after the temporary exists and before anything is written.
  4. The server writes the content. Every body the client sends on the channel is appended to the temporary, in order. An error on the channel, and a write that fails, discard the temporary and are answered by exactly one error response and the finish. The destination is untouched.
  5. The server puts the file in place. After the channel finishes, the temporary is renamed over the destination; a regular file at the destination lends the new file its permissions, and a symbolic link at the destination is replaced, not written through. A rename that fails discards the temporary and is answered by exactly one error response and the finish.
  6. The server answers Written and finishes the scope.

The rules that hold throughout#

  • Whole or not at all. The destination is either what it was or the whole new file. No partial file is left at the destination.
  • No durability. The server does not sync the file to storage.