Repository: square/okhttp
File: okhttp/src/jvmMain/kotlin/okhttp3/Cookie.kt (Kotlin)

Code before:
  @get:JvmName("persistent") val persistent: Boolean, // True if 'expires' or 'max-age' is present.

  /**
   * Returns true if this cookie's domain should be interpreted as a single host name, or false if
   * it should be interpreted as a pattern. This flag will be false if its `Set-Cookie` header
   * included a `domain` attribute.
   *
   * For example, suppose the cookie's domain is `example.com`. If this flag is true it matches
   * **only** `example.com`. If this flag is false it matches `example.com` and all subdomains
   * including `api.example.com`, `www.example.com`, and `beta.api.example.com`.
   */
  @get:JvmName("hostOnly") val hostOnly: Boolean, // True unless 'domain' is present.

  /**
   * Returns a non-empty string with the cookie's policy for whether the cookie is sent with
   * cross-site requests, providing some protection against cross-site request forgery (CSRF) attacks.
   * Same-site requests means requests originating from the same site that set the cookie. Cross-site
   * means requests originating from site that's different from the one that set the cookie.
   *
   * The possible values are:
   * - `Strict`: Cookie will only be sent for same-site requests. The scheme and domain
   *     must match the one on the cookie.
   * - `Lax`: Cookie is not sent on cross-site requests. Cookie won't be sent when going from origin
   *     site to an external site, but is sent when going from an external site to the origin site.
   * - `None`: Browser will send the cookie with both cross-site and same-site requests. The Secure
   *     attribute must be set when setting this value.
   */
  @get:JvmName("sameSite") val sameSite: String,
) {

  /**
   * Returns true if this cookie should be included on a request to [url]. In addition to this
   * check callers should also confirm that this cookie has not expired.
   */
  fun matches(url: HttpUrl): Boolean {
    val domainMatch = if (hostOnly) {
      url.host == domain
    } else {
      domainMatch(url.host, domain)
    }
    if (!domainMatch) return false

    if (!pathMatch(url, path)) return false

    return !secure || url.isHttps
  }

  override fun equals(other: Any?): Boolean {
    return other is Cookie &&
      other.name == name &&
      other.value == value &&

Review comment (suggestion):

```suggestion
   * Returns a string describing whether this cookie is sent for cross-site calls.
   *
   * Two URLs are on the same site if they share a [top private domain][HttpUrl.topPrivateDomain].
   * Otherwise, they are cross-site URLs.
   *
   * When a URL is requested, it may be in the context of another URL.
   *
   *  * **Embedded resources like images and iframes** in browsers use the context as the page in
   *    the address bar and the subject is the URL of an embedded resource.
   *
   *  * **Potentially-destructive navigations such as HTTP POST calls** use the context as the page
   *    originating the navigation, and the subject is the page being navigated to.
   *
   * The values of this attribute determine whether this cookie is sent for cross-site calls:
   *
   *  - "Strict": the cookie is omitted when the subject URL is an embedded resource or a
   *    potentially-destructive navigation.
   *
   *  - "Lax": the cookie is omitted when the subject URL is an embedded resource. It is sent for
   *    potentially-destructive navigation. This is the default value.
   *
   *  - None: the cookie is always sent. The "Secure" attribute must also be set when setting this
   *    value.
```

I wanna read the spec to confirm my understanding is correct. Also I wanna get the right terms; I don’t think 'Context' and 'Subject' are right, but there probably are words that are.

Code after:
  @get:JvmName("persistent") val persistent: Boolean, // True if 'expires' or 'max-age' is present.

  /**
   * Returns true if this cookie's domain should be interpreted as a single host name, or false if
   * it should be interpreted as a pattern. This flag will be false if its `Set-Cookie` header
   * included a `domain` attribute.
   *
   * For example, suppose the cookie's domain is `example.com`. If this flag is true it matches
   * **only** `example.com`. If this flag is false it matches `example.com` and all subdomains
   * including `api.example.com`, `www.example.com`, and `beta.api.example.com`.
   */
  @get:JvmName("hostOnly") val hostOnly: Boolean, // True unless 'domain' is present.

  /**
   * Returns a string describing whether this cookie is sent for cross-site calls.
   *
   * Two URLs are on the same site if they share a [top private domain][HttpUrl.topPrivateDomain].
   * Otherwise, they are cross-site URLs.
   *
   * When a URL is requested, it may be in the context of another URL.
   *
   *  * **Embedded resources like images and iframes** in browsers use the context as the page in
   *    the address bar and the subject is the URL of an embedded resource.
   *
   *  * **Potentially-destructive navigations such as HTTP POST calls** use the context as the page
   *    originating the navigation, and the subject is the page being navigated to.
   *
   * The values of this attribute determine whether this cookie is sent for cross-site calls:
   *
   *  - "Strict": the cookie is omitted when the subject URL is an embedded resource or a
   *    potentially-destructive navigation.
   *
   *  - "Lax": the cookie is omitted when the subject URL is an embedded resource. It is sent for
   *    potentially-destructive navigation. This is the default value.
   *
   *  - "None": the cookie is always sent. The "Secure" attribute must also be set when setting this
   *    value.
   */
  @get:JvmName("sameSite") val sameSite: String?,
) {

  /**
   * Returns true if this cookie should be included on a request to [url]. In addition to this
   * check callers should also confirm that this cookie has not expired.
   */
  fun matches(url: HttpUrl): Boolean {
    val domainMatch = if (hostOnly) {
      url.host == domain
    } else {
      domainMatch(url.host, domain)
    }