content/common/navigation_client.mojom

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

module content.mojom;

import "content/common/frame_messages.mojom";
import "content/public/common/alternative_error_page_override_info.mojom";
import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "mojo/public/mojom/base/uuid.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/restricted_cookie_manager.mojom";
import "services/network/public/mojom/url_loader.mojom";
import "services/network/public/mojom/url_loader_factory.mojom";
import "services/network/public/mojom/url_response_head.mojom";
import "third_party/blink/public/mojom/commit_result/commit_result.mojom";
import "third_party/blink/public/mojom/dom_storage/storage_area.mojom";
import "third_party/blink/public/mojom/frame/policy_container.mojom";
import "third_party/blink/public/mojom/loader/code_cache.mojom";
import "third_party/blink/public/mojom/loader/referrer.mojom";
import "third_party/blink/public/mojom/loader/fetch_later.mojom";
import "third_party/blink/public/mojom/loader/same_document_navigation_type.mojom";
import "third_party/blink/public/mojom/loader/transferrable_url_loader.mojom";
import "third_party/blink/public/mojom/loader/url_loader_factory_bundle.mojom";
import "third_party/blink/public/mojom/navigation/navigation_params.mojom";
import "third_party/blink/public/mojom/permissions_policy/document_policy_feature.mojom";
import "services/network/public/mojom/permissions_policy/permissions_policy.mojom";
import "third_party/blink/public/mojom/permissions_policy/policy_value.mojom";
import "third_party/blink/public/mojom/security_context/insecure_request_policy.mojom";
import "third_party/blink/public/mojom/service_worker/controller_service_worker.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_container.mojom";
import "third_party/blink/public/mojom/tokens/tokens.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";

[Native]
enum NavigationGesture;

[Native]
enum PageTransition;

[Native]
struct PageState;

// Parameters structure used in the IPC:
// - FrameHost.DidCommitProvisionalLoad
// - FrameHost.DidCommitSameDocumentNavigation
// - NavigationClient.CommitNavigationCallback
// - NavigationClient.CommitFailedNavigationCallback
struct DidCommitProvisionalLoadParams {
  // The item sequence number identifies each stop in the session history.  It
  // is unique within the renderer process and makes a best effort to be unique
  // across browser sessions (using a renderer process timestamp).
  int64 item_sequence_number = -1;

  // The document sequence number is used to identify cross-document navigations
  // in session history.  It increments for each new document and is unique in
  // the same way as |item_sequence_number|.  In-page navigations get a new item
  // sequence number but the same document sequence number.
  int64 document_sequence_number = -1;

  // Identifies a specific "slot" in the session history for the
  // window.navigation API. navigation.traverseTo() is given a key, which
  // matches against this to find the correct entry to traverse to.
  string navigation_api_key;

  // URL of the page being loaded.
  url.mojom.Url url;

  // URL of the referrer of this load. WebKit generates this based on the
  // source of the event that caused the load.
  blink.mojom.Referrer referrer;

  // The type of transition.
  // [Native] enums are by default initialized to 0 (i.e. PAGE_TRANSITION_LINK)
  PageTransition transition;

  // Set to false if we want to update the session history but not update the
  // browser history (e.g., on unreachable URLs). If the URL was reachable and
  // `blink::features::kVisitedLinksOnErrorNavigation` is enabled, this param is
  // set to `true` even if the navigation resulted in a 404 response code.
  bool should_update_history = false;

  // Contents MIME type of main frame.
  string contents_mime_type;

  // Whether this commit created a new entry.
  bool did_create_new_entry;

  // The HTTP method used by the navigation.
  string method;

  // The POST body identifier. -1 if it doesn't exist.
  int64 post_id;

  // The status code of the HTTP request.
  int32 http_status_code;

  // This flag is used to warn if the renderer is displaying an error page,
  // so that we can set the appropriate page type.
  bool url_is_unreachable;

  // The serialized history item state of the document that is being replaced by
  // this navigation (if the page is in the same renderer process as the new
  // page). Stored in the navigation entry.
  PageState? previous_page_state;

  // The initial serialized history item state of the document that is being
  // committed from this navigation. Stored in the navigation entry.
  PageState page_state;

  // User agent override used to navigate.
  bool is_overriding_user_agent;

