Storage

1. 序論

~webは、 何年かにわたり~storage用に利用できる様々な~APIを成長させてきた — 例えば IndexedDB, `localStorage^c, `showNotification()^c 。 ~Storage標準は、 次を定義することにより，これらの~APIを統括する： ◎ Over the years the web has grown various APIs that can be used for storage, e.g., IndexedDB, localStorage, and showNotification(). The Storage Standard consolidates these APIs by defining:

• これらの~APIが~dataを格納するための~primitiveとなる，~bucket。 ◎ A bucket, the primitive these APIs store their data in
• その~bucketを持続的にする仕方。 ◎ A way of making that bucket persistent
• 与えられた`生成元$に対する利用度と~quota見積もりを取得する仕方。 ◎ A way of getting usage and quota estimates for an origin

伝統的に，これらの~APIにより格納された~dataは、 機器~上の~storage空間を利用者が使果たすに伴い，利用者が介入できることなく喪失されていた。 が、 持続的な~bucketは，利用者の同意なくしては~clearできない。 したがって，これは、 利用者が~webに~nativeな~platformで享受した~dataの保証をもたらす。 ◎ Traditionally, as the user runs out of storage space on their device, the data stored with these APIs gets lost without the user being able to intervene. However, persistent buckets cannot be cleared without consent by the user. This thus brings data guarantees users have enjoyed on native platforms to the web.

navigator.storage.persist().then(%persisted => {
  if (%persisted) {
    /* … */
  }
});

Promise.all([
  navigator.storage.persisted(),
  navigator.permissions.query({name: "persistent-storage"})
]).then(([%persisted, %permission]) => {
  if (!%persisted && %permission.state == "granted") {
    navigator.storage.persist().then( /* … */ )
  } else if (!%persisted && %permission.state == "prompt") {
    showPersistentStorageExplanation()
  }
});

function retrieveNextChunk(%nextChunkInfo) {
  return navigator.storage.estimate().then(%info => {
    if (%info.quota - %info.usage > %nextChunkInfo.size) {
      return fetch(%nextChunkInfo.url);
    } else {【！"insufficient space to store next chunk"】
      throw new Error("次の~chunkを格納するための空きが足りません")
    }
  }).then( /* … */ );
}

【この訳に特有な表記規約】

2. 各種用語

この仕様は、 `INFRA$r に依存する。 ◎ This specification depends on the Infra Standard. [INFRA]

この仕様は、 次に挙げる各種~標準による各種用語を利用する ⇒＃ `HTML$r `WEBIDL$r `PERMISSIONS$r ◎ This specification uses terminology from the HTML, IDL, and Permissions Standards. [HTML] [WEBIDL] [PERMISSIONS]

3. 情勢

`~UA$は、 次に挙げるような何種類かの半-持続的な状態を有する： ◎ A user agent has various kinds of semi-persistent state:

資格証 ◎ Credentials

~HTML~formを通して提出された~usernameや~passwordなど，末端利用者の資格証からなる。 ◎ End-user credentials, such as username and passwords submitted through HTML forms

許可 ◎ Permissions

地理所在など，様々な特能に対する許可からなる。 ◎ Permissions for various features, such as geolocation

~network ◎ Network

次に挙げるもの, 等々からなる ⇒＃ ~HTTP~cache, ~cookie, 認証~entry, ~TLS~client証明書 ◎ HTTP cache, cookies, authentication entries, TLS client certificates

~storage ◎ Storage

次に挙げるもの, 等々からなる ⇒＃ Indexed DB, Cache API, ~sw登録, `localStorage^m, `sessionStorage^m, ~app~cache, 通知 ◎ Indexed DB, Cache API, service worker registrations, localStorage, sessionStorage, application caches, notifications, etc.

この標準が首に関わるのは、 ~storageである。 ◎ This standard primarily concerns itself with storage.

4. ~model

［ 局所／~session ］~storage~APIを定義している標準は、 `~storage端点$を定義して，それを — この標準を変更することを通して — `登録-済み~storage端点~群$に登録することになる。 当の標準は、［ `局所~storage瓶~mapを得する$／ `~session~storage瓶~mapを得する$ ］いずれかの~algoを呼出してそれを与えることになる： ◎ Standards defining local or session storage APIs will define a storage endpoint and register it by changing this standard. They will invoke either the obtain a local storage bottle map or the obtain a session storage bottle map algorithm, which will give them:

