chromium/third_party/blink/public/mojom/loader/fetch_later.mojom

// Copyright 2023 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/mutable_network_traffic_annotation_tag.mojom";
import "services/network/public/mojom/url_request.mojom";

// FetchLaterLoaderFactory is an interface for requesting FetchLater requests.
// It creates FetchLaterLoader instance per FetchLater request.
//
// There is one instance that serves this interface in the browser per
// FetchContext.
//
// * Design Doc:
// https://docs.google.com/document/d/1U8XSnICPY3j-fjzG35UVm6zjwL6LvX6ETU3T8WrzLyQ
// * API explainer:
// https://github.com/WICG/pending-beacon/blob/main/docs/fetch-later-api.md
// * Spec (draft):
// https://whatpr.org/fetch/1647/9ca4bda...7bff4de.html#fetch-later-method
interface FetchLaterLoaderFactory {
  // Creates a pending FetchLaterLoader with the given `request`.
  //
  // This method takes almost the same set of arguments as URLLoaderFactory's
  // CreateLoaderAndStart(), except URLLoaderClient is not needed here.
  //
  // `request_id` is an arbitrary id for the request. `request_id` should be
  // unique over all calls to CreateLoader() on this host, or 0, as defined in
  // url_loader_factory.mojom.
  //
  // `options` is a bitfield of the options the same as the ones defined in
  // url_laoder_factory.mojom.
  //
  // A FetchLaterLoader does not need URLLoaderClient, as the requester is not
  // expected to handle any responses by the nature of FetchLater API.
  CreateLoader(
    pending_associated_receiver<FetchLaterLoader> loader,
    int32 request_id,
    uint32 options,
    network.mojom.URLRequest request,
    network.mojom.MutableNetworkTrafficAnnotationTag traffic_annotation);

  // Connects a new pipe to this instance of FetchLaterLoaderFactory interface.
  Clone(pending_associated_receiver<FetchLaterLoaderFactory> factory);
};

// FetchLaterLoader is an interface for performing a single FetchLater request.
//
// Destroying a FetchLaterLoader will start the associated FetchLater request.
//
// A FetchLaterLoader is created using FetchLaterLoaderFactory::CreateLoader()
// to load a FetchLater request. The request, by its spec, is "deferred" to
// start, meaning that the browser will not start the loader immediately.
// Instead, it waits until FetchLaterLoader mojo pipe being disconnected to do
// so.
//
// The renderer can ask the browser
// (1) to start sending earlier instead of waiting for disconnection by calling
//     `SendNow()`
// (2) to cancel/abort instead of starting a FetchLaterLoader on disconnected by
//     calling `Cancel()` before destroying this loader.
interface FetchLaterLoader {
  // Asks to send out the deferred FetchLater request immediately. If the
  // request is already started to load, do nothing.
  //
  // Calling this will close the message pipe for the interface as well, so no
  // further calls can be made.
  SendNow();

  // Cancels the deferred FetchLater request. If the request is already started,
  // it may be aborted.
  //
  // Calling this will close the message pipe for the interface as well, so no
  // further calls can be made.
  Cancel();
};