Cookie 存储 API

document.cookie =
  '__Secure-COOKIENAME=cookie-value' +
  '; Path=/' +
  '; expires=Fri, 12 Aug 2016 23:05:17 GMT' +
  '; Secure' +
  '; Domain=example.org';
// 现在我们可以假设写入成功了，但由于
// 失败是静默的，因此很难判断，所以我们
// 读取以查看写入是否成功
var successRegExp =
  /(^|; ?)__Secure-COOKIENAME=cookie-value(;|$)/;
if (String(document.cookie).match(successRegExp)) {
  console.log('成功了！');
} else {
  console.error('未成功，且原因不明');
}

const one_day_ms = 24 * 60 * 60 * 1000;
cookieStore.set(
  {
    name: '__Secure-COOKIENAME',
    value: 'cookie-value',
    expires: Date.now() + one_day_ms,
    domain: 'example.org'
  }).then(function() {
    console.log('成功了！');
  }, function(reason) {
    console.error('未成功，原因如下：',
      reason);
  });
// 同时我们可以在等待Cookie存储处理写入时做其他事情...

try {
  const cookie = await cookieStore.get('session_id');
  if (cookie) {
    console.log(`找到 ${cookie.name} Cookie: ${cookie.value}`);
  } else {
    console.log('未找到Cookie');
  }
} catch (e) {
  console.error(`Cookie存储错误: ${e}`);
}

try {
  const cookies = await cookieStore.getAll('session_id'});
  for (const cookie of cookies)
    console.log(`结果: ${cookie.name} = ${cookie.value}`);
} catch (e) {
  console.error(`Cookie存储错误: ${e}`);
}

await cookieStore.getAll({url: '/admin'});

await cookie = cookieStore.get('session_id');
console.log(`Cookie范围 - 域名: ${cookie.domain} 路径: ${cookie.path}`);
if (cookie.expires === null) {
  console.log('Cookie在会话结束时过期');
} else {
  console.log(`Cookie过期时间: ${cookie.expires}`);
}
if (cookie.secure)
  console.log('该Cookie仅限安全源使用');

try {
  await cookieStore.set('opted_out', '1');
} catch (e) {
  console.error(`设置Cookie失败: ${e}`);
}

await cookieStore.set({
  name: 'opted_out',
  value: '1',
  expires: null,  // 会话Cookie

  // 默认情况下，domain为null，表示作用域限定在当前域名。
  domain: null,
  path: '/'
});

try {
  await cookieStore.delete('session_id');
} catch (e) {
  console.error(`删除Cookie失败: ${e}`);
}

try {
  const one_day_ms = 24 * 60 * 60 * 1000;
  await cookieStore.set({
    name: 'session_id',
    value: 'value will be ignored',
    expires: Date.now() - one_day_ms });
} catch (e) {
  console.error(`删除Cookie失败: ${e}`);
}

cookieStore.addEventListener('change', event => {
  console.log(`${event.changed.length} 个Cookie已更改`);
  for (const cookie in event.changed)
    console.log(`Cookie ${cookie.name} 变更为 ${cookie.value}`);

  console.log(`${event.deleted.length} 个Cookie已删除`);
  for (const cookie in event.deleted)
    console.log(`Cookie ${cookie.name} 已删除`);
});

self.addEventListener('activate', (event) => {
  event.waitUntil(async () => {
    // 快照当前订阅状态。
    const subscriptions = await self.registration.cookies.getSubscriptions();

    // 清除所有现有订阅。
    await self.registration.cookies.unsubscribe(subscriptions);

    await self.registration.cookies.subscribe([
      {
        name: 'session_id',  // 订阅名为session_id的Cookie变更事件。
      }
    ]);
  });
});

self.addEventListener('cookiechange', event => {
  // 事件拥有 |changed| 和 |deleted| 属性，与Document事件语义一致。
  console.log(`${event.changed.length} 个Cookie已更改`);
  console.log(`${event.deleted.length} 个Cookie已删除`);
});

const subscriptions = await self.registration.cookies.getSubscriptions();
for (const sub of subscriptions) {
  console.log(sub.name, sub.url);
}