• 結果における `失敗^i は、 次のいずれかを意味する ⇒＃ 当の~APIは例外を投出する必要があるかもしれない／ 当の`環境~設定群~obj$用に可用な~storageは無いことを指示する ◎ Failure, which might mean the API has to throw or otherwise indicate there is no storage available for that environment settings object.
• `~storage~proxy~map$は、 当の~APIに適する方式で~dataを格納するために利用でき，`~map$と相似的に演算する。 ［ 当の~APIと他の~APIからの~data／ 各`~storage~key$／ 各`~storage種別$ ］どうしを隔離する~careは、 この標準が担う。 ◎ A storage proxy map that operates analogously to a map, which can be used to store data in a manner that suits the API. This standard takes care of isolating that data from other APIs, storage keys, and storage types.

注記： そのような~API用の標準を定義している~~策定者は、 この標準に対し課題を申請して，支援と考査を受けることを考慮すること。 ◎ If you are defining a standard for such an API, consider filing an issue against this standard for assistance and review.

この~dataを隔離するため、 この標準は，次を定義する： ◎ To isolate this data this standard defines＼

• `~storage倉$は、 `~storage~key$により各`~storage棚$を区分する。 ◎ a storage shed which segments storage shelves by a storage key.＼
• `~storage棚$は、 1 個の`~storage~bucket$からなる — が，将来には、 各種~storage施策~用に［ 複数個の`~storage~bucket$からなることも許容する ］ことになる見込みが高い。 ◎ A storage shelf in turn consists of a storage bucket and will likely consist of multiple storage buckets in the future to allow for different storage policies.＼
• `~storage~bucket$は、 0 個以上の — 各`~storage端点$ごとに 1 個ある — `~storage瓶$からなる。 ◎ And lastly, a storage bucket consists of storage bottles, one for each storage endpoint.

5. 持続性~許可

`局所~storage~bucket$の`~mode$が `persistent^l 【 “持続的” 】に変更されるのは、 利用者が（または、~UAが利用者に利するために） `persistent-storage^l で識別される`強力な特能$を利用する許可を是認したときに限られる。 ◎ A local storage bucket can only have its mode change to "persistent" if the user (or user agent on behalf of the user) has granted permission to use the "persistent-storage" powerful feature.

注記： 持続性~許可は、 `生成元$に対し是認されたときは，［ ~UAによる ~storageを~clearするための施策 ］から保護するために利用できる。 ~UAは、 `生成元$や利用者の介在~抜きには，持続的にされた~storageを~clearできない。 これは特に、［ 利用者が~offlineの間でも可用になる必要がある資源 ］や［ 利用者が局所的に作成した資源 ］用に有用になる。 ◎ When granted to an origin, the persistence permission can be used to protect storage from the user agent’s clearing policies. The user agent cannot clear storage marked as persistent without involvement from the origin or user. This makes it particularly useful for resources the user needs to have available while offline or resources the user creates locally.

`persistent-storage^l で識別される`強力な特能$の許可に関係する各種［ ~algo, 型 ］は、 次に挙げるものを除いて既定のものになる： ◎ The "persistent-storage" powerful feature’s permission-related algorithms, and types are defaulted, except for:

`許可~状態$ ◎ permission state

`persistent-storage^l の`許可~状態$の値は、 同じ`生成元$enVを伴う すべての`環境~設定群~obj$にわたり，同じにするモノトスル。 ◎ "persistent-storage"'s permission state must have the same value for all environment settings objects with a given origin.

`許可~revocation~algo$ ◎ permission revocation algorithm

次を走らす：

