Address shadowing divergence in reftest, update semantics doc

[c-hagem]

This commit addresses a case where MP model and property tests diverge (#1066). The issue was caused by the reference not correctly implementing the shadowing order defined in #4f8cf0b. This commit fixes the reference model, and clarifies the semantics arising from concurrent MPUs.

This is not a breaking change, as it only impacts the reference tests.

This does not need a Changelog entry, as the change does not impact Mountpoint's behaviour.

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and I agree to the terms of the Developer Certificate of Origin (DCO).

[dannycjones]

I think this is the right change and semantics, I've put some feedback on docs mainly

[dannycjones]

I would cut this to be honest. We already recommend above not to write to the same object concurrently, and this is far too much detail for this half of the semantics doc. (We split it into an overview for most readers, then a detailed section below that goes into specific S3 and file system behaviors.)

If needed, we could mention in the detailed semantics later in the doc but delegate reading to the linked documentation: https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpuoverview.html#distributedmpupload.

[c-hagem]

I cut this and added one sentence to the end of the file -- but I'm not too sure if we should keep that or just cut it completely.

[dannycjones]

Suggested change

	then mounting your bucket would give a file system with a `blue` directory, containing the file `image.jpg`. The `blue` object will not be accessible. Deleting the key `blue/image.jpg` will remove the `blue` directory, and cause the `blue` file to become visible.
	Additionally, remote content shadows local content. Thus Mountpoint shadows in the order: remote directories > any local state > remote files.
	Thus, for example, if a user creates a local directory, and then a conflicting
	object appears in the remote bucket, the directory will still be
	visible instead of the new file.
	then mounting your bucket would give a file system with a `blue` directory, containing the file `image.jpg`. The `blue` object will not be accessible. Deleting the key `blue/image.jpg` will remove the `blue` directory, and cause the `blue` file to become visible.
	Additionally, remote directories will always shadow local directories and files. Thus, Mountpoint shadows directory entries in the following order where the first takes precedence: remote directories, any local state, and finally remote files.
	For example, if a user creates a local directory, and then a conflicting
	object appears remotely in the S3 bucket, the directory will still be
	visible instead of the new file.

[c-hagem]

Thanks, I mainly incorporated this -- I tried to additionally keep the example similar (using colours) / not switch from second to third person.

[dannycjones]

Suggested change

	/*
	Ensure that local files are shadowed by the remote directories.
	*/
	#[test]
	fn regression_put_nested_over_open_file() {
	/*
	Ensure that local files are shadowed by the remote directories.
	*/
	#[test]
	fn regression_put_shadowing_new_local_file() {

[c-hagem]

Fixed.

[dannycjones]

This should return false, no? The node was not added.

Suggested change

	// If a directory of this name exists, ignore any local file
	if let Some(node) = children.get(dir) {
	if node.node_type() == NodeType::Directory {
	return true;
	}
	}
	// If a directory of this name exists, ignore any local file
	if let Some(node) = children.get(dir) {
	if node.node_type() == NodeType::Directory {
	return false;
	}
	}

[c-hagem]

Yes, thanks for catching that. I'll also update the comment for the method to reflect the implemented behaviour.

[dannycjones]

This PR closes #1066.