对给定的string input，规范化 cookie 名称或值： 移除所有位于input开头或结尾的 U+0009 TAB 和 U+0020 SPACE。

[Exposed=(ServiceWorker,Window),
 SecureContext]
interface CookieStore : EventTarget {
  Promise<CookieListItem?> get(USVString name);
  Promise<CookieListItem?> get(optional CookieStoreGetOptions options = {});

  Promise<CookieList> getAll(USVString name);
  Promise<CookieList> getAll(optional CookieStoreGetOptions options = {});

  Promise<undefined> set(USVString name, USVString value);
  Promise<undefined> set(CookieInit options);

  Promise<undefined> delete(USVString name);
  Promise<undefined> delete(CookieStoreDeleteOptions options);

  [Exposed=Window]
  attribute EventHandler onchange;
};

dictionary CookieStoreGetOptions {
  USVString name;
  USVString url;
};

enum CookieSameSite {
  "strict",
  "lax",
  "none"
};

dictionary CookieInit {
  required USVString name;
  required USVString value;
  DOMHighResTimeStamp? expires = null;
  USVString? domain = null;
  USVString path = "/";
  CookieSameSite sameSite = "strict";
  boolean partitioned = false;
};

dictionary CookieStoreDeleteOptions {
  required USVString name;
  USVString? domain = null;
  USVString path = "/";
  boolean partitioned = false;
};

dictionary CookieListItem {
  USVString name;
  USVString value;
};

typedef sequence<CookieListItem> CookieList;

get(name) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 origin 为 settings 的 来源。

3. 如果 origin 是 不透明来源，则返回 一个被拒绝的Promise，错误为 "SecurityError" DOMException。

4. 令 url 为 settings 的 创建URL。

5. 令 p 为 一个新的Promise。

6. 并行执行以下步骤：

   1. 令 list 为运行 查询cookie（参数为 url 和 name）的结果。

   2. 如果 list 失败，则 拒绝 p，错误为 TypeError，并中止这些步骤。

   3. 如果 list 为空，则 解析 p 为 null。

   4. 否则，解析 p 为 list 的第一个项。

7. 返回 p。

get(options) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 origin 为 settings 的 来源。

3. 如果 origin 是 不透明来源，则返回 一个被拒绝的Promise，错误为 "SecurityError" DOMException。

4. 令 url 为 settings 的 创建URL。

5. 如果 options 为空，则返回 一个被拒绝的Promise，错误为 TypeError。

6. 如果 options["url"] 存在，则执行以下步骤：

   1. 令 parsed 为用 settings 的 API基础URL 解析 options["url"] 的结果。

   2. 如果 this 的 相关全局对象 是 Window 对象且 parsed 不 等于 url（排除片段）， 则返回 一个被拒绝的Promise，错误为 TypeError。

   3. 如果 parsed 的 来源 与 url 的 来源 不为 同源， 则返回 一个被拒绝的Promise，错误为 TypeError。

   4. 令 url 为 parsed。

7. 令 p 为 一个新的Promise。

8. 并行执行以下步骤：

   1. 令 list 为使用 url 和 options["name"]， 查询 cookies 的结果， 默认值为 null。

   2. 如果 list 失败，则 拒绝 p，错误为 TypeError，并中止这些步骤。

   3. 如果 list 为空，则 解析 p 为 null。

   4. 否则，解析 p 为 list 的第一个项。

9. 返回 p。

getAll(name) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 origin 为 settings 的 来源。

3. 如果 origin 是 不透明来源，则返回 一个被拒绝的Promise，错误为 "SecurityError" DOMException。

4. 令 url 为 settings 的 创建URL。

5. 令 p 为 一个新的Promise。

6. 并行执行以下步骤：

   1. 令 list 为运行 查询cookie（参数为 url 和 name）的结果。

   2. 如果 list 失败，则 拒绝 p，错误为 TypeError。

   3. 否则，解析 p 为 list。

7. 返回 p。

getAll(options) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 origin 为 settings 的 来源。

3. 如果 origin 是 不透明来源，则返回 一个被拒绝的Promise，错误为 "SecurityError" DOMException。

4. 令 url 为 settings 的 创建URL。

