Storage container terms are mysteriously opaque

[othermaciej]

The terms "storage shed", "storage shelf", "storage bucket" and "storage bottle" are hard to understand. The terms express a size hierarchy, which is pretty clear, but other than that, they don't convey what they mean. Even the size hierarchy is based on a somewhat arbitrary ordering of keys. The ordering of the hierarchy is not motivated in the spec, and the "model" section does not directly explain what they represent.

Here's what I was able to figure out on careful reading:

storage shed: seems to exist solely to distinguish "local" vs "session". Not clear why this is the outermost container. Also, currently redundant with identifier, since any given identifier can only be one of "local" or "session", the comment that this may change does not explain why.

storage shelf: represents the storage for an origin (presumably will change for storage partitioning; will this change the key, or will it add another level of storage hierarchy?)

storage bucket: can't figure out what this represents. Currently it seems there is only one per storage shelf (keyed as "default"), but even from reading the citied issue #2, I can't figure out what a non-default bucket would represent.

storage bottle: represents the storage for a particular storage API

Perhaps something like "storage scope", "origin storage", "???", "endpoint storage"/"API storage" would be more clear? (No suggestion for the bucket because it's not clear what it is). At the very least, an overview explaining what each of the containers represents, and why they are ordered this particular way, would make it easier to understand the spec.

[pwnall]

I'll comment to offer the context I have around buckets.

I think storage buckets are a relatively new concept in the realm of standards. Mozilla, LinkedIn and Google presented a proposal at TPAC 2019. I think that @youennf attended early discussions.

Storage buckets first appeared as the TEMPORARY and PERSISTENT areas in the file system API that failed to gain cross-browser adoption and ended up as Chrome-only, and in early Chrome-only iterations of the quota API.

The current plan for adding buckets smoothly to the Web platform is to introduce a default bucket, and say that storage APIs have been using this default bucket all along. In Chrome, we'd say the TEMPORARY area is this default bucket.

I hope I've managed to give useful context and not add more confusion to this complex area 😄

[annevk]

(The proposal is quite a bit older than that: #2. But yeah, the reason the specification provides room for buckets is because there appears to be tentative agreement to do something in that area.)