chromium/third_party/blink/public/mojom/speculation_rules/speculation_rules.mojom

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

module blink.mojom;

import "services/network/public/mojom/no_vary_search.mojom";
import "third_party/blink/public/mojom/loader/referrer.mojom";
import "url/mojom/url.mojom";

// See also third_party/blink/renderer/core/speculation_rules/README.md.

// Browser process interface for receiving information about proposed
// speculation from the renderer process.
//
// At the moment these updates are not incremental -- the renderer updates the
// entire set of speculation candidates at once. This is probably fine as long
// as it's occasional (i.e., the renderer buffers these updates somewhat) and
// the set of candidates is not unmanageably large. If so we may need to
// re-evaluate.
interface SpeculationHost {
  // Pushes a new set of speculation candidates, which replaces any previously
  // sent.
  UpdateSpeculationCandidates(array<SpeculationCandidate> candidates);
  // Called when LCP is predicted.
  OnLCPPredicted();
  // Initiates previewing the given `url`.
  // TODO(https://b/292184832): Give more hints, such as gfx.mjom.PointF
  // screen_position.
  InitiatePreview(url.mojom.Url url);
};

// The action that is proposed.
enum SpeculationAction {
  kPrefetch,
  kPrefetchWithSubresources,
  kPrerender,
};

// The target hint that is proposed.
enum SpeculationTargetHint {
  kNoHint,
  kBlank,
  kSelf,
};

// Shows how eager the developer is to perform the speculation action.
// NOTE: These values are persisted to logs. Entries should not be renumbered
// and numeric values should never be reused.
enum SpeculationEagerness {
  kConservative = 0,
  kModerate = 1,
  kEager = 2,
};

// Specifies the way in which speculation rules were injected.
enum SpeculationInjectionType {
  kNone,                  // Not injected, i.e., statically-inserted script tags.
  kMainWorldScript,       // Injected by main V8 world's script.
  kIsolatedWorldScript,   // Injected by an isolated V8 world's script.
  kAutoSpeculationRules,  // Injected by the browser as part of the auto speculation rules feature.
};

// A single candidate: a URL, an action, a referrer, and any associated
// metadata that might be needed to make a decision.
// https://wicg.github.io/nav-speculation/speculation-rules.html#prefetch-candidate
// https://wicg.github.io/nav-speculation/speculation-rules.html#prerender-candidate
struct SpeculationCandidate {
  // The URL which is eligible for some action.
  url.mojom.Url url;

  // The action which is proposed for that URL.
  SpeculationAction action = kPrefetch;

  // The referrer to be used when fetching this candidate.
  Referrer referrer;

  // If true, cross-origin requests associated with this speculation must be
  // made in a manner which anonymizes the client IP. If this is not possible,
  // this candidate must be discarded.
  bool requires_anonymous_client_ip_when_cross_origin = false;

  // The hint to be used to decide a target browsing context where preloaded
  // resource will be used. This is kNoHint for actions other than `kPrerender`.
  SpeculationTargetHint target_browsing_context_name_hint = kNoHint;

  // The eagerness level to be used by link selection heuristics to select the
  // candidate.
  SpeculationEagerness eagerness = kConservative;

  // The expected No-Vary-Search header if specified.
  // Explainer: https://github.com/WICG/nav-speculation/blob/main/no-vary-search.md#a-referrer-hint
  network.mojom.NoVarySearch? no_vary_search_hint;

  // The way in which the speculation rules were injected.
  SpeculationInjectionType injection_type = kNone;
};