  // Notifies the browser that for this navigation, the session history was
  // successfully cleared.
  bool history_list_was_cleared;

  // Origin of the document.  This will be replicated to any associated
  // RenderFrameProxies.
  url.mojom.Origin origin;

  // Base url of the document. This value is only used for
  // CreateNavigationRequestForSynchronousRendererCommit.
  // TODO(crbug.com/40184245): If synchronous about:blank commits are
  // removed, then this will no longer be needed.
  url.mojom.Url? initiator_base_url;

  // The 'Permissions-Policy' headers applied to the document.
  // https://w3c.github.io/webappsec-permissions-policy/#permissions-policy-http-header-field
  // Note: For backward compatibility, this field also contains
  // 'Feature-Policy' headers applied to the document.
  array<network.mojom.ParsedPermissionsPolicyDeclaration>
    permissions_policy_header;

  // The 'Document-Policy' headers applied to the document.
  // https://w3c.github.io/webappsec-permissions-policy/document-policy.html
  map<blink.mojom.DocumentPolicyFeature, blink.mojom.PolicyValue>
    document_policy_header;

  // The insecure request policy the document for the load is enforcing.
  blink.mojom.InsecureRequestPolicy insecure_request_policy;

  // The upgrade insecure navigations set the document for the load is
  // enforcing.
  array<uint32> insecure_navigations_set;

  // True if the document for the load is a unique origin that should be
  // considered potentially trustworthy.
  bool has_potentially_trustworthy_unique_origin;

  // Request ID generated by the renderer.
  int32 request_id;

  // A token that has been passed by the browser process when it asked the
  // renderer process to commit the navigation.
  mojo_base.mojom.UnguessableToken navigation_token;

  // An embedding token used to signify the relationship between a document and
  // its parent. This is populated for cross-document navigations including
  // sub-documents and the main document.
  mojo_base.mojom.UnguessableToken? embedding_token;

  // Start and end timestamps for running the unload event on the old document
  // before this navigation replaced it. This is only valid for same-process
  // navigations, where the unload handler on the old document runs
  // synchronously before the new document is allowed to commit.
  mojo_base.mojom.TimeTicks? unload_start;
  mojo_base.mojom.TimeTicks? unload_end;

  // Timestamp of when this frame started and ended the commit for the
  // navigation.
  //
  // TODO(alexmos): `commit_navigation_end` is a bit misleading, since it is
  // actually taken in the middle of processing a commit in the renderer, just
  // before calling DocumentLoader::CommitNavigation(), which does various other
  // work before actually sending the DidCommit IPC to unblock the browser
  // process. To get the latter timestamp, use `commit_reply_sent` below.
  // For now, `commit_navigation_end` is left alone as it's exposed to metrics,
  // but it should eventually be replaced with `commit_reply_sent`.
  mojo_base.mojom.TimeTicks commit_navigation_start;
  mojo_base.mojom.TimeTicks? commit_navigation_end;

  // The timestamp at which the renderer responded to the browser's
  // CommitNavigation IPC.
  // TODO(alexmos): replace `commit_navigation_end` with this timestamp.
  mojo_base.mojom.TimeTicks commit_reply_sent;
};

// Similar to DidCommitProvisionalLoadParams, but only used for
// FrameHost.DidCommitSameDocumentNavigation. Eventually, all parameters in
// DidCommitProvisionalLoadParams will either get removed or moved to
// DidCommitSameDocumentNavigationParams.
// See https://crbug.com/1133115, https://crbug.com/1131832
struct DidCommitSameDocumentNavigationParams {
  // Will be true if the navigation is the result of history.pushState or
  // history.replaceState.
  blink.mojom.SameDocumentNavigationType same_document_navigation_type;

  // Whether the navigation is a result of a client redirect (e.g. a
  // script-initiated navigation) or not (e.g. a link click).
  bool is_client_redirect = false;

  // Whether the navigation is started by a transient user activation or not.
  // TODO(mustaq): Figure out if we can drop this and use the user activation
  // state tracked in the browser instead.
  bool started_with_transient_activation = false;

  // Whether this commit should replace the current entry.
  bool should_replace_current_entry;