5. 如果 options["url"] 存在，则执行以下步骤：

   1. 令 parsed 为用 settings 的 API基础URL 解析 options["url"] 的结果。

   2. 如果 this 的 相关全局对象 是 Window 对象且 parsed 不 等于 url（排除片段）， 则返回 一个被拒绝的Promise，错误为 TypeError。

   3. 如果 parsed 的 来源 与 url 的 来源 不为 同源， 则返回 一个被拒绝的Promise，错误为 TypeError。

   4. 令 url 为 parsed。

6. 令 p 为 一个新的Promise。

7. 并行执行以下步骤：

   1. 令 list 为使用 url 和 options["name"]， 查询 cookies 的结果， 默认值为 null。

   2. 如果 list 失败，则 拒绝 p，错误为 TypeError。

   3. 否则，解析 p 为 list。

8. 返回 p。

set(name, value) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 origin 为 settings 的 来源。

3. 如果 origin 是 不透明来源，则返回 一个被拒绝的Promise，错误为 "SecurityError" DOMException。

4. 令 url 为 settings 的 创建URL。

5. 令 domain 为 null。

6. 令 path 为 "/"。

7. 令 sameSite 为 strict。

8. 令 partitioned 为 false。

9. 令 p 为 一个新的Promise。

10. 并行执行以下步骤：

    1. 令 r 为运行 设置cookie（参数为 url, name, value, domain, path, sameSite 和 partitioned）的结果。

    2. 如果 r 失败，则 拒绝 p，错误为 TypeError，并中止这些步骤。

    3. 解析 p 为 undefined。

11. 返回 p。

set(options) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 origin 为 settings 的 来源。

3. 如果 origin 是 不透明来源，则返回 一个被拒绝的Promise，错误为 "SecurityError" DOMException。

4. 令 url 为 settings 的 创建URL。

5. 令 p 为 一个新的Promise。

6. 并行执行以下步骤：

   1. 令 r 为运行 设置cookie（参数为 url, options["name"], options["value"], options["expires"], options["domain"], options["path"], options["sameSite"], 以及 options["partitioned"] 的结果。

   2. 如果 r 失败，则 拒绝 p，错误为 TypeError，并中止这些步骤。

   3. 解析 p 为 undefined。

7. 返回 p。

delete(name) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 origin 为 settings 的 来源。

3. 如果 origin 是 不透明来源，则返回 一个被拒绝的Promise，错误为 "SecurityError" DOMException。

4. 令 url 为 settings 的 创建URL。

5. 令 p 为 一个新的Promise。

6. 并行执行以下步骤：

   1. 令 r 为运行 删除cookie（参数为 url, name, null, "/" 和 true） 的结果。

   2. 如果 r 失败，则 拒绝 p，错误为 TypeError，并中止这些步骤。

   3. 解析 p 为 undefined。

7. 返回 p。

delete(options) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 origin 为 settings 的 来源。

3. 如果 origin 是 不透明来源，则返回 一个被拒绝的Promise，错误为 "SecurityError" DOMException。

4. 令 url 为 settings 的 创建URL。

5. 令 p 为 一个新的Promise。

6. 并行执行以下步骤：

   1. 令 r 为运行 删除cookie（参数为 url, options["name"], options["domain"], options["path"], 以及 options["partitioned"] 的结果。

   2. 如果 r 失败，则 拒绝 p，错误为 TypeError，并中止这些步骤。

   3. 解析 p 为 undefined。

7. 返回 p。

[Exposed=(ServiceWorker,Window),
 SecureContext]
interface CookieStoreManager {
  Promise<undefined> subscribe(sequence<CookieStoreGetOptions> subscriptions);
  Promise<sequence<CookieStoreGetOptions>> getSubscriptions();
  Promise<undefined> unsubscribe(sequence<CookieStoreGetOptions> subscriptions);
};

subscribe(subscriptions) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 registration 为 this 的 registration。

3. 令 p 为 一个新的Promise。

