ストレージ標準

1. 序章

長年にわたり、ウェブにはIndexedDB、localStorage、showNotification()など、ストレージに使用できるさまざまなAPIが成長してきました。ストレージ標準は、以下を定義することでこれらのAPIを統合します:

これらのAPIがデータを保存する基本単位であるバケット
そのバケットを永続化する方法
オリジンの使用量とクォータの推定値を取得する方法

従来、ユーザーのデバイスでストレージスペースが不足すると、これらのAPIで保存されたデータはユーザーが介入できないまま失われていました。しかし、永続バケットは、ユーザーの同意なしに削除することはできません。これにより、ネイティブプラットフォームでユーザーが享受していたデータ保証がウェブにもたらされます。

ストレージを永続化する簡単な方法は、persist() メソッドを呼び出すことです。このメソッドは、エンドユーザーに許可をリクエストし、それが許可されるとストレージを永続化に変更します:

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();
  }
});

estimate() メソッドは、アプリケーションのコンテンツを保存するのに十分なスペースが残っているかどうかを判断するために使用できます:

function retrieveNextChunk(nextChunkInfo) {
  return navigator.storage.estimate().then(info => {
    if (info.quota - info.usage > nextChunkInfo.size) {
      return fetch(nextChunkInfo.url);
    } else {
      throw new Error("insufficient space to store next chunk");
    }
  }).then( /* … */ );
}

2. 用語

この仕様はインフラ標準に依存します。[INFRA]

この仕様はHTML、IDL、および許可標準の用語を使用します。[HTML] [WEBIDL] [PERMISSIONS]

3. 全体像

ユーザーエージェントには、さまざまな種類の準永続的な状態があります:

認証情報: HTMLフォームを通じて送信されたユーザー名やパスワードなどのエンドユーザー認証情報
許可: 位置情報など、さまざまな機能の許可
ネットワーク: HTTPキャッシュ、クッキー、認証エントリ、TLSクライアント証明書
ストレージ: Indexed DB、キャッシュAPI、サービスワーカーレジストレーション、localStorage、 sessionStorage、アプリケーションキャッシュ、通知など

この標準は主にストレージに関わるものです。

4. モデル

ローカルまたはセッションストレージAPIを定義する標準は、ストレージエンドポイントを定義し、それを登録するためにこの標準を変更します。それらは、ローカルストレージボトルマップの取得またはセッションストレージボトルマップの取得アルゴリズムを呼び出します。これにより以下のものが得られます:

失敗した場合、APIは例外をスローするか、環境設定オブジェクトにストレージが利用できないことを示す必要があります。
ストレージプロキシマップで、これはマップに類似して動作し、APIに適した方法でデータを保存するために使用されます。この標準は、他のAPI、ストレージキーおよびストレージタイプからそのデータを分離することを担当します。

そのようなAPIの標準を定義している場合、この標準に対して助言やレビューを求める問題を提出することを検討してください。

ストレージモデルの図（次の段落で説明されています）。

このデータを分離するため、この標準はストレージシェッドを定義し、ストレージ棚をストレージキーで分割します。ストレージ棚はさらにストレージバケットで構成され、将来的には異なるストレージポリシーを可能にするため、複数のストレージバケットで構成される可能性があります。そして最後に、ストレージバケットは、ストレージボトルで構成され、各ストレージエンドポイントに対応する1つがあります。

4.1. ストレージエンドポイント

ストレージエンドポイントとは、この標準で定義されたインフラストラクチャ、特にストレージボトルを使用して、ストレージニーズを追跡するローカルまたはセッションストレージAPIです。

ストレージエンドポイントには、識別子があり、これはストレージ識別子です。

ストレージエンドポイントには、さらにタイプがあり、これはセットのストレージタイプです。

ストレージエンドポイントには、さらにクォータがあり、これはヌルまたはこのストレージエンドポイントに対応する各クォータ（バイト単位）を表す推奨値です。

ストレージ識別子は、ASCII文字列です。

ストレージタイプは、"local"または"session"です。

登録されたストレージエンドポイントは、以下の表で定義されたセットのストレージエンドポイントです。