  // Set if the renderer triggers a screenshot for the last frame before this
  // navigation. The screenshot is executed by Viz and sent back to the browser
  // via `mojom::FrameSinkManagerClient`. This token is used to associate the
  // screenshot sent by Viz to the corresponding navigation entry.
  blink.mojom.SameDocNavigationScreenshotDestinationToken?
    navigation_entry_screenshot_destination;
};

struct CookieManagerInfo {
  // The origin |cookie_manager| is associated with.
  url.mojom.Origin origin;

  // A cookie manager which can be used for |origin|.
  pending_remote<network.mojom.RestrictedCookieManager> cookie_manager;
};

struct StorageInfo {
  // A storage area which can be used for local storage.
  pending_remote<blink.mojom.StorageArea>? local_storage_area;

  // A storage area which can be used for session storage.
  pending_remote<blink.mojom.StorageArea>? session_storage_area;
};

enum NavigationClientDisconnectReason {
  // No explicit reason set while calling.
  kNoExplicitReason = 0,

  // Explicit reset reason when the NavigationClient needs to be reset when
  // swapping frames. In this case, it is often desirable to *not* cancel the
  // navigation: otherwise, this may interfere with the navigation queueing
  // logic (by unexpectedly cancelling the queued navigation).
  kResetForSwap,

  // Explicit reset reason when the NavigationClient needs to be reset because
  // the renderer explicitly aborted the navigation (instead of the connection
  // being automatically disconncted due to e.g. crashing).
  kResetForAbort,

  // Explicit reset reason when the NavigationClient needs to be reset because
  // a new renderer-initiated navigation started.
  kResetForNewNavigation,

  // Similar to above but the navigation is a duplicate navigation (i.e. the
  // URL, method, other params are all the same).
  kResetForDuplicateNavigation,
};