4. 并行执行以下步骤：

   1. 令 subscription list 为 registration 关联的 cookie 变更订阅列表。

   2. 对于 subscriptions 中的每个 entry，执行以下步骤：

      1. 令 name 为 entry["name"]。

      2. 规范化 name。

      3. 令 url 为 解析 entry["url"] 且使用 settings 的 API 基础 URL 的结果。

      4. 如果 url 并非以 registration 的 scope url 开头， 则使用 TypeError 拒绝 p，并终止这些步骤。

      5. 令 subscription 为 cookie 变更订阅 (name, url)。

      6. 如果 subscription list 尚未 包含 subscription，则 将 subscription 添加到 subscription list。

   3. 用 undefined 解析 p。

5. 返回 p。

getSubscriptions() 方法步骤如下：

1. 令 registration 为 this 的 registration。

2. 令 p 为 一个新的Promise。

3. 并行执行以下步骤：

   1. 令 subscriptions 为 registration 关联的 cookie变更订阅列表。

   2. 令 result 为一个新的 列表。

   3. 对 subscriptions 中每个 subscription，执行以下步骤：

      1. 追加 «[ "name" → subscription 的 name, "url" → subscription 的 url]» 到 result。

   4. 解析 p 为 result。

4. 返回 p。

unsubscribe(subscriptions) 方法步骤如下：

1. 令 settings 为 this 的 相关设置对象。

2. 令 registration 为 this 的 registration。

3. 令 p 为 一个新的Promise。

4. 并行执行以下步骤：

   1. 令 subscription list 为 registration 关联的 cookie变更订阅列表。

   2. 对 subscriptions 中每个 entry，执行以下步骤：

      1. 令 name 为 entry["name"]。

      2. 规范化 name。

      3. 令 url 为 解析 entry["url"] 且使用 settings 的 API 基础 URL 的结果。

      4. 如果 url 并非以 registration 的 scope url 开头， 则使用 TypeError 拒绝 p，并终止这些步骤。

      5. 令 subscription 为 cookie 变更订阅 (name, url)。

      6. 移除 subscription list 中等于 subscription 的任何 项。

   3. 解析 p 为 undefined。

5. 返回 p。

[Exposed=(ServiceWorker,Window)]
partial interface ServiceWorkerRegistration {
  [SameObject] readonly attribute CookieStoreManager cookies;
};

self.registration.cookies.subscribe([{name:'session-id'}]);

navigator.serviceWorker.register('sw.js').then(registration => {
  registration.cookies.subscribe([{name:'session-id'}]);
});

[Exposed=Window,
 SecureContext]
interface CookieChangeEvent : Event {
  constructor(DOMString type, optional CookieChangeEventInit eventInitDict = {});
  [SameObject] readonly attribute FrozenArray<CookieListItem> changed;
  [SameObject] readonly attribute FrozenArray<CookieListItem> deleted;
};

dictionary CookieChangeEventInit : EventInit {
  CookieList changed;
  CookieList deleted;
};

[Exposed=ServiceWorker]
interface ExtendableCookieChangeEvent : ExtendableEvent {
  constructor(DOMString type, optional ExtendableCookieChangeEventInit eventInitDict = {});
  [SameObject] readonly attribute FrozenArray<CookieListItem> changed;
  [SameObject] readonly attribute FrozenArray<CookieListItem> deleted;
};

dictionary ExtendableCookieChangeEventInit : ExtendableEventInit {
  CookieList changed;
  CookieList deleted;
};

[SecureContext]
partial interface Window {
  [SameObject] readonly attribute CookieStore cookieStore;
};

partial interface ServiceWorkerGlobalScope {
  [SameObject] readonly attribute CookieStore cookieStore;

  attribute EventHandler oncookiechange;
};

要将日期和时间dateTime表示为时间戳， 返回从1970年1月1日00:00:00 UTC到dateTime的毫秒数 （假定每一天正好为86,400,000毫秒）。

注意： 这与ECMAScript中的[ECMAScript]时间值表示方法一致。

要序列化日期一个 DOMHighResTimeStamp millis， 令dateTime为自1970年1月1日00:00:00 UTC起millis毫秒后的日期和时间 （假定每一天正好为86,400,000毫秒）， 并返回dateTime对应的最接近的cookie-date表示的字节序列，该表示依据Cookies § Dates定义。