識別子	タイプ	クォータ
"`caches`"	« "`local`" »	null
"`indexedDB`"	« "`local`" »	null
"`localStorage`"	« "`local`" »	5 × 2²⁰（つまり、5メビバイト）
"`serviceWorkerRegistrations`"	« "`local`" »	null
"`sessionStorage`"	« "`session`" »	5 × 2²⁰（つまり、5メビバイト）

前述のように、標準はこれらのストレージ識別子を使用して、ローカルストレージボトルマップの取得やセッションストレージボトルマップの取得を行うことができます。今後、一部のAPIは両方のストレージタイプに適用されると予想されています。

4.2. ストレージキー

ストレージキーとは、タプルであり、オリジン（オリジン）で構成されます。[HTML]

これは変更される可能性があります。詳しくはクライアントサイドストレージの分割を参照してください。

ストレージキーを取得するには、環境 environment が与えられた場合、次の手順を実行します:

keyを、environmentを使用してストレージ目的以外でストレージキーを取得するを実行した結果とします。
keyのオリジンが不透明なオリジンである場合、失敗を返します。
ユーザーがストレージを無効にしている場合、失敗を返します。
keyを返します。

ストレージ目的以外でストレージキーを取得するには、環境 environment が与えられた場合、次の手順を実行します:

environmentが環境設定オブジェクトである場合、environmentのオリジンをoriginとします。それ以外の場合、environmentの作成URLのオリジンをoriginとします。
originで構成されたタプルを返します。

ストレージキー A とストレージキー B が等しいかどうかを判定するには、次の手順を実行します:

AのオリジンがBのオリジンと同一オリジンでない場合、falseを返します。
trueを返します。

4.3. ストレージシェッド

ストレージシェッドとは、マップであり、ストレージキーをストレージ棚にマッピングします。初期状態では空です。

ユーザーエージェントは、ストレージシェッドを保持します。これはストレージシェッドです。ユーザーエージェントのストレージシェッドには、すべてのローカルストレージデータが含まれます。

移動可能ナビゲーブルは、ストレージシェッドを保持します。これはストレージシェッドです。移動可能ナビゲーブルのストレージシェッドには、すべてのセッションストレージデータが含まれます。

移動可能ストレージシェッドのレガシークローンを実行するには、移動可能ナビゲーブル A と移動可能ナビゲーブル B が与えられた場合、次の手順を実行します:

各 key → shelf について、Aのストレージシェッドを反復します:
1. "session"を使用してストレージ棚を作成するを実行した結果をnewShelfとします。
2. newShelfのバケットマップ["default"]のボトルマップ["sessionStorage"]のマップを、shelfのバケットマップ["default"]のボトルマップ["sessionStorage"]のマップのクローンに設定します。
3. Bのストレージシェッド[key]をnewShelfに設定します。

これはレガシーと見なされ、利点があったとしても実装の複雑さを上回るものではありません。そのため、HTML以外では拡張されたり使用されたりすることはありません。[HTML]

4.4. ストレージ棚

ストレージ棚は、ストレージシェッド内の各ストレージキーごとに存在します。これはストレージバケットへマッピングするマップであるバケットマップを保持します。

現在のところ、"default"はバケットマップ内に存在する唯一のキーです。詳しくはissue #2を参照してください。これは初めてストレージ棚が取得されたときに値が与えられます。

ストレージ棚を取得するには、ストレージシェッド shed、環境設定オブジェクト environment、およびストレージタイプ typeが与えられた場合、次の手順を実行します:

keyを、environmentを使用してストレージキーを取得するを実行した結果とします。
keyが失敗の場合、失敗を返します。
shed[key]が存在しない場合、shed[key]をストレージ棚を作成するをtypeで実行した結果に設定します。
shed[key]を返します。

ローカルストレージ棚を取得するには、環境設定オブジェクト environmentが与えられた場合、次の値を返します: ユーザーエージェントのストレージシェッド、environment、および"local"を用いてストレージ棚を取得するを実行した結果。

ストレージ棚を作成するには、ストレージタイプ typeが与えられた場合、次の手順を実行します:

shelfを新しいストレージ棚に設定します。
shelfのバケットマップ["default"]をストレージバケットを作成するをtypeで実行した結果に設定します。
shelfを返します。

4.5. ストレージバケット

