services/network/public/mojom/cookie_access_observer.mojom

// Copyright 2020 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module network.mojom;

import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";
import "services/network/public/mojom/site_for_cookies.mojom";
import "services/network/public/mojom/cookie_manager.mojom";
import "services/network/public/mojom/cookie_setting_overrides.mojom";

struct CookieAccessDetails {
  enum Type {
    kRead,
    kChange,
  };

  // Whether this request corresponds to a cookie read or a cookie write.
  Type type;

  // If the cookies are accessed by a network transfer, |url| is the URL being
  // loaded; if they're read by a script, it's the URL of window or service
  // worker script looking them up.
  url.mojom.Url url;

  // The top frame origin for the given request, we use top_frame_origin from
  // net::IsolationInfo.
  url.mojom.Origin top_frame_origin;

  SiteForCookies site_for_cookies;
  // Each element of the `cookie_list` array includes a CookieInclusionStatus
  // and a CanonicalCookie if one was successfully constructed; if we were
  // unable to create the CanonicalCookie, then we use the cookie string
  // instead. Note that this means we always get a CanonicalCookie for reads,
  // but may get a cookie string on writes.
  array<CookieOrLineWithAccessResult> cookie_list;

  // |devtools_request_id| contains the DevTools request id of the request
  // that triggered the cookie change, if the read was triggered by a request.
  string? devtools_request_id;

  // CookieAccessDetails may be deduplicated to reduce IPC costs. In this case,
  // |count| refers to the number of instances that are duplicates of |this|
  // that would have been sent (including |this|).
  uint32 count = 1;

  // If the cookies are accessed by a network transfer, `is_ad_tagged` records
  // whether the request was determined to be for advertising purposes.
  bool is_ad_tagged;

  // A set of enum values as a bitmask.
  CookieSettingOverrides cookie_setting_overrides;
};

// Cloneable interface to observe the cookie reads or writes.
// The user of the NetworkService should create a dedicated
// CookieAccessObserver for each context it is interested in.
interface CookieAccessObserver {
  // Called when attempts have been made to access (read or write) the cookies
  // in |details.cookie_list|, with the status indicating cookies were actually
  // used or blocked (and if blocked gives the reason). Currently, blocked
  // cookies are included if they are blocked by user preference, or if they
  // warrant a console deprecation warning.
  // The network skips sending this notification on consecutive "duplicate"
  // access events (i.e. where the cookie and its access result remain unchanged
  // since the previous event).
  // The network service queues multiple events within a short time window to
  // reduce mojo overhead.
  OnCookiesAccessed(array<CookieAccessDetails> details);

  // Used by the NetworkService to create a copy of this observer.
  // (e.g. when creating an observer for URLLoader from URLLoaderFactory's
  // observer).
  Clone(pending_receiver<CookieAccessObserver> listener);
};