From 62b74f09ebedb93936e4fd7c39897f2c1ccc7dfa Mon Sep 17 00:00:00 2001
From: Rowan Merewood <merewood@google.com>
Date: Tue, 6 Jun 2023 12:53:53 +0000
Subject: [PATCH] Update the WebView docs to point to MDN for cookie attribute
 explanations with an explicit callout for the Partitioned attribute.

Cherry picked I35d175ee34f1838f4db11c41a4115950fdb8b3f8 to master due to b/286408867.

Code was merged via `-s ours` and is missing even though the sha exists on the target branch. Cherry pick is required to bring in the code.

Manually remove the "Merged in" directive to allow for downstream propagation.

(cherry picked from https://android-review.googlesource.com/q/commit:09c55022b7623b6ed94123eed8da9006087d4107)
Change-Id: Iec51cfd48db0b2662b2c57d380417124e962ec57
---
 core/java/android/webkit/CookieManager.java | 50 ++++++++++++++-------
 1 file changed, 34 insertions(+), 16 deletions(-)

diff --git a/core/java/android/webkit/CookieManager.java b/core/java/android/webkit/CookieManager.java
index 20230e770bf5b..0427d10519190 100644
--- a/core/java/android/webkit/CookieManager.java
+++ b/core/java/android/webkit/CookieManager.java
@@ -103,15 +103,22 @@ public abstract class CookieManager {
      * will be ignored if it is expired. To set multiple cookies, your application should invoke
      * this method multiple times.
      *
-     * <p>The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP
-     * response header defined by
-     * <a href="https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03">RFC6265bis</a>.
-     * This is a key-value pair of the form {@code "key=value"}, optionally followed by a list of
-     * cookie attributes delimited with semicolons (ex. {@code "key=value; Max-Age=123"}). Please
-     * consult the RFC specification for a list of valid attributes.
+     * <p>The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP response
+     * header. This is a key-value pair of the form {@code "key=value"}, optionally followed by a
+     * list of cookie attributes delimited with semicolons (ex. {@code "key=value; Max-Age=123"}).
+     * For the header format and attributes supported by WebView, see the <a href=
+     * "https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie">{@code Set-Cookie}
+     * documentation on MDN</a>.
      *
-     * <p class="note"><b>Note:</b> if specifying a {@code value} containing the {@code "Secure"}
-     * attribute, {@code url} must use the {@code "https://"} scheme.
+     * <p class="note">
+     * <b>Notes:</b>
+     * <ul>
+     * <li>If specifying a {@code value} containing the {@code "Secure"} attribute,
+     * {@code url} must use the {@code "https://"} scheme.</li>
+     * <li>if specifying a {@code value} containing the {@code "Partitioned"}
+     * attribute, the cookie will be set for the top-level partition of the
+     * {@code url}.</li>
+     * </ul>
      *
      * @param url the URL for which the cookie is to be set
      * @param value the cookie as a string, using the format of the 'Set-Cookie'
@@ -125,12 +132,12 @@ public abstract class CookieManager {
      * will be ignored if it is expired. To set multiple cookies, your application should invoke
      * this method multiple times.
      *
-     * <p>The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP
-     * response header defined by
-     * <a href="https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03">RFC6265bis</a>.
-     * This is a key-value pair of the form {@code "key=value"}, optionally followed by a list of
-     * cookie attributes delimited with semicolons (ex. {@code "key=value; Max-Age=123"}). Please
-     * consult the RFC specification for a list of valid attributes.
+     * <p>The {@code value} parameter must follow the format of the {@code Set-Cookie} HTTP response
+     * header. This is a key-value pair of the form {@code "key=value"}, optionally followed by a
+     * list of cookie attributes delimited with semicolons (ex. {@code "key=value; Max-Age=123"}).
+     * For the header format and attributes supported by WebView, see the <a href=
+     * "https://developer.mozilla.org/docs/Web/HTTP/Headers/Set-Cookie">{@code Set-Cookie}
+     * documentation on MDN</a>.
      *
      * <p>This method is asynchronous. If a {@link ValueCallback} is provided,
      * {@link ValueCallback#onReceiveValue} will be called on the current
@@ -140,8 +147,15 @@ public abstract class CookieManager {
      * completes or whether it succeeded, and in this case it is safe to call the method from a
      * thread without a Looper.
      *
-     * <p class="note"><b>Note:</b> if specifying a {@code value} containing the {@code "Secure"}
-     * attribute, {@code url} must use the {@code "https://"} scheme.
+     * <p class="note">
+     * <b>Notes:</b>
+     * <ul>
+     * <li>If specifying a {@code value} containing the {@code "Secure"} attribute,
+     * {@code url} must use the {@code "https://"} scheme.</li>
+     * <li>if specifying a {@code value} containing the {@code "Partitioned"}
+     * attribute, the cookie will be set for the top-level partition of the
+     * {@code url}.</li>
+     * </ul>
      *
      * @param url the URL for which the cookie is to be set
      * @param value the cookie as a string, using the format of the 'Set-Cookie'
@@ -157,6 +171,10 @@ public abstract class CookieManager {
      * "; "} characters (semicolon followed by a space). Each key-value pair will be of the form
      * {@code "key=value"}.
      *
+     * <p class="note">
+     * <b>Note:</b> Any cookies set with the {@code "Partitioned"} attribute will only be returned
+     * for the top-level partition of {@code url}.
+     *
      * @param url the URL for which the cookies are requested
      * @return value the cookies as a string, using the format of the 'Cookie'
      *               HTTP request header