service_worker_container.mojom | Explore in Territory

// Copyright 2017 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 "mojo/public/mojom/base/file_path.mojom";
import "third_party/blink/public/mojom/loader/fetch_client_settings_object.mojom";
import "third_party/blink/public/mojom/messaging/transferable_message.mojom";
import "third_party/blink/public/mojom/service_worker/controller_service_worker.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_embedded_worker_status.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_error_type.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_object.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_registration.mojom";
import "third_party/blink/public/mojom/service_worker/service_worker_registration_options.mojom";
import "third_party/blink/public/mojom/use_counter/metrics/web_feature.mojom";
import "url/mojom/url.mojom";

// Used for EnsureControllerServiceWorker() to indicate why a controllee needs
// a controller ServiceWorker.
enum ControllerServiceWorkerPurpose {
  FETCH_SUB_RESOURCE
};

// Sent from the browser process to the renderer. Contains info needed
// for a service worker client (window or web worker) to talk with the
// ServiceWorkerContainerHost in the browser process.
struct ServiceWorkerContainerInfoForClient {
  pending_associated_remote<ServiceWorkerContainerHost> host_remote;
  pending_associated_receiver<ServiceWorkerContainer> client_receiver;
};

// ServiceWorkerContainerHost is an interface implemented by the browser
// process. The renderer process uses this interface to request the browser
// process to do operations involving service worker registrations.
//
// This interface is associated with its counterpart ServiceWorkerContainer.
// The message pipe it's used on depends on the container type.
// - For service workers:
//       Associated with EmbeddedWorkerInstanceClient, which is on a dedicated
//       message pipe.
// - For shared workers:
//       Associated with SharedWorkerFactory, which is on a dedicated message
//       pipe.
// - For documents:
//       Associated with NavigationClient/FrameNavigationControl, which is on
//       the channel-associated interface to the renderer process.
interface ServiceWorkerContainerHost {
  // Corresponds to navigator.serviceWorker.register().
  // Registers a service worker from |script_url| with |options|.
  // |outside_fetch_client_settings_object| is used to fetch the top-level
  // script.
  // On success, |error| is kNone with |registration| set.
  // Otherwise, |error| and |error_msg| describe the failure.
  Register(url.mojom.Url script_url,
           ServiceWorkerRegistrationOptions options,
           FetchClientSettingsObject outside_fetch_client_settings_object)
    => (ServiceWorkerErrorType error,
        string? error_msg,
        ServiceWorkerRegistrationObjectInfo? registration);

  // Corresponds to navigator.serviceWorker.getRegistration().
  // Gets the service worker registration for the |client_url|.
  // On success, |error| is kNone with |registration| set.
  // In case there is no registration at |client_url|, or the registration is
  // uninstalling, |error| is still kNone but with null |registration|.
  // Otherwise, |error| and |error_msg| describe the failure.
  GetRegistration(url.mojom.Url client_url)
    => (ServiceWorkerErrorType error,
        string? error_msg,
        ServiceWorkerRegistrationObjectInfo? registration);

  // Corresponds to navigator.serviceWorker.getRegistrations().
  // Gets all service worker registrations which have the same origin with
  // the ServiceWorkerContainer that this interface hosts.
  // On success, |error| is kNone with |infos| set. Otherwise, |error| and
  // |error_msg| describe the failure.
  GetRegistrations()
    => (ServiceWorkerErrorType error,
        string? error_msg,
        array<ServiceWorkerRegistrationObjectInfo>? infos);

  // Corresponds to navigator.serviceWorker.ready.
  // Returns the service worker registration for the ServiceWorkerContainer that
  // this interface hosts, once such a registration exists and has an active
  // service worker.
  GetRegistrationForReady()
    => (ServiceWorkerRegistrationObjectInfo? registration);

  // Returns a Mojo end point to the controller ServiceWorker. This may start a
  // service worker instance in a renderer process if the corresponding
  // instance is not alive.
  // This method must be called only by the controllees.
  // If the browser fails to start the service worker it is propagated as a
  // connection error of the returned pipe. The detailed error reasons are not
  // reported to the controllees, but the browser process is responsible for
  // properly handling the failure and recording the reasons.
  // |purpose| is used for UMA.
  EnsureControllerServiceWorker(
      pending_receiver<ControllerServiceWorker> receiver,
      ControllerServiceWorkerPurpose purpose);

  // Makes a new endpoint to this ServiceWorkerContainerHost.
  CloneContainerHost(pending_receiver<ServiceWorkerContainerHost> container_host);

  // Gives a hint to the browser process to update the service worker after a
  // controlled page load. This message is meant to be sent at a time when page
  // load is no longer busy, so update doesn't adversely affect performance.
  // The browser process can possibly coalesce hints for the same service
  // worker into a single update.
  HintToUpdateServiceWorker();

  // Ensures that controller Service Worker has access to specified |files|.
  // This is necessary in cases where controller Service Worker is being run in
  // a different process than controllee initiating the network request.
  // The implementation must validate that the caller already has access to
  // |files|.
  EnsureFileAccess(array<mojo_base.mojom.FilePath> files) => ();

  // Informs the host that the context is execution ready.
  // https://html.spec.whatwg.org/multipage/webappapis.html#concept-environment-execution-ready-flag
  OnExecutionReady();
};

// ServiceWorkerContainer is an interface implemented by the renderer process.
// The browser process uses this interface to send messages to documents or the
// service worker.
//
// Roughly corresponds to the web-exposed ServiceWorkerContainer interface,
// i.e., navigator.serviceWorker. Actually, the plan is for this interface to be
// used for anything that could access a ServiceWorkerRegistration or
// ServiceWorker object. For example, ServiceWorkerGlobalScope needs to be
// connected to this, since it has self.registration, even though we don’t
// implement navigator.serviceWorker for Worker yet. But eventually anything
// that can touch these objects should be a ServiceWorkerContainer, so it’s OK
// to use this name.
//
// This interface is associated with its counterpart,
// ServiceWorkerContainerHost, as they are sent on the same master interface
// together. See ServiceWorkerContainerHost for documentation about the message
// pipe they live on.
interface ServiceWorkerContainer {
  // Corresponds to setting ServiceWorkerContainer#controller.
  // If |controller_info| is invalid (its |object_info| is null), then
  // ServiceWorkerContainer#controller is cleared.
  // If |should_notify_controllerchange| is true, dispatch a 'controllerchange'
  // event.
  SetController(ControllerServiceWorkerInfo controller_info,
                bool should_notify_controllerchange);

  // Corresponds to Client#postMessage().
  // Sends |message| from the service worker |source| to this service worker
  // client.
  PostMessageToClient(ServiceWorkerObjectInfo source,
                      TransferableMessage message);

  // Notifies this service worker client that its controller used a |feature|,
  // for UseCounter purposes.
  CountFeature(WebFeature feature);
};
chromium/third_party/blink/public/mojom/service_worker/service_worker_container.mojom