ストレージバケットは、ストレージエンドポイントがデータを保存する場所です。

ストレージバケットには、ストレージ識別子をストレージボトルにマッピングするボトルマップがあります。

ローカルストレージバケットは、ローカルストレージAPI用のストレージバケットです。

ローカルストレージバケットには、"best-effort"または"persistent"であるモードがあります。初期状態では"best-effort"です。

セッションストレージバケットは、セッションストレージAPI用のストレージバケットです。

ストレージバケットを作成するには、ストレージタイプ typeが与えられた場合、次の手順を実行します:

bucketをnullに設定します。
typeが"local"の場合、bucketを新しいローカルストレージバケットに設定します。
それ以外の場合:
1. アサート: typeが"session"である。
2. bucketを新しいセッションストレージバケットに設定します。
各endpointについて、登録されたストレージエンドポイントの中で、そのタイプがtypeを含む場合、bucketのボトルマップ[endpointの識別子]を、ストレージボトルの新しいインスタンスに設定し、そのクォータをendpointのクォータに設定します。
bucketを返します。

4.6. ストレージボトル

ストレージボトルとは、単一のストレージエンドポイント専用に区切られたストレージバケットの一部です。ストレージボトルには、初期状態で空のマップであるマップがあります。また、ストレージボトルには、初期状態で空のセットであるプロキシマップ参照セットがあります。また、ストレージボトルには、保持できるバイト数の保守的な推定値を表す数値またはヌルであるクォータがあります。ヌルは制限がないことを示します。それでも、包含するストレージ棚のストレージクォータに制約されます。

ストレージボトルのマップは、実際に保存されるデータが存在する場所です。ユーザーエージェントは、このデータを保存し、エージェントやエージェントクラスターの境界を越えて、この標準およびこの標準を使用する標準が内容にアクセスできるようにするために、実装定義の方法で利用可能にすることが期待されています。

ストレージボトルマップを取得するには、ストレージタイプ type、環境設定オブジェクト environment、およびストレージ識別子 identifierが与えられた場合、次の手順を実行します:

shedをnullに設定します。
typeが"local"の場合、shedをユーザーエージェントのストレージシェッドに設定します。
それ以外の場合:
1. アサート: typeが"session"である。
2. shedをenvironmentのグローバルオブジェクトの関連付けられたDocumentのノードナビゲーブルの移動可能ナビゲーブルのストレージシェッドに設定します。
shelfをshed、environment、およびtypeを使用してストレージ棚を取得するを実行した結果に設定します。
shelfが失敗の場合、失敗を返します。
bucketをshelfのバケットマップ["default"]に設定します。
bottleをbucketのボトルマップ[identifier]に設定します。
proxyMapを新しいストレージプロキシマップに設定し、そのバッキングマップをbottleのマップに設定します。
bottleのプロキシマップ参照セットにproxyMapを追加します。
proxyMapを返します。

ローカルストレージボトルマップを取得するには、環境設定オブジェクト environmentおよびストレージ識別子 identifierが与えられた場合、"local"、environment、およびidentifierを使用してストレージボトルマップを取得するを実行した結果を返します。

セッションストレージボトルマップを取得するには、環境設定オブジェクト environmentおよびストレージ識別子 identifierが与えられた場合、"session"、environment、およびidentifierを使用してストレージボトルマップを取得するを実行した結果を返します。

4.7. ストレージプロキシマップ

ストレージプロキシマップは、マップと同等ですが、すべての操作がそのバッキングマップ上で実行されます。

これにより、バッキングマップを置き換えることが可能になります。これはissue #4および潜在的にStorage Access APIに必要です。

4.8. ストレージタスクソース

ストレージタスクソースは、タスクソースであり、タスクに関連するすべてのストレージエンドポイント、特にストレージエンドポイントのクォータに関連するものに使用されます。

ストレージタスクをキューに追加するには、グローバルオブジェクト global と一連の手順 steps が与えられた場合、グローバルタスクをキューに追加するをストレージタスクソースでglobalおよびstepsを指定して実行します。

5. 永続性の許可

ローカルストレージバケットは、ユーザー（またはユーザーに代わってユーザーエージェント）が"persistent-storage"の使用を許可する強力な機能への許可を与えた場合にのみ、そのモードを"persistent"に変更できます。

