[mojatter]

#291 fixed fs so that the root, a Sub of it and a DirFS opened on the same directory answer the same ETag, Content-Type and metadata for an object, whichever of them wrote it. Neither the Storage.Sub godoc nor docs/backends.md stated that property, and only an fs-only, memfs-only test covered root and Sub. This pins it in the conformance suite and the docs so the next layout change cannot silently undo it.

Closes #299

Affects: Storage implementers (contract and s2test).

Changes

• s2test.TestStorageSubConsistency(ctx, strg): writes s2test-sub/a.txt through the root and b.txt through Sub("s2test-sub"), each with a Content-Type and metadata, and requires the other view to answer the same ETag, ContentType() and Metadata(). It then runs PutMetadata through the view that did not write the object and reads it back through the one that did, requires a non-recursive List of both views to agree on the ETags, and checks that a Delete through one view makes Exists false through the other. It writes only under its own prefix s2test-sub/ and removes that prefix when done. Metadata must agree between the views and hold the keys the helper set; a backend's own extra keys are allowed.
• fs, s3, gcs and azblob call it beside TestStorageNameEscape: fs on memfs and an osfs temp root, the others with and without a root prefix.
• fs TestMetaSharedAcrossViews gains four DirFS rows (DirFS ↔ root, DirFS ↔ Sub) on osfs, since DirFS is not reachable through the interface.
• Storage.Sub godoc: a Sub is a view of the prefix; an object written through either is the same object, with the same ETag, Content-Type and metadata, through the other.
• docs/backends.md: the metadata-file layout is now a list of rules under "Metadata files on osfs and memfs" (location, independence from the writing view, .meta reserved at every depth, temp files, what blocks a write with fs.ErrMetaBlocked). The paragraphs about pre-v0.20.0 and pre-v0.18.1 roots move unchanged under "Metadata files written before v0.20.0", which Track compatibility shims to remove in v1.0.0 #247 can delete as a whole.

Upgrading notes for the release

• Storage implementers: the conformance suite now requires a Sub to be a view of its parent, not a copy. A backend whose Sub answers a different ETag, Content-Type or metadata than its parent, or does not see the parent's writes and deletes, fails s2test.TestStorageSubConsistency.

Verification

• TestStorageSubConsistencyRejects wraps memfs with a Sub that is a separate storage, one whose Get answers its own ETag, one that drops Content-Type and metadata, one whose List answers its own ETag, and one whose Delete does nothing, and checks that the helper reports each; an unwrapped Sub passes.
• Against v0.19.1 (before fs: Sidecar location depends on which storage wrote it #291) in a scratch worktree, the helper fails on memfs fs at every step: Put, PutMetadata and List each disagree between the root and the Sub.