// Implemented by the renderer and called by the browser. Used for two purposes:
//
// - When the renderer requests a navigation in a RenderFrame in the same
//   process, the renderer binds a NavigationClient interface. Disconnecting
//   this interface is used as a signal to potentially cancel the navigation
//   (because it was replaced or cancelled).
// - When committing a navigation: the browser asks the targeted RenderFrame to
//   bind a NavigationClient and makes exactly one call to `CommitNavigation()`
//   or `CommitFailedNavigation()`. Similar to requesting a navigation above,
//   disconnecting this interface is used as a signal to cancel the navigation.
interface NavigationClient {
  // Tells the renderer that a navigation is ready to commit.
  //
  // The renderer should bind the |url_loader_client_endpoints| to an
  // URLLoaderClient implementation to continue loading the document that will
  // be the result of the committed navigation.
  //
  // Note: |url_loader_client_endpoints| will be empty iff the navigation URL
  // wasn't handled by the network stack (i.e. about:blank, ...)
  //
  // Note: |response_body| will be invalid iff the navigation URL wasn't handled
  // by the network stack (i.e. about:blank, ...)
  //
  // When the Network Service is enabled, |subresource_loader_factories| may
  // also be provided by the browser as a a means for the renderer to load
  // subresources where applicable.
  //
  // |controller_service_worker_info| may also be provided by the browser if the
  // frame that is being navigated is supposed to be controlled by a Service
  // Worker.
  // |container_info| may also be provided if the browser has created a
  // ServiceWorkerContainerHost for this navigation.
  //
  // |subresource_proxying_loader_factory| is used to proxy prefetch and topics
  // (https://github.com/patcg-individual-drafts/topics) handling via the
  // browser process.
  //
  // |keep_alive_loader_factory| is used to handle fetch keepalive requests via
  // the browser process.
  // See https://docs.google.com/document/d/1ZzxMMBvpqn8VZBZKnb7Go8TWjnrGcXuLS_USwVVRUvY
  //
  // |fetch_later_loader_factory| is used to handle fetchLater() requests via
  // the browser process. See
  // https://docs.google.com/document/d/1U8XSnICPY3j-fjzG35UVm6zjwL6LvX6ETU3T8WrzLyQ
  //
  // For automation driver-initiated navigations over the devtools protocol,
  // |devtools_navigation_token_| is used to tag the navigation. This navigation
  // token is then sent into the renderer and lands on the DocumentLoader. That
  // way subsequent Blink-level frame lifecycle events can be associated with
  // the concrete navigation.
  // - The value should not be sent back to the browser.
  // - The value on DocumentLoader may be generated in the renderer in some
  // cases, and thus shouldn't be trusted.
  // TODO(crbug.com/40549185): Replace devtools navigation token with the generic
  // navigation token that can be passed from renderer to the browser.
  //
  // |code_cache_host|, |cookie_manager_info|, and |storage_info| are sent as
  // optimizations so the renderer doesn't need to request them from the
  // browser. These may be null if the NavigationThreadingOptimizations feature
  // is disabled. |cookie_manager_info| may also be null for non HTTP/HTTPS
  // navigations, or if the origin is opaque.
  //
  // The [SupportsUrgent] attribute enables marking this message as urgent by
  // calling the method in an UrgentMessageScope. Urgent messages cause the
  // renderer to prioritize the IPC task queue while there are urgent messages
  // pending, which increases their priority while maintaining ordering
  // guarantees. See also mojo/public/tools/bindings/README.md.
  [SupportsUrgent]
  CommitNavigation(
      blink.mojom.CommonNavigationParams common_params,
      blink.mojom.CommitNavigationParams request_params,
      network.mojom.URLResponseHead response_head,
      handle<data_pipe_consumer>? response_body,
      network.mojom.URLLoaderClientEndpoints? url_loader_client_endpoints,
      blink.mojom.URLLoaderFactoryBundle? subresource_loader_factories,
      array<blink.mojom.TransferrableURLLoader>? subresource_overrides,
      blink.mojom.ControllerServiceWorkerInfo? controller_service_worker_info,
      blink.mojom.ServiceWorkerContainerInfoForClient? container_info,
      pending_remote<network.mojom.URLLoaderFactory>? subresource_proxying_loader_factory,
      pending_remote<network.mojom.URLLoaderFactory>? keep_alive_loader_factory,
      pending_associated_remote<blink.mojom.FetchLaterLoaderFactory>? fetch_later_loader_factory,
      blink.mojom.DocumentToken document_token,
      mojo_base.mojom.UnguessableToken devtools_navigation_token,
      mojo_base.mojom.Uuid base_auction_nonce,
      array<network.mojom.ParsedPermissionsPolicyDeclaration>? permissions_policy,
      blink.mojom.PolicyContainer policy_container,
      pending_remote<blink.mojom.CodeCacheHost>? code_cache_host,
      pending_remote<blink.mojom.CodeCacheHost>? code_cache_host_for_background,
      CookieManagerInfo? cookie_manager_info,
      StorageInfo? storage_info)
      => (DidCommitProvisionalLoadParams params,
          DidCommitProvisionalLoadInterfaceParams? interface_params);

  // Tells the renderer that a failed navigation is ready to commit.
  //
  // The result of this commit usually results in displaying an error page.
  // Note |error_page_content| may contain the content of the error page
  // (i.e. flattened HTML, JS, CSS).
  //
  // When the Network Service is enabled, |subresource_loader_factories| may
  // also be provided by the browser as a means for the renderer to load
  // subresources where applicable.
  //
  // |info| contains values used to customise the error page. It may be null if
  // the page which displays an error should not be customized.
  //
  // The [SupportsUrgent] attribute enables marking this message as urgent by
  // calling the method in an UrgentMessageScope. Urgent messages cause the
  // renderer to prioritize the IPC task queue while there are urgent messages
  // pending, which increases their priority while maintaining ordering
  // guarantees. See also mojo/public/tools/bindings/README.md.
  [SupportsUrgent]
  CommitFailedNavigation(
      blink.mojom.CommonNavigationParams common_params,
      blink.mojom.CommitNavigationParams request_params,
      bool has_stale_copy_in_cache,
      int32 error_code,
      int32 extended_error_code,
      network.mojom.ResolveErrorInfo resolve_error_info,
      string? error_page_content,
      blink.mojom.URLLoaderFactoryBundle? subresource_loader_factories,
      blink.mojom.DocumentToken document_token,
      mojo_base.mojom.UnguessableToken devtools_navigation_token,
      blink.mojom.PolicyContainer policy_container,
      AlternativeErrorPageOverrideInfo? alternative_error_page_info)
      => (DidCommitProvisionalLoadParams params,
          DidCommitProvisionalLoadInterfaceParams? interface_params);
};