あるオリジンに許可が与えられると、永続性の許可を使用して、ユーザーエージェントのクリアポリシーからストレージを保護できます。永続性としてマークされたストレージは、オリジンまたはユーザーの関与なしにユーザーエージェントによってクリアされることはありません。これにより、オフライン時にユーザーが必要とするリソースや、ユーザーがローカルで作成するリソースに特に有用です。

"persistent-storage"の強力な機能の許可関連アルゴリズムおよびタイプはデフォルトですが、以下を除きます:

許可状態

"persistent-storage"の許可状態は、与えられた環境設定オブジェクトのすべてで同じオリジンを持つ必要があります。

許可の取り消しアルゴリズム

"persistent-storage"で現在の許可状態を取得するの結果が"granted"の場合、終了します。
shelfを、ローカルストレージ棚を取得するを現在の設定オブジェクトで実行した結果に設定します。
shelfのバケットマップ["default"]のモードを"best-effort"に設定します。

6. 使用量とクォータ

ストレージ棚のストレージ使用量は、使用されているバイト数の実装定義によるおおよその推定値です。

これは正確な量ではありません。ユーザーエージェントは、重複排除、圧縮、およびその他の技術を使用して、ストレージ棚が使用するバイト数を正確に把握できないようにすることが奨励されています。

ストレージ棚のストレージクォータは、保持できるバイト数の実装定義による保守的な推定値です。この量はデバイス上の総ストレージスペースより少なくなければなりません。また、デバイス上で利用可能なストレージスペースの関数であってはなりません。

ユーザーエージェントは、クォータを決定する際にナビゲーション頻度、訪問の新しさ、ブックマーク、および"persistent-storage"に対する許可を考慮することが強く推奨されます。

利用可能なストレージスペースを直接的または間接的に明らかにすることは、フィンガープリントやオリジンの範囲外で情報を漏洩する可能性があります。

7. 管理

ユーザーエージェントがストレージバケットをクリアする場合、完全にクリアする必要があります。スクリプトがアクセス可能な状態で実行中の場合、ユーザーからの指示がない限り、ユーザーエージェントはストレージバケットをクリアしないようにするべきです。

ストレージバケットを削除した結果、包含するストレージ棚のバケットマップが空になった場合、そのストレージ棚および対応するストレージキーを包含するストレージシェッドから削除します。

7.1. ストレージプレッシャー

ユーザーエージェントがストレージプレッシャーを受ける場合、ネットワーク状態およびローカルストレージバケットのうちモードが"best-effort"であるものをクリアするべきです。理想的には、ユーザーへの影響が最小限になるような方法で削除を優先します。

ユーザーエージェントが引き続きストレージプレッシャーを受ける場合、ユーザーエージェントはユーザーに通知し、残りのローカルストレージバケット（すなわち、モードが"persistent"であるもの）をクリアする方法を提供するべきです。

セッションストレージバケットは、移動可能ナビゲーブルが閉じられる際にクリアする必要があります。

ユーザーエージェントが移動可能ナビゲーブルの復活を許可する場合、たとえば移動可能ナビゲーブルを再オープンするか、ユーザーエージェントを再起動後に引き続き使用する場合、クリアにはより複雑なヒューリスティックが必要になります。

7.2. ユーザーインターフェースガイドライン

ユーザーエージェントは、個々のウェブサイトのためにネットワーク状態およびストレージをクリアする機能をユーザーに提供するべきです。ユーザーインターフェースでネットワーク状態とストレージを区別してはなりません。これにより、ネットワーク状態を使用してストレージを復活させることができなくなり、ユーザーが意識する必要のある概念の数を減らすことができます。

資格情報は分離するべきです。たとえば、自動生成されたパスワードなど、ユーザーが復活させることができないデータを含む場合があります。同様に、ユーザーの不便を避けるために許可も分離するのが最善です。

8. API

[SecureContext]
interface mixin NavigatorStorage {
  [SameObject] readonly attribute StorageManager storage;
};
Navigator includes NavigatorStorage;
WorkerNavigator includes NavigatorStorage;

各環境設定オブジェクトには、関連付けられたStorageManager オブジェクトがあります。[HTML]

