chromium/src/third_party/blink/public/mojom/service_worker/controller_service_worker.mojom

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

module blink.mojom;

import "mojo/public/mojom/base/time.mojom";
import "mojo/public/mojom/base/unguessable_token.mojom";
import "services/network/public/mojom/cross_origin_embedder_policy.mojom";
import "services/network/public/mojom/url_loader.mojom";
import "third_party/blink/public/mojom/service_worker/controller_service_worker_mode.mojom";
import "third_party/blink/public/mojom/service_worker/dispatch_fetch_event_params.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_event_status.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_fetch_response_callback.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_object.mojom";
import "third_party/blink/public/mojom/web_feature/web_feature.mojom";

// Represents a service worker that is a 'controller'.
// (https://w3c.github.io/ServiceWorker/#navigator-service-worker-controller)
// One of its Mojo end points (i.e. the caller end) is passed to the
// controllee in the renderer process, and used from there.  Its other Mojo
// end point (i.e. the destination of the events) is implemented by
// ControllerServiceWorkerImpl in the renderer process where the controller
// service worker runs.
//
// The controllees use this interface to directly talk to the controller. This
// implements a small subset of the ServiceWorker interface, namely dispatch
// methods for Fetch and PostMessage, because ordering must be preserved
// between them: controller.postMessage(...), controller.fetch(‘...’); from
// the page must result in a message event then fetch event dispatched to the
// service worker. They are believed to be the only events whose ordering
// guarantee is observable from the page context.
interface ControllerServiceWorker {
  // Dispatches Fetch event for sub-resources. (Fetch for main resource is
  // handled by the ServiceWorker interface, as the fetch is initiated
  // in the browser-process during the navigation)
  // The callback is called once the event finishes, which means the event
  // handler ran and all outstanding respondWith() and waitUntil() promises have
  // settled. |response_callback| is called once the promise to respondWith()
  // settles, or when the event handler ran without calling respondWith().
  DispatchFetchEventForSubresource(
      blink.mojom.DispatchFetchEventParams params,
      pending_remote<blink.mojom.ServiceWorkerFetchResponseCallback> response_callback)
      => (blink.mojom.ServiceWorkerEventStatus status);

  // TODO(kinuko): Add DispatchExtendableMessageEvent() as well.

  // Connects a new pipe to this controller instance.
  // |cross_origin_embedder_policy| is the policy for the client which uses the
  // counterpart of |receiver|.
  // |coep_reporter| is the endpoint to report the error raised by the CORP
  // validation based on |cross_origin_embedder_policy|. This can be null when
  // it's not supported yet.
  Clone(pending_receiver<ControllerServiceWorker> receiver,
        network.mojom.CrossOriginEmbedderPolicy cross_origin_embedder_policy,
        pending_remote<network.mojom.CrossOriginEmbedderPolicyReporter>?
            coep_reporter);
};

// A convenient struct that packs necessary information for a service worker
// client to talk to and set up its controller. Used to propagate controller
// information from the browser process to the renderer process on navigation
// commit, and also as a parameter of ServiceWorkerContainer.SetController().
struct ControllerServiceWorkerInfo {
  // Describes whether there is a controller and it has a fetch event handler.
  blink.mojom.ControllerServiceWorkerMode mode =
      blink.mojom.ControllerServiceWorkerMode.kNoController;

  // Non-null iff there is a controller and it has a fetch event handler.
  pending_remote<ControllerServiceWorker>? remote_controller;

  // The client being controlled, used for FetchEvent#clientId. The ID is
  // issued by the browser process for this receiving client, and would
  // never change thoughout the lifetime of the client.
  // TODO(bashi): Consider having a separate struct for passing this kind of
  // information, as this isn't really a part of controller info.
  string client_id;

  // This also identifies the client. Used to set |fetch_window_id| on
  // network::ResourceRequests originating from the client's context. Null if
  // this client is not a window.
  mojo_base.mojom.UnguessableToken? fetch_request_window_id;

  // Represents ServiceWorkerContainer#controller.
  // Null if there is no controller.
  blink.mojom.ServiceWorkerObjectInfo? object_info;

  // The set of features the controller has used, for UseCounter purposes.
  array<WebFeature> used_features;
};

// A renderer-side interface for talking across threads. The main thread
// uses this interface to update a ControllerServiceWorkerConnector on a
// different thread with a new controller service worker.
// TODO(kinuko): Stop using mojo interface for this, we can just make
// it work via posting tasks.
interface ControllerServiceWorkerConnector {
  // Resets the controller connection with the given |controller|, this
  // can be called when a new controller is given, e.g. due to claim().
  // |controller| can be null if it gets no controller.
  UpdateController(pending_remote<ControllerServiceWorker>? controller);
};