要根据 URL url 和 string-或-null name 查询 cookies：

1. 执行 Cookies § 检索模型 中定义的步骤，以使用 url 作为 request-uri 计算 "cookie-string from a given cookie store"。 cookie-string 本身会被忽略，后续步骤使用其中间结果 cookie-list。

   在这些步骤中，cookie-string 是为 “非 HTTP” API 生成的。

2. 令 list 为一个新的 列表。

3. 对于 cookie-list 中的每个 cookie，执行以下步骤：

   1. 断言：cookie 的 http-only-flag 为 false。

   2. 如果 name 非 null：

      1. 规范化 name。

      2. 令 cookieName 为对 cookie 的 无 BOM 的 UTF-8 解码结果， 使用 cookie 的 name。

      3. 如果 cookieName 不等于 name，则 继续下一项。

   3. 令 item 为对 cookie 创建 CookieListItem 的结果。

   4. 将 item 添加到 list。

4. 返回 list。

要根据 cookie cookie 创建 CookieListItem：

1. 令 name 为对 cookie 的 无 BOM 的 UTF-8 解码结果， 使用 cookie 的 name。

2. 令 value 为对 cookie 的 无 BOM 的 UTF-8 解码结果， 使用 cookie 的 value。

3. 返回 «[ "name" → name, "value" → value ]»。

注意： 已知有一个实现会暴露除 name 和 value 之外的信息。

要使用 url、name、value、可选的 expires、domain、path、sameSite 和 partitioned 设置 cookie，请执行以下步骤：

1. 规范化 name。

2. 规范化 value。