storageゲッターの手順は、thisの関連する設定オブジェクトのStorageManager オブジェクトを返すことです。

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

  Promise<StorageEstimate> estimate();
};

dictionary StorageEstimate {
  unsigned long long usage;
  unsigned long long quota;
};

persisted() メソッドの手順は次の通りです:

promise を新しい Promise とします。
global を this の関連するグローバルオブジェクトとします。
shelf をローカルストレージ棚を取得するを this の関連する設定オブジェクトを使用して実行した結果とします。
もし shelf が失敗であれば、reject promise を TypeError とします。
それ以外の場合、次の手順を並行して実行します:
1. persisted を、もし shelf のバケットマップ["default"] のモードが "persistent" であれば true、それ以外の場合は false とします。
  
  内部エラーがある場合、false になります。
2. ストレージタスクをキューに追加し、global を使用して resolve promise を persisted とします。
promise を返します。

persist() メソッドの手順は次の通りです:

promise を新しい Promise とします。
global を this の関連するグローバルオブジェクトとします。
shelf をローカルストレージ棚を取得するを this の関連する設定オブジェクトを使用して実行した結果とします。
もし shelf が失敗であれば、reject promise を TypeError とします。
それ以外の場合、次の手順を並行して実行します:
1. permission を使用許可をリクエストして "persistent-storage" とします。
  
  ユーザーエージェントは、同じオリジンに対して同じ時期にこの質問を2回させないようにすることが推奨されます。このアルゴリズムはそのようなシナリオに対応していません。
2. bucket を shelf のバケットマップ["default"] とします。
3. persisted を、bucket のモードが "persistent" であれば true、それ以外の場合は false とします。
  
  内部エラーがある場合、false になります。
4. もし persisted が false であり、permission が "granted" であれば:
  1. bucket のモードを "persistent" に設定します。
  2. 内部エラーがなければ、persisted を true に設定します。
5. ストレージタスクをキューに追加し、global を使用して resolve promise を persisted とします。
promise を返します。

estimate() メソッドの手順は次の通りです:

promise を新しい Promise とします。
global を this の関連するグローバルオブジェクトとします。
shelf をローカルストレージ棚を取得するを this の関連する設定オブジェクトを使用して実行した結果とします。
もし shelf が失敗であれば、reject promise を TypeError とします。
それ以外の場合、次の手順を並行して実行します:
1. usage をストレージ使用量として shelf について取得します。
2. quota をストレージクォータとして shelf について取得します。
3. dictionary を新しい StorageEstimate 辞書とし、そのusage メンバーを usage とし、quota メンバーを quota とします。
4. もし usage および quota を取得する際に内部エラーが発生した場合、ストレージタスクをキューに追加し、global を使用して reject promise を TypeError とします。
  
  内部エラーは非常に稀であるべきであり、何らかの低レベルのプラットフォームまたはハードウェアの障害を示します。ただし、ウェブの規模および実装やプラットフォームの多様性を考慮すると、予期しない事象が発生する可能性があります。
5. それ以外の場合、ストレージタスクをキューに追加し、global を使用して resolve promise を dictionary とします。
promise を返します。

謝辞

最後に、以下の皆様に感謝申し上げます： Adrian Bateman、 Aislinn Grigas、 Alex Russell、 Ali Alabbas、 Andrew Sutherland、 Andrew Williams、 Austin Sullivan、 Ben Kelly、 Ben Turner、 Dale Harvey、 David Grogan、 Domenic Denicola、 fantasai、 Jake Archibald、 Jeffrey Yasskin、 Jesse Mykolyn、 Jinho Bang、 Jonas Sicking、 Joshua Bell、 Kenji Baheux、 Kinuko Yasuda、 Luke Wagner、 Michael Nordman、 Mike Taylor、 Mounir Lamouri、 Shachar Zohar、黃強 (Shawn Huang)、簡冠庭 (Timothy Guan-tin Chien）、そして Victor Costan、素晴らしい貢献をありがとうございます！

この現行標準は、Anne van Kesteren（Apple, annevk@annevk.nl）により執筆されています。

知的財産権

これは現行標準です。特許レビュー版に関心のある方は、現行標準レビュー版をご覧ください。

ストレージ

概要