document what happens in case of errors

[droundy]

I would like to know when BufWriter::shutdown() or flush() fail whether the write has partially succeeded. Ideally I'd like to have a way to upload such that the operation will be atomic, and the file will not end up in a partially-uploaded state.

Specifically, I'd like to have documented what the consequences of an error in flush or shutdown are.

[tustvold]

All object store operations are atomic, and will never result in partially written files.

• https://docs.rs/object_store/latest/object_store/trait.ObjectStore.html#method.put
• https://docs.rs/object_store/latest/object_store/trait.MultipartUpload.html

The only slight caveat is multipart uploads, which may leave partial uploads behind in certain exceptional cases, but these are not visible and only exist in a staging area. See https://docs.rs/object_store/latest/object_store/aws/index.html#multipart-uploads.

As for what happens on error, it depends on the error. In most cases the file won't be committed, however, if there was say a network error after the operation completed, an error will be reported but the operation will have succeeded.

TLDR everything is atomic, but as with any distributed system, you can have failures occur after transaction commit.

FWIW if you're concerned about error handling I would recommend avoiding BufWriter, as documented here, as whilst it is still atomic the relationship to the underlying operations is obfuscated