3. 如果 name 或 value 包含 U+003B (;)、任何 C0 控制字符（除了 U+0009 TAB），或 U+007F DELETE，则返回失败。

   注意，这些字符限制是否也应该应用于 expires、domain、path 和 sameSite 仍在讨论中。[httpwg/http-extensions Issue #1593]

4. 如果 name 包含 U+003D (=)，则返回失败。

5. 如果 name 的 长度为 0：

   1. 如果 value 包含 U+003D (=)，则返回失败。

   2. 如果 value 的 长度为 0，则返回失败。

   3. 如果 value 字节小写后，以 `__host-`、`__host-http-`、`__http-` 或 `__secure-` 开头，则返回失败。

6. 如果 name 字节小写后，以 `__host-http-` 或 `__http--` 开头，则返回失败。

7. 令 encodedName 为 UTF-8 编码 name 的结果。

8. 令 encodedValue 为 UTF-8 编码 value 的结果。

9. 如果 encodedName 的 字节序列 长度加上 encodedValue 的 字节序列 长度大于 最大 name/value 对长度，则返回失败。

10. 令 host 为 url 的 主机。

11. 令 attributes 为一个新的 列表。

12. 如果 domain 不为 null，则执行以下步骤：

    1. 如果 domain 以 U+002E (.) 开头，则返回失败。

    2. 如果 name 字节小写后，以 `__host-` 开头，则返回失败。

    3. 如果 domain 不是 host 的可注册域名后缀且不等于 host，则返回失败。

    4. 令 parsedDomain 为 主机解析 domain 的结果。

    5. 断言：parsedDomain 不为失败。

    6. 令 encodedDomain 为 UTF-8 编码 parsedDomain 的结果。

    7. 如果 encodedDomain 的 字节序列 长度大于 最大属性值长度，则返回失败。

    8. 将 `Domain`/encodedDomain 添加到 attributes。

13. 如果提供了 expires，则将 `Expires`/expires（日期序列化）追加到 attributes。

14. 如果 path 是空字符串，则将 path 设为 url 的 序列化 Cookie 默认路径。

15. 如果 path 不以 U+002F（/）开头，则返回失败。

16. 如果 path 不等于 U+002F（/），且 name、字节小写后，以 `__host-` 开头，则返回失败。

17. 令 encodedPath 为 UTF-8 编码后的 path。

18. 如果 encodedPath 的字节序列长度大于最大属性值大小，则返回失败。

19. 追加 `Path`/encodedPath 到 attributes。

20. 追加 `Secure`/`` 到 attributes。

21. 根据 sameSite 进行分支：

    "none"

    追加 `SameSite`/`None` 到 attributes。

    "strict"

    追加 `SameSite`/`Strict` 到 attributes。

    "lax"

    追加 `SameSite`/`Lax` 到 attributes。

22. 如果 partitioned 为 true，追加 `Partitioned`/`` 到 attributes。

23. 执行 Cookies § 存储模型中，当用户代理“收到 cookie”时定义的步骤，其中 url 作为 request-uri，encodedName 作为 cookie-name，encodedValue 作为 cookie-value，attributes 作为 cookie-attribute-list。

    在这些步骤中，新创建的 cookie 被视为来自“非 HTTP”API。

24. 返回成功。

    注意：由于 [RFC6265BIS-14] 中的要求，存储 cookie 仍可能失败，但这些步骤将视为成功。

要使用 url、name、domain、path 和 partitioned 删除 cookie，请执行以下步骤：

1. 令 expires 为可表示的最早日期，并以 时间戳表示。

   注意： 对于本算法而言，expires 的具体值并不重要，只要是过去的日期即可。

2. 规范化 name。

3. 令 value 为空字符串。

4. 如果 name 的 长度为 0，则将 value 设为任意非空的 实现定义字符串。

5. 返回运行 设置 cookie 的结果，参数为 url、name、value、expires、domain、path、"strict" 和 partitioned。

要处理cookie变更，执行以下步骤：

1. 对于每个Window window，执行以下步骤：

   1. 令url为window的相关设置对象的创建URL。

   2. 令changes为url的可观察变更。

   3. 如果changes为空，则继续。

   4. 在 DOM 操作任务源上排队全局任务，给定 window，以触发名为 "change" 的更改事件，携带 changes，在 window 的 CookieStore 上。

2. 对于每个服务工作线程注册 registration，执行以下步骤：

   1. 令changes为一个新的集合。

   2. 对registration的可观察变更中的每个change（针对registration的scope url），执行：

      1. 令cookie为change的cookie。

      2. 对registration的cookie变更订阅列表中的每个subscription，执行：

         1. 如果change不在subscription的url对应的可观察变更中， 则继续。

         2. 令cookieName为对cookie的UTF-8无BOM解码得到的name。

         3. 如果cookieName等于subscription的name， 则追加change到changes并跳出循环。

   3. 如果changes为空，则继续。

   4. 令changedList和deletedList为对changes执行准备列表得到的结果。

   5. 在registration上触发一个名为"cookiechange"的功能事件， 使用ExtendableCookieChangeEvent， 并设置如下属性：

      changed

      changedList

      deleted

      deletedList

可观察变更，针对url，是集合， 包含cookie变更， 这些变更针对cookie存储区中的cookie， 满足Cookies § Retrieval Algorithm步骤1的要求， 即用url作为request-uri，针对“非HTTP”API计算“从给定cookie存储生成的cookie-string”的条件。

cookie变更是一个cookie和一个类型（changed或deleted）：

• 因插入另一个同名、同域、同路径的cookie而被移除的cookie会被忽略。

• 新创建且未立即被驱逐的cookie被视为changed。

• 新创建但立即被驱逐的cookie被视为deleted。

• 其他因驱逐或移除的cookie被视为deleted。

要在target上触发change事件，事件名为type，带有changes，执行：

1. 令event为用CookieChangeEvent创建的事件。

2. 设置event的type 属性为type。

3. 设置event的bubbles 和cancelable属性为false。

4. 令changedList和deletedList为对changes执行准备列表的结果。

5. 设置event的changed属性为changedList。

6. 设置event的deleted属性为deletedList。

7. 在target上分发event。

要对changes准备列表，执行以下步骤：

1. 令changedList为一个新的列表。

2. 令deletedList为一个新的列表。

3. 对changes中的每个change，执行：

   1. 令item为用change的cookie执行创建CookieListItem得到的结果。

   2. 如果change的类型是changed，则追加item到changedList。

   3. 否则，执行：

      1. 设置item["value"] 为undefined。

      2. 追加item到deletedList。

4. 返回changedList和deletedList。