1. ~IF［ `現在の許可~状態を取得する$( `persistent-storage^l ) ~EQ `granted$l ］ ⇒ ~RET ◎ If the result of getting the current permission state with "persistent-storage" is "granted", then return.
2. %棚 ~LET `局所~storage棚を得する$( `現在の設定群~obj$ ) ◎ Let shelf be the result of running obtain a local storage shelf with current settings object.
3. %棚 の`~bucket~map$[ `default^l ] の`~mode$ ~SET `best-effort^l ◎ Set shelf’s bucket map["default"]'s mode to "best-effort".

6. 利用度と~quota

`~storage利用度@ （ `storage usage^en ）とは、 `実装定義$な およその見積もりによる，`~storage棚$が利用している~byte数である。 ◎ The storage usage of a storage shelf is an implementation-defined rough estimate of the amount of bytes used by it.

注記： これは正確な量にはなり得ない。 ~UAは［ `~storage棚$が正確に何~byte利用しているか はっきりしなくなる ］ような［ 重複集約, 圧縮, その他の技法 ］を駆使しているかもしれず、 また，~UAには そうすることが奨励されるので。 ◎ This cannot be an exact amount as user agents might, and are encouraged to, use deduplication, compression, and other techniques that obscure exactly how much bytes a storage shelf uses.

◎追跡路 `~storage~quota@ （ `storage quota^en ）とは、 `実装定義$な保守的な見積もりによる，`~storage棚$が保持できる総~byte数である。 この量は、［ 利用者に ある程度の余裕を与えるため，機器~上の~storage空間の総計より少なくなる ］べきであるが， 機器~上の可用な~storage空間の関数にしないモノトスル。 ◎ (This is a tracking vector.) The storage quota of a storage shelf is an implementation-defined conservative estimate of the total amount of bytes it can hold. This amount should be less than the total storage space on the device. It must not be a function of the available storage space on the device.

注記： ~UAには、 ~quotaを決定するときには，次を考慮することが強く奨励される ⇒＃ ~naviの頻度, 訪問の近過去度, ~bookmarkされたかどうか, `persistent-storage^l に対する許可 ◎ User agents are strongly encouraged to consider navigation frequency, recency of visits, bookmarking, and permission for "persistent-storage" when determining quotas.

注記： 直接間接を問わず，可用な~storage空間を露呈すると、 指紋収集や［ 孕まれる`生成元$の視野の外側へ情報が漏洩される結果 ］に至らせ得る。 ◎ Directly or indirectly revealing available storage space can lead to fingerprinting and leaking information outside the scope of the origin involved.

7. 管理

~UAは、 `~storage~bucket$を~clearするときには，まるごと~clearするモノトスル。 ~UAは、 `~storage~bucket$に~access可能な~scriptが走っている間は — 利用者から他が指図されない限り — それを~clearするのを避けるベキである。 ◎ Whenever a storage bucket is cleared by the user agent, it must be cleared in its entirety. User agents should avoid clearing storage buckets while script that is able to access them is running, unless instructed otherwise by the user.

`~storage~bucket$の除去により，それを包摂している`~storage棚$ %棚 の`~bucket~map$が`空$mapになった場合、 %棚 を包摂している`~storage倉$から， 対応する`~storage~key$とともに %棚 を`除去する$mapこと。 ◎ If removal of storage buckets leaves the encompassing storage shelf’s bucket map empty, then remove that storage shelf and corresponding storage key from the encompassing storage shed.

8. ~API

[`SecureContext$]
interface mixin `NavigatorStorage@I {
  [`SameObject$] readonly attribute `StorageManager$I `storage$m;
};

`Navigator$I includes `NavigatorStorage$I;
`WorkerNavigator$I includes `NavigatorStorage$I;

各`環境~設定群~obj$ `HTML$r には、 `StorageManager$I ~objが結付けられる。 ◎ Each environment settings object has an associated StorageManager object. [HTML]

`storage@m 取得子~手続きは ⇒ ~RET コレに`関連な設定群~obj$の `StorageManager$I ~obj ◎ The storage getter steps are to return this’s relevant settings object’s StorageManager object.

[`SecureContext$,
 `Exposed$=(Window,Worker)]
interface `StorageManager@I {
  `Promise$<`boolean$> `persisted$m();
  [`Exposed$=Window] `Promise$<`boolean$> `persist$m();

  `Promise$<`StorageEstimate$I> `estimate$m();
};

dictionary `StorageEstimate@I {
  `unsigned long long$ `usage@m;
  `unsigned long long$ `quota@m;
};

謝辞

次の方々からの~~貢献に感謝する：

知的財産権